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": "4me",
  "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 Used
• non_standard: Non-Standard - Approved Workflow Template Not Available
• emergency: Emergency - Required for Incident Resolution
• order: 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 Requester
• rejected: Rejected - Rejected by Approver
• rolled_back: Rolled Back - Original Environment Restored
• failed: Failed - No Requirements Met
• partial: Partial - Not All Requirements Met
• disruptive: Disruptive - Caused Service Disruption
• complete: 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 Degraded
• low: Low - Service Degraded for One User
• medium: Medium - Service Down for One User
• high: High - Service Degraded for Several Users
• top: 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: Compliance
• correction: Correction
• expansion: Expansion
• improvement: Improvement
• maintenance: Maintenance
• move: Move
• removal: Removal
• replacement: Replacement
• purchase: 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 and completed_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 Created
• registered: Registered
• risk_and_impact: Risk & Impact — deprecated: replaced by in_progress
• approval: Approval — deprecated: replaced replaced by in_progress
• implementation: Implementation — deprecated: replaced by in_progress
• in_progress: In Progress
• progress_halted: Progress Halted
• completed: 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.