Workflows API
- List workflows
- Get a single workflow
- Create a workflow
- Update a workflow
- Archive a workflow
- Trash a workflow
- Restore a workflow
- Fields
List workflows
List all workflows for an account:
GET /workflows
Response
Status: 200 OK
[
{
"completed_at": null,
"created_at": "2016-03-10T12:32:00-06:00",
"category": "standard",
"sourceID": null,
"updated_at": "2016-03-14T03:14:17-06:00",
"service": {
"id": 21,
"name": "Email",
"localized_name": "Email",
"provider": {
"name": "Widget Data Center, External IT",
"id": 44,
"account": {
"id": "widget",
"name": "Widget International"
}
}
},
"manager": {
"id": 37,
"name": "Barney Turban",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"subject": "Upgrade Email servers to Exchange Server 2007 SP2",
"id": 1686,
"impact": "top",
"status": "risk_and_impact",
"completion_target_at": "2016-03-15T16:33:00-06:00"
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of workflows.
Predefined Filters
The following predefined filters are available:
/workflows/completed
: List all completed workflows/workflows/open
: List all open workflows/workflows/managed_by_me
: List all workflows which manager is the API user
Collection Fields
By default the following fields will appear in collections of workflows:
id
sourceID
subject
manager
category
impact
status
completion_target_at
completed_at
service
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Filtering
Filtering is available for the following fields:
id
source
sourceID
subject
manager
category
impact
status
completion_target_at
completed_at
service
created_at
updated_at
template
start_at
project
release
Sorting
By default a collection of workflows is sorted descending by id
.
The following fields are accepted by the ?sort= parameter:
id
sourceID
subject
manager
category
impact
status
completion_target_at
completed_at
service
created_at
updated_at
Response
The response is similar to the response in List workflows
Get a single workflow
GET /workflows/:id
Response
Status: 200 OK
{
"completion_reason": "complete",
"completed_at": "2016-03-14T03:14:13-06:00",
"created_at": "2009-02-03T03:08:00-06:00",
"category": "standard",
"sourceID": null,
"updated_at": "2016-03-14T03:14:13-06:00",
"release": null,
"project": null,
"service": {
"name": "Rack Space",
"id": 26,
"provider": {
"name": "Widget Data Center, External IT",
"id": 44
}
},
"manager": {
"id": 77,
"name": "Carla Cluster",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"subject": "Install new rack",
"start_at": "2016-03-14T09:14:13Z",
"id": 238,
"justification": "expansion",
"impact": "none",
"status": "completed",
"source": "R-Service",
"workflow_type": "infrastructure_change",
"completion_target_at": null,
"template": {
"id": 37,
"subject": "Non-standard infrastructure change"
},
"custom_fields": null
}
The response contains these fields.
Create a workflow
POST /workflows
When creating a new workflow these fields are available.
Response
Status: 201 Created
{
"category": "...",
"...": "..."
}
The response contains all fields of the created workflow and is similar to the response in Get a single workflow
Update a workflow
PATCH /workflows/:id
When updating a workflow these fields are available.
Response
Status: 200 OK
{
"category": "...",
"...": "..."
}
The response contains all fields of the updated workflow and is similar to the response in Get a single workflow
Archive a workflow
POST /workflows/:id/archive
Moves a given workflow to the Archive. This action requires the Account Administrator or Directory Administrator role in the account of the workflow.
Response
Status: 200 OK
{
"archived": "true",
"analysis_target_at": "...",
"...": "..."
}
The response contains all fields of the archived workflow and is similar to the response in Get a single workflow
Trash a workflow
POST /workflows/:id/trash
Moves a given workflow to the Trash. This action requires the Account Administrator or Directory Administrator role in the account of the workflow.
Response
Status: 200 OK
{
"trashed": "true",
"analysis_target_at": "...",
"...": "..."
}
The response contains all fields of the archived workflow and is similar to the response in Get a single workflow
Restore a workflow
POST /workflows/:id/restore
Moves a given workflow from the Archive or the Trash back into the view of “Completed Workflows”. This action requires the Account Administrator or Directory Administrator role in the account of the workflow.
Response
Status: 200 OK
{
"analysis_target_at": "...",
"...": "..."
}
The response contains all fields of the archived workflow and is similar to the response in Get a single workflow
Fields
- actual_effort
- Readonly integer — The Actual effort field shows the total time that has already been spent on the workflow. This is the sum of the time spent on each of the workflow’s tasks and the planned effort of the related requests and problems.
- actual_vs_planned_effort_percentage
- Readonly integer — The actual effort as a percentage of the planned effort.
- attachments
- Readonly aggregated Attachments
- Use Workflows - Notes API to get note attachments.
- category
- Required enum — The Category field is used to select the category of the workflow. A workflow is either planned or unplanned. Select the category “Emergency” for workflows that were not planned. Workflows that were planned by applying a standard workflow template are automatically set to the category “Standard”. When a workflow template is used that is not approved as a standard workflow, then the option “Non-Standard” is automatically selected in this field. Valid values are:
-
standard
: Standard - Approved Workflow Template Was Usednon_standard
: Non-Standard - Approved Workflow Template Not Availableemergency
: Emergency - Required for Incident Resolutionorder
: Order - Organization Order Workflow
- completed_at
- Readonly datetime — The Completed at field is automatically set to the date and time at which the workflow is saved with the status “Completed”.
- completion_reason
- Optional enum — The Completion reason field is used to select the appropriate completion reason for the workflow when it has been completed. It is automatically set to “Complete” when all tasks related to the workflow have reached the status “Completed”, “Approved” or “Canceled”. Valid values are:
-
withdrawn
: Withdrawn - Withdrawn by Requesterrejected
: Rejected - Rejected by Approverrolled_back
: Rolled Back - Original Environment Restoredfailed
: Failed - No Requirements Metpartial
: Partial - Not All Requirements Metdisruptive
: Disruptive - Caused Service Disruptioncomplete
: Complete - All Requirements Met
- completion_target_at
- Readonly datetime — The Completion target field shows the target date and time of the last task of the workflow.
- created_at
- Readonly datetime — The date and time at which the workflow was created.
- custom_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the related workflow template.
- custom_fields_attachments
- Writeonly attachments The attachments used in Custom fields.
- id
- Readonly integer — The unique ID of the workflow.
- impact
- Readonly enum, default:
none
— The Impact field shows the maximum impact level that is selected in the tasks that are a part of the workflow. This indicates the maximum extent to which the service is impacted when the implementation tasks that are related to the workflow are executed. Valid values are: -
none
: None - Service Not Degradedlow
: Low - Service Degraded for One Usermedium
: Medium - Service Down for One Userhigh
: High - Service Degraded for Several Userstop
: Top - Service Down for Several Users
- justification
- Required enum — The Justification field is used to select the reason why the workflow was requested. Valid values are:
-
compliance
: Compliancecorrection
: Correctionexpansion
: Expansionimprovement
: Improvementmaintenance
: Maintenancemove
: Moveremoval
: Removalreplacement
: Replacementpurchase
: Purchase
- manager
- Required reference to Person — The Manager field is used to select the Person who is responsible for coordinating the implementation of the workflow. If a manager is not specified for a new workflow, the API user is selected in the Manager field by default.
- note
- Optional text (max 64KB) — The Note field is used to provide a high-level description of the result that should be accomplished by the implementation of the workflow. It is also used to add any information that could prove useful for anyone affected by the workflow, including the people whose approval is needed and the specialists who are helping to implement it.
-
The Note field cannot be specified in the ?fields= parameter.
- note_attachments
- Writeonly attachments The attachments used in the Note field.
- planned_effort
- Readonly integer — The Planned effort field shows the total planned effort of the workflow. This is the sum of the planned effort (or planned duration if the planned effort is empty) of the workflow’s tasks and the planned effort of the related requests and problems.
- project
- Optional reference to Project — The Project field is used to link the workflow to a project.
- release
- Optional reference to Release — The Release field is used to select the release that the workflow is a part of.
- resolution_duration
- Readonly integer — The number of minutes it took to complete this workflow, which is calculated as the difference between the
created_at
andcompleted_at
values. - service
- Required reference to Service — The Service field is used to select the Service that will directly be affected by the workflow implementation, or in case of an emergency workflow, the service that was directly affected by the workflow implementation.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- start_at
- Optional datetime — The Start at field is used to specify the date and time at which the Status field of the first tasks of the workflow will automatically be set to “Assigned”.
- status
- Optional enum, default:
registered
— The Status field is automatically set based on the status of the workflow’s tasks. Valid values are: -
being_created
: Being Createdregistered
: Registeredrisk_and_impact
: Risk & Impact — deprecated: replaced byin_progress
approval
: Approval — deprecated: replaced replaced byin_progress
implementation
: Implementation — deprecated: replaced byin_progress
in_progress
: In Progressprogress_halted
: Progress Haltedcompleted
: Completed
- subject
- Required string (max 255) — The Subject field is used to enter a short description of the objective of the workflow.
- template
- Required reference to Workflow Template — The Template field contains the link to the workflow template that was used to register the workflow.
- updated_at
- Readonly datetime — The date and time of the last update of the workflow. If the workflow has no updates it contains the
created_at
value. - workflow_type
- Required enum — The type of the workflow. It contains the value of the Reference field of a Workflow Type.