This documentation is archived and is not being maintained.

OC Presence: Category Instances

A table of all the category instance IDs that Office Communicator uses is shown in the Table of Office Communicator Containers and Categories section. A good example is the user state, which is published when the user sets availability using the Office Communicator user interface, as in the following figure. The Office Communicator server then uses a script to implement a process called aggregation. Aggregation uses various published states to come up with a final availability value, which is then published to other containers. This process is described in the Aggregation section below.

Setting user state with Office Communicator
Dd941370.346085b5-0a4b-45a8-948b-b16bf0304862(en-us,office.13).bmp

Aggregation is the process of taking multiple pieces of data and analyzing them to determine the availability state for a user. Office Communications Server uses an Aggregation script designed for Office Communicator to make this calculation. The Aggregation script gathers state category instances published by all the endpoints that a specific user has signed in to Office Communications Server from, such as Office Communicator. Examples of these state instances include the devices the user is logged into, Unified Communications phones, and calendaring systems, such as the Microsoft Exchange Server. The Aggregation script aggregates all the individual category state instances into an availability number that it then publishes to other containers. For example, Office Communicator might publish that a user is available based on Exchange data (that is, there are currently not any meetings on the user’s calendar), and it might use information from the user’s device to publish that the machine is active, but it might also publish a Busy user state because the user has selected it. The Aggregation script then calculates and publishes an aggregate state of Busy, because a user state of Busy gets priority in this situation.

The Aggregation script’s algorithm is quite complex, taking into account whether users have been active on one or more machines, whether they are on the phone, whether they are scheduled for a meeting, and so on. This algorithm is not described in this paper, but details can be found in section 3.8 of [MS-PRES]: Presence Protocol Specification.

Office Communicator publishes state category instances to containers 2 and 3 (Aggregation 1 and Aggregation 2). Office Communications Server takes the data that is published to these two containers and uses the Aggregation script to calculate an Availability state. The Aggregation script then publishes this state to containers 100, 200, 300, and 400 (Public, Workplace, Team, and Personal). The reason there are two aggregation containers is discussed later.

The aggregated presence state is defined as an integer, and Office Communicator defines the availability ranges listed in Table 5. Using ranges instead of single values allows additional information to be communicated, as described in the States section. The states that end with “Idle” mean that the presentity’s devices have been inactive past the Idle timeout, but not inactive past the Away timeout. When the devices are inactive past the Away timeout, the state changes to Away.

Availability Ranges

Aggregated Presence State Description

3,000-4,499

Available

4,500-5,999

Available – Idle

6,000-7,499

Busy

7,500-8,999

Busy - Idle

9,000-11,999

Do Not Disturb

12,000-14,999

Be Right Back

15,000-17,999

Away

18,000 and higher

Offline

The two Aggregation containers operate identically with one important exception: container 2 (Aggregation 1) publishes to containers 100, 200, and 400 (Public, Company, and Personal), whereas container 3 (Aggregation 2) publishes to container 300 (Team). This allows applications to have special behaviors for members of the Team container. If a user chooses the “Do Not Disturb” state from the Office Communicator user interface, Office Communicator publishes a “Do Not Disturb” user state into container 2 (Aggregation 1). Members of the containers 100, 200, and 400 then see a “Do Not Disturb” presence icon, and they are not able to phone or send messages to that user. However, the experience for members of container 300 (Team) is different, because Office Communicator publishes an “Urgent Interruptions Only” user state (Availability = 6900) to container 3. As a result, Team members are aware that they should only contact the user if the situation is urgent, and Office Communicator does allow phone calls and messages from members of the Team container.

The state category is used to capture information about anything that can be in any number of states. The state schema is defined as containing an availability value, an activity string, or both. The availability is defined as an integer and the activity is typically a string with further information about the state. For example, an availability value might signify “Busy” and an activity might be “On a Call”.

The schema for the state category is described in the st:state section of the Unified Communications Enhanced Presence Schemas for Microsoft Office Communications Server 2007.

Availability and Activity

Office Communicator uses the Availability Ranges table above when publishing user state and interpreting availability. Based on where the aggregated state falls in the table, it displays an availability string. In addition, a client application can create a set of custom activities that map across a range of availability, using either standard strings (tokens) or custom strings to describe the activity. When an availability value falls within the range of at least one custom activity, the Aggregation script publishes the state with the activity token or custom string and Office Communicator displays that string rather than the standard availability string. Table 6 shows the activity tokens that the Aggregation script uses and their availability ranges. If a token is used, Office Communicator displays the appropriate string depending on the locale; if a custom string is used, the locale ID might need to be specified for it to be displayed by Office Communicator. If an availability falls into more than one activity range, the activity whose minimum availability is closest to the availability is the activity whose token is displayed. Which type of state was published by the client influences which activity token the Aggregation script publishes. For example, if Office Communicator published a calendar state with an availability of 6500, the Aggregation script sets the published state’s token to “in-a-meeting”. However, if Office Communicator published a phone state with an availability of 6500, this takes precedence over the calendar state and the Aggregation script publishes with the “on-the-phone” token.

Ranges for Activity Tokens

Activity token Minimum Maximum

on-the-phone

6500

8900

in-a-conference

7000

8999

in-a-meeting

6500

8999

urgent-interruptions-only

6900

8999

out-of-office

12000

No maximum

Machine, calendar, and phone states

Office Communicator publishes machine states with a category instance ID whose first hexadecimal digit is 0x3, and the remaining 7 hexadecimal digits uniquely identify the device. Machine states are based on information from the device, and they contain information such as timeouts for idle and away, whether the machine is locked, and so on.

Office Communicator communicates with the Exchange server using MAPI or Exchange Web services and publishes calendar state instances when a user’s state changes due to meetings or other information that are set in Outlook. Office Communicator publishes a state category instance every 5 minutes if there is a change in meeting state or a change in the start time of back-to-back meetings. This category instance has a category instance ID with 0x4 for its first hexadecimal digit, and the remaining 7 digits are unique per calendar. The expiration time is set to the duration of the meeting. Office Communicator also publishes a state category instance at the start and finish of a meeting that has been labeled as Out of Office. This category instance has a category instance ID with 0x5 for its first hexadecimal digit, and the remaining 7 digits are unique per calendar. In addition, Office Communicator publishes a state category instance when the user has set or removed an Out of Office message for automatic e-mail replies. This category instance has a category instance ID with 0x6 for its first hexadecimal digit, and the remaining 7 digits are unique per calendar.

Office Communicator publishes phone state instances for Remote Call Control (RCC), Voice over IP (VOIP), Public Switched Telephone Network (PSTN), and Telephony Application Program Interface (TAPI). The following table shows the category instance ID for each of these phone states, where the first hexadecimal digit defines the phone type, and the last seven hexadecimal digits are chosen to be unique.

Phone States

Phone type Category ID first hexadecimal digit Category ID final 7 hexadecimal digits

RCC

0x7

Unique per telephone URI

VOIP

0x8

Unique per sip URI and device

PSTN

0x9

Unique per PSTN URI and device

TAPI

0xa

Unique per device

RCC and VOIP phone state instances are published when a call is connected or disconnected, or when the call participant count changes from 0 to 2, from 2 to more than 2, from more than 2 down to 2, and from 2 down to 0. PSTN phone state instances are published when a PSTN conference call is connected or disconnected. TAPI phone state instances are published when a mobile call is connected or disconnected.

Device

When a user signs in to Office Communicator, it publishes a device category instance with category name “device”, which specifies a collection of capabilities. These capabilities allow other client applications to determine what means are available for communication, such as text messaging, voice, or video. The category instance ID is unique to the device.

Available device capabilities can be found in the de:capabilities section of the Unified Communications Enhanced Presence Schemas for Microsoft Office Communications Server 2007. They include calendar, remote call control, voice, video, CCCP, text, gfInk, and isfInk. Publishing the device category instance lets subscribing applications know what the endpoint’s device is capable of doing.

The schema for the device category is described in the de:device section of the Unified Communications Enhanced Presence Schemas for Microsoft Office Communications Server 2007.

Contact Card

Contact card information is typically obtained from Active Directory and the options set in Office Communicator and then published by Office Communicator. The category name is “contactCard”. The following table indicates which information is contained in which category instance.

contactCard category instances

Category Instance Category Instance ID Description

Identity

0

Identity defined by Display Name and e-mail address

Options

1

Work phone, mobile phone, home phone, and other phone as set by Office Communicator options

User Properties

2

Work address and URL, as set by Active Directory

Address Book Server

3

Title, company, work phone, mobile phone, home phone, other phone, and office as set by Active Directory

In-band provisioning

4

Voicemail URI, and UC-enabled attribute

Both User Properties and Address Book Server data come from Active Directory. For User Properties, Office Communications Server obtains the data directly from Active Directory and provides it to Office Communicator as roaming data, which then publishes it. For Address Book Service data, Office Communicator accesses a local file called Address Book Service that contains stored contact card data previously obtained from Active Directory.

Note that when a user subscribes to a presentity’s presence, the user can receive multiple instances of the presentity’s contact card. One of these is published by Office Communications Server when the data is from Active Directory. Others are published by Office Communicator when the presentity signs in, and they can be from in-band provisioning, the Address Book Service file, or user input. The data from the different instances can conflict with each other. It is up to the client application to interpret and reconcile the conflicting data. Office Communicator does the reconciliation for some properties, but not all of them. Office Communicator Service does not do any reconciliation, except publishing the Office Communicator Server instance of the contact card if it is missing or accidentally overwritten by client publication.

Not all subscribers have access to all contactCard data. The following table displays which contactCard data Office Communicator publishes to which containers.

Data that is published in various containers by Office Communicator

Container Container ID Data

Public

100

The presentity’s work title and company, which is taken from Active Directory data.

Company

200

The presentity’s phone numbers for work, mobile, home, and other. The user has set these values through the Office Communicator options.

Team

300

The presentity’s work phone number and mobile phone number, as set through the Office Communicator options. The presentity’s work address and URL from the User Properties. The presentity’s work title, company, work phone number, mobile phone number, and office from Active Directory data.

Personal

400

The presentity’s work phone number and mobile phone number, as set through the Office Communicator options. The presentity’s work address and URL from the User Properties. The presentity’s work title, company, work phone number, mobile phone number, other phone number, and office from Active Directory data.

The schema for the contactCard category is described in the cc:contactCard section of the Unified Communications Enhanced Presence Schemas for Microsoft Office Communications Server 2007.

Calendar Data

Office Communicator publishes calendar data for presentities. Office Communicator typically connects to Microsoft Outlook through MAPI, but this can be supplemented or replaced by Office Communicator connecting to a Microsoft Exchange Server if the Exchange Server instance has a Web service for the calendar data.

The calendar data category name is “calendarData”. Calendar data includes information about the user’s working hours and when the user is free or busy. Office Communicator publishes working hours category instances with a category instance ID of 0, and it publishes free/busy data instances with a category instance ID whose first hexadecimal digit is 0x4, and the remaining 7 hexadecimal digits uniquely define the calendar.

Free/busy data is stored using a start time, a granularity, and a string that contains the data. The free/busy data starts at the start time and then contains a series of intervals of time, each one the length of the granularity, which is in minutes. For each interval of time, the free/busy state can be free, tentative, busy, or out of office. The freebusy property or attribute of the calendarData category instance is a string. To decode the string into the array of intervals with free/busy information, follow these steps:

How to Decode the free/busy String
  1. Convert the string into a byte array, using the Convert.FromBase64String method.

  2. Loop through the byte array. Separate each byte into four groups of two bits each.

  3. Each group of two bits represents an interval. Interpret the two bits as follows:

    • 00 = free
    • 01 = tentative
    • 10 = busy
    • 11 = out of office

The following C# method is for illustrative purposes only. It demonstrates how to convert the freeBusyData string into a string of characters where each interval is represented by the characters F, T, B, O, for free, tentative, busy, and out of office, respectively.

public string DecodeFreeBusy(string freeBusyData)
{
    // Codes for state
    int free = 0x00000000;
    int tent = 0x00000001;
    int busy = 0x00000002;
    int oof = 0x00000003;

    // Convert codes to bytes
    byte bFree = Convert.ToByte(free);
    byte bTent = Convert.ToByte(tent);
    byte bBusy = Convert.ToByte(busy);
    byte bOof = Convert.ToByte(oof);

    // Convert free/busy string to byte array
    byte[] bytes = Convert.FromBase64String(freeBusyData);

    string blocks = "";
    foreach (byte bb in bytes)
    {
        // If the byte is zero, then this block of four intervals 
        // is completely free
        if (bb == 0)
        {
            blocks += "FFFF";
        }
        else
        {
            // Compare each pair of bits to the free/busy codes
            byte b = bb;
            string byteBlocks = null;
            for (int i = 0; i < 4; i++)
            {
                if ((b & bOof) == bOof)
                    byteBlocks += "O";
                else if ((b & bBusy) == bBusy)
                    byteBlocks += "B";
                else if ((b & bTent) == bTent)
                    byteBlocks += "T";
                else if ((b & bFree) == bFree)
                    byteBlocks += "F";

                // Move b to the next pair of bits
                b = (byte)((short)b >> 2);
            }
            blocks += byteBlocks;
        }
    }
                
    return blocks;
}

The schema for the calendarData category is described in the cd:calendarData section of the Unified Communications Enhanced Presence Schemas for Microsoft Office Communications Server 2007.

When a user uses Office Communicator to add someone as a member to the Blocked container (sometimes referred to as the Block container), all Office Communicator information is blocked to that person except the display name. Office Communicator accomplishes this blocking by publishing blank calendar data and note category instances with blank data to the Blocked container and by publishing the availability as offline. Because the Blocked container has the highest ID (32000) of any container that Office Communicator uses, what Office Communicator publishes to this container is the information that anyone in the Blocked container sees. Other applications can publish category instances to the Blocked container or containers with container ID that is higher than the Blocked container and these are visible to the subscribers in the members of the Blocked container.

Show: