The Contact Service

The contact service is the IContactService interface defined in thecom.genesyslab.ail.ws.contact namespace. It handles the management of contacts.

Introduction

The following sub-sections present the contact service of Agent Interaction Service API.

What Is a Contact?

A contact is a customer with whom the agent may interact through a medium. Each contact has an ID which is a unique system reference used in the Genesys Framework. The Universal Contact Server (UCS) stores the contact data—that is, names, e-mail addresses, phone numbers, and other information.
This server also stores the history of a contact—that is, processed interactions. For further details, see The History Service.

What Is the Contact Service?

The contact service is an interface that lets your application access contacts’ data using the contacts’ IDs. Your application can create, retrieve, and modify a contact’s data set.
The contact service is independent from other services. To use the contact service, your application does not require specifics such as a logged in agent.
However, your application can use this service together with other services to fit agents’ needs. The contact is important information, used to deal with interactions and callback records. The interaction includes two participants, the agent and the contact.
The following scenarios illustrate uses of the contact service:

• The agent wants to see a contact’s phone numbers. Your application displays the list of phone numbers. The agent selects the contact’s mobile phone number and your application offers to launch a call.
  
• Your application receives an InteractionEvent for a ringing call.
  
• It uses the contact ID to display who is calling the agent.
  
• The contact is unknown: As soon as the agent answers the call, the application displays a wizard to collect the contact information.
  

Contact Information

The IContactService interface does not use specific DTO classes to deal with contacts. It uses a set of ContactXxx classes defined in the com.genesyslab.ail.ws.contact namespace.
The following subsections detail how the IContactService interface uses these classes.


Contacts’ Attributes

Most of the time, a contact is an instance of the ContactValue class of the com.genesyslab.ail.ws.contact namespace. The IContacService interface lets your application manage ContactValue objects containing the contacts’ information.
The ContactValue class has two attributes:


• contactId—The unique system reference for the contact.
  
• attributes—An array of ContactAttribute containing the contact’s attributes.
  

The contact service’s attributes are characteristic values of a contact. For example, an attribute may be the contact’s last name, first name, or a set of e-mail addresses.


Attribute Values

The following class diagram shows how the contact information is structured.
 



ContactValue Class Diagram

The ContactAttribute objects define the data of a contact. Each ContactAttribute contains the existing values for an attribute. The attribute values are available in the ContactAttribute.values field, which is an array of ContactAttributeValue . Each ContactAttributeValue object contains a single attribute value which has a unique system reference available in the ContactAttributeValue.id field.
For example, if a contact has one or several e-mail addresses, EmailAddress is considered an attribute. A single ContactAttribute contains its values—that is, all the contact’s e-mail addresses—and each ContactAttributeValue contains an e-mail address, as illustrated below.
 



Example of Contact Information

Important
Each contact attribute is associated with a metadata object. See MetaData in Other Contact Attribute Classes.

Primary Attributes

The primary attribute value of a contact is defined for a contact attribute. It is one of the attribute values marked as primary.
For example, if a contact has several e-mail addresses, the work e-mail address might be the primary e-mail attribute. In the above example, the primary attribute is underlined for each type of attribute.
To retrieve primary attributes, see Retrieving Contact Information.


Important
There is only one primary attribute value per attribute’s type.

MetaData

The Universal Contact Server defines a metadata for each type of attribute. For example, the last name is a type of contact attribute specified by a metadata. For the last name attribute, the metadata specifies that the attribute name is LastName, the type of the attribute value is a string, the display name is Last name, and so on.
A single metadata is available for each type of attribute; this metadata has a unique system identifier and a unique name. For example, a single metadata is available for all the existing last names’ attribute values. The metadata is independent from the contacts’ attribute values.
The Agent Interaction SDK (Web Services) lets your application access the metadata information with classes detailed in the following subsections.


ContactAttributeMetadata

Class

The ContactAttributeMetadata class defines the attribute metadata. The following are some of the main ContactAttributeMetaData fields:


• id—The unique system identifier for this metadata.
  
• name—The unique attribute name.
  
• active—true if the attribute is active in the Contact Server.
  
• displayName—The attribute display name.
  
• predefinedValues—A list of predefined contact attribute values, or null.
  
• searchable—true if the attribute is searchable. For example, a last name might be searchable, whereas a title, such as Mr. or Ms, might not be searchable.
  
• sortable—true if the attribute can be used to sort the contacts. For example, a last name might be sortable.
  
• type—The type of attribute defined by ContactAttributeMetaDataType. (See below).
  
Important
To retrieve attributes, the metadata identifier id is required.

Type

The ContactAttributeMetaDataType enumeration defines the type for the values specified by a metadata:


• ContactAttributeMetaDataType.BINARY—Type for binary contact attribute values.
  
• ContactAttributeMetaDataType.STRING—Type for string contact attribute values.
  
• ContactAttributeMetaDataType.DATE—Type for date contact attribute values.
  

MetaData in Other Contact Attribute Classes

Each ContactAttribute object associates an array of ContactAttributeValue values with a metadata:


• The ContactAttribute.attributeMetaDataId field is the ID of the available metadata for the set of attribute values.
  
• For each ContactAttributeValue, the name field points out the name of the metadata.
  

The example below presents a ContactAttributeMetaData related to a ContactAttribute and its array of ContactAttributeValue.
 



Example of ContactAttributeMetaData and ContactAttribute

Predefined MetaData

Some contact attributes are fixed and the associated metadata are predefined.
The ContactAttributeMetaDataPredefinedType enumerated type lists the existing predefined attributes handled by the contact service:


• TITLE—Fixed contact attribute for the title.
  
• FIRSTNAME—Fixed contact attribute for the first name.
  
• LASTNAME—Fixed contact attribute for last names.
  
• PHONE_NUMBER—Fixed contact attribute for phone numbers.
  
• EMAIL_ADDRESS—Fixed contact attribute for e-mail addresses.
  

The ContactAttributeMetaDataPredefined class associates a ContactAttributeMetaDataPredefinedType with a ContactAttributeMetaData object.
Use these objects to get fixed ContactAttributeMetadata without the name or the identifier of these metadata. See Getting Predefined MetaData.


Information Update

Thecom.genesyslab.ail.ws.contact.ContactUpdateType enumeration corresponds to the types of update that the contact service can perform on the information of several contacts at the same time.
For each contact to update, your application builds a ContactValue object. The content of the array of ContactValue is used to update the contacts’ information in the database according to the type of update. The following sub-sections detail these update types. For implementation, refer to Setting Attribute Values.


Attributes Update

When the agent using your application wants to fill in some contact information or add additional values for a contact attribute, your application can use the ContactUpdateType.UPDATE_ATTRIBUTE mode. For example, your application might add new e-mail addresses for a customer, as shown below.
 



Updating Contact Attribute Values

In Updating Contact Attribute Values, the application defines a ContactValue object for the contact John Connor. This ContactValue instance has an Email Address ContactAttribute containing two ContactAttributeValue s, which define new e-mail addresses. As a result of the update, the new addresses are added to the database. The other contact information has not been affected by the update, and the former e-mail addresses remain.


Overwrite Attributes

When the agent using your application wants to modify the existing values for a contact attribute, your application can use the ContactUpdateType.OVERWRITE_ATTRIBUTE mode. For example, if a contact’s e-mail addresses are obsolete, your application has to replace them with new e-mail addresses, as shown below.
 



Overwrite of some Contact Attributes

In Overwrite of some Contact Attributes, the application defines a ContactValue object for the contact John Connor. This ContactValue instance contains an EmailAddress ContactAttribute containing two ContactAttributeValue s which define the available e-mail addresses. As a result of the update, the available e-mail addresses replace the former e-mail addresses in the database. The other types of contact attributes have not been modified by the update. Only the specified ContactAttribute objects of the ContactValue.attributes array overwrite the contact attributes in the database.


Overwrite a Contact

When the agent using your application wants to change all the contact information, your application can use the ContactUpdateType.OVERWRITE_CONTACT mode. To properly overwrite the contact, define all the attributes that must remain after the update. The diagram below shows this type of overwrite with the same ContactValue than in previous figures (Updating Contact Attribute Values and Overwrite of some Contact Attributes).
 



Overwrite of all the Contact Information

In Overwrite of all the Contact Information, the application defines a ContactValue object for the contact John Connor. This ContactValue instance only contains an EmailAddress ContactAttribute containing two ContactAttributeValue s which define the available e-mail addresses. As a result of the update, the available e-mail addresses replace the former e-mail addresses in the database and the last name and first name information is removed (since no ContactAttribute object defines a new value for them).


Retrieving Contact Information

The IContactService interface uses several other container classes in methods calls to manage contacts. The following table summarizes the relationship between container classes and methods.
 

Contacts, Methods, and Containers of the IContactService

IContactService Methods	Container classes	Description
createContacts()	ContactAttributeCreate	This method uses the ContactAttribute of the container to create a new contact.
mergeContacts()	ContactMergeForm	This method merges the contact pairs of each container instance.
removeContactAttributes()	ContactAttributeRemove	This method removes only contact attribute values specified in the container.
searchContacts()	ContactSearchTemplate	This method uses the container to restrict the contact search.

Later sections of this chapter provide details about the operations listed above.


Retrieving Contact MetaData

Your application must retrieve the ContactAtributeMetaData objects of the required attributes. The IDs of these objects are necessary to retrieve the contact attribute information.
The following subsection provides you with two ways of getting metadata.


Getting Predefined MetaData

Predefined metadata are the metadata of the fixed attributes defined in the UCS. The IContactService.getContactAttributePredefinedMetaData() method lets your application retrieve all the existing ContactAttributePredefinedMetaData objects as shown in the following code snippet.


/// Retrieving the predefined metadata
ContactAttributePredefinedMetaData[] myPredefMetaData =
myContactService.getContactAttributePredefinedMetaData();
 
/// Displaying the name of each predefined metadata
foreach(ContactAttributePredefinedMetaData predef in myPredefMetaData)
{
   System.Console.WriteLine("Predefined Attribute: " + predef.predefinedType
   +"MetaData name: "
   + predef.metaData.name);
}

Important
Retrieving predefined metadata does not require any metadata name or identifier.

Getting MetaData

To retrieve the metadata, the IContactService interface offers the two following methods:


• getContactAttributeMetaDataByName() retrieves the metadata corresponding to the names specified in the array passed as parameter.
  
• getContactAttributeMetaDataById() retrieves the metadata corresponding to the IDs specified in an array passed as parameter.
  

Retrieving Contact Values

When your application needs to retrieve contact values, it must specify which attributes must be retrieved. Therefore, to retrieve contact values, the IContactService interface needs:


• The list of contact IDs involved in the information retrieval.
  
• The types of attributes to retrieve for each contact.
  

Setting a List of Attributes to Retrieve

First, create an array of ContactAttributeRetrieve objects. Each ContactAttributeRetrieve object sets:


• metaDataId—The ID of the metadata corresponding to a type of attribute to retrieve.
  
• primary—If true, only the primary values of this type of contact attribute are retrieved; otherwise, all the values of this attribute type are retrieved for each contact. For further information, see Primary Attributes.
  

 
ContactRetrieveAttribute[] toRetrieve = new ContactRetrieveAttribute[2];
 
/// For each contact, retrieve the last name of the contact
toRetrieve[0] = new ContactRetrieveAttribute();
toRetrieve[0].primary = true;
toRetrieve[0].attributeMetaDataId = myLastNameMetaData.id;
 
/// For each contact, retrieve all the e-mail addresses /// of the contact
toRetrieve[1] = new ContactRetrieveAttribute();
toRetrieve[1].primary = false;
toRetrieve[1].attributeMetaDataId = myEMailAddressMetaData.id;

Retrieving the Contacts’ Values

To retrieve the contacts values, use the previously defined array of ContactAttributeRetrieve objects to call the IContactService.getContacts() method, as shown in the following code snippet.


  
/// Retrieving attributes of myContactId
ContactValue[] myContacts = myContactService.getContacts( new string[]{myContactId}, toRetrieve);
 
/// Displaying the retrieved values
foreach(ContactValue myContactValue in myContacts)
{
   System.Console.WriteLine("**********");
   foreach(ContactAttribute myContactAtt in myContactValue.attributes)
   {
      /// Displaying the contact attribute values
      System.Console.WriteLine("Attribute Values: ");
      foreach(ContactAttributeValue myValue in myContactAtt.values)
      {
          System.Console.WriteLine(myValue.value.ToString()+" ");
      }
   }
}
 

Note that the above code snippet displays all the contents of the retrieved contacts’ values.


Searching Contacts

The contact service includes an advanced search feature for contacts. With the IContactService interface, your application can search contacts according to several attributes’ values and their associated metadata IDs.
The following sections detail how to build a contact filter tree—equivalent to a search request—and how to implement the contact service’s search feature.


Contact Filter Trees

Thecom.genesyslab.ail.ws.contact namespace contains classes and enumerations to build filter trees corresponding to search requests that approximate SQL requests to the UCS. Those filter trees are equivalent to arithmetic expressions.
Wildcards are autorized in leaves to facilitate the search:


• The * wildcard matches any string of zero or more characters,
  
• The \* sequence matches one character.
  

For example, ((LastName="B*" and FirstName="A*") or (EMailAddress="ab*@company.com")) searches for any contact whose first name begins with an A and whose last name begins with aB, or for any contact whose e-mail address begins with ab and finishes with @company.com.
To build a filter tree, your application must define filter nodes and filter leaves, as detailed in the following subsections.


Filter Leaves

A filter leaf contains a terminal expression that defines a search value for a contact attribute, such as: LastName="B*". Your application can create a filter leaf with an instance of the ContactFilterLeaf class, which associates a metadata ID with a contact attribute value. The ContactFilterLeaf class contains the following fields:


• attributeMetaDataId—the metadata ID of a contact attribute.
  
• operator—a ContactFilterLeafOperator value, which can be EQUAL or NOT_EQUAL.
  
• value—an attribute value.
  
• primary—boolean; if true, the leaf defines a search restricted to the primary values of a contact attribute.
  

The following code snippet implements a ContactFilterLeaf object for the LastName=”B*” expression:


  
ContactFilterLeaf myLeaf = new ContactFilterLeaf();
myLeaf.attributeMetaDataId = "my LastName Metadata ID";
myLeaf.@operator = ContactFilterLeafOperator.EQUAL;
myLeaf.value = "B*";
myLeaf.primaryOnly = true;

Filter Nodes

A filter node contains a non terminal expression that defines an operation for several non-terminal (node) or non terminal (leaf) expressions, as in the following examples:


• a or b or c
  
• a and b and c
  
• a or b
  
• a and b
  

In the preceding examples, a, b, and c can be other filter nodes or leaves, and the terms or and and are operators.
Your application can create a filter node by creating an instance of the ContactFilterNode class. This class contains the following files:


• operator—A ContactFilterNodeOperator value which can be AND or OR.
  
• leaves—An array of ContactFilterLeaf objects affected by the operator.
  
• nodes—An array of ContactFilterLeaf objects affected by the operator.
  

The following example presents a filter node containing the following expression:(LastName="B*" and FirstName=”A*”) or (EMailAddress="ab*@company.com")
 



An Example of Filter Node

Here is the corresponding code snippet:


 
/// The lower filter node defines: LastName="B*" AND FirstName="A*"
/// Creating a contact filter node
ContactFilterNode myLowerNode = new ContactFilterNode();
myLowerNode.@operator = ContactFilterNodeOperator.AND;
 
/// This node applies an AND operation to two leaves
myLowerNode.leaves = new ContactFilterLeaf[2];
 
/// Defining a leaf for LastName="B*"
myLowerNode.leaves[0] = new ContactFilterLeaf();
myLowerNode.leaves[0].attributeMetaDataId = "my Last Name Metadata ID";
myLowerNode.leaves[0].@operator = ContactFilterLeafOperator.EQUAL;
myLowerNode.leaves[0].value = "B*";
myLowerNode.leaves[0].primaryOnly = true;
 
/// Defining a leaf for FirstName="A*"
myLowerNode.leaves[1] = new ContactFilterLeaf();
myLowerNode.leaves[1].attributeMetaDataId = "my Fist Name Metadata ID";
myLowerNode.leaves[1].@operator = ContactFilterLeafOperator.EQUAL;
myLowerNode.leaves[1].value = "A*";
myLowerNode.leaves[1].primaryOnly = true;
 
/// The upper filter node defines:
/// myLowerNode OR (EMailAddress=”ab*@company.com”)
 
/// Creating a contact filter node
ContactFilterNode myUpperNode = new ContactFilterNode();
myUpperNode.@operator = ContactFilterNodeOperator.OR;
 
/// This node applies an OR operation to a node and a leaf
/// Adding myLowerNode to the nodes of myUpperNode
myUpperNode.nodes = new ContactFilterNode[1];
myUpperNode.nodes[0] = myLowerNode;
 
/// Defining a leaf for (EMailAddress="ab*@company.com")
myUpperNode.leaves = new ContactFilterLeaf[1];
myUpperNode.leaves[0] = new ContactFilterLeaf();
myUpperNode.leaves[0].attributeMetaDataId = "my EMail Address Metadata ID";
myUpperNode.leaves[0].@operator = ContactFilterLeafOperator.EQUAL;
myUpperNode.leaves[0].value = "ab*@company.com";
myUpperNode.leaves[0].primaryOnly = false;

Filter Root

A filter root is the entry point of a filter tree. Your application can define a filter tree with the ContactFilterRoot class, which contains the following fields:


• node—The root ContactFilterLeaf node of a tree.
  
• leaf—The root and single ContactFilterLeaf leaf of a tree.
  

Although the class has a node and a leaf field, your application must define the leaf or the node field, but not both. The following figure illustrates this, showing the two types of possible trees that a ContactFilterRoot instance defines.
 



Filter Roots

The left tree shows a filter root containing a filter node, and the right tree shows a filter root containing a filter leaf. Those two trees could not be merged into a single tree whose root would contains a filter node and a filter leaf.
The following code snippet shows how to create a ContactFilterRoot object for the left tree of Filter Roots diagram.


// Creating a contact filter root
ContactFilterRoot myFilterRoot = new ContactFilterRoot();
 
// Setting its node field with the upper node of the filter tree
myFilterRoot.node = myUpperNode;

Contact Search

To search a contact with the contact service, your application has to:


• Create a filter tree, as detailed in Contact Filter Trees.
  
• Fill in a contact search template.
  
• Call the searchContacts() method of the IContactService interface.
  

A contact search template delimits the contact search result associated with a filter tree. Your application can set the number of contacts to retrieve, and which attributes to retrieve, in the search call. This is useful for (as one example) displaying a contact search by pages, with a limited set of attributes.
To fill in a contact search template, your application must create an instance of the ContactSearchTemplate class, which defines the following fields:


• filter—A contact filter tree defining the search request.
  
• index—The index of the first ContactValue to retrieve in the list of matching ContactValue objects.
  
• length—The length of the list of ContactValue objects returned by the searchContact() method call.
  
• retrieveAttributes—The array of contact attributes to retrieve. For further information, see Setting a List of Attributes to Retrieve.
  
• sortAttributes—The array of contact attributes to sort.
  

The call to the IContactService.searchContacts() method returns an array of ContactValue objects matching the specifications of the search template that was passed as a parameter.
The following code snippet implements a simple search for the contact filter root example on Filter Roots.


 
/// Defining a contact search template
ContactSearchTemplate mySearchTemplate= new ContactSearchTemplate();
mySearchTemplate.filter = myFilterRoot;
 
// search of the ten first results
mySearchTemplate.index=0;
mySearchTemplate.length=10;
 
//Request a search for this template
ContactValue[] myFoundContacts = myContactService.searchContacts(mySearchTemplate);

Tuning the Contact Search

The definition of this ContactSearchTemplate form is very important because it determines the processing times of your search requests. There are several aspects to take into account to fit your application needs and fine-tune your search requests.


Number of Attributes

The number of attributes used in the filter tree to refine your search impacts the request’s processing time. The more attributes you set up, the finer your search is, but the longer the request takes.
Additionally, if you set up a wide search with few attributes or vague values, that returns a large collection of instances. This increases the processing time as well, because it impacts the network activity. The problem is similar if you set up a great number of attributes to be returned with each matching instance: the more instances that match, the more data will slow down the network activity.


is-searchable

Genesys recommends that your application uses attributes marked as is-searchable. This ensures calls to the appropriate UCS search algorithms, and gets responses with good performance.
To set up is-searchable attributes, open the targeted Attribute Value object in the Contact Attributes list of your Configuration Manager. In the Annex tab of the attribute object, open settings and set to true the is-searchable option.
In the Agent Interaction Services API, call theisSearchable() method of the ContactAttributeMetadata instance to determine whether the associated attribute values are searchable.
If your application searches for any attributes, regardless of whether they are marked as searchable, this will be time-consuming, and will slow down your application. In particular, if your application is a server, this is inappropriate, and detracts from good performances.


SearchPrimaryValueOnly flag

If you set the primaryOnly flag to true by calling the FilterLeaf.setPrimaryOnly() method, you restrict the search to the attributes’ primary values. The more you search for primary values, the less the SQL request is being complex, and thus, UCS requires less time to return a result.
Also, for the quickest search, set the SearchPrimaryValueOnly flag to true by calling the SearchContactTemplate.setSearchPrimaryValueOnly() method. The search is restricted to attributes’ primary values, regardless of the definition of FilterLeaf objects (which are part of the filter tree).


Managing Contacts

The IContactService includes features to manage a set of contact data. The following sections detail the most commonly used features.


Creating a Contact

The IContactService provides you with the createContact() method. For each contact to create, fill a ContactAttributeCreate object with ContactAttribute objects (containing, for each type of attribute, the set of corresponding values).


  
/// Creating a contactAttributeCreate for john connor
ContactAttributeCreate myNewContact = new ContactAttributeCreate();
/// The contact is created with 2 attributes only:
/// last name + e-mail addresses
myNewContact.attributes = new ContactAttribute[2];
 
/// Filling the contact attribute for lastname
myNewContact.attributes[0]=new ContactAttribute();
myNewContact.attributes[0].attributeMetaDataId = myLastNameMetaData.id;
// Creating a single attribute value for the last name
myNewContact.attributes[0].values = new ContactAttributeValue[1];
myNewContact.attributes[0].values[0] = new ContactAttributeValue();
myNewContact.attributes[0].values[0].value = "Connor";
myNewContact.attributes[0].values[0].primary = true;
 
/// Filling the contact attribute for the e-mail addresses
myNewContact.attributes[1]=new ContactAttribute();
myNewContact.attributes[1].attributeMetaDataId = myEMailAddressMetaData.id;
/// Creating two attribute values for the e-mail
myNewContact.attributes[1].values = new ContactAttributeValue[2];
// Creating the attribute value for the primary e-mail address
myNewContact.attributes[1].values[0] = new ContactAttributeValue();
myNewContact.attributes[1].values[0].value = "John.Connor@company.com";
myNewContact.attributes[1].values[0].primary = true;
// Creating the attribute value for another e-mail address
myNewContact.attributes[1].values[1] = new ContactAttributeValue();
myNewContact.attributes[1].values[1].value = "jconnor@home.com";
myNewContact.attributes[1].values[1].primary = false;
 

The createContact() method returns an array of ContactResult objects as shown in the following code snippet.


  
ContactResult[] myResults = myContactService.createContacts( new ContactAttributeCreate[]{myNewContact}, true);

The ContactResult class contains the result of a contact creation:


• contactId—The unique system identifier created for the new contact; null if not created.
  
• contactError—The string for the contact error if an error occurred during the contact creation; otherwise null.
  
• attributes—The ContactAttribute array of successfully created attributes; all the ContactAttributeValue.id fields have been created.
  
• attributesErrors—The array of AttributeErrors containing the metadata IDs, and the corresponding error for each attribute not created.
  

The following code snippet displays the returned ContactResult array:


  
/// Displaying the ContactResult array returned /// in the previous code snippet
foreach (ContactResult myContactResult in myResults)
{
    // the contact has not been created
    if(myContactResult.contactError != null)
    {
       System.Console.WriteLine("Error at contact creation: " + myContactResult.contactError);
    }
    /// The contact is created
    else
    {
       // Displaying the retrieved contact id
       System.Console.WriteLine("Contact successfully created: " + myContactResult.contactId);
       // Displaying the created attributes
       System.Console.WriteLine("* Attributes successfully created: ");
       foreach( ContactAttribute attribute in myContactResult.attributes )
       {
          if(attribute.attributeMetaDataId == myLastNameMetaDataId)
              System.Console.WriteLine(" Last name");
          else if(attribute.attributeMetaDataId == myEMailMetaDataId)
              System.Console.WriteLine(" E-Mail Address");
       }
       // Displaying which attributes were not created
       System.Console.WriteLine("* Attributes with error at creation: ");
       foreach( AttributeError myError in myContactResult.attributeErrors )
       {
           if(myError.attribute == myLastNameMetaDataId)
             System.Console.WriteLine(" Last name: "+myError.error);
           else if(myError.attribute == myEMailMetaDataId)
             System.Console.WriteLine(" E-Mail Address:" +myError.error);
       }
   }
}

Merging Contacts

If an agent finds out that two contacts are the same person, he or she might want to merge those contacts to avoid information duplication.
The IContactService interface offers a mergeContact() method that merges two contacts. The contacts’ identifiers are passed as parameters: the information of the from contact is copied to the To contact. The from contact identifier disappears, and the remaining contact identifier is the To ID.
Your application can merge several pairs of contacts in a single call to the IContactService.mergeContact() method. For each pair of contacts to merge, your application fills in a ContactMergeForm that contains the two contacts’ identifiers.
The following code snippet merges two contacts.


/// Creating an array of merge form
ContactMergeForm[] myMergeForms= new ContactMergeForm[1];
 
/// Filling a form of the array
myMergeForms[0] = new ContactMergeForm();
myMergeForms[0].contactIdFrom=myContactIdFrom;
myMergeForms[0].contactIdTo=myContactIdTo;
 
/// Merging each contact pair of the forms
myContactService.mergeContacts(myMergeForms);

Setting Attribute Values

The following table summarizes the three ways of updating contact attributes with the contact service. See also Information Update.
 

Updating Contacts

ContactUpdateType	Description
UPDATE_ATTRIBUTE	Adds new values to contacts attributes
OVERWRITE_ATTRIBUTE	Overwrites the attribute values of a contact with new attribute values.
OVERWRITE_CONTACT	Overwrites all the contacts attribute.

Your application can set attribute values only for a contact that exists in the UCS. Therefore, your application needs a contact’s identifier in order to modify that contact’s attributes.
For each contact to update, whatever the type of update, your application must:
Create a ContactValue object.

1. Set the ContactValue.contactId field with the contact’s identifier.
   
2. Create an array of ContactAttribute objects, and for each ContactAttribute object:
   
   • Set the corresponding ContactAttributeMetaData identifier.
     
   • Fill in the ContactAttribute.values array with ContactAttributeValues containing the new contact attribute values to input.
     

The following code snippet illustrates these steps.

 
// Creating a ContactValue array having 1 ContactValue
ContactValue[] datas = new ContactValue[1];
// Creating a ContactValue object for myContact
datas[0]=new ContactValue();
datas[0].contactId = myContactId;
 
// The update consists in adding an email address to the contact
// Creating a Single ContactAttribute
datas[0].attributes = new ContactAttribute[1];
datas[0].attributes[0] = new ContactAttribute();
 
//Setting the metadata id of the email metadata
datas[0].attributes[0].attributeMetaDataId = myEMailMetaData.id;
 
//Creating
datas[0].attributes[0].values = new ContactAttributeValue[1];
datas[0].attributes[0].values[0] = new ContactAttributeValue();
datas[0].attributes[0].values[0].value = "contact@new.email.com";
datas[0].attributes[0].values[0].primary = false;
 
myContactService.setContactAttributes(datas, ContactUpdateType.UPDATE_ATTRIBUTE, false);

Removing Attribute Values

The IContactService.removeContactAttributes() method uses the ContactAttributeRemove and ContactAttributeValueRemove container classes.
Each ContactAttributeRemove object contains:

• The ID of the contact involved in the removal of some attribute values.
  
• An array of ContactAttributeValueRemove objects; eachContactAttributeValueRemove object contains:
  • The ID of an attribute value to remove.
    
  • The ID of the corresponding attribute metadata.
    

The following code snippet shows an example of a call to the removeContactAttributes() method.

 
///Creating a ContactAttributeRemove object
ContactAttributeRemove toRemove = new ContactAttributeRemove();
 
// Setting the id of the contact
toRemove.contactId = myContactId;
toRemove.attributes = new ContactAttributeValueRemove[1];
 
// Creating a ContactAttributeValueRemove object to // remove an e-mail address of the contact
toRemove.attributes[0] = new ContactAttributeValueRemove();
 
// Setting the metadata id for the e-mail address
toRemove.attributes[0].attributeMetaDataId = myEMailMetaDataId;
 
// Setting the ID of the e-mail address to remove
toRemove.attributes[0].attributeValueIds = new string[]{ emailValueIdToRemove };
 
// Calling the remove method of the contact service.
myContactService.removeContactAttributes( new ContactAttributeRemove[]{toRemove});