State Transitions
Trackers, where Workflow is enabled, have State Transitions
, that define a Finite State Machine for the tracker items.
This allows fine grained control over the tracker item lifecycle (business processes) and associated work flow.
For example:
A customer or a test engineer can directly enter bugs into a tracker, and developers (one developer, or all belonging to a role) are automatically notified about the bug. A developer can fix the bug, associate the source code changes with the bug, and set the bug status to fixed. The source code change association with the bug is typically performed by associating a commit with the issue. Team members' project roles determine which notifications they receive in this corrective process.
The two basic elements are:
- State
This is equivalent with the concept of a node in a graph.
- Transition
This is equivalent with the concept of a directed edge in a graph.
State
Basically State comprises of all field/attribute values of a Tracker Item, but in this context:
- the current state of a tracker item is defined by the (value of the) choice field Status,
- and a State transition is really a Status transition (A value change of the Status field).
Consequently, the possible States of a Tracker Item are the defined values (choice options) of the Status field:
For example: The default Status Options for trackers of type Task:
The order of status options should reflect the position of this status in the lifecycle of the tracker items.
State Transition
A value change of the Status field is called a State Transition from the old status to the new status.
If Workflow is enabled for a Tracker, then only those Status changes are allowed,
- where an appropriate state transition (from old to new status) is defined
- and the current user is permitted to execute that state transition.
If Workflow is not enabled for a Tracker, then the tracker items still have a Status, but there is no control
- which status changes are allowed
- and who can make them.
The (allowed) state transitions for items of a specific Tracker are defined on the State Transitions tab of the tracker's configuration screen. E.g.:
Check the "Show obsolete states" to see all states.
If a state is obsolete then the name contains the "(Obsolete)" suffix.
The State Transitions will also be visualized as a State Diagram:
To define a new state transition, click on Add Transition.... This will open a dialog, where you can enter the transition specification:
You must specify the From and To status for the transition:
- Because a transition is a status change, From and To must be different.
- There can only be one transition with the same From and To status per tracker.
There are two special From status values:
- --
This value represents the unknown/undefined/non-existing status of a tracker item.
- ***
This value represents any status (except the To status)
There should be exactly one state transition from "Undefined/--" to a defined/initial status!
This is the initial state transition, that controls the process of creating new tracker items:
- All newly created items will have the specified initial status.
- Only users with permission for the initial state transition can create new items.
They still must also have Issue - Add permission on the tracker.
If there is no initial state transition at all, creating tracker items will not be allowed!
Caution!
For legacy reasons, it is possible to define multiple (ambiguous) state transitions from "Undefined/--" to different states. In this situation:
- newly created items will end up in no defined status ("Undefined/--"),
- which should never occur under regular conditions.
State transitions also have a
- Name (required)
There can be multiple transitions with the same name.
- Description (optional)
This could be some instructions for the user invoking the transition.
- Permitted
defines which Participants (e.g. Item Submitter or Assignees) and Roles (e.g. Members in role Developer) are permitted to execute this status change.
- Condition (optional)
defines in which context/for which tracker items this transition is applicable at all.
- Guard (optional)
is a gate keeper, that will only let pass transitions, if the subject tracker item matches specific criteria.
- Actions (optional)
are the 
Workflow Actions to execute upon this transition.
State transitions can be Hidden, which means they will not occur in the Next Steps/Transitions menu, but are still valid status changes.
The names of hidden transitions will be shown in gray instead of blue (see Approve and Reject in the screenshot below).
To Edit an existing state transition, either click on the transition name, or choose Edit from the context menu:
To Delete a defined state transition, choose Delete from the context menu.
Transition Condition
The optional Condition defines, in which context/for which tracker items the transition is applicable at all.
The only available default Condition is:
which allows to define a formula/expression (see Computed Fields), that will be evaluated against a tracker item, and that must yield true or false, whether or not this transition is applicable for this item.
For example: Only allow this transition, if the Story Points field of the item has a value less than 7:
storyPoints < 7
Since CB-7.9.2, there is an additional default condition: Leads back to previous item status
that will only allow this transition, if it leads back to the previous status of the subject item.
The typical use for this condition is for transitions out of special parking states, where multiple transitions lead into this state and there are also multiple transitions out of this state, and you want to restrict an outgoing transition to only be applicable, if the state was entered via a transition in the opposite direction.
If you need conditions, that exceed the expression language capabilities or need to consider other context information like
- the HttpServletRequest (to check region, locale or user agent)
- or the current user (to check other user attributes, than the transition permissions, which have already been checked before checking the condition)
then you can implement a custom condition. See instructions here.
Transition Guard
Each transition can be associated with a Guard, which will only let the transition pass if the subject tracker item matches specific criteria.
A transition guard is a tracker view, whose Condition will be evaluated against the tracker item which is the subject of the state transition.
The Guard selector shows all available tracker views in the current context.
If no suitable guard/view exists yet, you can create a new one by right-clicking on the guard selector and choosing New from the context menu:
For example, All approvals are finished and accepted from Forking sub-processes from processes (work items):
The new guard will be stored as a tracker view of the type Table with the configured Condition and Default Columns and Sorting.
You can edit the currently selected guard by right-clicking the guard selector and choosing Edit from the context menu.
From codeBeamer 9.4.0, you can use also "suspected reference" guards:
- Has Suspected Link
- Has Upstream Suspected Link
- Has Downstream Suspected Link
Please note: Guards evaluate stored field values which may differ from what is rendered on the user interface. For example, wiki content is stored as its markup code potentially containing formatting and escape characters. That has to be taken into account when defining guard conditions.
Transition Actions
Since CB-7.8, multiple Workflow Actions can be associated with a state transition.
The Fields to Update from older CodeBeamer releases are now also actions:
Caution!
Old pre-CB-7.8 Actions implementing StateTransitionAction or based on DefaultWorkflowListener are not longer supported in CB-7.8 or newer!
Any attempt to deploy such old actions via ~/CB-.../tomcat/webapps/cb/WEB-INF/classes/my-applicationContext.xml will cause the CodeBeamer startup to fail.
If you had developed custom actions, you should first check, whether one of the new parameterizable Workflow Actions can be used for this task:
Only if no such action exists, you should try to migrate your custom action. See instructions here.
Watch a video on workflows here.
to log in.
anonymous
Hotkeys