Scripts Overview

Scripts define actions that can be triggered on objects. They can run automatically when an object is created or updated, or they can be triggered manually by the user.

Script types

Scripts fall into two categories:

• Actor scripts — perform side effects on objects. Triggered via POST, run automatically on create/update, or invoked manually from the UI.
• Producer scripts — return a list of results without modifying any object. Always invoked on demand via GET. See Sources for details.

Type	JSON value	Category	Description
JavaScript	JAVASCRIPT	Actor	Run a JavaScript function, inline or from a file.
JavaScript producer	JAVASCRIPT_PRODUCER	Producer	Run a JavaScript function that returns a list of results. See Sources.
Consumer Gateway	CONSUMER_GATEWAY	Actor	Call an external service (e.g. send an email).
Function Gateway	FUNCTION_GATEWAY	Actor	Call an enrichment function and write the results back to the object.
Producer Gateway	PRODUCER_GATEWAY	Producer	Query an external source and return a list of results.

Common properties

All script types share these properties:

Property	Type	Default	Description
name	string	—	Unique identifier for this script within the class.
type	string	—	One of JAVASCRIPT, JAVASCRIPT_PRODUCER, CONSUMER_GATEWAY, FUNCTION_GATEWAY, PRODUCER_GATEWAY.
apiVersion	integer	1	For a JavaScript script: the script API version it was written for. For a gateway script: the version of that gateway's contract.
scope	GENERAL | OBJECT	—	OBJECT: applies to a specific class. GENERAL: not tied to a specific object.
trigger	string[]	["MANUAL"]	When the script runs: one or more of MANUAL, CREATE, UPDATE, DELETE, e.g. ["CREATE", "UPDATE"].
parameters	Parameter[]	—	Input values passed to the script.
preconditions	string[]	—	Formula expressions that must all evaluate to true before the script runs.
triggerValues	string[]	—	For UPDATE trigger: the names of the fields to watch. The script only runs when at least one of these fields was modified. To filter on a specific value, combine with preconditions.

Parameters

Parameters pass values into a script. Each parameter has a name and exactly one value source:

Property	Description
value	A literal value.
formula	A formula expression evaluated on the current object.
template	A Handlebars template string evaluated on the current object.
templateFile	Path to a template file, relative to the repository root, including the .hbs extension.

{
  "name": "email",
  "dataType": "EMAIL",
  "formula": "emailAddress"
}

{
  "name": "subject",
  "dataType": "TEXT",
  "value": "You have been invited"
}

{
  "name": "message",
  "dataType": "TEXT",
  "templateFile": "templates/invitationMailText.hbs"
}

Preconditions

Preconditions are formula expressions. The script only runs if all preconditions evaluate to true. They are evaluated on the current object before the script executes.

{
  "preconditions": ["emailAddress != null", "activeDate != null"]
}

Triggers

The trigger property is an array of one or more values:

"trigger": ["UPDATE"]

"trigger": ["CREATE", "UPDATE"]

Value	UI label	When it runs
MANUAL	"Manual Action"	The script appears as a button in the UI. The user clicks it to run it.
CREATE	—	Runs automatically when the object is first created.
UPDATE	—	Runs automatically every time the object is saved.
DELETE	—	Runs automatically after the object is deleted. See below.

UI label mismatch

The UI displays manual scripts as "Manual Action", but the enum value in JSON is "MANUAL" — not "MANUAL_ACTION". "MANUAL_ACTION" is an invalid value and refuses the model (see below).

Invalid trigger values

An unrecognised trigger value refuses the whole model, with an error naming the file and the JSON path of the value. The previously loaded model keeps serving the tenant until it is fixed — see Loading a model. Always use one of the four documented values: MANUAL, CREATE, UPDATE, DELETE.

DELETE trigger

DELETE scripts run after the object has been removed from the data store. Because the object no longer exists at execution time, the platform constructs a stub containing only the object's id, tenant, and class — no field values are available.

Practical implications:

• Field formulas in parameters (e.g. "formula": "status") resolve to null for DELETE invocations.
• The object id is always available and sufficient to identify the row in external systems (e.g. for a hard delete in an analytics table).
• If a delete is blocked (e.g. by a precondition or a referential constraint), no DELETE scripts run.

Both CONSUMER_GATEWAY and JAVASCRIPT scripts support the DELETE trigger.

The _trigger parameter is automatically injected into all auto-triggered scripts with the value CREATE, UPDATE, or DELETE. Consumer gateways can read it via parameters.get("_trigger"); JavaScript scripts via params._trigger. For scripts invoked via api.runScript(), _trigger is absent.