Actions guide

Turn a business operation into one backend call.

Declare the request contract, validate it, execute ordered outcomes, and return a response the client can act on.

Input fields
Ordered outcomes
HTTP + GraphQL

Start with one observable action.

Actions:
  - Name: greet_user
    Label: Greet user
    OnType: user_account
    InstanceOptional: true
    InFields:
      - Name: name
        ColumnType: label
        IsNullable: false
    OutFields:
      - Type: client.notify
        Method: ACTIONRESPONSE
        Attributes:
          type: success
          message: "~name"

Call it at POST /action/user_account/greet_user with an attributes object. Schema-file definitions load on startup; actions created or changed through the API also require a server restart in the latest release.

Build the operation in layers.

Inputs

Name and type every client value. Add validation and conformations before an outcome consumes it.

Conditions

Skip or select outcomes from explicit conditions rather than reproducing branching in the frontend.

Outcomes

Create, read, update, or delete records; invoke registered performers; call providers; or return client responses.

Instance scope

Require a record reference when the operation acts on one object, or mark the instance optional for collection-level work.

Test the action permissions and effects.

Valid input returns the expected response and database state.
Missing, malformed, and unauthorized input fails before protected outcomes run.
Every action has intentional Execute and Peek permissions.
A failed database outcome rolls back related database work in the request transaction.
External HTTP, mail, or provider side effects are not described as transactionally reversible.
ContinueOnError is enabled only where partial outcome execution is intentional.
The action works through each interface the product will use.

Failure rehearsal

Test the operation as a single contract.

Invalid input fails before outcomes begin.
A caller without action permission receives no partial result.
A failed database outcome rolls back database work in the action transaction.
External HTTP, mail, or storage effects are designed for retry and idempotency because SQL rollback cannot undo them.
Definitions created or changed through the API are checked after the required server restart in the latest release.

Run the same operation on a schedule.

Return to Actions →Scheduled work guide ↗