This article demonstrates how to create and use State Workflows, which are sometimes also referred to as state machines.
As an example, we will use the task manager from the initial tutorial.
Introduction
A state workflow defines individual states and determines how transitions between those states are allowed — in other words, which state can transition into another.
A typical use case for this functionality is a drop-down menu, where the state workflow filters the available options so that only valid target states are displayed for the current state, instead of all existing states.
A possible state change is therefore based on the current state and also on the user role, because certain transitions may be available only to specific role(s).
The list of possible states is provided by the default lookup defined for the given database field. However, for transformations, you must define all possible states using constants, which need to be created beforehand.
These state constants are used by the state workflow and by transition restrictions. This is how the state workflow is enforced in the underlying business logic — if there is an attempt to perform an invalid transition in a transformation, the system blocks it.
State workflows may also include events that trigger sequential workflows in the following situations — leaving state A, entering state B, or transitioning from state C to state D.
The state workflow and all events within it, including the individual sequential workflows, can run within a single transaction. This means that if any of the contained sequential workflows fails and the transaction is not completed successfully, the entire transaction is rolled back.
One last important detail — the default state of the workflow is named Initial.
Example assignment
We will demonstrate a simple workflow using the example of the Task Manager, where three possible statuses are defined: New, In progress, and Done.
We will restrict transitions between statuses as follows:
New→In progress– the task is taken by an assigneeIn progress→Done– the task is completedDone→In progress– the task is reopened
We could further restrict the transition from the In progress state to the Done state (or to another state such as Approved) based on a user role, for example Manager, but we will not cover that in this tutorial.
Workflow creation
To create the workflow, go to the ORIGAM Architect, open the Model Browser tab, navigate to Business Logic / State Workflows / your package, right-click your package, and choose New / State Workflow.
Here is an example of a workflow that targets the Task entity and its referential field refTaskStatusId, which contains the task status Id:
Once a database entity and its field are selected, the workflow is automatically named in the format entity_field.
States
Next, you need to define all required states. Click New / State on the workflow name, select the appropriate value for the Value field, and choose the State type — Initial, Running, Final, or Group.
In our example, we will use only the first three state types. Here is an example of the Initial state for New:
The list of possible states for the Value field is determined by the default Lookup configured for that field:
By the way, once a state workflow is assigned to a database field, there is usually no need to configure the DefaultValue property separately, because it is automatically set to the Initial state.
Transitions
The next step is to connect the defined states together by creating New / Transition on the states whose transitions to other states should be restricted.
Here is an example of a transition for a Task from the New state to the In progress state:
Workflow overview
The complete workflow may look like this:
Do not be confused by the fact that the states are listed alphabetically.
The result
After restarting the server, you can see the result in the client application, where the drop-down menu now displays only a subset of the available statuses. For example, from the New status you can transition only to the In progress status:
