Shared patterns

The examples in this section use the JavaScript Domain and Action APIs shared by the scripting features. Start with basic Domain operations for retrieval and CRUD, then use advanced Domain queries for filter syntax, references, null handling, and object initializers. The Domain API reference explains the underlying operations.

These are reusable fragments, not complete scripts. A user business rule or calculated attribute can receive subject; a managed script receives declared values through args; a freeform ExecuteScript request receives neither automatically. Obtain IDs and Domain objects from the relevant execution context. Modifications participate in the current transaction and take effect only if it commits.

Special Domain types

When customer has a configured CustomerTier custom property:

const tier = customer.CustomProperties["CustomerTier"].Value;
customer.CustomProperties["CustomerTier"] =
    new Domain.Types.CustomPropertyValue("Platinum", "Highest tier");

For a multilingual description, create a new value rather than changing an existing one:

const description = new Domain.Types.MultilanguageString({
    en: "Preferred customer",
    bg: "Предпочитан клиент"
});
customer.CustomProperties["CustomerTier"] =
    new Domain.Types.CustomPropertyValue("Platinum", description);

An amount needs a currency object, and a quantity needs a unit object. Neither accepts a currency or unit name in place of the Domain object:

const amount = new Domain.Types.Amount(10, currency);
const total = Domain.Types.Amount.Multiply(amount, 5);

const quantity = new Domain.Types.Quantity(10, unit);
const doubled = Domain.Types.Quantity.Multiply(quantity, 2);

See Domain special types for their value semantics.

Log, cancel, and inspect context

Action is available without an import:

Action.log("Processing started");
Action.error("A validation failed");

To reject the current operation from a rule:

Action.cancel("This operation is not allowed.");

User and session information can be absent in some invocation contexts:

const userId = Action.user.id;
const sessionId = Action.session.id;

Action.log and Action.error write their messages in a separate committed transaction. See the Action reference for other fields and operations.

Notify a user

Action.notify.user requires an entity execution context, such as an entity-triggered business rule. Retrieving an entity inside a managed script does not by itself provide that context:

Action.notify.user(
    "6dc7e681-8b65-4095-beb1-b3bc0c948b7c",
    "Please review this record.");

Call an HTTP service

Action.http uses the host's network policy. Check the response and do not embed secrets in script source:

const response = Action.http.get("https://api.example.com/status");
if (!response.isSuccess)
    throw new Error("HTTP " + response.statusCode);

Action.log(response.body);

For a JSON POST, serialize the request and set its content type:

const response = Action.http.post(
    "https://api.example.com/items",
    JSON.stringify({ value: 42 }),
    "Content-Type: application/json");

Create and update an attached file

An attached file needs a folder or entity owner. This example creates a root folder, then a text file in it:

const folder = Action.files.createFolder({ name: "Exports" });
const file = Action.files.createFile({
    folder,
    name: "result.txt",
    mediaType: "text/plain",
    content: "First result"
});
file.writeText("Updated result");