Workflows

Card key

docs_26

Status

Ready

Card type

base/cardTypes/page

Labels

Owner

N/A

Information classification

public

Introduction

A workflow defines the states and state transitions that cards move through during their lifecycle.

For example, a task workflow could consists of the states and transitions Open → In Progress → Done, and a document workflow could be defined as Draft → Approved → Archived.

Managing workflows using the Cyberismo command line tool

To see a list of the available workflows, use the following command:

$ cyberismo show workflows

The names of workflows are of the format module/workflows/workflow, for example base/workflows/decision.

To see the help for how to create a workflow, use the following command:

$ cyberismo create workflow --help

To create a new workflow, for example myWorkflow, use the following command:

$ cyberismo create workflow myWorkflow

Cyberismo will create a new file called myWorkflow.json in .cards/local/workflows/myWorkflow.json. If the card prefix of your Cyberismo project is example, then the full name of the new workflow will be example/workflows/myWorkflow.

When choosing a name for your workflow, see Naming conventions.

To finalise the workflow definition, you need to edit the myWorkflow.json file with a text editor.

Workflow file format

Workflows are defined in JSON files that follow the workflow schema, as described in the following tables.

Basic structure of a workflow definition

Table 1. The properties of a workflow
Property	Type	Description	Required
name	`string`	The name of this workflow	✓ Yes
states	`object` `[]`	The states of the workflow, see below.	✓ Yes
transitions	`object` `[]`	The state transitions of the workflow, see below	✓ Yes

Additional properties are not allowed.

Workflow states

The states property of a workflow is an array of objects that have the following properties:

Table 2. Properties of the items in the states array
Property	Type	Description	Required
name	`string`	A string that identifies the workflow state.	✓ Yes
category	`string`	One of the following values: "initial", "active", or "closed". The category of the workflow state is used for visualising the state of the card on broad terms.	✓ Yes

Workflow transitions

The transitions property of a workflow is an array of objects that have the following properties:

name: A name that identifies the workflow transition. Required.
fromState: An array of state names, where this transition can start from. Each item of the array is a name of the starting state of the transition. The wildcard '*' denotes any state and and empty value denotes the transition to create a new card with this workflow. Required
toState: A string that is the name of the end state of the transition. Required.

Table 3. Properties of the items in the transitions array
Property	Type	Description	Required
name	`string`	A string that identifies the workflow transition.	✓ Yes
fromState	`string []`	An array of state names, where this transition can start from. Each item of the array is a name of the starting state of the transition. The wildcard '*' denotes any state and and empty string denotes the transition to create a new card with this workflow.	✓ Yes
toState	`string`	A string that is the name of the end state of the transition.	✓ Yes