A cluster is a grouping of states. There are two main reasons why a grouping of particular states might be beneficial within a workflow. It may be useful for purely administrative reasons, making it possible to easily monitor a section in a workflow, or it may be used in conjunction with other clusters inside of a parallel, which is the more likely use case. For whatever the reason may be, it is important to know how to clusters work and how to create them.
Creating and Entering Clusters in Workflow
Any state can have the cluster characteristic added to it. This means that the particular state can have sub-states. The first sub-state in a cluster has to be an Initial state in order for the workflow to be valid. This means that there could be multiple states in a workflow with the characteristic of Initial state.
Note: For more on the Initial state, refer to Initial and Final States in a Workflow in the Workflows documentation
It is important to note that states with cluster characteristics are still states in their own right. If an object is in a cluster sub-state, it is also at the same time in the state with the cluster characteristic.
If a state with a cluster characteristic contains sub-states, the cluster characteristic cannot be deselected in the State Editor.
In looking at the following cluster, it is important to know how an object placed into the workflow would move through it.
- After entering into the 1st Initial State, an object enters into the 2nd State, which also happens to be a cluster.
- Once in the cluster, the object also simultaneously enters into the 3rd State-Initial.
- It then proceeds through the next ordered steps until it reaches the End Inside Cluster (Final state). Because this is inside of a cluster, there is a transition allowed out of this Final state (which is different than what is allowed for the ultimate Final state of a workflow). In this case, it exits not only the End Inside Cluster (Final state), but it also exits the entire cluster and goes to the 7th State.
- From the 7th State, it proceeds to the End of Workflow (Final state). The object has reached the end of the workflow.
Exiting a Cluster in a Workflow
When exiting a Final state in a cluster, the name of events on transitions can aid with the progression of the workflow. If an event on a transition has the naming formula of 'cluster state ID.done' the transition out of the Final state with the cluster characteristic to the next state will be triggered automatically.
For example, in the picture below, the name of the event on the transition from End Inside Cluster (which has the characteristic of a Final state) to 7th State is being named. Following the formula to trigger the transition automatically, the name takes on the 2nd State cluster's ID followed by '.done'.
This is useful for clusters that have their last state in the cluster with the characteristic as Final state, such as the one in the example. Normal functionality dictates that an object in a Final state would stay there until it is manually taken out or there is special coding set up to take the object out of the workflow automatically. However, with this naming system there is no need for a manual removal or special configurations to progress the object through the workflow. This naming configuration allows the object to leave the Final state within the cluster, and also leave the cluster state itself.
The system will always look for a transition out of a cluster that has an event name of 'Cluster ID.done'. If there is not a transition found with this name, the system will look for a transition out of the cluster with no named event and perform that transition.
If there are two or more transitions out of the cluster that all have either the 'Cluster ID.done' event name or no named events, the system will randomly perform one of the transitions unless conditions on the transitions determine which one to perform.
If there are only transitions with named events different from 'Cluster ID.done' out of the cluster, objects will remain in the Final state and can only be progressed by triggering events on the cluster state.
Note: Prefixing an event on a transition with the ID of the state from which the transition goes and a dot ('.') will cause the event to be hidden to users working with the workflow in the workbench. This approach should therefore be used whenever you have a 'system' event that should not be triggerable by human users.
The image below shows an alternate way of configuring a cluster and transition relationship. There is no Final state inside the cluster. Instead there is a transition directly from End Inside Cluster to 7th State outside the cluster.
When this transition is performed, the object will exit both the End Inside Cluster state and the 2nd State cluster. While this configuration is perfectly valid, generally the first type of state setup with a Final state and transition is recommended.
