Configuration
You can use the Configuration Platform SDK to write Java or .NET applications that access and update information from the Genesys Configuration Layer. These applications can range from the simple to the advanced.
This article shows how to implement the basic functions you will need to write a simple Configuration Layer application.
Once you have reviewed the information in this document, you should familiarize yourself with Configuration Layer Objects. Since the Configuration Platform SDK uses these objects for nearly everything it does, you will need to understand them before you start using this SDK.
When you are ready to write more complicated applications, take a look at the classes and methods described in the Platform SDK API Reference.
Setting Up a ConfServerProtocol Object
The first thing you need to do to use the Configuration Platform SDK is instantiate a ConfServerProtocol object. To do that, you must supply information about the Configuration Server you want to connect with. This example uses the URI of the Configuration Server, but you can also use the server's name, host, and port information:
[Java]
ConfServerProtocol confServerProtocol =
new ConfServerProtocol(
new Endpoint(
confServerUri));
Configuration Server needs some additional information in order to create a successful connection. This information includes the type of client you wish to create, your client's name, and your user name and password:
[Java]
confServerProtocol.setClientApplicationType(CfgAppType.CFGSCE.asInteger());
confServerProtocol.setClientName("default");
confServerProtocol.setUserName(userName);
confServerProtocol.setUserPassword(password);
After instantiating the ConfServerProtocol object, you need to open the connection to the Configuration Server:
[Java] confServerProtocol.open();
Creating a Query
Now that you have opened a connection, you can create a query and send it to Configuration Server. Let's say that you want to get information about a particular agent. To do this, you will need to supply the agent's user name using a filter key.
The filter key tells Configuration Server to narrow your query to a specific agent, rather than retrieving information about all of the persons in your contact center:
[Java]
KeyValueCollection filterKey = new KeyValueCollection();
filterKey.addObject("user_name", userName);
You can find the names of the filter keys for Person objects by looking in the Filter Keys section of the CfgPerson entry.
Now you are ready to create the request.
As you may know, Configuration Server considers agents to be objects of type CfgPerson. So you will need to create a request for information about a Person who has the user name you specified in the filter key:
[Java] CfgObjectType objectType = CfgObjectType.CFGPerson; int intPerson = objectType.asInteger(); RequestReadObjects requestReadObjects = RequestReadObjects.create( intPerson, filterKey);
After you have created your request, you can send it to Configuration Server, as shown here:
[Java] confServerProtocol.send(requestReadObjects);
If the request is successful, you will receive an EventObjectsRead message.
Interpreting the Response
The information you asked for is returned by invoking the getConfObject method of the EventObjectsRead message. This method returns an org.w3c.dom.Document representation of the object.
Here is a sample of how you might print the XML document:
[Java]
EventObjectsRead objectsRead =
(EventObjectsRead) theMessage;
System.out.println(theMessage.messageName());
System.out.println("There are "
+ objectsRead.getObjectTotalCount() + " objects of this type.");
Document resultDocument =
(Document) objectsRead.getConfObject();
... Add code to parse and print...
And this is what the XML document might look like:
<ConfData>
<CfgPerson>
<DBID value="105"/>
<tenantDBID value="101"/>
<lastName value="agent1"/>
<firstName value="Agent"/>
<employeeID value="agent1"/>
<userName value="agent1"/>
<password value="204904E461002B28511D5880E1C36A0F"/>
<isAgent value="2"/>
<CfgAgentInfo>
<placeDBID value="102"/>
<skillLevels>
<CfgSkillLevel>
<skillDBID value="101"/>
<level value="9"/>
</CfgSkillLevel>
</skillLevels>
<agentLogins>
<CfgAgentLoginInfo>
<agentLoginDBID value="103"/>
<wrapupTime value="0"/>
</CfgAgentLoginInfo>
</agentLogins>
<capacityRuleDBID value="127"/>
</CfgAgentInfo>
<isAdmin value="1"/>
<state value="1"/>
<userProperties>
<list_pair key="desktop-redial">
<str_pair key="phone-number0" value="5551212"/>
<str_pair key="phone-number1" value=""/>
<str_pair key="phone-number2" value=""/>
<str_pair key="phone-number3" value=""/>
<str_pair key="phone-number4" value=""/>
<str_pair key="phone-number5" value=""/>
<str_pair key="phone-number6" value=""/>
<str_pair key="phone-number7" value=""/>
<str_pair key="phone-number8" value=""/>
<str_pair key="phone-number9" value=""/>
</list_pair>
<list_pair key="multimedia">
<str_pair key="last-media-logged"
value="voice,email"/>
</list_pair>
</userProperties>
<emailAddress value="agent1@techpubs3"/>
</CfgPerson>
</ConfData>
This XML document contains information about a Person. To interpret the information contained in the document, look at the Parameters section for CfgPerson.
If you compare the elements in this XML document to the CfgPerson entry, you can see that some of them contain information that is explained in detail in another entry. For example, the CfgAgentInfo element contains information that is described in the CfgAgentInfo entry. Similarly, the CfgAgentLoginInfo element contains information described in the CfgAgentLoginInfo entry.
Updating an Object
You can update a Configuration Layer object by passing in an XML Document containing the appropriate information about that object:
[Java] CfgObjectType objectType = CfgObjectType.CFGPerson; int intPerson = objectType.asInteger(); RequestUpdateObject requestUpdateObject = RequestUpdateObject.create( intPerson, xmlDocument);
Creating a New Object
You can also create a new Configuration Layer object by sending an XML Document to Configuration Server, as shown here:
[Java] CfgObjectType objectType = CfgObjectType.CFGPerson; int intPerson = objectType.asInteger(); RequestCreateObject requestCreateObject = RequestCreateObject.create( intPerson, xmlDocument);
Closing the Connection
Finally, when you are finished communicating with the Configuration Server, you should close the connection, in order to minimize resource utilization:
[Java] confServerProtocol.close();
Working with Delta Objects
When using the Configuration Platform SDK to change attribute values of a configuration object, it is important to understand how "delta structures" work.
A delta structure contains values for each attribute in the configuration object. When a change is requested, a delta object is created that contains values for each attribute. Delta values are initialized to either zero (for integer values) or a null string - defaults that indicate no change should be made for that attribute. To change attributes of a configuration object, you first set the delta value for that attribute and then send the request to Configuration Server to be processed. Only attribute values that are changing should be specified in the delta structure for that object.
Any attributes with a delta value set to zero are left unchanged, so there are two special cases to remember when updating integer values in a configuration object:
- leaving the integer as 0 (zero) means that attribute does not change;
- setting a delta value to the current value of the configuration object attribute will change that attribute value to zero.
For example, if an Agent skill level is currently set to 5, then the following table illustrates the effect of various delta structure values:
| Initial Attribute Value | Delta Structure Value | Updated Attribute Value | Comment |
|---|---|---|---|
| 5 | 3 | 3 | Setting the delta structure value to a non-zero integer will change the attribute to that value. |
| 5 | 0 | 5 | Leaving the delta structure value as zero will leave the attribute unchanged. |
| 5 | 5 | 0 | Setting the delta structure value to the current attribute value will change the attribute to zero. |
Requests sent by SOAP clients and formed in an XML format do not use delta structures, because these types of request do not require all attributes to be present. The COM application block (which is shipped with the Platform SDKs) also does not use delta objects, as shown in the following code snippet:
[Java]
//retrieve an agent that has a single skill, with skill level set to 5
CfgPersonQuery query = new CfgPersonQuery();
query.setUserName("userName");
CfgPerson person = confService.retrieveObject(CfgPerson.class, query);
//Setting the skill level to 5 again will NOT result in a change in skill level (ie: it will remain 5).
((List<CfgSkillLevel>)person.getAgentInfo().getSkillLevels()).get(0).setLevel(5);
person.save();
//Setting the skill level to 0 will actually change the current skill level value.
((List<CfgSkillLevel>)person.getAgentInfo().getSkillLevels()).get(0).setLevel(0);
person.save();
Setting Up a ConfServerProtocol Object
The first thing you need to do to use the Configuration Platform SDK is instantiate a ConfServerProtocol object. To do that, you must supply information about the Configuration Server you want to connect with. This example uses the URI of the Configuration Server, but you can also use the server's name, host, and port information:
[C#]
ConfServerProtocol confServerProtocol =
new ConfServerProtocol(
new Endpoint(
confServerUri));
Configuration Server needs some additional information in order to create a successful connection. This information includes the type of client you wish to create, your client's name, and your user name and password:
[C#] confServerProtocol.ClientApplicationType = (int) CfgAppType.CFGSCE; confServerProtocol.ClientName = clientName; confServerProtocol.UserName = userName; confServerProtocol.UserPassword = password;
After instantiating the ConfServerProtocol object, you need to open the connection to the Configuration Server:
[C#] confServerProtocol.Open();
Creating a Query
Now that you have opened a connection, you can create a query and send it to Configuration Server. Let's say that you want to get information about a particular agent. To do this, you will need to supply the agent's user name using a filter key.
The filter key tells Configuration Server to narrow your query to a specific agent, rather than retrieving information about all of the persons in your contact center:
[C#]
KeyValueCollection filterKey = new KeyValueCollection();
filterKey.Add("user_name", userName);
You can find the names of the filter keys for Person objects by looking in the Filter Keys section of the CfgPerson entry in the Configuration Objects section of this API reference. This section has a similar reference page for each Configuration Layer object.
Now you are ready to create the request.
As you may know, Configuration Server considers agents to be objects of type CfgPerson. So you will need to create a request for information about a Person who has the user name you specified in the filter key:
[C#] RequestReadObjects requestReadObjects = RequestReadObjects.Create( (int) CfgObjectType.CFGPerson, filterKey);
After you have created your request, you can send it to Configuration Server, as shown here:
[C#] confServerProtocol.Send(requestReadObjects);
If the request is successful, you will receive an EventObjectsRead message.
Interpreting the Response
The information you asked for is returned in the ConfObject property of the EventObjectsRead message.
Here is a sample of how you might print the XML document:
[C#]
EventObjectsRead objectsRead = theMessage;
StringBuilder xmlAsText = new StringBuilder();
XmlWriterSettings xmlSettings = new XmlWriterSettings();
xmlSettings.Indent = true;
using (XmlWriter xmlWriter =
XmlWriter.Create(xmlAsText, xmlSettings))
{
XDocument resultDocument = objectsRead.ConfObject;
resultDocument.WriteTo(xmlWriter);
}
Console.WriteLine("This is the response:\n"
+ xmlAsText.ToString() + "\n\n");
And this is what the XML document might look like:
<ConfData>
<CfgPerson>
<DBID value="105"/>
<tenantDBID value="101"/>
<lastName value="agent1"/>
<firstName value="Agent"/>
<employeeID value="agent1"/>
<userName value="agent1"/>
<password value="204904E461002B28511D5880E1C36A0F"/>
<isAgent value="2"/>
<CfgAgentInfo>
<placeDBID value="102"/>
<skillLevels>
<CfgSkillLevel>
<skillDBID value="101"/>
<level value="9"/>
</CfgSkillLevel>
</skillLevels>
<agentLogins>
<CfgAgentLoginInfo>
<agentLoginDBID value="103"/>
<wrapupTime value="0"/>
</CfgAgentLoginInfo>
</agentLogins>
<capacityRuleDBID value="127"/>
</CfgAgentInfo>
<isAdmin value="1"/>
<state value="1"/>
<userProperties>
<list_pair key="desktop-redial">
<str_pair key="phone-number0" value="5551212"/>
<str_pair key="phone-number1" value=""/>
<str_pair key="phone-number2" value=""/>
<str_pair key="phone-number3" value=""/>
<str_pair key="phone-number4" value=""/>
<str_pair key="phone-number5" value=""/>
<str_pair key="phone-number6" value=""/>
<str_pair key="phone-number7" value=""/>
<str_pair key="phone-number8" value=""/>
<str_pair key="phone-number9" value=""/>
</list_pair>
<list_pair key="multimedia">
<str_pair key="last-media-logged"
value="voice,email"/>
</list_pair>
</userProperties>
<emailAddress value="agent1@techpubs3"/>
</CfgPerson>
</ConfData>
This XML document contains information about a Person. To interpret the information contained in the document, look at the Parameters section of the CfgPerson entry in the list of Configuration Objects.
If you compare the elements in this XML document to the CfgPerson entry, you can see that some of them contain information that is explained in detail in another entry. For example, the CfgAgentInfo element contains information that is described in the CfgAgentInfo entry. Similarly, the CfgAgentLoginInfo element contains information described in the CfgAgentLoginInfo entry.
Updating an Object
You can update a Configuration Layer object by passing in an XML document (of type XDocument) containing the appropriate information about that object:
[C#] RequestUpdateObject requestUpdateObject = RequestUpdateObject.Create( (int) CfgObjectType.CFGPerson, xDocument);
Creating a New Object
You can also create a new Configuration Layer object by sending an XML Document (of type XDocument) to Configuration Server, as shown here:
[C#] RequestCreateObject requestCreateObject = RequestCreateObject.Create( (int) CfgObjectType.CFGPerson, xDocument);
Closing the Connection
Finally, when you are finished communicating with the Configuration Server, you should close the connection, in order to minimize resource utilization:
[C#] confServerProtocol.Close();
Working with Delta Objects
When using the Configuration Platform SDK to change attribute values of a configuration object, it is important to understand how "delta structures" work.
A delta structure contains values for each attribute in the configuration object. When a change is requested, a delta object is created that contains values for each attribute. Delta values are initialized to either zero (for integer values) or a null string - defaults that indicate no change should be made for that attribute. To change attributes of a configuration object, you first set the delta value for that attribute and then send the request to Configuration Server to be processed. Only attribute values that are changing should be specified in the delta structure for that object.
Any attributes with a delta value set to zero are left unchanged, so there are two special cases to remember when updating integer values in a configuration object:
- leaving the integer as 0 (zero) means that attribute does not change;
- setting a delta value to the current value of the configuration object attribute will change that attribute value to zero.
For example, if an Agent skill level is currently set to 5, then the following table illustrates the effect of various delta structure values:
| Initial Attribute Value | Delta Structure Value | Updated Attribute Value | Comment |
|---|---|---|---|
| 5 | 3 | 3 | Setting the delta structure value to a non-zero integer will change the attribute to that value. |
| 5 | 0 | 5 | Leaving the delta structure value as zero will leave the attribute unchanged. |
| 5 | 5 | 0 | Setting the delta structure value to the current attribute value will change the attribute to zero. |
Note that requests sent by SOAP clients and formed in an XML format do not use delta structures, because these types of request do not require all attributes to be present. The COM application block (which is shipped with the Platform SDKs) also does not use delta objects, as shown in the following code snippet:
[C#] //retrieve a particular agent whose last name is "Jones" CfgPersonQuery query = new CfgPersonQuery(); query.UserName = "userName"; query.LastName = "Jones"; CfgPerson person = myConfService.RetrieveObject<CfgPerson>(query); //Setting the last name to the same value will NOT result in a change person.LastName = "Jones"; person.Save(); //Setting the last name to a different value will change the actual value person.LastName = "Smith"; person.Save();