Definitions and instances

A definition describes a process. An instance is one run of that process.

A workflow definition is the authored, deployable description of a process. It combines fields, stages and transitions, activities and actions, conditions, effects, and guards into one versioned contract.

An instance is the durable state of one run. One definition can produce many instances, each with its own field values, current stage, history, pending effects, and child workflows.

Use defineWorkflow to author a definition:

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

The definition is the complete authored contract. Deployment validates cross-field invariants, expands authoring conveniences, and produces the stored form used by the engine.

Deploying validates the definition, expands authoring conveniences into stored primitives, and stores a content-addressed version. Deploying identical content is a no-op; changing the definition creates the next version.

An instance pins the definition version and a frozen definition snapshot when it starts. Redeploying therefore changes future runs without silently changing work already in flight.

The optional start block controls discovery and requirements. See the Start block reference for its complete shape.

Starting an instance creates one durable run from a deployed definition. Pass the definition name and any declared workflow inputs to engine.startInstance:

import {gdrFromResource} from '@sanity/workflow-engine'

const subject = gdrFromResource(
  {type: 'dataset', id: 'yourprojectid.production'},
  'article-123',
)

const {instance} = await engine.startInstance({
  definition: 'article-review',
  initialFields: [
    {
      type: 'subject',
      name: 'subject',
      value: {id: subject, type: 'article'},
    },
  ],
})

This supplies the subject input declared in the definition above. See Fields for input and subject declarations, and Conditions for controlling when a workflow may start.

The engine rejects an initial field when:

• Its name is not declared at workflow scope.
• Its declaration is not input-sourced.
• Its type does not match the declaration.
• The same field appears more than once.

evaluateStart returns allowed: false with the invalid fields. No instance is written.

An instance is an engine-owned sanity.workflow.instance document. It records the pinned definition, current stage, resolved fields, stage-visit history, effects, child workflows, audit history, and lifecycle timestamps for one run.

To update an instance, use the engine rather than ordinary content patches.

This is the top-level object passed to defineWorkflow(...). The engine compiles and deploys it as the versioned definition that instances reference.

The top-level properties accepted by defineWorkflow(...).

Named predicates use the GROQ variables defined by the Conditions reference. This table shows which are available at this site.

The optional start block configures discovery and fresh standalone starts. See Start filters and requirements for behavior and evaluation context.

start: {
  kind: 'interactive',
  filter: "status == 'draft'",
  requirements: [
    {
      type: 'singleSubject',
      name: 'one-open-review',
      title: 'Review already in progress',
    },
    {
      type: 'groq',
      name: 'article-ready',
      title: 'Article is not ready',
      query: '$fields.ready == true',
    },
  ],
}

Use a GROQ requirement when readiness depends on supplied workflow inputs.

Use a single-subject requirement to permit at most one unfinished run of this definition for the same subject. It requires one first-class input-sourced subject field; see Allow one active workflow per subject.

A workflow instance is the engine-owned sanity.workflow.instance document returned by startInstance and subsequent engine verbs. Read it through the engine and change it only through engine verbs.

These fields identify the run and preserve the definition it started with.

These fields hold the instance’s resolved state and its place in a workflow hierarchy.

These fields track queued work and committed engine activity.

These fields record lifecycle timestamps and the persisted data-model contract.