Section I – SCXML > SCXML Extensions > Action Elements         Bottom of Page
Genesys 8.1
SCXML Technical Reference
< Parameter Elements            Events >

Action Elements

This covers action elements that are related to SCXML sessions, but are Genesys-specific. The namespace for these session-related actions is www.genesyslab.com/modules/session .

<fetch>

This action element fetches business content or data from an application server. The content could be generated by actual "business logic" running on the application server or it could just be a static content file on the application server, which could be updated (even manually) as required to allow things to be dynamic. The business content and associated logic itself will be created based on the programming technology of the application server it is going to run on. So the application server–specific development tools will be used to create this content and associated logic. This element is used within executable content processing. This business content and associated logic will be deployed and executed on an application server. The orchestration platform will support both .NET and J2EE application servers. The form of the returned business content will be JSON. There is no explicit context or state shared between the orchestration platform and the application server. All context or state that is needed by the business content and logic must be sent via this action element. If the needed context or state is not totally known at the time of invocation, then the developer can use the QuerySessionData web services within their business content–fetching logic to get the current orchestration logic context for the given orchestration logic session. This provides a more flexible and dynamic mechanism. It also allows the developer to optimize what context or state is needed for each business content–fetching logic "application".

This element may cover web service invocations in the future. In the meantime, the customer can use business content–fetching logic as a proxy for executing web services. This is also the way to invoke both database-related actions and rules system–related actions.

In addition, this action will support ESP-based requests from Genesys Interaction Server through the ESP (External Service Protocol) protocol.

For HTTP and HTTPS, basic authentication is supported if the username and or password is provided in the request. This will result in the request being submitted to the application server with the Authorization HTTP header element added to the message. In addition to this, for both HTTP and HTTPS additional headers may be provided by passing an ECMAScript object into the request.

Attribute Details

Name

Required

Type

Default Value

Valid Values

Description

requestid

false

location expression

none

Any valid location expression which represents a string field

This is the location for the request ID that is returned as part of this request. Any data model expression evaluating to a data model location. See SCXML Location Expressions for details. The location's value will be set to an internally generated unique string identifier to be associated with the action being sent. If this attribute is not specified, the event identifier is dropped. This identifier can be tested by the completion event handler to distinguish among several outstanding requests. If this attribute is not specified, the identifier can be acquired from the fetch completion event. Every request must receive a unique identifier, even if the request is for the same URL.

srcexpr

true

value expression

none

Any value expression that returns a valid URI of the following types:

  • HTTP
  • HTTPS
  • File
  • gesp

This value expression

will be evaluated at the time that the fetch element is executed to produce the URI to pass to the application server. The URI schemes supported are HTTP, HTTPS and File. Note: when the scheme is 'gesp', the URI will have a specific format. See the ESP based <fetch> actions section for details.

See SCXML Legal Data Values and Value Expressions for details.

type

false

value expression

application/json

application/xml,

application/json,

text/plain

This value expression returns a character string that specifies the type of the fetched content. Values defined by the specification are:

  • application/xml — This specifies that the document being fetched must be an XML document for a given namespace.
  • application/json — This specifies that the fetched content must be JSON format. This is the default.
  • text/plain — This specifies that the fetched content must be plain text in format.

If method attribute is "esp", this attribute is ignored.

The type attribute in the issued HTTP request will be passed to the application server as the Accept header.

See SCXML Legal Data Values and Value Expressions for details.

method

false

value expression

get

get

post

esp

put

delete

A value expression which returns a character string that indicates the HTTP method to use. See SCXML Legal Data Values and Value Expressions for details. Values defined by the specification are:

  • get — This indicates that the "GET" method must be used to fetch the URL.
  • post — This indicates that the "POST" method must be used while submitting the URL to the web server.
  • esp — This indicates that the ixn-server ESP protocol is to be used.
  • put — This indicates that the "PUT" method must be used while submitting the URL to the web server.
  • delete — This indicates that the "DELETE" method must be used while submitting the URL to the web server.

timeout

false

value expression

0

A value expression which returns an integer

A value expression which returns an integer that represents the number of seconds to wait. See SCXML Legal Data Values and Value Expressions for details. The integer returned must be interpreted as a time interval. This interval begins when <fetch> is executed. A failed and timed out fetch must return the error.session.fetch event.

maxage

false

value expression

 

A value expression which returns a valid time value for the HTTP 1.1 request RFC 2616

The integer returned must be interpreted as a time interval. This indicates that the logic is willing to use content whose age must be no greater than the specified time in seconds (compare with 'max-age' in HTTP 1.1 RFC 2616). The logic is not willing to use stale content, unless maxstale is also provided.

If method attribute is "esp", this attribute is ignored.

maxstale

false

value expression

 

A value expression which returns a valid time value for the HTTP 1.1 request RFC 2616

The integer in string form returned must be interpreted as a time interval. This indicates that the logic is willing to use content that has exceeded its expiration time (cf. 'max-age' in HTTP 1.1 RFC 2616). If maxstale is assigned a value, then the logic is willing to accept content that has exceeded its expiration time by no more than the specified number of seconds.

If method attribute is "esp", this attribute is ignored.

username

false

value expression

none

Any expression that results in a valid string value

This value expression returns a character string that represents the username to be used as apart of HTTP Basic Authentication as defined by HTTP 1.1 [See RFC 2616].

password

false

value expression

none

Any expression that results in a valid string value

This value expression returns a character string that represents the password to be used as apart of HTTP Basic Authentication as defined by HTTP 1.1 [See RFC 2616].

enctype

false

value expression

application/x-www-form-urlencoded

application/x-www-form-urlencoded,

application/json

This value expression returns a character string that specifies the type of encoding to be used for the content of the POST/PUT message. Values defined by the specification are:

  • application/x-www-form-urlencoded — This specifies that the message content must be encoded in URL encoded form. This is the default.
  • application/json — This specifies that the message content must be encoded in JSON format.

If method attribute is "esp", this attribute is ignored.

The content type returned by the application server response will be checked against the enctype attribute. If it is different, an error.session.fetch event will be raised — the exception is the text/plain value case, in which case any type of returned value is accepted.The returned body is provided "as-is" in the content of the session.fetch.done event. The application logic is supposed to use the JSON functions to convert it into appropriate values.

See SCXML Legal Data Values and Value Expressions for details.

gdelivery

false

value expression

false

A value expression which returns a boolean value (true or false)

A value expression which returns a boolean value that indicates whether the platform is to guarantee the execution of the <fetch> action. This does not guarantee that the action associated with the srcexpr value has been carried out successfully. It just guarantees that the HTTP request gets to the defined destination (srcexpr value) and that a response (positive or negative) is returned.

See SCXML Legal Data Values and Value Expressions for details.

gd_retries

false

value expression

0

A value expression which returns a valid integer

A value expression which returns an integer that indicates the number of times the platform should try to successfully deliver the associated HTTP request to the defined destination (srcexpr value). This attribute is ignored if the gdelivery attribute value is false.

If the gdelivery attribute value is true and the gd_retries value is 0, the platform will try to delivery the associated HTTP request indefinitely.

See SCXML Legal Data Values and Value Expressions for details.

gd_retry_interval

false

value expression

0

A value expression which returns an integer

A value expression which returns an integer that represents the number of seconds to wait. The integer returned must be interpreted as a time interval. This interval is the time to wait between retries. This interval begins after a failed retry.

This attribute is ignored if the gdelivery attribute value is false.

See SCXML Legal Data Values and Value Expressions for details.

headers

false

value expression

none

Any valid ECMAScriipt object

A value expression which returns an ECMAScript object. Each property name within the object will be interpreted as a separate HTTP header. Its value will be obtained using toString() and appended after the property name followed by a “:” character. No checking or validation will be performed on the properties and or values provided within the object. This will not override any headers automatically added by <fetch> such as Cache-Control and is provided as a means to provide the ability to add customer header information.

See SCXML Legal Data Values and Value Expressions for details.

The mapping of this action to the underlaying HTTP request and response is described in the Mapping of the SCXML and Functional Module Elements to the HTTP Messages section.

The following are examples of the <session:fetch> action:

<state id="get_business_data_using_param_child">
<datamodel>
	<data id="reqid"/>
	<data id="customervalue"/>
</datamodel>
<onentry>
	<session:fetch requestid="_data.reqid" srcexpr="'www.joes.com\getbusinessdata'" timeout="'30'">
		<param name="customerID" expr="_cv.customerid"/>
	</session:fetch>

</onentry>
<transition event="session.fetch.done" target="statex">
	<assign location="customervalue" expr="_event.data.cvalue"/>
</transition>
<transition event="error.session.fetch" target="statey"/>

</state>

<state id="get_business_data_using_content_child">
<datamodel>
	<data id="reqid"/>
	<data id="complextobject"/>
</datamodel>
<onentry>
	<session:fetch requestid="_data.reqid" srcexpr="'www.joes.com\getbusinessdata'" timeout="'30'">
		<content _expr="_data.complexobject"/>
	</session:fetch>

</onentry>
<transition event="session.fetch.done" target="statex">
	<assign location="customervalue" expr="_event.data.cvalue"/>
</transition>
<transition event="error.session.fetch" target="statey"/>
</state>

<state id="get_business_data_using_basic_auth_and_headers">
<datamodel>
	<data id="reqid"/>
	<data id="customervalue"/>
</datamodel>
<onentry>
	<script>
		var myheaders = new Objects();
		myheaders["If-Modified-Since"] = "Sat, 1 Jan 2011 20:00:00 GMT";
		myheaders["X-CUSTOM-HEADER"] = "Custom header information";
	</script>

	<session:fetch requestid="_data.reqid" srcexpr="'www.joes.com\getbusinessdata'" timeout="'30'" username="'bob'" password="'mysecret'" headers="myheaders" >
		<param name="customerID" expr="_cv.customerid"/>
	</session:fetch>

</onentry>
<transition event="session.fetch.done" target="statex">
	<assign location="customervalue" expr="_event.data.cvalue"/>
</transition>
<transition event="error.session.fetch" target="statey"/>

</state>
Children
Summary of URL and JSON encoding

The following table is a summary of the rules described above.

 

URL Encoded

JSON Encoded

<param>

<content>

<param>

<content>

GET, DELETE

Name and expression attributes of each <param> element (name and expr, correspondingly) will be evaluated, URL-encoded, and combined into a standard name-value sequence (n1=v1&n2=v2&...). Duplicate parameter names are acceptable.
The following rules will be used when URL-encoding the expression attribute:

  • String, number, true, false, and null – as usual.
  • Any ECMAScript object will be encoded to the following: %5Bobject%20Object%5D
  • Array will be encoded as a comma-separated string of values. For example, [1,2,A] will be encoded as the following: 1%2C2%2C%5Bobject%20Object%5D

Content of the <content> element will be URL-encoded without prior evaluation. This element cannot be used together with <param>.

Not supported.

Not supported.

POST, PUT

Name and expression attributes of each <param> element (name and expr, correspondingly) will be evaluated, combined into a single object and then converted into the JSON string. Duplicate parameter names are acceptable, however, remember that duplicate property names in JSON string will be eliminated during evaluation. For example, the following ECMAScript expression:
eval('({"p1":1,"p1":2})');
will return the following object:
{"p1": 2}

Expression attribute (_expr) of the <content> element will be evaluated and converted into the JSON string. This element cannot be used together with <param>.

Events

The following events can be generated as part of this action:

ESP-Based <fetch> Actions

For backwards compatibility purposes the platform and the <fetch> element will support the invocation of External Service Protocol (ESP) requests and responses. In order to use the <fetch> element for ESP-related requests, the developer needs to do the following:

The following is an example of the <session:fetch> action:

<state id="updateContact">
	<datamodel>
		<data id="reqid" />
	</datamodel>
	<onentry>
		<script>
			var updateContactRequestContent = {
				params: {
					UseDataFromParameters: false
				},
				udata: {
					TenantId: 101,
					ContactId: "GK4MW583K80DTE04",
					FirstName: "James",
					LastName: "Johnson"
				}
			};
		</script>
		<session:fetch method="'esp'" requestid="_data.reqid"
			srcexpr="'ContactServer_801_04\\CFGContactServer\\Contact\\Update'">
			<content _expr="updateContactRequestContent" />
	 </session:fetch>

	</onentry>
	<transition event="session.fetch.done" target="statex">
		<script>
			var eventDataObject = eval("(" + _event.data + ")");
		</script>
			<assign location="_interactionID" expr="eventDataObject.envelope.Parameters.InteractionId"/>
	</transition>
	<transition event="error.session.fetch" target="statey" />
</state>

For a successful ESP call the returned response will use the following conversion logic to determine how the JSON object is structured.

The following is an example of the above ESP-to-JSON conversion logic operating on the following ESP response.

06:22:54.082 'external_srvice_response' (501) message:
	attr_ref_id [int] = 294014
	attr_envelope [list, size (unpacked)=604] = 
		'Service' [str] = "Contact"
		'Method' [str] = "Identify"
		'Parameters' [list] = (size=228)
			'ContactCreated' [str] = "false"
			'ContactIdList' [str] = "0005Ua6CJC69002J"
			'ContactIdList' [str] = "0005Ua6CJC69002N"
			'ContactIdList' [str] = "0005Ub6CJC6H0001"
			'ContactIdList' [str] = "0005Ub6CJC6H0004"
			'ContactIdList' [str] = "0005Ub6CJC6H0007"
			'NumberOfContactsFound' [int] = 5

The following would be the JSON representation of the successful ESP call.

{
	"envelope": {
		"Service": "Contact",
		"Method": "Identify",
		"Parameters": {
			"ContactCreated": "false",
			"ContactIdList": [
				"0005Ua6CJC69002J", 
				"0005Ua6CJC69002N", 
				"0005Ub6CJC6H0001", 
				"0005Ub6CJC6H0004",
				"0005Ub6CJC6H0007"], 
			"NumberOfContactsFound": 5
		}
	}
}

For ESP calls that return user data in addition to an enevelope, the following would be expected to be represented.

{
	"envelope": {
		"Service": "Contact",
		"Method": "Identify",
		"Parameters": {
			"ContactCreated": "false",
			"ContactIdList": "0005Ub6CJC6H0001",
			"NumberOfContactsFound": 1
		}
	},
	"user_data": {
		"FirstName": "James",
		"ContactId": "0005Ub6CJC6H0001",
		"LastName": "Johnson"
	}
}
Guaranteed Delivery of the <fetch> Action

When a web service request is made to the external service using <fetch>, the orchestration platform guarantees delivery of such a request. That is, the orchestration platform handles situations in which normal web service requests cannot be fulfilled.

Here are some situations in which a web service request cannot be fulfilled:

To handle these situations, the orchestration platform would queue web service requests, and retry making the request within the configured timeout period. The orchestration platform would queue web service requests on the basis of their URIs.

Note that this functionality addresses both cases of:

Important Note: If the session exits a state that has an outstanding <fetch> action, then the outstanding <fetch> action will be terminated. Also if an invoked session with an outstanding <fetch> action terminates, then the outstanding <fetch> action will be terminated.

<start>

This starts an independent SCXML document and session and runs completely independently of the starting (that is, parent) session. If the starting session ends, the started session does not, and vice versa. Session content is not shared between the sessions. Any session or 3rd party application can terminate (for example, <terminate>) this started session, as long as they have the session ID. When this session terminates, a done event will be fired by the orchestration platform for all interested parties (other sessions, and so on). This action can also be used to restart a session with a new SCXML document (that is, if the sessionid attribute contains an existing sessionid).

Attribute Details

Name

Required

Type

Default Value

Valid Values

Description

sessionid

true

location expression

none

Any value location that represents a valid string field

This is the location for the session ID that is returned as part of this request. Any data model expression evaluating to a data model location. See SCXML Location Expressions for details. The location's value will be set to an internally generated unique string identifier to be associated with the newly created session. This ID is immediately populated by the platform and can be used on subsequent elements (<send>, for example).

If this attribute contains a session, then the existing session will be restarted with the new SCXML document.

src

true

value expression

none

Any value expression that returns a valid URI

This value expression returns a character string that represents the URI of the SCXML document. The URI schemes supported are HTTP, HTTPS and File. See SCXML Legal Data Values and Value Expressions for details.

idealtime

false

value expression

none

Any expression that results in a valid dateTime value

This value expression returns a dateTime value which will represent the date and time that this session is to be started. This value should be the time as returned by the ECMAScript Date(...).getTime() function, which is given in the number of milliseconds since 00:00:00 UTC on January 1, 1970. See SCXML Legal Data Values and Value Expressions for details.

prewindow

false

value expression

none

Any expression that results in a valid duration value

This value expression returns a duration value which will represent the time window prior to the ideal time for which the session could be started. For details on the duration type, see the duration datatype . See SCXML Legal Data Values and Value Expressions for details.

postwindow

false

value expression

none

Any expression that results in a valid duration value

This value expression returns a duration value which will represent the time window after the ideal time for which the session could be started. For details on the duration type, see the duration datatype . See SCXML Legal Data Values and Value Expressions for details.

delay

false

value expression

0

A value expression which returns an integer

A value expression which returns an integer which represents the number of seconds to wait. See SCXML Legal Data Values and Value Expressions for details. The integer returned must be interpreted as a time interval. This interval begins when <start> is executed. A failed and timed out start must return the error.session.start event.

The following is an example:

<state id="Starting_a_new_session">
	<datamodel>
		<data id="newsessid"/>
		<data id="newsession"/> 
	</datamodel>
	<onentry>
		<session:start src="www.genesyslab.com\session\orchapp1" sessionid=_data.newsessid/>
		<send event="start.event" target="_data.newsessid"/>
	</onentry>
	<transition event="session.start.done" target="statex"/>
	<transition event="error.session.start" target="statey"/>
</state>
Children
Events

The following events can be generated as part of this action:

<updatestart>

This action updates the starting time of the SCXML session. It can only be used after the session is started using the idealtime attribute and if the requested session has not been started yet.

Attribute Details

Name

Required

Type

Default Value

Valid Values

Description

sessionid

true

value expression

none

Any value expression which returns a valid string.

A value expression which returns the session ID to be updated. See SCXML Legal Data Values and Value Expressions for details.

idealtime

false

value expression

none

Any expression that results in a valid dateTime value

This value expression returns a dateTime value which will represent the updated date and time that this session is to be started. This value should be the time as returned by the ECMAScript Date(...).getTime() function, which is given in the number of milliseconds since 00:00:00 UTC on January 1, 1970. See SCXML Legal Data Values and Value Expressions for details.

prewindow

false

value expression

none

Any expression that results in a valid duration value

This value expression returns a duration value which will represent the updated time window prior to the ideal time for which the session could be started. For details on the duration type, see the duration datatype. See SCXML Legal Data Values and Value Expressions for details.

postwindow

false

value expression

none

Any expression that results in a valid duration value

This value expression returns a duration value which will represent the updated time window after the ideal time for which the session could be started. For details on the duration type, see the duration datatype . See SCXML Legal Data Values and Value Expressions for details.

delay

false

value expression

0

A value expression which returns an integer

A value expression which returns an integer which represents the number of seconds to wait. See SCXML Legal Data Values and Value Expressions for details. The integer returned must be interpreted as a time interval. This new interval begins when <updatestart> is executed. A failed and timed out start must return the error.session.updatestart event.

Children

None

Events

The following events can be generated as part of this action:

<terminate>

This action terminates an SCXML session from an unrelated SCXML session. As a result of termination, the orchestration platform sends the done event to the invoking SCXML session (if it is still running). It will also be used to cancel a scheduled session.

Attribute Details

Name

Required

Type

Default Value

Valid Values

Description

sessionid

true

value expression

none

Any value expression which returns a valid string.

A value expression which returns the session ID to be terminated. See SCXML Legal Data Values and Value Expressions for details.

Children

None

Events

The following events can be generated as part of this action:

<cancel>

This action terminates a pending fetch action request <session:fetch>. This is used to allow the application to ensure that any guaranteed delivery fetch requests are terminated. This action should be put in the <onexit> element where these types of fetch actions are invoked

Attribute Details

Name

Required

Type

Default Value

Valid Values

Description

requestid

true

value expression

none

Any valid value expression which returns a valid string.

This is the request ID of the outstanding <fetch>> action.

Children

None

Events

The following events can be generated as part of this action:




Section I – SCXML > SCXML Extensions > Action Elements         Top of Page
Genesys 8.1
SCXML Technical Reference
< Parameter Elements            Events >