Section I – SCXML > SCXML Extensions > Action Elements Bottom of Page
| Genesys 8.0 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.

##### 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.
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.

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>

##### Children

- `<param>` Occurs 0 to N. See SCXML `<param>` for details. This element is mutually exclusive with the `<content>` element. These parameters will be submitted differently, depending on the type of message used:

- HTTP GET/DELETE Message — The `<param>` elements yield a URL parameter list (name1=value1&name2=value2...) at the end of the path element. Note that if the srcexpr attribute evaluates to a URL with URL parameters, the `<param>` element parameters will be concatenated to the end of the URL component. If the `<param>` element value is a complex object, the value is the result of evaluating the ECMAScript toString() function of that object, which is usually the string "[object object]". As a result, instead of submitting objects directly, the application developer must explicitly submit the properties of an object, for example, "_genesys.ixn.interactions[0].g_uid". The following is the mapping of the `<param>` element attributes to the URL parameter list format:

- name — The "name" attribute of the `<param>` element will be submitted with the given parameter value as its key.
- value — The current value associated with this `<param>` element "expr" attribute:

- Simple types (string, integer, boolean, or decimal) will be converted into strings.
- ECMAScript objects will be converted into the string "[object object]". Complex objects should not be used.

- HTTP POST/PUT Message — The `<param>` elements yield different formats depending on the `<fetch>` enctype attribute value. Regardless, the results will be put into the body element of the POST/PUT message:

- application/x-www-form-urlcoded — The `<param>` elements for this encoding format will be transformed into a URL parameter list (name1=value1&name2=value2...) which will be inserted into the body element of the message. If the `<param>` element value is a complex object, the value is the result of evaluating the ECMAScript toString() function of that object, which is usually the string "[object object]". As a result, instead of submitting objects directly, the application developer must explicitly submit the properties of an object, for example, "_genesys.ixn.interactions[0].g_uid". The following is the mapping of the `<param>` element attributes to the URL parameter list format:

- name — The "name" attribute of the `<param>` element will be submitted with the given parameter value as its key.
- value — The current value associated with this `<param>` element "expr" attribute:

- Simple types (string, integer, boolean, or decimal) will be converted into strings.
- ECMAScript objects will be converted into the string "[object object]". Complex objects should not be used.

- application/json — The `<param>` elements for this encoding format will be a JSON-formatted string which will be inserted into the body element of the message. Each `<param>` element will be a top-level attribute in the format. For example, `<param name="a" expr="value1"/>` `<param name="b" expr="complexb"/>` `<!- complexb has three properties e,f,g ->` will result in the following JSON-formatted string — {"a":value1, "b":{"e":88, "f":"john", "g":22}}.

- ESP Message — The `<param>` elements will put in the Interaction Server TKVList format. The `<fetch>` enctype attribute value is ignored.

- `<content>` Occurs 0 to 1. See SCXML `<content>` for details. This element is mutually exclusive with the `<param>` element. The content defined in this element will match the value of the `<fetch>` element enctype attribute:

- application/x-www-form-urlencoded — The _expr attribute cannot be used and the content of this element will be sent as is.
- application/json — The _expr attribute must be specified and must evaluate to an ECMAScript object. The object will be sent as is.

##### Events

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

- session.fetch.done
- error.session.fetch

##### 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:

- Specify a value of 'esp" for the method attribute.
- Construct the gesp URI with the following format for the srcexpr attribute:

`gesp:[<applname>\]|[<type>\]<service>\[method>]`

The following are the meanings of the different elements of the format:

- "applname" is the 3rd party application that is to be used to process this request.
- "type" is the 3rd party application type that is to be used to process this request. (optional)
- "service" is the name of the service with which this request is associated.
- "method" is the specific function to be performed by the 3rd party application. (optional)

For example: `http://www.ixnserver1.com\Interaction\SubmitNew`

- The only way to pass request parameters and interaction user data on an ESP-based `<fetch>` action is with the `<content>` element. You use the _expr attribute with an ECMAScript object which contains properties called "params" and "udata". The one with the name "udata" will be an ECMAScript object which contains the user-data parameters that you want to pass with the action. The other properties in the main ECMAScript object will be request parameters. All of these parameters will be in the Interaction Server TKVList format.
- The `<fetch>` type, enctype, maxage, and maxstale attributes are ignored.
- The response data content will be return as a JSON string in the session.fetch.done event.

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

    <state id="get_business_data">
    	<datamodel>
    		<data id="reqid"/>
    		<data id="customervalue"/>
    	</datamodel>
    	<onentry>
    		<session:fetch requestid="_data.reqid" srcexpr="'gesp:CFGInteractionServer\Interaction\SubmitNew'" timeout="'30'">
    			<param name="TenantId" expr="'business1'"/>
    			<param name="MediaType" expr="'email'"/>
    			<param name="InteractionType" expr="'Outbound'"/>
    			<param name="InteractionSubtype" expr="'Reply'"/>
    		</session:fetch>
    	</onentry>
    	<transition event="session.fetch.done" target="statex">
    		<assign location="_interactionID" expr="_event.data.InteractionId"/>
    	</transition>
    	<transition event="error.session.fetch" target="statey"/>
    </state>

##### 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:

- Cannot establish a connection to a given URI
- Received a redirect response when making a request to a given URI
- Received an error response when making a request to a given URI
- No response received to the web service request during timeout

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:

- Temporary unavailability of the external service
- Unavailability of one of the nodes in the load-balanced external service

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

- `<param>` Occurs 0 to N — This contains data to be passed to the newly created session. See the Supported URI Schemes section for details. The use of this element will follow the same rules as the SCXML `<invoke>` element definition.

##### Events

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

- session.start.done
- error.session.start
- session.restored

#### <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:

- session.updatestart.done
- error.session.updatestart

#### <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:

- session.terminate.done
- error.session.terminate

#### <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:

- session.cancel.done
- error.session.cancel

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