Workflow

A workflow is a versioned definition. Dart and JSON both produce a WorkflowDefinition that WorkflowRuntime executes. JSON is not a second engine.

Define in Dart

final orderWorkflow = Workflow.define<OrderInput, OrderResult>(
  code: 'order-approval',
  version: 1,
  fingerprint: deploymentFingerprint,
  input: orderInputCodec,
  output: orderResultCodec,
  execute: (workflow, input) async {
    final order = await workflow.serviceTask(
      loadOrder,
      input.orderId,
      id: 'load-order',
      retry: RetryPolicy.simple,
    );
    final decision = await workflow.userTask(
      approvalTask,
      id: 'approve-order',
      title: 'Approve order',
      assignment: Assignment(roleIds: ['order-approver']),
      input: {'order': order.toJson()},
    );
    if (!decision.approved) return OrderResult.rejected();
    return OrderResult.approved(order.id);
  },
);

code + version is immutable. fingerprint prevents two deployments from silently using different code for the same identity.

Dart conditions, loops, functions, and typed values are allowed. Direct I/O, clocks, randomness, and Future.wait are not. Use workflow.parallel so every branch has a stable replay identity.

Define in JSON

The JSON format is small. References use name:vN. Bindings are data, not executable expressions.

{
  "code": "order-approval",
  "version": 1,
  "fingerprint": "order-approval-v1-build-42",
  "start": "load-order",
  "steps": [
    {
      "id": "load-order",
      "type": "serviceTask",
      "service": "orders.load:v1",
      "inputBinding": "$.input.orderId",
      "next": "approve"
    },
    {
      "id": "approve",
      "type": "userTask",
      "task": "orders.approve:v1",
      "title": "Approve order",
      "assignment": {"roleIds": ["order-approver"]},
      "outcomes": {"approved": "approved", "rejected": "rejected"}
    },
    {
      "id": "approved",
      "type": "end",
      "outputBinding": {"status": "approved"}
    },
    {
      "id": "rejected",
      "type": "end",
      "outputBinding": {"status": "rejected"}
    }
  ]
}

final definition = Workflow.fromJson(jsonMap);

Compilation is one-way. The compiler rejects unknown fields, duplicate IDs, dangling transitions, and invalid retries before registration.

Construction API

API	Creates
Workflow.ref	Typed reference to another workflow
Workflow.activity	Versioned automated-work contract
Workflow.userTask	Versioned assigned-work contract
Workflow.signal	Versioned external-message contract
Workflow.define	Typed Dart workflow
Workflow.defineJson	Dart workflow whose values are JSON-native
Workflow.fromJson	Compile a JSON document

Attach an optional structure: WorkflowDocument.fromJson(...) when the inspector needs a complete pre-run map. Dart remains the executable source.

See Also

• Bindings
• Durable Vocabulary
• Workflow and Context API