com.genesyslab.ail
Interface Contact

All Superinterfaces:
IdObject

public interface Contact
extends IdObject

Contact contains information and methods for handling customer data. A Contact object is a container. AIL does not keep contact objects in its cache. Each object reference is unique. AIL client applications do not deal with the same reference even though they use the same contact ID (ContactServerID) to retrieve their contact reference by calling a ContactManager.getContact() method.

Contact instances that handle the same contact ID, may not store the same contact attribute values according to the ContactManager.getContact() method called.
For instance, if you call the ContactManager.getContact(id) method, the returned contact has no attribute values. If you call the ContactManager.getContact(ID, collection) method, the returned instance contains the attribute values specified in the collection parameter.

You can access contact attributes in two ways:

Note: If the ServiceStatus.Type.DATABASE service is not available (UCS is not connected), you cannot get features associated with UCS, including interfaces for contacts.


Nested Class Summary
 
Nested classes/interfaces inherited from interface com.genesyslab.ail.IdObject
IdObject.ObjectType
 
Method Summary
 void addEmailAddress(java.lang.String email_address, java.lang.String description)
          Adds an address to this Contact's e-mail addresses.
 void addPhoneNumber(java.lang.String phone_number, java.lang.String description)
          Adds a phone number to this Contact's phone numbers.
 void delete()
          Deletes this Contact from the database.
 java.util.Map getAllEmailAddresses()
          Returns all the e-mail addresses of this Contact as a Map of (String address, String description).
 java.util.Map getAllPhoneNumbers()
          Returns all the phone numbers of this Contact as a Map of (String phone number, String description).
 ContactAttributeValue getAttributeValue(java.lang.String contactAttributeId)
          Returns one attribute value for this ID (ContactServerID).
 java.util.Collection getAttributeValues(ContactAttributeMetaData attributeName, boolean primaryOnly)
          Returns all the attribute values for this attributeName.
 java.lang.String getFirstName()
          Returns the first name of this contact.
 java.lang.String getId()
          Returns the unique ID of this object.
 java.lang.String getLastName()
          Returns the last name of this contact.
 MergeContactDetail getMergeDetail()
          Returns the details for the last merge action performed on this Contact.
 java.lang.String getObjectType()
          Returns the type of this object.
 java.lang.String getPrimaryEmailAddress()
          Returns the main e-mail address of this contact.
 java.lang.String getPrimaryPhoneNumber()
          Returns the main phone number of this contact.
 java.lang.String getTitle()
          Returns the title (Mr, Mrs...) of this contact .
 boolean isUndoAvailable()
          Indicates if the undoMerge() method can be called for this Contact.
 void merge(java.lang.String from)
          Merges all the history from the specified contact into this Contact.
 void merge(java.lang.String sourceContactId, java.lang.String user_name, java.lang.String reason, java.lang.String description)
          Merges all the history of the source Contact into this Contact.
 void removeAttributeValues(ContactAttributeMetaData attributeName, java.util.Collection values)
          Removes contact attribute values for a ContactAttributeMetaData.
 void removeEmailAddress(java.lang.String emailAddress)
          Removes an e-mail address from this Contact's e-mail addresses.
 void removePhoneNumber(java.lang.String phone_number)
          Removes a number from this Contact's phone numbers.
 void save()
          Saves the object into the database.
 java.util.Collection setAttributeValues(ContactAttributeMetaData attributeName, java.util.Collection values)
          Adds or updates contact attribute values of this attribute name.
 void setFirstName(java.lang.String firstName)
          Sets the first name of this Contact.
 void setLastName(java.lang.String lastName)
          Sets the last name of this Contact.
 void setPrimaryEmailAddress(java.lang.String email_address)
          Sets this e-mail address as primary.
 void setPrimaryPhoneNumber(java.lang.String phone_number)
          Sets this phone number as primary.
 void setTitle(java.lang.String title)
          Sets the title of this Contact.
 void undoMerge()
          Undoes the last merge action performed on this Contact.
 

Method Detail

getId

java.lang.String getId()
Returns the unique ID of this object. This ID can be used in the methods of AilFactory.

Specified by:
getId in interface IdObject
Returns:
an ID as String.

getObjectType

java.lang.String getObjectType()
Returns the type of this object. Uses the constants defined in IdObject.ObjectType.

Specified by:
getObjectType in interface IdObject
Returns:
type of object as String.

getTitle

java.lang.String getTitle()
Returns the title (Mr, Mrs...) of this contact .

Returns:
a title as String

getFirstName

java.lang.String getFirstName()
Returns the first name of this contact.

Returns:
the firstname as String

getLastName

java.lang.String getLastName()
Returns the last name of this contact.

Returns:
the lastname as String

getPrimaryEmailAddress

java.lang.String getPrimaryEmailAddress()
Returns the main e-mail address of this contact.

Returns:
the primary e-mail address as String

getPrimaryPhoneNumber

java.lang.String getPrimaryPhoneNumber()
Returns the main phone number of this contact.

Returns:
the primary phone number as String.

getAllEmailAddresses

java.util.Map getAllEmailAddresses()
                                   throws RequestFailedException
Returns all the e-mail addresses of this Contact as a Map of (String address, String description).

Returns:
a Map of e-mail address as key and description as value.
Throws:
RequestFailedException - if the service cannot fulfill the request.

getAllPhoneNumbers

java.util.Map getAllPhoneNumbers()
                                 throws RequestFailedException
Returns all the phone numbers of this Contact as a Map of (String phone number, String description).

Returns:
a Map of phone number as key and description as value.
Throws:
RequestFailedException - if the service cannot fulfill the request.

merge

void merge(java.lang.String from)
           throws RequestFailedException
Merges all the history from the specified contact into this Contact. You do not need to call save() to apply this modification.

The 'from' contact attributes are not deleted, all its contact attribute values are assigned to the 'to' contact with primary status set to false (if needed).

Parameters:
from - the ID of the contact, the interactions of which must be merged into the history of this contact.
Throws:
InvalidParameterException - if the parameter is null or invalid.
DatabaseServiceException - if the database service is out of order.
RequestFailedException - if the service cannot fulfill the request.

delete

void delete()
            throws RequestFailedException
Deletes this Contact from the database. Do not call save() to apply this modification. If you call save() on a deleted object, it will be added back into the database.

Throws:
DatabaseServiceException - if the database service is out of order.
RequestFailedException - if the service cannot fulfill the request.

setFirstName

void setFirstName(java.lang.String firstName)
                  throws RequestFailedException
Sets the first name of this Contact. Call save() to apply this modification.
For example,
Contact myContact = ...;
myContact.setFirstName("Name");
myContact.save();

Parameters:
firstName - first name as a String.
Throws:
RequestFailedException - if the service cannot fulfill the request.

setLastName

void setLastName(java.lang.String lastName)
                 throws RequestFailedException
Sets the last name of this Contact. Call save() to apply this modification.

Parameters:
lastName - last name as a String.
Throws:
RequestFailedException - if the service cannot fulfill the request.

setTitle

void setTitle(java.lang.String title)
              throws RequestFailedException
Sets the title of this Contact. Call save() to apply this modification.

Parameters:
title - title as a String.
Throws:
RequestFailedException - if the service cannot fulfill the request.

addEmailAddress

void addEmailAddress(java.lang.String email_address,
                     java.lang.String description)
                     throws RequestFailedException
Adds an address to this Contact's e-mail addresses. Call save() to apply this modification.

Parameters:
email_address - the e-mail address to add.
description - a String comment for this address.
Throws:
RequestFailedException - if the service cannot fulfill the request.

setPrimaryEmailAddress

void setPrimaryEmailAddress(java.lang.String email_address)
                            throws RequestFailedException
Sets this e-mail address as primary. Call save() to apply this modification.

Parameters:
email_address - the e-mail address to set primary.
Throws:
RequestFailedException - if the service cannot fulfill the request.

removeEmailAddress

void removeEmailAddress(java.lang.String emailAddress)
                        throws RequestFailedException
Removes an e-mail address from this Contact's e-mail addresses. Call save() to apply this modification.

Parameters:
emailAddress - the e-mail address to remove.
Throws:
RequestFailedException - if the service cannot fulfill the request.

addPhoneNumber

void addPhoneNumber(java.lang.String phone_number,
                    java.lang.String description)
                    throws RequestFailedException
Adds a phone number to this Contact's phone numbers. Call save() to apply this modification. Phone numbers are compared on a digit basis.

Parameters:
phone_number - the phone number to add.
description - a String commenting this phone number.
Throws:
RequestFailedException - if the service cannot fulfill the request.

setPrimaryPhoneNumber

void setPrimaryPhoneNumber(java.lang.String phone_number)
                           throws RequestFailedException
Sets this phone number as primary. Call save() to apply this modification.

Parameters:
phone_number - the phone number to set primary.
Throws:
RequestFailedException - if the service cannot fulfill the request.

removePhoneNumber

void removePhoneNumber(java.lang.String phone_number)
                       throws RequestFailedException
Removes a number from this Contact's phone numbers. Call save() to apply this modification.

Parameters:
phone_number - the phone number to remove.
Throws:
RequestFailedException - if the service cannot fulfill the request.

setAttributeValues

java.util.Collection setAttributeValues(ContactAttributeMetaData attributeName,
                                        java.util.Collection values)
                                        throws RequestFailedException
Adds or updates contact attribute values of this attribute name. Call save() to apply this modification. If all contact attribute values of the contact are loaded, then when a ContactAttributeValue is added, updated, the primary status of all ContactAttributeValues for this ContactAttributeMetaData are checked. Only one primary value is allowed for a ContactAttributeMetaData.

Parameters:
attributeName - one instance of ContactAttributeMetaData
values - a Collection of ContactAttributeValue instances, if attributeId is null then the value is added, otherwise an update of the given attribute value is done (this parameter cannot be null).
Returns:
Collection of ContactAttributeValue instances with the updated attributeId value (if needed).
Throws:
RequestFailedException - if the service cannot fulfill the request.
Since:
G7.0

removeAttributeValues

void removeAttributeValues(ContactAttributeMetaData attributeName,
                           java.util.Collection values)
                           throws RequestFailedException
Removes contact attribute values for a ContactAttributeMetaData. Call save() to apply this modification.

Parameters:
attributeName - one instance of ContactAttributeMetaData.
values - a Collection of ContactAttributeValue instances (this parameter cannot be null).
Throws:
RequestFailedException - if the service cannot fulfill the request.
Since:
G7.0

getAttributeValues

java.util.Collection getAttributeValues(ContactAttributeMetaData attributeName,
                                        boolean primaryOnly)
                                        throws RequestFailedException
Returns all the attribute values for this attributeName.

Parameters:
attributeName - one instance of ContactAttributeMetaData.
primaryOnly - primary attributes only.
Returns:
Collection of ContactAttributeValue instances.
Throws:
RequestFailedException - if the service cannot fulfill the request.
Since:
G7.0

getAttributeValue

ContactAttributeValue getAttributeValue(java.lang.String contactAttributeId)
                                        throws RequestFailedException
Returns one attribute value for this ID (ContactServerID).

Parameters:
contactAttributeId - the ContactServerID of ContactAttributeValue.
Returns:
one ContactAttributeValue instance; null if ID is not in this contact object or does not exist.
Throws:
RequestFailedException - if the service cannot fulfill the request.
Since:
G7.0

save

void save()
          throws RequestFailedException
Saves the object into the database.

Throws:
InvalidParameterException - if the contact does not exist.
DatabaseServiceException - if the database service is out of order.
RequestFailedException - if the service cannot fulfill the request.

getMergeDetail

MergeContactDetail getMergeDetail()
                                  throws RequestFailedException
Returns the details for the last merge action performed on this Contact.

Returns:
a MergeContactDetail instance that contains source and destination information about the last merge performed on this contact.
Throws:
InvalidParameterException - if the parameter is null or invalid.
DatabaseServiceException - if the database service is out of order.
RequestFailedException - if the service cannot fulfill the request.
Since:
7.5

merge

void merge(java.lang.String sourceContactId,
           java.lang.String user_name,
           java.lang.String reason,
           java.lang.String description)
           throws RequestFailedException
Merges all the history of the source Contact into this Contact.
Note: You do not need to call save() to apply this modification.

Parameters:
sourceContactId - a String value (mandatory),
user_name - agent user name as a String value (optional),
reason - as String value (optional),
description - as String value (optional).
Throws:
InvalidParameterException - if the parameter is null or invalid.
DatabaseServiceException - if the database service is out of order.
RequestFailedException - if the service cannot fulfill the request.
Since:
7.5

undoMerge

void undoMerge()
               throws RequestFailedException
Undoes the last merge action performed on this Contact.

Throws:
InvalidParameterException - if the parameter is null or invalid.
DatabaseServiceException - if the database service is out of order.
RequestFailedException - if the service cannot fulfill the request.
Since:
7.5

isUndoAvailable

boolean isUndoAvailable()
                        throws RequestFailedException
Indicates if the undoMerge() method can be called for this Contact.

Returns:
true if undoMerge capacity is available.
Throws:
RequestFailedException
Since:
7.5