Conditions

Write GROQ conditions over the engine’s bounded instance snapshot: what the snapshot holds, which sites bind the caller, named predicates, and the start filter and requirements.

Conditions are GROQ expressions that answer a yes-or-no question about workflow state. Where a condition sits — its site — decides what data it can read and what its answer controls.

const articleReview = defineWorkflow({
  name: 'article-review',
  title: 'Article review',
  initialStage: 'review',
  fields: [
    defineField({type: 'subject', name: 'subject', initialValue: {type: 'input'}, required: true}),
    defineField({type: 'boolean', name: 'approved'}),
  ],
  stages: [
    defineStage({
      name: 'review',
      transitions: [
        defineTransition({name: 'publish', to: 'published', when: '$fields.approved == true'}),
      ],
    }),
    defineStage({name: 'published'}),
  ],
})

The engine evaluates each condition as GROQ against a context it builds for that one decision. A condition is not a free-ranging Content Lake query. The condition variable reference lists the GROQ variables available at each condition site.

For a running instance, the engine builds a limited in-memory snapshot. It holds:

• The current instance, its ancestor instances, and live spawned child instances.
• Accessible content documents declared by subject, doc.ref, and doc.refs fields at workflow or current-stage scope.
• The release document declared by a release.ref field.

Documents that are missing or unreadable are not there at all, and the engine does not follow references beyond the first hop. Single reference fields resolve to full documents in $fields, while doc.refs stays an array of reference identities. See Fields and Global document references for those contracts.

Use $now for the engine’s evaluation time. It is an ISO-8601 string; use dateTime($now) when an expression needs a datetime value. Definition validation rejects now() and dateTime::now() in conditions, predicates, spawn expressions, start.filter, and GROQ start requirements. Replace them with $now and dateTime($now), respectively. This lets the runtime identify expressions that need clock-driven reevaluation.

Query-based field initial values are the exception: they run when a field enters scope, may use the GROQ clock functions, and also receive $now. See Query values.

A condition site either has a caller acting at it or it does not, and that decides whether the condition can read one. Three sites are caller-bound: the filter on an action a caller fires, an activity’s requirements, and an editable predicate. Those three bind $actor, $assigned, $can, and $attributes, so a rule such as "only the assigned reviewer may approve" belongs at one of them.

Routing is caller-blind on purpose. A transition’s when, an activity’s filter, and a cascade-fired action’s when and filter are re-evaluated by whatever legitimate call comes along next, so they have to give the same answer no matter which token drives them. Reading a caller at one of those sites would be asking about a caller who is not there, so defineWorkflow rejects the definition, and deploy runs the same check again, rather than letting the condition quietly never match. Gate on instance state instead, such as a field an action wrote, or say who may run the action with roles.

$params carries the arguments of the action being fired. It is bound only while that action’s effect bindings and its operations’ where expressions are being evaluated. It is not part of the caller-bound projection, and a cascade-fired action never binds it at all, because no caller supplied the arguments.

Every one of these checks is advisory: it tells a surface which controls to disable and why. See Actors, tokens, and what’s actually enforced for what an actor is and for which restriction stops a client that never calls the engine.

When several decisions use the same instance rule, declare it once in predicates and reference it as $name. A named predicate can read instance variables, but not caller-bound variables or another named predicate. attributes is reserved for the synthetic $attributes bag, so rename a predicate with that name before you upgrade.

defineWorkflow({
  // ...
  predicates: {
    readyToPublish: '$fields.approved == true && $allActivitiesDone',
  },
  stages: [
    defineStage({
      name: 'review',
      transitions: [
        defineTransition({
          name: 'publish',
          to: 'published',
          when: '$readyToPublish',
        }),
      ],
    }),
  ],
})

Starting has two decisions. start.filter controls discovery. start.requirements is an ordered list of checks that run before a fresh standalone start. See the start block reference for the complete nested interfaces.

A subject field identifies the document the workflow is about. See Field types for its declaration contract.

defineWorkflow({
  name: 'article-review',
  title: 'Article review',
  initialStage: 'review',
  fields: [
    defineField({
      type: 'subject',
      name: 'subject',
      types: ['article'],
      initialValue: {type: 'input'},
      required: true,
    }),
    defineField({
      type: 'boolean',
      name: 'approved',
      initialValue: {type: 'input'},
    }),
  ],
  start: {
    filter: "status == 'draft'",
    requirements: [
      {
        type: 'singleSubject',
        name: 'one-open-review',
        title: 'Review already in progress',
      },
      {
        type: 'groq',
        name: 'approved',
        title: 'Approval required',
        query: '$fields.approved == true',
      },
    ],
  },
  stages: [defineStage({name: 'review'})],
})

The subject field makes this workflow available for articles, and the filter narrows discovery to drafts. A fresh startInstance call succeeds only when no unfinished run of this definition holds the same subject and the supplied approved input is true. Start requirements are not evaluated when you resume an unfinished start, or when a parent spawns a child.

The root document is the candidate supplied to start.filter. Reads through references(), sanity::versionOf(), and sanity::partOfRelease() count as root reads when evaluated in that scope; ^ also counts when it reaches that root from a nested scope. A start.filter that reads the root requires a subject field. GROQ start requirements cannot read a root document; use their supplied variables instead. Their $fields values are raw inputs, so a document reference has {id, type}, not a hydrated document.

Workflows identifies each subject with a global document reference, which combines the document ID with its dataset, project, or other Sanity resource. Because the identity is complete, unrelated documents that happen to share an ID never block each other.

Use a singleSubject requirement when this definition may have only one unfinished run for the same subject. The rule applies across deployed versions of that definition. A different definition does not block it.

start: {
  requirements: [
    {
      type: 'singleSubject',
      name: 'one-open-review',
      description: 'Finish the existing review before starting another.',
    },
  ],
}

The workflow must declare one first-class subject field with initialValue: {type: 'input'}. Completing the existing run permits another start.

The * operator searches this snapshot. It does not open a Content Lake query. Use the condition variables whenever they give you the state you need, and reach for the raw instance only for state they do not expose, such as stage-visit history:

defineTransition({
  name: 'finish-after-rework',
  to: 'done',

  // $stage == "review" is true on every visit.
  // Read the raw stage entries to detect a return visit.
  when:
    'count(*[_id == $self][0].stages[name == "review"]) > 1',
})

The engine provides $stage, the current stage name. It does not provide a $stages history variable. The current-stage check is true on both the first and later review visits, while the $self query counts the stored stage entries, so it can tell a return visit apart.

Building a custom interface or diagnostic? See Evaluation insights to explain the outcome of these conditions without changing how you compose them.

Not every condition site receives the same variables. This reference lists the context available at each site.

These variables describe the running instance and are available at instance condition sites.

These variables appear only at the sites that supply their context.

$attributes uses the workflow spelling for values that Content Lake role filters read through user::attributes(). The engine fetches it only for caller-bound soft gates, never stores it, and treats it as advisory. When it is expected to be absent, it stays unbound and any condition that depends on it fails closed. When the fetch fails unexpectedly, that evaluation stops. Today the fetch reads one page of up to 100 active values.

These conditions make decisions about a running instance.

These expressions shape work after an action fires.

Start visibility and start permission use different inputs.

Guard predicates use Content Lake delta GROQ with their own variables and enforcement model.