People and contacts in EWS in Exchange
Learn about personas, the Unified Contact Store, and how to work with contacts by using the EWS Managed API or EWS in Exchange.
Contacts are items in Exchange that store information about an individual, group, or organization. Contacts can include names and email addresses, and other information, including IM addresses, physical addresses, birthdays, family information, and a photo or image that represents the contact.
Contact information is stored in one of two places:
Active Directory Domain Services (AD DS), if the contact is within the organization.
The Contacts folder or another folder in a user's mailbox, if the contact is outside the organization.
Multiple contact items can represent a single individual. Exchange uses personas to help bring these different contact items together. A persona is an aggregation of contact information for the same individual from different sources. In addition to contact information in Exchange, personas can also be aggregated from information in the recipient cache for the mailbox, a hidden folder for IM contacts called QuickContacts, and from third-party data sources. The Unified Contact Store in Exchange enables IM clients to use this aggregation; the only difference is that the Unified Contact Store does not aggregate information from AD DS, as shown in Figure 1.
Figure 1. Contact information sources for personas and for the Unified Contact Store
Table 1. EWS Managed API methods and EWS operations for working with contacts
| If you want to… | Use this EWS Managed API method | Use this EWS operation |
|---|---|---|
| Create a new contact |
Instantiate a new Contact object, and use Contact.Save |
CreateItem |
| Copy a contact |
Contact.Copy |
CopyItem |
| Move a contact |
Contact.Move |
MoveItem |
| Update an existing contact |
Contact.Bind and Contact.Update |
UpdateItem |
| Delete a contact |
Contact.Bind and Contact.Delete |
DeleteItem |
| Search for a contact |
ExchangeService.FindItems |
FindItem |
| Search for people |
N/A |
FindPeople |
| Expand a distribution group |
ExchangeService.ExpandGroup |
ExpandDL |
| Resolve an ambiguous name |
ExchangeService.ResolveName |
ResolveNames |
| Get a persona |
N/A |
GetPersona |
| Work with contact photos |
Contact.SetContactPicture, Contact.GetContactPictureAttachment, or Contact.RemoveContactPicture |
GetUserPhoto or GetAttachment |
Personas
Until recently, contacts were commonly stored in a single location — typically, on an email client. Today, it is becoming more common to store contacts in many different locations, such as on a phone, on a social networking site, in a Contacts folder in an Exchange mailbox, or in an organization's directory service. With the proliferation of contact information, it's possible that multiple contacts that represent the same person contain different information; for example, one contact might include a business phone number and another a personal phone number, or a contact stored in a Contacts folder might have a different name than the contact for the same person that is stored on your phone.
In Exchange Online, Exchange Online as part of Office 365, and on-premises versions of Exchange starting with Exchange 2013, contacts from different sources that represent the same person are associated with one another, similar to the way that email messages are aggregated into conversations, by means of a common link ID. When aggregated contact information is returned by an Exchange server, it includes a set of attributes for each contact, such as a source folder, a display name, an ID, and a source ID. The sum of the properties and attributes returned is known as a persona, and the set of properties returned is referred to as the persona's shape.
Because the information that makes up a persona is not stored in a single location, and because that information can change at any time, a persona is created only when you make a request to an Exchange server. You use the FindPeople EWS operation to make a persona search request. Your request can include a sort order, and can be filtered according to a query string to help you find the correct persona by ordering and filtering the results. For example, you can retrieve the display name and a set of all email addresses that are associated with a specific contact from the Contacts folder, a Hotmail account, a LinkedIn account, and a company's directory service, or you can retrieve a set of all personas that have IM addresses. The linking of contacts into personas is automatic based on an algorithm that recognizes a relationship between contacts stored on various devices.
Note
The EWS Managed API does not implement this functionality.
Table 2. EWS operations for working with personas
| Operation name | Description |
|---|---|
| FindPeople |
Returns all available personas from a specified contacts folder or retrieves contacts that match a specified query string. |
| GetPersona |
Returns a set of properties associated with a specific persona, such as all the IM addresses or display names for a specified persona ID. |
You can use the GetPersona and FindPeople operations to efficiently retrieve contact information from multiple sources. Because all items related to a persona are associated with a link ID, you can use these operations in a wide variety of applications that use contact data. The following are some examples:
A mobile phone app that uses the GetPersona operation when a user calls a contact, and then offers additional phone numbers to call if no one answers.
An application that uses the FindPeople operation to scan Inbox messages for email addresses to determine whether they are found in an existing persona. Addresses that are not already associated with a persona can be used to create sales leads or list all recent communications with the person represented by that persona.
A mail app for Outlook that offers different salutations based on whether correspondence is formal or informal. Formal salutations are supplied by the display names from the directory service and informal salutations come from the display name that originates in social network contacts.
Unified Contact Store
Personas aren't just limited to an email client. If you're developing an IM client, you might ask yourself any or all of the following:
How can I provision Lync client applications with a default set of IM contact items?
How do I manage IM contact and group lists?
How do I manage custom Lync client access to IM contacts and IM groups?
The Unified Contact Store works behind the scenes in Exchange to aggregate contact data from Exchange and other sources into a single entity, or persona. Although the EWS operations that you use to access the Unified Contact Store are specific to IM contacts, You can use the Unified Contact Store in Exchange to work with personas in all types of applications. Keep in mind that the Unified Contact Store cannot access contact data AD DS.
IM contacts are stored in a hidden folder called QuickContacts. You can use the AddNewImContactToGroup and AddImContactToGroup operations to add contacts to groups that are stored in this hidden folder. And because you can use the Unified Contact Store to group IM contacts, you can access and update groups of contacts more easily.
Note
The EWS Managed API does not implement this functionality.
Table 3. EWS operations for accessing the Unified Contact Store
| Operation name | Description |
|---|---|
| AddNewImContactToGroup |
Adds a new IM contact to an IM group, up to a maximum of 1000 contacts. |
| AddImContactToGroup |
Adds an existing IM contact to an IM group, up to a maximum of 1000 contacts. |
| AddImGroup |
Adds a new IM group, up to a maximum of 64 groups. |
| AddDistributionGroupToImList |
Adds a new distribution group to an IM group, up to a maximum of 64 groups. |
| GetImItemList |
Retrieves a list of IM groups and IM contact personas. |
| GetImItems |
Retrieves information about specific IM groups and IM contact personas. |
| RemoveContactFromImList |
Removes a contact from an IM group. |
| RemoveImContactFromGroup |
Removes an IM contact from an IM group. |
| RemoveDistributionGroupFromImList |
Removes a distribution group from an IM group. |
| RemoveImGroup |
Removes an IM group. |
| SetImGroup |
Changes the display name of an IM group. |