Management Layer
You can use the Management Platform SDK to write Java or .NET applications that interact with the Genesys Message Server, Solution Control Server and Local Control Agents (LCAs). Most people will want to use this SDK to make their applications visible to the Genesys Management Layer so they can monitor them with Solution Control Server.
This document shows how to implement the basic functions you will need to write a simple voice application. It is organized to show the kind of structure you will probably use to write your own applications.
Making Your Application Visible to the Genesys Management Layer
A Genesys Local Control Agent (LCA) runs on each host in the Genesys environment, enabling the Management Layer to monitor and control the applications running on that host. This section shows how to use the LCA running on your own host to make your application visible to the Genesys Management Layer.
Connecting to the Local Control Agent
As mentioned previously, the Platform SDK uses a message-based architecture to connect to Genesys servers. Genesys recommends that you use the Protocol Manager Application Block to handle these connections. We also recommend that you use the Message Broker Application Block for your message handling. Here is how to use Protocol Manager to connect to the LCA. (This discussion is based on the material in the article on Connecting to a Server Using the Protocol Manager Application Block.)
Here are the import statements you need for Protocol Manager:
[Java] import com.genesyslab.platform.applicationblocks.commons.protocols.LcaConfiguration; import com.genesyslab.platform.applicationblocks.commons.protocols.ProtocolManagementServiceImpl;
After you have set up your import statements, the first thing you need to do is create a Protocol Management Service object:
[Java] protocolManagementServiceImpl = new ProtocolManagementServiceImpl();
Then you need to create an LCA Configuration object:
[Java]
lcaConfiguration = new LcaConfiguration("Lca_App");
Note that the name you supply with the Configuration object ("Lca_App" in this example) is arbitrary.
Now you can configure the connection. This sample uses the default LCA port of 4999. It also sets the execution mode to Backup:
[Java]
try {
lcaConfiguration.setUri(new URI("tcp://localhost:4999"));
} catch (URISyntaxException e) {
e.printStackTrace();
}
lcaConfiguration.setClientName("Generic_Server_Backup");
lcaConfiguration.setExecutionMode(ApplicationExecutionMode.Backup);
Once you have configured your connection, you can register your LcaConfiguration object with the Protocol Management Service, and open your connection to the LCA:
[Java]
protocolManagementServiceImpl.register(lcaConfiguration);
try {
protocolManagementServiceImpl.getProtocol("Lca_App").open();
} catch (InterruptedException e) {
e.printStackTrace();
} catch (ProtocolException e) {
e.printStackTrace();
}
Updating the Application Status
When you need to update the status of your application, send a RequestUpdateStatus. Here is how to indicate that the application is running:
[Java]
RequestUpdateStatus requestUpdateStatus = RequestUpdateStatus.create();
requestUpdateStatus
.setApplicationName(lcaConfiguration.getClientName());
requestUpdateStatus.setControlStatus(ApplicationStatus.Running.asInteger());
try {
protocolManagementServiceImpl.getProtocol("Lca_App").send(
requestUpdateStatus);
} catch (ProtocolException e) {
e.printStackTrace();
}
The LCA will not return an event when you change the application status. So for this particular task, you will not need any more code.
Execution Mode and Event Handling
As mentioned, the LCA will not return an event when you change the application status. But when you change the execution mode — for example, from Primary to Backup — you will receive an EventChangeExecutionMode. Unlike most events you receive in the Platform SDK, this event requires a response from your application. If the Management Layer does not know that your application is expecting to work in Primary mode, for example, it cannot rely on the stability of the Genesys environment.
After receiving the EventChangeExecutionMode, your application must send a ResponseExecutionModeChanged to indicate to the Management Layer that you are now ready to run in the new execution mode.
In order to handle these events, you need to set up the Message Broker Application Block, as outlined here. (Note that this information is based on the Event Handling Using the Message Broker Application Block article, which discusses this process in more detail.)
First, here are the import statements:
[Java] import com.genesyslab.platform.applicationblocks.commons.Action; import com.genesyslab.platform.applicationblocks.commons.broker.BrokerServiceFactory; import com.genesyslab.platform.applicationblocks.commons.broker.EventBrokerService; import com.genesyslab.platform.applicationblocks.commons.broker.MessageIdFilter;
Now you can create an Event Broker Service object and register your event handler:
[Java] eventBrokerService = BrokerServiceFactory .CreateEventBroker(protocolManagementServiceImpl.getReceiver()); eventBrokerService.register(new ChangeExecutionModeHandler(), new MessageIdFilter(EventChangeExecutionMode.ID));
Here is a sample of the handler you might set up for the EventChangeExecutionMode. This handler includes your ResponseExecutionModeChanged:
[Java]
class ChangeExecutionModeHandler implements Action {
public void handle(Message obj) {
EventChangeExecutionMode eventChangeExecutionMode = (EventChangeExecutionMode) obj;
if (eventChangeExecutionMode != null) {
System.out.println("eventChangeExecutionMode:\n"
+ eventChangeExecutionMode + "\n\n");
ApplicationExecutionMode mode = eventChangeExecutionMode
.getExecutionMode();
lcaConfiguration.setExecutionMode(mode);
ResponseExecutionModeChanged response = ResponseExecutionModeChanged
.create(mode);
System.out.println("Sending response: " + response);
try {
protocolManagementServiceImpl.getProtocol("Lca_App").send(
response);
} catch (ProtocolException e) {
e.printStackTrace();
}
}
}
}
This is how you might send a request to change your application's execution mode from Backup to Primary:
[Java]
RequestUpdateStatus requestUpdateStatus = RequestUpdateStatus.create();
requestUpdateStatus
.setApplicationName(lcaConfiguration.getClientName());
requestUpdateStatus.setExecutionMode(ApplicationExecutionMode.Primary);
try {
protocolManagementServiceImpl.getProtocol("Lca_App").send(
requestUpdateStatus);
} catch (ProtocolException e) {
e.printStackTrace();
}
Once you have sent this request, the LCA will return an EventChangeExecutionMode, to which your application will respond with the ResponseExecutionModeChanged shown above.
Closing the Connection
When you are finished, close the connection to the LCA:
[Java]
try {
protocolManagementServiceImpl.getProtocol("Lca_App").close();
} catch (ProtocolException e) {
e.printStackTrace();
}
Monitoring Your Application with Solution Control Server
Solution Control Server can be used to monitor applications running in the Genesys environment. Here is how to obtain information about hosts and applications.
Connecting to Solution Control Server
As with the LCA example above, you need to set up a Protocol Management Service:
[Java] protocolManagementServiceImpl = new ProtocolManagementServiceImpl();
Now you can create an ScsConfiguration object and supply the necessary parameters. The ClientName is the name of a Solution Control application that has been set up in the Configuration Layer, while the ClientId is the DBID of that application:
[Java]
scsConfiguration = new ScsConfiguration("Scs_App");
try {
scsConfiguration.setUri(new URI(uriString));
} catch (URISyntaxException e) {
e.printStackTrace();
}
scsConfiguration.setClientName(applicationName);
scsConfiguration.setClientId(applicationDbid);
scsConfiguration.setUserName(userName);
At this point, register your Configuration object with the Protocol Management Service and open the connection to Solution Control Server:
[Java]
protocolManagementServiceImpl.register(scsConfiguration);
try {
protocolManagementServiceImpl.getProtocol("Scs_App").open();
} catch (InterruptedException e) {
e.printStackTrace();
} catch (ProtocolException e) {
e.printStackTrace();
}
Setting Up Event Handling
You will need to set up some event handling code, since Solution Control Server will return EventInfo or EventError messages in response to your requests for information. The code for this is similar to the LCA-related code shown above:
[Java]
eventBrokerService = BrokerServiceFactory
.CreateEventBroker(protocolManagementServiceImpl.getReceiver());
.
.
.
eventBrokerService.register(new ScsEvent(),
new MessageIdFilter(EventInfo.ID));
.
.
.
class ScsEvent implements Action {
public void handle(Message obj) {
EventInfo eventInfo =
(EventInfo) obj;
if (eventInfo != null) {
// Handle this event
}
}
}
Requesting Application Information
Here is how to request the status of an application, using its DBID:
[Java]
RequestGetApplicationInfo requestGetApplicationInfo =
RequestGetApplicationInfo.create(applicationDbid);
try {
protocolManagementServiceImpl.getProtocol("Scs_App").send(requestGetApplicationInfo);
} catch (ProtocolException e) {
e.printStackTrace();
}
When you send this request, you will receive an EventInfo that includes the status of the application:
'EventInfo' (1) attributes: attr_cfg_obj_type [int] = 9 [Application] attr_obj_live_status [int] = 1 [Stopped] attr_client [int] = 1384 attr_message [str] = "APP_STATUS_STOPPED" attr_cfg_obj_id [int] = 174 attr_live_status_second [int] = [output suppressed] attr_ref_id [int] = 2 attr_app_work_mode [int] = 2 [Exiting]
If you want to be notified when the status of an application changes, send a RequestSubscribe.
[Java]
RequestSubscribe requestSubscribeApp = RequestSubscribe.create();
requestSubscribeApp.setControlObjectType(ControlObjectType.Application);
requestSubscribeApp.setControlObjectId(applicationDbid);
try {
protocolManagementServiceImpl.getProtocol("Scs_App").send(requestSubscribeApp);
} catch (ProtocolException e) {
e.printStackTrace();
}
Whenever the application's status changes, you will receive an EventInfo that informs you of the new status.
Requesting Host Information
You can also request information about the status of a host. But in this case, you must issue a RequestSubscribe before you will receive any information about the host. Here is how:
[Java]
RequestSubscribe requestSubscribe = RequestSubscribe.create();
requestSubscribe.setControlObjectType(ControlObjectType.Host);
requestSubscribe.setControlObjectId(hostDbid);
try {
protocolManagementServiceImpl.getProtocol("Scs_App").send(requestSubscribe);
} catch (ProtocolException e) {
e.printStackTrace();
}
RequestGetHostInfo requestGetHostInfo =
RequestGetHostInfo.create(hostDbid);
try {
protocolManagementServiceImpl.getProtocol("Scs_App").send(requestGetHostInfo);
} catch (ProtocolException e) {
e.printStackTrace();
}
If you just send the RequestSubscribe, you will be notified any time the host status changes. If you also send the RequestGetHostInfo, you will also receive an immediate notification of the host's status, whether it has changed or not. Here is a sample of the information you will receive.
'EventInfo' (1) attributes: attr_cfg_obj_type [int] = 10 [Host] attr_obj_live_status [int] = 2 [StopTransition] attr_client [int] = 1920 attr_message [str] = "HOST_STATUS_RUNNING" attr_cfg_obj_id [int] = 114 attr_ref_id [int] = 3
Once you have subscribed to a host, you can send a RequestGetHostInfo at any time to receive information about its status.
Closing the Connection
When you are finished, close the connection to Solution Control Server:
[Java]
try {
protocolManagementServiceImpl.getProtocol("Scs_App").close();
} catch (ProtocolException e) {
e.printStackTrace();
} catch (IllegalStateException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}
Sending a Log Message to Message Server
You can easily send log messages to Message Server using the Management Platform SDK. The following discussion will use a MessageServerProtocol object, rather than using the Protocol Manager Application Block.
First you need to create the Protocol object:
[Java] MessageServerProtocol messageServerProtocol = new MessageServerProtocol( new Endpoint(new URI(serverUri)));
Now you can configure the Protocol object and open the connection to Message Server:
[Java]
messageServerProtocol.setClientType
(ConfServerClientType.ThirdPartyApp.ordinal());
messageServerProtocol.setClientName("Third_Party_App");
messageServerProtocol.setClientHost("hostname");
messageServerProtocol.open();
At this point, you are ready to create a RequestLogMessage:
[Java]
RequestLogMessage request = RequestLogMessage.create();
request.setEntryId(9600);
request.setEntryCategory(LogCategory.Alarm);
request.setEntryText("Message Text...");
request.setLevel(LogLevel.Alarm);
request.setTime(new Date());
Once you have created the request, you can send the request to Message Server. When you are finished, you should close the connection:
[Java] messageServerProtocol.send(request); . . . messageServerProtocol.close();
Making Your Application Visible to the Genesys Management Layer
A Genesys Local Control Agent (LCA) runs on each host in the Genesys environment, enabling the Management Layer to monitor and control the applications running on that host. This section shows how to use the LCA running on your own host to make your application visible to the Genesys Management Layer.
Connecting to the Local Control Agent
As mentioned previously, the Platform SDK uses a message-based architecture to connect to Genesys servers. Genesys recommends that you use the Protocol Manager Application Block to handle these connections. We also recommend that you use the Message Broker Application Block for your message handling. Here is how to use Protocol Manager to connect to the LCA. (This discussion is based on the material in the article on Connecting to a Server Using the Protocol Manager Application Block.)
Here is the using statement you need for Protocol Manager:
[C#] using Genesyslab.Platform.ApplicationBlocks.Commons.Protocols;
After you have set up your using statement, the first thing you need to do is create a Protocol Management Service object:
[C#] protocolManagementService = new ProtocolManagementService();
Then you need to create an LCA Configuration object:
[C#]
LcaConfiguration lcaConfiguration = new LcaConfiguration("Lca_App");
Note that the name you supply with the Configuration object ("Lca_App" in this example) is arbitrary.
Now you can configure the connection. This sample uses the default LCA port of 4999. It also sets the application status to Initializing and the execution mode to Backup:
[C#]
lcaConfiguration.Uri = new Uri("tcp://localhost:4999");
lcaConfiguration.ClientName = applicationName;
lcaConfiguration.ControlStatus = (int) ApplicationStatus.Initializing;
lcaConfiguration.ExecutionMode = ApplicationExecutionMode.Backup;
Once you have configured your connection, you can register your LcaConfiguration object with the Protocol Management Service, and open your connection to the LCA:
[C#] protocolManagementService.Register(lcaConfiguration); protocolManagementService["Lca_App"].Open();
Updating the Application Status
When you need to update the status of your application, send a RequestUpdateStatus. Here is how to indicate that the application is running:
[C#] RequestUpdateStatus requestUpdateStatus = RequestUpdateStatus.Create(); requestUpdateStatus.ApplicationName = lcaConfiguration.ClientName; requestUpdateStatus.ControlStatus = (int) ApplicationStatus.Running; protocolManagementService["Lca_App"].Send(requestUpdateStatus);
The LCA will not return an event when you change the application status. So for this particular task, you will not need any more code.
Execution Mode and Event Handling
As mentioned, the LCA will not return an event when you change the application status. But when you change the execution mode — for example, from Primary to Backup — you will receive an EventChangeExecutionMode. Unlike most events you receive in the Platform SDK, this event requires a response from your application. If the Management Layer does not know that your application is expecting to work in Primary mode, for example, it cannot rely on the stability of the Genesys environment.
After receiving the EventChangeExecutionMode, your application must send a ResponseExecutionModeChanged to indicate to the Management Layer that you are now ready to run in the new execution mode.
In order to handle these events, you need to set up the Message Broker Application Block, as outlined here. (Note that this information is based on the Event Handling Using the Message Broker Application Block article, which discusses this process in more detail.)
First, here is the using statement:
[C#] using Genesyslab.Platform.ApplicationBlocks.Commons.Broker;
Now you can create an Event Broker Service object and register your event handler:
[C#] eventBrokerService = BrokerServiceFactory.CreateEventBroker(protocolManagementService.Receiver); eventBrokerService.Register(this.OnEventChangeExecutionMode, new MessageIdFilter(EventChangeExecutionMode.MessageId));
Here is a sample of the handler you might set up for the EventChangeExecutionMode. This handler includes your ResponseExecutionModeChanged:
[C#]
private void OnEventChangeExecutionMode(IMessage theMessage)
{
EventChangeExecutionMode eventChangeExecutionMode = theMessage as EventChangeExecutionMode;
if (eventChangeExecutionMode != null)
{
ApplicationExecutionMode mode = eventChangeExecutionMode.ExecutionMode;
lcaConfiguration.ExecutionMode = mode;
ResponseExecutionModeChanged response = ResponseExecutionModeChanged.Create(mode);
Console.WriteLine("Sending response: " + response);
protocolManagementService["Lca_App"].Send(response);
}
}
This is how you might send a request to change your application's execution mode from Backup to Primary:
[C#] RequestUpdateStatus requestUpdateStatus = RequestUpdateStatus.Create(); requestUpdateStatus.ApplicationName = lcaConfiguration.ClientName; requestUpdateStatus.ExecutionMode = ApplicationExecutionMode.Primary; protocolManagementService["Lca_App"].Send(requestUpdateStatus);
Once you have sent this request, the LCA will return an EventChangeExecutionMode, to which your application will respond with the ResponseExecutionModeChanged shown above.
Closing the Connection
When you are finished, close the connection to the LCA:
[C#] protocolManagementService["Lca_App"].Close();
Monitoring Your Application with Solution Control Server
Solution Control Server can be used to monitor applications running in the Genesys environment. Here is how to obtain information about hosts and applications.
Connecting to Solution Control Server
As with the LCA example above, you need to set up a Protocol Management Service:
[C#] protocolManagementService = new ProtocolManagementService();
Now you can create an ScsConfiguration object and supply the necessary parameters. The ClientName is the name of a Solution Control application that has been set up in the Configuration Layer, while the ClientId is the DBID of that application:
[C#]
scsConfiguration = new ScsConfiguration("Scs_App");
scsConfiguration.Uri = new Uri(uriString);
scsConfiguration.ClientId = applicationDbid;
scsConfiguration.ClientName = applicationName;
scsConfiguration.UserName = userName;
At this point, register your Configuration object with the Protocol Management Service and open the connection to Solution Control Server:
[C#] protocolManagementService.Register(scsConfiguration); protocolManagementService["Scs_App"].Open();
Setting Up Event Handling
You will need to set up some event handling code, since Solution Control Server will return EventInfo or EventError messages in response to your requests for information. The code for this is similar to the LCA-related code shown above:
[C#]
eventBrokerService =
BrokerServiceFactory.CreateEventBroker(protocolManagementService.Receiver);
.
.
.
eventBrokerService.Register(OnEventInfo);
.
.
.
private void OnEventInfo(IMessage theMessage)
{
EventInfo eventInfo = theMessage as EventInfo;
if (eventInfo != null)
{
// Handle this event
}
}
Requesting Application Information
Here is how to request the status of an application, using its DBID:
[C#] RequestGetApplicationInfo requestGetApplicationInfo = RequestGetApplicationInfo.Create(applicationDbid); protocolManagementService["Scs_App"].Send(requestGetApplicationInfo);
When you send this request, you will receive an EventInfo that includes the status of the application:
'EventInfo' ('1')
message attributes:
attr_app_work_mode [int] = 0 [Primary]
attr_client [int] = 660
attr_ref_id [int] = 4
attr_message [str] = "APP_STATUS_RUNNING"
attr_obj_live_status [int] = 6 [Running]
attr_cfg_obj_id [int] = 109
attr_cfg_obj_type [int] = 9 [Application]
If you want to be notified when the status of an application changes, send a RequestSubscribe.
[C#] RequestSubscribe requestSubscribeApp = RequestSubscribe.Create(); requestSubscribeApp.ControlObjectType = ControlObjectType.Application; requestSubscribeApp.ControlObjectId = applicationDbid; protocolManagementService["Scs_App"].Send(requestSubscribeApp);
Whenever the application's status changes, you will receive an EventInfo that informs you of the new status.
Requesting Host Information
You can also request information about the status of a host. But in this case, you must issue a RequestSubscribe before you will receive any information about the host. Here is how:
[C#] RequestSubscribe requestSubscribeHost = RequestSubscribe.Create(); requestSubscribe.ControlObjectType = ControlObjectType.Host; requestSubscribe.ControlObjectId = hostDbid; protocolManagementService["Scs_App"].Send(requestSubscribeHost); RequestGetHostInfo requestGetHostInfo = RequestGetHostInfo.Create(); requestGetHostInfo.ControlObjectId = hostDbid; protocolManagementService["Scs_App"].Send(requestGetHostInfo);
If you just send the RequestSubscribe, you will be notified any time the host status changes. If you also send the RequestGetHostInfo, you will also receive an immediate notification of the host's status, whether it has changed or not. Here is a sample of the information you will receive.
'EventInfo' ('1')
message attributes:
attr_client [int] = 660
attr_ref_id [int] = 3
attr_message [str] = "HOST_STATUS_RUNNING"
attr_obj_live_status [int] = 2 [StopTransition]
attr_cfg_obj_id [int] = 111
attr_cfg_obj_type [int] = 10 [Host]
Once you have subscribed to a host, you can send a RequestGetHostInfo at any time to receive information about its status.
Closing the Connection
When you are finished, close the connection to Solution Control Server:
[C#] protocolManagementService["Scs_App"].Close();
Sending a Log Message to Message Server
You can easily send log messages to Message Server using the Management Platform SDK. The following discussion will use a MessageServerProtocol object, rather than using the Protocol Manager Application Block.
First you need to create the Protocol object:
[C#]
MessageServerProtocol messageServerProtocol = new MessageServerProtocol(
new Endpoint(new Uri("tcp://host:4321")));
Now you can configure the Protocol object and open the connection to Message Server:
[C#] messageServerProtocol.ClientType = (int) ConfServerClientType.ThirdPartyApp; messageServerProtocol.ClientName = "Third_Party_App"; messageServerProtocol.ClientHost = "hostname"; messageServerProtocol.Open();
At this point, you are ready to create a RequestLogMessage:
[C#] RequestLogMessage requestLogMessage = RequestLogMessage.Create(); requestLogMessage.EntryId = 9600; requestLogMessage.EntryCategory = LogCategory.Alarm; requestLogMessage.EntryText = "Message Text..."; requestLogMessage.Level = LogLevel.Alarm; requestLogMessage.Time = new DateTime();
Once you have created the request, you can send the request to Message Server. When you are finished, you should close the connection:
[C#] messageServerProtocol.Send(requestLogMessage); . . . messageServerProtocol.Close();