Automation Script Anatomy

To better understand the process of implementing custom functionalities with the automation system, we define and describe the anatomy of automation scripts, and establish a few rules. An automation script is considered valid if:

a given .js file is structured under client-scripts or server-scripts directory,
a given .js file exports exactly one JS object with the export default keyword,
a given script defines at least one valid trigger or iterator definition,
a given script defines the security context if the script is a deferred or sink script,
a given JS object defines an exec (args, ctx) function.

Invalid automation scripts are still processed by the Corredor, but are excluded from further operations. Detected errors are visible in the Corredor logs. This allows for easier debugging.

Overview of script object properties and function

label: Automation script’s label, used to provide a user-friendly identification of the automation script,
description: A more verbose automation script description,
security: Defines automation script’s security context and role based filtering,
triggers: Defines automation script’s triggers as propery or method. Not compatible with iterator,
iterator: Defines automation script’s iterator as property or method Not compatible with triggers,
exec: Execution function that is invoked when the automation script is triggered.

Security

Script’s security property allows definition of user who’s credentials will be used when executing the script. It also allows access control by defining list of allowed and denied roles that can execute it.

security.runAs: Define security context for the automation script,
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,

security.runAs parameter is only valid for server scripts.

Exec function

The execution function defines the actual code for the automation script, and conforms to the following interface:

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

Execution arguments

Execution arguments (first argument) contain the arguments that the automation script can work with, such as a newly created record, updated module, deleted page, … Arguments depend on the automation script’s event and resource (see [ext-resevt]).

Execution context

Execution context (second argument) contains contextual information about the execution, such as security context, helper class instances, API clients, loggers, …

ctx.console: console object that can be 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: Full blown API for Corteza System interaction,
ctx.ComposeAPI: Full blown API for Corteza Compose interaction,
ctx.MessagingAPI: Full blown API for Corteza Messaging interaction,
ctx.System: Helper class instance for the Corteza System,
ctx.Compose: Helper class instance for the Corteza Compose,
ctx.ComposeUI: Helper class instance for the Corteza Compose 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.

Automation script execution result

When the script’s execution is complete, it should provide one of the following results:

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

If the resource defines a before event variant, the return value will be used as the updated version of that resource. For example: if the automation script is defined with the resource type of compose:record and returns the updated version of the args.$record value, the existing version is replaced by the updated version.

Server script vs. client script

There is a small deviation when it comes to client and server script executions. One of the differences is that, when it comes to client scripts, the arguments are provided as a reference, meaning that any changes to the resource are reflected to the original object. Because of that the resource does not need to be returned in order for the changes to take effect.

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

If your script should be able to revert the changes, in case of an error, you should use an intermediate object for the new values. For example:

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

    try {
      await apiOperation($record)
    } catch (e) {
      throw new Error(e)
    }

    $record.setValues(v)
  },
}