Workflow Statuses Resource

The following requests are supported for operations with workflow statuses via actiTIME API:

GET/workflowStatuses/{id}
GET/workflowStatuses
PATCH/workflowStatuses/{id}
POST/workflowStatuses
DELETE/workflowStatuses/{id}

Workflow Status Properties

Workflow status properties available via API:

Property Description
id Unique workflow status identifier.
name Workflow status name.
type Workflow status type (group). Possible values: open, completed.

Alongside with the properties listed above, the ‘allowedActions’ property is also returned. The ‘allowedActions’ property shows whether user can modify or can delete the returned workflow status. See the PATCH/workflowStatuses/{id} and DELETE/workflowStatuses/{id} methods to read about the required permissions for these actions.

Retrieve Workflow Status Properties

Use the following request to retrieve all properties of the workflow status with given ID:

GET/workflowStatuses/{id}

Example Request:

curl -X GET "<actiTIME URL>/api/v1/workflowStatuses/1" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "id": 1,
  "name": "New",
  "type": "open",
  "allowedActions": {
    "canModify": true,
    "canDelete": false
  }
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Retrieve List of Workflow Statuses

Use the following request to retrieve a list of workflow statuses with all their properties:

GET/workflowStatuses

The request can be specified with several parameters:

Parameter Description
offset Pagination offset.
If provided, first n workflow statuses will be not shown in the list.
limit Pagination limit.
If provided, number of returned workflow statuses will be limited to n.
If not provided, default value (1000) is used.
ids If provided, only workflow statuses with specific IDs will be returned.
name If provided, only the workflow status with exact name match will be returned.
words If provided, only workflow statuses containing all given words in their names will be returned.
type If provided, workflow statuses from open or completed group only will be returned.
If not provided, all workflow statuses will be returned.
sort Sets sorting of the results.
Workflow statuses can be sorted by name or type.

Example Request:

curl -X GET "<actiTIME URL>/api/v1/workflowStatuses?offset=0&limit=3&sort=%2Bname" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "offset": 0,
  "limit": 3,
  "items": [
    {
      "id": 7,
      "name": "Done Well",
      "type": "completed"
    },
    {
      "id": 4,
      "name": "In Progress",
      "type": "open"
    },
    {
      "id": 2,
      "name": "Just Done",
      "type": "completed"
    }
  ]
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Update Workflow Status Properties

Use the following request to update properties of the workflow status with given ID:

PATCH/workflowStatuses/{id}

Only the ‘name’ property can be updated.

Required Permissions

To be able to modify a workflow status, the user must have the ‘Manage System Settings’ permission.

Example Request:

curl -X PATCH "<actiTIME URL>/api/v1/workflowStatuses/5" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"name\": \"Reviewed\"}"

Example Response:

{
  "id": 5,
  "name": "Reviewed",
  "type": "open",
  "allowedActions": {
    "canModify": true,
    "canDelete": false
  }
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Create Workflow Status

Use the following request to create a new workflow status:

POST/workflowStatuses

While creating a workflow status, the following properties must be specified: ‘name’, ‘type’.

Required Permissions

To be able to create new workflow statuses in the system, the user should have the ‘Manage System Settings’ permission.

Example Request:

curl -X POST "<actiTIME URL>/api/v1/workflowStatuses" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"name\": \"new status\",\"type\": \"completed\"}"

Example Response:

{
  "id": 9,
  "name": "new status",
  "type": "completed",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  }
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Delete Workflow Status

Use the following request to delete workflow status with given ID:

DELETE/workflowStatuses/{id}

Required Permissions

To be able to delete a workflow status:

  • the user should have the ‘Manage System Settings’ permission;
  • the workflow status should be not in use (no tasks in the system should have the selected workflow status).

Example Request:

curl -X DELETE "<actiTIME URL>/api/v1/workflowStatuses/7" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response

The 204 status code is returned if operation is successful. Response body is empty.

If the operation has failed, an error code is returned.

For example, the 403 error code is returned when the workflow status is currently in use:

{
  "key": "api.error.workflow_status_used",
  "message": "Cannot delete workflow status as it is currently in use"
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger