Contacts and Contact Groups
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.
Adding another Microsoft Office Communicator user to your contact list requires you to make two individual requests to the Communicator Web Access Server. Normally, you do not know the SIP URI of the user you want to add to your contact list. When this is the case, the two requests you make are search, and addContact. When the SIP URI of the user you want to add to the contact list is known, it is not necessary to make the searchrequest.
The search request has a corresponding and asynchronous searchResult event. If the searchResult event returns the requested user's SIP URI, you use that SIP URI value to add the user to the contact list by making an addContact request. In addition to the SIP URI, the searchResult returns the user presence information to which the searching user is allowed access.
Contacts
Creating a contact allows the logged-on user to create a permanent presence subscription for a user. Subscribing to user presence is not required however. Within the addContactrequest, the contact element contains an optional subscribed attribute. Setting this attribute to true creates a subscription to the user. A false value does not create a subscription. There is also an optional tag attribute. When the tag attribute is set to true, a reminder is created. The Unified Communications API client application can be coded to respond to this reminder when contact presence changes. For example, you may want to pop up a dialog when a tagged contact goes online.
Contacts can be added even though a contact group does not exist to hold the contact. If you create your first contact group after you have added contacts, you can update each of your contacts to add them to the new contact group. If a contact group exists at the time you are adding a contact, you can place the new contact in the contact group as you are adding the contact.
Contact List Size
An organization Office Communications Server sets the maximum number of contacts a single user can have in his contact list. The maximum value is set by an Office Communicator Server administrator. The default maximum number of contacts is 150. The value can be set as low as 150 and as high as 1000.
A single user can be subscribed to or "watched" by a maximum number of subscribers. This value is configured on an Office Communications Server by an administrator. By default, the maximum value is 200. It can be set as low as 10 or as high as 3000.
Contact Groups
Unified Communications gives you the ability to organize your list of subscribed users (contacts) into Contact Groups. Contact Groups help you organize your list of contacts into groupings of your own definition. By default, a user does not have any contacts or Contact Groups. They can be added and updated using different types of requests.
Adding a Contact
To add a contact, you send the addContact request. You must include the URI of the person you want to add. You can also choose a display name independent of the name that is part of the other user's Contact Card. If you want to see the Contact's presence whenever you log in, you need to set the subscribed and tag attributes to true. If you have an existing Contact Group and you want to add this new contact to that group, you must supply the groupID of the group.
Adding a Contact Group
To add a Contact Group, you send the addGroup request. The Id and name attributes of the group element are required.
Adding a Contact to a Contact Group
If you want to assign the contact to a Contact Group at the time you are adding the contact, you specify the group ID of the Contact Group in the contact element.
To assign existing contacts to Contact Groups, send the updateContactrequest. The contact element of the request must contain the groups attribute with a list of the group id's you want the contact assigned to.
Examples
John at Contoso.com wants to add Joe Healy to his contact list. Because John does not know Joe's e-mail address, he uses the firstName, lastName, and function elements of the search request to locate Joe. John is using the "and" function value because he only wants to return users who match both the first name and last name he specifies.
<search rid="24">
<firstName>Joe</firstName>
<lastName>Healy</lastName>
<function>and</function>
</search>
The Communicator Web Access Server returns the results of the search within a cwaEvents response. These search results provide the information needed to add Joe Healy to John's contact list.
<searchResults eid="134" rid="20" moreAvailable="true">
<user uri="sip:joeh@contoso.com"
sourceNetwork="sameEnterprise">
<cwaCategory name="contactCard" instance="0">
<contactCard xmlns="...contactcard">
<identity>
<name>
<displayName>Joe Healy</displayName>
</name>
</identity>
</contactCard>
</cwaCategory>
<cwaCategory name="contactCard" instance="3">
<contactCard xmlns="...contactcard">
<company>Contoso.com</company>
<title>Product Manager</title>
<office>Seattle</office>
</contactCard>
</cwaCategory>
<cwaCategory name="state" instance="0">
<state xsi:type="aggregateState"
xmlns:xsi="...XMLSchema-instance"
xmlns="...state">
<availability>3000</availability>
</state>
</cwaCategory>
</user>
</searchResults>
John adds Joe to his contact list and creates a permanent subscription to Joe's presence with the following request.
<addContact>
<contact> uri="sip:joeh@contoso.com" name="Joe Healy"
subscribed="true" tag="true" groups="1"
</contact>
</addContact>
John is using Joe's first and last name from the searchResult element above. He could have chosen to provide any name value he wanted to. The subscribed attribute was set to true so that John would continue to receive presence information for Joe whenever John is on-line. tag is set to true so that John can receive an event when Joe logs onto Unified Communications. John previously created a contactGroup, which he assigned the id 1. The request above adds Joe Healy to that contact group.
The logon-related event generated because the tag attribute is true, allows the programmer writing a custom Unified Communications client to create a custom event handler specifically for the log on event.