Jump to: navigation, search

ECMAScript

SCXML Elements

<anchor>

The <anchor> module is not supported by the SCXML engine. This element would otherwise be used for providing 'go back' or 'redo'-like functionality for applications.

<cancel >

TTTTFor <cancel>, either one of the attributes id and sendid may be used. However, both cannot be defined at the same time.

When using <send> to generate events, if there is an intention to cancel the event sent, it is recommended to use the attribute idlocation instead of id. The sendid stored at the location specified by idlocation may then be used in <cancel>.

When the <cancel> request has been processed, the SCXML engine will send back the "cancel.successful" event if the event was successfully removed, or "error.notallowed" if there was a problem, along with the attribute sendid in the event.

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

Attribute Details

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. Note that this does not impact the way in which the SCXML document is executed.

_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. Note that this does not impact the way in which the SCXML document is executed.

src Attribute

The currently supported URI schema types for the src attribute are:
  • HTTPS
  • HTTP
  • FILE

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

<foreach> (Since ORS 8.1.200.40, SCXML 8.1.000.77)

This element is an extension to the W3C Working Draft 7 May 2009. However, it has been formally added to the W3C SCXML specification since the W3C Working Draft 26 April 2011. <foreach> is an Executable Content element (like <if>, or <log>) and can be used to create iterators. The behaviour of <foreach> is similar to that of the C# and Perl 'foreach' construct, which traverses items in a collection. This implementation differs from the W3C specification in that the SCXML engine behaves as though a deep copy of each item in the collection is created during iteration as opposed to a shallow copy. Nevertheless, iteration behaviour will remain unaffected by changes to the collection.

Attribute Details

Name

Required

Type

Default Value

Valid Values

Description

array

true

Value expression

none

A value expression that evaluates to an iterable collection.

The <foreach> element will iterate over a deep copy of this collection.

item

true

string

none

Any variable name that is valid in the specified data model.

A variable that stores a different item of the collection in each iteration of the loop.

index

false

string

none

Any variable name that is valid in the specified data model.

A variable that stores the current iteration index upon each iteration of the foreach loop.

<history>

The <history> element is not supported by the SCXML engine. This element would otherwise be used for allowing 'pause and resume' control flows.

<invoke>

The child element <content> of <invoke> is not supported.

<scxml>

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

Attribute Details

Name

Required

Type

Default Value

Valid Values

Description

_type

false

string

combination

Any valid string

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

_persist

false

boolean

false true (prior to 8.1.2)

The following is the set of valid values:

  • true
  • false

This allows the developer to suppress all persistence capabilities.

Persistence is not always desired, due to the associated performance overhead. For instance, in Orchestration, 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.

_statePersistDefault

false

string "may" The following is the set of valid values:
  • must
  • may
  • no

To ensure proper session persistence during High Availability recovery, the _statePersistDefault may be used as an attribute to the top-level <scxml> element.

Orchestration Server uses the value of _statePersistDefault as the default for the <state> _persist attribute, if it is not specified at the <state> level.

  • may—Default value. ORS will persist the SCXML session in the entered state once the event queue becomes empty.
  • must—ORS will immediately persist the SCXML session in the entered state.
  • no—ORS will not persist the SCXML session in the entered state.

_maxtime (Since ORS 8.1.300.03, SCXML 8.1.300.00)

false integer "604800" Any valid positive integer, inside double quotes.

Specifies the maximum age in seconds that an ORS session should exist.  If this age is reached, ORS shall attempt to exit the session.

If specified, this overrides the value specified in configuration for ORS under scxml/max-session-age.

To disable this feature, set the _maxtime to "0".

As of ORS 8.1.300.13, SCXML 8.1.300.13, an available Cassandra data store will be required for this functionality.

_microStepLimit (Since ORS 8.1.300.11, SCXML 8.1.300.10)

false

integer

1000

Any valid positive integer, inside double quotes.

Specifies the maximum number of microsteps allowed to be taken following the processing of one event. Subsequent transitions may arise from the processing of one event if the following transitions are eventless. If this number is reached, ORS shall attempt to exit the session. To use ORS configured default, leave _microStepLimit undefined. To disable this feature, set _microStepLimit="0".

_stateEntryLimit (Since ORS 8.1.300.11, SCXML 8.1.300.10)

false

integer

100

Any valid positive integer, inside double quotes.

Specifies the maximum number of times that a state may be entered as the target of a transition. States entered indirectly as the result of a transition element or initial attribute are not considered for this limit (for example, ancestors of the target state that must be entered before entering the target state). If this number is reached, ORS shall attempt to exit the session. To use ORS configured default, leave _stateEntryLimit undefined. To disable this feature, set _stateEntryLimit="0".

_maxPendingEvents (Since ORS 8.1.300.11, SCXML 8.1.300.10)

false

integer

100

Positive integer between 30 to 100000, inclusive, inside double quotes.

Specifies the maximum number of events allowed to be queued to a session (inclusive of internal, external, delayed and undelivered events). If this number is reached, ORS shall attempt to exit the session. This feature cannot be disabled.

_processEventTimeout (Since ORS 8.1.300.11, SCXML 8.1.300.10)

false

integer

10000

Any valid positive integer, inside double quotes.

Specifies the maximum time allotted for the processing of the event queue. The processing of one event may lead to additional events being queued. Processing of the event queue does not complete until the event queue is empty. This feature sets an upper bound to the amount of time dedicated to processing these events. If the timeout is reached, ORS shall attempt to exit the session. To use ORS configured default, leave _processEventTimeout undefined. To disable this feature, set _processEventTimeout="0".

_sendSessionRecovered (Since ORS 8.1.300.13, SCXML 8.1.300.13) _recoveryEnabled (Since ORS 8.1.300.12, SCXML 8.1.300.12)

false

boolean

false

The following is the set of valid values:

  • true
  • false

Specifies whether or not this strategy is eligible for proactive recovery. If set to true, the session will be explicitly restored by ORS when an ORS node performs switch-over to Primary.

_debug (Since ORS 8.1.300.11, SCXML 8.1.300.10)

false

boolean

false

The following is the set of valid values:

  • true
  • false

Specifies whether or not debugging of SCXML strategy is required. When set to true, the session will save a copy of the fully assembled SCXML strategy to disk (working directory).

_transitionStyle (Since ORS 8.1.300.28, SCXML 8.1.300.38)

false

string

legacy

The following is the set of valid values:

  • legacy
  • genesys
  • w3c

Specifies the order in which the <transition> executable content is to be executed in the scenario where there are two or more selected transitions (only in <parallel> regions).

  • legacy setting dictates that transitions are executed by line order (lowest line number first)
  • genesys setting orders transitions by reverse scope order. Transitions of deepest scope (most nested) are executed first. Ties for scope are broken by lowest line number first.
  • w3c setting adheres to the ordering prescribed by the W3C Working Draft for SCXML. Transitions are executed in the scope order of the states which selected them. Ties for scope are broken by lowest line number first.

<log>

<log> has three attributes (expr, label, level). For attribute details, please refer to State Chart XML (SCXML): State Machine Notation for Control Abstraction W3C Working Draft 7 May 2009 (www.w3.org). As of version 8.1.200.46, specifying a level of 5 with a label of 22000 to 22020 will result in behavior equivalent to that for URS/IRD.

<state>

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

Attribute Details

Name

Required

Type

Default Value

Valid Values

Description

_type

false

NMTOKEN

normal

The following is the set of valid values:

  • normal

This allows the developer to control how the platform is to handle this state and is a place holder for future support.

_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 is used to indicate to the 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 platform may persist the session in this state at its discretion. This is the default value.
  • must - The 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).

Note: Orchestration Server uses the value of <scxml> _statePersistDefault as the default for the <state> _persist attribute, if it is not specified at the <state> level.

_deactivate

false

string

no

The following is the set of current valid values:

  • now
  • no

This attribute defines 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 platform about how meaningful it is to persist the session.

src Not Supported

Persist/Deactivate option matrix

_persist

no

may

must

_deactivate

no

Persistence disabled. _deactivate attribute is ignored.

The session may be persisted in this state at the platform's discretion.

The platform guarantees that this state will be persisted upon entry.

now

Persistence disabled. _deactivate attribute is ignored.

The session may be persisted in this state at the platform's discretion and will be marked as inactive when waiting for transition.

The session that enters this state and is waiting for transition will be immediately persisted and marked as inactive.

<param>

The <param> element has the following restriction:

  • When using the <param> element with any action element, you must 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.

<transition>

The attribute anchor of the <transition> is not supported.

ORS Version 8.1.200.60/8.1.300.01

The behaviour of transitions in the SCXML engine is different from that which is described in the W3C Working Draft 7 May 2009 [1]. This draft spec explains the following:

The LCA is the innermost <state>, <parallel>, or <scxml> element that is a proper ancestor of the transition's source state and its target state(s).

During a transition, all active states that are proper descendants of the LCA are exited.

The new transition behaviour of the SCXML engine shares greater similarities with that of the W3C Working Draft 16 December 2010 [2], in that in the case of a transition whose source state is a compound state and whose target(s) is a descendant of the source, the transition will not exit and re-enter its source state. In addition, the notion of the LCA is replaced by the LCCA:

The LCCA is the innermost compound <state> or <scxml> element that is a proper ancestor of the transition's source state and its target state(s).

During a transition, all active states that are proper descendants of the LCCA are exited.

<validate>

The <validate> element is not supported by the SCXML engine. This would otherwise be used to invoke a validation of the datamodel.

<xi:include>

The xinclude recommendation (http://www.w3.org/TR/xinclude/) is 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. See section below on using <xi:include>.

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

  • Developers should ensure that the 'resolveid' attribute value is unique within a document. This is necessary when the same included document is used multiple times within the including document since, the IDs of <state>, <parallel>, and so on, must be unique across the entire document.
  • Included documents must NOT transition back to states that are defined in an including document. This does not work.

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

  • For the included document:
    • The document must be a valid <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 is to be used as the subroutine.
    • The referenced <state> can be a simple or a compound state. If it is a compound state, it must define <initial> as well as <final> states.
    • An atomic state must use <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.
    • The included <state> must be self-contained: it should not have transitions to states in the including document or outside of itself.
    • The included <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.
    • The included <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>.
    • The included <state> must not rely on events from the including document other than the transition to the included state.
  • For the including document:
    • The document must have a <transition> for the event generated by the included state or subroutine. This event will contain the results from the subroutine.
    • The document must have a <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.
    • When using <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 <xi:include> element as well as existing attribute limitations.

Attribute Details

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.

As of ORS 8.1.300.27, this attribute also supports substitution by session start parameters. These parameters may come from the ApplicationParms section of an Enhanced Routing Script, URL-encoded parameters of a web-started session, or the <param> elements nested within a <session:start>

For example:

<xi:include href="http://appsrv:80/scxml/subroutine_routing.scxml" />

It is possible to parametrize the URI as follows:

<xi:include href="http://appsrv:80/scxml/$$MY_SUBROUTINE$$" />

When a special token of the form $$parameter_name$$ is provided, it will be automatically substituted with the value of the matching session start parameter (case-sensitive).

If the session start parameters are as follows:

MY_SUBROUTINE = subroutine_chat.scxml

Resulting URI:

<xi:include href="http://appsrv:80/scxml/subroutine_chat.scxml" />

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 are 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 is 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 is 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_$$ is 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> is 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.

Children

The child element <fallback> is not supported.

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on September 22, 2017, at 10:55.