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

TL;DR

Script signature

An automation script must conform to the given interface:

export interface Script extends ScriptFile {
  label?: string;(1)

  description?: string;(2)

  security?: {(3)
    runAs?: string;
    deny: string[];
    allow: string[];
  }|string;

  triggers?: Trigger[];(4)

  iterator?: Iterator;(5)

  exec?: ScriptFn;
}
1 User-friendly name for the script.
2 Additional description if needed.
3 Security context for the script; if defining runAs, you can provide a string.
4 Script triggers; refer to [extensions:automation-triggers] for details.
5 Script iterator; refer to [extensions:automation-iterators] for details.

File structure

Server-scripts

/server-scripts (1)
    /... (2)
1 Root folder for all server scripts (under each search path).
2 Undefined file structure; can be defined as needed.

Client-scripts

/client-scripts (1)
    /auth (2)
        /... (7)

    /admin (3)
        /... (7)

    /compose (4)
        /... (7)

    /messaging (5)
        /... (7)

    /shared (6)
        /... (7)
1 Root folder for all client scripts (under each search path).
2 Defines a bundle for Corteza Auth.
3 Defines a bundle for Corteza Admin.
4 Defines a bundle for Corteza Low Code.
5 Defines a bundle for Corteza Messaging.
6 Reserved directory for any shared logic, such as custom libraries, assets, …​
7 Undefined file structure; can be defined as needed.

Meta

/package.json(1)
/...(2)
1 Dependencies to use.
2 Undefined file structure. Can be used for assets, tools, common scripts, test configuration, …​

Server-scripts

Server-scripts are executed in the Corteza Corredor server.

Use when

  • Interaction with the user is not required,

  • response latency is not as important,

  • execution consistency is important,

  • automation script produces a heavy load on system resources.

Example use case

  • Insert additional record fields based on an external data source,

  • send an email when a new user signs up,

  • run statistic operations once a month for reporting purposes.

Client-scripts

Client-scripts are executed in the client’s browser (user agent; UA).

Use when

  • Interaction with the user is required,

  • response latency should be minimal,

  • execution reliability is not important,

  • we are not working with sensitive information such as authentication tokens or api credentials,

  • automation script produces a light load on system resources.

Example use-cases

  • Prompt user to confirm form submission,

  • validate or modify form’s data before submission,

  • redirect the user to another page; either in Corteza Low Code or other,

  • open an external resource inside a popup window.

Automation triggers

An automation triggers specify under what conditions an automation script should be executed execute and its execution context.

Explicit triggers

Explicit triggers execute on a specific user invocation, such as a button press. These include:

  • Manual.

Implicit triggers

Implicit triggers execute as a collateral to another system event such as record creation. These triggers include any before/after event. For a full list of events see resources and events.

Deferred triggers

The minimum time precision is 1 minute.

Requires explicit security context.

Only available inside server-scripts.

Deferred automation triggers are executed at a specific point in time; once or multiple times, such as a reminder. These include:

  • Scheduled,

  • interval.

Scheduled triggers use a ISO 8601 timestamp.

Interval triggers use cron expressions.

Sink triggers

Only available inside server-scripts.

Requires explicit security context.

Sink automation triggers are executed on a specific http request. They can be used to implement new routes on the API, such as a web hook to some external service.

Automation iterators

An automation iterators specify under what conditions an automation script iterator should execute and part of the execution context.

The given operation is executed over a set of resources defined by the iterator.

Conventions

Writing triggers

Use object destructuring

This helps you shorten the entire thing. For example:

// Instead of using:
triggers (t) {
  return t.after('create')
    .for('compose:record')
    .where('module', 'super_secret_module')
},

// you can do:
triggers ({ after }) {
  return after('create')
    .for('compose:record')
    .where('module', 'super_secret_module')
},

// Neat, right?!
Make trigger constraints as strict as possible

Having loose constraints can cause unwanted issues when there are multiple namespaces under the same Corteza Low Code. Two namespaces could easily define a module with the same handle, which would cause both of them to execute the given script. For example:

// Instead of using:
triggers (t) {
  return t.after('create')
    .for('compose:record')
    .where('module', 'super_secret_module')
},

// you can do:
triggers ({ after }) {
  return after('create')
    .for('compose:record')
    .where('module', 'super_secret_module')
    .where('namespace', 'super_secret_namespace')
},