Skip to content
Version: XState v4

SCXML

XState is compatible with the SCXML (State Chart XML: State Machine Notation for Control Abstraction) specification. This page contains details on where our API relates to the SCXML specification.

Events​

Events in SCXML contain information relevant to the source of the event and have a different schema than event objects in XState. Internally, event objects are converted to SCXML events for compatibility.

SCXML events include:

  • name, a character string giving the name of the event. name is equivalent to the .type property of an XState event.
  • type, the event type: 'platform', 'external', or 'internal'.
    • platform events are raised by the platform itself, such as error events.
    • internal events are raised by raise(...) actions or by send(...) actions with target: '_internal'.
    • external events describe all other events.
  • sendid, the send ID of the triggering send(...) action.
  • origin, a string that allows the receiver of this event to send(...) a response event back to the origin.
  • origintype, used with origin.
  • invokeid, the invoke ID of the invocation that triggered the child actor.
  • data, any data that the sending entity included with this event. data is equivalent to an XState event object.

The SCXML event form of all XState events is present in the _event property of action and guard meta objects as the third argument:

// ...
{
  actions: {
    someAction: (context, event, { _event }) => {
      console.log(_event); // SCXML event
    };
  },
  guards: {
    someGuard: (context, event, { _event }) => {
      console.log(_event); // SCXML event
    }
  }
}
// ..

Transitions​

The event-target mappings defined on the on: { ... } property of state nodes is synonymous to the SCXML <transition> element:

{
  green: {
    on: {
      TIMER: {
        target: '#yellow',
        cond: context => context.timeElapsed > 5000
      },
      POWER_OUTAGE: { target: '#red.flashing' }
    }
  },
  // ...
}
<state id="green">
  <transition
    event="TIMER"
    target="yellow"
    cond="timeElapsed > 5000"
  />
  <transition
    event="POWER_OUTAGE"
    target="red.flashing"
  />
</state>

Guards​

The cond property is equivalent to the cond attribute on the SCXML <transition> element:

{
  on: {
    e: {
      target: 'foo',
      cond: context => context.x === 1
    }
  }
}
<transition event="e" cond="x == 1" target="foo" />

Similarly, the in property is equivalent to the In() predicate:

{
  on: {
    e: {
      target: 'cooking',
      in: '#closed'
    }
  }
}
<transition cond="In('closed')" target="cooking"/>

cond and In() in the SCXML specification​

State IDs​

IDs correspond to the definition of IDs in the SCXML spec:

{
  green: {
    id: 'lightGreen';
  }
}
<state id="lightGreen">
  <!-- ...-->
</state>

IDs in the SCXML specification​

Actions​

Executable actions in transitions are equivalent to the SCXML <script> element. The entry and exit properties are equivalent to the <onentry> and <onexit> elements, respectively.

{
  start: {
    entry: 'showStartScreen',
    exit: 'logScreenChange',
    on: {
      STOP: {
        target: 'stop',
        actions: ['logStop', 'stopEverything']
      }
    }
  }
}
<state id="start">
  <onentry>
    <script>showStartScreen();</script>
  </onentry>
  <onexit>
    <script>logScreenChange();</script>
  </onexit>sc
  <transition event="STOP" target="stop">
    <script>logStop();</script>
    <script>stopEverything();</script>
  </transition>
</state>

script, onentry and onexit in the SCXML specification​

Invoke​

The invoke property is synonymous with the SCXML <invoke> element:

// XState
{
  loading: {
    invoke: {
      src: 'someSource',
      id: 'someID',
      autoForward: true, // currently for machines only!
      onDone: 'success',
      onError: 'failure'
    }
  }
}
<!-- SCXML-->
<state id="loading">
  <invoke id="someID" src="someSource" autoforward />
  <transition event="done.invoke.someID" target="success" />
  <transition event="error.platform" cond="_event.src === 'someID'" target="failure" />
</state>

SCXML definition of <invoke>