Workflows

A workflow is a named container that holds one or more immutable versions, each containing a step definition that the execution engine runs as jobs.

Workflow Lifecycle

Workflow (container)
  └── Version 1 (step definition)
  └── Version 2 (step definition)  ← $LIVE tag
  └── Version 3 (step definition)

1. Register a workflow — creates a named container with a unique workflowId
2. Add versions — each version is immutable and gets an auto-incrementing versionNumber
3. Tag a version — assign $LIVE (or custom tags) to mark which version should be executed
4. Submit jobs — reference a workflow + version selector to start execution

Step Definitions

A workflow definition is a JSON object with steps and definitions:

{
  "workflowName": "my-workflow",
  "steps": [
    {
      "name": "fetchData",
      "integrationDetails": {
        "type": "/justworkflowit/aws/lambda",
        "config": {
          "region": "us-east-1",
          "accountId": "123456789012",
          "functionName": "fetch-data"
        },
        "inputDefinition": { "$ref": "#/definitions/workflowInput" },
        "outputDefinition": { "$ref": "#/definitions/fetchOutput" }
      },
      "transitionToStep": "processData"
    },
    {
      "name": "processData",
      "integrationDetails": {
        "type": "/justworkflowit/noop",
        "inputDefinition": { "$ref": "#/definitions/fetchOutput" },
        "outputDefinition": { "$ref": "#/definitions/fetchOutput" }
      },
      "transitionToStep": null
    }
  ],
  "definitions": {
    "workflowInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false },
    "fetchOutput": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"], "additionalProperties": false }
  }
}

Each step has:

• name — unique identifier within the workflow
• integrationDetails.type — the step executor that runs this step
• integrationDetails.config — executor-specific configuration
• integrationDetails.inputDefinition / outputDefinition — $ref pointers to JSON Schema definitions
• transitionToStep — the step to execute next (null for terminal steps, or a conditional object)

Version Tags

Tags are mutable pointers to immutable versions:

• $LIVE — the conventional tag for the production version
• Custom tags must match $[A-Z_]+ (e.g., $STAGING, $CANARY)
• Moving a tag is atomic — no downtime when promoting versions
• Resolve tags to versions via GetTaggedWorkflowVersion