| Oracle® Real-Time Collaboration Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25461-01 |
|
|
View PDF |
| Oracle® Real-Time Collaboration Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25461-01 |
|
|
View PDF |
Business can extend their application with Oracle Real-Time Collaboration Integration Services for enhanced interactions with external customers or partners. In this way, businesses can equip employees with the same Oracle Real-Time Collaboration tools in external as well as internal collaboration flows. A typical scenario is a live help scenario in which customer support Web pages indicate the availability of support personnel, with options to allow the customer to start an instant messaging session with the support personnel.
This chapter describes steps you would typically perform to integrate presence and live help into your applications.
The live help flow typically involves allowing guest users, who are most likely known only to an integrating site and not to the Oracle Real-Time Collaboration base installation, to participate in Oracle Real-Time Collaboration features like instant messaging. This flow involves the following high-level steps:
Step 1 Provision Site
Communication with Oracle Real-Time Collaboration Integration Services involves the concept of a logical entity called a site. Provision the site for the presence and guest user chat policies. The presence policy allows a site to include presence information in its Web pages through the Presence URL service. The guest user chat policy permits a site to request a chat session for a guest user.
Step 2 Create Support Groups
Create a live help support group for the site that will provide live help support. Register your support personnel with this group. This is the group to which live help messages will be broadcasted when a guest user requests live help.
Step 3 Enable Presence in Your Web Pages
Providing presence information in customer interfaces is a powerful way of letting users know if support personnel are available to service a customer's request. An indicator reflecting whether support personnel are online and available, and possibly indicators about predicted hold times or queue lengths, can inform the customer appropriately and set the right expectations of service.
Presence indicators also provide natural invocation hooks for a customer to invoke the next step in the flow: involving actual chat with support personnel.
Step 4 Integrate Live Help into Your Application
This involves the user clicking on a presence indicator (or an equivalent link) to invoke the appropriate Oracle Messenger client to start a chat session.
An administrator can provision a site through the Oracle Real-Time Collaboration Web application interface. To enable live help, provision the site for the following two policies:
PRESENCE
GUESTCHAT
The PRESENCE policy allows a site to include presence information in its Web pages through the Presence URL Service. The GUESTCHAT policy permits a site to request a chat session for a guest user.
A provisioned site is provided with a set of site credentials: a site ID and a site authentication token. A site authenticates itself by providing its credentials to Oracle Real-Time Collaboration Authentication services.
Users with administrative privileges can add support groups and register support personnel to these groups. An administrator would use the command rtcctl addGroup to create a group for this purpose. For more information about the rtcctl command, see Chapter 4, "rtcctl Command-Line Utility for Oracle Real-Time Collaboration" in Oracle Real-Time Collaboration Administrator's Guide.
Assume within the context of this chapter that the name of the support group is otn.support@sites.oracle.com.
The presence integration scenario uses the Presence URL service. This service provides a registered user with a unique URL that displays user presence information securely in an application. Presence information can be obtained in the form of an image or a status string using the JavaScript variant of Presence URL Services.
The logic involved in creating the URL lies in generating a unique, asymmetric hash key for each user. This key is generated from valid session information that is common to all users that belong to a given site along with user specific information.
The following diagram illustrates the flow of enabling presence:
Before proceeding further, make sure you have the following system and account information:
Access to an Oracle Real-Time Collaboration deployment
Valid site ID and authentication token for the Web site you would like to include presence information
Site ID provisioned for the PRESENCE policy
The Presence URL Service allows integrating sites to query and provide presence information directly in their web pages. This allows for requests to come directly from the user's browser, eliminating the need for server-side processing of presence information by the site. (If the sites does need to process presence information on the server, the Presence SOAP Service may be consumed.) In addition, client-side processing is possible, using the JavaScript version of the service.
The following is an example presence URL:
https://rtc.domain.com/imtapp/Presence? TID=11704&R_UID=OTN.SUPPORT@GROUPS.DOMAIN.COM& R_MODE=IMG&K1=659314C60136CF096DBA01B969992AB9F
The URL uses the following parameters:
R_TID (Required): Token ID for a token authorized for the Presence Service. This can be obtained using Authentication Services, by setting "PRESENCE" in the policy option.
R_UID (Required): User ID (or JID) of the target presentity.
R_K1 (Required): A SHA1 hash key used to secure the request.
R_MODE (Optional): Optional parameter to specific Image ("IMG") or JavaScript ("JS") mode. Default is "IMG"
R_OP (Optional): Optional parameter specific to the request mode. For example, this parameter can be used to request alternate images when using the "IMG" mode, by setting its value between 1 and 5.
R_RES (Optional): Optional parameter to explicitly retrieve presence of a specific resource.
To integrate presence in a Web site, follow these steps:
In order to generate the presence URL, the integrating site needs to first obtain an authentication token from Oracle Real-Time Collaboration Authentication Services. This is a two-step process:
Step 1 Create Session
The integrating site calls the Create Session operation to create an Oracle Real-Time Collaboration Authentication Services session. The inputs to this operation are siteID, siteauthkey and entityType (SITE). The output of this operation is a TokenObject (sessionToken in the following code extract):
AuthenticationServiceEIProxy asProxy = new AuthenticationServiceEIProxy();
asProxy._setSoapURL("http://rtc.domain.com/imtapp/AuthenticationService");
try
{
oracle_imt_service_data_TokenObject tObj =
asProxy.createSession("12345","MSJSJASDJJASDJASDASD=","SITE");
String sessionToken = tObj.getToken();
}
catch (Exception e)
{
// Process Error
}
Step 2 Request PRESENCE Token
Since the site wants to display the presence of the live help support group, it needs to then obtain a token for the PRESENCE policy.
A site may call the Request Token operation to request an Oracle Real-Time Collaboration Authentication Services token for a specific purpose. The inputs to this operation are the siteID, sessionToken, TokenProperties and PolicyObject. The following code extract requests an Authentication Services token for the PRESENCE policy:
try
{
oracle_imt_service_data_TokenProperties tProps =
new oracle_imt_service_data_TokenProperties();
tProps.setTokenPolicy("PRESENCE");
oracle_imt_service_data_TokenObject tObj =
asProxy.requestToken("12345", sessionToken, tProps, null);
String presenceToken = tObj.getToken();
String tokenID;
oracle_imt_service_data_AdhocAttribute[] adAttrs = tObj.getTokenAttributes();
for (int i = 0; i < adAttrs.length; i++)
{
if (adAttrs[i].getName().equalsIgnoreCase("TOKENID"))
tokenID = adAttrs[i].getValue();
}
}
catch (Exception e)
{
// Process Exception
}
The value of the K1 parameter is computed using the SHA1 Digest algorithm on a custom message composed using the URL parameters. This is needed since the presence request would be coming from the end-user browser and not a site. Hence, it is necessary to ensure that only presence requests authorized by a site are served. The input message to the SHA1 hash algorithm is a message obtained from the URL parameters using the following logic:
Arrange the URL parameters should be arranged in alphabetical order
Ignore parameters that do not have an assigned value
For parameters with an assigned value (other than K1), add the following string to the message:
<param_name><param_value>
In front of the above parameter-value string, include the following string:
<TOKEN><authentication_token_presence>
The Secure Hash Algorithm (SHA1) is a standard message digest algorithm, with libraries available in most programming languages. In Java, the java.security.MessageDigest class can be used for this purpose.
Assume for the sake of this example that the presenceToken returned by the requestToken step is 1000641_QAHnRTN3L8E1DVEHL3UFKYuxHcW8ce7p and the tokenID is 100641. The presence hash (K1) can be calculated as shown in the following code extract:
String tokenString = "<TOKEN>" + "<1000641_QAHnRTN3L8E1DVEHL3UFKYuxHcW8ce7p><R_MODE><IMG>" + "<R_UID><john.doe@oracle.com>"; String K1 = getJavaDigest(tokenString);
The presence URL can then be constructed as follows for the image version:
https://rtc.domain.com/imtapp/Presence? TID=100641&R_UID=john.doe@oracle.com& R_MODE=IMG&K1=B1CA85982C3221F29E0808F6DB91AFB6AB84008D
There is also a Javascript version of the presence URL that can also be generated in a similar fashion as the image version. The following is the Javascript version of the presence URL:
https://rtc.domain.com/imtapp/Presence? TID=100641&R_UID=john.doe@oracle.com& R_MODE=JS&K1=DFGJKCA85982DHJKRU28EWKJ3EWK391KKED9QKDJK
The following is an implementation of the getJavaDigest method:
private static String getJavaDigest(String inputString)
throws NoSuchAlgorithmException, FileNotFoundException, IOException
{
MessageDigest md = MessageDigest.getInstance("MD5"); //SHA1 is also supported
byte[] dataBytes = new byte[2048];
dataBytes = inputString.getBytes();
int nread = dataBytes.length;
md.update(dataBytes, 0, nread);
byte[] mdbytes = md.digest();
String s = byteArray2Hex(mdbytes);
return s;
}
private static char[] hexChars = {
'0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
'A', 'B', 'C', 'D', 'E', 'F'};
public static String byteArray2Hex(byte[] ba)
{
StringBuffer sb = new StringBuffer();
for (int i = 0; i < ba.length; i++) {
int hbits = (ba[i] & 0x000000f0) >> 4;
int lbits = ba[i] & 0x0000000f;
sb.append("" + hexChars[hbits] + hexChars[lbits] + "");
}
return sb.toString();
}
Directly embed the presence URL into HTML pages by using the SRC option in an IMG element. The following HTML extract illustrates this (line breaks inserted for clarity):
<img src="http://rtc.domain.com/imtapp/Presence? TID=100641&R_UID=OTN.SUPPORT@GROUPS.ORACLE.COM& R_MODE=IMG&K1=659314C60136CF096DBA01B2432395969992AB9F">
Use Embeddable Presence to publish your presence (availability) to others. Navigate to Preferences > Embeddable Presence after logging in to the Oracle Real-Time Collaboration Web application for more details.
In order for an action to be performed when a user clicks the image, enclose the IMG tag in an HTML address element as follows:
<a href="customaction.jsp"><img src="imageurl"></a>
To enable custom actions based on presence status, use the JavaScript version of the Presence URL. The JavaScript version returns JavaScript script that assigns values to standard variables (status, show). The following code extract illustrates this (line breaks inserted in URLs for clarity):
<SCRIPT
LANGUAGE="JavaScript"
src="http://rtc.domain.com/imtapp/Presence?
TID=100641&R_UID=OTN.SUPPORT@GROUPS.ORACLE.COM&
R_MODE=JS&K1=659314C60136CF096DBA01B2432395969992AB9F">
</SCRIPT>
<SCRIPT LANGUAGE="JavaScript">
gotoURL = "default.jsp"
if (show == "AVAILABLE") {
gotoURL = "chat.jsp"
} else if (show == "OFFLINE") {
gotoURL = "email.jsp "
}
document.write("<A href=\'")
document.write(gotoURL)
document.write("\'>Contact Me (I\'m" + status + ")</A>")
</SCRIPT>
The first <SCRIPT> segment sets the values of the "status" and "show" variables based on the presence status. The second <SCRIPT> segment consumes these values to enable the appropriate actions. In this way, a site can route its users to the appropriate destinations based on the status obtained by Presence Services. One of the possible actions is an invocation of a guest user chat session.
The live help scenario uses Oracle Real-Time Collaboration Authentication Services: John Doe purchases a product from Vision Corp. He runs into some issues while using the product and decides to visit the company Web site to see if he can find some information there. He notices that there is a "Live Help Available" button on the Web site. He clicks the button. Immediately, a chat window opens and a company service representative starts debugging John's issue. The problem is resolved in a matter of minutes and John Doe is extremely satisfied with the overall support experience he has had with Vision Corp.
This section describes how to implement this live help scenario in a Web application. It involves creating a URL for the "Live Help Available" button. To create this URL, you generate a unique, asymmetric hash key for a particular user. This key is generated using valid session information that is common to all users that belong to a given site along with user-specific information.
This hash key, along with other parameters, define a context for a request for a guest user chat. These context parameters are submitted, through an HTTP POST operation, to a custom Java Servlet page that calls imRequestorMsg.jsp, the interface file for the Web chat client of Oracle Real-Time Collaboration. This page calls a Java Applet client that establishes an XMPP (Extensible Messaging and Presence Protocol) connection with the Oracle Messenger server.
The Oracle Messenger server receives the context parameters through the XMPP connection established by the Java Applet client. The Oracle Messenger server validates the guest user chat request by recomputing the hash key by using the context parameters it has received. If the recomputed hash key matches the one submitted in the context parameters, the server will allow the guest user chat request.
The server creates a restricted temporary user for the session and allows a guest user chat with the company service representative. The life of the temporary user may extend beyond the chat session depending on Oracle Real-Time Collaboration configuration parameters, which would allow the message history be retrieved for the same user. Therefore, it is important that the live help site does not reuse userJID (a unique identifier that identifies Oracle Real-Time Collaboration users) values between different users.
The following diagram illustrates the flow of live help:
Before proceeding further, make sure you have access to the following:
An Oracle Real-Time Collaboration deployment
A valid site ID and authentication token for the Web site you would like to include presence information
The site ID provisioned for the GUESTCHAT policy
Information about groups for group presence services. These groups respond to guest user chat requests. An administrator would use the command rtcctl addGroup to create a group for this purpose. For more information about the rtcctl command, see Chapter 4, "rtcctl Command-Line Utility for Oracle Real-Time Collaboration" in Oracle Real-Time Collaboration Administrator's Guide.
As described in the section "Enable Presence in Your Web Pages," custom actions can be enabled based on presence status obtained from the Presence URL service. In order to establish a guest user chat session, complete the following steps:
Establish Context for Chat: Establish a guest user chat context from the site
Forward Request to Appropriate Clients: Forward the request context to clients such as the HTML chat client
Request Processing by Clients: The request context is processed by the clients and forwarded to the Oracle Real-Time Collaboration server in a way that they can be securely validated.
Request Processing by Server: If the request context is validated, then the server grants a guest user session.
After a user clicks the guest user chat invocation widget, the site should intercept the request to construct the necessary context. Establish this context by supplying the following parameters:
r_fromUserJID (for example, guest_user_12345@sites.oracle.com): This parameter is used to identify the end user uniquely to the Oracle Real-Time Collaboration system. A site can leverage this parameter by establishing a unique identifier for each of its users. Thus if the user visits this functionality again, it would be possible to retrieve message history for the user from the Oracle Real-TIme Collaboration system by using the same unique identifier.
guestDisplayName (for example, OTN Guest): This parameter is displayed as the guest user's name in chat sessions.
useToken: This parameter should always be set to true.
r_groupJID (for example, otn.support@groups.oracle.com): This parameter is the target group with which the chat session is to be established.
r_toJID: Use this parameter if you want to establish a chat session with an individual user instead of a target group.
s: Subject (for example, Pricing on OCS)
In addition, the following security parameters are needed:
tokenID: This is the tokenID of a Authentication Token obtained from Authentication Services using a policy of "GUESTCHAT"
tokenDigest: A hash key used for secure validation on the server side. Details about how to compute this parameter are given in the following section.
In order to implement guest chat, the integrating site needs to obtain an Authentication Token for the GUESTCHAT policy from Authentication Services. This is a two-step process:
Step 1 Create Session
Call the Create Session operation from the integrating site to create an Authentication Services session. The inputs to this operation are the siteID, siteauthkey and entityType (SITE). The output of this operation is a TokenObject (sessionToken in the following code extract):
AuthenticationServiceEIProxy asProxy = new AuthenticationServiceEIProxy();
asProxy._setSoapURL("http://rtc.domain.com/imtapp/AuthenticationService");
try
{
oracle_imt_service_data_TokenObject tObj =
asProxy.createSession("12345","MSJSJASDJJASDJASDASD=","SITE");
String sessionToken = tObj.getToken();
}
catch (Exception e)
{
// Process Error
}
Step 2 Request GUESTCHAT Token
Since the site wants to display the presence of the live help support group, it needs obtain a token for the GUESTCHAT policy.
Call the Request Token operation from the site to request an Authentication Services token for a specific purpose. The inputs to this operation are the siteID, sessionToken, TokenProperties and PolicyObject. The following code excerpt requests an Authentication Token for the GUESTCHAT policy:
try
{
oracle_imt_service_data_TokenProperties tProps =
new oracle_imt_service_data_TokenProperties();
tProps.setTokenPolicy("GUESTCHAT");
oracle_imt_service_data_TokenObject tObj =
asProxy.requestToken("12345", sessionToken, tProps, null);
String presenceToken = tObj.getToken();
String tokenID;
oracle_imt_service_data_AdhocAttribute[] adAttrs = tObj.getTokenAttributes();
for (int i = 0; i < adAttrs.length; i++)
{
if (adAttrs[i].getName().equalsIgnoreCase("TOKENID"))
tokenID = adAttrs[i].getValue();
}
}
catch (Exception e)
{
// Process Exception
}
The tokenDigest parameter is a wrapper around an MD5 message digest (hashkey) of a message composed from context parameters. The tokenDigest parameter is computed in a manner similar to how the presence URL hash key is generated. Specifically, the following are the steps for creating this hash key are:
Arrange the context parameters in alphabetical order.
For parameters with an assigned value (other than tokenDigest), add the following string to the message (including the angle brackets):
<param_name><param_value>
After all parameters have been added, add the following string to the beginning of the message (including the angle brackets):
<token><token_value>
Note: Currently only three context parameters are supported (r_fromUserJID, r_toJID in the case of target users, and r_groupJID in the case of target groups). An example of the final concatenated string would look similar to the following:
<token><12345_ASDASLjaasljdaSAD><r_fromUserJID> <guest_user_12345@sites.oracle.com><r_groupJID><otn.support@groups.oracle.com>
The resulting message is then processed by the MD5 algorithm to obtain a hashKey. The MD5 algorithm is a standard message digest algorithm, with libraries available in most programming languages. In Java, the java.security.MessageDigest class can be used for this purpose.
Once the MD5 digest (md5digestValue) is generated successfully, the tokenDigest parameter is a hexadecimal conversion of the string that is constructed as follows:
12345_<digest><md5digestValue><r_fromUserJID> <guest_user_12345@sites.oracle.com><r_groupJID><otn.support@groups.oracle.com>
Note: The above string is constructed as follows:
tokenID + "_" + "<digest>" + "<" + md5digestValue + ">" + attributeString
The value of attributeString is constructed as follows:
attributeString = "<r_fromUserJID><guest_user_12345@sites.oracle.com> <r_groupJID><otn.support@groups.oracle.com>"
The following code extract illustrates these steps. See "Compute Presence Hash Key (K1) and URL" for an implementation of the getJavaDigest and byteArray2Hex methods.
String inputString = "<token><" + tObj.getToken() + ">" + "<r_fromUserJID><guest_user02@sites.oracle.com>" + "<r_groupJID><otn.support1@groups.domain.com>"; String javaDigest = getJavaDigest(inputString); String guestUserDigestUnencrypted = tokenID + "_<digest><" + javaDigest + ">" + "<r_fromUserJID>" + "<guest_user02@sites.oracle.com><r_groupJID>" + "<otn.support1@groups.domain.com>"; byte[] dataBytes = new byte[1024]; dataBytes = guestUserDigestUnencrypted.getBytes(); String tokenDigest = byteArray2Hex(dataBytes);
The following is an example of a guest chat URL (line breaks inserted for clarity):
http://rtc.domain.com/imtapp/im/imWebChatClient.jsp? r_groupJID=otn.support1@groups.domain.com& useToken=true& r_fromUserJID=guest_user02@sites.domain.com& tokenDigest=313030303634305F3C6469676573743E3C313636363144303035393031303035& tokenID=1000640& s=Hello& siteID=12345
In addition to establishing the request context, this interception by the site gives the site to re-confirm the user's credentials. This step is recommended to ensure that the guest user feature is not being invoked from a Web page that has been rendered outside the context in which it was generated. For example, if the original Web page was emailed to a group, the recipients should not automatically be able to invoke the guest user chat feature unless they can be authenticated and authorized by the site.
The parameters described in the previous section define a context for the guest user chat. These parameters are communicated to the appropriate clients though a Web page (http://rtc.domain.com/imtapp/im/imWebChatClient.jsp), which is hosted by the Oracle Real-Time Collaboration server. The parameters should be submitted to this page through an HTTP POST operation. Currently, only a Java applet client is supported. Hence, the receiving page will download this Applet with the context parameters. This page will automatically provide additional parameters needed by the client. For example, the IP Address and port number of the Oracle Messenger server may be provided as additional parameters to the client.
The Java applet client will establish an XMPP connection with the Oracle Messenger server and submit the required user and security context parameters. Since these parameters are submitted by the applet from the user's console, it is necessary to ensure that the request parameters can be secured. This is achieved using the tokenDigest.
The Oracle Messenger server receives the context parameters through the XMPP connection established by the client. It is the duty of the Oracle Messenger Server to ensure the validity of the request and enforce the guest user chat restrictions communicated through the context parameters. Oracle Messenger validates the request by recomputing the request hash key using the parameters it receives (the Oracle Real-Time Collaboration server may do this by itself or delegate it to Authentication Services). If the hash key computed by the server matches the one submitted in the parameters, the server will allow the request.
The Oracle Real-Time Collaboration server will create a restricted temporary user for the session and allow a guest user chat session with the target user. The life of the user may extend beyond the session, based on the Oracle Real-Time Collaboration server configuration parameters. As a result, the message history may be retrieved for subsequent interaction by the same user. Hence, it is important that the site does not reuse the userJID values between different users.
