This documentation is archived and is not being maintained.

Enhanced Presence Data Model

Unified Communications uses a publication and subscription model for enhanced presence data. For example, if Alice has presence data that she wants viewed by Brad, she publishes that data to Office Communications Server and Brad subscribes to it using an application, such as Office Communicator or an application that was created specifically for his business and designed to interoperate with Office Communicator.

Entities that are capable of publishing presence information about themselves are called presentities. Presentities are typically users, but they can also be a service or an application. Presentities publish presence information for subscribers to view and applications display their presence.

Consider the following situation for a presentity named Alice: Brad is in Alice’s company and on Alice’s team, whereas Colleen is in Alice’s company but not on her team. Alice may want Brad to see a higher level of detail about her presence than Colleen. To handle this situation, Unified Communications uses a concept called containers. A container holds a list of members and a set of data that the members can access. In other words, the container specifies access through a mapping between members and data. The members define which subscribers have access by specifying a scope that encompasses either one potential subscriber or a set of potential subscribers. Consider an example where Alice has added a member for Brad (that is, whose scope is limited to Brad) to her team contacts container and then published a note to that container; in addition, Colleen has added a member for David to her team contacts container and also published a note to that container. Alice’s Team container would contain her note as well as the information that Brad has access to it and Colleen’s Team container would container her note with the information that David has access to it. Because Colleen is in Alice’s company, she has access to information in Alice’s Company container, but not her Team container; therefore, she does not have access to Alice’s note in her Team container.

In addition to members whose scope is limited to individual users, containers can have special members that allow access to groups of subscribers. For example, containers can have a special member that gives access to everyone from the same domain as the presentity. The following types of members are allowed: user, domain, sameEnterprise, federated, publicCloud, or everyone. More information about membership can be found in section 3.5.5.2 of [MS-PRES]: Presence Protocol Specification.

When published to a container, data remains in that container until the data expires or is replaced by newer data of the same type. When data is published to a container, it is published with an expiration type that determines whether and when it expires. For example, data that says that a device is being actively used expires after a few minutes unless the device is used again, whereas data about a user setting a “Do Not Disturb” availability does not expire and remains in the state until the user sets the availability to another value or the user logs off.

Containers are identified by a container ID, which is an integer. Because a subscriber can be included in the scope of members of several containers, each containing different published data, a series of rules are followed to determine which container has the data that the subscriber sees. Office Communications Server returns data from the container whose member has the narrowest scope that contains the user (that is, first user, then domain, and so on.), and among all the containers that have members of that type, it returns the data from the container with the highest container ID. For example, if a user is specified as a user for members in containers with IDs of 100 and 200, and her domain is specified in a member in a container with an ID of 300, she sees the data that has been published to the container with the ID of 200, because the member in container 200 has the narrowest scope (user) and of the containers of type user, it has the highest ID.

A complete list of rules about subscribers and containers can be found in section 1.3.1.2.7 of [MS-PRES]: Presence Protocol Specification. The following sequence summarizes how a subscriber is resolved to a container:

  1. Select the highest numbered container that contains both the category and the subscriber in the container's URI list. If a matching container is found, stop.
  2. Select the highest numbered container that contains the category and a domain membership list with the subscriber's SIP domain. If a matching container is found, stop.
  3. If the subscriber is a user from the same enterprise, select the highest numbered container that contains the category and has a member that allows access to users from the same enterprise. If a matching container is found, stop.
  4. If the subscriber is a federated user, select the highest numbered container that contains the category and has a member that allows access to users from the federation. If a matching container is found, stop.
  5. If the subscriber is a public cloud user, select the highest numbered container that contains the category and has a member that allows users from the public cloud. If a matching container is found, stop.
  6. If the default container (container with ID = 0) contains the category, select the default container and stop.

As previously mentioned, presence data is published to Office Communications Server in the form of an XML payload of a SIP message, which in turn is sent to the subscribers. Each piece of enhanced presence data belongs to a category, and each category is identified by a string name that specifies a type of data. The category name implies a schema that is agreed on for client applications about how the data is published and how it should be interpreted. For example, a category with name “state” contains data about the state of some aspect of the presentity. The enhanced XML schemas for the categories that are used by Office Communicator by default can be found in the Unified Communications Enhanced Presence Schemas for Microsoft Office Communications Server 2007.

A category XML schema defines many individual data elements. For example, there are several types of states that can apply to a presentity: a user state indicates the availability of the presentity based on user action, a machine state indicates the activity of the device used by the presentity, and a phone state indicates whether the presentity is on the phone, and so on. Each piece of data is called a category instance, and it is identified by an ID that is integer. A category instance is uniquely defined by a three-part key: the container ID, the category name and the container instance ID.

As an example, consider the user state, which is identified by the category name “state” and the category instance ID of 2. Our user, Alice, might have multiple devices running an application that allows her to specify her availability. If she specifies “Do Not Disturb” from one device, a category instance of category “state” and category instance ID of 2 is published to the appropriate containers. When she sets her state back to “Available” using the application on a different device, the application on that device publishes a new user state category instance of category “state” and category instance ID of 2, and now a newer version of the instance is in the container. Brad, who subscribes to her state, sees her availability first as “Do Not Disturb,” and then as “Available.”

The user state has the same category instance ID, regardless of which device publishes the data, because the device is irrelevant to the information being published. However, other states, such as the machine state, need to have a category instance ID that is unique to the device. If one of Alice’s devices has been idle for an hour, this does not mean that she has been idle because one of her other devices might have been actively used. To track this, all machine states need to have a category instance ID that is unique for the device so that it’s possible to distinguish between devices that are publishing state. For example, for Office Communicator, the machine state is an integer that begins with 0x3 when expressed as a hexadecimal number. The remaining seven hexadecimal digits uniquely define the device.

Category instance IDs for calendar data, such as when a presentity is in a meeting, are required to be unique by the data that identifies the calendar, such as the SMTP address. A similar approach can be used, where the first hexadecimal digit is used to identify what kind of calendar data and the remaining digits identify the calendar. Category instance IDs for phone states, such as when the presentity is on the phone, should be unique by phone line. For Office Communicator, the category instance ID has the first hexadecimal digit be used to identify what kind of phone (such as RCC and VOIP) and the other digits are unique to a URL that specifies the phone line.

When category instances are published, an expiration type is specified that indicates whether and when they are automatically removed from a container. For example, if an Office Communicator user manually changes state to “Available”, the user state is published with an expiration user type, which expires when the user logs off. The following table describes the expiration types.

Category Instance Expiration Types

Expiration typeDescription

Device

The category instance expires when the hosting device is shut down.

None

The expiry type is not specified. The API sets this flag if the expiration type of a category instance cannot be determined. An application must not set this flag to publish any category instance.

Static

The category instance does not expire.

Time

The category instance expires after a specified time.

User

The category instance expires when its owner is logged off.

Office Communications Server requires that category instances contain the following XML attributes when published: category name, category instance ID, container ID indicating the container to publish to, and expiration type. If they have an expiration type of time, the expiration time is also required. The category instance will have a value attribute that is also XML, and the schema for this data depends on the category, as described in the Unified Communications Enhanced Presence Schemas for Microsoft Office Communications Server 2007.

The instances are also published with a version attribute, whose value is an integer. The most recent version of an instance will have the highest version value. A description of how versions are handled is in section 1.3.1.5.1 of [MS-PRES]: Presence Protocol Specification. Publishers present the current version number when they request that an item be updated. The server updates the instance and increment its version number only if the publisher-provided version number matches the current version. As a developer, you do not need to specify the version number when publishing an instance, because this is handled by the SDK.

Version numbers can become important in determining whether information is outdated. For example, if an application attempts to publish a category instance with a version of 30, but the application is disconnected from the server for some time, there might be a situation where another device publishes successfully its equivalent category instance with the same version of 30. Sometime later, when the first application reconnects, it might try to republish that category instance. Because a category instance with version 30 has already been published to that container, the server requires that the version number be 31 or higher to publish, so it does not publish the outdated category instance.

Office Communicator uses this data model and has specific uses for certain containers, categories, and category instance IDs. The following sections describe how Office Communicator makes use of containers and categories. If you are developing an application using Unified Communications and you either want to display presence information that is set by Office Communicator or want to publish presence information that Office Communicator will display, you need to understand which containers and categories Office Communicator uses. You can create a Unified Communications application that does not interact with Office Communicator at all, but you will want to avoid certain containers and categories so you do not interfere with how Office Communicator operates.

Show: