Workflow

Introduction

From a user perspective the workflow mechanism provide the following features:

• Except the single "Save" button at the bottom of the record screen some new buttons appear. These button represents the possible workflow transitions. Or in the other words, the states that can be accessed from the current state. Clicking a button "X" transit the record from the current state to the "X" state.

• Some fields of the form needs to be filled before entering another state. They turns red if not filled.

• Some fields values are filled automatically when a workflow transition take place.

• The way the record is displayed (visible and editable groups and columns) can change after workflow transition. It happens because it is common to use workflow state as a match parameter for (edit rules).

Enabling workflow

In InstaDB every workflow is associated with a table or a view. To start developing a workflow first you need to enable it in the workflow section of chosen table. When enabled, the workflow section reveals the workflow parameters:

• Column - Here you need to specify which column of the table will be storing the current state of a record. Usually the column is dedicated for this purpose. Selecting a column is obligatory to complete the process of enabling the workflow.

• States - This section contains a detailed definition of states and relations (paths) between them. This is the core of workflow definition.

• Initial states - A workflow must have at least one entry point, or the initial state. You define which states can be initial in this section.

Initial states

An initial state is the first state a record achieve. It is possible to enable multiple initial states for a given workflow if needed. To mark a state as an initial state you need to add it to the list in this section.

Note that a state must be created ("states" section) before it can be add to initial states list.

Every initial state will be displayed at the bottom on the new record screen. Clicking one of them provide a record to the selected state. Note that:

• standard "Save" button disappears when a workflow is disabled (it is replaced by one or more initial states buttons);

• some buttons may not appear when a user do not fill their rules requirements (described in the further part of the article);

• new rules suggestions can setup some values in the new record form; in case of workflow it make sense if they are in the fields editable for a user;

• for fields intended as not editable using the workflow suggestions (described further, in the workflow state definition) is usually a better idea;

Definition of a state

Every workflow state is described by the following parameters:

• Name is the value which will be stored in the status column of the workflow.

• Title is the text that will be displayed on the workflow button. If the title is not set, the state name will be used.

• Rules describe when it is possible to enter the workflow state. Or, in other words, when a button leading to the state will be displayed to a user. Note that rules are used only when the target state is available from the current state (or it is one of the initial states).

• Next states are the states potentially accessible from the current state. This accessibility can be narrowed by the rules.

• Required columns are the columns that need to be filled to enter the state. If they are empty when a state button is pressed, the record will not change the state (and missing fields will be listed to a user).

• Suggestions define the values that are automatically calculated and entered into the corresponding fields when a record enter the state.

Rules

A rule define a set of conditions that must be fulfilled for a state to be accessible for a user.

Every rule is composed of two components:

• Roles (do not confuse with rules) for which the rule will be applied; you may specify multiple roles in a single rule; if no role is specified, the rule is universal for all users;

• Match is a condition the record must fulfil for application of the rule; it is defined as a pair column‑value; the column is usually an expression column; you may specify multiple matches in a single rule; if no match is specified, rule is universal for all records.

If no rule is defined for the given state, the transition is always available, if it result form "next states" or "initial states".

Next states

The next states section specify the list of states accessible from the current state. In other words, it defines edges of a graph representing the workflow.

If the list is empty the state is considered a final state.

Note that you there is no limitations of the next states. You may introduce cycles in your workflow, including smallest possible cycle, when you set a state as one of the next states of itself.

Remember that the rules of next states may limit their accessibility for a user. So a button may not be displayed even if the next states suggest that.

Required columns

This section specify a list of columns that cannot be empty when a record enters the state. If at least one of these columns is not filled, the new state will not be achieved and a user will receive the information about missing fields.

Note that an expression column may be specified in dis section, what let to provide some additional logic in the workflow.

If no column is selected, the state can be enter regardless of the record state (of course if the transition is possible according to rules).

Suggestions

Suggestions are expressions that are calculated after a record enter the state. A suggestion is composed of two components:

• Column, where the result of calculation will be stored; it cannot be an expression column;

• Expression, which result will be written to the column; expression can be a simple value or a complex select; it is useful to use the expression editor when filling this field.

You may set any number of suggestions for a single workflow state.

Note that when a suggestion is executed, the previous value of the column is overwritten.