Publishing and Subscribing to Presence
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
User presence describes the availability status and other information about a user. Presence is useful in facilitating real-time communications between a user and others. When the user is busy, she can publish her presence state as "Busy" to inform other users that she is not available to take calls or chat using instant messaging (IM). It is possible to subscribe to the presence of any federated user. As an example, if a user logs on to Microsoft Windows Live Messenger, the user's presence can be detected and displayed if it is queried or subscribed to.
A presence subscription persists for the duration of a Unified Communications session. Future Unified Communications sessions do not remember prior presence subscriptions unless the remote user is subscribed to again. To create a permanent subscription, the remote user must be added to a contact list with an instruction to the server to make the subscription permanent. For more information about adding and subscribing to contacts, see the addContact Request.
In Unified Communications, presence data is represented by category instances. Categories can be system-defined (also known as well-known categories) or application-specific (also known as custom categories).
The Microsoft Office Communicator 2007 enhanced presence model is specifically designed to meet the requirements of information workers in the enterprise. The primary purpose of presence awareness is to enhance the communication and collaboration experience. Enhanced presence awareness helps users make informed decisions about the availability and willingness of colleagues to communicate at any given time. All presence information is collected and published in the least intrusive manner possible by employing automatic sensors to detect a users presence status. However, users can also manually set their own presence status when desired. See The Enhanced Presence Model.
Well-Known Categories
Well-known categories have predefined category names and data structures with which the presence data and its metadata are specified. Some examples of well-known categories include:
contactCard: This category specifies contact information such as the display name and work telephone number of the presence publisher. The category name, contactCard, is specified by the name attribute of the cwaCategory element. The presence data, the display name of the user, is specified in a displayName child element under the cwaCategory element. Other attributes are determined at run time. Contact card data is updated by a Communicator Web Access Server when user information is changed in an organization's Active Directory.
state: This category provides an aggregated user state of the presence publisher. The category name is specified by the name attribute of the category element. The presence data, namely, the aggregated state information, is specified in a state child element under the category element. Other attributes are determined at run time. The aggregateState is actually an aggregation of user, device, and other individual states. A Communicator Web Access Server calculates an aggregate state for each user based on the individual user and machine state published by the client. The client should publish the user state value when the logged on user wants to change his apparent online status. Machine state should be published after a client specific time of inactivity has elapsed. If a client workstation is re-activated, the machine state should be published again. Machine state is also communicated to a Communicator Web Access Server with each GET polling request on the data channel. See Setting Up Data Channels for information about polling requests.
Note: This category can be used to provide a descriptive message when the presence publisher either is out of office or present. The category name, Note, is specified by the name attribute of the category element. The presence data, namely, the descriptive text message, is specified in a note. Note data is static and should only be published when the local user has modified her presence note data in the client interface.
calendarData: This category contains free/busy time blocks for a user as well as her normal work hours. Like the note category, this should only be published when the user changes a value.
Routing: Inbound call routing that define forwarding for a UC enabled telephone.
For more information about well-known categories, see the cwaCategory element.
Custom Categories
An application may need to deal with other presence information. For example, a Global Positioning System (GPS) service provider may want to provide location information as part of the presence data. Developers of such applications can create or use one or more custom categories for this purpose. An example of such custom category could be:
gpsLocation: This category could provide GPS coordinates of the publisher. The developer specifies that the name attribute of category is gpsLocation and the XML schema for the category is as follows:
<rawCategory name="gpsLocation" version="..." instance="..." container="..." expireType="..." doNotNotify="..." publishTime="..."> <coordinates L="..." A="..." /> </rawCategory>The developer can choose some other XML schema for the child element as the custom presence data. She needs to make available this category schema to other applications if she wants this presence data accessible by users of other Communicator-compatible clients. Otherwise, the custom presence data is ignored by the other clients. For more information, see pubishRawCategories.
Subscribing to Presence
In a Unified Communications AJAX API client application, subscribing to a user presence amounts to performing the following tasks:
Specify users whose presence data is of interest
Specify categories of interest
Handle presence publication event notifications
Specifying users
To specify which user's presence to watch, a Unified Communications API client application makes a subscribePresence request to a Communicator Web Access Server. For example, the following example request indicates that the caller is interested in being notified of the presence data of two people (John and Adam) at contoso.com. If the Unified Communications API client application is requesting a subscription for a user who is already subscribed to, the subscribePresence request is rejected.
<subscribePresence rid="43">
<uris>
<uri>sip:john@contoso.com</uri>
<uri>sip:adam@contoso.com</uri>
</uris>
</subscribePresence>
By default, a user is given a subscription to the presence of the contacts listed in the user's contact list.
The application can also let a user cancel the subscription, in part or as a whole, by submitting an unSubscribePresence request.
Specifying categories
A Unified Communications API client application lets a user subscribe to certain categories when a user session is initiated. It does so by specifying the categoryEventFilter child element when making an initiateSession request.
The content of a categoryFilter element can be a list of names of the categories to which the caller wants to subscribe.
For example, the following request lets the caller subscribe to the following categories:
State
contactCard
userInfo
gpsLocation
The first three are all well-known categories and the last one is a custom category.
<?xml version="1.0" encoding="UTF-8"?>
<cwaRequests sid="0" xmlns="http://schemas.microsoft.com/2006/09/rtc/cwa">
<initiateSession rid="1">
<categoryFilter>aggregateState displayName mobilePhone1 gpsLocation
</categoryFilter>
</initiateSession>
</cwaRequests>
The categoryFilter element is optional. When it is absent, the Unified Communications API client application subscribes to a list of default categories, drawn from the well-known categories, on the caller's behalf.
Category subscription is session-specific. It can only be specified when a session is initiated.
Handling Presence Publication Event Notification
When a subscribed presence category instance is published or updated, the subscriber receives a userPresence event. A Unified Communications AJAX API client application is responsible for parsing the events and displaying the presence data to the user.
Publishing Presence
A user publishes her presence by sending the server a publishSelfPresence request with current machine and user state plus a list of new or updated category instances, each of which is bound to a specific container on the server.
State. This type of data is published quite frequently. Without frequent and accurate publishing of this information, the Communicator Web Access Server is unable to publish accurate information about the aggregate state of a local user to subscribing remote users. State can be communicated to a Communicator Web Access Server in a state category or as a parameter of a GET polling request. State is composed of two elements. Machine state is based on the activity level of a user on a device. Client application logic is responsible for determining the keyboard or mouse activity of the local user, otherwise known as user activity. The client provides a true | falsevalue to a Communicator Web Access Server with each polling request made on the asynchronous data channel. See Setting Up Data Channels for information about polling requests. User state is defaulted to a value of 3500 when a user initiates a session. It is possible to specify a different user state on session initiation. See the initiateSession element for information about this. If a client provides the functionality, a user can set her online state manually. For example, a user can set her state to 15500 (Away) on a device even though she remains active on the device. User state must be published using the publishSelfPresence request. See userStateAvailability Element for a list of possible user states.
Category instances. Well-known category instances are primarily static in nature. Such a category is only published when values change. The exception is the state category. When state is published as a category, it is normally the user state component that is published. The publishSelfPresence Element provides an example of publishing user presence.
The server manages presence publication with a container that holds a list of users and a list of category instances. When a Publish request is received, the server notifies the users in the container of the changes of the contained category instances. Containers are identified by numbers. For example, the following Publish request broadcasts a new customNote category instance to inform all the members of Container 300 that John (of contoso.com) has a package for each and every one of them.
<selfPublish rid="3">
<cwaCategory name="" version="0"
instance="0" doNotNotify="False" expiryType="static"
expires="-1" >
<note value="" />
</cwaCategory>
</selfPublish>
Container Membership
Presence publication amounts to assigning a potential subscriber to one or more containers of one or more categories. A Unified Communications API client application does this by making an updateContainer request. For example, the following request adds one user and deletes another ("donh" and "adam" of contoso.com) to the membership of Container 300. If the container does not exist, the server creates one before adding the members.
<updateContainer rid="2">
<container id="300" version="6">
<addMember type="uri" value="sip:donh@contoso.com" />
<deleteMember type="uri" value="sip:adam@contoso.com" />
</container>
</updateContainer>
Effectively, a container describes how a set of category instances are published to its members. For example, one container can be used to let everyone watch the availability status of the publisher, plus her e-mail address. Another one can be used to let only members of the team of the publisher to view her presence information that including work and cell phone numbers. Yet another container can be used to block the specified user from viewing the presence information of the publisher. Again there are well-known containers and there can be custom containers. Behaviors of well-known containers are system-specified and those of custom containers are application-specific.
A container represents an Access Control List. That is, the container holds a list of individual user URI's and domains. When a custom rawCategory is associated to one of these containers by the container attribute of the rawCategory, you are allowing the users and domains in that container to receive the data you have placed in the rawCategory. Well known cwaCategory data has already been associated to well-known containers by the Communicator Web Access Server.
Well-Known Containers
The following is a list of some commonly used well-known containers.
Container ID |
Description |
|---|---|
100 |
Presence is accessible by all federated users. |
200 |
Users from the same company can access the presence data of the publisher. |
300 |
The team members of the publisher can access the presence data of the publisher. |
400 |
Specified subscribers have unrestricted access to the presence data, including sending a potentially interruptive IM invitation when the publisher's status is displayed as Do Not Disturb. |
32000 |
The specified members are blocked to view the presence data. The category instances should be empty category elements. |
A publisher may assign a user to multiple containers (say, Container 400, 300, and 200). When the publisher publishes her gpsLocation raw category to Container 300 and 200, the user only receives notification of category from one container. In this case, it is Container 300. That is, a container with a higher ID value takes the precedence.
Well-known presence categories have predefined containers associated with it. Explicit specification of container ID and other category metadata are not required. In the following example, userState is a well-known category. Its default container is Container 400.
< selfPublish rid="29">
<cwaCategory name="userState">
<state availability="3500" set="manual" />
</cwaCategory>
</selfPublish>