# Workflows

The Workflow REST API allows you to create, modify, and execute Workflows and Workflow actions via standard REST API calls.

## Endpoint Summary

| Method | Endpoint                                            | Description                                |
| ------ | --------------------------------------------------- | ------------------------------------------ |
| GET    | `/schemes`                                          | Find workflow schemes                      |
| GET    | `/schemes/{schemeId}/steps`                         | Find steps by workflow scheme              |
| GET    | `/schemes/{schemeId}/actions`                       | Find actions by workflow scheme            |
| GET    | `/schemes/{schemeId}/system/actions`                | Find system actions by workflow scheme     |
| GET    | `/schemes/schemescontenttypes/{contentTypeId}`      | Find schemes by content type               |
| GET    | `/schemes/{schemeIdOrVariable}/export`              | Export a workflow scheme                   |
| POST   | `/schemes/import`                                   | Import a workflow scheme                   |
| POST   | `/schemes`                                          | Create a workflow scheme                   |
| POST   | `/schemes/{schemeId}/copy`                          | Copy a workflow scheme                     |
| PUT    | `/schemes/{schemeId}`                               | Update a workflow scheme                   |
| DELETE | `/schemes/{schemeId}`                               | Delete a workflow scheme                   |
| GET    | `/steps/{stepId}`                                   | Find a workflow step by ID                 |
| GET    | `/steps/{stepId}/actions`                           | Find actions by workflow step              |
| GET    | `/steps/{stepId}/actions/{actionId}`                | Find action by step and action ID          |
| POST   | `/steps`                                            | Create a workflow step                     |
| POST   | `/steps/{stepId}/actions`                           | Add action to a workflow step              |
| PUT    | `/steps/{stepId}`                                   | Update a workflow step                     |
| DELETE | `/steps/{stepId}`                                   | Delete a workflow step                     |
| DELETE | `/steps/{stepId}/actions/{actionId}`                | Remove action from step                    |
| PUT    | `/reorder/step/{stepId}/order/{order}`              | Reorder steps in scheme                    |
| PUT    | `/reorder/steps/{stepId}/actions/{actionId}`        | Reorder actions in step                    |
| GET    | `/actions/{actionId}`                               | Find action by ID                          |
| GET    | `/actions/{actionId}/condition`                     | Evaluate action condition                  |
| GET    | `/actions/{actionId}/actionlets`                    | Find actionlets by action                  |
| POST   | `/actions`                                          | Create a workflow action                   |
| POST   | `/actions/separator`                                | Add separator action                       |
| PUT    | `/actions/{actionId}`                               | Update a workflow action                   |
| DELETE | `/actions/{actionId}`                               | Delete a workflow action                   |
| POST   | `/actions/{actionId}/actionlets`                    | Add actionlet to action                    |
| DELETE | `/actionlets/{actionletId}`                         | Remove actionlet from action               |
| GET    | `/actionlets`                                       | Find all actionlets                        |
| GET    | `/contentlet/{inode}/actions`                       | Find available actions for contentlet      |
| PUT    | `/actions/{actionId}/fire`                          | Fire workflow action by ID                 |
| PUT    | `/actions/fire`                                     | Fire workflow action by name               |
| PUT    | `/actions/default/fire/{systemAction}`              | Fire default system action                 |
| POST   | `/actions/default/fire/{systemAction}`              | Fire system action on multiple contentlets |
| PATCH  | `/actions/default/fire/{systemAction}`              | Merge and fire system action               |
| POST   | `/contentlet/actions/bulk`                          | Get bulk actions for contentlets           |
| PUT    | `/contentlet/actions/bulk/fire`                     | Fire bulk actions                          |
| POST   | `/contentlet/actions/_bulkfire`                     | Fire bulk actions (streaming)              |
| POST   | `/actions/default/fire/{systemAction}`              | Fire actions by schemes and system action  |
| GET    | `/contenttypes/{contentTypeVarOrId}/system/actions` | Find system actions by content type        |
| GET    | `/system/actions/{workflowActionId}`                | Find system actions by action ID           |
| PUT    | `/system/actions`                                   | Save system action mapping                 |
| DELETE | `/system/actions/{identifier}`                      | Delete system action mapping               |
| GET    | `/defaultactions/contenttype/{contentTypeId}`       | Find default actions by content type       |
| GET    | `/defaultactions/schemes`                           | Find default actions by schemes            |
| GET    | `/initialactions/contenttype/{contentTypeId}`       | Find initial actions by content type       |
| GET    | `/status/{contentletInode}`                         | Get workflow status for contentlet         |
| POST   | `/tasks`                                            | Get workflow tasks with filters            |
| GET    | `/tasks/history/comments/{contentletIdentifier}`    | Get workflow history and comments          |
| POST   | `/{contentletId}/comments`                          | Create a workflow comment                  |

***

## Endpoint Details

### Workflow Schemes

#### GET `/schemes`

`GET /api/v1/workflow/schemes`

Find workflow schemes, optionally filtered by content type and archive status.

**Query Parameters:**

* `contentTypeId` (optional): Filter by content type identifier
* `showArchived` (optional, default: `true`): Include archived schemes

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/schemes?showArchived=false" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example Response:**

```json
{
  "entity": [
    {
      "id": "d61a59e1-a49c-46f2-a929-db2b4bfa88b2",
      "name": "System Workflow",
      "description": "Default system workflow",
      "archived": false,
      "mandatory": false,
      "defaultScheme": true,
      "modDate": 1234567890
    }
  ]
}
```

***

#### POST `/schemes`

`POST /api/v1/workflow/schemes`

Create a new workflow scheme.

**Request Body:**

```json
{
  "schemeName": "My Workflow",
  "schemeDescription": "Custom workflow for content approval",
  "schemeArchived": false
}
```

**Example Request:**

```bash
curl -X POST "http://localhost:8080/api/v1/workflow/schemes" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemeName": "My Workflow",
    "schemeDescription": "Custom workflow for content approval",
    "schemeArchived": false
  }'
```

***

#### PUT `/schemes/{schemeId}`

`PUT /api/v1/workflow/schemes/{schemeId}`

Update an existing workflow scheme.

**Path Parameters:**

* `schemeId`: Identifier of the workflow scheme

**Request Body:**

```json
{
  "schemeName": "Updated Workflow Name",
  "schemeDescription": "Updated description",
  "schemeArchived": false
}
```

***

#### DELETE `/schemes/{schemeId}`

`DELETE /api/v1/workflow/schemes/{schemeId}`

Delete a workflow scheme. The scheme must be archived first.

> **Note:** The response is asynchronous. The endpoint returns immediately, but scheme deletion happens in the background. Verify completion by checking that the scheme no longer appears in `GET /schemes`.

**Path Parameters:**

* `schemeId`: Identifier of the workflow scheme

**Example Request:**

```bash
curl -X DELETE "http://localhost:8080/api/v1/workflow/schemes/d61a59e1-a49c-46f2-a929-db2b4bfa88b2" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

***

### Workflow Steps

#### GET `/schemes/{schemeId}/steps`

`GET /api/v1/workflow/schemes/{schemeId}/steps`

Find all steps in a workflow scheme.

**Path Parameters:**

* `schemeId`: Identifier of the workflow scheme

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/schemes/d61a59e1-a49c-46f2-a929-db2b4bfa88b2/steps" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example Response:**

```json
{
  "entity": [
    {
      "id": "ee24a4cb-2d15-4c98-b1bd-6327126451f3",
      "name": "Draft",
      "schemeId": "d61a59e1-a49c-46f2-a929-db2b4bfa88b2",
      "myOrder": 0,
      "resolved": false,
      "enableEscalation": false
    }
  ]
}
```

***

#### GET `/steps/{stepId}/actions`

`GET /api/v1/workflow/steps/{stepId}/actions`

Find all actions associated with a workflow step.

**Path Parameters:**

* `stepId`: Identifier of the workflow step

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/steps/ee24a4cb-2d15-4c98-b1bd-6327126451f3/actions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

***

#### GET `/steps/{stepId}/actions/{actionId}`

`GET /api/v1/workflow/steps/{stepId}/actions/{actionId}`

Find a specific workflow action by step and action ID.

**Path Parameters:**

* `stepId`: Identifier of the workflow step
* `actionId`: Identifier of the workflow action

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/steps/ee24a4cb-2d15-4c98-b1bd-6327126451f3/actions/b9d89c80-3d88-4311-8365-187323c96436" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

***

#### POST `/steps`

`POST /api/v1/workflow/steps`

Create a new workflow step.

**Request Body:**

```json
{
  "schemeId": "d61a59e1-a49c-46f2-a929-db2b4bfa88b2",
  "stepName": "Review",
  "stepResolved": false,
  "enableEscalation": false,
  "escalationTime": "0",
  "escalationAction": null
}
```

***

#### PUT `/steps/{stepId}`

`PUT /api/v1/workflow/steps/{stepId}`

Update an existing workflow step.

**Path Parameters:**

* `stepId`: Identifier of the workflow step

**Request Body:**

```json
{
  "stepName": "Final Review",
  "stepOrder": 1,
  "stepResolved": false,
  "enableEscalation": true,
  "escalationTime": "86400",
  "escalationAction": "action-id-here"
}
```

***

### Workflow Actions

#### GET `/actions/{actionId}`

`GET /api/v1/workflow/actions/{actionId}`

Find a workflow action by ID.

**Path Parameters:**

* `actionId`: Identifier of the workflow action

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/actions/b9d89c80-3d88-4311-8365-187323c96436" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

***

#### GET `/contentlet/{inode}/actions`

`GET /api/v1/workflow/contentlet/{inode}/actions`

Find available workflow actions for a specific contentlet.

**Path Parameters:**

* `inode`: Inode of the contentlet

**Query Parameters:**

* `renderMode` (optional): `EDITING` or `LISTING` (default: `EDITING`)

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/contentlet/abc123def456/actions?renderMode=EDITING" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example Response:**

```json
{
  "entity": [
    {
      "id": "b9d89c80-3d88-4311-8365-187323c96436",
      "name": "Publish",
      "schemeId": "d61a59e1-a49c-46f2-a929-db2b4bfa88b2",
      "icon": "publishIcon",
      "assignable": false,
      "commentable": true,
      "showOn": ["LOCKED", "UNLOCKED"]
    }
  ]
}
```

***

#### POST `/actions`

`POST /api/v1/workflow/actions`

Create a new workflow action.

**Request Body:**

```json
{
  "schemeId": "d61a59e1-a49c-46f2-a929-db2b4bfa88b2",
  "stepId": "ee24a4cb-2d15-4c98-b1bd-6327126451f3",
  "actionName": "Submit for Review",
  "whoCanUse": ["reviewer-role-id"],
  "actionIcon": "submitIcon",
  "actionCommentable": true,
  "showOn": ["UNLOCKED", "NEW"],
  "actionNextStep": "next-step-id",
  "actionNextAssign": "role-id",
  "actionAssignable": true,
  "actionRoleHierarchyForAssign": false,
  "actionCondition": ""
}
```

**`showOn` valid values:** `NEW`, `LOCKED`, `UNLOCKED`, `PUBLISHED`, `UNPUBLISHED`, `ARCHIVED`

**`actionCondition`:** An optional Velocity expression evaluated at runtime. The action is only shown if the expression evaluates to `true`. Leave empty to always show the action.

***

#### PUT `/actions/{actionId}`

`PUT /api/v1/workflow/actions/{actionId}`

Update an existing workflow action.

**Path Parameters:**

* `actionId`: Identifier of the workflow action

**Request Body:**

```json
{
  "schemeId": "d61a59e1-a49c-46f2-a929-db2b4bfa88b2",
  "stepId": "ee24a4cb-2d15-4c98-b1bd-6327126451f3",
  "actionName": "Submit for Review",
  "whoCanUse": ["reviewer-role-id"],
  "actionIcon": "submitIcon",
  "actionCommentable": true,
  "showOn": ["UNLOCKED", "NEW"],
  "actionNextStep": "next-step-id",
  "actionNextAssign": "role-id",
  "actionAssignable": true,
  "actionRoleHierarchyForAssign": false,
  "actionCondition": ""
}
```

**`showOn` valid values:** `NEW`, `LOCKED`, `UNLOCKED`, `PUBLISHED`, `UNPUBLISHED`, `ARCHIVED`

***

#### POST `/steps/{stepId}/actions`

`POST /api/v1/workflow/steps/{stepId}/actions`

Add an existing action to a workflow step.

**Path Parameters:**

* `stepId`: Identifier of the workflow step

**Request Body:**

```json
{
  "actionId": "b9d89c80-3d88-4311-8365-187323c96436"
}
```

***

### Firing Workflow Actions

#### PUT `/actions/{actionId}/fire`

`PUT /api/v1/workflow/actions/{actionId}/fire`

Fire a workflow action on a contentlet by action ID.

**Path Parameters:**

* `actionId`: Identifier of the workflow action

**Query Parameters:**

* `inode` (optional): Inode of the contentlet
* `identifier` (optional): Identifier of the contentlet
* `language` (optional, default: `-1`): Language ID
* `indexPolicy` (optional): `DEFER`, `WAIT_FOR`, or `FORCE`

**Request Body:**

```json
{
  "comments": "Approving this content",
  "assign": "user-id-or-role",
  "contentlet": {
    "stInode": "content-type-inode",
    "name": "My Content",
    "title": "Updated Title"
  }
}
```

> **Note:** `stInode` is the content type inode — required when creating new content. `name` is used to identify the content in workflow history.

**Example Request:**

```bash
curl -X PUT "http://localhost:8080/api/v1/workflow/actions/b9d89c80-3d88-4311-8365-187323c96436/fire?identifier=abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comments": "Publishing this content",
    "assign": "reviewer-role"
  }'
```

***

#### PUT `/actions/fire`

`PUT /api/v1/workflow/actions/fire`

Fire a workflow action by name.

**Query Parameters:**

* `inode` (optional): Inode of the contentlet
* `identifier` (optional): Identifier of the contentlet
* `language` (optional, default: `-1`): Language ID
* `indexPolicy` (optional): Index policy

**Request Body:**

```json
{
  "actionName": "Publish",
  "comments": "Ready for publication",
  "contentlet": {
    "stInode": "content-type-inode",
    "name": "My Content",
    "identifier": "abc123",
    "title": "My Content"
  }
}
```

> **Note:** `stInode` is the content type inode — required when creating new content via this endpoint. `name` appears in workflow history to identify the item.

***

#### PUT `/actions/default/fire/{systemAction}`

`PUT /api/v1/workflow/actions/default/fire/{systemAction}`

Fire a default system action on a contentlet.

**Path Parameters:**

* `systemAction`: One of `NEW`, `EDIT`, `PUBLISH`, `UNPUBLISH`, `ARCHIVE`, `UNARCHIVE`, `DELETE`, `DESTROY`

**Query Parameters:**

* `inode` (optional): Inode of the contentlet
* `identifier` (optional): Identifier of the contentlet
* `language` (optional, default: `-1`): Language ID
* `indexPolicy` (optional): Index policy

**Request Body:**

```json
{
  "comments": "Publishing via system action",
  "contentlet": {
    "identifier": "abc123"
  }
}
```

**Example Request:**

```bash
curl -X PUT "http://localhost:8080/api/v1/workflow/actions/default/fire/PUBLISH?identifier=abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comments": "Auto-publishing"
  }'
```

***

### Bulk Operations

#### POST `/contentlet/actions/bulk`

`POST /api/v1/workflow/contentlet/actions/bulk`

Get available bulk actions for multiple contentlets.

**Request Body:**

```json
{
  "contentletIds": [
    "651a4dc8-2124-45d8-8bd2-d8e68ad358a8",
    "f8d60f79-e006-42e0-894f-5d3488b796f6"
  ]
}
```

or

```json
{
  "query": "+contentType:Blog"
}
```

***

#### PUT `/contentlet/actions/bulk/fire`

`PUT /api/v1/workflow/contentlet/actions/bulk/fire`

Fire a workflow action on multiple contentlets.

**Request Body:**

```json
{
  "query": "+contentType:Blog +working:true",
  "workflowActionId": "b9d89c80-3d88-4311-8365-187323c96436",
  "additionalParams": {
    "comments": "Bulk publishing blogs",
    "assign": "editor-role"
  }
}
```

**Example Request:**

```bash
curl -X PUT "http://localhost:8080/api/v1/workflow/contentlet/actions/bulk/fire" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contentletIds": ["id1", "id2", "id3"],
    "workflowActionId": "b9d89c80-3d88-4311-8365-187323c96436",
    "additionalParams": {
      "comments": "Bulk approval"
    }
  }'
```

***

### System Actions

#### GET `/system/actions/{workflowActionId}`

`GET /api/v1/workflow/system/actions/{workflowActionId}`

Find system actions associated with a workflow action.

**Path Parameters:**

* `workflowActionId`: Identifier of the workflow action

***

#### PUT `/system/actions`

`PUT /api/v1/workflow/system/actions`

Save a system action mapping.

**Request Body:**

```json
{
  "systemAction": "PUBLISH",
  "actionId": "b9d89c80-3d88-4311-8365-187323c96436",
  "schemeId": "d61a59e1-a49c-46f2-a929-db2b4bfa88b2"
}
```

or for content type mapping:

```json
{
  "systemAction": "NEW",
  "actionId": "action-id-here",
  "contentTypeVariable": "Blog"
}
```

***

#### DELETE `/system/actions/{identifier}`

`DELETE /api/v1/workflow/system/actions/{identifier}`

Delete a system action mapping.

**Path Parameters:**

* `identifier`: Identifier of the system action mapping

***

### Workflow Status and Tasks

#### GET `/status/{contentletInode}`

`GET /api/v1/workflow/status/{contentletInode}`

Get the current workflow status of a contentlet.

**Path Parameters:**

* `contentletInode`: Inode of the contentlet

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/status/abc123def456" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example Response:**

```json
{
  "entity": {
    "scheme": {
      "id": "d61a59e1-a49c-46f2-a929-db2b4bfa88b2",
      "name": "System Workflow"
    },
    "step": {
      "id": "ee24a4cb-2d15-4c98-b1bd-6327126451f3",
      "name": "Draft"
    },
    "task": {
      "id": "task-id",
      "assignedTo": "user-id",
      "createdBy": "creator-id",
      "status": "open"
    }
  }
}
```

***

#### POST `/tasks`

`POST /api/v1/workflow/tasks`

Search for workflow tasks with filters.

**Request Body:**

```json
{
  "assignedTo": "user-id",
  "keywords": "review",
  "showCompleted": false,
  "page": 0,
  "perPage": 20,
  "orderBy": "modDate desc"
}
```

***

#### GET `/tasks/history/comments/{contentletIdentifier}`

`GET /api/v1/workflow/tasks/history/comments/{contentletIdentifier}`

Get workflow history and comments for a contentlet.

**Path Parameters:**

* `contentletIdentifier`: Identifier of the contentlet

**Query Parameters:**

* `language` (optional, default: `-1`): Language ID

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/tasks/history/comments/abc123?language=1" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

***

#### POST `/{contentletId}/comments`

`POST /api/v1/workflow/{contentletId}/comments`

Add a comment to a contentlet's workflow task.

**Path Parameters:**

* `contentletId`: Identifier of the contentlet

**Query Parameters:**

* `language` (optional, default: `-1`): Language ID

**Request Body:**

```json
{
  "comment": "This looks good, approved for publication"
}
```

***

### Import/Export

#### GET `/schemes/{schemeIdOrVariable}/export`

`GET /api/v1/workflow/schemes/{schemeIdOrVariable}/export`

Export a workflow scheme with all dependencies.

**Path Parameters:**

* `schemeIdOrVariable`: ID or variable name of the scheme

**Example Request:**

```bash
curl -X GET "http://localhost:8080/api/v1/workflow/schemes/d61a59e1-a49c-46f2-a929-db2b4bfa88b2/export" \
  -H "Authorization: Bearer YOUR_TOKEN" > workflow-export.json
```

***

#### POST `/schemes/import`

`POST /api/v1/workflow/schemes/import`

Import a workflow scheme.

**Request Body:**
The full entity object from an export, containing `workflowObject` and `permissions` properties.

**Example Request:**

```bash
curl -X POST "http://localhost:8080/api/v1/workflow/schemes/import" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @workflow-export.json
```

***

## Common Patterns

### Working with Multipart Forms

Some endpoints support multipart form data for uploading binary files with content:

```bash
curl -X PUT "http://localhost:8080/api/v1/workflow/actions/fire?identifier=abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "actionName=Publish" \
  -F "comments=Publishing with image" \
  -F "contentlet={\"title\":\"My Page\"};type=application/json" \
  -F "binary1=@/path/to/image.jpg"
```

### Index Policies

Control how content is indexed after workflow operations:

* **DEFER** (default): Async indexing, operation completes before content appears in search
* **WAIT\_FOR**: Operation waits for content to be indexed
* **FORCE**: Immediate indexing (not recommended for production)

### Push Publishing Parameters

When using push publishing actionlets, include these parameters:

```json
{
  "whereToSend": "environment-id",
  "iWantTo": "publish",
  "publishDate": "2024-12-31",
  "publishTime": "23:59",
  "timezoneId": "America/New_York",
  "filterKey": "filter-key-here"
}
```

***

## Error Handling

All endpoints return errors in a consistent format:

```json
{
  "errors": [
    {
      "errorCode": "ERROR_CODE",
      "message": "Human readable error message",
      "fieldName": "fieldName"
    }
  ]
}
```

Common error scenarios:

* **401**: User not authenticated
* **403**: User lacks permissions for the operation
* **404**: Workflow scheme, step, action, or contentlet not found
* **400**: Invalid request parameters or body
