Automation

Corteza provides a powerful automation system that implements custom business logic. This allows you to extend Corteza and support your business needs.

Corteza allows you to perform tasks as trivial as inserting missing values, or as complex as collecting payments for your subscription service. The applications section covers the applications that the automation system was designed for.

Our CRM and Case Management applications are open-source. You can refer to their workflows if you need some inspiration.

Important notes

Please read this sub-section carefully. It outlines some system design decisions that may not work as expected if not used properly or if their function is assumed.

Execution cycles

When your automation interacts with Corteza, that interaction may execute additional automation.

For example; if your automation is executed before the record is updated, and the given automation explicitly calls an update for the same record, the same automation will be executed indefinitely (illustrated on the bellow diagram).

There is a mechanism in place to prevent indefinite execution for workflows, but none for automation scripts.

When you need to explicitly update the same resource, define some flags to help you keep track of what is going on. Some updates are automatically performed when using implicit automation. Refer to execution flow details for more insight into the internals.

The following is a diagram outlining the potential infinite execution cycle. Note how the explicit update loops back to the update request step.
Figure 1. The following is a diagram outlining the potential infinite execution cycle. Note how the explicit update loops back to the update request step.

Asynchronous execution

An automation can be executed synchronously or asynchronously.

When an automation is executed asynchronously, it is unable to alter the operation that caused the automation to execute.

To exemplify; an asynchronous automation can not change the values of the record that is about to be created or updated.

Any workflow that defines a prompt or a delay step is executed asynchronously as the system can not guarantee that the execution will be finished in a timely manner, which may cause further complications and confusion.

Access control

When an automation is executed and the automation interacts with Corteza, the invoking user (the user that caused the automation to execute) is used when performing access control checks.

If the invoking user is allowed to access a certain resource, the automation is also allowed to access that same resource. If the invoking user is not allowed to access a certain resource, the automation is also not allowed to access that same resource.

Any automation executed on the back-end (server scripts and workflows) is able to overwrite this by explicitly setting the invoking user. The flow of defining the invoking user differs for both automation scripts and workflows, so it is covered in their respective sections.

Automation facilities

Corteza provides two facilities for defining automation; automation scripts and workflows.

An automation script is a piece of JavaScript code that allows you to code your automation. Automation scripts are low-level and require programming knowledge, as well as some extra steps when setting up.

As of 2021.3, when the workflow feature was introduced, automation scripts are disabled by default and can be enabled by setting the CORREDOR_ENABLED=true .env variable.

A workflow is presented as a simplified BPMN diagram, which allows you to configure instead of code. Workflows are easier to visualize and maintain, therefore they should be used whenever possible. If your automation requirement is one of larger scale and includes operations that are not supported by the workflow engine, an automation script is a better choice.

A workflow can execute automation scripts. This allows you to mix-and-match the two.

Abstract overview of the automation flow

Refer to execution flow details for more insight into the internals.

An automation trigger tells Corteza when the automation should be executed. When the system starts or when there is a change, the triggers are registered on the event bus.

When working with automation scripts and the Corredor server is running in production, the Corredor server needs to be restarted in order to process new changes.

You can enable the CORREDOR_EXT_SERVER_SCRIPTS_WATCH and CORREDOR_EXT_CLIENT_SCRIPTS_WATCH .env variables to be on the lookout for changes.
The diagram below provides the general idea of how the different components interact and how a request invokes an automation. Refer to the xref:automation/execution-flow-details.adoc[execution flow details] section for a deeper dive into the internals.
Figure 2. The diagram below provides the general idea of how the different components interact and how a request invokes an automation. Refer to the execution flow details section for a deeper dive into the internals.

When a Corteza component receives a request to interact with a resource, it may generate a series of events (usually two; a before and an after event) that describe what is about to happen and the current context. For example; when we wish to create a new record the compose component would dispatch a before record create and an after record create events. Besides the description, the event contains the data that describes the involved resource along with some metadata (the initial scope).

The provided data and metadata depend on the trigger. Refer to the lists of trigger constraints and resource events for more details.

The event is dispatched on the event bus where the automation system executes every automation that matches the events' constraints with the provided initial scope (execution arguments). The provided data may be used to control the automation execution and, in some cases, manipulate the original operation.

Some flows may bypass the event bus and execute a specific automation directly.

An automation obtains the permissions of the invoking user (the user that caused the automation to execute). A workflow that attempts to perform operations (such as accessing sensitive data), for which the invoking user does not have sufficient permissions, fails.

The invoking user may be overwritten by explicitly setting the security context (the runAs parameter).

When the automation finishes executing, it returns an execution result. The execution result may dictate how the initial operation resolves.

A quick outline of how the execution result affects the initial operation:

  • If the automation is asynchronous, the execution result is disregarded and does not manipulate the initial operation.

  • If the automation results in an unknown error, the initial operation is canceled and no additional processing is done.

  • If the automation results without errors and it returns a zero value, the initial operation continues as if no automation occurred.

  • If the automation results without errors and it returns a non-zero value, the returned value is used to replace the original value, if the operation permits it.

Applications

Extend standard operations

Corteza components dispatch events on the event bus when the system is about to interact with the resource of the components. This allows you to detect specific operations and build upon the standard flow, such as create audit log entries, or send a welcome email when a user signs up. You can also cancel the operation by raising errors when something is not ok.

You can react to such events, by defining a before/after event listener for a system resource. For example; if you were to bind the beforeCreate event for Compose Record resource, you would label such triggers as implicit. You should use the same label for the corresponding automation.

Only before events are able to alter the original operation.

Refer to execution flow details for more information.

Time-based execution

Corteza allows you to execute an automation at a specific time or in an interval by using a deferred trigger. This allows you to delay execution until a specific time, or to perform routine tasks such as generate report emails.

Timestamp triggers execute the automation at a specific time using the ISO 8601 format. For example; 2021-01-01T10:30:00Z executes on first of January at 10:30 AM.

Interval triggers execute the automation in an interval using a cron expression. For example; 0 0 1 * * executes on the first day of each month at 00:00.

Crontab guru is a tool that helps you write and debug your cron expressions.

The default granularity for timestamps and intervals is one minute. You can change this by changing the EVENTBUS_SCHEDULER_INTERVAL .env variable.

Finer granularity may lower the performance of the systems.

Refer to execution flow details for more information.

Webhooks and custom endpoints

Corteza allows you to execute an automation when a request is received on a specific HTTP API endpoint. This allows you to define custom API endpoints and webhooks to use with third-party services.

We react to API requests by defining an onRequest event for the System Sink resource. For example; you define a sink route with the path of POST /system/sink/api/request-demo that collects potential leads sent over by the landing page.

To use a sink route, you must first register it in the system. Refer to the DevOps guide for details.

Refer to execution flow details for more information.

Process email requests

Corteza allows you to execute an automation when an email is received or sent by the system.

Reacting to email requests can be done by defining an event on the System Mail resource; either onReceive for inbound emails, or onSend for outbound emails.

You must firstly follow the DevOps guide to configure the system.

Refer to execution flow details for more information.

General automation

Alongside the event-based model, Corteza allows you to implement general use automation that is executed by manual invocation. Such automation triggers are labeled as explicit as they require explicit invocation.

Explicit triggers can be invoked via the REST API which may allow you to avoid sink routes and their additional configuration.

Define explicit triggers by defining the onManual event. An explicit automation is usually represented as a button on of the Corteza user interfaces either inside the automation or the record list page block.

Explicit automation can be defined or specific resources (such as records and users) which indicate the initial scope (execution arguments) of the automation.

Refer to execution flow details for more information.

Examples of usage

Automation examples:

  • populate missing values on a newly created record,

  • create an audit log when changing specific record values,

  • send an email when a new user is added to the system,

  • send a monthly report email to executive members.

DevNote add some examples and references to the above examples.

Where to next?

To dive deeper into the execution flow and what happens under-the-hood, refer to the execution flow details section.

Refer to the workflows section and the automation scripts section to learn about the two automation systems.

To see some actual examples, refer to out CRM and Case Management applications. You can use these workflows as a base to implement your own.

You can get in touch with us on our forum with any questions and suggestions.