Extensions

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 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.

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')
},

Automation triggers

An automation trigger (later refereed as "trigger") specifies under what conditions an automation script should execute and part of the execution context.

The main difference between triggers and iterators is, that an iterator is executed for multiple resources defined by the constraints, one after another.

A trigger is executed for a single resource defined by the constraints.

Triggers are defined by the triggers (t) {…} method defined by the automation script.

Triggers are evaluated in an isolated context, outside of the actual automation script. This prevents use of any constants or other symbols defiled outside of the trigger.

For example, the following trigger will not work:

const modName = 'Contact'
export default {
  triggers ({ on }) {
    return on('manual')
      .for(modName)
  },
  exec (args, ctx) {...}
}

Trigger and iterator are not compatible; you can only use one or the other within the same automation script.

Conventions

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')
},

Trigger interface

t.on: Defines the event type, such as 'manual', 'request' (see resources and events).

Not compatible with t.before, t.after, t.on, t.at.

t.before: Defines that the automation script is executed before a specific operation occurs.

You can define multiple event types for the given resource.

For example: before('create', 'update', 'delete')

Not compatible with t.on

t.after: Defines that the automation script is executed after a specific operation occurs.

You can define multiple event types for the given resource.

For example: after('create', 'update', 'delete')

Not compatable with t.on

t.at: Defines that the automation script is executed at a specific time, defined as a ISO 8601 timestamp.

Not compatable with t.on

t.every: Defines the interval in which the automation script is executed, defined as a cron expression.

Not compatable with t.on

t.for: Defines the resource type, such as 'compose:record' (see resources and events).
t.where: Defines the constraints that must match in order for the automation script to be executed (eg. t.where('module', 'Lead')). Refer to constraint resources for the full list of available resources and constraint options. See Trigger constraints for extra bits on this.

You can define multiple constraints inside the same trigger.

For example: .where('module', 'super_secret_module').where('namespace', 'super_secret_namespace')

t.uiProp: Defines the visual representation of the manual automation trigger, such as its color and label.

Only available for explicit scripts.

Trigger types

Explicit

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

Manual: They most commonly appear inside Low Code automation page blocks or inside Low Code record list toolbars.

Implicit

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

Deferred

Deferred automation triggers are executed at most once every minute, so you should not define an interval or timestamp that uses higher precision (seconds or milliseconds).

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

Scheduled: scheduled triggers are executed at an exact time specified by a time stamp in ISO 8601 format (This one — YYYY-MM-DDTHH:mm:ss.sssZ). This trigger is executed exactly once.
Interval: interval triggers are executed periodically in an interval defined by a cron expression (see robfig/cron package for details).

Sink

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.

Trigger constraints

Trigger constraints allow you to specify when the script should be executed based on the resource that would like to execute it. Constraints take 2 + 1 arguments:

t.where(
  resourceAttribute,(1)
  comparator/value,(2)
  [value],(3)
)

1	The resource attribute that the constraint should check against. Refer to resources and events for a complete list of available things.
2	When 2 arguments are provided, this is the value to check against; when 3 arguments are provided, this is the comparison operator; see below.
3	When provided, this is the value to check against.

Available comparison operators:

Equals (default)

eq
=
==
===

Not equals

not eq
ne
!=
!==

Partial comparison

like

Supported wildcards:

one or more characters: %, *,
one character: _, ?.

Partial comparison; negated

not like

Supported wildcards:

one or more characters: %, *,
one character: _, ?.

Regex comparison

Regex comparison; negated

!~

Automation iterators

An automation iterator (later refereed as "iterator") specifies under what conditions an automation script iterator should execute and part of the execution context.

The main difference between triggers and iterators is, that an iterator is executed for multiple resources defined by the constraints, one after another.

A trigger is executed for a single resource defined by the constraints.

Iterators are defined by the iterator (i) {…} method defined by the automation script.

Iterators are evaluated in an isolated context, outside of the actual automation script. This prevents use of any constants or other symbols defiled outside of the iterator.

For example, the following iterator will not work:

// @todo provide an example, similar to how triggers have it.

Trigger and iterator are not compatible; you can only use one or the other within the same automation script.

Iterator interface

i: Defines the resource, action and the filter used for resource fetching. Passed object must conform to the interface:

interface {
  resourceType: string; (1)
  eventType: 'onManual' | 'onInterval' | 'onTimestamp' = 'onManual'; (2)
  action: 'update' | 'delete' | 'clone' | '' = ''; (3)
  filter: IteratorFilter; (4)
}

1	define the resource type; see resources and events for details.
2	define the event type; see resources and events for details.
3	define what action the script performs; see Iterator actions for details,
4	define the filter to use.

interface IteratorFilter {
  query: string; (1)
  sort: string; (2)
  limit: number | string; (3)
  offset: number | string; (4)
  [_: string]: number | string; (5)
}

1	SQL like query filter to use (`WHERE <query>`).
2	SQL like sort to use (`ORDER BY <sort>`).
3	Maximum number of resource.
4	Offset from first record.
5	additional non-standard resource specific parameters. `i.at` Defines that the automation script is executed at a specific time, defined as a ISO 8601 timestamp. `i.every` Defines the interval in which the automation script is executed, defined as a cron expression.

Iterator actions

Iterator script doesn’t perform any operation on the resource except if explicitly specified by the action property.

update: The result of the automation script will be used to update the original resource.
delete: The result of the automation script will be used to delete the original resource.
clone: The result of the automation script will be used to create a new resource with updated values; original resource is left unchanged.

API clients

API clients simplify the process of accessing information stored inside Corteza via the API. API clients can be found in the GitHub corteza-js repository.

When writing automation scripts, these API clients are automatically provided via the execution context.

These API clients greatly simplify the code so you should always use these instead of writing your own.

Corredor helpers

Corredor helpers simplify some of the more common operations that are usually performed inside automation scripts — creating records, filtering for specific records, creating messages, … These can be found in the GitHub corteza-js repository and the GitHub corteza-vue repository.

When writing automation scripts, these helpers are automatically provided via the execution context.

These helpers greatly simplify the code so you should always use these instead of writing your own.

These helpers can also be used outside of automation scripts, when creating portals based on Corteza, for example.

Corredor helpers are context-aware, meaning that they can determine some parts of the execution context on their own. For example, when a script is run for a record creation. ComposeHelper can automatically determine what namespace was used, what module and the created record.

Security Context

The security property allows you to manage security and access related things from inside the automation script.

Deferred and sink scripts require you to specify the security context as the invoker is unknown.

Iterators require you to specify the security context as the invoker is unknown.

You can specify the following:

security.runAs: Specify what user credentials should be used when executing the automation script. For example, if the value of admin@corredor.crust.tech is provided, the given user’s credentials will be used instead of the invoking user.

This is available only inside server-scripts.

security.allow: Explicitly define what roles have access to the automation script.
security.deny: Explicitly define what roles do not have access to the automation script.

Instead of giving users more permissions you can create a new system user with valid permissions and define the scripts security context.

Script execution

What operation the given script performs is determined by the execution function (referred to as the exec function). The function conforms to the following interface:

interface ScriptFn {
  (args: exec.Args, ctx?: exec.Ctx): unknown;
}

Execution arguments

Arguments to a client-script are provided via references to the original objects, meaning that any change to the argument parameter will reflect to the original object.

For example, running the following code in the client script’s exec function will reflect the values without the need of returning the updated record.

{
  ...
  async exec ({ $record }) {
    $record.values.Field1 = 'value1'
    $record.values.Field2 = 10
  },
}

The execution arguments provide an object containing all of the arguments related to the given operation and resource. For example, when working with records this will contain the $record, $module and $namespace.

Refer to resources and events for a complete list of available arguments.

Execution context

The execution context provides an object containing things related to the given system. It contains:

ctx.console: Used for logging. When running in the UA, this will be native window.console. When running in Corredor, this will be a Pino instance,
ctx.log: Shortcut for ctx.console.log,
ctx.$authUser: User object corresponding to the security context,
ctx.SystemAPI: API client for Corteza System interaction,
ctx.ComposeAPI: API client for Corteza Low Code interaction,
ctx.MessagingAPI: API client for Corteza Messaging interaction,
ctx.System: Helper class instance for the Corteza System,
ctx.Compose: Helper class instance for the Corteza Low Code,
ctx.ComposeUI: Helper class instance for the Corteza Low Code user interface,
ctx.Messaging: Helper class instance for the Corteza Messaging,
ctx.frontendBaseURL: Base URL used by front-end web applications. This is useful when generating URL’s inside server scripts.

Execution result

Unknown Error: An error aborts the script’s execution chain (the current script and all following scripts).
Aborted Error: An error with the value of 'Aborted' stops the execution of the current automation script. Any further scripts down the chain are executed as usual.
false: Same as aborted error. A return value of false stops the execution of the current automation script. Any further scripts down the chain are executed as usual.
unknown: Any other return value specifies that the execution was successful and the following script (if any) can execute.

Debugging

Why is this script not valid?

An automation script is valid if:

Defined in a .js file,
is located under client-scripts or server-scripts,
it defines an export default {…},
defines at least one valid trigger or iterator,
defines a security context if it the script is a sink or deferred,
conforms to the Script signature.

1	Dependencies to use.
2	Undefined file structure. Can be used for assets, tools, common scripts, test configuration, …

Extensions

TL;DR

Script signature

File structure

Server-scripts

Client-scripts

Meta

Server-scripts

Use when

Example use case

Client-scripts

Use when

Example use-cases

Automation triggers

Explicit triggers

Implicit triggers

Deferred triggers

Sink triggers

Automation iterators

Conventions

Writing triggers

Automation triggers

Conventions

Trigger interface

Trigger types

Explicit

Implicit

Deferred

Sink

Trigger constraints

Available comparison operators:

Automation iterators

Iterator interface

Iterator actions

API clients

Corredor helpers

Security Context

Script execution

Execution arguments

Execution context

Execution result

Debugging

Why is this script not valid?

Testing