Section I – SCXML > SCXML Extensions > SCXML Element Extensions         Bottom of Page
Genesys 8.1
SCXML Technical Reference
< Session Parameterization            SCXML Event Extensions >

SCXML Element Extensions

Our goal is to make the smallest possible changes to the SCXML elements and specification. If changes are needed, they will follow the following guidelines:

<scxml>

The following are the additional Genesys attributes for the <scxml> element

Attributes

Name

Required

Type

Default Value

Valid Values

Description

_type

false

string

combination

The following is the set of valid values:

  • routingstrategy
  • interactionprocess
  • serviceprocess
  • combination

This is set by the developer at the beginning of the SCXML document to define what type of orchestration logic has been defined. Composer will set this property based on the type of logic you are building. It is used for reporting purposes.

_persist

false

boolean

true

The following is the set of valid values:

  • true
  • false

This will allow the developer to suppress all persistence capabilities.

Persistence is not always desired, due to the associated performance overhead. For instance, current voice-related routing strategies normally run to completion in a reasonable amount of time, and in the event of a failure, restarting the routing strategy may not be problematic. Therefore, this attribute allows sessions to suppress all use of persistence, which prevents the orchestration platform from ever persisting the session. (Note that this does *not* preclude the orchestration platform from employing other techniques, such as hot standby servers, to achieve fault tolerance for these types of session.

<state>

The following are the additional Genesys attributes, children, and behavior for the <state> element.

Attributes

Name

Required

Type

Default Value

Valid Values

Description

_type

false

NMTOKEN

normal

The following is the set of valid values:

  • normal
  • queue

This will allow the developer to control how the platform is to handle this state. The following are the possible values

  • normal (default) — follow the SCXML spec.
  • queue — This indicates that the state processing is to be queued or throttled by the platform as well as explicitly exposed to outside components.

_persist

false

NMTOKEN

May

The following is the set of valid values:

  • no
  • may
  • must

Long-running sessions typically experience concentrated time windows in which active processing is performed, followed by a relatively long time window during which the system awaits follow-up by a customer or potentially by the agent. This attribute will be used to indicate to the orchestration platform whether a session can or must be persisted:

  • no — Used to indicate a state is transitional, or is not meaningful for recovery purposes over the last persisted state.

  • may — The orchestration platform may persist the session in this state at its discretion. This is the default value.

  • must — The orchestration platform must persist the session as part of entry processing of this state (before the <onentry> elements are executed). This is used to guarantee that the session can be recovered from this point in the event of failure (that is, the ability to reenter the session at this state).

_deactivate

false

string

No

The following is the set of current valid values:

  • now
  • no

This attribute will define whether the session that enters this state and is waiting for a transition should be immediately persisted, removed from platform memory, and marked as inactive. This attribute is valid only if the "_persist" attribute is set to "may" or "must", since only persistable sessions can be de-activated. This attribute is treated purely as a hint to the orchestration platform about how meaningful it is to persist the session.

Modularity/Subroutine Support

A way to accomplish a limited form of modularity with SCXML is to create a separate ECMAScript document for each reusable sub-state model module where the URI for the included ECMAScript document associated with the module is specified using the xinclude recommendation and the <include> element. See the <include> section for details.

Queue States

State elements in a document that have the "_type" attribute equal to "queue" will be controlled by the platform. A queue will be created for each unique state id and application name (_name). This means that all sessions going through that state may be queued to wait based on the maximum number of sessions (_max) that can be in this state at any given time. The application developer can define a default maximum number of sessions in the <state> element, but this value can be overridden by an administrator at provisioning time or during runtime. In addition to being queued, the session will assume the proper position in the queue based on ordering criteria (that is, the _order attribute) defined for the state. The application developer can define default ordering criteria in the <state> element, but this value can be overridden by an administrator at provisioning time or during runtime. This capability has been added to deal with conditions where the processing of a particular portion of an application needs be controlled across the associated sessions so that it does not overload the services being used (application servers, functional modules, etc). This is primarily used when processing non-voice–related interactions.

The following are some of the characteristics and limitations of this type of state:

Error Processing

Situations in which an ECMAScript engine encounters an error script processing will be terminated, the error will be logged, and the appropriate event will be raised to the application.

<log>

There are no new attributes for this element but there are some additional values for certain attributes:

<send>

There are no new attributes for this element, but there are some additional values for certain attributes:

Compared to the previous SCXML draft, the following attributes have been added or changed in the currently implemented SCXML standard:

<invoke>

Compared to the previous SCXML draft, the following attributes have been added or changed in the currently implemented SCXML standard:

In addition, the currently implemented SCXML standard assumes using done.invoke.invokeid as the event to raise on completion of an invoke action. The previous SCXML draft used invokingstate.done event instead.

Modularity or Subroutine Support

The <invoke> element can be used to accomplish modularity with SCXML. It is used to create an independent session that can communicate asynchronously with the invoking sessions, as described in Section 2.2. For complete details on how this will work see the following in the SCXML specification: <invoke> element.

In addition to what the SCXML specification defines, the following guidelines can be followed when developing an asynchronous subroutine with this functionality:

Children

The following are the changes to the children of the <invoke> element:

<raise>

The following are the Genesys differences for the <raise> element.

Children

<final>

The following are the Genesys differences for the <final> element.

Children

<data>

The following are the additional Genesys attributes for <data> element. They are strictly used to help define and administer the provisioning of this data from the appropriate source.

Attributes

Name

Required

Type

Default Value

Valid Values

Description

_type

false

NMTOKEN

data

The following is the set of valid values:

  • data
  • parameter

This allows the developer to identify the data elements that are to be parameters that the platform must obtain values for when the session is initiated.

_desc

false

string

none

Any valid string

This allows the developer to provide a description of the parameter that is to be supplied at session initiation.

_datatype

false

NMTOKEN

none

The following is the set of valid values:

  • boolean
  • string
  • binary
  • integer
  • float
  • object

This allows the developer to identify the data elements that are to be parameters that the platform must obtain values for when the session is initiated.

_min

false

integer

none

Any valid integer

This defines the minimum allowed value for data. This attribute is only valid for the following data types:

  • String — This is the minimum length of the string.
  • Binary — This is the minimum length of the binary data.
  • Integer — This is the minimum value.
  • Float — This is the minimum value.

_max

false

INTEGER

none

Any valid integer

This defines the maximum allowed value for data.

This attribute is only valid for the following data types:

  • String — This is the maximum length of the string.
  • Binary — This is the maximum length of the binary data.
  • Integer — This is the maximum value.
  • Float — This is the maximum value.

_enumvalues

false

string

none

Any valid string that following this pattern,

"value1string,value2string, ...,valueNstringform"

This defines the set of valid values for the data. This attribute is only valid for the following data types:

  • String — This is the set of valid string values for this data.
  • Integer — This is the set of valid integer values (in string form) for this data.
  • Float — This is the set of valid float number values (in string form) for this data.
src Attribute

The orchestration platform will support the following URI schemes for the src attribute:

For details on how these different schemes are used, see the Session Parameterization section.

The content retrieved from the URL location will be in text form. It can be plain text.

id Attribute

The value of this attribute must be a valid ECMAScript variable name. This means that variable semantics that include elements like "." (for example, foo.foo) and "-" (for example, foo-foo) are not allowed. The rule is that the variable name must be able to be processed on its own in an ECMAScript snippet. If not, then a TypeError event will be generated.

For example,

Valid element

<data id="foo" expr="value1"/>

Invalid element

<data id="foo.foo" expr="value2"/> <!--TypeError event generated ->

If you need to create complex objects you can always create them with the <script> element as a child of the <scxml> element with the src attribute where the src attribute value points to a valid JSON object with a mime type of application/json.

<parallel>

The following are the additional Genesys attributes, children and behavior for the <parallel> element.

xinclude <include>

The xinclude recommendation (http://www.w3.org/TR/xinclude/) will be used for inlining of ECMAScripts (<script>) and states (<state>). An application developer may specify scripts, states, and other content separately from the main SCXML document. The included document or fragment can be text or xml.

When using xinclude, the following are important considerations to keep in mind:

Xinclude can also be used to provide a subroutine-like capability within an SCXML application by using it like a macro facility. This replaces all <xi:include> elements with the referenced state content during the initial document fetch and load. Once the SCXML application is fully assembled, it is compiled and validated before sessions can be created based on this application.

In addition to the considerations above, the following guidelines must be followed when using xinclude as a macro style "subroutine":

The following are the additional Genesys attributes for the <include> element as well as existing attribute limitations.

Attributes

Name

Required

Type

Default Value

Valid Values

Description

accept

false

string

   

Not supported

accept-language

false

string

   

Not supported

encoding

false

string

   

Not supported

href

true

URL

none

 

The URI of the resource to include. It is supported as is.

parse

false

string

"xml"

"xml", "text"

See the following for details: http://www.w3.org/TR/xinclude/#include_element

resolveid

false

string

none

Any value string

In order to support subroutines and avoid issues with duplicate SCXML element IDs (for example, <state id=x>), this Genesys extension attribute must be used. If this attribute is specified, then ID modifications will occur. All the SCXML elements with an ID attribute (<state>, <parallel>, <final>, <history>, <send>, <invoke>, <cancel>, and <data>) in the included document will be prefixed by the value of this attribute, and a separating dot. In addition, the IDREF attributes in the included document (the initial attribute in the <state> element and the target and event attributes in the <transition> element) can also be modified as long as the following wildcard substitution key is specified in the value. Otherwise they will not be changed when included. The substitution key is the string "$$_MY_PREFIX_$$". If specified, it will be replaced by the value of this attribute for the included document.

IMPORTANT NOTE: Developers must ensure that each use of the 'resolveid' attribute value is unique across the chain of included documents.

xmlns

false

string

none

Any value string

Used to provide namespaces for the included document. This is necessary for fragments. If subroutines include subroutines, this attribute must be set to the appropriate namespace for the including element. For example, xmlns:xi="http://www.w3.org/2001/XInclude"

xpointer

false

string

none

 

When parse="xml", xpointer may be used to specify a particular element and its children to include. The value of xpointer must be a literal ID. The first node in the included document that matches that ID will be included. When xpointer is omitted, the entire resource is included. Note: XPath is not supported.

When resolveid is used, two additional items can be used to handle the prefix provided by this attribute:

Name

Valid locations

Description

$$_MY_PREFIX_$$

  • initial attribute of <state>
  • event and target attribute of <transition>

During document assembly, $$_MY_PREFIX_$$ will be replaced with the value of resolveid only in the defined locations. The engine does not perform global search and replace with this token.

_my_prefix

Any ECMAScript expression

During document assembly, <state>, <parallel>, and <final> will be given a _my_prefix attribute extension that contains the value of resolveid. This allows the prefix value to be used in ECMAScript expressions within these states.

The following example illustrates how xinclude can be used to compose several subroutine documents into the main application. The main application (complex_main.scxml) includes a subroutine (complex_sub) that is composed of two additional subroutines (compound_sub and simple_sub).

Main document/SCXML Application (complex_main.scxml)

<scxml version="1.0" xmlns="http://www.w3.org/2005/07/scxml"
	xmlns:queue="http://www.genesyslab.com/modules/queue"
	xmlns:ixn="http://www.genesyslab.com/modules/interaction"
	xmlns:dialog="http://www.genesyslab.com/modules/dialog"
	xmlns:xi="http://www.w3.org/2001/XInclude">
	<initial>
		<transition target="start"/>
	</initial>
	
	<state id="start" initial="complex.complex_sub">
		<onentry>
			<script> 
				var args = new Object( );
				args.var1 = 3;
				args.var2 = 'data3';
			</script>
		</onentry>
		
		<transition event="done.state.complex.complex_sub" target="exit">
			<log expr="_event.data.val1"/>
			<log expr="_event.data.val2"/>
		</transition>

		<xi:include parse="xml" href="complex_sub.scxml" resolveid="complex" />
	</state>
	
	<final id="exit">
		<onentry>
			<log expr="'success!'"/>
		</onentry>
	</final>
	
	<final id="error">
		<onentry>
			<log expr="'failed!'"/>
		</onentry>
	</final>
</scxml>

Primary subroutine (complex_sub.scxml)

<state id="complex_sub" initial="$$_MY_PREFIX_$$.first_step" >
	<onentry>
		<script>
			var usefulName1 = args.var1;
			var usefulName2 = args.var2;
		</script>
	</onentry>

	<state id="first_step" initial="$$_MY_PREFIX_$$.compound.compound_sub">
		<onentry>
			<log expr="'Performing complex_sub.results calculation for ' + _my_prefix" />
			<script>
				var args = new Object( );
				args.var1 = 1;
				args.var2 = 'data1';
			</script>
		</onentry>

		<xi:include parse="xml" href="compound_sub.scxml" resolveid="compound" xmlns:xi="http://www.w3.org/2001/XInclude" />

		<transition event="done.state.$$_MY_PREFIX_$$.compound.compound_sub" target="$$_MY_PREFIX_$$.second_step">
			<log expr="_event.data.val1"/>
			<log expr="_event.data.val2"/>
		</transition>
	</state>

	<state id="second_step" initial="$$_MY_PREFIX_$$.simple.simple_sub">
		<onentry>
			<script> 
				var args = new Object( );
				args.var1 = 2;
				args.var2 = 'data2';
			</script>
		</onentry>
		
		<xi:include parse="xml" href="simple_sub.scxml" resolveid="simple" xmlns:xi="http://www.w3.org/2001/XInclude" />

		<transition event="simple_sub.results.*" target="$$_MY_PREFIX_$$.complete">
			<log expr="_event.data.val1"/>
			<log expr="_event.data.val2"/>
		</transition>
	</state>
		
	<final id="complete">
		<donedata>
			<param name="val1" expr="usefulName1"/>
			<param name="val2" expr="usefulName2"/>
		</donedata>
	</final>
</state>

Nested compound subroutine (compound_sub.scxml):

<state id="compound_sub" initial="$$_MY_PREFIX_$$.calculate" >
	<onentry>
		<script>
			var usefulName1 = args.var1;
			var usefulName2 = args.var2;
		</script>
	</onentry>

	<state id="calculate">
		<onentry>
			<log expr="'Performing compound_sub.results calculation for ' + _my_prefix" />
		</onentry>

		<transition target="$$_MY_PREFIX_$$.complete"/>
	</state>

	<final id="complete">
		<donedata>
			<param name="val1" expr="usefulName1"/>
			<param name="val2" expr="usefulName2"/>
		</donedata>
	</final>
</state>

Nested simple subroutine (simple_sub.scxml):

<state id="simple_sub">
	<onentry>
		<script>
			var usefulName1 = args.var1;
			var usefulName2 = args.var2;
		</script>
		<log expr="'Performing simple_sub.results calculation for ' + _my_prefix" />
		<raise event="simple_sub.results.success">
			<param name="val1" expr="usefulName1"/>
			<param name="val2" expr="usefulName2"/>
		</raise>
	</onentry>
</state>

Fully assembled SCXML Application document:

<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" xmlns:dialog="http://www.genesyslab.com/modules/dialog" xmlns:ixn="http://www.genesyslab.com/modules/interaction" xmlns:queue="http://www.genesyslab.com/modules/queue" xmlns:xi="http://www.w3.org/2001/XInclude">
	<initial>
		<transition target="start"/>
	</initial>
	<state id="start" initial="complex.complex_sub">
		<onentry>
			<script> 
				var args = new Object( );
				args.var1 = 3;
				args.var2 = 'data3';
			</script>
		</onentry>

		<transition event="done.state.complex.complex_sub" target="exit">
			<log expr="_event.data.val1"/>
			<log expr="_event.data.val2"/>
		</transition>

		<state _my_prefix="complex" id="complex.complex_sub" initial="complex.first_step" >
			<onentry>
				<script>
					var usefulName1 = args.var1;
					var usefulName2 = args.var2;
				</script>
			</onentry>

			<state _my_prefix="complex" id="complex.first_step" initial="complex.compound.compound_sub">
				<onentry>
					<log expr="'Performing complex_sub.results calculation for ' + _my_prefix"/>
					<script>
						var args = new Object( );
						args.var1 = 1;
						args.var2 = 'data1';
					</script>
				</onentry>

				<state _my_prefix="complex.compound" id="complex.compound.compound_sub" initial="complex.compound.calculate">
					<onentry>
						<script>
							var usefulName1 = args.var1;
							var usefulName2 = args.var2;
						</script>
					</onentry>

					<state _my_prefix="complex.compound" id="complex.compound.calculate">
						<onentry>
							<log expr="'Performing compound_sub.results calculation for ' + _my_prefix"/>
						</onentry>

						<transition target="complex.compound.complete"/>
					</state>

					<final _my_prefix="complex.compound" id="complex.compound.complete">
						<donedata>
							<param expr="usefulName1" name="val1"/>
							<param expr="usefulName2" name="val2"/>
						</donedata>
					</final>

				</state>
				<transition event="done.state.complex.compound.compound_sub" target="complex.second_step">
					<log expr="_event.data.val1"/>
					<log expr="_event.data.val2"/>
				</transition>
			</state>

			<state _my_prefix="complex" id="complex.second_step" initial="complex.simple.simple_sub">
				<onentry>
					<script> 
						var args = new Object( );
						args.var1 = 2;
						args.var2 = 'data2';
					</script>
				</onentry>

				<state _my_prefix="complex.simple" id="complex.simple.simple_sub">
					<onentry>
						<script>
							var usefulName1 = args.var1;
							var usefulName2 = args.var2;
						</script>
						<log expr="'Performing simple_sub.results calculation for ' + _my_prefix"/>
						<raise event="simple_sub.results.success">
							<param expr="usefulName1" name="val1"/>
							<param expr="usefulName2" name="val2"/>
						</raise>
					</onentry>
				</state>

				<transition event="simple_sub.results.*" target="complex.complete">
					<log expr="_event.data.val1"/>
					<log expr="_event.data.val2"/>
				</transition>
			</state>

			<final _my_prefix="complex" id="complex.complete">
				<donedata>
					<param expr="usefulName1" name="val1"/>
					<param expr="usefulName2" name="val2"/>
				</donedata>
			</final>
		</state>
	</state>

	<final id="exit">
		<onentry>
			<log expr="'success!'"/>
		</onentry>
	</final>

	<final id="error">
		<onentry>
			<log expr="'failed!'"/>
		</onentry>
	</final>
</scxml>

Output from application:

"Performing complex_sub.results calculation for complex"
"Performing compound_sub.results calculation for complex.compound"
"1"
"data1"
"Performing simple_sub.results calculation for complex.simple"
"2"
"data2"
"3"
"data3"
"success!"
Children

The child element <fallback> is not supported.

Handling Assembly and Compilation Problems

When using xinclude, developers should ensure that valid documents and fragments are used. This will avoid many XML parsing problems. However, since large SCXML documents can be very complicated, it is still possible to have document errors that prevent the final application from being assembled, parsed, and compiled.

When dealing with such a situation, a developer can place the following in the main application document:

<!-- $$_GENESYS_DEBUGGING_$$ -->

If the application document cannot be parsed and compiled, and this element is present in the document, the entire application document will be written to a file in the current working directory. The filename will be sessionid.scxml, where sessionid is the ID of the session that was being created. The information contained in this file should be sufficient to allow the developer to determine why the failure occurred.

These files need to be removed manually by the developer after the problems have been resolved.

<param>

The <param> element has the following restriction:

<content>

The following are the additional Genesys attributes, children and behavior for the <content> element.

Attributes

Name

Required

Type

Default Value

Valid Values

Description

_expr

false

value expression

none

Any value expression that returns a valid ECMAScript object

This value expression returns an ECMAScript object which represents a parameter on the action. See SCXML Legal Data Values and Value Expressions for details.

Children

No change from what is in the SCXML standard.




Section I – SCXML > SCXML Extensions > SCXML Element Extensions         Top of Page
Genesys 8.1
SCXML Technical Reference
< Session Parameterization            SCXML Event Extensions >