Action types

Typed server-side mutations gated by the policy decision point — preconditions, postconditions, side effects, audit.

An action type is a typed, server-side mutation against the ontology. Examples: AssignAsset, FileSAR, EscalateCase, MergeEntities.

Unlike workflow tools (which wrap an external API call), action types operate on the ontology itself — they create or modify instances, create links, or change state. Every action is gated by the policy decision point and produces an audit event.

Why typed actions matter

Without typed actions, workflows would mutate the underlying data store directly — bypassing classifications, masking, and audit. Action types provide:

Typed input — the action declares its schema; callers can't pass arbitrary fields.
Typed preconditions — the action declares state requirements; failures are returned as typed errors, not silent corruption.
Typed side effects — the action declares what it changes; reviewers can see the full impact.
Authorisation — every dispatch goes through the policy decision point with the caller's identity.
Audit — every dispatch produces an event with the actor, action, target, and outcome.

Anatomy

Field	Purpose
`id`	The action's identifier (e.g. `AssignAsset`).
`title`	Human-readable name.
`input`	The input schema (typed properties).
`preconditions`	Predicates that must hold on the input before the action runs.
`effect`	The mutation itself — what changes.
`postconditions`	Predicates the system asserts after the effect — guarantees for downstream callers.
`auditMetadata`	What's recorded in the audit event.

Example

defineActionType({
  id: "AssignAsset",
  title: "Assign Asset",
  input: {
    assetId: { type: "string", required: true },
    userId: { type: "string", required: true },
  },
  preconditions: [
    { rule: "asset-exists",        params: { ref: "assetId" } },
    { rule: "user-in-workspace",   params: { ref: "userId" } },
    { rule: "asset-unassigned",    params: { ref: "assetId" } },
  ],
  effect: {
    kind: "update-object",
    type: "Asset",
    set: { ownerId: "{userId}", assignedAt: "{now}" },
  },
  postconditions: [
    { rule: "asset-owner-equals", params: { ref: "userId" } },
  ],
});

Dispatch

Actions are dispatched from:

A workflow agent — the Run Ontology Action tool.
The workbench — manual dispatch from the Actions tab.
Custom UI — via the platform API with a workspace-scoped session.

In all three cases, the dispatch passes through:

Schema validation — input must match the declared types.
Authorisation — the policy decision point evaluates the caller's identity against the action.
Precondition evaluation — all preconditions must pass; failure returns a typed PreconditionFailed error.
Effect execution — the mutation runs inside a transaction.
Postcondition verification — failures roll back the transaction.
Audit emission — a structured event lands in the audit log.

A failed action is observable. If a precondition fails, the caller gets a typed error; the audit log records the attempt; no partial mutation happens. Workflows can branch on the error class.

Idempotency

Actions can declare an idempotency key. Re-dispatching the same action with the same key inside the idempotency window returns the prior result without re-executing. Useful for retry-safe workflow patterns.

Authorisation

Each action declares which roles or grants are needed to dispatch it. A workspace member without the right grant can't see the action in the workbench, and a workflow without the right grant can't call the Run Ontology Action tool against it.

Concepts → Action types — where actions fit in the five layers.
Using in workflows — how an agent dispatches an action.
Security → Authorization — how the policy decision point evaluates dispatches.
Audit logging — what every action emits.