Corteza Extending and Customizing ⛏
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.
-
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.
-
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.
-
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:
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 is designed to be the simplest way possible to make http calls. It supports HTTPS and follows redirects by default.
Visit https://github.com/request/request for more info
const request = require('request')
// ...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
-
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
-
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)
-
QUARTER(ts) -
YEAR(ts) -
DATE(ts) -
NOW(ts) -
DATE_ADD(ts) -
DATE_SUB(ts) -
DATE_FORMAT(ts)