25 Using the Web Presence API

About the Instant Messaging Server Web Presence API

Users of instant messaging are typically able to see a contact list showing whether individual contacts are available. Instant messaging users who are not contacts typically do not receive such presence information. Instant Messaging Server provides a Web Presence API that allows a Web application to obtain presence information from Instant Messaging Server and display it to users, independent of whether they are contacts. An example of where this is useful is an enterprise application that provides an employee listing with information such as employee name, department, title, location, and phone number. If the application provides availability information, it may help a user who looks up an employee to decide whether to make a phone call, send an email, or look for someone else to contact.

For a Web application to obtain presence information from Instant Messaging Server, it needs to use the new Web Presence API and the Web Presence API must be configured to allow use by the Web application. In addition, any Instant Messaging server that the Web Presence API communicates with must be configured to recognize the Web Presence API (see "Configuring an Instant Messaging Server to Recognize the Web Presence API").

Web Presence API for Requesting Presence Information

When a user's instant messaging application starts and contacts Instant Messaging Server, it sends presence information about the user. A web application can then obtain this information from Instant Messaging Server by making an HTTP GET or HTTP POST request that uses the Web Presence API. The request can be for the availability of a single user or of multiple users.

InstantMessaging_home/lib/presenceapi-web.xml.template

GET /presence/node@domain.com/resource

GET /presence?request={JSON object}

[{"presence":{"type":"probe","to":"node@domain/resource"}},{"presence":{"type":"probe","to":"node1@domain1/resource2"}},{"presence":{"type":"probe","to":"node2@domain/resource3"}}]

POST /presence

request:JSON object

POST /presence

request:[{"presence":{"type":"probe","to":"node@domain/resource"}},{"presence":{"type":"probe","to":"node1@domain1/resource2"}},{"presence":{"type":"probe","to":"node2@domain/resource3"}}]

{"response":[{"presence":{"show":"dnd","from":"node@domain/resource "}},{"presence":{"show":"away","status":"temporarily unavailable ","from":"node1@domain/resource"}},{"presence":{"from":"node2@domain/resource"}}]}

Configuring the Instant Messaging Server Web Presence API

For a Web application to obtain and display presence information, you must configure properties in the Web Presence API's configuration file. A template for the configuration file is installed in: InstantMessaging_home/lib. There is no required name or location for the configuration file.

Table 25-1 lists Web Presence API configuration properties.

Configuring an Instant Messaging Server to Recognize the Web Presence API

The Web Presence API is an XMPP component that communicates with Instant Messaging Server. The Web Presence API must be configured to communicate with the Instant Messaging Server, and Instant Messaging Server must be configured to receive communications from an XMPP component. This requires using the imconfutil command to add the Web Presence API as a component of the Instant Messaging Server, as in the following example:

imconfutil -c InstantMessaging_home/config/iim.conf.xml add-component id=presenceapi jid=presenceapi.example.com password=drowp broadcastpresence=true

where:

• jid must be set to the same value as the Web Presence API's ImServer1.componentjid property.

• password must be set to the same value as the Web Presence API's ImServer1.password property.

• broadcast must be set to true to allow Instant Messaging Server to send presence information to the Web Presence API.

After adding the Web Presence API as a component to Instant Messaging Server, restart the server:

imadmin refresh server

Configuring and Testing the Web Presence API

This section provides steps for configuring and trying out the Web Presence API before you have done more extensive application development. The steps cover:

• Configuring and deploying the Web Presence API on a local machine.

• Configuring Instant Messaging Server for the Web Presence API and restarting the Server.

• Logging a user in to Instant Messaging Server through an XMPP client.

• Sending a GET request for the user's presence to Instant Messaging Server and viewing the response.

To configure and test the functionality of the Web Presence API:

1. Use the iwadmin command to create a ZIP file for the Web Presence API that you can move to another machine or keep locally:

   iwadmin generatezip presenceapi -c /local/presenceAPI/config/presenceapi.conf -d /tmp/presenceapi.zip
   

   where:

   • The -c parameter specifies the future location of the configuration file for the Web Presence API, once the ZIP file is unzipped.

   • The -d parameter specifies a destination directory and file name for the ZIP file. The directory must exist before you generate the ZIP file.

   • The ZIP file contains:

     • A deployable WAR file for the Web Presence API

     • A template file (presenceapi.conf.template) to use for creating a Web Presence API configuration file.

     • A template file, presenceapi_log4j.conf.template, for configuring a log4j log file.

     • The Instant Messaging Server password tool. See "passwordtool Command Reference" for more information.

2. Extract the contents of the ZIP file to the directory that you want to use as your Web Presence API configuration directory, for example, /local/presenceAPI.

   unzip /tmp/presenceapi.zip -d /local/presenceAPI
   

3. To create a configuration file for the Web Presence API, copy the configuration file template, presenceapi.conf.template, to presenceapi.conf.

4. In presenceapi.conf, edit the following lines according to the instructions below them.

   presenceapi.config=default
   

   default.presencepolicy=open
   

   default.domains=DOMAINS_LIST
   

   default.hosts=HOSTS_LIST
   

   default.componentjid=COMPONENT_JID
   

   default.password=ENCRYPTED_COMPONENT_PASSWORD
   

   presenceapi.log4j.config=LOG4J_CONFIG_FILE
   

   # Comment out the following options if you are not using an encrypted password.
   

   presenceapi.component.password.cipher.delegate=DELEGATE_CLASS
   

   presenceapi.component.password.cipher=CIPHER_CLASS
   

   For information about the configuration properties above, see Table 25-1.

   1. Leave the first two entries, presenceapi.config=default and default.presencepolicy=open as they are.

      The first property identifies a deployment of Instant Messaging servers as default.

      The second property sets the deployment to provide presence information for contacts in all domains, except for domains that are listed with the default.domains property.

   2. Delete default.domains=DOMAINS_LIST. There is no need to restrict the domains open to presence requests in this example.

   3. Set default.hosts to a space-separated list of the Instant Messaging servers and their ports (hostname:port) that make up the default deployment. For example:

      default.hosts=ImServer1.example.com:5269 ImServer2.example.com:5269
      

   4. Set default.componentjid to the JID of the Web Presence API in its Web server. The same JID must be entered when you use the command to configure Instant Messaging Server at a later step. Example:

      default.componentjid=presenceapi.example.com
      

   5. Set default.password to the password you want to use in connecting to Instant Messaging Server. The same password must be entered when you use the command to configure Instant Messaging Server at a later step. Example:

      default.password=asdfjkl;
      

   6. Set presenceapi.log4j.config to the absolute path of the log4j configuration file. For example:

      set presenceapi.log4j.config=/local/presenceAPI/config/presenceapi_log4j.conf
      

5. Deploy the Web Presence API WAR file.

   • GlassFish Server: Use the asadmin command to deploy the Web Presence API WAR file (you will need Administrator privileges), for example:

     asadmin deploy /local/presenceAPI/presenceapi.war
     

   • Oracle WebLogic Server: use WebLogic console to deploy the Web Presence API WAR file.

6. Use the imconfutil command to add the Web Presence API as an XMPP Web component to the Instant Messaging server identified as ImServer1:

   imconfutil -c InstantMessaging_home/config/iim.conf.xml add-component id=presenceapi jid=presenceapi.example.com password=asdfjkl; broadcastpresence=true
   

   where:

   • jid must be set to the same value as the Web Presence API's ImServer1.componentjid property.

   • password must be set to the same value as the Web Presence API's ImServer1.password property.

   • broadcast must be set to true to allow Instant Messaging Server to send presence information to the Web Presence API.

7. Restart Instant Messaging Server using the imadmin command. This is necessary because of the configuration changes you made to the Server.

   imadmin refresh server
   

8. In preparation for the next step, sending a request for presence information, get the JID of a user that is logged-in to Instant Messaging Server through an XMPP client. If you have an instant messaging account on an XMPP client that uses the Instant Messaging Server, and your XMPP client is running, you can use your own JID.

9. Send a GET or POST request for presence information to the Web Presence API, using the JID from the previous step.

   • You can send a GET request manually by entering it directly in the address bar of a browser and pressing Return. The following is an example of such a request. Note the / that follows the JID. Without it, the JID is interpreted as a file name and the request fails.

     http://imhost@pythia.com:8080/presenceapi/presence/wxyz@example.com/
     

     If the request is successful, a JSON object with presence information is displayed in the browser, as in the following example:

     {"response":[{"presence":{"from":"wxyz@example.com/1379305740520"}}]}
     

   • You can send the request from a JavaScript, in which case the response is returned to the script as a JSON object.

10. Verify that the response received is what was expected.