Jump to: navigation, search

Additional Services

This chapter presents services that provide additional information to complement other services, or to assist you in monitoring your application. For instance, the history service complements the contact service because it provides contacts’ histories. The workflow service enables an agent to use workbins to put or pull interactions. The system service determines whether or not your application is correctly connected to the servers that provide interactions, contacts, and other resources.

The History Service

The Universal Contact Server (UCS) stores contacts’ data, including the contact history. The history service gives access to a set of contact histories managed by the UCS. For each contact, its history contains a set of interactions involving the contact. Within the history service, your application can retrieve data about those interactions.
The history service is the IHistoryService interface defined in the com.genesyslab.ail.ws.history namespace. To use this service, your application works with classes and enumerations of this namespace.

History Information

A Contact’s history information consists of interactions and is organized into history items. Each history item contains the history information of one interaction associated with a contact.
The history domain of the IHistoryService interface lists the accessible data of a history item:

  • history:interactionId—ID of the interaction involved.
  • history:dateCreated—Creation date of the interaction.
  • history:interactionType—Type of the interaction.
  • history:sender—Initiator of the interaction.
    If this is an incoming interaction, the name of the customer
    If this is an outgoing interaction, the name of the agent who has processed this interaction.
  • history:subject—Subject of the interaction.


This list is not exhaustive. For a full and exhaustive description of each UCS interaction data, refer to the UCS multimedia data model document.

Your application can retrieve a history item in a HistoryItemDTO instance. The HistoryItemDTO class associates a contact with the key-value array data that contains history attribute keys and values describing an interaction of within the contact history. For further details, see Getting History Information.
Thehistory.additional domain provides a set of additional interaction attributes. These attributes are dynamic and depend on the Configuration Layer. To get the attribute keys of this domain, retrieve the metadata name of these attributes with the IResourceService methods. For further details, see Interaction Attributes.
Your application can use metadata names as attribute keys when retrieving history DTOs, as, in this example: history.additional:<metadata.name> (where <metadata.name> is the string corresponding to a metadata name).

Getting History Information

To retrieve a contact’s HistoryItemDTO, your application must first create and fill an InteractionSearchTemplate instance, and then call the IHistoryService.getHistoryDTO() method.
An interaction search template delimits the retrieved interaction history items. Your application can set the index and numbers of history items, and can specify which attributes to retrieve in the DTO result. These features are useful to (for example) display the interaction data of a contact history by pages with a limited set of attributes.
The following code snippet retrieves the first 10 interactions of a contact history.

 
///Filling the template
InteractionSearchTemplate mySearchTemplate = new InteractionSearchTemplate();
mySearchTemplate.index = 0;
mySearchTemplate.length = 10;
 
/// Retrieving the history item DTOs for the ten first contacts
HistoryItemDTO[] myItems = myHistoryService.getHistoryDTO("my contact ID",
mySearchTemplate, true, new string[]{"history:*"}); // Each DTO contains all the // historic attribute values.
 
/// Displaying the retrieved historic data
foreach( HistoryItemDTO item in myItems)
{
   System.Console.WriteLine("— History item —\n");
   foreach(KeyValue myPair in item.data)
   {
      System.Console.WriteLine("Key: "+myPair.key + " Value: "+ myPair.value.ToString()+"\n");
   }
}

The Workflow Service

The workflow service provides your application with workbins. From an agent’s point of view, a workbin is a sort of interaction directory from which your application can pull, or into which it can put, interactions.
To define workbins more precisely: a queue contains interactions, and a view filters a queue’s interactions according to a set of criteria. A workbin filters a view’s interactions according to a further set of criteria. The following diagram shows an example of a view and workbins defined for a queue.
 

Example for Workbins, Views, and Queues

This example shows a queue containing e-mail interactions. For this queue, View0 lets your application see only e-mail interactions that are no older than a week.
In this view, two workbins coexist: one for draft e-mail interactions, and one for pending e-mail interactions. The workflow service can use those filters to retrieve a set of interactions organized in workbins for a particular place.
Here, the workflow service retrieves interactions no older than a week and available for place0. E-Mail1 and E-Mail2 are not retrieved as they should not be treated in place0.
Use the Configuration Layer to define views and workbins. For further details, refer to your Configuration Layer Documentation.
The workflow service is the IWorkflowService interface defined in the com.genesyslab.ail.ws.workflow namespace. To use this service, your application works with classes and enumerations of this namespace.
Use the workflow service to:

  • Display workbins and their filtered interactions.
  • Enable an agent to put an interaction in a workbin.

Handling a Workbin Interaction

By default, all interactions contained in a workbin are in the IDLE state. To handle a workbin’s interaction, you must pull it using IInteractionService.openInteractionForAgentDTO() or IInteractionService.openInteractionForPlaceDTO() methods from the IInteractionService interface. For more details, see Opening a Workbin Interaction.

Workbin Information

Workbin information is composed of a set of attributes and their content in terms of interactions.

Workbin Attributes

The workflow service defines a workbin’s information in the workbin domain. The following list is not exhaustive:

  • workbin:id—The system identifier of a workbin; used to retrieve all information about a workbin.
  • workbin:viewId—The system identifier of the view that contains a workbin.
  • workbin:placeId—The system identifier of the place that contains a queue’s views.
  • workbin:type—A workbin’s type.
  • workbin:reason—A string to display when an event occurs on the content of a workbin.
Workbin DTO

Your application can retrieve a workbin’s attributes and content—with respect to a particular place or agent—using a WorkbinDTO instance. The WorkbinDTO class has the following attributes:

  • workbinId—System ID of a workbin.
  • data—Key-value list of workbin attributes.
  • worbinInteractionsDTO—Array of DTOs; each DTO contains the information for an interaction of the workbin.

Workbin Interaction Information

The level of information provided for a workbin interaction depends on the type of interaction. The workflow service provides more data for multimedia interactions—that is, CHAT*, COLLABORATION*, or EMAIL* interactions.
The workflow service includes two domains of attributes for interactions:

  • workbin-interaction—Attributes summarizing an interaction.
    • interactionId—System ID of an interaction.
    • interactionType—Type of interaction.
    • subject—Subject of an interaction.
  • workbin-interaction.multimedia—Additional information specific to an multimedia interaction. The following list of attributes is not exhaustive:
    • from—Sender field of an interaction.
    • to—Receiver field of an interaction.
    • contactId—System ID of a contact in the UCS. See also The Contact Service.

To get information about workbin interactions, use one of the getWorkbins*() methods of the IWorkflowService interfaces.

Getting Information

The following table presents the methods of the IWorkflowService interface, which accesses workbin information.

Methods to Get Workbin Information

IWorkflowService Methods

Description

getQueues()

Gets simple containers for queues information.

getWorkbinsDTO()

Gets workbin DTOs for a particular place or agent (including workbin information and workbin interactions DTO).

getWorkbinsContentDTO()

Gets only the interactions contained in a workbin for a particular place or agent.

getWorkbinsContentForAllDTO()

Gets all interactions contained in a workbin (regardless of agent or place).

For example, the following code snippet uses the IWorkflowService.getWorkbinsDTO() method to retrieve information from all the workbins defined for a view for place0. For each workbin, it displays the DTO content, including workbin interaction DTOs.

 
///Getting Workbin DTO for place0
WorkbinDTO[] myWorkbinsDTO = myWorkflowService.getWorkbinsDTO("place0",
   null, /// all workbins are retrieved
   new string[]{"workbin:*"},///with all info for each workbin
   new string[]{"workbin-interaction:*",	///with all info for each
   "workbin-interaction.multimedia:*"}); /// contained ixn
 
   ///Displaying each Workbin DTO content
   foreach(WorkbinDTO myDTO in myWorkbinsDTO)
   {
      /// Displaying workbin ID:
      System.Console.WriteLine("Workbin: "+myDTO.workbinName+"\n");

      /// Displaying workbin data: (workbin domain)
      foreach(KeyValue myWorkbinPair in myDTO.data)
      {
         System.Console.WriteLine("key: "+myWorkbinPair.key
            + " value:"+myWorkbinPair.value.ToString()+"\n");
      }
 
      /// Displaying DTO content for each workbin interactions
      foreach(WorkbinInteractionDTO myWorkbinIxn in myDTO.workbinInteractionsDTO)
      {
         /// Displaying interaction ID:
         System.Console.WriteLine("Ixn Id: " +myWorkbinIxn.workbinInteractionId+"\n");
 
         /// Displaying data of current interaction: /// (workbin-interaction.*:* domain)
         foreach(KeyValue myWorkbinIxnPair in myWorkbinIxn.data)
         {
            System.Console.WriteLine("key: "+myWorkbinIxnPair.key +
               " value:"+myWorkbinIxnPair.value.ToString()+"\n");
         }
      }
   }

The System Service

The system service is the ISystemService interface of the com.genesyslab.ail.ws.system namespace. This service informs your application of the state of the Genesys servers connected to your client application. This service includes:

  • Methods to retrieve information about the currently connected servers.
  • Events to inform your application of real-time changes about the connected servers, using SystemEvent.

For further information about the Genesys servers, refer to your Genesys documentation.

Server Information

System service attributes provide your application with information about the connected servers that perform services requests. Your application can either retrieve these attributes with the ISystemService interface methods, or propagate them in SystemEvent.
The following are the ISystemService interface’s:

  • system.server-info:name—A string for the AIL Framework service name.
  • system.server-info:host—A string for the name of the host where the service should run.
  • system.server-info:port—A string for the port on which the service should run.
  • system.server-info:status—The ServerStatus value.
  • system.server-info:type—The ServerType value.
  • system.server-info:switch—The Switch object associated with this server (if the type is a telephony type); else null.

Server Type

Each server is associated with a service, and this association is provided in the system.server-info:type attribute. The ServerType enumeration lets your application with which server the application is connected through the server-side application. The following table comments the existing ServerType values.
 

Server and Services

ServerType

Description

CHAT

The server manages the chat service.

TELEPHONY

The server manages connections to voice media.

CONFIGURATION

The Configuration Layer server manages the configuration.

DATABASE

The server is the Universal Contact Server.

STATISTIC

The server manages the statistics service.

AIL

The server manages the server-side application connected to the Genesys Framework. Your client application interacts with this server.

IS

The server is the Interaction Server which manages voice, e-mail, and chat interactions.

Server Status

Combined with the server type attribute, the server status attribute lets your application determine whether a service is available or not. The service associated with the server is enabled if the system.server-info:status attribute’s value is ServerStatus.ON.
For other ServerStatus values, refer to the Agent Interaction SDK 7.6 Services API Reference.

Retrieving Server Information

To retrieve servers’ information, use the getServersDescriptionDTO() method of the ISystemService interface. This method takes a list of attribute keys as its parameter, and retrieves an array that contains information for all available servers. Each ServerDescriptionDTO object of the array contains the key-value pairs that corresponds to the key list.
The ServerDescriptionDTO class associates the server name with the server’s information. This class has the following attributes:

  • name—The server name.
  • data—A key-value array containing the attribute values.

The following code snippet shows how to call the getServersDescriptionDTO() method, and how to then display the contents of the DTO objects retrieved for the available servers.

/// Retrieving the DTOs
ServerDescriptionDTO[] myServerDescriptionDTOs =
mySystemService.getServersDescriptionDTO(new string[]{"*"});
 
/// Displaying the content of each DTO
foreach(ServerDescriptionDTO description in myServerDescriptionDTOs)
{
   System.Console.WriteLine(description.name+": ");
   // Displaying name and value for each attribute
   foreach(KeyValue pair in description.data)
   {
      System.Console.WriteLine(pair.key +" - "+pair.value.ToString());
   }
}

System Events

The SystemEvent event of the ISystemService interface occurs when a value of one of this interface’s published attributes has changed. (The published attributes are all ISystemService attributes.)
See also The Event Service.

The Resource Service

The resource service provides access to configuration data defined in the Configuration Layer. For example, your application can use the resource service to retrieve action codes, DN information, and interaction attribute metadata.
The resource service is the IResourceService interface defined in the com.genesyslab.ail.ws.resource namespace. To use this service, your application works with classes and enumerations of this namespace.

Resource Information

Two domains are defined to provide your application with resource information:

  • resource.dn —DN summary data.
  • resource.common —Common data.

The following subsections describe those domains.

DN Summary

Your application can use the resource service to get information about the DNs of a switch without registering those DNs. This information corresponds to DN summaries and is defined in the resource.dn domain.
Retrieve this information with the IResourceService.getDnSummariesDTO() method.The information is returned in a DnSummaryDTO object. This class associates the DN identifier with this DN’s DTO data.

Common Information

Your application can retrieve two types of common information defined in the resource.common domain:

  • resource.common:actionCodes —The codes that can be used to specify a reason in calls to the agent service methods. All action codes are defined in the ActionCodeType enumeration.
  • resource.common:incomingAddresses —The call center’s e-mail addresses.

Use the IResourceService.getCommonsDTO() method to retrieve the corresponding attributes as key-value pairs.

Enumerators

Use enumerators to get the key-value pairs of attributes defined in the Configuration Layer. The Enumerator class describes an enumerator and contains its associated values:

  • defaultValue —The default value of this enumerator, if any.
  • description —The enumerator’s description.
  • enumeratorId —The name of this enumerator.
  • type —The type of this enumerator; null if no type is defined.
  • values —The values of this enumerator. Each value of an enumerator is an EnumeratorValue instance.

Use the IResourceService.getCommonsDTO() method to retrieve the enumerators defined in the Configuration Layer.

Interaction Information

The Configuration Layer defines interaction attributes and interaction custom properties in the Business Attributes section. Your application can get the corresponding metadata objects using the resource service and access the corresponding values in the attached data of an interaction using the metadata name as an attached data key. See Attached Data.

Interaction Attributes

Values

The InteractionAttributeValue class characterizes the information in an interaction attribute’s value:

  • id—The system ID of the interaction attribute’s value.
  • name —The name of the corresponding interaction attribute’s metadata.
  • value —The value of the interaction attribute.
  • description —The description of the interaction attribute’s value.
  • default —True if the interaction attribute value’s is a default value.
  • type —The type of interaction attribute.
Metadata

Each interaction attribute value has a type that specifies the corresponding interaction attribute. This type resides in a InteractionAttributeMetaData instance, as shown below.
 

Interaction Attribute Value and Metadata

The InteractionAttributeMetaData class’ main fields are the following:

  • 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.
  • sortable—True, if the attribute can be used to sort the contacts. For example, a last name may be sortable.
  • type—Type of the corresponding attribute values defined in the InteractionAttributeMetaDataType enumeration

Your application can retrieve interaction attributes’ metadata using the following IResourceService methods:

  • getInteractionAttributeMetaDataById()—To retrieve metadata with their IDs.
  • getInteractionAttributeMetaDataByName()—To retrieve metadata with their names.

Then, to get interaction attribute values, use the metadata name as the key when retrieving history.additional data with the history service. See also History Information.

Custom Attached Data

The Interaction Custom Properties in the Configuration Layer correspond to the CustomAttachedData objects that your application can retrieve using the IResourceService.getCustomAttachedDataByXxx() method.
The CustomAttachedData class describes a metadata for a custom property. This class includes method to get the corresponding name, display name, and description of a custom property. It also provides the predefined values for the custom attached data (if any).
Call the CustomAttachedData.getName() method to get the name of a custom property and use it as a key to access or modify the corresponding value in an interaction’s attached data map. See Attached Data.

Getting Resource Information

The following code snippet shows how to get and display some common information.

///Getting Common DTOs
KeyValue[] myCommonDTOs = myResourceService.getCommonsDTO(new string[]{"resource.common:*"});
 
///Displaying the common DTOs
foreach(KeyValue myCommonDTO in myCommonDTOs )
{
   /// If action codes, displaying them
   if(myCommonDTO.key == "resource.common:actionCodes")
   {
      ActionCode[] myActionCodes = (ActionCode[]) myCommonDTO.value;
      System.Console.WriteLine( "Configuration Layer: agent actions codes");
      foreach(ActionCode myCode in myActionCodes)
      {
         System.Console.WriteLine(myCode.ToString());
      }
   }
   /// If e-mail addresses, displaying them
   else if(myCommonDTO.key == "resource.common:incomingAddresses")
   {
      System.Console.WriteLine( "Configuration Layer: Call Center addresses");
      string[] myCallCenterAddresses = (string[]) myCommonDTO.value;
      foreach(string myAddress in myCallCenterAddresses)
      {
         System.Console.WriteLine(myAddress.ToString());
      }
   }
}

The Monitor Service

The MonitorService interface provides monitoring features for agent status. With this service, you can subscribe to an agent and get real-time information about that agent’s status (which is available in the AgentCurrentState category from Stat Server).

Monitor Information

MonitorService information consists of a set of current-state data:

  • monitor-status:agent —The current status of an agent and all his or her media.
  • monitor-status:media —The current status of a media associated with an agent.

Getting Monitor Information

To access monitor information, you can either subscribe to StatusEvent (details on events are in The Event Service), or you can use the PeekStatus method. The two snippets that follow correspond to these two options, respectively.

Subscribing to StatusEvent

/// Creating topic objects for the monitor service
TopicsService [] topicServices = new TopicsService[1];
topicServices[0] = new TopicsService();
topicServices[0].serviceName = "MonitorService";
topicServices[0].topicsEvents = new TopicsEvent[1];
topicServices[0].topicsEvents[0] = new TopicsEvent();
 
// Creating a topic event for status events
topicServices[0].topicsEvents[0].eventName = "StatusEvent";
topicServices[0].topicsEvents[0].attributes =
new String[]{"monitor-status:agent","monitor-status:media"};
topicServices[0].topicsEvents[0].triggers = new Topic[1];
topicServices[0].topicsEvents[0].triggers[0] = new Topic();
topicServices[0].topicsEvents[0].triggers[0].key = "STATUS";
topicServices[0].topicsEvents[0].triggers[0].value = mValue; //objectType:objectid:notificationMode:notificationValue

Values

  • objectType—type of the object (PERSON or QUEUE).
  • objectId—identifier of the object.
  • notificationMode—CHANGED_BASED orTIME_BASED.
  • notificationValue—the value of the notification.
    • CHANGED_BASED —an event will be sent only if the value changes by more than this notificationValue.
    • TIME_BASED—an event is sent every notificationValue seconds.
    • Important
    If the parameter contains a ":" (colon) character, escape it with a "\" (slash) character (for example, Agent:100 becomes Agent\:100).

Example

Here is an example of the full parameter string you might use:

 
PERSON:Agent10:CHANGED_BASED:10
topicServices[0].topicsEvents[0].filters = null;

Using the PeekStatus Method

//Retrieving an Agent status:
MonitorEventStatus myMonitorEventStatus = myMonitorService.peekStatus(PERSON, myAgentId)
 
//Display this agent's status data:
System.Console.WriteLine(myMonitorEventStatus.agentStatus.userName+": "+myMonitorEventStatus.agentStatus.agentStatus.ToString());
 
//and all his media statuses
foreach(MonitorEventMediaStatus mediaStatus in myMonitorEventStatus.agentStatus.mediaStatuses)
{
   System.Console.WriteLine(mediaStatus.name+": "+mediaStatus.mediaStatus.ToString());
 
}
This page was last edited on January 30, 2014, at 15:29.
Comments or questions about this documentation? Contact us for support!