Workflow

Transition rules

How do you prevent certain state changes or ensure that a team always follows the same workflow?

Let's take the example of an accounting department that manages its invoices with a computer tool.
When an order needs to be invoiced, its status changes to "To Invoice" and then to "Invoice" once the invoice is sent to the customer.
Finally, when the payment is received, the order reaches the "paid" status .

It is impossible to re-invoice an order that has already been invoiced and it is essential to never change a paid report in order to avoid accounting errors.

If a Tracker handles this type of workflow, it is therefore necessary to precisely define the allowed transitions.

For each tracker, it is possible to configure the transitions for a given field. This field must be a list field ("Selectbox").

There are two configuration modes available: a simple mode and an advanced mode.

Practical information

Configuration is done on the Transition tab of the Workflow menu.

The simple mode

By default, a workflow is created in simple mode.
In this mode, the configuration is about the states themselves. This ensures that all outbound transitions in a state share the same rules.

Warning

If you enable the "Enable Transition Rules" button, the current state of the workflow configuration is applied to users who are currently browsing the tracker.

Actions on transitions in simple mode

For each transition, the Configure Status link allows you to define:

• The user group that is allowed to change the value of the field.

• the list of fields that must be filled in to authorize the transition;

• Mandatory comment entry (except when creating an artifact)

• a series of actions (to be added by clicking on "Add an action"), such as:

  • Configure or change the value of a numeric or floating field

  • Configure or change the value of a date field

  • Trigger a job Jenkins or Hudson

  • Freeze the value of a field to prevent it from being modified in a specific state

  • Hide a group of fields to lighten the display for a given state.

Advanced mode

In advanced mode, each transition is configured individually.
The tracker administrator must therefore define the configuration transition by transition.

To enable this mode, simply select "Use Advanced Setup".

Warning

If you revert to the simple configuration mode, you lose the specific rules granted to your transitions. Thus, the first configuration of the destination state column ("In Progress" for example) will be copied for the entire state.

Actions on transitions in advanced mode

For each transition, the "Configure" link allows you to define:

• The group authorized to make the transition.

• Fields that must be filled in before the change of status.

• the requirement to enter a comment (except when creating the artifact);

• a list of possible actions, such as:

  • Configure a numeric or floating field

  • Configure a Date Field

  • Trigger a Jenkins or Hudson job.

Global rules

It may be necessary to set up certain rules on the tracker fields to avoid for example that the start date of a task is later than the closing date as shown below.

Warning

It is possible to create as many rules as you need. However, a high number of rules greatly increases the risk of a block, as it becomes more likely that at least one of them will be broken.

When a user attempts to violate a rule, they will be notified with the following message:

The modification attempted by the user will not be taken into account (the artifact will not be modified) and he will be asked to correct his error.

Field dependencies

Very often, when many fields are used, some relationships exist between them.
There are also times when certain combinations of values between two fields are impossible or must be prohibited.

For example, in a weekly activity tracker, each activity should be scheduled for one day.
Two types of activities can be entered: personal or professional.
A professional activity can be scheduled from Monday to Friday, while a personal activity must be planned only on weekends.

The configuration of these rules is done in the tracker's admin area, in the section Managing dependencies between fields.

The dependency is configured between two fields of the same tracker, provided that they are list or multiple-choice list fields.
After selecting the field that influences the second field, you just have to define the combinations of allowed values.

Once the dependency is configured, it applies when creating and editing tracker artifacts.
Any changes to the first field automatically adjust the values available in the second field.

Practical information

It is possible to configure multiple dependencies between different fields.

Triggers

Check out this article to learn more about the tracker hierarchy.

Webhooks

It is possible to configure a tracker to trigger a webhook each time an artifact is created or updated.
The configuration of webhooks is done in the "Workflow" section of the tracker administration.

Tuleap Functions

Tuleap Functions allow you to automatically run a calculation when creating or updating an artifact. This can be used, for example, to assess a risk based on several factors. This approach eliminates the need for a webhook and an external server to perform the calculation.

The executed code is a WebAssembly function (WASI Preview one) uploaded by the tracker administrator. Tuleap performs this function asynchronously after each artifact is created or updated.

For more information, please consult the technical documentation.