Understanding Workflow

Overview 

The Workflow V2 UI in App Studio is split into two pages: 

• The index page 
• The Workflow editor 

It also provides functionality to migrate existing Workflows to the new workflow editor. 

Think of Workflow as an IF… THEN statement. IF this condition is met (e.g. a 'Status' Field has turned Red) THEN send an email to the Executive. Workflow requires a 'Trigger' to decide when the workflow will occur and also an 'Action' to determine what occurs when the Workflow has been triggered.

However, setting Workflow needs the App Builder to understand who the key stakeholders for an App are, what process is to be followed and who does what. This will then indicate the key steps requiring automation.

This process can be enabled by working with the App owner or client to create what is called an Activity-vs-Role (or 'swimlane') Process Map.

It can be very useful to automate administration tasks such as: linking Child Records to appropriate Parent Records, setting Security for a Record based on the creation User creating the record, or even Field values within the Record.

Look for opportunities to set up Workflow on an App whenever there is a hand-off from one stakeholder group to another.

 

Concepts 

In Workflow V2, each app has a number of workflow elements, each of which consists of nodes that are connected together. Each node represents a single, distinct operation that can be performed on records in the app. There are three categories of nodes: 

• Triggers are nodes that begin a workflow and denote what causes it to start. 
• Filters are nodes that choose which records to pass on to the rest of the workflow and which not to. 

• Actions are nodes that do something based on the records they receive, such as send a notification, update the record in the database, etc. 

All workflow is directional. Each node may be connected to none or more following nodes, but (currently) may be connected from only a single node. Each workflow must begin with a trigger node; trigger nodes may not be connected to from other nodes. 

Workflow V2 is a dataflow system: each node performs an action when it receives a document (an object containing record data.) Depending on the result of the action, the document may either be passed on to the connected nodes or dropped (no further processing is performed on it.) This means that record data is typically read only once at trigger time. A “send email” action that formats an email template using record data will format it using the record data as it existed at the moment the workflow was triggered, not the data as it exists in the database at the time the action runs. 

 

Index page 

The index page shows a list of all the workflow that exist for an app, much like the index pages for other categories. Click a link to open the workflow editor; click Add to add a new Workflow (opening the workflow editor.) 

 

Workflow Editor 

 The workflow editor (here shown for a new workflow) is split into three sections: 

• In the description pane, write a brief description of the workflow (that will be shown in the index) and fill in a longer notes section if desired. A description must be filled in in order to save the workflow. 
• The palette contains templates for all the node types that can be added to the workflow, divided between three tabs (“trigger”, “filter”, “action”). (Since all workflow must begin with a trigger, the other two tabs are greyed out when the workflow is empty.) 
• The largest portion of the screen is taken up with the workflow view itself, which starts out blank. 

Begin to populate/edit the workflow by dragging nodes onto it from the palette, or by clicking on the “Empty workflow” box. This will bring up the Node editor: 

• The node type-dependent section contains controls that let you configure the node, varying depending on what node type is selected. Most of them should be self-explanatory. 
• The notes editor lets you add text notes to a node – these appear in the workflow below the node (see an example below.) 
• The node type selection drop-down gives you another opportunity to choose the node type: 

Click OK to save the node to add it to the workflow or Close to cancel. 

 

After adding a couple of nodes your workflow may look like this: 

• The “delete node” icon deletes a node if it has no onward connections. If it does (it is at the root of a workflow), it deletes the node and the rest of the nodes it is connected to. 
• The “show details” tool opens a details pane where you can see information about the node and what it has run (see later.) 
• The “add a node” tool opens the node editor, allowing you to choose a node to add as an onward connection. You can also connect a new node to the existing workflow by dragging and dropping a filter or action node template from the palette onto the node you want it to be connected to. 
• You can add another trigger node by dragging a trigger node template from the palette and dropping it onto an empty space on the editor. It will form the beginning of a new workflow element within the same workflow. This will be treated as if it were a separate workflow by the Workflow engine, but remain grouped together in the same workflow editor. 
• You can click on the body of a node to re-open the node editor and make changes to it. Note that the node type cannot be changed after the node has been created (the node type selection drop-down will be greyed out.) 

 

Workflows can be branched, e.g. the one above may be extended like this (here also showing an example of how node notes are displayed on the workflow editor): 

In this workflow, when the button is clicked, the notification is always sent, but the email is only sent if the “Namelength” field in the record has a value greater than 4. 

Edits to a workflow do not take effect until they are saved (using the Save button at the bottom left of the page.) The nodes are coloured in as follows: 

• 🟢Green: a newly created node that has not been saved yet. 
• 🔵Blue: a node that has been created, but has unsaved changes. 
• 🔴Red: a node that has been created, but will be deleted when Save is clicked. 
• 🔘Grey: a node that was previously saved and has not been changed. 

Saving the above workflow takes you back to the Index page where, if the description is clicked from the list, the workflow would then be shown like this, with all nodes showing the status of having been saved: 

If you change the notification text and delete the filter, it looks like this: 

The delete option/icon on the deleted node has become an undelete option/icon, and no other options are available for deleted nodes. 

You can drag nodes already on the workflow onto other nodes to reposition them within the workflow. Thus, if you want to replace a trigger Action or node with one of a different type, you can do so by the following process: 

• Add the new trigger or intermediate node to the workflow in the place you want it to be connected from. 
• Drag the node(s) that you want it to be connected to from their current place(s) in the workflow onto the new node. 
• Delete the old trigger or intermediate node. 

 

Details and metrics

After a workflow has been saved and some records processed with it, the node editor will start to show summary metrics of how many records were processed within the last 12 hours (approximately): 

• “6 acc” means the node has processed 6 records successfully and passed them on to the connected nodes. 
• “0 rej” means the node has processed and shows the number of records that have been rejected as not matching a criteria. (This counter is typically zero for all node types except filter nodes – records that do not match the filter are rejected, and counted here.) 
• “0 err” means the node has encountered 0 errors while processing records. Records that cause an error while processing are not passed on to connected nodes. You might get this if for example you have specified a field update where the value specified is not allowed or outside a range

Note that if the system is busy and/or a large number of records have been processed, the numbers may not be complete – metrics are gathered with a sampling system to reduce load. 

Clicking on the grey “show details” tool will open a pane on the right-hand side of the workflow editor containing more information about the node and the metrics gathered: 

If any errors have occurred, they should appear at the bottom of this pane – copy and paste the text from them into a bug report and send to support@softools.net . Always include the node ID (here “255c15e3-0ce2-46fb-85ac-4d26bba219c9”) with any bug report – this is the key for the node record in the database and will enable further debugging. Also include the URL for the workflow page you are on.

Eventually. the metrics shown will update every few minutes while the node editor page remains open (but as of 2021-08-24 this is not yet implemented), or you can reload the page to refresh the metrics. Expect it to take a few minutes before workflow processing is reflected in the metrics. 

 

Node types 

Most node types should be self-explanatory but a few of them merit further explanation: 

 

Button clicked 

After creation, a workflow beginning with a “button clicked” node will do nothing until you associate one or more image action buttons with that specific trigger. You can do so by finding the Name property of the “button clicked” node in the selection drop-down when configuring an image action button. 

If the node editor for your trigger node looks like this: 

Then you can associate it with a button by doing the following in the Image Action Button field configuration: 

And then 

Make sure to write something distinctive in the Name field for your button clicked triggers, there is no validator checking these strings are unique. 

 

Expression Language filter (NCalc) 

This filter node accepts only records that match the filter string and rejects the rest. The filter string is written in expression syntax (the same syntax used for the expression in expression fields.) The field features as-you-type validation, e.g. a syntactically invalid expression will appear like this: 

The save button will remain greyed out until the expression is thought to be valid. 

Only a subset of the expression language is supported in these filters (because the expression must be turned into an platform database query.) The validation feature will tell you when an expression is syntactically valid but not supported: 

In this case, we would rewrite the expression as follows 

In general, most expression functions are not supported. The following expression, which will match all records with a DueDate of yesterday or earlier, is supported: 

If you feel an expression that is not supported should be, please email support@softools.net  

for comparing a date value with a real date, you will need to do something like

          [DueDate] >= dateparse('2022-01-01') && [DueDate] < dateparse('2023-01-01')

This would check that the date field has the year 2022 

 

Scheduled job 

The Scheduled job trigger runs a workflow at a defined time, either once at that time, or repeating at an interval starting at that time. 

This workflow will run first on 2021-08-26 at 13:00 UTC, and repeat at the same time every day thereafter. (Because of the way workflows are implemented, it may not begin exactly on the hour, but rather at any time between 13:00 and 14:00.) 

Please note that dates specified here are in UTC date, not local time, so if you need a trigger to run at 1pm, you will need to work out what time that would be in local time. Use a service such as 

https://www.worldtimeserver.com/convert_time_in_UTC.aspx if you are not sure 

 

Workflows scheduled to run monthly will run on the closest matching day of the month. So, for example, a workflow scheduled to run every 1 month from a 31st January will run on 31st January, 28th (or 29th) February, 31st March, 30th April, etc. 

Each scheduled workflow must have a user it runs as – actions such as “update record” that check record permissions will check the permissions for that user. 

Unlike most triggers, which affect a single record at a time, the scheduled job trigger runs the workflow for all records in the app each time (excluding archived records – unless you check the “include archived records” check box.) We recommend connecting a scheduled trigger to filter nodes and not directly to action nodes: the records to be processed by the workflow are fetched lazily, and the filter in any filter node directly connected to a scheduled trigger will be processed as a database query. If your scheduled workflow takes too long to process it may be cancelled before it has processed every record (the timeout is around 30 minutes); if this happens the error should appear in the details pane after metrics have been gathered. 

You also have the option to run the workflow from the workflow edit/create screen, this can be used to test that the workflow works and what it looks like rather than wait for the scheduled time. This button can be located at the bottom of the screen:

 

Update field value 

The update field value action edits an existing record, updating the value of one field to a value computed by the expression. 

The expression string is written in the usual expression syntax (like expression fields) and, like the filter node type, there is as-you-type validation. The other settings affect how this action interacts with the rest of the workflow. Consider the following workflow, where a user can set a new due date for a task by clicking a button (using the expression shown above): 

Typically, it will have the following results: 

Today’s date	Value of [DaysInSprint]	Value of [DueDate] in database before action	“Pass updated values” setting	Value of [DueDate] in database after action	Value of DueDate in the email that is sent
2021-08-24	7	2021-08-25	False	2021-08-31	2021-08-25
2021-08-24	7	2021-08-25	True	2021-08-31	2021-08-31
2021-08-24	14	2021-08-22	False	2021-09-07	2021-08-22
2021-08-24	14	2021-08-22	True	2021-09-07	2021-09-07

Conflicts

The two conflict behavior settings (target and parameter) only take effect if something else (e.g. another run of this workflow, another workflow, an interactive user) alters the value of one of the fields involved this update in between this workflow starting and the “update field value” node being executed.

Remember that WorkflowV2 is a dataflow system in which the values of records are typically read only once at the start of the workflow and then passed along to each node in the workflow: this means that a workflow node can be run with outdated values. “Update field value” matches these values against the ones currently in the database when it runs and chooses a course of action if there is a difference.

 

Limitations

There are a few limitations in place to make sure that any one workflow cannot affect other users by inadvertently adding circular workflow or adding workflow which is too large. These are mitigated as follows

30 Minute timeout - After a workflow job has started it has 30 minutes to complete or it will be cancelled at the next step.

100 Email Limit - There is a current limit of a 100 emails that can be sent out by a single workflow. Note that having multiple email address's on one email in the CC/BCC does not count to this limit and will still only count as one email within the 100 limit.

 

Make sure to click the 'Save' button when making any changes in order for them to be added to the next app version. Once you have made all the changes you need to an application you are then ready to publish it to workspace.

Navigating away without clicking save will mean you lose any changes