Skip to content

Named actions

A named action is an operation with a name, such as promote or release. The user runs it from the document page menu, Facet checks the typed arguments, and a Lua function in the doctype script does the work. An action lands in the history as the changes it made, next to plain edits.

Add an action when a change needs more than an edit: a state rule, several fields moved together, or a value derived from arguments. If the rule only checks one field, a pattern or a lifecycle guard is simpler (see Lifecycle scripts and guards).

  • A script. A doctype that declares actions must carry a script, and the script must define one function per action.
  • A permission. Users need a permission whose action name equals the action key, for example promote on hr.Employee.
  • A free name. validate, create, and update are reserved names; they belong to the lifecycle.
"actions": {
"release": {
"description": "Release the order to production",
"states": { "status": ["approved"] },
"args": {
"note": { "type": "string", "required": true, "max": 200 }
}
}
}
Key Purpose
args Typed arguments. Facet checks type, required, min/max, default, and a closed values list before the script runs.
states The field values the document must carry before the action is offered. An action without states is always offered.
description The text the action editor shows.

The script exports one function per action. It receives the context ctx and the checked arguments args, and it changes the document by writing to ctx.root.

Add a permission line with the action name to a role:

{ "action": "release", "on": "projects.Order" }

Without the line, the menu entry stays hidden and a direct call answers 403.

In the app, open a document and pick the action from its menu. Facet checks the arguments, runs the script, and shows the result.

The complete script below implements release. It re-checks the state rule, sets three fields, and stamps the time.

local export = {}
function export.release(ctx, args)
if ctx.root.status ~= "approved" then
ctx.error("Only approved orders can be released")
return
end
ctx.root.status = "released"
ctx.root.released_at = ctx.now
ctx.root.release_note = args.note
end
return export

The call runs the action on one document:

Terminal window
curl -k -X POST "https://facet.localhost:3443/Api/projects/Order/01HQ2F5WX8K4M3PZC6NRB9TJVA/release" \
-H "Authorization: Bearer $FACET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"note": "Budget confirmed"}'

-k skips the certificate check of the local development address. Facet stores one history entry with the fields the action changed.

The document state does not match the states gate, or your role lacks the action permission.

The call answers 422 with an argument error

Section titled “The call answers 422 with an argument error”

An argument is missing, out of range, or outside a closed values list. The message names the argument.

The Lua function raised an error it did not catch. The message carries the line number in your script. Fix the script and save the doctype; the definition cache updates a second or two later.

The function returned without changing ctx.root. Facet stores no history entry when an action changes nothing.