Quick reference

This chapter gives an overview of the building blocks a statechart consists of and their semantics. It also shows the textual syntax used to express behavior inside the graphical model. If you are new to itemis CREATE, this is a good starting point to learn the main concepts. This reference also applies to former YAKINDU Statechart Tools version.

Overview of a statechart’s basic building blocks

You can download the Quick Reference as a PDF file here.

Statechart elements overview

A statechart consists of a number of different elements. The following list gives an overview of these elements in the order they are listed in the editor palette.

Statechart Element	Description
	Transitions connect states with each other. Transition reactions define under which conditions a transition is taken. Read more in section States and transitions.
	A state is the most basic building block of a statechart. A state can define reactions for when it gets entered or left. Read more in section States and transitions.
	A composite state groups a number of substates. It can be used to express state hierarchies. Read more in section Composite states.
	An orthogonal state is used to express concurrency. Read more in section Orthogonality.
	A region is a container for states and transitions. Regions can exist as top-level elements or inside of a composite or orthogonal state. Multiple regions that coexist on the same level express concurrency as in an orthogonal state.
	Entry points mark the initial state of a region. A region can have multiple named entry points to specify different execution flows. Learn more about them in section Composite states.
	A shallow history remembers the last active state inside a composite state. Read more in section History nodes.
	A deep history remembers all nested active state inside a composite state. Read more in section History nodes.
	A final state denotes the end of the execution flow. Read more in chapter final state of the complete reference.
	Exit points are used to leave a composite state and are the counterparts of entry points. Read more about them in section Composite states.
	A choice node is used to model a conditional path. Read more in section Choices.
	Synchronization nodes are used to model forks and joins in combination with orthogonal states. Read more in section Orthogonality.

Statechart definition section

The definition section of the statechart defines which entities of the statechart, like variables, events and operations, are accessible from the outside and which ones are only used internally. For this, a definition section can declare an internal scope and multiple interfaces.

Statechart interfaces

A statechart interface declares the entities that are externally visible. These are the elements by which the client code can interact with the statechart. A statechart can declare multiple interfaces with different names. The unnamed interface is also called the default interface.

Interface Element Declaration	Meaning
in event SwitchOn	Incoming event, supposed to be raised by the client code and processed by the state machine to evaluate potential state transitions.
in event Slider : integer	Incoming event with payload of type integer
out event Finish	Outgoing event, supposed to be raised by the state machine and delivered to the outside.
out event Error : string	Outgoing event with payload of type string. Can be raised by a transition or state reaction with raise Error : "Some error message"
var brightness : integer	Variable, used to store some data. Can be changed by the state machine and by the client code.
var brightness : integer = 3	Variable with initial value.
var brightness = 3	Variable with type inferred from initial value - integer in this case.
var readonly brightness : integer	Variable marked as readonly to ensure it is not changed by the client code.
const PI : real = 3.14	Constant, used to store some immutable data that is not changeable by the client code or the state machine. Constants must have an initial value.
operation average(a : real, b : real) : real	Operation, connects a state machine to the outside world by making external behaviour accessible. Implementation needs to be provided by the client code.

Typed elements must have one of the following types: integer, real, boolean or string.

Internal scope

The internal scope declares the entities that are only used internally by the statechart and hence are not visible to the outside.

Internal Element Declaration	Meaning
event Process	Internal event, can only be raised by the state machine.
var brightness : integer	Internal variable, only visible by the state machine, not by the client code.
const PI : real = 3.14	Internal constant, only visible by the state machine, not by the client code
const PI = 3.14	Internal constant, only visible by the state machine, not by the client code. The type is inferred by the initial value - real in this case
operation average(a : real, b : real) : real	Operation, connects a state machine to the outside world by making external behaviour accessible. Implementation needs to be provided by client code.
every 500ms / raise Process	Statechart reaction, is evaluated on each run cycle. Used to specify reactions that are independent of the current state.

For more details on the definition section, consult the language reference.

States and transitions

States and transitions are the basic building blocks of a statechart. States and transitions are contained in regions. At each point of a statechart’s execution, there is at most one active state per region.

States are connected by transitions. Transitions are directed, therefore states have incoming and outgoing transitions. All states must have at least one incoming transition.

Transition reactions

Transition reactions specify under which conditions a state transition is taken. Reactions have the following syntax:

trigger [guard] / effect

A state transition is taken when its trigger is raised and the guard condition is satisfied. When the transition is taken, its effect actions are executed.

Triggers

A transition reaction can specify the following triggers:

Trigger Syntax Examples	Meaning
ev1	Event trigger, triggers when the event ev1 is raised. The used event needs to be declared in the definition section.
ev1, ev2	Multiple event triggers, triggers when one of the events ev1 or ev2 is raised. The used events need to be declared in the definition section.
after 10s	Time trigger, trigger after given amount of time.
always	Always trigger, triggers always. Can be omitted when used with a guard.
oncycle	Oncycle trigger, same as always trigger.
else	Else trigger, only valid on outgoing transitions of choice states to denote the default transition if no other outgoing transition can be taken.
default	Default trigger, same as else trigger.

Guards

The reaction guard is optional. If specified, it needs to be a boolean expression. Here are some examples of valid guard conditions:

Guard Syntax Examples	Expression Kind
[var1 && !var2]	Logical AND, OR, NOT
[var1 > 0 && var1 <= 10]	Logical comparisons <, <=, >, >=
[var1 == 10 && var2 != 17]	Logical equality or inequality
[isOdd(var1)]	Operation calls with boolean return type
[var1]	Boolean variables or constants

Effects

The reaction effect is optional. If specified, the effect is executed when the transition is taken. Multiple effects are separated by a semicolon. The last effect has no trailing semicolon.

Effect Syntax Examples	Meaning
/ var1+=10; var2=var1	Variable assignment
/ calculate(var1, var2)	Operation call
/ raise ev1	Event raising
/ raise ev2 : 42	Event raising with payload
/ var1 > 10 ? var1=0 : var1++	Conditional expression
/ var1 << 8	Bit shifting

State reactions

A state can also define reactions. The syntax is the same as for transitions. In addition to the above mentioned examples, a state can also define entry and exit reactions.

State Reaction Examples	Meaning
entry / var1=10	Entry reaction, is executed when the state is entered.
exit / var1=0	Exit reaction, is executed when the state is exited.
ev1 / var1+=1	Local reaction, is executed when no outgoing transition can be taken.

Built-in functions

The statechart language comes with two built-in functions that can be used inside a guard or effect expression:

Built-in Function	Meaning
event.value	Returns the payload of an event. Note, that the event needs to be raised when .value is called.
valueof(event)	Same as the one before except member acces is not available if the payload is some complex type. This expression will be deprecated in the future.
active(state)	Returns true if the given state is active, otherwise false. This function is especially useful in combination with orthogonality.

Basic execution flow

When a state transition occurs, the specified reaction effects are executed in a defined execution order:

1. All source state’s exit actions are executed
2. All transition actions are executed
3. All target state’s entry actions are executed

Consider the following simple example:

When StateA is entered, its entry reaction is executed first ( a=1). When event ev1 is raised, the transition towards StateB is taken. As StateA is left, its exit reaction is executed ( b=1) before the transition reaction is executed ( c=1), following by entering StateB and executing its entry reaction ( d=1). While StateB is active, each time the event ev1 is raised, the state’s local reaction is executed ( d++). Note, that this is a different behavior compared to StateB having an outgoing transition pointing to itself, as taking such a self-transition would also invoke the state’s exit and entry reactions. Finally, when event ev2 is raised, StateB is left and its exit reaction is executed ( e=1, followed by the transition’s reaction ( f=1), and StateA's entry reaction ( a=1).

Choices

A choice is a pseudo state. It is used to model a conditional path. If a choice’s incoming transition is taken, its outgoing transitions are immediately evaluated to decide which path to take. To ensure there is always a valid path, a default transition can be defined with the trigger else or default.

Composite states

itemis CREATE allows the user to express state hierarchies by the means of composite states and subdiagrams.

A composite state is a state that contains one or more other substates. It can be used to group states into logical compounds and thus make the statechart more comprehensible.

When a composite state is entered, its entry node denotes the substate to be activated. A composite state can specify multiple entry nodes with unique names. Incoming transitions of the composite state can specify the desired entry node to take for entering the composite state.

When a composite state is left, all active substates are also left. A composite state can specify multiple exit nodes with unique names. Outgoing transitions of the composite state can specify the relevant exit node for them.

The syntax for referencing entry or exit points in a transition reaction is the following:

Transition Reaction Examples	Meaning
# > entry-point-1	Enters the target composite state by the entry point entry-point-1
# exit-point-1 >	Exit the composite state by this transition if exit point exit-point-1 is active
# exit-point-1 > exit-point-2 >	Exit the composite state by this transition if one of the exit points exit-point-1 or exit-point-2 is active

Parent-first vs. child-first execution

The parent-first and child-first execution schemes define in which order a composite state and its substates are processed:

• In the parent-first execution scheme, the composite state (parent) is processed first, before its substates are processed.
• In the child-first execution scheme, the active substate (child) is processed first, before its parent composite state is processed.

Consider the previous example model. When state A1 is active and the event ev1 is raise, it depends on the execution scheme whether the transition to state B2 (child-first execution) or the one to state End1 (parent-first execution) is taken.

The execution scheme is specified by the @ParentFirstExecution resp. @ChildFirstExecution annotation in the definition section. For more details, take a look at the language reference.

Orthogonality

itemis CREATE allows the user to specify orthogonal regions that are executed virtually concurrently. Orthogonal regions can be modeled either on top level, or within a composite state (or subdiagram). They allow to describe that the modeled system can be in multiple states simultaneously.

Orthogonal regions are executed in a deterministic sequential order and not in parallel as one might expect. The execution order is defined by the regions' priorities. These are indicated in the top left corner of a region. The defined execution order plays a particular role when orthogonal regions raise and react to the same events. For more details, see also chapter Raising and processing an event.

Synchronizations (forks and joins)

Orthogonal regions can be defined on top level or within composite states. The semantics explained above are the same. The example model above uses a synchronization node to fork the execution flow into both orthogonal regions r1 and r2. After both regions have executed their state transitions, the execution flow is joined again by a synchronization node. A joining synchronization is only executed when all incoming transitions can be taken within the same run-to-completion cycle. Read more about synchronization nodes in the language reference.

History nodes

A shallow history state is a pseudo state that is placed inside the region of a composite state. It is used to remember the last active state inside a composite state. This makes it possible to jump back to the remembered state instead of starting at the initial substate again.

A deep history state is similar to a shallow history state, but more complex. With a deep history state, the latest status of all nested states is remembered.

Final state

A final state denotes the end of the execution flow of a state machine or region. It can have multiple incoming transitions but no outgoing ones. Each region may contain at most one final state. In the case of orthogonal regions, the execution flow stops when all regions' final states have been reached. A statechart is final if active leaf states are final states. Final states are typically used together with completion transitions .

Event-driven vs. cycle-based execution

The state machine can define one of two different execution schemes:

• In the cycle-based execution scheme, a run-to-completion step is executed periodically in regular time intervals.
• In the event-driven execution scheme, a run-to-completion step is executed each time an event is raised.

The execution scheme is selected in the definition section by either using the @CycleBased or @EventDriven annotation. If nothing is specified, the cycle-based execution scheme with a time interval of 200 milliseconds is used for simulation. For a better understanding, see also this example, or the more elaborate explanation in the language reference.

Completion transitions

Completion transitions enable a transition to occur automatically when a state’s activities are completed or when all of its child states have completed their activities. This means that instead of explicitly triggering a transition with an explicit event, completion transitions are triggered internally by the implicit completion event which is derived from the completion status of the state or its children. This can be very helpful in situations where the statechart models activity sequences or processes which can terminate or complete. Completions transitions are typically used with composite states which contain regions whith behavior that completes with a final states. Composite state which have only final states as active substates are considered as completed. Completion transitions react to completion events which indicate that the state completed. Let’s take a look at the following example.

The example defines a state Complex Task which controls a process consisting of two parallel activities A and B represented by the two subregions. As soon as both activities are finished by entering their final states then Complex Task becomes completed and a completion event is raised which triggers the completion transition to Done state. Completion transition by definition have no trigger and no guard but may define a transition action. This example also shows that leaf states (non composite states) like state Step A can define completion transitions. Here the local completion transition to the final state is automatically taken without any delay. This is useful if a sequence of steps which follow each other immediately and unconditionally should be modeled. So completion transitions help in modeling processes and activities using state machines.

Beyond this example there are several other details you should know about completions transitions. Completion transitions are immediately taken when the transition’s source state is " completed" and they have priority over any other events, thus they are dispatched before any other pending event occurrences in the event pool.
This also means that these kinds of transitions implicitly raises completion events, which are raised and consumed throughout the statechart’s execution (and with that, they are present in the code generated from it).

A state is considered completed when all of its entry actions are executed (if there are any). A Composite states is considered completed when all of its subregions reach their final state . This means completion transitions can only be used with composite states if all subregions contain a final state.

Completion transitions can’t be used with source states that contain local reactions. Those states do not complete and adding a completion transition is considered as an error. A validation check will add a error message: “Completion transition is not allowed with local reactions”.

Defining other transitions with trigger(s) from the same leaf state as the completion transition will raise a warning with a message: “Dead transition. This transition can not be taken due to completion transition.” This is because these will never be taken due to the precedence of the completion transition. Also defining multiple completion transitions from the same state will result in a warning for both transitions with the message: "Multiple completion transition. There should be only one completion transition from state ..."

This feature is compatible with OMG UML 2.5.1 specification. (For more details please see the corresponding documentation under chapter 14.2.3.8.3)