Workflows

Define how products move through your process

Standalone workflow entities with lifecycle states and transitions. Gate transitions on completeness scores and role permissions. Attach a workflow to any schema to control how products progress from draft to published.

Draft → Review → Published

Lifecycle States

Each state defines which attributes are hidden, required, or readOnly. States have a color for visual identification in the UI.

Transitions

Transitions define valid movements between states. Each transition can gate on allowedRoleIds and requiresCompleteness (0–100).

Schema Binding

Attach a workflow to a schema via schema.workflowId. All records of that schema will follow the workflow's state machine.

Delete Protection

Workflows referenced by schemas cannot be deleted. Remove the schema binding first, then delete the workflow.

Endpoints

Method	Path	Description
GET	`/workflows`	List all workflows
POST	`/workflows`	Create a workflow
GET	`/workflows/:id`	Get workflow by ID
PUT	`/workflows/:id`	Update a workflow
DELETE	`/workflows/:id`	Delete a workflow

GET /workflows

Returns all workflows with their states and transitions.

curl https://api.sigma-pim.com/api/v1/workflows \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
[
  {
    "id": "wf-product-lifecycle",
    "alias": "product-lifecycle",
    "name": "Product Lifecycle",
    "description": "Standard product review and publishing flow",
    "defaultStateId": "state-draft",
    "states": [ /* ... */ ],
    "transitions": [ /* ... */ ]
  }
]

POST /workflows

Create a new workflow with lifecycle states and transitions. Each state can control attribute visibility and editability. Each transition can gate on roles and completeness.

Request Body

Field	Type	Description
`id`	`string`	Unique identifier for the workflow
`alias`	`string`	URL-friendly alias
`name`	`string`	Display name
`description`	`string?`	Optional description
`defaultStateId`	`string`	ID of the initial state for new records
`states`	`State[]`	Array of lifecycle state objects
`states[].id`	`string`	Unique state identifier
`states[].alias`	`string`	State alias
`states[].name`	`string`	State display name
`states[].color`	`string`	Hex color for UI display
`states[].hiddenAttributeIds`	`string[]`	Attributes hidden in this state
`states[].requiredAttributeIds`	`string[]`	Attributes required in this state
`states[].readOnlyAttributeIds`	`string[]`	Attributes locked in this state
`transitions`	`Transition[]`	Array of transition objects
`transitions[].id`	`string`	Unique transition identifier
`transitions[].fromStateId`	`string`	Source state ID
`transitions[].toStateId`	`string`	Target state ID
`transitions[].name`	`string`	Transition display name
`transitions[].allowedRoleIds`	`string[]`	Roles allowed to perform this transition
`transitions[].requiresCompleteness`	`number`	Minimum completeness score (0–100) to transition

curl -X POST https://api.sigma-pim.com/api/v1/workflows \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "wf-product-lifecycle",
    "alias": "product-lifecycle",
    "name": "Product Lifecycle",
    "description": "Standard product review and publishing flow",
    "defaultStateId": "state-draft",
    "states": [
      {
        "id": "state-draft",
        "alias": "draft",
        "name": "Draft",
        "color": "#9ca3af",
        "hiddenAttributeIds": [],
        "requiredAttributeIds": [],
        "readOnlyAttributeIds": []
      },
      {
        "id": "state-review",
        "alias": "review",
        "name": "Review",
        "color": "#3b82f6",
        "hiddenAttributeIds": [],
        "requiredAttributeIds": ["attr-sku", "attr-product-name"],
        "readOnlyAttributeIds": ["attr-sku"]
      },
      {
        "id": "state-published",
        "alias": "published",
        "name": "Published",
        "color": "#22c55e",
        "hiddenAttributeIds": [],
        "requiredAttributeIds": ["attr-sku", "attr-product-name", "attr-price"],
        "readOnlyAttributeIds": ["attr-sku", "attr-product-name", "attr-price"]
      }
    ],
    "transitions": [
      {
        "id": "tr-submit",
        "fromStateId": "state-draft",
        "toStateId": "state-review",
        "name": "Submit for Review",
        "allowedRoleIds": ["role-editor", "role-admin"],
        "requiresCompleteness": 0
      },
      {
        "id": "tr-approve",
        "fromStateId": "state-review",
        "toStateId": "state-published",
        "name": "Approve",
        "allowedRoleIds": ["role-admin"],
        "requiresCompleteness": 80
      },
      {
        "id": "tr-reject",
        "fromStateId": "state-review",
        "toStateId": "state-draft",
        "name": "Reject",
        "allowedRoleIds": ["role-admin"],
        "requiresCompleteness": 0
      }
    ]
  }'

// Response — 201 Created
{
  "id": "wf-product-lifecycle",
  "alias": "product-lifecycle",
  "name": "Product Lifecycle",
  "description": "Standard product review and publishing flow",
  "defaultStateId": "state-draft",
  "states": [
    {
      "id": "state-draft",
      "alias": "draft",
      "name": "Draft",
      "color": "#9ca3af",
      "hiddenAttributeIds": [],
      "requiredAttributeIds": [],
      "readOnlyAttributeIds": []
    },
    {
      "id": "state-review",
      "alias": "review",
      "name": "Review",
      "color": "#3b82f6",
      "hiddenAttributeIds": [],
      "requiredAttributeIds": ["attr-sku", "attr-product-name"],
      "readOnlyAttributeIds": ["attr-sku"]
    },
    {
      "id": "state-published",
      "alias": "published",
      "name": "Published",
      "color": "#22c55e",
      "hiddenAttributeIds": [],
      "requiredAttributeIds": ["attr-sku", "attr-product-name", "attr-price"],
      "readOnlyAttributeIds": ["attr-sku", "attr-product-name", "attr-price"]
    }
  ],
  "transitions": [
    {
      "id": "tr-submit",
      "fromStateId": "state-draft",
      "toStateId": "state-review",
      "name": "Submit for Review",
      "allowedRoleIds": ["role-editor", "role-admin"],
      "requiresCompleteness": 0
    },
    {
      "id": "tr-approve",
      "fromStateId": "state-review",
      "toStateId": "state-published",
      "name": "Approve",
      "allowedRoleIds": ["role-admin"],
      "requiresCompleteness": 80
    },
    {
      "id": "tr-reject",
      "fromStateId": "state-review",
      "toStateId": "state-draft",
      "name": "Reject",
      "allowedRoleIds": ["role-admin"],
      "requiresCompleteness": 0
    }
  ]
}

GET /workflows/:id

Retrieve a single workflow by its ID, including all states and transitions.

Path Parameters

Parameter	Type	Description
`id`	`string`	The workflow ID (e.g. `wf-product-lifecycle`)

curl https://api.sigma-pim.com/api/v1/workflows/wf-product-lifecycle \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — full workflow object (same shape as POST response above)
{
  "id": "wf-product-lifecycle",
  "alias": "product-lifecycle",
  "name": "Product Lifecycle",
  "description": "Standard product review and publishing flow",
  "defaultStateId": "state-draft",
  "states": [
    { "id": "state-draft", "alias": "draft", "name": "Draft", "color": "#9ca3af", /* ... */ },
    { "id": "state-review", "alias": "review", "name": "Review", "color": "#3b82f6", /* ... */ },
    { "id": "state-published", "alias": "published", "name": "Published", "color": "#22c55e", /* ... */ }
  ],
  "transitions": [
    { "id": "tr-submit", "name": "Submit for Review", /* ... */ },
    { "id": "tr-approve", "name": "Approve", "requiresCompleteness": 80, /* ... */ },
    { "id": "tr-reject", "name": "Reject", /* ... */ }
  ]
}

PUT /workflows/:id

Update a workflow. Provide the full workflow object with updated states and transitions. Changes take effect for all schemas bound to this workflow.

curl -X PUT https://api.sigma-pim.com/api/v1/workflows/wf-product-lifecycle \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "wf-product-lifecycle",
    "alias": "product-lifecycle",
    "name": "Product Lifecycle",
    "description": "Updated flow with archival step",
    "defaultStateId": "state-draft",
    "states": [
      { "id": "state-draft", "alias": "draft", "name": "Draft", "color": "#9ca3af", "hiddenAttributeIds": [], "requiredAttributeIds": [], "readOnlyAttributeIds": [] },
      { "id": "state-review", "alias": "review", "name": "Review", "color": "#3b82f6", "hiddenAttributeIds": [], "requiredAttributeIds": ["attr-sku"], "readOnlyAttributeIds": ["attr-sku"] },
      { "id": "state-published", "alias": "published", "name": "Published", "color": "#22c55e", "hiddenAttributeIds": [], "requiredAttributeIds": ["attr-sku", "attr-price"], "readOnlyAttributeIds": ["attr-sku", "attr-price"] },
      { "id": "state-archived", "alias": "archived", "name": "Archived", "color": "#6b7280", "hiddenAttributeIds": [], "requiredAttributeIds": [], "readOnlyAttributeIds": [] }
    ],
    "transitions": [
      { "id": "tr-submit", "fromStateId": "state-draft", "toStateId": "state-review", "name": "Submit for Review", "allowedRoleIds": ["role-editor", "role-admin"], "requiresCompleteness": 0 },
      { "id": "tr-approve", "fromStateId": "state-review", "toStateId": "state-published", "name": "Approve", "allowedRoleIds": ["role-admin"], "requiresCompleteness": 80 },
      { "id": "tr-reject", "fromStateId": "state-review", "toStateId": "state-draft", "name": "Reject", "allowedRoleIds": ["role-admin"], "requiresCompleteness": 0 },
      { "id": "tr-archive", "fromStateId": "state-published", "toStateId": "state-archived", "name": "Archive", "allowedRoleIds": ["role-admin"], "requiresCompleteness": 0 }
    ]
  }'

DELETE /workflows/:id

Delete a workflow. Returns { "deleted": true } on success. Protected: will return an error if the workflow is referenced by any schema.

curl -X DELETE https://api.sigma-pim.com/api/v1/workflows/wf-product-lifecycle \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — 200 OK
{
  "deleted": true
}

// Error — workflow is referenced by a schema
{
  "error": "WORKFLOW_IN_USE",
  "message": "Cannot delete workflow 'wf-product-lifecycle' — it is referenced by schema 'schema-apparel'"
}

Previous Option Lists Next Roles