Workflows

Corteza workflow allows you to implement custom business logic without the need for any programming knowledge. This section focuses on the most important aspects of the system. If you wish to learn more about a specific topic, refer to the subsections under Low-Code Platform Developer Guide Automation Workflows.

In contrast to automation scripts, workflows are presented as a simplified BPMN diagram, allowing you to configure instead of code. You are not required to have any BPMN knowledge, although it might be helpful.

Create a new workflow

DevNote how to include the flow from the admin panel?

To create a workflow, navigate to your Corteza instance (for example http://latest.cortezaproject.org/) and click ok the "Workflows" application.

Figure 1. The screenshot indicates how to access the workflow web application.

A new screen showing you all of the available workflows will appear.

From there you can:

create new workflows by clicking on the New Workflow button,
edit existing workflows by clicking on them,
manage global permissions by clicking on the Permissions button,
manage workflow-specific permissions by clicking on the "Lock" icon next to the workflow, or
import/export workflows by clicking on the Import/Export buttons.

Figure 2. The screenshot indicates how to create a new workflow.

When you click on the New Workflow button, a new screen will appear with an open modal window, where you should insert initial parameters to describe the workflow.

Label provides a user-friendly identifier for the workflow, for example "Test Workflow". A label doesn’t define any special constraints.
Handle defines a unique value that may be used instead of the system identifier for easier referencing.
Description defines a verbose description of the workflow in order to better explain what the workflow does.
Run as defines which user should be used when executing this workflow (the invoking user).

Handle constraints:

start with a character,
contain at most 64 characters,
contain only characters, numbers, _ (underscore), - (dash) or . (dot),
end with a character or a number.

Figure 3. The screenshot shows the newly created workflow where the modal window for the initial parameters is open.

About the workflow editor

The workflow editor consists of four main parts; workflow configuration screen, toolbar, canvas, and step configurator.

Workflow configuration (accessible by clicking on the configuration icon in the header) is where you provide basic workflow configurations.
Toolbar is where you can find all of the available steps.
Canvas is where you can build and configure the workflow.
Step configurator is where you can configure the workflow steps.

Figure 4. The workflow editor user interface.

Structure the workflow

To start building your workflow, simply drag-and-drop different elements (further referred to as steps) from the toolbar to the canvas. If you are using similar steps with similar configurations, using copy-paste to duplicate existing steps might be faster (cmd+c and cmd+v).

Figure 5. Example of adding a new step from the toolbar to the canvas.

To define the flow of your workflow, simply connect the steps by drawing a connector between them.

Figure 6. Example of connecting two steps.

To change the start point or the end point of the connector, click on the connector to view its points; then hover over the connecting point and drag it to another connector point.

Figure 7. Example of changing the origin connector point.

Figure 8. Example of changing the destination connector point.

Add some extra steps to get the feel for the interface. The resulting workflow doesn’t need to be valid or make any sense. All of the available steps and their configuration will be addressed in detail in the following sections.

Gesture reference:

Click and hold the right mouse button, drag the mouse to pan the canvas.
Scroll up to zoom in the canvas (inverted when natural scrolling is enabled).
Scroll down to zoom out the canvas (inverted when natural scrolling is enabled).

The remaining gestures and keyboard shortcuts can be found in the help menu.

Remember, every workflow must start with a trigger trigger . The termination step is optional, but may increase clarity. A single workflow can have multiple triggers and multiple termination steps.

When you’re satisfied with your workflow or wish to save your progress, click on the save button on the bottom of the screen, or use the ctrl+s shortcut.

Figure 9. The screenshot shows how to save the workflow.

Configuring the workflow

Without any configuration, most workflow steps don’t do anything unless we configure them to perform some task such as evaluating an expression or executing a complex function.

In order to configure specific steps, click on the configuration icon cog in the header of the step. To configure a specific connector, click on its label or double click on it.

The configuration is automatically saved to the step. The workflow needs to be saved in order for the configuration to take affect.

Figure 10. The screenshot shows the step connector for the expression step.

Execution control

Execution control allows you to indicate where the workflow starts, its steps, and where the workflow ends.

Triggers

A trigger trigger defines when the workflow is executed and what steps the workflow execution should perform.

A single workflow can have multiple triggers. Multiple triggers allow you to define fewer workflows for different events.

Every time an action occurs (e.g. a record is created or a user signed-up) the system finds all of the workflows with a trigger that conform to that operation. To exemplify; when a client signs-up for your newsletter, the system finds all of the workflows where the trigger listens to a "user signed up" event.

A trigger consists of four main components (click on the configuration icon in the header):

a resource which specifies what system resource the trigger reacts to,
an event which specifies what system events the trigger reacts to,
a series of constraints which specify how an event should look like in order for the trigger to react.
- To exemplify; we can react to a Corteza created event only when the record was created for a lead module under the CRM namespace,
an initial scope which specifies what variables are available to the workflow as soon as it is executed. When working with records this is the current record, the previous version of it, the related module, the related namespace, and any record validation errors.

Constraint your triggers as much as possible to prevent your workflows from executing when they shouldn’t.

Figure 11. An example of a workflow with multiple triggers.

Terminators

A termination step terminates the execution of a workflow.

The termination step terminates the entire workflow, regardless of any other execution branches.

Figure 12. An example of a workflow with multiple terminators with a potential early termination issue.

In the example above, when any of the long running tasks finishes, the entire workflow will be terminated and the other long running task gets canceled.

Refer to Parallelism for details.

The termination step is not required, and is implied wherever the workflow is unable to continue due to the lack of steps.

A single workflow can have multiple termination steps. Multiple termination steps allow you to explicitly terminate the execution of a workflow.

Figure 13. An example of a workflow with multiple termination steps.

Expressions

An expression step expressions defines a set of expressions which allow you to directly interact with values defined in your workflow. Think of this as defining an equation in spreadsheets.

A single expression step can define multiple expressions, allowing you to aggregate similar operations under a single step; this reduces the size and increases readability. Refer to Expressions for more details regarding expression definition.

Examples of usage:

generate a full name for a contact,
calculate the grand total for a quote,
copy values from one record to another.

To configure the expression step, click on the configuration icon cog in the header of the expression step.

Figure 14. The expression configuration interface.

To add a new expression to the expression step, click on the + Add Expression button. Click on the expression to collapse or collapse the expression editing interface.

Figure 15. The expression configuration interface with inserted expressions.

Functions

A function step defines what operation should be performed when the function step is executed. Think of this as defining a macro in spreadsheets.

If you’re using logging functions, make sure to correctly set your environment variables. Refer to the DevOps guide for details.

Examples of usage:

create a new quote for an account,
send an email notification to your mailing list,
delete a suspended user.

Functions that are not natively supported by workflows can be implemented with automation scripts. An automation script can be executed from a workflow.

To configure the function step, click on the configuration icon cog in the header of the function step.

Figure 16. The function configuration interface.

Select what function you wish to perform in the dropdown select box under the "type" section.

Figure 17. The function configuration interface.

When you select a function, the list of function arguments appears. An argument defines what piece of data the function should use to perform some operation. To exemplify; the message parameter in the "log debug message" function defines the message displayed in the debug log.

Figure 18. The function configuration interface with defined parameters.

The function step in the above example creates a log entry based on the provided message and fields arguments.

Function arguments can be passed in two different ways:

Constant values which are passed into function in their present condition. Use constant values when the passed data should not change.
Expressions are evaluated and the result is passed into function. This is useful when you wish to change the input without the need for an additional expression step.

Processing multiple items

When you wish to process multiple items, such as a list of leads that were created in the past month, you should use an iterator . An iterator allows you to sequentially process a series of items one after another.

An iterator consists of two main parts; the configuration and the iterator body.

Iterator configuration

To access the iterator configuration, click on the configuration icon cog in the header. The configuration consists of three parts; type, arguments, and result parts.

Iterator type

From the end-user’s perspective, the iterator type specifies what arguments you need to provide in order to process the requested set of items. We characterise three main kinds of iterators:

Condition iterators: A condition iterator repeats for as long as the condition you’ve provided results as truthy. To examplify; a condition of counter < 10 would make the iterator repeat for as long as the counter is below 10.
Item iterators: An item iterator traverses the provided set of items from start to finish. To examplify; we pass in 10 records, therefore the iterator repeats 10 times, once for each record in the provided set.

Most item iterators are able to fetch and iterate over items.

Stream iterators: A stream iterator traverses the provided file one line at a time. To exemplify; we provide a text document containing 10 email addresses each in its own line, therefore the iterator repeats 10 times, once for each line (in this case email address).

Be careful when using the stream iterator with arbitrary file types. File types and encodings may cause unwanted behavior.

Iterator arguments

Iterator arguments allow you to specify the data that the iterator is allowed to work with.

Iterator arguments can be passed in two different ways:

Constant values are passed into the iterator function in its present condition. Use constant values when the passed data should not change.
Expressions are evaluated and the result is passed into the iterator. This is useful when you wish to change the input without the need for an additional expression step.

Iterator results

During the execution of an iterator a set of results for each iteration is generated. The results depend on the iterator type.

Iterator body

The iterator body is implied by the first outgoing connector. The second connector indicates where the execution continues after the iterator executes.

Note the "body" and the "end" labels on the outgoing connectors.

Use the iterator body to define what should happen to the items in processing, for example; if our intent is to send out email notifications, this is where you do that.

The iterator body is implicitly terminated by the continue step if neither of the iterator execution control steps are used prior.

Use either the continue or break steps to terminate the loop body. The advised approach is less prone to errors such as infinite loops. Do not create a loop using connectors.

Figure 19. An example of a valid iterator body.

Figure 20. An example of an invalid iterator body.

Controlling iterator execution

There may be cases where you would like to prematurely terminate the ongoing iteration or the entire iterator all together. This can be done using the break break or the continue steps.

The break and the continue steps are only valid within iterator bodies.

Continue

The continue step terminates the ongoing iteration and continues with the potential following iteration. The continue step should be used to either prematurely terminate the iterator body or when the iterator body is considered as completed.

Figure 21. An example of a premature and a complete iterator body.

Break

The break step break terminates the ongoing iteration and any additional iterations performed by the iterator. The break step should be used to prematurely terminate the entire iterator. To exemplify; when a system error occurs or when you find the item you are looking for.

Figure 22. An example of a prematurely terminating the iterator.

Error handling

Whenever you work with dynamic data (especially end-user input) and external services, you are always reminded that errors can and will occur. We define two steps for working with errors; error handler step and error step error .

Error handler

An error handler step allows you to catch and react to any errors that may occur in continuation of the workflow.

Think of this as a try-catch.

Figure 23. An example of an error handler in action.

The steps in the red zone can be considered as dangerous (can fail). If any step in the "dangerous" zone fails, the execution continues along the "Catch" connected steps.

Error

An error step error allows you to manually trigger an error during the execution of a workflow. Forcefully terminating the workflow using an error step prevents additional operations from executing (such as the record is not saved or a user is not suspended).

Think of the error step as raising an error or an exception.

Figure 24. An example of an error in action.

Gateways

Gateways allow you to implement conditional execution based on the ongoing state of your workflow, for example, if a current user is already a subscriber, we should send a renewal request instead of a subscription request.

There are three kinds of gateway steps; exclusive gatewayExclusive , inclusive gatewayInclusive , and fork gatewayParallel .

The break and the continue steps are not supported for gateways. If the gateway is nested within an iterator, the iterator will be affected instead.

Exclusive

An exclusive gateway gatewayExclusive defines two or more connectors. Only the first connector that meets the condition is evaluated. Connectors are evaluated in the order they were initially defined in.

Figure 25. An example of an exclusive gateway in action.

Inclusive

An inclusive gateway inclusive gatewayInclusive defines two or more connectors. Any connector that meets the condition is evaluated.

Figure 26. An example of an inclusive gateway in action.

Fork

A fork gateway gatewayParallel defines two or more connectors. Each connector is evaluated and executed in parallel.

All of the different "branches" created by a fork must be collected using a second fork step.

Important notes

Inclusive and join gateways

When using inclusive gateways with join gateways, the workflow may run indefinitely.

The join step waits for all of the inbound paths to resolve. If any one of the inclusive paths does not resolve, the join gateway never resolves, and the workflow runs indefinitely.

Workflow execution, by design, does not timeout unless forcefully terminated.

You can resolve this by reworking your workflow logic to avoid such cases.

Figure 27. An example of a workflow that will never resolve.

Interacting with the user

Any workflow that uses a prompt step prompt is treated as asynchronous. Refer to the automation/execution-flow-details.adoc#exec-flow-implicit for potential implications.

The prompt step prompt allows you to interact with the user in order to provide additional confirmation or data, such as a recipient email address or filling in any missing parameters.

External redirect

An external redirect redirects the receiving user to the specified URL anywhere on the internet.

You can use this prompt to initiate download procedures.

Internal redirect

An internal redirect prompt redirects the receiving user to the specified route on the current web application. Refer to the /src/views/routes.js JS file of each Corteza web application for a complete list of available routes and their parameters.

Record page redirect

A record page redirect prompt redirects the receiving user to the specified record page. This can be used to redirect the user to the newly created record.

Notification

A notification prompt displays a notification to the receiving user but is dismissed immediately when shown. This can be used to show success or other informative notifications.

Alert

An alert prompt displays a notification to the receiving user. This can be used to show success or other informative notifications.

Choice

A choice prompt displays a notification with two buttons to either confirm or reject something to the receiving user. This can be used to request additional confirmation before performing an operation or to optionally perform additional operations.

Single input

A single input prompt displays a notification with a value input box to the receiving user. This can be used to request additional information from the receiving user, such as missing contact data or their pin code.

Option select

An option select prompt displays a notification with a list of available options either as a select or a list of radio buttons. This can be used as a more verbose choice prompt or a more constrained input prompt.

Record select

A record select prompt displays a notification with a record list search box from where the selected record is passed into the workflow. This can be used to allow users to select some record relevant to workflow execution.

Delay and schedule workflows

Corteza workflow allows you to schedule or delay its execution. This can be a powerful tool when working with external services that throttle their API usage or when a task should be performed in an interval, for example monthly subscription renewal.

To achieve this, you are provided with a delay step delay and a deferred trigger trigger .

When you use a delay or a prompt step, the workflow becomes asynchronous and can no longer invalidate actions like create, update, or delete a record.

Operations such as "confirm record creation" are currently not possible with workflows. If you need to perform value validation or sanitization, use field expressions instead.

The delay of execution

The delay step delay allows you to explicitly pause the workflow’s execution for a set period of time.

This type of delaying is common when working with APIs that throttle their access. To exemplify; let’s say that the API allows 10 calls per minute and we wish to fetch 100 items. A possible execution is as it follows:

In case you wish to wait for an action performed by a user (such as a confirmation), use a prompt step instead.

Execution scheduling

Execution scheduling is performed by configuring the trigger trigger to run in an interval or at a specific timestamp.

Interval

An interval trigger allows you to run the workflow in a specified interval. This can be used to perform routine daily tasks or process larger data in batches.

A good example is a subscription service where it is necessary to renew the subscriptions of the clients on a monthly basis. We define an interval that executes the workflow each day, determine what clients need to be renewed that day and renew them.

The form of the above example should not be used in production. The actual workflow should implement error handling, transaction logging, and email notifications.

To define an interval trigger, click on the click on the configuration icon cog and specify the system as the resource resource with the on interval event.

The interval is defined as a chron expression and can be extremely flexible. You can also use this amazing tool to verify that your expressions are valid.

Common cron examples:

every hour at minute 0: 0 * * * *
every 30 minutes (0 and 30): 0/30 * * * *
every day at the start of the day: 0 0 * * *
every month at the start of month: 0 0 1 * *

You can define multiple intervals under the same trigger.

Timestamp

A timestamped trigger allows you to run the workflow at a specified time.

To illustrate; you have just received a new client that requested a series of deadlines where they would like to see the current progress. We could define a scheduled workflow that is executed at each one of the timestamps. The workflow would aggregate all of the completed tickets into an email and send it off to the client.

Timestamps are defined in the ISO 8601, YYYY-MM-DDThh:mm:ssZ format.

You can define multiple timestamps under the same trigger.

Ready for more?

The sub-sections under Automation Workflows go into more details regarding specific topics, such as:

the style guide and best practices,
an introduction into our testing and debugging facility,
how to manage and organize larger workflows,
how to execute automation scripts available in the Corredor server,
how to process requests via Integration gateway.

For more advanced users who wish to know more about the internals: