|
Genesys 8.1 SCXML Technical Reference |
||
< Session Parameterization SCXML Event 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:
The following are the additional Genesys attributes for the <scxml>
element
Name |
Required |
Type |
Default Value |
Valid Values |
Description |
---|---|---|---|---|---|
_type |
false |
string |
combination |
The following is the set of valid values:
|
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:
|
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. |
The following are the additional Genesys attributes, children, and behavior for the <state>
element.
Name |
Required |
Type |
Default Value |
Valid Values |
Description |
---|---|---|---|---|---|
_type |
false |
NMTOKEN |
normal |
The following is the set of valid values:
|
This will allow the developer to control how the platform is to handle this state. The following are the possible values
|
_persist |
false |
NMTOKEN |
May |
The following is the set of valid values:
|
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:
|
_deactivate |
false |
string |
No |
The following is the set of current valid values:
|
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. |
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.
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:
<history>
state element, and the transitioned-to state transitions to the history state, then the session will go back through the queue state and be put back into the queue if necessary.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.
There are no new attributes for this element but there are some additional values for certain attributes:
5 = alarm — This will send the alarm message to the Genesys management framework.
6 = peg — This will maintain a peg count associated with the session and the associated interaction. The "Label" attribute will be the name of the peg count and the "expr" attribute will indicate how much to increment the counter. Before the platform terminates the session or when the associated interaction is routed, the platform will attach this counter's name and value to the "interaction.udata" attribute.
There are no new attributes for this element, but there are some additional values for certain attributes:
"fm" — for sending events to functional modules. The target attribute value will be the namespace of the target functional module.
Compared to the previous SCXML draft, the following attributes have been added or changed in the currently implemented SCXML standard:
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.
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>
In addition to what the SCXML specification defines, the following guidelines can be followed when developing an asynchronous subroutine with this functionality:
<datamodel>
and <data>
for mapping of the invoking session's <param>
s to the invoked session's data model. This is the primary means of passing data to the invoked session.<donedata>
element as a child of the top-level <final>
state(s). This will allow the invoked state machine to return the appropriate output parameters in the done.invoke event. This event is sent to the invoking session.<param>
to provide argument information to the invoked session. Since the sessions do not share a <datamodel>
, this is the primary means for passing data to the invoked session.<transition>
for the done.invoke event that will be generated by the invoked session. This allows the invoked session to communicate the subroutine results back to the invoking document/session and transition to the next state based on the results.The following are the changes to the children of the <invoke>
element:
<content>
will not be supported. The following are the Genesys differences for the <raise>
element.
<content>
— occurs 0 to 1. The containing data to be passed to the specified session.<param>
Occurs 0 to N — See SCXML <param>
for details. Each <param>
element specifies a key/value pair that will be included in the 'data' property of the resulting 'xxx' event that is being sent (put on the internal queue of the session). This is primarily used for subroutine-type processing. The name attribute will be the name of the property in the event (for example, name="results" will be _event.data.results). The value of the property will either come from the "expr" attribute or a data location. The "name" and "expr" attributes will work the same as they do as input parameters or the <invoke>
or <send>
elements.The following are the Genesys differences for the <final>
element.
<content>
— This is not supported as a child element.<donedata>
Occurs 0 to 1 — See SCXML <donedata>
for details. The <donedata>
element specifies a key/value pairs (via child <param>
elements) that will be included in the 'data' property of the resulting 'done.state.xxx' event associated with the ending a session or a state. This is primarily used for subroutine-type processing. The following is the behavior of the included <param>
elements: <invoke>
or <send>
element.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.
Name |
Required |
Type |
Default Value |
Valid Values |
Description |
---|---|---|---|---|---|
_type |
false |
NMTOKEN |
data |
The following is the set of valid values:
|
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:
|
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:
|
_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:
|
_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:
|
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.
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.
The following are the additional Genesys attributes, children and behavior for the <parallel>
element.
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:
<state>
, <parallel>
, and so on, must be unique across the entire document.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":
<state>
fragment that specifies the complete behavior of the subroutine. The document can contain an <scxml>
document, but if it does, the xinclude declaration must use xpointer to reference the <state>
that will be used as the subroutine.<state>
can be a simple or a compound state. If it is a compound state, it must define <initial>
as well as <final>
states. <raise>
/<event>
to return the appropriate output parameters. A compound state, on the other hand, can use either <raise>
, <event>
, or the <donedata>
element of the <final>
states to perform this function. <state>
must be self-contained: it should not have transitions to states in the including document or outside of itself. <state>
must not use datamodel elements from the included document, unless the <data>
elements are defined within the <state>
or one of its children. Using <data>
elements defined elsewhere in the included document will likely result in an error since they are not defined in the including document. <state>
should not use datamodel elements from the including document. Doing so makes subroutine information global to the application. It is recommended that data should be passed to a subroutine via an event, or through variables defined via <script>
.<state>
must not rely on events from the including document other than the transition to the included state. <transition>
for the event generated by the included state or subroutine. This event will contain the results from the subroutine.<transition>
to the included state. The event can contain the input parameters for the subroutine. Alternately, the including state can use a <script>
element in its <onentry>
element to define and initialize a set of parameters that are passed to the included <state>
. The included state can access these parameters through the variable scoping that ECMAScript provides.<xi:include>
elements, the namespaces used in the included document need to be declared in the including document.The following are the additional Genesys attributes for the <include>
element as well as existing attribute limitations.
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, 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, |
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_$$ |
|
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, |
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!"
The child element <fallback>
is not supported.
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.
The <param>
element has the following restriction:
<param>
element with any action element, you must also specify both the name and expr attributes. Because of this, the platform does not support the name attribute value as a data model location expression if the expr attribute is missing.The following are the additional Genesys attributes, children and behavior for the <content>
element.
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. |
No change from what is in the SCXML standard.
|
Genesys 8.1 SCXML Technical Reference |
||
< Session Parameterization SCXML Event Extensions > |