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.
|
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.
|
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.
|
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.
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.
The function label should contain the verb and the subject of the 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.
-
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 
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 Service Solution.
If the case was created in the CRM or in the Service Solution, it causes the workflow to execute regardless.
To fix this edge-case, we can define an extra constraint that checks the namespace:
One expression step may have multiple expressions
When you click on the configuration icon 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.
The above could easily be rewritten into the below form.
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.