DFM Prototype

Home > Orchestration Server Start Page > DFM Prototype

The Distributed Functional Module (DFM) enables 2nd and 3rd parties to create functional modules that extend the capabilities of the Orchestration Server (ORS). It provides the capability to process requests coming from SCXML strategies and translates them into external service calls. A configuration file is used to define a set of actions and the logic behind processing those corresponding actions found in SCXML strategies.

Creating a configuration file

A configuration file is an XML file defining actions that are supported by the DFM, as well external server addresses and transport definitions. The configuration file must have a path associated with it where the file can be found.

The following is a sample XML configuration file:

<dfm name='context_services' namespace='http://www.genesyslab.com/modules/dfm/context_services/v1'> 

	<globalsessionscripts>
		<script name='MyScript1'   ref='file://C:\ORS\DFM\Scripts\Script1.js' />
		<script name='MyScript2'   ref='file://C:\ORS\DFM\Scripts\Script2.js' />
		<script name='MyScript2'   ref='file://C:\ORS\DFM\Scripts\Script2.js' />
		<script name='MyScript3'   ref='http://138.120.72.36:17080/DFM/Scripts/Script3.js' />
		<script name='MyScript4'   ref='${dfmgvar.cfgbaselocation}\${dfmgvar.dfmname}\${dfmgvar.nodeid}\${dfmgvar.clustername}' />
	</globalsessionscripts>

	<sessions>
		<session name='DNISAlloc' ref='http://ca-to-ferb:80/DFM/rm.scxml' type='cluster' >
			<params>
				<param name='DNISPOOL' expr='7102' />
			</params>
		</session>
		<session name='Directory'  ref='http://ca-to-ferb:80/DFM/rm.scxml' type='node' expose='true' />
	</sessions>

	<protocols>
		<protocol type='http'>
			<params>
				<param name='timeout' expr='2'/>
			</params>
			<globalevents>
				<event name='protocol_event' mapping='101'/>
			</globalevents>
		</protocol>
		<protocol type='https'>
			<params>
				<param name='timeout' expr='3'/>
			</params>
			<globalevents>
				<event name='protocol_event' mapping='104'/>
			</globalevents>
		</protocol>
	</protocols>
	
	<connections> 
		<connection name='UCS_HTTP_simple' type='http' selectionmode='simple'> 
			<servers>
				<server name='UCS1' host='ca-to-ferb' port='80'> 
					<param name='username' expr='default'/>  
					<param name='password' expr='password'/> 
				</server>  
				<server name='UCS2' host='ca-to-cosmo' port='80'/> 
			</servers>
			<events> 
				<event name='done' mapping='200-202'/>
				<event name='error' mapping='0,401-510'/> 
			</events> 
		</connection> 			
		<connection name='UCS_HTTP_primary_backup' type='http' selectionmode='primary-backup'>  
			<servers>
				<server name='UCS1' host='ca-to-aries' port='80'/> 
				<server name='UCS2' host='ca-to-cosmo' port='80'/> 
				<server name='UCS3' host='ca-to-ferb' port='80'/> 			
			</servers>
		</connection> 
		<connection name='UCS_HTTP_round_robin' type='http' selectionmode='round-robin'>  
			<servers>
				<server name='UCS1' host='ca-to-cosmo' port='80'/>   
				<server name='UCS2' host='ca-to-aries' port='80'/> 
				<server name='UCS3' host='ca-to-ferb' port='80'/> 
			</servers>
		</connection> 
		<connection name='UCS_HTTPS' type='https' selectionmode='simple'>  
			<servers>
				<server name='UCS1' host='ca-to-aries' port='80'/> 
			</servers>
		</connection>  		
	</connections> 
		
	<transports> 
		<transport name='UCS_HTTP_GET' conntype='UCS_HTTP_simple'>  
			<param name='method' expr='GET'/> 
			<param name='enctype' expr='application/x-www-form-urlencoded'/>
			<param name='url' expr='/interactions'/> 
		</transport> 			
		<transport name='UCS_HTTP_DELETE' conntype='UCS_HTTP_primary_backup'>  
			<param name='method' expr='DELETE'/> 
			<param name='url' expr='/profiles'/> 
		</transport> 
		<transport name='UCS_HTTP_PUT' conntype='UCS_HTTP_primary_backup'>  
			<param name='method' expr='PUT'/> 
			<param name='url' expr='/interactions'/> 
		</transport> 
		<transport name='UCS_HTTP_POST' conntype='UCS_HTTP_round_robin'>  
			<param name='method' expr='POST' /> 
			<param name='enctype' expr='application/json'/>
			<param name='url' expr='/profiles'/> 
		</transport> 
		<transport name='UCS_HTTP' conntype='UCS_HTTP_simple'/> 
		<transport name='UCS_HTTPS' conntype='UCS_HTTPS'/>  		
	</transports> 
	
	<actions> 
 		<action name='query_ixn_by_customer' transport='UCS_HTTP' sessionaffinity='true'> 
			<overrides> 
				<param name='method' expr='${method1}'/> 
				<param name='enctype' expr='${enctype1}'/> 
				<param name='timeout' expr='${timeout1}'/> 
				<param name='url' expr='/interactions/${cid}'/>
			</overrides>  
			<attributes> 
				<attribute name='method1' type='Expression' optional='true' default='POST'/> 
				<attribute name='enctype1' type='String' optional='true' default='application/json'/> 
				<attribute name='timeout1' type='Number' optional='true'/>  
				<attribute name='customer_id' alias='cid' type='String' mapping='parameter' optional='false'/> 
			</attributes>
			<events> 
				<event name='done' mapping='200,405'/>
				<event name='error' mapping='404'/> 
				<event name='redirect' mapping='300-308'/>
			</events>
		</action> 		
		<action name='create_customer_profile' transport='UCS_HTTP_POST'>
			<attributes>
				<attribute name='profile' type='Expression' optional='true' mapping='content' default='({})'/>
				<attribute name='X-Genesys-DFM-Tenant' alias='tenant' type='Expression' optional='true' mapping='header' default='Environment'/>
			</attributes>
			<events>
				<event name='done' mapping='200'/>
				<event name='error' mapping='0,404'/>
				<event name='no_content' mapping='204'/>
			</events>
		</action>
		<action name='update_customer_profile' transport='UCS_HTTP_PUT' sessionaffinity='false'>
			<overrides>
				<param name='url' expr='/profiles/${customer_id}'/> 
			</overrides>
			<attributes>
				<attribute name='customer_id' type='String' optional='false'/>
				<attribute name='profile' type='Expression' optional='false' mapping='content'/>
			</attributes>
			<events>
				<event name='done' mapping='204'/>
				<event name='error' mapping='0,405'/>
			</events>
		</action>
	</actions> 
	
</dfm>

Configuration File

All configuration files must begin with the <dfm> element, along with the following attributes:

Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string that is unique across all DFM types.	This specifies the DFM's name.
namespace	yes	string		Any valid string that is unique across the ORS cluster.	This specifies the DFM's SCXML namespace. It cannot use values that have been used by other DFMs and existing FMs which includes: http://www.genesyslab.com http://www.genesyslab.com/modules/session http://www.genesyslab.com/modules/statistic http://www.genesyslab.com/modules/interaction http://www.genesyslab.com/modules/queue http://www.genesyslab.com/modules/resource http://www.genesyslab.com/modules/dialog http://www.genesyslab.com/modules/classification http://www.genesyslab.com/modules/ws

Predefined DFM Variables - Since 8.1.2.41

The following set of read-only variables are provided by the DFM to aid in configuration:

DFM Predefined Variable	Description
${dfmgvar.cfgbaselocation}	This is used to define the fully qualified location of the configuration file without the actual file name and is used regardless of if the file was obtained via HTTP , an actual directory or a fully qualified file path. For example if the file is located at http://localhost:8080/mydirectory/mydfm.txt, then ${dfmgvar.cfgbaselocation} = http://localhost:8080:/mydirectory If the configuration was located at file://C:\ORS\DFM\CfgFiles\cfg_contextServices.txt, then ${dfmgvar.cfgbaselocation} =  file:// C:\ORS\DFM\CfgFiles
${dfmgvar.dfmname}	This is used to store the name of the DFM as obtained from the <dfm> name attribute.
${dfmgvar.nodeid}	This is the ORS node ID.
${dfmgvar.clustername}	This is the ORS cluster identifier.

DFM Session Function Support (optional) - Since 8.1.2.41

This adds JavaScript function support to the DFM that the user can call directly.  The scripts are loaded into the DFM at startup and made available to any sessions that reference the DFM.  These functions can act as helper functions that can be executed within the context of the session and requires no services from the DFM.  They are global and may share a global object available to all execution contexts within the SCXML engine.

The JavaScript functions are referred as follows:

_genesys.<dfmname>.<functionname>()

DFM scripts are not expected to change during the runtime of the Orchestration Server and so it is expected that if they are changed externally, the Orchestration Server would have to be restarted.

Each configuration file could define zero or one <globalsessionscripts> element which contains one or more <script> elements.

<script> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string that is unique within the scope of the current DFM configuration file for the script. It should adhere to the JavaScript variable naming conventions.	This is the name of the file that contains the JavaScript functions.
ref	yes	string		Any valid string.	This specifies the URL of the script file to be used. It may be the local file location or HTTP based.

Sample Script File

This is a sample file called Script1.js:

exports.a = function () {
    return 1;};

exports.b = function () {
    return exports.a();};

exports.c = function ( i ) {
    return i+3;};

exports.d = function ( ) {
    return hiddenFunction();};

function hiddenFunction(){
    return 200;}

exports.magicNumber = 7;

Using the JavaScipt functions in a SCXML file

This is a sample of how to use the functions defined in Script1.js in a SCXML file:

<script>
    var A = _genesys.DFMv5.a();
    var B = _genesys.DFMv5.b();
    var C = _genesys.DFMv5.c( 5 );
    var D = _genesys.DFMv5.d();
    var hiddenFunction = _genesys.DFMv5.hiddenFunction();
    var magicNumber = _genesys.DFMv5.magicNumber ;
</script>

<state id="initial">
    <transition target="start_session">
        <log expr="'The value of A is = '+ A"/>
        <log expr="'The value of B is = '+ B"/>
        <log expr="'The value of C is = '+ C"/>
        <log expr="'The value of D is = '+ D"/>
        <log expr="'The value of hiddenFunction is = '+ hiddenFunction"/>
        <log expr="'The value of magicNumber  is = '+ magicNumber "/>
    </transition>
</state>

And this is the expected results in the ORS log:

METRIC <log sid='GEPFKUK5C16I5B59G7UB9RIHD0000001' expr='The value of A is = 1' label='' level='1' />
METRIC <log sid='GEPFKUK5C16I5B59G7UB9RIHD0000001' expr='The value of B is = 1' label='' level='1' />
METRIC <log sid='GEPFKUK5C16I5B59G7UB9RIHD0000001' expr='The value of C is = 8' label='' level='1' />
METRIC <log sid='GEPFKUK5C16I5B59G7UB9RIHD0000001' expr='The value of D is = 200' label='' level='1' />
METRIC <log sid='GEPFKUK5C16I5B59G7UB9RIHD0000001' expr='The value of hiddenFunction is = undefined' label='' level='1' />
METRIC <log sid='GEPFKUK5C16I5B59G7UB9RIHD0000001' expr='The value of magicNumber is = 7' label='' level='1' />

Notes:

The JavaScript function _genesys.DFMv5.hiddenFunction() is not exposed to the session and therefore, cannot be called directly.  However, the hiddenFunction() was used in function d(), and therefore, could be accessed by calling _genesys.DFMv5.d().

A limitation of this JavaScript function _genesys.DFMv5.hiddenFunction() is that it is not available to a recovered session. If you try to call _genesys.DFMv5.d() within a recovered session, you will get an error message saysing 'ReferenceError: hiddenFunction is not defined.'

You can declare constants like magicNumber within the script file.

Management Sessions (optional) - Since 8.1.2.29

This defines the management sessions which are to be started when the DFM is finished initializing.  Sessions can be either started globally within a cluster, or within the scope of a single ORS node. By distinguishing between local bound sessions and cluster wide sessions, the user can choose to either localize logic by using a node bound session, or globalize the session to allow all nodes access to the same information using a cluster mode.

Each configuration file could define zero or one <sessions> element which contains one or more <session> elements.

<session> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string that is unique across the current DFM instance.	This is the name of the session.  It is used to reference the session within the bounds of the DFM and is required to be unique for the DFM.
ref	yes	string		Any valid string.	This specifies the URL of the SCXML document used to start the session. The value is the local file location (ex "file://C:\file.scxml") or the web address where the file is stored (ex. "http://localhost:17080/file.scxml")
type	yes	string	node	node cluster	This is used to indicate if the session is to be created locally on the current node or globally within the cluster.
expose	no	string	false	true false	This is used to indicate if the session ID would be exposed within the ORS session or not. If expose = true, the session ID would be accessible through _genesys.<DFMNAME>.sessions.<SESSIONNAME>

Session Parameters (optional)

For each session type, it is possible to provide extra configuration options.  This is an optional field.  If used, the session type will have one <params> element which contains one or more <param> elements.

<param> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string this is unique across the current session.	This specifies the session parameter name.  This name should match the name defined within the SCXML documents <datamodel>.  If there is a match, then the value shall be set to that as passed in the evaluated expression.
expr	yes	string		Any valid string.	This specifies the session parameter value.

Session ID Naming Convention

Sessions that are to be defined by a DFM need to be identified by their session ID in a consistent manner when executing.  When actions are called with the ORS Web API, the URL should use this session ID. 

For local node bound sessions, the naming convention should be:

DFM_<CLUSTERNAME>_<DFMNAME>_<SESSIONNAME>_<NODEID>

For clustered sessions, the naming convention should be:

DFM_<CLUSTERNAME>_<DFMNAME>_<SESSIONNAME>

Example

For example, if the local node session ID is DFM_CLUSTER1_rmServices_DNISAlloc_150, the URL to invoke the reserve action is:

   http:://localhost:17011/scxml/sessions/DFM_CLUSTER1_rmServices_DNISAlloc_150/request/request.reserve

And if the clustered session ID is DFM_CLUSTER1_rmServices_DNISAlloc, the URL to invoke the reserve action is:

   http:://localhost:17011/scxml/sessions/DFM_CLUSTER1_rmServices_DNISAlloc/request/request.reserve

Referencing DFM sessions

Sessions may be referenced anywhere within the DFM configuration. As such, it should be possible to refer to a fully qualified session ID by simply referring to the implicit DFM session name created. This then allows the session to be used to provide services to actions that are invoked using the existing ORS Web API's to send events.

DFM management sessions are referred as follows:

${dfmsession.<name>}

Example

For example, if the DNISAlloc was defined in the configuration as one of the DFM management sessions, this session can be referenced later in the configuration file as follows:

   <param name='url' expr='/scxml/session/${dfmsession.DNISAlloc}/request'/>

Session Restart with Persistence

DFM management sessions that are started using SCXML documents with persistence turned on will have the full persistence capabilities which are supported by ORS.  This means that the user may define node bound sessions or cluster sessions as requiring persistence.  When persistence is used, subsequent restarts of a node may not infer a new net state of an SCXML session, but will result in the last known state being resumed.

The following table outlines the expected behaviour:

Session Type	Pre Condition	Post Condidtion
Node	Not started or presisted	Session is started locally on the node and any data required to be passed to the session is passed.
Node	Persisted, not active	The session will be claimed by the current node and started without knowledge of the last known state.
Node	Active on antoher node	The node will not currently win the claim for this actively running session.  For a node session that has swapped nodes, this will be approached in a subsequent phase.  This is not a desirable scenario.
Cluster	Not started or presisted	The cluster session shall be started on exactly one node within the cluster.  The first node to claim this session shall be allowed to own the session.  The session shall be provided the start up parameters as defined within the DFM session.
Cluster	Persisted, not active	The session will be claimed by the current node, however, it is not expected that any data will be passed to the session.  The session shall just become active on the node that first claims the session.
Cluster	Active on antoher node	The session will not be claimed and no duplicate session shall be created, which is the desired behaviour.

It is recommended that DFM sessions not utilize the persistence mechanisms within ORS at the moment unless the desired restart behaviour is adquate. 

It is also recommended that node sessions are used specifically by the local actions only and that there should not be any cross node communication initiated from an action to a particular node session.

Protocols

This defines the protocol types which can be used in the current DFM for connecting to external servers. Each configuration file must have one <protocols> element which contains one or more <protocol> elements.

<protocol> Attributes

Name	Required	Type	Default Value	Valid Values	Description
type	yes	string	http	http https	This specifies the protocol type (i.e. connection protocol).

Protocol Parameters (optional)

For each protocol type, it is possible to provide extra configuration options.  This is an optional field.  If used, the protocol type will have one <params> element which contains one or more <param> elements.

<param> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string this is unique across the current protocol.	This specifies the protocol parameter name.
expr	yes	string		Any valid string.	This specifies the protocol parameter value.

Global Events (optional)

For each protocol type, it is possible to define global events which apply to every action of this protocol type for the current DFM instance.  This is an optional field.  If used, the protocol type will have one <globalevents> element which contains one or more <event> elements.  The <event> element describes events to be pushed by the current DFM instance to the strategy.

Although this field is optional, event mapping for "error" is required when another connection server is to be used while operating in primary-backup or round-robin selection mode.  Please click here for more details.

<event> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string this is unique across the current protocol.	This specifies the event name.
mapping	yes	string		Any valid string. For HTTP/HTTPS, comma-separated non-negative integers and/or dash-separated intervals between two non-negative integers should be used.	This protocol-specific attribute describes how some external service (request or response) should be translated into the native SCXML event. When using the HTTP/HTTPS transport, the external service(request or response) is the HTTP/HTTPS status code.

Example

For example, if the "error" event was defined as follows in the configuration file:

<globalevents>
   <event name='error' mapping='404, 500-505'/>
</globalevents>

The error event will be posted when the HTTP response status code is either 404, 500, 501, 502, 503, 504, or 505.

Connections

This defines which external servers will be used in the current DFM, and how the DFM will connect to those servers. Each configuration file must have one <connections> element which contains one or more <connection> elements.

<connection> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string that is unique across the current DFM instance.	This specifies the connection name.
type	yes	string		Any value defined as a protocol.	This references the protocol object to be used by this connection.
selectionmode	no	string	simple	simple primary-backup round-robin	This specifies the selection mode.

Connection Server Selection

A connection is made between a DFM action and an external server when an action is called within a DFM.  The connection server to be used is based on the list of servers defined in the configuration fine and is determined by the selection mode chosen.

First connection:  refers to the connection made when the first action within the DFM is called for a particular session.

Subsequent connections:  refers to the connections used for actions of the same type within the same session. 

Session affinity:  the act of using the same connection server for all actions called by the DFM within the same session.  Affinity is established when the first action is completed for a particular session. When the first action is completed, and the response from the request has been mapped to the done event, the connection server used is marked as the affinity server and all subsequent actions within the same session will use that affinity server. In the case where an action tried using all connection servers defined in the configuration file, and got the response from the request that has been mapped to the error event, an error is returned. Also, all future requests using this action will get an error without trying to connect to a connection server. In the situation where multiple actions are made concurrently, and affinity has not been established, the first request received by ORS will attempt to establish the affinity server and all other requests will get the affinity pending event until the first request is complete.

Selection Mode	First Connection	Subsequent Connections Without Session Affinity	Subsequent Connections With Session Affinity
simple	The DFM uses the first server for this particular connection type.  It is possible to define more than one server in the configuration file.  However, only the first server will be used and all others will be disregarded.	Same as first connection.	Same as first connection. If the first action failed to establish the affinity server, all subsequent actions will not be executed.
primary-backup	The DFM will try to connect to the first/primary server, and proceeds to the second/backup server if the connection breaks or fails. It is possible to define more than two servers in the configuration file.  However, only the first server will be used in the first attempt, and the second server used if the first connection fails*.	Subsequent connections will try to connect to the first/primary server, and proceeds to the second/backup server if the connection breaks or fails*.	All subsequent connections will be made to the same server as that used in the first connection, regardless of whether that server is the first/primary server or the second/backup server. If the first action failed to establish the affinity server, all subsequent actions will not be executed.
round-robin	The DFM will try to connect to the next server defined in the configuration file for this connection type.  For example, if there are 3 servers defined in the configuration file for a particular connection type: session 1 will connect to server 1 session 2 will connect to server 2 session 3 will connect to server 3 session 4 will connect to server 1 session 5 will connect to server 2 If a connection fails*, it tries the next server as follows: session 2 will connect to server 2, then 3, then 1. If all 3 attempts fail* (one time per server), no additional attempts are made and an error is returned.	The DFM will try to connect to the next server defined in the configuration file for this connection type.  For example, if there are 3 servers defined in the configuration file for a particular connection type: session 1 will connect to server 1 session 2 will connect to server 2 session 1 will connect to server 3 session 3 will connect to server 1 session 1 will connect to server 2 If a connection fails*, it tries the next server in the same manner as the first connection.	All subsequent connections will be made to the same server as that used in the first connection.  For example, if there are 3 servers defined in the configuration file for a particular connection type: session 1 will connect to server 1 session 2 will connect to server 2 session 1 will connect to server 1 session 3 will connect to server 3 session 1 will connect to server 1 If connecting to the same server as that used in the first connection fails, an error is returned and no attempts are made to any other servers. If the first action failed to establish the affinity server, all subsequent actions will not be executed.

NOTE: *For primary-backup and round-robin, a connection fails if the response from the request has been mapped to the error event.  For example, when making an HTTP request, if "400-404" has been mapped to "error" by either using global events, connection events, or action events, then a response code of "404" would result in the next connection server being used. However, a response code of "405" would not result in further attempts since it is not mapped as "error".

Affinity Broken Event

This event indicates that an error occurred while trying to connect to the same server as that used during the initial connection when session affinity is "true". The naming convention is as follows:

error.affinitybroken.<dfm_name>.<action_name>

Example

For example, if the "query_ixn_by_customer" action was called in the SCXML strategy using the "UCS_HTTP" transport with session affinity set to "true", and the session connected to server 1 in the first connection, all subsequent actions for this session will be made to server 1. If server 1 goes down after the initial connection, then the subsequent actions for this session will fail. The following event will be sent:

ors:+OrsEvent[0x04e14030]:name=error.affinitybroken.context_services.query_ixn_by_customer

Servers

A server refers to either a standalone server, or a collection of servers.  For a collection of servers, the DFM will connect to a single master node, or a load balancer if there is one.  Each <connection> element must have one <servers> element, and within the <servers> element, you must specify one or more <server> elements with the following attributes:

<server> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string this is unique across the current connection.	This specifies the server name.
host	yes	string		Any valid host server.	This specifies the server host name.
port	yes	number		Any valid port number.	This specifies the server port number.

Server Parameters (optional)

For each server, it is possible to provide extra configuration options by specifying one or more <param> elements.

<param> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string this is unique across the current server connection.	This specifies the server connection parameter name.
expr	yes	string		Any valid string.	This specifies the server connection parameter value.

Connection Events (optional)

It is possible to define connection specific events to be published by the DFM to the SCXML strategy as a response to some request sent by the strategy. This can be done by using the <events> element and specifying one or more <event> elements for responses. The event may be a new response, or may be overriding a global event using the same name.  This event may also be overwritten later on by an action event.

<event> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		A valid string for a new event name, or an existing global event name.	This specifies the event name.
mapping	yes	string		A valid string for a new event name, or an existing global event name. For HTTP/HTTPS, comma-separated non-negative integers and/or dash-separated intervals between two non-negative integers should be used.	This connection-specific attribute describes how some external service (request or response) should be translated into the native SCXML event. When using the HTTP/HTTPS transport, the external service(request or response) is the HTTP/HTTPS status code.

Events will be described in more details in the action events section.

Transports

This provides details about each particular type of transport that can be used by the current DFM. Each configuration file must have one <transports> element which contains one or more <transport> elements.

<transport> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string that is unique across the current DFM instance.	This specifies the transport name.
conntype	yes	string		Any value defined as a connection.	This references the connection object to be used by this transport.

Transport Parameters (optional)

For each transport, it is possible to provide extra configuration options by specifying one or more <param> elements as children of <transport>.

<param> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string this is unique across the current transport object.	This specifies the transport parameter name.
expr	yes	string		Any valid string.	This specifies the transport parameter value.

HTTP/HTTPS Transport Parameters (optional)

There are three HTTP-specific parameters that are required for HTTP requests.  Although they are required for ORS to make a HTTP request, these parameters are not mandatory in your configuration file. The method and enctype parameters have default values that will be used if no value is defined in the configuration file. However, you can override these default parameters at the transport-level described here, or at the action-level (described in the Action Overrides section). As for the url, a base URL " http://<host>:<port>" is automatically generated and any values you define for this parameter will be added to the end of the base URL.

<param> Attributes

Name	Required	Type	Default Value	Valid Values	Description
method	no	string	GET	GET POST PUT DELETE	This specifies the HTTP method to be used to send the HTTP request.
enctype	no	string	application/x-www-form-urlencoded	application/x-www-form-urlencoded application/json text/xml	This specifies the type of encoding to be used for the content of the HTTP request.
url	no	string	empty	Any valid string.	This specifies the URL of the remote web-service. The value specified here is added to the end of the base URL  "http://<host>:<port>".

Examples

For this example, the fetch method is HTTP PUT, the encoding type is url encoded, and the url is "http://ca-to-ferb:80/interactions".

<transports>
  <transport name='UCS_HTTP_PUT' conntype='UCS_HTTP_primary_backup'>
    <param name='method' expr='PUT' />
    <param name='url' expr='/interactions' /> 
  </transport>
</transports>

For this example, the fetch method is HTTP POST, the encoding type is JSON, and the url is "http://ca-to-ferb:80/profiles".

<transports>
  <transport name='UCS_HTTP_POST' conntype='UCS_HTTP_round_robin'>
    <param name='method' expr='POST' />
    <param name='enctype' expr='application/json' />
    <param name='url' expr='/profiles'/>
  </transport>
</transports>

Actions

Each action defined in the DFM is implemented as an extension action that can be used within a SCXML strategy. Each configuration file must have one <actions> element which contains one or more <action> elements.

<action> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid string that is unique across the current DFM instance.	This specifies the action name.
transport	yes	string		Any value defined as a transport.	This references the transport object to be used by this action.
sessionaffinity	no	boolean	false	true false	This specifies whether or not to use session affinity for this action. A description of session affinity can be found here.

Action Attributes (optional)

For each action, it is possible to provide extra attributes by specifying one <attributes> element, which contains one or more <attribute> elements

<attribute> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		If alias is defined for this attribute, the name can be one that has already been used as another attribute's name. It cannot be the same as any other attribute's alias. If alias is not defined for this attribute, the name must be unique against all other attribute's alias (if defined), otherwise, their name. The scope of this uniqueness is within the current action.	This specifies the action name which is used in SCXML strategies. By default, the requestid attribute will always be added automatically to the attributes list and therefore, the name requestid is reserved and cannot be used.
alias	no	string		Value is only valid when mapping is defined for this attribute. The value must be unique against all other attribute's alias (if defined), otherwise, their name. The scope of this uniqueness is within the current action.	This is a shorthand for the attribute name. If the alias is specified for this attribute, it will be used in place of the attribute name within the SCXML strategy. It is also used for internal references as overrides. For example, suppose we have the following in the configuration file:
type	yes	string		String Number Boolean Expression	This specifies the action attribute type.
mapping	no	string		For HTTP/HTTPS requests: parameter content header	It describes the way this attribute will send requests to an external server. By default, this attribute is not included in the request. For HTTP/HTTPS requests: If  mapping = 'parameter', this attribute will be mapped into the request URL for GET and DELETE and mapped into the request body for POST and PUT.  It uses the default application/x-www-form-urlencoded encoding, unless explicitly defined using the enctype transport parameter.  It is prohibited to have one attribute with mapping = 'parameter' and one attribute with mapping = 'content' within one action. If  mapping = 'content', this attribute will be mapped directly into the request body using the default application/json encoding, unless explicitly defined using the enctype transport parameter.  It is prohibited to have more than one attribute with  mapping = 'content'within one action. If  mapping = 'header', this attribute will be mapped as a custom header along with the standard HTTP headers to be sent with the request.
optional	no	boolean	false	true false	It indicates whether this attribute is required.
default	no	string		Value is only valid when optional = true for this attribute. The value can be any valid string.	It sets some default value for this attribute to be used when the attribute is not defined in the SCXML strategy.

Action Overrides (optional)

For each action, it is possible to override or add additional transport parameters to be linked to the current action.  This can be done by using the <overrides> element and specifying the parameter inside the <param> element.

<param> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		Any valid transport parameter name. It can be a previously defined parameter name, or a new transport parameter name.	This specifies the transport parameter name. If the name already exists in the transport object being used in this action, no modification is done to the name. If the name is new, then this name is added to the list of transport parameter names.
expr	yes	string		Any valid transport parameter value.	This specifies the transport parameter value. If the parameter name already exists in the transport object being used in this action, the value will be replaced by the value defined here. It is possible to use an internal reference here to any action attribute value defined within the current action.

Internal References

For each parameter, it is possible to reference any action attribute value defined within the current action.  The following format should be used:

${<attribute_name>}

where

<attribute_name> is the value of the name of the corresponding <attribute> element.

Example

Configuration File:

<action name='query_ixn_by_customer'  transport='UCS_HTTP'>
  <overrrides>
    <param name='method' expr='${method1}' />
    <param name='enctype' expr='application/x-www-form-urlencoded' />
    <param name='url' expr='interactions/${cid}' />
  </overrides>
  <attributes>
    <attribute name='method1' type='String' /> 
    <attribute name='customer_id'  alias='cid' type='String' />
  </attributes>
  <events>
    <event name='done' mapping='200,405' /> 
    <event name='error' mapping='404' />
    <event name='redirect' mapping='300-308' />
  </events>
</action>

SCXML Strategy:

<context_services:query_ixn_by_customer  method1="'GET'" cid="'A12345'" />

Action Events (optional)

It is possible to define action specific events to be published by the DFM to the SCXML strategy as a response to some request sent by the strategy. This can be done by using the <events> element and specifying one or more <event> elements for responses. The event may be a new response, or may be overriding a global event or connection event by using the same name.

<event> Attributes

Name	Required	Type	Default Value	Valid Values	Description
name	yes	string		A valid string for a new event name, or an existing global event or connection event name.	This specifies the event name.
mapping	yes	string		A valid string for a new event name, or an existing global event or connection event name. For HTTP/HTTPS, comma-separated non-negative integers and/or dash-separated intervals between two non-negative integers should be used.	This action-specific attribute describes how some external service (request or response) should be translated into the native SCXML event. When using the HTTP/HTTPS transport, the external service(request or response) is the HTTP/HTTPS status code.

Event List

All events are named using the following convention:

<dfm_name>.<action_name>.<event_name>

where

• <dfm_name> is the value of the name attribute of the <dfm> element
• <action_name> is the value of the name attribute of the <action> element
• <event_name> is the value of the name attribute of the <event> element

External Event Response Attributes

Name	Type	Description
requestid	string	This identifies the ID associated with the request.
eventid	string	This identifies the ID of the event (e.g. HTTP status code).

Done Event

This event indicates that the corresponding request has been completed successfully. It follows the same naming convention as global and action-specific events.

<dfm_name>.<action_name>.done

Done Event Attributes

Name	Type	Description
requestid	string	This identifies the ID associated with the request.
eventid	string	This identifies the ID of the event (e.g. HTTP status code).

Error Event

This event indicates that an error occurred while trying to perform the corresponding external request. This event is required when another connection server is to be used when operating in primary-backup or round-robin selection mode. Please click here for more details.

The naming convention is as follows:

error.<dfm_name>.<action_name>

Error Event Attributes

Name	Type	Description
requestid	string	This identifies the ID associated with the request.
eventid	string	This identifies the ID of the event (e.g. HTTP status code).
error	number	This identifies the type of error that occurred.  It usually represents the protocol-specific (e.g. HTTP) error that occurred during the request.
description	string	This gives a detailed description of the error (e.g. "HTTP 404 Not Found").

Examples

Using the action query_ixn_by_customer, if you get the response code 308, then the following event is generated:

context_services.query_ixn_by_customer.redirect

Using the action create_customer_profile, if you get the response code 204, then the following event is generated:

context_services.create_customer_profile.no_content

Using the action update_customer_profile, if you get the response code 204, then the following event is generated:

context_services.update_customer_profile.done

Using the action update_customer_profile, if you get the response code 405, then the following event is generated:

error.context_services.update_customer_profile

Specifying a Configuration File

1. In Configuration Manager, open the properties of the Orchestration Server Application object.
2. On the Options tab, click the Create New Section / Option icon to open theAdd Section dialog.  Name the section dfm.
3. Within the dfm section, click the Create New Section / Option icon to open the Edit Option dialog. For the Option Name, enter the name of your DFM instance (ex. context_services) or the name of the folder containing the configuration files.  For the Option Value, enter the path to the corresponding DFM configuration file (ex. file://C:\ORS\DFM\CfgFiles\cfg_contextServices.txt), or the path to the corresponding folder where the DFM configuration files can be found (ex. file://C:\ORS\DFM\CfgFiles).
   Since 8.1.200.41, storing the config file on a web server is supported. (ex. http://138.120.72.26:17080/DFM/config/cfg_contextServices.txt)
   Note: when specifying the path of the folder, all files within the folder are read and parsed despite the file type.
4. Repeat step 3 for each DFM configuration file / folder that you want to register.
5. Repeat steps 1 - 4 for each node of the ORS cluster. 

Note:  Any changes to the DFM Configuration Files will be applied as soon as the node starts up.  In order to propagate these changes to the entire cluster, it is necessary to restart them.  However, it is not required to shutdown all cluster nodes at once - a rolling start is acceptable.

Writing a SCXML Strategy

Here is a simple example of a SCXML strategy using the context_services DFM described above:

<scxml version="1.0" xmlns="http://www.w3.org/2005/07/scxml" 
	xmlns:context_services="www.genesyslab.com/modules/dfm/context_services/v1" 
        initial="initial">

  <datamodel>
    <data ID="RequestID" expr="''"/>
  </datamodel>
  
  <state id="initial">
    <transition target="query"/>
  </state>
  
  <state id="query">
    <onentry>   
	<context_services:query_ixn_by_customer requestid="_data.RequestID" method1="'GET'" enctype1="'application/x-www-form-urlencoded'" timeout1="25"  cid="'A12345'" />
    </onentry>
    <transition  event="context_services.query_ixn_by_customer.done"  target="create" />
  </state>

  <state id="create">
    <onentry>   
	<script>
		var strName = "Gold";
        </script>
		<context_services:create_customer_profile requestid="_data.RequestID"  profile="strName" />
	</onentry>
    <transition event="context_services.create_customer_profile.done" target="update" />
  </state>  

  <state id="update">
    <onentry>   
	<script>
		var strName = "Silver";
        </script>
		<context_services:update_customer_profile requestid="_data.RequestID" customer_id="'A12345'" profile="strName" />
	</onentry>
    <transition event="error.context_services.update_customer_profile" target="exit" />
  </state>
  
  <final id="exit"/>
  <final id="error"/>

</scxml>

XSD Validation Schema

Below is an sample XSL document for the transformation of the configuration file from XML to XSD.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> 
  <xsl:output version="1.0" indent="yes" encoding="UTF-8" method="xml"/> 
  <xsl:template match="/"> 
    <xsl:variable name="dfmname"> 
      <xsl:value-of select="dfm/@name"/> 
    </xsl:variable> 
    <xsl:variable name="dfmNameSpace"> 
      <xsl:value-of select="dfm/@namespace"/> 
    </xsl:variable> 
    <xsl:variable name="newline">
      <xsl:text> </xsl:text>
    </xsl:variable> 
    <xsl:variable name="documentation"> 
      This is the XML Schema for the 
      <xsl:copy-of select="$dfmname"/> 
      Module Consisting of the following Actions 
      <xsl:for-each select="dfm/actions/action"> 
        <xsl:value-of select="@name"/> 
        <xsl:text disable-output-escaping="yes">,</xsl:text> 
      </xsl:for-each> 
      The core module defines these elements and their attributes. 
    </xsl:variable> 
    <xsl:text disable-output-escaping="yes"> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:scxml="http://www.w3.org/2005/07/scxml" xmlns=" </xsl:text>
    <xsl:copy-of select="$dfmNameSpace"/> 
    <xsl:text disable-output-escaping="yes"> " targetNamespace=" </xsl:text>
    <xsl:copy-of select="$dfmNameSpace"/>
    <xsl:text disable-output-escaping="yes"> " elementFormDefault="qualified" > </xsl:text> 
    <xsl:text disable-output-escaping="yes"> <xsd:annotation> <xsd:documentation> </xsl:text> 
    <xsl:copy-of select="$documentation"/> 
    <xsl:text disable-output-escaping="yes"> 
      </xsd:documentation> </xsd:annotation> <xsd:import namespace="http://www.w3.org/2005/07/scxml" schemaLocation="scxml-profile-genesys.xsd"> 
      <xsd:annotation> <xsd:documentation> This is importing the Genesys SCXML extensions of SCXML because we use datatypes and elements in this FM. 
      </xsd:documentation> </xsd:annotation> </xsd:import> <!-- core executable content model --> <xsd:group name=" </xsl:text>
    <xsl:copy-of select="$dfmname"/>
    <xsl:text disable-output-escaping="yes">"> <xsd:choice> </xsl:text> 
    <xsl:for-each select="dfm/actions/action"> 
      <xsl:text disable-output-escaping="yes"> <xsd:element ref="</xsl:text><xsl:value-of select="@name"/><xsl:text disable-output-escaping="yes">"/> </xsl:text> 
    </xsl:for-each> 
    <xsl:text disable-output-escaping="yes"> </xsd:choice> </xsd:group> </xsl:text> 
    <xsl:for-each select="dfm/actions/action"> 
      <xsl:text disable-output-escaping="yes"> <xsd:attributeGroup name="</xsl:text>
      <xsl:copy-of select="$dfmname"/>
      .
      <xsl:value-of select="@name"/>
      .attlist"
      <xsl:text disable-output-escaping="yes"> > <xsd:attribute name="requestid" type="scxml:ValueLang.datatype"/></xsl:text> 
      <xsl:for-each select="attributes/attribute"> 
        <xsl:variable name="datatype"> 
          <xsl:value-of select="@type"/> 
        </xsl:variable> 
        <xsl:choose>
          <xsl:when test="$datatype = 'String' "> 
            <xsl:text disable-output-escaping="yes"> <xsd:attribute name="</xsl:text>
            <xsl:value-of select="@name"/>
            "
            <xsl:text disable-output-escaping="yes"> type="scxml:ValueLang.datatype" /> <!-- Data Type=</xsl:text>
            <xsl:value-of select="@type"/>
            <xsl:text disable-output-escaping="yes">--></xsl:text> 
          </xsl:when> 
          <xsl:when test="$datatype = 'Expression' "> 
            <xsl:text disable-output-escaping="yes"> <xsd:attribute name="</xsl:text>
            <xsl:value-of select="@name"/>
            "
            <xsl:text disable-output-escaping="yes"> type="scxml:ValueLang.datatype" /> <!-- Data Type=</xsl:text>
            <xsl:value-of select="@type"/> 
            <xsl:text disable-output-escaping="yes">--></xsl:text> 
          </xsl:when> 
          <xsl:when test="$datatype = 'Number' "> 
            <xsl:text disable-output-escaping="yes"> <xsd:attribute name="</xsl:text>
            <xsl:value-of select="@name"/>
            "
            <xsl:text disable-output-escaping="yes"> type="scxml:ValueLang.datatype" /> <!-- Data Type=</xsl:text>
            <xsl:value-of select="@type"/>
            <xsl:text disable-output-escaping="yes">--></xsl:text> 
          </xsl:when> 
          <xsl:when test="$datatype = 'Boolean' "> 
            <xsl:text disable-output-escaping="yes"> <xsd:attribute name="</xsl:text>
            <xsl:value-of select="@name"/>
            "
            <xsl:text disable-output-escaping="yes"> type="scxml:CondLang.datatype" /> <!-- Data Type=</xsl:text>
            <xsl:value-of select="@type"/>
            <xsl:text disable-output-escaping="yes">--></xsl:text> 
          </xsl:when> 
          <xsl:otherwise> 
            <xsl:text disable-output-escaping="yes"> <xsd:attribute name="</xsl:text>
            <xsl:value-of select="@name"/>
            "
            <xsl:text disable-output-escaping="yes">/> <!-- Data Type=</xsl:text><xsl:value-of select="@type"/>
            <xsl:text disable-output-escaping="yes">--></xsl:text> 
          </xsl:otherwise> 
        </xsl:choose>       
      </xsl:for-each> 
      <xsl:text disable-output-escaping="yes"> </xsd:attributeGroup> </xsl:text> 
    </xsl:for-each> 
    <xsl:for-each select="dfm/actions/action"> 
      <xsl:text disable-output-escaping="yes"> <xsd:complexType name="</xsl:text>
      <xsl:copy-of select="$dfmname"/>
      .
      <xsl:value-of select="@name"/>
      .type"
      <xsl:text disable-output-escaping="yes">> <xsd:attributeGroup ref="</xsl:text>
      <xsl:copy-of select="$dfmname"/>
      .
      <xsl:value-of select="@name"/>
      .attlist"
      <xsl:text disable-output-escaping="yes">/> </xsd:complexType> </xsl:text> 
      <xsl:text disable-output-escaping="yes"> <xsd:element name="</xsl:text>
      <xsl:value-of select="@name"/>
      " type="
      <xsl:copy-of select="$dfmname"/>
      .
      <xsl:value-of select="@name"/>
      .type"
      <xsl:text disable-output-escaping="yes">/> 
      </xsl:text> 
    </xsl:for-each> 
    <xsl:text disable-output-escaping="yes"> 
      </xsd:schema> 
    </xsl:text> 
  </xsl:template> 
</xsl:stylesheet>

The XSD schema dictates what the XML configuration file must conform to. Below is a sample:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:scxml="http://www.w3.org/2005/07/scxml" xmlns=$$DFM_NAMESPACE$$ targetNamespace=$$DFM_NAMESPACE$$  elementFormDefault="qualified">
  <xsd:annotation>
    <xsd:documentation>
      This is the XML Schema for the $$DFMNAME$$ Module Consisting of the following Actions
      $$DFM_ACTIONS_LIST$$
      The core module defines these elements and their attributes.
    </xsd:documentation>
  </xsd:annotation>
  <xsd:import namespace="http://www.w3.org/2005/07/scxml" schemaLocation="scxml-profile-genesys.xsd">
    <xsd:annotation>
      <xsd:documentation>
        This is importing the Genesys SCXML extensions of SCXML because we use datatypes and elements in this FM.
      </xsd:documentation>
    </xsd:annotation>
  </xsd:import>
  <!-- core executable content model -->
  <xsd:group name="$$DFM_NAME$$.core.executablecontent">
    <xsd:choice>
      <!-- Generate each element for the DFM one item per action in the DFM <xsd:element ref="$$DFM_ACTION_NAME$$"/> -->
      $$DFM_ACTIONS_ELEMENT$$
    </xsd:choice>
  </xsd:group>
      
  $$DFM_ATTRIBUTE_GROUPS$$
  <!-- Generate the following snippet for each of the Actions containing the Action Attributes -->
  <xsd:attributeGroup name="$$DFM_NAME$$.$$DFM_ACTION_NAME$$.attlist">
    <xsd:attribute name="requestid" type="scxml:ValueLang.datatype"/>
    <!-- For each attribute in the given Action generate its attribute definition -->
    $$DFM_ACTION_ATTRIBUTE$$            
  </xsd:attributeGroup>
      
  $$DFM_ACTION_TYPES$$
  <!-- For each Action generate the following -->
  <xsd:complexType name="$$DFM_NAME$$.$$DFM_ACTION_NAME$$.type">
    <xsd:attributeGroup ref="$$DFM_NAME$$.$$DFM_ACTION_NAME$$.attlist"/>
  </xsd:complexType>
      
  $$DFM_ACTION_ELEMENTS$$
  <!-- For each action we need to generate the following -->
  <xsd:element name="$$DFM_ACTION_NAME$$" type="$$DFM_NAME$$.$$DFM_ACTION_NAME$$.type"/>
      
</xsd:schema> 

Future Considerations

The DFM currently only supports HTTP and HTTPS connection types but will expand to include others in the future. In order to support other connection types, additional changes will have to be made to the event handling of responses.

Samples

DFM for ORS

It is possible to use the DFM to simplify Session FM action calls to external web services. Click here for details.

Reverse geocoding

Reverse geocoding is ability to determine a readable address from a given latitude and longitude. The result that is returned include information such as street addresses, places, neighbourhoods, county, state, and country. When given a latitude and longitude, the geocoder will perform a reverse lookup and return the closest addressable location based on interpolation from a reference dataset.

Reverse geocoding services are provided through APIs and other web services. Here are two examples:

1. Yahoo! PlaceFinder
2. GeoNames

DFM for Genesys Services Gateway

The DFM can be used to make calls to Genesys Services Gateway. Here is an example of how to use the DFM:

1. DFM for GMS based Services
2. DFM for GSG Storage
3. DFM for GSG Notification