Collections & Versions

Collections organize schemas and processes into folders. Versions capture point-in-time snapshots of processes for rollback and auditing.

Collections

What Collections Are

Collections are organizational folders. They help you group related schemas and processes together. Collections exist independently for schemas and processes:

• Schema Collections -- group related schemas (e.g., "Steel Operations", "Customer Data")
• Process Collections -- group related processes (e.g., "Order Processing", "Reporting")

Collection Properties

Nesting

Collections can be nested by setting parentCollectionId:

Steel Operations/
  ├── Order Processing/
  │    ├── Steel Order Quoter (process)
  │    └── Order Confirmation (process)
  ├── Inventory/
  │    └── Stock Check (process)
  └── Steel Order Schema (schema)

Many-to-Many Membership

A schema or process can belong to multiple collections. Membership is tracked through a join table:

schema_collection_members:
  collection_id: UUID
  schema_id: UUID

process_collection_members:
  collection_id: UUID
  process_id: UUID

Managing Process Collections

Managing Schema Collections

UI Interaction

In the UI:

• Collections appear as folders in the schemas and processes list views.
• Drag and drop schemas/processes into collections.
• Right-click to create nested collections.
• Use search and filters across all collections.

Process Versions

What Versions Are

A version is a named snapshot of a process at a specific point in time. It captures the complete graph state: all nodes, edges, and configurations.

Versions serve two purposes:

1. Rollback: Restore a process to a previous working state.
2. Audit trail: See what the process looked like when past executions ran.

Version Properties

Creating a Version

API: POST /processes/versions/:process_id

{
  "label": "v1.0 - initial release"
}

Response:

{
  "id": "version-uuid",
  "versionNumber": 1,
  "label": "v1.0 - initial release",
  "createdBy": "John Smith",
  "createdAt": "2026-04-12T10:00:00Z"
}

What the Snapshot Contains

The snapshot field stores the full process state:

{
  "nodes": [
    {
      "id": "node-uuid",
      "type": "inputNode",
      "position": { "x": 100, "y": 200 },
      "config": {
        "label": "Email Input",
        "authMethod": "service_account",
        "serviceAccountId": "sa-uuid",
        "senderFilter": "*@steelcustomer.com"
      }
    },
    {
      "id": "node-uuid-2",
      "type": "schematizationNode",
      "position": { "x": 400, "y": 200 },
      "config": {
        "label": "Extract Order",
        "schemaId": "schema-uuid",
        "model": "gpt-4o"
      }
    }
  ],
  "edges": [
    {
      "id": "edge-uuid",
      "sourceNodeId": "node-uuid",
      "targetNodeId": "node-uuid-2",
      "sourceHandle": "output",
      "targetHandle": "input"
    }
  ]
}

Listing Versions

API: GET /processes/versions/:process_id

Returns all versions ordered by version number (newest first):

[
  {
    "id": "version-uuid-3",
    "versionNumber": 3,
    "label": "v1.2 - added urgency handling",
    "createdBy": "John Smith",
    "createdAt": "2026-04-12T14:00:00Z"
  },
  {
    "id": "version-uuid-2",
    "versionNumber": 2,
    "label": "v1.1 - fixed stainless pricing",
    "createdBy": "Jane Doe",
    "createdAt": "2026-04-10T09:00:00Z"
  },
  {
    "id": "version-uuid-1",
    "versionNumber": 1,
    "label": "v1.0 - initial release",
    "createdBy": "John Smith",
    "createdAt": "2026-04-08T16:00:00Z"
  }
]

Getting Version Detail

API: GET /processes/version/:version_id

Returns the full version including the snapshot. Use this to inspect what the process looked like at that point.

Restoring a Version

API: POST /processes/version/:version_id/restore

Replaces the current process graph with the snapshot from the specified version:

1. All current nodes and edges are deleted.
2. Nodes and edges from the snapshot are created.
3. Configs are restored exactly as they were.

Deleting a Version

API: DELETE /processes/version/:version_id

Permanently removes the version record and its snapshot.

Versioning Best Practices

When to Create Versions

• Before making significant changes to a running process
• After verifying a new configuration works correctly
• Before deploying a process to production
• After fixing a bug (label it with the fix description)

Labeling Convention

Use descriptive labels that explain what changed:

v1.0 - initial release
v1.1 - fix: stainless steel price was using carbon rate
v1.2 - feat: added urgency multiplier to quote calculation
v2.0 - refactor: split into sub-processes for modularity

Version vs. Export

Execution Graph Snapshots

Separately from versions, every execution also captures a graph snapshot in the graph_snapshot field. This happens automatically and cannot be disabled.

The execution snapshot ensures that:

• You can always see exactly what config produced a given result
• Editing a process doesn't retroactively change how past executions appear
• Debugging uses the actual graph that ran, not the current (possibly modified) graph

Difference from Versions