You are reading the documentation for an outdated Corteza release. 2024.9 is the latest stable Corteza release.

Execution flow details

The section goes into the details of what causes the automation to execute, the important steps of the execution flow, and what happens with the result of the automation. A simplified explanation is described here.

Implicit automation

An automation is considered implicit, if the trigger uses a before, or an after event; for example beforeCreate and afterCreate.

Implicit automation is automatically executed whenever we interact with specific resources, such as records or users. The two variations of events (before and after) follow the same path, with the difference in when the event is dispatched, and how the resulting value is used.

before events are dispatched first and their execution result may affect the rest of the execution, while the after events are dispatched after and the execution result does not affect the rest of the execution.

The diagram provides an abstract overview of the execution flow for implicit automation. The flow is explained in details bellow the diagram.
Figure 1. The diagram provides an abstract overview of the execution flow for implicit automation. The flow is explained in details bellow the diagram.
Table 1. Detailed outline of the implicit automation execution flow:

A component receives a request to interact with a resource.

For example; we wish to create a new record, or update the email of a user.

Access control checks if the invoker is allowed to perform the operation.

If the invoker is not allowed to perform the operation, the request is rejected and no automation is executed.

Content sanitization and validation prepare and validate the data.

Before any destructive operation occurs and before the before event is dispatched, the values are validated and sanitized. If the validation fails, the request is rejected and no automation is executed.

The before event is dispatched on the eventbus.

If the automation is synchronous, the operation awaits for the dispatched event to resolve before continuing the initial operation. If the automation is asynchronous, the initial operation does not await.

The resulting value of the synchronous automation affects how the initial operation should continue:

  • If the execution resulted as successful (no errors):

    • If the resulting value is set (non-zero value), the resulting value replaces the original value and the initial operation continues.

    • If the resulting value is not set (zero value), the original value is used and any modifications by the workflow are omitted.

  • If the execution results as failed (an error occurred), the initial operation is canceled and the resource remains untouched.

A failed execution only terminates the current operation, and will not revert any changes that were made in the executed automation.

Content validation and sanitization occurs.

Before any destructive operation occurs, the modified values are validated and sanitized. If the validation fails, the request is rejected and the after event is not dispatched.

The resource is manipulated.

The original operation completes and the change is permanently written to the store.

The after event is dispatched on the eventbus.

The operation does not await for the event to resolve and the result of the automation is therefore ignored.

The resulting value of the automation is ignored and does not affect the original operation.

Explicit automation

An automation is considered explicit, if the trigger uses an onManual event for any resource.

In some cases, you can use explicit automation to replace the need for sink routes.

DevNote add some documentation regarding the above statement.

Explicit automation is executed when manually invoked. On the front-end this is usually done with a button press, but under-the-hood, this is just an HTTP request to an API endpoint.

Automation scripts and workflows define separate API endpoints to invoke explicit automation.

For automation script this is a POST $API/$COMPONENT/automation/trigger, where $API is the base URL to your Corteza API, and the $COMPONENT is the name of the component that should execute the automation script (compose or system).

For workflows this is a POST $API/automation/$WORKFLOW_ID/exec, where $API is the base URL to your Corteza API, and the $WORKFLOW_ID is the ID of the workflow you wish to execute.
The diagram provides an abstract overview of the execution flow for explicit automation. The flow is explained in details bellow the diagram.
Figure 2. The diagram provides an abstract overview of the execution flow for explicit automation. The flow is explained in details bellow the diagram.
Table 2. Detailed outline of the explicit automation execution flow:

A component receives a request to execute an automation.

For example; a CRM user pressed the button to send an email message, or to initiate an outbound phone call.

(Workflow specific) The RBAC facility checks if the invoker is allowed to execute the automation.

If the invoker is not allowed to execute the workflow, the request is rejected.

Custom security context (the run as option) does not affect the RBAC at this stage. If the automation in question was triggered by another automation, which defined the run as option, the RBAC will check over the specified invoker.

The automation is executed and the results are returned as a standard HTTP response.

The results provide the output of the automation, along with some metadata such as execution stack traces and error messages.

Deferred automation

An automation is considered deferred, if the trigger uses an onInterval on an onTimestamp event.

Deferred automation is invoked by the system based on the provided temporal information. The execution is not tied to an operation (such as a manual invocation or an event).

Under-the-hood, Corteza defines a ticker, that dispatches onInterval and onTimestamp events once every minute (can be configured via EVENTBUS_SCHEDULER_INTERVAL .env variable). The dispatched events are then used to match and invoke any automation with conforming triggers.

Corteza dispatches interval and timestamp events for the system and compose components. Internally, these events are the same, but are kept for legacy reasons.

Deferred automation requires you to explicitly set the invoking user as the automation is executed by the system and we are unable to determine the invoking user.
The diagram provides an abstract overview of the execution flow for deferred automation. The flow is explained in details bellow the diagram.
Figure 3. The diagram provides an abstract overview of the execution flow for deferred automation. The flow is explained in details bellow the diagram.
Table 3. Detailed outline of the explicit automation execution flow:

The system ticker dispatches an onInterval and an onTimestamp event.

The events are dispatched on the eventbus.

The automation is executed asynchronously and the results are ignored.

The execution value of the automation does not affect any other automation.

Sink automation

An automation is considered sink, if the trigger is bound to the System Sink resource.

A sink automation is executed when the system component receives an HTTP request to the /sink API endpoint. The execution is not tied to an operation (such as a manual invocation or an event).

Sink automation requires you to explicitly set the invoking user as the automation is executed by an external user and we are unable to determine the invoking user.
The diagram provides an abstract overview of the execution flow for sink automation. The flow is explained in details bellow the diagram.
Figure 4. The diagram provides an abstract overview of the execution flow for sink automation. The flow is explained in details bellow the diagram.
Table 4. Detailed outline of the sink automation execution flow:

The system component receives an HTTP request to the /sink API endpoint.

For example; GET $API/system/sink/leads/?__sign=$SIGN, where $API is the base URL to your Corteza API, and the $SIGN is the sink route signature.

Refer to the DevOps guide/sink routes for setup details.

The signature is validated

Firstly the sink signature is validated to make sure it was not altered.

Sink signatures are generated on-the-fly based on the JWT secret and are not stored in the database.

The signature is used to validate the request.

The system validates the protocol, headers, origin, and other signature constraints.

The onRequest event is dispatched on the eventbus.

If the automation is synchronous, the operation awaits for the dispatched event to resolve before continuing the initial operation. If the automation is asynchronous, the initial operation does not await.

The resulting value of the synchronous automation affects how the server should respond:

  • If the execution results as failed (an error occurred), the server responds with the error message and (optionally) error stack traces and other debugging metadata.

  • If the execution results as successful (no errors), the server prepares a response based on the execution result:

    • the status code and response headers are set,

    • the response body is encoded as a byte stream and sent as the response.

Currently only strings and byte slices can be used as the response.

Email automation

System email; receive/send

DevNote: @todo