Workflow Configuration

Workflows are a digitised representation of the governance path or lifecycle of an entity that is tracked in the platform. For example a holiday request form collects details of the person requesting the holiday and the dates being requested. The associated workflow defines the lifecycle of the request following submission which in this case would typically include an approval step.

Workflows are always associated with a form. Workflows are modelled in the Process Template Editor for the associated form template.

Introduction to the workflow editor

The workflow editor is part of the process template editor. This is accessed from the Process Templates Dashboard, either by clicking on an existing template or by clicking on the '+' icon to create a new one.
Once in the process template editor, click on the 'Workflow' tab to access the editor.
As the workflow gets larger through adding steps and transitions it may be necessary to zoom in and out. Use the zoom slider to the top left of the grid to zoom in and out. The vertical and horizontal scroll bars can also be used to navigate around the workflow.
There are no specific requirements for how the workflow should be structured, whether it be left to right or top to bottom. Bear in mind that the workflow can be viewed when an end user select the 'Graphical View' option on the form, so it makes sense to structure the flow so that it is as user-friendly to read as possible.

Workflow Step Types

Workflows can be made up of various different step types which perform a specific function or logical operation. Certain workflow step types will be more suitable than others depending on the behaviour required by the Workflow at that particular point in the process

Adding a workflow step

The different step types are presented in a list at the top of the workflow editor.
Click on a step type to add a new step of that type. When adding an execution step a pop-up window will display requesting confirmation of which type of execution step is to be added. Refer to the section Execution steps for further details.

Editing a workflow step

To edit a workflow step click on the step.
The step will be surrounded by a circle with 3 icons. Click on the icon with 3 stacked lines to edit the settings for that step.
The settings will depend on the type of step. Refer to the sections below for the settings relevant to each step.

The start step

The start step represents the starting point for the workflow. The start step cannot be deleted and there is only one start step.
When the process template is first created a default workflow is created comprising a start step and an end step with a close transition between the two steps.
Once steps have been added to the workflow editor the default close transition between the start and end step should be deleted. Click on the 'Close' transition to put it in edit mode (indicated by a circle).
Click on the bin/trash can icon to delete the transition.
Click on the circular start step to put it in edit mode. The step is surrounded by a wider circle with a single arrow icon.
Click on the icon with the arrow to add a transition which represents an outcome. A transition is added with a green dot in the center and a wider circle around it.
Drag the green dot to whichever will be the first step following submission. The transition is connected to the target and has the label 'New Transition'.
Click on the 'New Transition' label to edit the transition. A circle is placed around the transition with 3 icons. Click on the icon with 3 stacked lines to edit the settings for transition. In the pop-up settings window, set the values as follows:

End steps

End steps mark the end of a workflow and closure of the form.
A single end start is created by default when a process template is created. It is linked to the start step with a 'Close' transition that should be deleted as described above.
A workflow should have at least one end step and can have multiple end steps. The reason multiple end steps are supported is to enable different closure statuses. For example it may be desirable to close a form with two possible statuses: 'Closed (Approved)' and 'Closed (Rejected)'.
If the outcome of a workflow step results in closure of the form, then a transition should be added between that step and an end step.
To add end steps click on the 'End' option in the list of the workflow step types at the top of the workflow editor.
Once added click on the step in the workflow editor. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with 3 stacked lines to edit the settings for that step. The following settings should be set:

Decision steps

Introduction

Decision steps require a person to make a decision, the outcome of which will determine what happens next in the workflow.

Basic decision step information

To edit the decision step settings click on the step in the workflow editor. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with 3 stacked lines to edit the settings for that step

Defining who can make the decision

To define who can act on the decision step click on the step in the workflow. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with 3 stacked lines to edit the settings for that step.
From the pop-up settings window, select the 'Access' tab. The table below shows the options for access.

As can be seen from the table above, it is not possible to specify a named user in the decision step, only a dynamic one based on a field on the form. The reason for this is that it is not recommended practice to name individual users inside a workflow in case that user changes role or leaves the organisation, in which case the workflow has to be re-configured for the new user.
If a single user is required, the recommended approach is to create a security group for that single user and reference the group on the step. In the event that the user changes role or leaves the organization, the group can simply be amended rather than having to reconfigure the workflow.

Defining what decisions can be made

Before being able to configure the possible outcomes of a decision step it is necessary to have already added steps which will be followed for each given outcome. For example if the outcomes of an approval step are 'Approve' and 'Reject' where the approval results in a project baseline being taken and the reject routes to a rework step, the two steps (baseline and rework) must already have been added to the workflow editor.
To define the possible outcomes of a decision step click on the step in the workflow. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with arrow to add a transition which represents an outcome. A transition is added with a green dot in the center and a wider circle around it.
Drag the green dot to the target step which follows the decision outcome. The transition is connected to the target and has the label 'New Transition'.
Click on the 'New Transition' label to edit the transition. A circle is placed around the transition with 3 icons. Click on the icon with 3 stacked lines to edit the settings for transition. In the pop-up settings window, set the values as follows:

Repeat the above steps for each of the possible decisions to be made.
If a decision step has multiple transitions with the same transition name which transition to separate steps then both those steps will be initiated.
Multiple transitions can be added with the same outcome. For example a decision step 'Submit Gate Approval' might have a single decision outcome 'Submit' which the person preparing for the approval clicks on when ready for submission and once submitted approval is required by a person from 3 separate groups. and these happen in parallel there would be 3 transitions from the step, all with the same transition name (in this case 'Submit') each one going to a separate step handling approval from that group.

Execution steps

Introduction

Execution steps bring automation capability to a workflow. Commonly used scenarios for execution step are:
- Creating a form from another form, for example because a project risk has materialized and needs to be turned into a project issue.
- Creating baselines of the project work plan, resourcing plan and/or financial plan following approval
- Creating a project following approval of a proposal/project business case
- Using an SQL statement to automatically set the value of a field on a form, for example to calculate a risk score based on impact and likelihood.
- Calling a script which calls an integration with another system.

Creating a new form as a copy of the current one

This type of execution step automatically creates a new form in the system. The new form can be a different process template to the one initiating the copy.
Form field values will be copied to the new form provided the two fields have the same token. For example, if a risk form has an execution step to create an issue and both process templates have a field 'Impact' with token IMPACT then the impact field will be copied. If both forms have a field labelled 'Impact' but the token on the risk is RISK_IMPACT and the token on the issue is ISSUE_IMPACT, the value will not be copied.
When adding a new execution step, select 'Copy Form' as the type. A new step is added with a pair of cogs as the icon.
Edit the step by clicking on the step. The step is circled and has multiple icons. Click on the icon with 3 stacked lines to edit the settings for that step.
Set the Info section as follows:

Do not use this approach to create a project from a proposal. There is a separate execution type to create projects.

Baselining a project

This type of execution automatically creates a baseline for a project.
When adding a new execution step, select 'Baseline Project' as the type. A new step is added with a pair of cogs as the icon.
Edit the step by clicking on the step. The step is circled and has multiple icons. Click on the icon with 3 stacked lines to edit the settings for that step.
Set the Info section as follows:

Creating a project

This type of execution step automatically creates a new project in the system. It is most commonly used in a proposal or business case workflow to create the project entity when the proposal/business case is approved.
Form field values will be copied to the project where the project fields have the same token as the form initiating the creation of the project. For example, if a proposal form and project form both have a field 'Business Sponsor' with token BUSINESS_SPONSOR, then the person acting as the business sponsor will be copied.
When adding a new execution step, select 'Create Project' as the type. A new step is added with a pair of cogs as the icon.
Edit the step by clicking on the step. The step is circled and has multiple icons. Click on the icon with 3 stacked lines to edit the settings for that step.
Set the Info section as follows:

SQL

This type of execution step runs an SQL statement against the database. It is most commonly used to automatically update fields on a form
When adding a new execution step, select 'SQL' as the type. A new step is added with a pair of cogs as the icon.
Edit the step by clicking on the step. The step is circled and has multiple icons. Click on the icon with 3 stacked lines to edit the settings for that step.
Set the Info section as follows:

update form_fields ff set

ff.hidden_value_5 = (select * from

(select

case

when ifnull(round(ff.hidden_value_6*ff.hidden_value_7,2),0) >= 12 then 'RED'

when ifnull(round(ff.hidden_value_6*ff.hidden_value_7,2),0) between 6 and 11 then 'AMBER'

else 'GREEN'

end

from form_fields ff

join forms f on ff.form_id = f.id and batch_num = 0

where f.id = [P.FORM_ID]) x),

ff.visible_value_5 = (select * from

(select

case

when ifnull(round(ff.hidden_value_6*ff.hidden_value_7,2),0) >= 12 then 'Red'

when ifnull(round(ff.hidden_value_6*ff.hidden_value_7,2),0) between 6 and 11 then 'Amber'

else 'Green'

end

from form_fields ff

join forms f on ff.form_id = f.id and batch_num = 0

where f.id = [P.FORM_ID]) x)

where ff.form_id = [P.FORM_ID] and batch_num = 0

Call script

This type of execution step executes a linux bash script. The script must be placed in the correct location on the server. The correct location for the script is a Server Properties setting with the key WORKFLOW_SCRIPT_PATH.
When adding a new execution step, select 'Call Script' as the type. A new step is added with a pair of cogs as the icon.
Edit the step by clicking on the step. The step is circled and has multiple icons. Click on the icon with 3 stacked lines to edit the settings for that step.
Set the Info section as follows:

Handling the outcome of execution steps

Execution steps always have two possible outcomes: 'Success' or 'Error'. Good practice dictates that both should be handled within the workflow otherwise the form cannot progress beyond the step.
Before being able to configure the possible outcomes of a execution step it is necessary to have already added steps which will handle the possible outcomes. Either separate steps can each handle the 'Success' or 'Error' or one step can handle both outcomes.
To define the possible outcomes of a execution step click on the step in the workflow. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with arrow to add a transition which represents an outcome. A transition is added with a green dot in the center and a wider circle around it.
Drag the green dot to the target step which follows the execution outcome. The transition is connected to the target and has the label 'New Transition'.
Click on the 'New Transition' label to edit the transition. A circle is placed around the transition with 3 icons. Click on the icon with 3 stacked lines to edit the settings for transition. In the pop-up settings window, set the values as follows:

Repeat the above steps so that both 'Success' and 'Error' are handled. If 'All Results' is selected then only 1 transition is required.

Evaluation Steps

Introduction

The purpose of evaluation steps is to provide routing capability to workflows based on the value of a field in a form. For example, there may be a requirement for a issue form to follow a different path depending on its priority.
Evaluations can be based on text values or mathematical expressions.

Defining the evaluation statement

Add the evaluation step as described in the section Adding workflow steps
Edit the step by clicking on the step. The step is circled and has multiple icons. Click on the icon with 3 stacked lines to edit the settings for that step.
Set the Info section as follows:

Handling the results of the evaluation

Before being able to configure the possible outcomes of a evaluation step it is necessary to have already added steps which will handle the possible outcomes. For example if a form should route to 'Step A' when the priority is critical and 'Step B' for all other priorities then both 'Step A' and 'Step B' must already be defined on the workflow editor.
To define the possible outcomes of a execution step click on the step in the workflow. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with arrow to add a transition which represents an outcome. A transition is added with a green dot in the center and a wider circle around it.
Drag the green dot to the target step which follows the execution outcome. The transition is connected to the target and has the label 'New Transition'.
Click on the 'New Transition' label to edit the transition. A circle is placed around the transition with 3 icons. Click on the icon with 3 stacked lines to edit the settings for transition. In the pop-up settings window, set the values as follows:

Advanced Routing - Evaluation Steps with SQL Execution Steps

To perform advanced routing, use an SQL execution step to perform a calculation and storage of a value, followed by an evaluation step to route based on the value.
Here is an example of routing based on whether a date in a field on the form is in the past. The SQL execution step is set up with the following update statement to store the result in a separate field called 'Is Future?' (stored in parameter 9). If the date is in the future it will return 1, otherwise it will return 0.

update form_fields ff

set hidden_value_9=datediff(str_to_date(visible_value_3, '%d-%b-%Y'),now()) > 0,

visible_value_9=datediff(str_to_date(visible_value_3, '%d-%b-%Y'),now()) > 0

where batch_num=0

and form_id='[P.FORM_ID]'

Following the execution step, an evaluation step is used to evaluate the field just updated.
The evaluation step will set the evaluation statement to: '[P.FUTURE]'
There will be two transition steps fro the evaluation step, one with name: =1 and another with name =0.

Handling multiple approvals - AND and OR steps

Introduction

A common scenario is the case where a form is submitted for approval and approval is required from multiple separate groups. For example a business case is submitted for approval and needs to be signed off by someone from the 'Business Change' team, someone from the 'Technical Team' and someone from the 'Information Security' team. This is not a sequential sign-off but one that happens in parallel.
Execution steps can also be handled in parallel although this scenario is less common. Usually execution steps take only a short amount of time so can be run sequentially.
When workflows involve parallel steps, the outcomes of these should be handled appropriately with the use of AND and OR steps.

Initiating multiple approvals

To initiate multiple approvals the same transition from the initiating step should be repeated to each of the approval steps.
Refer to the section Defining what decisions can be made above.
An example is shown below for the scenario where 3 separate groups are required to approve in parallel. All the steps shown in the example are decision steps.
When selecting a status for the steps running in parallel it is recommended to use the same status across all the steps. Selecting different statuses may result in inconsistent results.

Using an AND step to wait for all multiple approvals to complete

The AND step waits for a response from all the parallel streams before proceeding. The image below extends the example above to include the AND step.

Add the AND step as described in the section Adding workflow steps
Edit the step by clicking on the step. The step is circled and has multiple icons. Click on the icon with 3 stacked lines to edit the settings for that step.
Set the Info section as follows:

There is only a single outcome from an AND step which is 'All Results'
Before being able to configure the possible outcomes of the AND step it is necessary to have already added the step(s) which should succeed the AND step.
To define the possible outcomes of an AND step click on the step in the workflow. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with arrow to add a transition which represents an outcome. A transition is added with a green dot in the center and a wider circle around it.
Drag the green dot to the target step which follows the execution outcome. The transition is connected to the target and has the label 'New Transition'.
Click on the 'New Transition' label to edit the transition. A circle is placed around the transition with 3 icons. Click on the icon with 3 stacked lines to edit the settings for transition. In the pop-up settings window, set the values as follows:

Using an OR step to wait for one of multiple approvals to complete

The OR step waits for a response from the parallel streams before proceeding. The OR step is triggered as soon as one response is received. The image below extends the example above to include the OR step.If any of the approval groups rejects the entity it is routed back to the submission stage.

Add the OR step as described in the section Adding workflow steps
Edit the step by clicking on the step. The step is circled and has multiple icons. Click on the icon with 3 stacked lines to edit the settings for that step.
Set the Info section as follows:

There is only a single outcome from an OR step which is 'All Results'
Before being able to configure the possible outcomes of the OR step it is necessary to have already added the step(s) which should succeed the OR step.
To define the possible outcomes of an OR step click on the step in the workflow. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with arrow to add a transition which represents an outcome. A transition is added with a green dot in the center and a wider circle around it.
Drag the green dot to the target step which follows the execution outcome. The transition is connected to the target and has the label 'New Transition'.
Click on the 'New Transition' label to edit the transition. A circle is placed around the transition with 3 icons. Click on the icon with 3 stacked lines to edit the settings for transition. In the pop-up settings window, set the values as follows:

Workflow step security

Introduction

Workflow step security defines who has the ability to action a workflow step.

Accessing workflow security settings

With the exception of the start step, all types of workflow steps support the ability to define who has the ability to act on a step.
The security for the step is accessed by clicking on the step to put it in edit mode and then clicking on the icon with 3 stacked lines to edit the setting.
Once the settings window is open, click on the 'Access' tab to edit security.

Security setting options

The options for setting security on workflow steps is as follows:

As can be seen from the table above, it is not possible to specify a named user in the decision step, only a dynamic one based on a field on the form. The reason for this is that it is not recommended practice to name individual users inside a workflow in case that user changes role or leaves the organisation, in which case the workflow has to be re-configured for the new user.
If a single user is required, the recommended approach is to create a security group for that single user and reference the group on the step. In the event that the user changes role or leaves the organization, the group can simply be amended rather than having to reconfigure the workflow.

Types of steps require security

The following table shows when security access should be defined for each type of step

Sending email notifications

All Workflow Steps can be configured to send email notifications to recipients to inform them of a decision that they need to make or keep them up to date on general progress of the business process.
Email notifications for a workflow step can be managed by clicking on the workflow step to place it in edit mode then clicking on the icon with 3 stacked lines to edit the setting.
Once the settings window is open, click on the 'Email' tab to edit email notifications for that step.
Click on the '+' icon to add a new recipient or simply edit and existing one.
In each case select an email template to use for the email. Email templates are defined using the email templates dashboard.
The following table shows the recipient types

Transitions between workflow steps

Introduction

Transitions represent the path that a form follows when progressing from one workflow step to another. Transitions can be thought of as the possible outcomes from a workflow step.
On the workflow editor transition refer to the arrows between steps.

Adding a transition

To add a transition, click on the source step. The step is surrounded by a circle to indicate it is in edit mode. Click on the icon with an arrow to add a transition. A transition is added with a green dot in the center and a wider circle around it.
Drag the green dot to the target step. The transition is connected to the target and has the label 'New Transition'.
Click on the 'New Transition' label to edit the transition. A circle is placed around the transition with 3 icons. Click on the icon with 3 stacked lines to edit the settings for transition. In the pop-up settings window, set the values as follows:

Transition types

The following table shows the list of transition types and the types of steps for which they are relevant

Where an email is notifying a person that an action is available for them to take, that person must have a login and the correct subscription to be able to act on the step in question.

Editing transitions

Click on the transition to place it in edit mode. The transition will be surrounded by a circle with 3 icons.
Click on the on the icon with 3 stacked lines to edit the settings for the transition.

Using transition elbows to make workflows more readable

Transition elbow help to make a workflow more readable so that a transition doesn't overlap other transitions or workflow steps.
Click on the transition to place it in edit mode. The transition will be surrounded by a circle with 3 icons.
Click on the on the icon with 3 joined dots to add an elbow. A green dot will be inserted into the mid point of the transition and have a larger circle around it.
Drag the dot as required.
Repeat this step by clicking on any portion of the line and adding another elbow.
Delete an elbow by clicking on the dot and then clicking on the bin/trash can icon.

Deleting transitions

Click on the transition to place it in edit mode. The transition will be surrounded by a circle with 3 icons
Click on the bin/trash can icon to delete the transition.

Workflow timeouts

Workflow timeouts are a type of transition which when added to a step will result in an automatic outcome if no other outcome is given beforehand.
An simple scenario is one where a group is given a fixed period of time to provide a decision for a step and if no decision is made within a set time the form should follow whatever path is defined by the timeout transition.
An alternative scenario is one where a form is required to undergo a periodic 'Assessment' or 'Review' as part of its ongoing management. Risk assessments are a common example.
If a workflow step has no timeout transition defined, it will never timeout.
Timeout transitions are added in the same way as other transitions but when selecting the transition type of 'Timeout' and additional field will be displayed labelled 'Timeout(minutes)'. This should be set to the time in minutes at which the step should timeout. For example use 10080 for a one week timeout.
The 'Timeout(minutes)' setting can also be set to the token of a field containing the value (in minutes). An example is [P.TIMEOUT] for a field on the form with the token TIMEOUT. This allows the person editing the form to enter a variable timeout value. Alternatively the field can be set dynamically by configuring an execution step of type 'SQL' to set the timeout field based on some other criteria in the form.
A sample script for dynamically setting a timeout is shown below. If a drop-down field is set to 'End of Week' it calculates the time in minutes from now to the end of the week, otherwise it sets the timeout to the number of minutes from now until 11pm same day.

UPDATE form_fields ff

SET ff.token_9 = 'TIMEOUT'

, ff.hidden_value_9 =

IF('[P.RULE_DURATION]'='End of week',

TIMESTAMPDIFF(MINUTE,NOW(),STR_TO_DATE(CONCAT(DATE_FORMAT(NOW(), '%Y-%m-%d'),' 23:00:00'),'%Y-%m-%d %H:%i:%s'))+

(1440*(6-DAYOFWEEK(NOW()))),

TIMESTAMPDIFF(MINUTE,NOW(),STR_TO_DATE(CONCAT(DATE_FORMAT(NOW(), '%Y-%m-%d'),' 23:00:00'),'%Y-%m-%d %H:%i:%s')))

, ff.visible_value_9 =

IF('[P.RULE_DURATION]'='End of week',

TIMESTAMPDIFF(MINUTE,NOW(),STR_TO_DATE(CONCAT(DATE_FORMAT(NOW(), '%Y-%m-%d'),' 23:00:00'),'%Y-%m-%d %H:%i:%s'))+

(1440*(6-DAYOFWEEK(NOW()))),

TIMESTAMPDIFF(MINUTE,NOW(),STR_TO_DATE(CONCAT(DATE_FORMAT(NOW(), '%Y-%m-%d'),' 23:00:00'),'%Y-%m-%d %H:%i:%s')))

WHERE ff.form_id = [P.FORM_ID]

AND ff.batch_num = 0

Impact of changing a workflow on existing forms

The workflow for a process template can be amended even after forms have been created with that template. This table lists the key impacts of making changes.

Workflow configuration checklist

Use the following checklist to validate readiness of the workflow for user.

Configuring the ability to reopen a form

If there is a requirement to be able to reopen previously closed forms the workflow can be configured to support this.
There are two configuration tasks required to enable reopening:
1. Security must be defined against the end workflow step(s) to define who can reopen the form. Refer to the section accessing workflow security settings for details.
2. An 'On-Click' transition should be created from the End step to the step in the workflow where the form should reopen. Refer to the section Adding a transition for further details.