State Chart XML (SCXML): State Machine Notation for Control Abstraction

3.1 <scxml>

The top-level root state, which carries version information etc.

A state machine must specify either an "initial" attribute or an <initial> element, but not both. Either notation can be used to specify the state that the machine will transition to at the start of processing. The only difference between the two notations is that the <initial> element contains a <transition> element which may in turn contain executable content which will be executed before the initial state is entered. If the "initial" attribute is specified instead, the specified state will be entered, but no executable content will be executed.

3.2 <state>

Holds the representation of a state.

3.3 <transition>

Transitions between states are triggered by events and conditionalized via guard-conditions. The optional attribute "target" specifies the destination of the transition, which may be a <state> or a <parallel> region. If the "target" on a <transition> is omitted, then taking the transition has the effect of leaving the machine in the same state after invoking any executable content that is included in the transition. Such a transition is equivalent to an 'event' handler in Harel State Table notation. Note that this is different from a <transition> whose "target" is its source state. In the latter case, the state is exited and reentered, triggering execution of its <onentry> and <onexit> executable content.

Any executable content contained in a transition is executed after the <onexit> handlers of the source state and before the <onentry> handlers of the target state.

If a transition has both "event" and "cond" attributes, it will be taken only if an event is raised that matches the "event" pattern and the "cond" condition evaluates to true. If the "event" clause is missing, the transition is taken whenever the "cond" evaluates to true. If the "cond" clause is also empty, the transition is taken as soon as the state is entered. Note that the data model can be changed only by the execution of <invoke> or executable content. Therefore transitions with empty "event" conditions need be checked only 1) upon arrival into a state, after the completion of all <onentry> handlers and 2) after an event has been processed (since it may have triggered executable content which could have updated the data model). See B Algorithm for SCXML Interpretation for details.

3.4 <parallel>

A state that encapsulates a set of parallel states. The <parallel> element has <onentry> and <onexit> and <transition> elements analogous to <state>. In addition, the <parallel> element holds a set of <state> elements that execute in parallel and join at the <onexit> handler of the <parallel> element. In particular, when all of the parallel substates reach final states, a completion event "ID.done" is generated, where "ID" is the "id" of the <parallel> element. Either the <parallel> element or one of its ancestors can trigger a transition off this event, at which time the <onexit> handler of the element will be executed.

When the state machine enters the parent <parallel> state, it simultaneously enters each child state. Transitions within the individual child elements operate normally. However any of the child elements may take a transition outside the <parallel> element. When this happens, the <parallel> element and all of its child elements are exited and the corresponding <onexit> handlers are executed. The handlers for the child elements execute first, in document order, followed by those of the parent <parallel> element, followed by an action expression in the <transition> element, and then the <onentry> handlers in the "target" state. See B Algorithm for SCXML Interpretation for a detailed description of the semantics <parallel> and the rest of SCXML.

3.5 <initial>

This element represents the default initial state for a complex state with sequential substates. Suppose <state> S1 has child states S11, S12, and S13. If the system is in S1, it must also be in one (and only one) of S11, S12, or S13. A <transition> in a distinct <state> S2 may take S11, S12, or S13 as its "target", but it may also simply specify the parent S1. In that case, the <initial> child of S1 specifies which of S11, S12, or S13 the system should transition to.

The only difference between the <initial> element and the 'initial' attribute is that the <initial> element contains a <transition> element which may in turn contain executable content which will be executed before the default state is entered. If the "initial" attribute is specified instead, the specified state will be entered, but no executable content will be executed. As an example, suppose that parent state S contains child states S1 and S2. If S specifies S1 as its default initial state via the "initial" attribute, then any transition that specifies S as its target will result in S entering S1 as well as S. In this case, the result is exactly the same as if the transition had taken S1 as its target. If, on the other hand, S specifies S1 as its default initial state via the <initial> tag containing a <transition> with S1 as its target, the <transition> can contain executable content which will execute before the default entry into S1. In this case, there is a difference between a transition that takes S as its target and one that takes S1 as its target. In the former case, but not in the latter, the executable content inside the <initial> transition will be executed.

3.6 <final>

<final> represents a final state of a compound state. When the system reaches a final state, it means that its parent state has completed its activity. Upon entry to the final state, the event "ParentID.done" is generated, where 'ParentID' is the ID of the parent state. Note that even though the parent state has run to completion, more remote ancestors may still be active. When the state machine reaches a top-level final state (namely one that is a child of <scxml>), it has finished processing and will terminate.

3.7 <onentry>

3.8 <onexit>

3.9 <history>

The <history> pseudo-state allows for 'pause and resume' control flow. Whenever a complex <state> is exited, its <history> pseudo-state, if present, records the state configuration at exit. Later a <transition> taking the <history> state as its "target" allows the <state> to pick up where it left off. If the state containing the <history> state is a compound state, then the history value will be a single state. However, if the parent state is a <parallel> state, the history value will be a set of states, one for each parallel child region.

3.10 Executable Content

Executable content consists of actions that are performed as part of taking transitions and entering and leaving states (<onentry> and <onexit>, etc.) Executable content occurs in blocks, meaning that wherever executable content may occur, an arbitrary number of elements may occur. These elements in a block are processed in document order. If the processing of an element causes an error to be raised, the remaining elements of the block are not processed and the error event is placed on the internal event queue and processed like any other event (see B Algorithm for SCXML Interpretation). In particular, the error event will not be removed from the queue and processed until all events preceding it in the queue have been processed.

Note that 4 External Communications Module, 5 Data Module and 6 Script Module all define additional elements of executable content beyond those listed here. Thus the exact set of executable content available depends on the profile (see 9 Profiles for examples).

<if cond="cond1">
  <!-- selected when "cond1" is true -->
<elseif cond="cond2"/>
  <!-- selected when "cond1" is false and "cond2" is true -->
<elseif cond="cond3"/>
  <!-- selected when "cond1" and "cond2" are false and "cond3" is true -->
<else/>
  <!-- selected when "cond1", "cond2", and "cond3" are false -->
</if>
            

<transition event="ccxml:connection.alerting">
  <ccxml:accept connectionid="eventdata.connectionid"/>
</transition>

3.11 Referencing External Files

The "src" attribute on <state> and <parallel> contains a URL which is used to reference an external file containing all or part of the definition of the state. The file must contain a document that matches the SCXML schema but it need not match the extra-schematic constraints contained in this specification. (For example, the document may contain transitions that reference state IDs that are not defined within it.) The exact treatment of the file depends on the format of the URL. If it ends with '#' followed by a string, the string is taken to be the ID of an element in the file and the children of that element are inserted into the state's definition before any other material contained in the <state>. Thus the state is incorporating the definition of a state defined within the file. If, on the other hand, the URL does not contain '#', the contents of the <scxml> element are inserted into the definition of the state before any other material in the state, along with an <initial> element whose <transition> takes as its target the value of the <scxml> element's 'initial' attribute. Thus in this case the contents of the entire state machine are inserted into the definition of the state.

Suppose that the file at "someURL" looks as follows:

<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initialstate="someState">
<state id="someState">
  <transition event="foo" target="someOtherState"/>
</state>
<state id="someOtherState">
  <transition event="bar" target="finalState"/>
</state>
</scxml>

A 'src' expression referencing 'someOtherState' will result in 'someOtherState's contents being inserted into the state's definition, as shown below. The following markup:

<state id="state1" src="someURL#someOtherState">
   <transition event="state1.Done" target="yetAnotherState"/>
   <final id="finalState"/>
</state>

will expand to:

<state id="state1">
   <transition event="bar" target="finalState"/>   
   <transition event="state1.Done" target="yetOtherState"/>
   <final id="finalState"/>
</state>

On the other hand, a 'src' expression referencing the whole file will result in both 'someState' and 'someOther' state being inserted into the state's definition, along with the appropriate <initial> element. Thus

<state id="state1" src="someURL">
   <transition event="state1.Done" target="yetOtherState"/>
   <final id="finalState"/>
</state>

becomes

 
 <state id="state1">
  <initial>
    <transition target="someState"/>
  </initial>
  <state id="someState">
    <transition event="foo" target="someOtherState"/>
  </state>
  <state id="someOtherState">
    <transition event="bar" target="finalState"/>
  </state>   
  <transition event="state1.Done" target="yetOtherState"/>
  <final id="finalState"/>
</state>

File inclusion takes place at load time. Implementations are free to perform document validation by any method they choose as long as the result is logically equivalent to a single pass of validation occurring after the material from the external file has been incorporated. (Note that implementations are not required to validate the external file. All that is required is that the document resulting from the incorporation be valid.)

3.12 SCXML Events

Events are one of the basic concepts in SCXML since they drive most transitions. The internal structure of events is platform-specific as long as the following external interface is observed:

• Events have names which are matched against the "event" attribute of transitions. These names are strings consisting of alphanumeric characters plus the character '.' which is used to segment names into tokens. The "event" attribute of a transition may end with the wildcard '.*', which will match zero or more tokens at the end of the processed event's name. Thus a transition with an "event" attribute of 'error.*' will match 'error', 'error.send', 'error.send.failed', etc. Furthermore, a transition with an "event" attribute consisting solely of '*' will match any event.

• Events optionally contain data organized into XML trees. If data is present, it must be able to be accessed via the 'event' variable, as specified in 5.5 System Variables.

• Events are immutable read-only data structures. Neither the browser's processing nor the user's markup may modify an event once it is placed in queue. Note that this implies that modifications to the event structure are not permitted.

There is a class of error events whose names begin with 'error.'. They may be raised by the platform, as specified in this document, or under application control. They are placed in the internal event queue and processed like any other event. In particular, they are not processed immediately if there are other events in the queueand they are ignored if no transition is found that matches them. Note however that authors can arrange for otherwise unhandled errors to cause the interpreter to exit by creating a transition with "event" attribute of 'error.*' and a target of any top-level final state (i.e. one that is a child of <scxml>). If such a transition T is placed in a state S, it will cause the state machine to terminate on any error that is raised in S or one of its substates and is not handled by another transition that is placed in a substate of S or in S and preceding T in document order.

In many applications, it is important for SCXML to receive events from external entities (for example those which it contacted with <invoke> and <send>.) Such applications should use profiles that include 4 External Communications Module.

For the most part, the set of events raised during the execution of an SCXML document is application-specific and generated under author control by use of the <event> and <send> elements. However, certain events are mandatory and generated automatically by the interpreter. In this version of the specification, in addition to error events, there is only the 'Cancel' event which is sent if the state machine leaves the containing state after executing the <invoke> element but before receiving the 'Done' event. Note that there are also mandatory events that invoked components must return to the invoking SCXML state machine. In this version of the specification, there are two such events, namely 'Done' and 'CancelResponse'. We may well change or expand this set of mandatory events in future drafts of this specification. Furthermore, it is likely that there will be distinct profiles of SCXML for specific applications, such as the Multi-modal Interaction Framework [W3C MMI] and VoiceXML 3.0. These profiles will define extensions to the core language and will likely extend the set of mandatory events with additional events appropriate to the specific application.

4.1 <send>

4.2 <invoke>

<invoke> and its child <finalize> are useful in states that model the behavior of an external service. The <invoke> element is executed immediately after the state's <onentry> element and sends an event invoking the external service. The <param> element may be used to pass data to the service. Any events that are received by the state machine from the invoked component during the invocation are preprocessed by the <finalize> handler before transitions are selected. The <finalize> code is used to normalize the form of the returned data and to update the data model before the transitions' "event" and "cond" clauses are evaluated.

When the <invoke> element is executed, the platform MUST start a new logical instance of the external service specified in "targettype" and pass it the data specified by "src", "srcexpr", <content>, or <param>. The service instance MAY be local or remote. In addition to the explicit arguments, the platform MUST pass a unique id to the external service . The external service MUST include the same id in all events that it returns to the invoking machine. (Syntax TBD.)

The external service MAY generate multiple events while it is processing, but it MUST generate a special ''id.Done' event , (where the 'id' is the id for this invocation) once it has finished processing. It MUST not generate any other events afterwards. If the invoking state machine takes a transition out of the state containing the <invoke> before it receives the 'Done' event, it MUST automatically send a 'Cancel' event to the invoked component to notify it that it may stop its processing. The 'Cancel' event will be sent as if it were the final <onexit> handler in the invoking state. The invoked component MUST respond to the 'Cancel' event with a 'CancelResponse' event (syntax of both events TBD). The invoking state machine will take its transition without waiting for the CancelResponse event, which will be processed like any other external event.

Note that the <invoke> element can be used to invoke an external SCXML interpreter to execute a different state machine. In this case, the external state machine acts in certain respects as if it were a set of substates of the invoking state. The behavior is thus similar to a complex state defined with <state> child elements. The most important difference is that in the <invoke> case, the external state machine does not share context or event queueswith the invoking machine. In particular, the invoked machine cannot access any variables declared in the invoking machine and data can be shared only by being explicitly passed via the <param> element. Similarly, events received or generated in one state machine are not seen by the other, though the two machines may exchange events via the <send> tag. Furthermore, state IDs need not be distinct across the two machines (though they must, of course, be distinct within each machine.) The <invoke> element thus provides a means of well-encapsulated code reuse.

When parallel states invoke the same external service concurrently, separate instances of the external service will be started. They can be distinguished by the id which is passed with the invocation. Similarly, the id contained in the events returned from the external services can be used to determine which events are responses to which invocation. Each event that is returned will be processed only by the <finalize> in the state that invoked it, but that event is then processed like any other event that the state machine receives. The finalize code can thus be thought of as a preprocessing stage that applies before the event is added to the event queue. Note that the event will be passed to all parallel states simultaneously to check for transitions.

<invoke> occurs only in atomic states, namely those that do not have <state> or <parallel> children. Thus, a state may have either <state> and <parallel> children or an <invoke> child,but not both.

4.3 <param>

4.4 <finalize>

4.5 <content>

5.1 <datamodel>

To provide a uniform method of access to both local and remote data, we introduce a <datamodel> element which encapsulates any number of <data> elements. Each such element defines a single data object. The exact nature of the data object depends on the data model language used. The data object may be fetched from an external source or specified in-line. In cases where the data object specified is not a legal instance of the data model language, implementations MAY translate it into a legal expression, and MUST signal an error if the cannot do so.

Data created via the <data> element is local to the SCXML interpreter and not shared with any external resource. However, the local data model, or parts of it, may be sent to an external resource via the <send> element. (See 4.1 <send>.) Existing data values may be modified with the <assign> element. (See 5.3 <assign>).

Logically, there is a single globally visible data model for the entire state machine. As an authoring convenience, however, we allow <datamodel> as a child of any <state>, thus allowing parts of the data model to be distributed throughout the document closer to the locations where the data will be accessed. However, all instances of the <data> element are created and initialized when the state machine is instantiated and may be accessed from any state at any time.

5.2 <data>

The <data> element is used to declare and populate portions of the datamodel. All <data> tags are evaluated exactly once, at load time. Implementations thus MUST evaluate <data> elements at load time but MAY do so in any order they choose. Ordering dependencies among <data> elements are thus not permitted. Suppose, for example, that the declaration of element "a" precedes the declaration of element "b" in a document. It is not safe to assume that "a" will be instantiated and have a value when the declaration of "b" is executed. Therefore the "expr" in "b" cannot reference the value of "a" (and vice-versa).

The <assign> element may be used to modify the data model.

5.3 <assign>

If "expr" is present, then the element MUST not have any children. Thus "expr" and children are mutually exclusive inside the <assign> element.

Assignment to a data model is done by using a location expression to denote the part of the data model where the change is to be made. If the location expression does not denote a valid location in the datamodel an error error.illegalalloc is raised. If the value specified (by 'expr' or children) is not a legal value for the location specified, the error error.invaliddata is raised. Note that what constitutes a legal value depends on the data model language used. See 9 Profiles for details.

5.4 <validate>

The <validate> element causes the datamodel to be validated. Note that validation of the datamodel occurs only when explicitly invoked by this element.

5.5 System Variables

The Data Module maintains a protected portion of the data model containing information that may be useful to applications. We refer to the items in this special part of the data model as 'system variables'. Implementations that include the Data Module MUST provide the following system variables, and MAY support others.

• _event. The variable 'event' is bound to a structure containing the current event's name and any data contained in the event. The exact nature of the structure depends on the datamodel being used. See 9 Profiles for details. In the executable content of <onentry>, <onexit> and <transition> elements, the current event is defined to be the event that triggered the transition, if there is one. In the "cond" attribute of <transition>, the current event is the one that is currently being matched against the transition, if there is one. In all other locations, 'event' is undefined. Note, in particular, that 'event' is not bound when the system is evaluating or taking a transition that lacks an "event" attribute.

  If the data in the event is not a legal instance of the data model language, and the system cannot translate it into one, then at the point at which the system attempts to bind 'event', the error error.invaliddata will be raised and the event data part of the 'event' structure will not be bound. The event's name will still be available, however. Processing of both the original event and the error event will proceed as usual.

• _sessionID. The variable 'sessionID' is bound at load time to the system-generated ID for the current SCXML session. It remains bound until the session terminates.

• _name. The variable 'name' is bound at load time to the name of the state machine, which is specified in the "name" attribute of the <scxml> element. It remains bound until the session terminates.

The set of system variables may be expanded in a future version of this specification. Therefore developers SHOULD NOT use IDs beginning with '_' in the <data> element since this may cause forwards-compatibility problems.

The concrete realization of these variables in a specific data model depends on the language used. For the exact location of these variables in an XML data model, see 9.3 The XPath Profile. All system variables are protected and any attempt to change their values MUST fail and result in the error error.illegalassign being raised.

6.1 <script>

The Script Module adds scripting capability to the state machine. Its schema may be found at D.5 Schema for Script Module. Profiles including the Script Module MUST:

• Redefine the executable content group to include the <script> tag.

For an example of how to do this, see 9.2 The ECMAScript Profile.

7.1 <anchor>

8.1 Conditional Expressions

Conditional expressions are used inside the 'cond' attribute of <transition>, <if> and <elseif>. If a conditional expression does not evaluate to a boolean value ('true' or 'false'), the error 'error.illegalcond' is raised. The set of operators in conditional expressions varies depending on the profile, but all profiles must support the 'In()' predicate, which is used to test whether the state machine is in a given state. This predicate allows coordination among parallel regions.

8.2 Location Expressions

Location expressions are used to specify a location in the datamodel as part of the <assign>element. The exact nature of a location depends on the profile. For example, in the XPath Profile (9.3 The XPath Profile), the underlying datamodel is an XML tree and a location expression must evaluate to an existing node or nodeset in the datamodel. If a location expression does not evaluate to a legal location, an error error.illegalalloc is raised.

8.3 Legal Data Values and Value Expressions

Any profile that includes the Data Module must specify the structure of the underlying data model. For example, the XPath Profile (9.3 The XPath Profile) defines the data model to be an XML tree. Such a specification of the data model implicitly defines a set of "legal data values", namely the objects that can be part of such a data model. For an XML data model, the set of legal data values consists of XML trees and subtrees, plus strings (as values of attributes or text children). In conjunction with this, the Profile must define a set of value expressions which can be evaluated at runtime to return legal data values. If a value expression does not return a legal data value, the error error.illegalvalue is raised.

8.4 Errors in Expressions

Implementations MAY raise errors caused by syntactically ill-formed expressions at document load time, or they MAY wait and raise these errors at runtime when the expressions are evaluated. Implementations MUST raise errors caused by expressions returning illegal values at the points at which B Algorithm for SCXML Interpretation indicates that the expressions are to be evaluated. Note that this requirement holds even if the implementation is optimizing expression evaluation.

9.1 The Minimal Profile

9.2 The ECMAScript Profile

<state id="errorSwitch">
  <datamodel>
   <data ID="time"/>
  </datamodel>
        
  <onentry>
    <assign location="_data.time" expr="currentDateTime()"/>
  </onentry>
          
  <transition cond="yearFromDatetime(_data.time) > 2009" target="newBehavior"/>
 
  <transition target="currentBehavior"/>
</state>

<scxml version="1.0" profile="ecmascript">
  <datamodel>
   <data ID="employees" src="http://example.com/employees.json"/>
   <data ID="year" expr="2008"/>
   <data ID="CEO" expr="\"Mr Big\""/>
   <data ID="profitable" expr="true"/>
  </datamodel>
</scxml>

<state id="errorSwitch">
    <datamodel>
      <data ID="employees" src="http://example.com/employees.json"/>
    </datamodel>
    
    <onentry>
        <assign location="_data.employees.employee[12].salary" expr="42000"/>
    </onentry>
</state>

<state id="processEvent">
    <datamodel>
        <data ID="myEvent"/>
    </datamodel>
    
    <onentry>
        <assign location="_data.myEvent" expr="_data._event"/>
    </onentry>
</state>

<state id="checkSessionID">
    <transition cond="_event.name=='connector.sip.invite'" target="nextState">
     ...
    </transition>
</state>

<scxml version="1.0" profile="ecmascript">
  <script>
       var globalCounter = 0;

       function updateCounter() {
        globalCounter++;
       }
  </script>
</scxml>

<state id="updateDM">
    <onentry>
      <script>
        _data.myDate = new Date(); 
        updateCounter();
      </script>
    </onentry>
</state>

9.3 The XPath Profile

<state id="errorSwitch" xmlns:fn="http://www.w3.org/2005/xpath-functions">
  <datamodel>
    <data ID="time"/>
  </datamodel>
          
  <onentry>
    <assign location="instance('time')" expr="fn:current-dateTime()"/>
  </onentry>
          
  <transition cond="fn:year-from-dateTime(/data[@ID='time']) > 2009" target="newBehavior"/>
  <transition target="currentBehavior"/>
</state>