Style guide and best practices
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:
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.
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.
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.
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.
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:
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.
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.
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