Style guide and best practices

Style guide

Workflows are based on and inherit the base rules from the BPMN 2.0 standard. We define some additional rules to help keep workflows consistent.

Follow the KISS principle

The Keep It Simple, Stupid principle indicates that your workflows should not be needlessly overcomplicated. Over-engineering usually reduces clarity and introduces more failure points.

To exemplify, instead of using a gateway to set a Boolean variable to the correct value, write an expression that evaluates the desired value.

An over-engineered version:

workflow style simple gateway

A simplified version:

workflow style simple expression

Most operations can be transformed into expressions but at the cost of clarity. If a simplification causes the clarity to decrease, you should not use simplification.

Larger complex operations can be replaced by automation scripts.

Avoid crossing connectors

When working with larger workflows, crossing connectors may mislead and confuse the reader. Workflow steps define many anchor points to help you achieve this.

An example of crossing connectors:

workflow style connectors nok

An example of corrected, non-crossing connectors:

workflow style connectors ok

A connector defines a series of anchor points that you may use to adjust the flow of the connector. The anchor points become available when you click on the connector.

workflow style connector anchors

Step labels

All workflow steps should have a short label that outlines the core of the step. To exemplify, an expression that calculates the sales commissions should be labelled as "Calculate sales commissions".

A Trigger label should state the resource and the trigger type. This allows the reader to understand when the trigger is executed without reading the configuration.

workflow style label trigger

A gateway label should state the question that determines the output. The output path labels should state the answer to the question of the corresponding gateway.

workflow style label gateway

The function label should contain the verb and the subject of the function.

workflow style label function

Readable layouts

The initial integration usually consists of multiple workflows which can be extended and added in the future. A consistent layout increases consistency and readability.

Here are some tips:
  • the flow should go from top-left to bottom-right,

  • group the related steps,

  • align the steps with the grid,

  • keep the layout symmetric as it is generally easier to understand.

Best practices

Define as many trigger constraints as sanity allows

When you click on the configuration icon cog in the header of the trigger, you see that it is possible to define multiple trigger constraints.

When defining a "loose trigger" you can run into a situation where some events may trigger the workflow even though they shouldn’t.

An example of this is the case module in our CRM and in our Case Management.

Defining a trigger with these constraints:

bp constraints no

If the case was created in the CRM or in the Case Management, it causes the workflow to execute regardless.

To fix this edge-case, we can define an extra constraint that checks the namespace:

bp constraints yes

One expression step may have multiple expressions

When you click on the configuration icon cog in the header of the expression step, you see that you can add multiple expressions.

Use this to reduce the number of expression steps, but don’t go overboard. If you wish to change the values of a contact and an account record, define only two expression steps where each focuses only on one record.

An overengineered workflow example:

bp compact no

The above could easily be rewritten into the below form.

A correct workflow example:

bp compact yes

Most iterators are able to load and process data

Item iterators that work with system resources (e.g. Corteza Low Code records, system users and roles) can both fetch and process the data.

When you need to iterate over external resources (for example, social media posts), you need to fetch those beforehand.

Use handles whenever possible

Most resources allow you to define a human-friendly identifier next to the system generated identifier (a handle or a slug in case of a namespace).

These identifiers make it easier to write workflows that will work across different instances where the identifier may not be the same. Readability is also increased; it’s easier to read lead as an identifier to the lead module instead of 12897612987021.