Data Transfer Object

This chapter discusses the use of Data Transfer Objects (DTO).

Introduction

The purpose of this section is to introduce the general DTO concepts.
In a client application, a transaction may require multiple server requests to complete. This going back and forth takes up significant amount of time to complete the transaction.
To improve the performance of a set of requests, the solution is to package all the required data into a Data Transfer Object (DTO) that can be sent with a single call.
A DTO is a generic container for a key-value list of data associated with several distinct remote objects. You specify in the list only the keys you are interested in.
You use this list to retrieve or modify attributes’ values according to their properties.

DTOs in the Service API

The Agent Interaction Service API makes use of the DTO Pattern for services attributes that can be retrieved, set or published. DTOs are involved in published events, in services methods calls, and so on.
DTOs carry key-value attributes of several services. They are handled with dedicated methods and classes as presented in the following sections.

Dedicated Classes

Each service namespace includes classes gathering attributes for DTO handling. You can find several types of DTO classes:

• XxxDTO —This class manages the DTO related to Xxx; for example, InteractionDTO is a class managing the DTO of an interaction.
  
• XxxListDTO —This class manages an array of XxxYyyDTO; for example AgentListDTO manages an array of PersonDTO.
  
• XxxSummaryDTO —This class manages the DTO of an Xxx summary; for example AgentSummaryDTO is a class managing the DTO of an agent summary.
  

The attributes list of a DTO is a KeyValue array. The KeyValue class is a very simple container having two fields:

• KeyValue.key —The attribute name
  
• KeyValue.value —The object corresponding to the attribute value.
  

Attributes

Each service handles a set of objects and proposes several domains defining accessible attributes to deal with objects data.

Important

To determine what are the available attributes of a service, see the service interface description in theAgent Interaction SDK 7.6 Services API Reference.

For example, the IAgentService interface is a service dealing with a set of agents. Agents have two defined domains:

• person defines common data associated with persons (even if the person is not an agent) as for example: person:lastname and person:firstname.
  
• agent defines specific agent data as for example agent:defaultPlaceId (default place for the agent) or agent:currentPlaceId (current place for the agent).
  

Notation

For each service, the domain attributes used in DTO are defined in accordance with the following rule:

domain[[.subdomain]...]:attributeName

For example, the following attributes exist:

• interaction:interactionId
• interaction.voice:phonenumber
• interaction.mail.out:invitations
Warning
When you use an attribute, you have to use the complete attribute name, including the domain and sub-domains.

Properties

An attribute can have the properties defined, as shown in the following figure.
 

Attribute Properties

Attribute	Properties
read	The IXxxService attribute is readable and can be retrieved with a IXxxService.getXxxDTO() method.
read-default	The IXxxService attribute is likely to be often read, so it is part of the default attributes.
write	The IXxxService attribute is writable using a IXxxService.setXxxDTO() method.
event	The attribute can be published via the event service.
event-default	The attribute is likely to be often published via the event service, so it is part of the default attributes.

Important

To determine an attribute’s properties, see the attribute description in the service interface definition in the Agent Interaction SDK 7.6 Services API Reference.

DTOs Handling

Agent desktop applications use DTOs to read and write service attributes. DTOs also play an essential role in event handling.

Important

Genesys recommends that you avoid the use of the * wildcard in DTOs since they cause longer processing times for transactions.

This section shows how to read and set DTO attributes values and introduces the use of DTOs in events.

Reading DTOs

Reading a DTO consists in reading a list of attributes identified with a read property in the service domain. You first define the list of attribute names, then use the appropriate get*DTO() method.
For example, if you want to read the person:firstname and person:lastname attributes of the IAgentService interface, first define an array of these attribute names:

string[] myAttributeNames = new string[]{“person:firstname”, “person:lastname” };

Retrieve the corresponding values using the IAgentService.getPersonsDTO() method as illustrated in the following code snippet:

/// Defining the list of agents you are interested in:
string[] myAgentIds = new string[]{ “agent0”, “agent1”};
 
/// Retrieving for each agent the attributes value /// defined in mAttributeNames
PersonDTO[] myValues = myAgentService.getPersonsDTO(myAgentIds,myAttributeNames);
 

Access to the attribute values in the data field of the AgentDTO object.

/// Displaying agent0 attributes name and value:
foreach(KeyValue data in myValues[0].data )
{
   System.Console.WriteLine("{0}={1}", data.key, data.value.ToString());
}

Setting DTOs

You can set new values for service attributes having the write property in the service domain.
Create a *DTO containing the KeyValue pairs of the writable service attributes and their new values. Once you have created the DTO, you call the appropriate I**Service.set*DTO() method.
For example, the IAgentService interface allows you set an array of PersonDTO. Each PersonDTO object associates a list of KeyValue attributes with an agent ID. You can create a DTO containing the writable agent:signature attribute and set it with the IAgentService.setPersonsDTO() method, as illustrated in the following code snippet:

/// Creating a DTO array
AgentDTO[] aNewDTO = new PersonDTO[1];
 
/// Creating a new DTO
aNewDTO[0] = new PersonDTO();
 
/// This DTO is related to agent0 information
aNewDTO[0].personId = “agent0”;
aNewDTO[0].data = new KeyValue[1];
 
/// The targeted data is the agent0 signature
aNewDTO[0].data[0] = new KeyValue();
aNewDTO[0].data[0].key = "agent:signature";
aNewDTO[0].data[0].value = "This is agent0 signature";
 
/// Setting the new DTO
PersonError[] errors = myAgentService.setPersonsDTO(aNewDTO);
/// Displaying the errors
foreach(PersonError err in errors)
{
   System.Console.WriteLine("Setting DTO: {0} -", err.ToString());
}

The attributes are updated in the order of the KeyValue array. If an error occurs on an attribute, the method returns an error in an array specifying on which attribute the error has occurred.

Important

If an error occurs on the update of an attribute, it does not stop the update process: the remaining attributes are updated.

DTOs and Events

Domain attributes that have the event property or the event-default property are published in events.
To determine which attributes are published by an event, refer to the Agent Interaction SDK 7.6 Services API Reference. The available attributes are listed in the event description (part of the service interface definition).
When you subscribe to events, you specify which attributes are retrieved. Then, the incoming events contain the KeyValue array with these attributes and their current value.
For further information about event handling, refer to The Event Service:

• Building TopicsEvent for further details on DTO when subscribing to events.
  
• Reading DTOs in Events for further details on published DTOs.
  

DTOs and Wildcards

Agent Interaction SDK 7.6 Services API includes wildcards which simplify the code for getting attributes through DTOs.
Attribute Wildcard lists the possible wildcards to access groups of attributes. However, Genesys recommends that your application makes a limited use of these wildcards.
Retrieving large groups of attribute values causes longer processing times for transactions, and decreases your application’s performances. In particular, Genesys recommends that you avoid using the * wildcard.
The default wildcard should be your preferred one, because attributes marked as default are commonly used by applications deployed above the Agent Interaction SDK 7.6 Services API.

Attribute Wildcard

Wildcard	Meaning
*	All the attributes of all the domains and subdomains.
default	All the attributes marked default in all domains and subdomains.
domain:*	All the attributes of this domain.
domain:default	All the attributes marked as default in this domain.
domain.*:*	All the attributes of the subdomains.
domain.*:default	All the attributes marked as default in the subdomains.
domain.subdomain:*	All the attributes of this domain.subdomain.
domain.subdomain:default	All the attributes marked as default in this domain.subdomain.