Automation Scripts

As with any system, automation scripts can cause unwanted complications if misused or left open for modification by users who may do harm, willingly or otherwise.

You (or whoever will configure this system) is responsible for making sure scripts are written in a way that do not cause problems to users or the underlying system running them.

Triggers

When an event is fired it triggers automation script that receives a context. Context is a set of information about the event and parameters needed for automation script.

Supported scenarios:
  • when record is created, changed or deleted, triggers can be placed before or after this event

  • when user executes manual script for record automation

  • on configured interval

  • on specific date and time

Low Code administrator assign one or more scripts that will be executed on a specific event.

Environment limitations
  • backend scripts do not support UI manipulation, redirection

  • browser (or frontend, user-agent) scripts can not use external libraries

  • interval and time-triggered scripts can only be executed on the backend

When a certain triggered, context is created with record, module and current user and send to Corredor (automation script execution engine). Corredor verifies authenticity of the user and his credentials and executes the assigned script. Script can read and change given record from the context and access, modify or delete any other Corteza resource via API.

Security

Script can be configured to be executed with security context of the user triggering the event or with security context of a predefined user.

Example scenario:
  • User creates a Client record in Compose. This triggers a script that create a new user. User creation is only allowed to administrators and script can be ran with privileges of an administrator

Modern JavaScript

About async/await and Promises

If you are not familiar with Promises, we strongly recommend reading MDN article about using promises

In short: Promises solve problem of asynchronous code and remove the need for cumbersome callbacks via function parameters. They provide a simple and readable syntax and error handling via .catch().

About use of await/async syntactic sugar

You will find examples with await prefix. You can not use this on the global scope of the script, it will result in "await is only valid in async function syntax error".

You can, however wrap your code with (async () ⇒ { …​ }()) and place your await calls there.

The arrow function expression (⇒)

MDN article about arrow functions

Context

Authenticated user ($authUser)

Access info (User object) about the authenticated user (user who’s running the script)

Current $record, current $module

On automatically triggered scripts (before/after-create/update/delete) events and manually triggered scripts on record-pages, scripts can use $record and $module variables to access current record and/or current module.

In all methods where there is a function param for record or module that param can be omitted (or NULL-ed) and function will use current record or module (when available)

Module parameter

Resolution rules for module parameter in every ComposeHelper class method:

  • if string contains only digits, use as module ID and load module

  • if string, use as module name and load module

  • object, verify that it has namespaceID and moduleID properties

  • if null, use current $module (when available)

Including outside libraries & modules

In Corredor (non-browser) automation scripts we allow a predefined list of libraries you can use:

axios

A JavaScript utility library delivering consistency, modularity, performance, & extras.

This is the library used by Corteza API clients.

Visit https://github.com/axios/axios for more info

const axios = require('axios')

// ...
request

Request is designed to be the simplest way possible to make http calls. It supports HTTPS and follows redirects by default.

const request = require('request')

// ...
lodash

A JavaScript utility library delivering consistency, modularity, performance, & extras.

const _ = require('lodash')

// ...

Returning values

You can abort script execution by returning (return …​) at any point in the script. Returning false will cause abort and will prevent record create/update/delete in before* triggers.

You can always return the (changed) record you’re currently running the script for and cause that a modified (by your script) version of an object is then passed back to Compose. This can be used in beforeCreate and beforeUpdate triggers to save modified version or in manual triggers to change the current record on the fly (even without explicitly saving it in the script)

Modifying current $record and returning from automation script

Rules:
  • Critical scripts have to be executed successfully and return [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) value.

  • If automation scripts returns Record system will update current $record (if Module then $module, etc…​)

  • Modifications of $record (and other $*) and return values of async scripts are ignored

  • Modifications of $record (and other $) and return values of after triggers are ignored

Interacting with the outside world

List filtering & sorting

API endpoints for resource set/lists support filtering, sorting and paging of resources.

Record filtering & sorting

Some limitations: - searches only within a one module and within a one namespace - has max limit of 100 records for perPage with 50 records as default

Syntax

SQL syntax should be used for filtering (WHERE <filter>) and sorting (ORDER BY <sort>). API supports simple arithmetics (+, -, *, /), boolean (AND, OR, NOT) and comparison operators (<, >, =, ⇐, >=)

Sorting

All module fields are case-sensitive and can be used for filtering and sorting

Record’s system fields
  • ownedBy, user (ID) that owns this module

  • createdBy, created by user (ID)

  • updatedBy, updated by user (ID)

  • deletedBy, deleted by user (ID)

  • createdAt, created on (date + time)

  • updatedAt, updated on (date + time)

  • deletedAt, deleted on (date + time)

Functions that can be used with the fields:
  • QUARTER(ts)

  • YEAR(ts)

  • DATE(ts)

  • NOW(ts)

  • DATE_ADD(ts)

  • DATE_SUB(ts)

  • DATE_FORMAT(ts)

Sorting:

  • someField, order by someField, ascending

  • someField DESC, order by someField, descending

  • YEAR(someDate) DESC, someOtherField, order by descending by year and everything inside one year, ascending by someOtherField