State Chart XML (SCXML)

https://www.w3.org/TR/scxml/
Admin
SCXML is a general-purpose event-based state machine language that provides a generic state-machine...
Tokens:49,064
Snippets:337
Trust Score:10
Update:9 months ago
Show doc for...
Tokens:
Raw
### SCXML with CCXML Extension Example

Source: https://www.w3.org/TR/scxml/index

This snippet demonstrates how to incorporate CCXML functionality into SCXML. It shows an example of using a CCXML <accept> element within a transition's executable content. The behavior of such platform-specific elements is implementation-dependent.

```xml
<transition event="ccxml:connection.alerting">
  <ccxml:accept connectionid="_event.data.connectionid"/>
</transition>
```

--------------------------------

### SCXML System Variables and Data Model Example (ECMAScript)

Source: https://www.w3.org/TR/scxml/index

Illustrates the structure of the ECMAScript data model, including automatically populated system variables like _name, _sessionid, _event (with its properties and data), and _ioprocessors. It shows how application-specific data is integrated and provides an example of accessing system variables within the data model.

```ECMAScript
{
  "_name": "myName",
  "_sessionid": "12345",
  "_event": {
    "name": "foo.bar",
    "data": {
      "answer": 42
    }
  },
  "_ioprocessors": {
    "http://www.w3.org/TR/scxml/#BasicHTTPEventProcessor": {
      "location": "http://example.com/scxml-http/12345"
    },
    "http://www.w3.org/TR/scxml/#SCXMLEventProcessor": {
      "location": "http://example.com/scxml-http/23456"
    }
  }
}
```

--------------------------------

### SCXML Interpreter Initialization Procedure

Source: https://www.w3.org/TR/scxml/index

This procedure initializes the SCXML interpreter and starts processing the SCXML document. It includes validation, data model initialization, script execution, and entering initial states before starting the main event loop. Dependencies include validation functions and data structure initializations.

```pseudo-code
procedure interpret(doc):
    if not valid(doc): failWithError()
    expandScxmlSource(doc)
    configuration = new OrderedSet()
    statesToInvoke = new OrderedSet()
    internalQueue = new Queue()
    externalQueue = new BlockingQueue()
    historyValue = new HashTable()
    datamodel = new Datamodel(doc)
    if doc.binding == "early":
        initializeDatamodel(datamodel, doc)
    running = true
    executeGlobalScriptElement(doc)
    enterStates([doc.initial.transition])
    mainEventLoop()

```

--------------------------------

### SCXML State Transition Example

Source: https://www.w3.org/TR/scxml/index

This snippet demonstrates a basic SCXML state with multiple transitions based on events and conditions. It shows how to define transitions that trigger based on specific events, conditional logic, or any event.

```xml
<state id="s">
   <transition event="e" cond="x==1" target="s1"/>
   <transition event="e" target="s2"/>
   <transition event="*" target="s3"/>
</state>
```

--------------------------------

### SCXML External Transition Example

Source: https://www.w3.org/TR/scxml/index

Demonstrates an SCXML transition with 'type' set to 'external' (or default). It shows the sequence of state exits and entries when an event occurs, impacting nested states and the LCCA. The example includes SCXML code and the resulting log output.

```xml
<state id="S" initial="s1">
   <state id="s1" initial="s11">
      <onexit>
         <log expr="'leaving s1'"/>
     </onexit>
     
     <state id="s11">
        <onexit>
           <log expr="'leaving s11'"/>
        </onexit>
     </state>
     
     <transition event="e" target="s21">
        <log expr="'executing transition'"/>
     </transition>

   </state>
  
   <state id="s2" initial="s21">
      <state id="s21">
         <onentry>
            <log expr="'entering s21'"/>
         </onentry>
      </state>
      <onentry>
         <log expr="'entering s2'"/>
      </onentry>
   </state>

   <onentry>
     <log expr="'entering S'"/>
   <onentry>   
   <onexit>
     <log expr="'leaving S'"/>
   <onexit>
</state>
```

--------------------------------

### SCXML State Machine Example

Source: https://www.w3.org/TR/scxml/index

This SCXML code defines a state machine with various states and transitions. It includes examples of nested states, parallel execution, event handling, logging actions, and referencing external SCXML files using 'xi:include'. It also demonstrates datamodel usage and invoking external components via CCXML and VoiceXML namespaces.

```scxml
<?xml version="1.0" encoding="us-ascii"?>
<!-- A wrapper state that contains all other states in this file
- it represents the complete state machine --> 
<scxml xmlns="http://www.w3.org/2005/07/scxml"
       xmlns:xi="http://www.w3.org/2001/XInclude"
       version="1.0"
       initial="Main"
       datamodel="ecmascript">
  <state id="Main">
    <!-- its initial state is Test1 -->
    <initial>
      <transition target="Test1"/>
    </initial>

    <!-- Really simple state showing the basic syntax. -->
    <state id="Test1">
      <initial>
        <transition target="Test1Sub1"/>
      </initial>
      <!-- Runs before we go into the substate -->
      <onentry> 
        <log expr="'Inside Test1'"/>
      </onentry>

      <!-- Here is our first substate -->
      <state id="Test1Sub1">
        <onentry>
          <log expr="'Inside Test1Sub1.'"/>
        </onentry>
        <onexit>
          <log expr="'Leaving Test1Sub1'"/>
        </onexit>
        <!-- Go to Sub2 on Event1 -->
        <transition event="Event1" target="Test1Sub2"/>
      </state>

      <!-- Here is the second substate 
           It is final, so Test1 is done when we get here -->
      <final id="Test1Sub2"/>

      <!-- We get this event when we reach Test1Sub2. -->
      <transition event="Test1.done" target="Test2"/>

      <!-- We run this on the way out of Test1 -->
      <onexit>
        <log expr="'Leaving Test1...'"/>
      </onexit>
    </state>

    <state id="Test2" xmlns:xi="http://www.w3.org/2001/XInclude">
      <initial>
        <transition target="Test2Sub1"/>
      </initial>

      <!-- This time we reference a state 
           defined in an external file.   -->
       <xi:include href="SCXMLExamples/Test2Sub1.xml" parse="text"/>
  
      <final id="Test2Sub2"/>

      <!-- Test2Sub2 is defined as final, so this
           event is generated when we reach it -->
      <transition event="done.state.Test2" next="Test3"/>
    </state>

    <state id="Test3">
      <initial>
        <transition target="Test3Sub1"/>
      </initial>

      <state id="Test3Sub1">
        <onentry>
          <log expr="'Inside Test3Sub1...'"/>
          <!-- Send our self an event in 5s -->
          <send event="Timer"  delay="5s"/>
        </onentry>
        <!-- Transition on to Test4.
             This will exit both us and our parent. -->
        <transition event="Timer" target="Test4"/>
        <onexit>
          <log expr="'Leaving Test3Sub1...'"/>
        </onexit>
      </state>

      <onexit>
        <log expr="'Leaving Test3...'"/>
      </onexit>
    </state>
    
    <state id="Test4">
      <onentry>
        <log expr="'Inside Test4...'"/>
      </onentry>
      <initial>
        <transition target="Test4Sub1"/>
      </initial>

      <state id="Test4Sub1">
        <onexit>
          <log expr="'Leaving Test4Sub1...'"/>
        </onexit>
        <!-- This transition causes the state to exit immediately
             after entering Test4Sub1.  The transition has no event
             or guard so it is always active -->
        <transition target="Test5"/>
      </state>
    </state>
       
    <state id="Test5">
      <onentry>
        <log expr="'Inside Test5...'"/>
      </onentry>
      <initial>
        <transition target="Test5P"/>
      </initial>

      <!-- Fire off parallel states.  In a more realistic example
      the parallel substates Test5PSub1 and Test5PSub2 would themselves
      have substates and would do some real work before transitioning to final substates -->
      <parallel id="Test5P">
        <state id="Test5PSub1" initial="Test5PSub1Final">
           <final id="Test5PSub1Final"/>
           </state>
        <state id="Test5PSub2" initial="Test5PSub2Final">
            <final id="Test5PSub2Final"/>
            </state>
        <onexit>
          <log expr="'all parallel states done'"/>
        </onexit>
      </parallel>

      <!-- The parallel states immediately transition to final substates,
      so this event is generated immediately.   -->
      <transition event="done.state.Test5P" target="Test6"/>
    </state>

    <!-- 
         - This state shows invocation of an external component.
         - We will use CCXML + VoiceXML actions as an example 
         - as it is a good smoke test to show how it all 
         - fits together. 
         - Note: In a real app you would likely 
         - split this over several states but we 
         - are trying to keep it simple here. 
    -->
    <state id="Test6"
           xmlns:ccxml="http://www.w3.org/2002/09/ccxml"
           xmlns:v3="http://www.w3.org/2005/07/vxml3">
      <datamodel>
        <data id="ccxmlid" expr="32459"/>
        <data id="v3id" expr="17620"/>
        <data id="dest" expr="'tel:+18315552020'"/>
        <data id="src" expr="'helloworld2.vxml'"/>
```

--------------------------------

### SCXML Internal Transition Example

Source: https://www.w3.org/TR/scxml/index

Illustrates an SCXML transition with 'type' set to 'internal'. This type differs from 'external' when the target is a descendant of the source, as it avoids exiting and re-entering the source state. The example includes SCXML code and its log output.

```xml
<state id="S" initial="s1">
   <state id="s1" initial="s11">
      <onentry>
        <log expr="entering S1"/>
        </onentry>
      <onexit>
         <log expr="'leaving s1'"/>
     </onexit>
     
     <state id="s11">
       <onentry>
        <log expr="entering s11"/>
       </onentry>
        <onexit>
           <log expr="'leaving s11'"/>
        </onexit>
     </state>
     
     <transition event="e" target="s11" type="internal">
        <log expr="'executing transition'"/>
     </transition>

   </state>
  

==== log output will be ======>

leaving s11
executing transition
entering s11

=== if transition were external, log output would be ====>

leaving s11
leaving s1
executing transition
entering s1
entering s11



```

--------------------------------

### SCXML Parallel State Example

Source: https://www.w3.org/TR/scxml/index

This snippet demonstrates the structure and usage of the <parallel> element in SCXML. It defines a parallel state 'p' with two child states, S1 and S2, each having their own sub-states and transitions. The example illustrates how events can trigger transitions within individual child states and how the completion of all child states leads to the finalization of the parallel state.

```scxml
<parallel id="p">

    <transition event="done.state.p" target="someOtherState"/>

    <state id="S1" initial="S11">
        <state id="S11">
            <transition event="e4" target="S12"/>
        </state>
        <state id="S12">
            <transition event="e1" target="S1Final"/>
        </state>
        <final id="S1Final"/>
    </state> 

    <state id="S2" initial="S21">
        <state id=S21">
            <transition event="e1" target="S22"/>
        </state>
        <state id="S22">
            <transition event="e2" target="S2Final/>
        </state>
        <final id="S2Final"/>
    </state> 

</parallel>
```

--------------------------------

### SCXML <foreach> Example: Logging Book ISBNs

Source: https://www.w3.org/TR/scxml/index

This SCXML snippet demonstrates the use of the <foreach> element to iterate over an array of books in a shopping cart and log the ISBN of each book. It utilizes the 'item' attribute to represent each book during iteration.

```SCXML
<foreach array="cart.books" item="book">
<log expr="'Cart contains book with ISBN ' + book.isbn"/>
</foreach>
```

--------------------------------

### SCXML Blackjack Game Example

Source: https://www.w3.org/TR/scxml/index

This SCXML document outlines the state machine for a blackjack game. It uses 'invoke' to interact with VXML dialogs and external data models, and 'finalize' to process data returned from invocations. The 'initial' state and transitions manage the game's progression.

```scxml
<?xml version="1.0"?>
<?access-control allow="*"?>
<scxml version="1.0" datamodel="ecmascript" initial="master"> <state id="master">
    <initial id="init1">
      <transition target="_home"/>
    </initial>
    <transition event="new_dealer" target="NewDealer"/>
    <transition event="mumble" target="_home"/> <!-- bail out to caller -->
    <transition event="silence" target="_home"/> <!-- bail out to caller -->
    <state id="_home">
      <onenter>
        <script>
        _data = {};
        </script>
      </onenter>
      <invoke src="datamodel.v3#InitDataModel" type="vxml3">
        <finalize>
          <script>
          var n;
          for (n in event) {
              _data[n] = event[n];
          }
          </script>
        </finalize>
      </invoke>
      <transition event="success" target="Welcome"/>
    </state>

    <state id="Welcome">
      <invoke src="dialog.vxml#Welcome" type="vxml3">
        <param name="skinpath" expr="skinpath"/>
      </invoke>
      <transition event="success" target="Intro2"/>
    </state>

    <state id="Intro2">
      <invoke src="dialog.vxml#Intro2" type="vxml3">
        <param name="skinpath" expr="skinpath"/>
      </invoke>
      <transition event="success" target="EvalDeal"/>
    </state>

    <state id="EvalDeal">
      <onenter>
        <script>enterEvalDeal();</script>
      </onenter>
      <invoke src="dialog.vxml#EvalDeal" type="vxml3">

```

--------------------------------

### SCXML Traffic Report Example

Source: https://www.w3.org/TR/scxml/index

This SCXML document defines the control flow for a voice portal application that provides traffic reports. It utilizes 'invoke' to call external VXML dialogs and 'finalize' blocks to execute scripts after an invocation completes. The transitions manage the user's interaction based on events and conditions.

```scxml
<?xml version="1.0"?>
<?access-control allow="*"?>
<scxml version="1.0" initial="Intro" datamodel="ecmascript">
  <state id="Intro">
    <invoke src="dialog.vxml#Intro" type="vxml2"/>
    <transition event="success" cond="sessionChrome.playAds" target="PlayAds"/>
    <transition event="success" cond="!sessionChrome.playAds &amp;&amp; ANIQuality" 
                    target="ShouldGoBack"/>
    <transition event="success" cond="!sessionChrome.playAds &amp;&amp; !ANIQuality" 
                    target="StartOver"/>
  </state>

  <state id="PlayAds">
    <invoke src="dialog.vxml#PlayAds" type="vxml2"/>
    <transition event="success" cond="ANIQuality" target="ShouldGoBack"/>
    <transition event="success" cond="!ANIQuality" target="StartOver"/>
  </state>

  <state id="StartOver">
    <onenter>
      <script>enterStartOver();</script>
    </onenter>
    <invoke src="dialog.vxml#StartOver" type="vxml2">
      <param name="gotItFromANI" expr="gotItFromANI"/>
      <finalize>
        <script>finalizeStartOver();</script>
      </finalize>
    </invoke>
    <transition event="success" target="ShouldGoBack"/>
    <transition event="doOver" target="StartOver"/>
    <transition event="restart" target="Intro"/> <!-- bail out to caller -->
  </state>

  <state id="ShouldGoBack">
    <invoke src="dialog.vxml#ShouldGoBack" type="vxml2">
      <param name="cityState" expr="cityState"/>
      <param name="gotItFromANI" expr="gotItFromANI"/>
      <finalize>
        <script>finalizeShouldGoBack();</script>
      </finalize>
    </invoke>
    <transition event="highWay" target="HighwayReport"/>
    <transition event="go_back" target="StartOver"/>
    <transition event="doOver" target="ShouldGoBack"/>
    <transition event="restart" target="Intro"/>
  </state>

  <state id="HighwayReport">
    <invoke src="dialog.vxml#HighwayReport" type="vxml2">
      <param name="cityState" expr="cityState"/>
      <param name="gotItFromANI" expr="gotItFromANI"/>
      <param name="playHRPrompt" expr="playHRPrompt"/>
      <param name="metroArea" expr="metroArea"/>
      <finalize>
        <script>finalizeHighwayReport();</script>
      </finalize>
    </invoke>
    <transition event="highway" target="PlayHighway"/>
    <transition event="go_back" target="StartOver"/>
    <transition event="doOver" target="HighwayReport"/>
    <transition event="fullreport" target="FullReport"/>
    <transition event="restart" target="Intro"/>
  </state>

  <state id="FullReport">
    <invoke src="dialog.vxml#FullReport" type="vxml2">
      <param name="cityState" expr="cityState"/>
      <param name="metroArea" expr="metroArea"/>
      <finalize>
        <script>finalizeFullReport();</script>
      </finalize>
    </invoke>
    <transition event="go_back" target="HighwayReport"/>
    <transition event="new_city" target="StartOver"/>
  </state>

  <state id="PlayHighway">
    <invoke src="dialog.vxml#PlayHighway" type="vxml2">
      <param name="cityState" expr="cityState"/>
      <param name="curHighway" expr="curHighway"/>
      <finalize>
        <script>finalizePlayHighway();</script>
      </finalize>
    </invoke>
    <transition event="go_back" target="HighwayReport"/>
  </state>
</scxml>

```

--------------------------------

### SCXML Invoke with Content Element

Source: https://www.w3.org/TR/scxml/index

This example demonstrates how to invoke an external resource, such as a VoiceXML session, using the <invoke> tag. It specifies the type of the resource and uses the 'content' attribute to embed data directly within the invocation. The 'idlocation' attribute stores the generated invoke ID for later use.

```scxml
<invoke type="http://www.w3.org/TR/voicexml21/" idlocation="myInvoke">
    <content expr="'This is some data to send to the invoked session.'"/>
</invoke>
```

--------------------------------

### SCXML Send Message to Parent Session

Source: https://www.w3.org/TR/scxml/index

This example illustrates how an invoked SCXML session can send an event with data back to its invoking parent session. It utilizes the <send> tag with the special target '_parent' and the type 'scxml', ensuring communication back to the originating state machine.

```scxml
<send target="_parent" type="scxml">
    <content expr="'Data from child session.'"/>
</send>
```

--------------------------------

### CCXML <createcall> Element Example

Source: https://www.w3.org/TR/scxml/index

Illustrates the use of a CCXML <createcall> element within an 'onentry' block to initiate a call and assign a connection ID. This is a more complex Custom Action Element.

```xml
<onentry>
  <ccxml:createcall dest="'tel:+18315552020'" connectionid="myConnectionID"/> 
</onentry>
```

--------------------------------

### SCXML Send with Event and Namelist Attributes

Source: https://www.w3.org/TR/scxml/index

This example demonstrates how to send a message using the 'event' and 'namelist' attributes within an SCXML <send> element. The 'event' attribute specifies the event type, and 'namelist' references data elements containing the message content. This is suitable for sending data-driven messages.

```SCXML
<datamodel>
<data id="target" expr="'tel:+18005551212'"/>
<data id="content" expr="'http://www.example.com/mycontent.txt'"/>
</datamodel>
   ...
<send target="target" type="x-messaging" event="fax.SEND" namelist="content"/>

```

--------------------------------

### SCXML Send with Inline XML Content

Source: https://www.w3.org/TR/scxml/index

This example demonstrates an SCXML '<send>' element with inline XML content, including a namespace declaration for CSTA. The receiving SCXML session handles an 'external.event' and uses platform-specific executable content '<csta:makecall>' to initiate a call based on the XML payload.

```SCXML
<send id="send-123"
      target="http://scxml-processors.example.com/session2"
      type="http://www.w3.org/TR/scxml/#SCXMLEventProcessor"
      xmlns:csta="http://www.ecma.ch/standards/ecma-323/csta">

  <content>
     <csta:MakeCall>
       <csta:callingDevice>22343</csta:callingDevice>
       <csta:calledDirectoryNumber>18005551212</csta:calledDirectoryNumber>
     </csta:MakeCall>
  </content>

</send>
```

```SCXML
<scxml:transition event="external.event">
  <csta:makecall callingDevice="data('_event')/csta:MakeCall/csta:callingDevice"
                 callingDirectoryNumber="data('_event')/csta:MakeCall/csta:callingDirectoryNumber"/>
</scxml:transition>
```

--------------------------------

### SCXML Low-Level Send for V3 Form Execution

Source: https://www.w3.org/TR/scxml/index

Shows how to use the low-level <send> element to initiate a V3 form. It assumes that a 'v3:HelloWorld.done' event is explicitly or implicitly generated after the form execution. This allows for controlled execution of external V3 forms.

```scxml
<send target="v3id" type="http://www.w3.org/TR/scxml/#BasicEventProcessor" event="v3:formstart" namelist="src id"/>
```

--------------------------------

### SCXML Platform-Specific Extension V3 Form

Source: https://www.w3.org/TR/scxml/index

Illustrates the use of platform-specific custom action elements (V3 form) as an alternative to <send> for executing logic. This section highlights that the implementation details are platform-dependent. It defines a simple 'Hello World' prompt.

```scxml
<v3:form id="HelloWorld">
          <v3:block><v3:prompt>Hello World!</v3:prompt></v3:block>          
        </v3:form>
```

--------------------------------

### SCXML Microwave Oven Data Initialization

Source: https://www.w3.org/TR/scxml/index

Initializes data variables for a microwave oven simulation, including 'cook_time', 'door_closed', and 'timer'. These variables define the state and behavior of the microwave within the SCXML model.

```scxml
<data id="cook_time" expr="5"/>
    <data id="door_closed" expr="true"/>
    <data id="timer" expr="0"/>
```

--------------------------------

### Get SCXML Child States

Source: https://www.w3.org/TR/scxml/index

Retrieves a list of direct children of a given state in an SCXML document. This function specifically returns `<state>`, `<final>`, and `<parallel>` elements that are immediate children of the provided state.

```javascript
function getChildStates(state1) {
    // Implementation details omitted for brevity
}
```

--------------------------------

### CCXML <accept> Equivalent using <send>

Source: https://www.w3.org/TR/scxml/index

Shows how the functionality of a CCXML <accept> element can be achieved using the <send> element. This involves setting up a datamodel for 'connectionid' and then sending the 'ccxml:accept' event.

```xml
<datamodel>
<data name="connectionid"/>
</datamodel>
<transition event="ccxml:connection.alerting">
  <assign location="connectionid" expr="_event.data.connectionid"/>
 <send type="ccxml" event="ccxml:accept" namelist="connectionid"/> 
</transition>
```

--------------------------------

### SCXML Value Expression: Copy Event Data

Source: https://www.w3.org/TR/scxml/index

Demonstrates using ECMAScript expressions as value expressions in SCXML's <assign> element. This example copies data from the incoming event (_event.data) into the local data model.

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

--------------------------------

### Execute SCXML Microstep

Source: https://www.w3.org/TR/scxml/index

The `microstep` procedure processes a set of enabled transitions atomically. This involves exiting the source states, executing transition actions, and entering the target states in a lock-step manner. This is crucial for maintaining the integrity of the state machine, especially in parallel regions.

```javascript
procedure microstep(enabledTransitions):
    exitStates(enabledTransitions)
    executeTransitionContent(enabledTransitions)
    enterStates(enabledTransitions)

```

--------------------------------

### SCXML Location Expression: Assign Salary

Source: https://www.w3.org/TR/scxml/index

Shows how to use ECMAScript left-hand-side expressions as location expressions in SCXML's <assign> element. This example updates an employee's salary based on data loaded from a JSON file.

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

--------------------------------

### SCXML: Execute Transition Content

Source: https://www.w3.org/TR/scxml/index

The `executeTransitionContent` procedure iterates through a list of enabled transitions and executes the associated executable content for each transition. This is a straightforward procedure for handling actions tied to transitions.

```scxml
procedure executeTransitionContent(enabledTransitions):
    for t in enabledTransitions:
        executeContent(t)


```

--------------------------------

### Get SCXML State Ancestors

Source: https://www.w3.org/TR/scxml/index

Retrieves a list of proper ancestors for a given state in an SCXML document. It can return all ancestors up to the root `<scxml>` element or stop before a specified ancestor. Proper ancestors are defined as parents, grandparents, etc., excluding the state itself.

```javascript
function getProperAncestors(state1, state2) {
    // Implementation details omitted for brevity
    // Returns a set of ancestors in ancestry order.
}
```

--------------------------------

### Get Transition Domain in SCXML

Source: https://www.w3.org/TR/scxml/index

This function identifies the lowest common ancestor (LCA) state for a transition's source and target states. This domain is the compound state such that all states affected by the transition are descendants of it, and no descendant of it shares this property. It handles internal transitions specifically.

```javascript
function getTransitionDomain(t)
    tstates = getEffectiveTargetStates(t)
    if not tstates:
        return null
    elif t.type == "internal" and isCompoundState(t.source) and tstates.every(lambda s: isDescendant(s,t.source)):
        return t.source
    else:
        return findLCCA([t.source].append(tstates))
```

--------------------------------

### SCXML Initial State

Source: https://www.w3.org/TR/scxml/index

Documentation for the <initial> element in SCXML, representing the default initial state for a complex state.

```APIDOC
## SCXML Initial State

### Description
Represents the default initial state for a complex `<state>` element (one containing child `<state>` or `<parallel>` elements).

### Method
N/A (Element definition)

### Endpoint
N/A (Element definition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None

#### Attribute Details
None

#### Children
* `<transition>`: A single transition whose `target` specifies the default initial state(s). This transition must not have `cond` or `event` attributes and must target only descendants of the containing state. It may contain executable content.
```

--------------------------------

### SCXML Microwave Oven State Transitions

Source: https://www.w3.org/TR/scxml/index

Defines state transitions for a microwave oven simulation. This includes turning the oven on/off, handling door open/close events, and managing the cooking timer based on elapsed time.

```scxml
<state id="off">
    <transition event="turn.on" target="on"/>
  </state>

  <state id="on">
    <initial>
        <transition target="idle"/>
    </initial>
    

    <transition event="turn.off" target="off"/>
    <transition cond="timer &gt;= cook_time" target="off"/>

    <state id="idle">
      <transition cond="door_closed" target="cooking"/>
      <transition event="door.close" target="cooking">
        <assign location="door_closed" expr="true"/>
        
      </transition>
    </state>

    <state id="cooking">
      <transition event="door.open" target="idle">
        <assign location="door_closed" expr="false"/>
      </transition>

      
      <transition event="time">
        <assign location="timer" expr="timer + 1"/>
      </transition>
    </state>

  </state>
```

--------------------------------

### SCXML Microwave Oven Implementation (SCXML)

Source: https://www.w3.org/TR/scxml/index

This SCXML code defines a microwave oven's states and transitions. It uses a parallel state to manage both the cooking engine and the door status independently. The In() predicate is used to check the current state of the door within the engine's logic.

```scxml
<?xml version="1.0"?>
<scxml xmlns="http://www.w3.org/2005/07/scxml"
       version="1.0"
       datamodel="ecmascript"
       initial="oven"> 

  <!-- trivial 5 second microwave oven example -->
  <!-- using parallel and In() predicate -->
  <datamodel>
    <data id="cook_time" expr="5"/>
    <data id="door_closed" expr="true"/>
    <data id="timer" expr="0"/>
  </datamodel>

  <parallel id="oven">

    <!-- this region tracks the microwave state and timer -->
    <state id="engine">
    <initial>
      <transition target="off"/>
      </initial>

      <state id="off">
        <!-- off state -->
        <transition event="turn.on" target="on"/>
      </state>
      
      <state id="on">
      <initial>
        <transition target="idle"/>
        </initial>
        
         <!-- on/pause state -->
        
        <transition event="turn.off" target="off"/>
        <transition cond="timer &gt;= cook_time" target="off"/>
        
        <state id="idle">
          <transition cond="In('closed')" target="cooking"/>
        </state>
        
        <state id="cooking">
          <transition cond="In('open')" target="idle"/>

          <!-- a 'time' event is seen once a second -->
          <transition event="time">
            <assign location="timer" expr="timer + 1"/>
          </transition>
        </state>
      </state>
    </state>

    <!-- this region tracks the microwave door state -->
    <state id="door">
      <initial>
        <transition target="closed"/>
      </initial>
      <state id="closed">
        <transition event="door.open" target="open"/>
      </state>
      <state id="open">
        <transition event="door.close" target="closed"/>
       </state>
    </state>

  </parallel>

</scxml>
```

--------------------------------

### SCXML Cancel Delayed Event

Source: https://www.w3.org/TR/scxml/index

This example shows how to cancel a previously sent delayed event in SCXML using the <cancel> element. It utilizes the 'sendid' attribute to specify the ID of the event to be cancelled. The <cancel> element attempts to halt delayed events but cannot guarantee success if the event has already been dispatched.

```SCXML
<cancel sendid="event_id_to_cancel"/>

```

--------------------------------

### Get Effective Target States for SCXML Transitions

Source: https://www.w3.org/TR/scxml/index

Resolves the actual target states for a given SCXML transition, correctly handling history states. This function iterates through transition targets, dereferencing history states by recursively calling itself or retrieving stored history values. It utilizes an `OrderedSet` for storing unique targets.

```javascript
function getEffectiveTargetStates(transition) {
    const targets = new OrderedSet();
    for (const s of transition.target) {
        if (isHistoryState(s)) {
            if (historyValue[s.id]) {
                targets.union(historyValue[s.id]);
            } else {
                targets.union(getEffectiveTargetStates(s.transition));
            }
        } else {
            targets.add(s);
        }
    }
    return targets;
}
```

--------------------------------

### CCXML <createcall> Equivalent using <send>

Source: https://www.w3.org/TR/scxml/index

Demonstrates how the CCXML <createcall> functionality can be replicated using the <send> element. This requires a two-step process: sending the 'ccxml:createcall' event with destination, and then handling the 'ccxml:createcall.success' event to assign the connection ID.

```xml
<datamodel>
  <data name="dest" expr="'tel:+18315552020'"/>
  <data name="connectionid"/>
</datamodel>
<onentry>
  <send type="ccxml" event="ccxml:createcall" namelist="dest"/>
</onentry>
<transition event="ccxml:createcall.success">
   <assign location="connectionid" expr="_event.data.connectionid"/>
</transition>
```

--------------------------------

### SCXML Procedure: Enter States and Handle Invocations

Source: https://www.w3.org/TR/scxml/index

The `enterStates` procedure computes and enters states based on enabled transitions. It manages state configurations, data model initialization, event handlers, and final state processing. It also adds states to `statesToInvoke` for subsequent invocation processing.

```SCXML
procedure enterStates(enabledTransitions):
    statesToEnter = new OrderedSet()
    statesForDefaultEntry = new OrderedSet()
    // initialize the temporary table for default content in history states
    defaultHistoryContent = new HashTable() 
    computeEntrySet(enabledTransitions, statesToEnter, statesForDefaultEntry, defaultHistoryContent) 
    for s in statesToEnter.toList().sort(entryOrder):
        configuration.add(s)
        statesToInvoke.add(s)
        if binding == "late" and s.isFirstEntry:
            initializeDataModel(datamodel.s,doc.s)
            s.isFirstEntry = false
        for content in s.onentry.sort(documentOrder):
            executeContent(content)
        if statesForDefaultEntry.isMember(s):
            executeContent(s.initial.transition)
        if defaultHistoryContent[s.id]:
            executeContent(defaultHistoryContent[s.id]) 
        if isFinalState(s):
            if isSCXMLElement(s.parent):
                running = false
            else:
                parent = s.parent
                grandparent = parent.parent
                internalQueue.enqueue(new Event("done.state." + parent.id, s.donedata))
                if isParallelState(grandparent):
                    if getChildStates(grandparent).every(isInFinalState):
                        internalQueue.enqueue(new Event("done.state." + grandparent.id))
 

```

--------------------------------

### SCXML Main Event Loop Procedure

Source: https://www.w3.org/TR/scxml/index

This procedure outlines the core logic of the SCXML interpreter's main event loop. It handles sequential processing of events, ensuring run-to-completion semantics by completing all enabled transitions before waiting for new external events. Dependencies include internal and external event queues, datamodel, and functions like selectEventlessTransitions, selectTransitions, and microstep.

```scxml
procedure mainEventLoop():
    while running:
        enabledTransitions = null
        macrostepDone = false
        # Here we handle eventless transitions and transitions 
        # triggered by internal events until macrostep is complete
        while running and not macrostepDone:
            enabledTransitions = selectEventlessTransitions()
            if enabledTransitions.isEmpty():
                if internalQueue.isEmpty(): 
                    macrostepDone = true
                else:
                    internalEvent = internalQueue.dequeue()
                    datamodel["_event"] = internalEvent
                    enabledTransitions = selectTransitions(internalEvent)
            if not enabledTransitions.isEmpty():
                microstep(enabledTransitions.toList())
        # either we're in a final state, and we break out of the loop 
        if not running:
            break
        # or we've completed a macrostep, so we start a new macrostep by waiting for an external event
        # Here we invoke whatever needs to be invoked. The implementation of 'invoke' is platform-specific
        for state in statesToInvoke.sort(entryOrder):
            for inv in state.invoke.sort(documentOrder):
                invoke(inv)
        statesToInvoke.clear()
        # Invoking may have raised internal error events and we iterate to handle them        
        if not internalQueue.isEmpty():
            continue
        # A blocking wait for an external event.  Alternatively, if we have been invoked
        # our parent session also might cancel us.  The mechanism for this is platform specific,
        # but here we assume it’s a special event we receive
        externalEvent = externalQueue.dequeue()
        if isCancelEvent(externalEvent):
            running = false
            continue
        datamodel["_event"] = externalEvent
        for state in configuration:
            for inv in state.invoke:
                if inv.invokeid == externalEvent.invokeid:
                    applyFinalize(inv, externalEvent)
                if inv.autoforward:
                    send(inv.id, externalEvent) 
        enabledTransitions = selectTransitions(externalEvent)
        if not enabledTransitions.isEmpty():
            microstep(enabledTransitions.toList()) 
    # End of outer while running loop.  If we get here, we have reached a top-level final state or have been cancelled          
    exitInterpreter()            

```

--------------------------------

### SCXML Send with Content Child Element

Source: https://www.w3.org/TR/scxml/index

This code snippet illustrates sending a message with inline content using the <content> child element within an SCXML <send> tag. This method is used for embedding the message body directly, as shown in the CSTA MakeCall example. It allows for complex XML structures as message bodies.

```SCXML
<send target="csta://csta-server.example.com/" type="x-csta">
      <content>
      <csta:MakeCall>
        <csta:callingDevice>22343</csta:callingDevice>
        <csta:calledDirectoryNumber>18005551212</csta:calledDirectoryNumber>
      </csta:MakeCall>
      </content>
</send>

```

--------------------------------

### SCXML Procedure: Compute States to Enter from Transitions

Source: https://www.w3.org/TR/scxml/index

The `computeEntrySet` procedure identifies all states that need to be entered as a consequence of executing specific transitions. It populates `statesToEnter` and `statesForDefaultEntry`, considering target states, their descendants, and relevant ancestors.

```SCXML
procedure computeEntrySet(transitions, statesToEnter, statesForDefaultEntry, defaultHistoryContent)
    for t in transitions:
        for s in t.target:
            addDescendantStatesToEnter(s,statesToEnter,statesForDefaultEntry, defaultHistoryContent)
        ancestor = getTransitionDomain(t)
        for s in getEffectiveTargetStates(t)):
            addAncestorStatesToEnter(s, ancestor, statesToEnter, statesForDefaultEntry, defaultHistoryContent)


```

--------------------------------

### SCXML <param> Element

Source: https://www.w3.org/TR/scxml/index

The <param> element defines a key and a dynamic value for passing data.

```APIDOC
## <param> Element

### Description
Provides a general mechanism to identify a key and a dynamically calculated value for transmission to external services or inclusion in events.

### Method
Not applicable (XML element)

### Endpoint
Not applicable (XML element)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### Attributes
- **name** (string) - Required - The key or name associated with the value.
- **expr** (value expression) - Optional - A value expression to dynamically calculate the value.

##### Children
None

### Request Example
```xml
<param name="userId" expr="session.current_user.id"/>
```

### Response
#### Success Response (200)
Not applicable (XML element)

#### Response Example
Not applicable (XML element)

#### Notes
Used within elements like <donedata> to specify data to be included in events.
```

--------------------------------

### Sending Events using <send> Element

Source: https://www.w3.org/TR/scxml/index

Explains how to send events from an SCXML implementation using the `<send>` element with the Basic HTTP Event I/O Processor type. It covers target specification, event naming, parameter mapping, and content handling.

```APIDOC
## Sending Events with `<send>`

### Description
Allows SCXML implementations to send events to a target URI using the Basic HTTP Event I/O Processor. Events are sent via HTTP POST, with parameters and content encoded in the request body.

### Method
POST

### Endpoint
`target` or `targetexpr` attribute of the `<send>` element

### Parameters
#### Attributes of `<send>` element
- **type** (string) - Required - Must be set to `"http://www.w3.org/TR/scxml/#BasicHTTPEventProcessor"`.
- **target** (string) - Optional - The access URI of the target SCXML Processor.
- **targetexpr** (string) - Optional - An expression evaluating to the access URI of the target SCXML Processor.
- **event** (string) - Optional - If defined, its value is used as the `_scxmleventname` HTTP POST parameter.

#### Child Elements of `<send>`
- **<param>** (element) - Optional - Its `name` attribute and value are mapped to HTTP POST parameters.
- **<content>** (element) - Optional - Its value is used as the body of the HTTP POST message.

### Request Body (application/x-www-form-urlencoded by default)
- **_scxmleventname** (string) - The name of the event to send, derived from the `event` parameter of the `<send>` element.
- **(mapped variable names)** (string) - Variable names from the `namelist` attribute of the `<send>` element are mapped to HTTP POST parameters.
- **(param names)** (string) - Names from the `name` attributes of `<param>` children are mapped to HTTP POST parameters.

### Request Example (Conceptual)
```json
{
  "_scxmleventname": "user_event",
  "param1": "value1",
  "session_id": "12345"
}
```
(If `<content>` is present, it would be the raw body of the POST request.)

### Response
#### Success Response (200)
- **Status** (integer) - Indicates successful delivery of the event.

#### Error Response
- **error.communication** (SCXML Event) - Added to the internal event queue of the sending session if `target` or `targetexpr` are not specified or if communication fails.
```

--------------------------------

### SCXML Transition Element

Source: https://www.w3.org/TR/scxml/index

Documentation for the <transition> element in SCXML, used to define state transitions triggered by events and conditional guards.

```APIDOC
## SCXML Transition Element

### Description
Defines transitions between states, triggered by events and conditionalized via guard conditions. Transitions may contain executable content executed upon taking the transition.

### Method
N/A (Element definition)

### Endpoint
N/A (Element definition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None

#### Attribute Details
* **event** (EventsTypes.datatype.) - Optional - A space-separated list of event descriptors that trigger this transition.
* **cond** (Boolean expression) - Optional - The guard condition for this transition. Defaults to 'true'.
* **target** (IDREFS) - Optional - The identifier(s) of the state or parallel region to transition to.
* **type** (enum) - Optional - Determines whether the source state is exited for transitions to descendant states. Valid values: "internal", "external". Defaults to "external".

#### Children
* Executable content: Run after `<onexit>` handlers and before `<onentry>` handlers triggered by this transition.
```

--------------------------------

### SCXML: Compute States to Exit and Handle History/OnExit

Source: https://www.w3.org/TR/scxml/index

The `exitStates` procedure computes the set of states to exit, updates history states with descendant configurations, executes onexit handlers, cancels invocations, and removes states from the current configuration. It assumes the existence of helper functions like `computeExitSet`, `isAtomicState`, `isDescendant`, `configuration`, and `documentOrder`.

```scxml
procedure exitStates(enabledTransitions):
    statesToExit = computeExitSet(enabledTransitions)           
    for s in statesToExit:
        statesToInvoke.delete(s)
    statesToExit = statesToExit.toList().sort(exitOrder)
    for s in statesToExit:
        for h in s.history:
            if h.type == "deep":
                f = lambda s0: isAtomicState(s0) and isDescendant(s0,s) 
            else:
                f = lambda s0: s0.parent == s
            historyValue[h.id] = configuration.toList().filter(f)
    for s in statesToExit:
        for content in s.onexit.sort(documentOrder):
            executeContent(content)
        for inv in s.invoke:
            cancelInvoke(inv)
        configuration.delete(s)

```

--------------------------------

### SCXML Substate Log on Entry

Source: https://www.w3.org/TR/scxml/index

Logs a message upon entering a substate named 'Test2Sub1'. This is a common practice for debugging and understanding the flow of execution within complex SCXML state machines.

```scxml
<log expr="'Inside Test2Sub1'"/>
```

--------------------------------

### SCXML Predicate for Entry Order

Source: https://www.w3.org/TR/scxml/index

Defines the 'entryOrder' predicate used for determining state entry sequence. It prioritizes ancestors over descendants, using document order as a tie-breaker, effectively meaning document order.

```SCXML
entryOrder // Ancestors precede descendants, with document order being used to break ties 
    (Note:since ancestors precede descendants, this is equivalent to document order.)
```
Tokens:
Raw