Skip navigation links

Digital Messaging Server. Channel Driver API

This document explains how to create a custom media channel driver for Digital Messaging Server (DMS) on an example of Sample Driver.

See: Description

Packages 
Package Description
com.genesyslab.mcr.smserver.channel
Interfaces, definitions and implementation of Social Messaging Server's channel driver interface.

This document explains how to create a custom media channel driver for Digital Messaging Server (DMS) on an example of Sample Driver. The Sample Driver is a part of DMS installation package; it is located in an DMS installation folder at the location <DMS installation folder >\media-channel-drivers\channel-sample

Pluggable Media Channel Drivers in DMS

DMS’ pluggable channel drivers’ architecture specifies an open interface for media channel drivers, which allows easily to add-on custom channel drivers in the server’s structure. The next schema shows DMS configuration with two media channel drivers involved – the Twitter Driver and the Facebook Driver, which are delivered by Genesys Telecommunications Laboratories as a part of the standard DMS’ installation package. Both these drivers are built as regular pluggable DMS’ channel drivers on the bases of the DMS’ open channel driver’s interface.

Each channel driver, to be accessible by DMS, is to be configured in the Genesys CME. Configuration of Genesys drivers is described in the technical documentation “eServices 9.0. Reference Manual”, section “Digital Messaging Server Options” and in the Genesys Documentation Wiki - Digital Messaging Server.

Every channel driver is represented in the DMS’s configuration by one mandatory section and it may have a few optional driver-specific sections. Some elements of the Genesys drivers’ configuration, i.e. sections and options, may be referred in the following description as mandatory, exemplary, or recommended ones. Mandatory sections of Genesys drivers are illustrated on the right part of the schema below.

A channel driver submits data from a media source to business logic (via DMS and Interaction Server) and implements a processing of requests from business logic. Requests to a media channel driver are formulated as ESP (External Service Protocol) requests; they are passed to DMS via ESP data port exposed by the server. Naturally, that a set and functions of a channel driver’s requests are specific for every channel driver. Yellow boxes on the left side of the schema presented below represent ESP requests exposed by channel drivers.

Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: Description: T:\icswc_source\Work\MessagingServer\Messaging_Server_802\src\com\genesyslab\mcr\smserver\channel\doc-files\SmServer-1.gif

Mandatory Section of a Driver Instance in DMS’ Configuration

Mandatory section of a driver instance in DMS’s configuration is named channel-<name> (see limitations in the Reference Manual or in the Genesys Documentation Wiki - Digital Messaging Server). This section name is used for driver instance identification in Genesys environment. It’s used in ESP requests, as described later, and for logging purposes, both by the driver and DMS, as it is also described below.

Mandatory section should include the following mandatory options (see the Reference Manual or the Genesys Documentation Wiki - Digital Messaging Server):
driver-classname, inbound-route-default.

It is recommended to include in this section options with credentials of the driver’s instance in a media data source, e.g. in a social network. It is also recommended to include option x-inbound-media here (see the Reference Manual or the Genesys Documentation Wiki - Digital Messaging Server).

It is recommended to include other driver instance-related parameters, such as data queries, timeouts for data fetching, etc. in separate configuration section(s). See naming convention for additional sections in the Reference manual.

Below is an example of the Twitter Driver configuration.

[channel-twitter-a]

driver-classname=com.genesyslab.mcr.smserver.channel.twitter.TwitterDriver

inbound-route-default=<set value>

x-access-token=<set value>

x-access-token-secret=<set value>

x-consumer-key=<set value>

x-consumer-secret=<set value>

x-inbound-media=twitter

x-registered-app-name=<set value>

x-user-id=<set value>

Interfaces and Classes for Plug-in Schema

DMS specifies two interfaces com.genesyslab.mcr.smserver.channel.ChannelDriver ChannelDriver and com.genesyslab.mcr.smserver.channel.ChannelDriverPU ChannelDriverPU which are used in any media channel driver.
Channel driver must implement interface com.genesyslab.mcr.smserver.channel.ChannelDriver ChannelDriver which is used by DMS to interact with driver, for example, to initialize a driver or to request it to send a message to media.
Interface com.genesyslab.mcr.smserver.channel.ChannelDriverPU ChannelDriverPU represents services provided by SM Server to a channel driver, for example, methods to write logging messages or to submit incoming message to Interaction Server.

Class com.genesyslab.mcr.smserver.gframework.CfgOptions CfgOptions provides an ability to read configuration information from Genesys CME. Thus, custom implementation of a driver can (and supposed to) keep driver configuration information inside corresponding SM Server configuration object.

Class com.genesyslab.mcr.smserver.channel.ChannelDriverConstants ChannelDriverConstants contains pre-defined constants supposed to be used in exchange of data between the server and a channel driver.

Some other classes are used for work with parameters of methods of interfaces and classes above.

Driver Lifecycle, General Description

Channel driver is associated with a media channel configured by specifying a driver’s class name in configuration option driver-classname.
The server reads configuration from Configuration Server and determines which Java class is to be loaded for each media channel specified. The server creates an instance of the class, initializes and starts the channel driver.

On initialization, driver reads its configuration from Genesys CME.

On start, driver starts its data fetching monitors. From that moment the server and a channel driver work mostly asynchronously: driver fetches data and submits it to the server, while the server can pass ESP requests to the driver.

For logging purposes, driver uses log of the server.

On its shutdown, DMS shutdowns channel drivers. On shutdown command driver stops its data fetching monitors.

Following description provides more accurate and detailed info about the matter.

Media Channel Data Fetching

A media channel fetches data from a media source by repeatedly executing a set of data queries on this media source. Data queries’ execution is implemented in a driver’s components named monitors. A driver’s design may be based on a several simultaneously running monitors, or may be based on one and the only monitor, which sequentially executes all data queries. The Sample Driver implements one-monitor data fetching schema.
Parameters of a channel driver monitors (fetch queries, timings, et al) are specified in the server’s configuration sections channel-<name>-monitor[-<name>] (refer to technical documentation “eServices 8.0. Reference Manual”, section “Digital Messaging Server Options” and in the Genesys Documentation Wiki - Digital Messaging Server).

Below is an example of the Twitter Driver data fetching monitor configuration.

[channel-twitter-a-monitor]

get-direct-messages=true

get-home-timeline=false

get-mentions=true

qry-alu=ALU

qry-from-somebody=from:GenesysCustomer

sampling-history=3600

sampling-period=600

Processing of ESP Requests

DMS uses the next procedure to select a media channel for processing of ESP request received from a caller (e.g. from Interaction Server).

  • The server searches attribute _umsChannel in parameters or in user data (interaction attributes) of ESP request received.
  • If the attribute has been found, then DMS tries to match its value with media channel names specified in the server configuration. Matched media channel is selected for processing of this ESP request and the request is passed to the channel’s driver by invoking method com.genesyslab.mcr.smserver.channel.ChannelDriver#umsRequest umsRequest. If no channel is matched, DMS returns ESP-response with error to the caller.
  • If the attribute has not been found and there is only one media channel exists in the server, then this channel is selected, otherwise DMS returns ESP-response with error to the caller.

Sample Media Channel Driver

The sample media channel driver imitates an activity of a real media channel driver; plus it demonstrates a technique and a possible structure of a real channel driver implementation. Particularly, the sample driver submits simulated “incoming” messages to Interaction Server and “processes” ESP requests received by SM Server and passed to the driver.

The Driver’s Configuration in Genesys CME

Below is an example of the Sample Driver’s configuration.

[channel-sample]

driver-classname=com.genesyslab.mcr.smserver.channel.sample.SampleDriver

inbound-route-default=101:endpointsample

x-inbound-media=samples

 

[channel-sample-monitor]

qry-alu=ALU

qry-from-somebody=from:GenesysCustomer

sampling-period=60

messages-create-max=10

itx-submit-timeout=30

itx-resubmit-delay=30

itx-resubmit_attempts=3

driver-classname – used by SMedia server as described above.
inbound-route-default – see “eServices 8.0. Reference Manual” section “Digital Messaging Server Options” or Genesys Documentation Wiki - Digital Messaging Server for more details.
x-inbound-media – used by the driver as an attribute of submitted data. See the Reference Manual or the Genesys Documentation Wiki - Digital Messaging Server for more details.

qry-alu, qry-from-somebody – “class” options. See analogous qry-<name> option in the Reference Manual or in the Genesys Documentation Wiki - Digital Messaging Server. In the Sample Driver this options are used for demonstration of a reading “class” options from Genesys CME.
sampling-period – analog of the same option in the Driver for Use with Twitter.
messages-create-max – max number of interactions the Sample Driver may submit to Interaction Server.
itx-submit-timeout - time to wait a response for a submitted request.
itx-resubmit-delay – analog of the x-itx-resubmit-delay option in the Driver for Use with Facebook.
itx_resubmit-attempts – analog of the x-itx-resubmit-ntimes option in the Driver for Use with Facebook.

The Driver’s Implementation

The driver’s implementation includes three Java classes (java files):

The Driver’s Build Procedure

The Sample Driver binaries, source code and complemented data are located in the DMS’s installation folder. The driver’s build procedure consists of the following steps:

  • Copy the Sample Driver source files with its folders structure from the Sample Driver folder to a build folder, where the build procedure will be performed.
  • Copy build.bat command file to the build folder.
  • Modify build.bat file - set variable GCTI_JDK_PATH with JDK's location (where files javac.exe and jar.exe are located).
  • Modify build.bat file - set variable BUILD_LIBS with DMS's folder lib location.
  • Run build.bat command file.
  • Get the build's result (file channel-sample.jar) from folder release.

Additional Information

Additional information on Genesys Telecommunications Laboratories, Inc. is available on our Technical Support website. The following documentation also contains information about this software.

Copyright Information

Copyright © 2010–2018 Genesys Telecommunications Laboratories, Inc. All rights reserved.

Any authorized distribution of any copy of this code (including any related documentation) must reproduce the following restrictions, disclaimer and copyright notice:

The Genesys name, trademarks and/or logo(s) of Genesys shall not be used to name (even as a part of another name), endorse and/or promote products derived from this code without prior written permission from Genesys Telecommunications Laboratories, Inc.

The use, copy, and/or distribution of this code is subject to the terms of the Genesys Developer License Agreement. This code shall not be used, copied, and/or distributed under any other license agreement.

THIS CODE IS PROVIDED BY GENESYS TELECOMMUNICATIONS LABORATORIES, INC. (“GENESYS”) “AS IS” WITHOUT ANY WARRANTY OF ANY KIND. GENESYS HEREBY DISCLAIMS ALL EXPRESS, IMPLIED, OR STATUTORY CONDITIONS, REPRESENTATIONS AND WARRANTIES WITH RESPECT TO THIS CODE (OR ANY PART THEREOF), INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. GENESYS AND ITS SUPPLIERS SHALL NOT BE LIABLE FOR ANY DAMAGE SUFFERED AS A RESULT OF USING THIS CODE. IN NO EVENT SHALL GENESYS AND ITS SUPPLIERS BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, ECONOMIC, INCIDENTAL, OR SPECIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, ANY LOST REVENUES OR PROFITS).

Copyright © 2010–2018 Genesys Telecommunications Laboratories, Inc. All rights reserved.

Top of Page

Copyright © 2018 Genesys Telecommunications Laboratories Inc.. All rights reserved.