Updates

Welcome to our Updates page, where you can find news and information about our latest API releases.

February 6, 2024

Version 2024-02-06

This update includes updates to the endpoint descriptions, a new attribute to the Runbook resource and a source_runbook attribute.

In this update, we have made the following changes: 

  • New updated descriptions now provide further clarity on each endpoint.

  • We have added a restricted attribute to the Runbook resource which means that the user must have a direct role to access the runbook. 

Note: You need to have at least Cutover Core version 2024.2.0 to see this attribute.

  • We have added a source_runbook attribute. The source runbook provides the ID from which the runbook was copied from. 

Note: This is only required on the Get a Runbook endpoint. 

November 20, 2023

Version 2023-11-20

This release introduces three new endpoints and an enhancement to List Runbooks.

New Runbook endpoints

In this update, we’ve added three new endpoints:

These endpoints will allow you to manage your runbooks by giving you the ability to pause, resume and cancel. 

Note: You need to have at least Cutover Core version 3.84 to use these endpoints.

Enhancement to the List Runbook(s) endpoint

We’ve added the following attributes to the Runbook resource to help with sorting the List Runbooks response by when the runbooks were last touched_at.

  •  GET /core/runbooks?sort= parameter. sort=touched_at

Note: You need to at least have Cutover Core version 3.83 to use this attribute.

November 7, 2023

Version 2023-11-07

This release introduces new Stream endpoints.

In this update, we’ve added three new endpoints: 

Note: You need to have at least Cutover Core version 3.84 to use these endpoints.

October 3, 2023

Version 2023-10-03

This release introduces a new query parameter to Get Roles for a User API.

Major changes

Enhancements to the Get Roles for a User endpoint

We’ve added a 'resource_type' query parameter to the Get Roles for a User endpoint to help improve the filtering of your results. It can filter on global, folder, workspace, runbook, stream or user.

Note: You need to at least have Cutover Core version 3.82 to use this query parameter.

August 22, 2023

Version 2023-08-22

This release introduces enhancements to merge runbooks API and the ability to create linked runbooks.

Major changes

New options added to the Merge Runbook(s) endpoint

We’ve added a new Merge Runbook(s) endpoint:

  • Insert after task id - PATCH/core/runbooks/{id}/merge . This allows you to specify where you want the incoming runbook to be inserted.
  • Insert type - PATCH/core/runbooks/{id}/merge. When you are inserting multiple runbooks, the ‘insert type’ determines whether the tasks are inserted in parallel or sequence. 

Added new Linked Runbooks functionality

  • We’ve added the following attributes to the Task resource to help with managing Snippets and Linked Runbooks. This new functionality allows you to create linked runbooks: core.task.attributes.task_links

Other minor changes

Enhancements to the Get a Runbook resource for Snippets functionality

  • We’ve enhanced the following attribute: template_type - Indicates whether the runbook isn’t a template at all (off), is a normal template (default), or is a snippet template (snippet). 

New Get a User query parameter

  • We’ve added a new query parameter to the Get a User endpoint: id_key

Note: You will need to at least have Cutover Core version 3.82 to use all of these new features

July 25, 2023

Version: 2023-07-25

This release introduces enhancements to the List Tasks in a Runbook response, to the runbook resource and to the Get a Runbook endpoint.

Major changes

Enhancements to the List Tasks in a Runbook response

We’ve made two enhancements to the List Tasks in a Runbook response:

  • Forecast mode now also returns predecessors and successors array of tasks as part of the relationships object.
  • When the source_runbook field is included in the fields list, custom field values belonging to that source runbook are now included. These values are marked read_only in the response because they are a historical snapshot of the source runbook, and are not updatable when updating custom fields on a task.

Note: You need to at least have Cutover Core version 3.81 to benefit from both of these improvements.

Enhancements to the Runbook resource

We’ve made two enhancements to the the Runbook resource:

  • We’ve added an author object to the relationships object of the Runbook resource. It can be read to see which user created a runbook but can also be written to (to state which user authored a new runbook) when using Create a new Runbook. This is important for any user looking to make API calls from ServiceNow using Business Rules. The author object can be used to pass through the user that has made the call request and will make them the Runbook Admin in Cutover. The user must have the 'Workspace runbook creator' role assigned to them to be made Runbook Admin in this scenario.
  • We’ve added an external_id attribute to the Runbook resource. This ID pertains to an external system, such as an IT service management ticket associated with the runbook. It must be unique to Cutover - two runbooks can’t share the same external_id.

Note:  You need to at least have Cutover Core version 3.81 to benefit from both of these improvements.

New Get a Runbook query parameter

In light of the addition of the external_id attribute to the Runbook resource, a new query parameter has been added to the Get a Runbook endpoint:

  • id_key

It can filter on either a normal runbook id or on the external_id.

Note: You need to at least have Cutover Core version 3.81 to use this query parameter.

May 22, 2023

Version: 2023-05-22

This release introduces two new query parameters for listing action logs, plus a couple of other minor improvements and fixes.

Major changes

New ActionLog query parameters

We've added two new query parameters to the List Action Logs endpoint:

  • created_after
  • created before

These new query parameters allow you to filter by actions performed after and before a given date and time.

Note: You need to at least have Cutover Core version 3.79 to use these query parameters.

Other minor changes

  • We've improved our generic remote error response by now providing specific error information with it.
  • The List Tasks in a Runbook response now provides relationships data about runbook_teams.
May 4, 2023

Version: 2023-05-04

This release introduces three new endpoints for runbook teams, plus some other enhancements for template workflows.

Major changes

New RunbookTeam endpoints

We've added three new RunbookTeam endpoints:

These endpoints give you greater control and more efficient management over your runbook teams. You can create new runbook teams in a specified runbook, as well as delete them from a specified runbook. You can also unlink a runbook team from its centralized team, which copies its list of users over to a specified runbook which can then be customized.

Enhancement to the Runbook resource for template workflows

We’ve added the following attributes to the Runbook resource to help with managing and tracking template workflows. They can be used to retrieve the status of templates, as well as provide other key information, all of which can be important for reporting purposes.

  • attributes.template_status - Indicates whether the template’s status is currently draft, pending or approved. This attribute is read only.
  • attributes.template_type - Indicates whether the runbook isn’t a template at all (off), is a normal template (default), or is a snippet template (snippet). This attribute can be read and written.
  • meta.approval_status - Indicates whether the template’s approval status is currently pending, open, approved, rejected, expiring or expired. This attribute is read only.
  • meta.template_version - Indicates the current version of the template. This attribute is read only.
  • relationships.reviews - Provides an array of template reviews with their respective IDs. This attribute is read only. The details of each review is in the included section at the bottom of the response. This relationship is only included in the Get a Runbook response.
March 1, 2023

Version: 2023-03-01

This release introduces two enhancements to the task resource.

Major changes

Enhancements to Task resource

We’ve added the following in relation to the auto_finish attribute. Note: You need to at least have Cutover Core version 3.76 to benefit from these improvements:

  • New error codes for scenarios in which it isn't possible to set auto_finish:

    - task.auto_finish_on_auto_finish_task_type: It can't be set on an Auto Finish task type.
    - task.auto_finish_on_branching_task_type: It can't be set on a Branching task type.
    - task.auto_finish_on_integration: It can't be set on an Integration task type.
    - task.auto_finish_on_linked_task_type: It can't be set on a Linked to Runbook task type.
    - task.auto_finish_on_required_custom_fields: It can't be set on tasks with required custom fields that display on the task's end.
    - end.task.auto_finish_on_snippet_task_type: It can't be set on a Snippet task type.
    - task.auto_finish_requires_end_fixed: It can't be set on tasks that have a fixed due date and time.
  • The auto_finish attribute can be set to null, which will mean the task will fall back to the associated task type's auto_finish value.
January 31, 2023

Version: 2023-01-31

This release introduces three enhancements to the task resource, the List Folders endpoint and the stream resource respectively.

Major changes

Enhancement to Task resource

We’ve added an auto_finish attribute to the Task resource. This means you can read whether a task is set to automatically finish, as well as use the endpoints Create a New Task and Update a Task to apply automatic finishes to tasks. To clarify the working of the auto finish feature, a task will automatically finish once its specified duration has expired, provided all validation has passed beforehand. Note: You need to at least have Cutover Core version 3.76 to benefit from this improvement.

Enhancement to the List Folders endpoint

We’ve added meta.permissions data to the Folder resource in the List Folders response, enabling you to read which folders you have the permission to create runbooks in. Note: You need to at least have Cutover Core version 3.76 to benefit from this improvement.

Enhancement to the Stream resource

We’ve added parent data to the stream.relationships  object so you can see which substreams belong to which parent stream.

January 11, 2023

Version: 2023-01-11

This release introduces an enhancement to the folder resource.

Major changes

Enhancement to Folder resource

We’ve added parent data to the folder.relationships object so you can see which subfolders belong to which parent folder, create new subfolders, and update subfolders so they belong to different parent folders. Note: You need to at least have Cutover Core version 3.73 to benefit from this improvement.

December 6, 2022

Version: 2022-12-06

This release introduces a new endpoint for runbook teams, plus an enhancement to task endpoints.

Firstly, a notice: A fix has been implemented in Cutover Core version 3.73 meaning that Update a Runbook works as expected. If you have an earlier Cutover Core version, the call incorrectly results in creating a new or empty runbook version. To avoid this, upgrade to 3.73.

Major changes

New RunbookTeam endpoint

We've added a new RunbookTeam endpoint:

This endpoint lets you retrieve all runbook teams from the current version of a specified runbook.

Note: You need to at least have Cutover Core version 3.73 to use this endpoint.

Enhancement to Task endpoints

For Task endpoints, we've added the ability to read and update runbook teams who are assigned to, and are recipients of communications from, a task. Note: You need to at least have Cutover Core version 3.73 to benefit from this improvement.

Other minor changes

  • We’ve implemented a fix to ensure that Runbook endpoint responses include the relationships object’s runbook_type object.
September 26, 2022

Version: 2022-09-26

This release introduces two new endpoints for teams and runbooks respectively, as well as some other minor improvements and fixes.

Major changes

New Team endpoint

We've added a new Team endpoint:

This endpoint lets you delete a centralized team that you no longer require. It will temporarily mark the team as archived before copying all deleted roles to linked runbook teams, and then fully deleting the team.

New Runbook endpoint

We've added a new Runbook endpoint:

This endpoint lets you retrieve the roles (for example Runbook Admin, Stream Editor and Runbook Member) connected to a specified runbook.

Note: You need to at least have Cutover Core version 3.65 for this endpoint to work.

Other minor changes

  • We’ve added the ability to read and update users who are assigned to, and are recipients of communications from, a task. This applies to List Tasks in a Runbook, Get a Task, Create a new Task and Update a Task endpoints. Note: You need to at least have Cutover Core version 3.68 for this endpoint to work.
  • We’ve added query parameters to the List Users endpoint so you can filter returned results. Note: You need to at least have Cutover Core version 3.69 for these to be available:

    - page[number](pagination)
    - query (approximate string matching by team name (also known as a ‘fuzzy’ search))
    - role_type_id
    - workspace_id
  • We’ve added event and resource_type query parameters to the List Action Logs endpoint to help improve the filtering of your results. Note: You need to at least have Cutover Core version 3.68 for these to be available.
  • When no bearer token is passed for authentication, we’ve corrected the error that gets returned; it is now 401 Unauthorized instead of500 Internal Server Error.
  • We’ve now removed support for Cutover Core version 3.63.0.

September 8, 2022

Version: 2022-09-08

This release introduces a couple of enhancements to a task and user endpoint respectively, as well as some other minor improvements and fixes.

Major changes

Enhancement to List Tasks in a Runbook endpoint

When you request a source_runbook in the  List Tasks in a Runbook endpoint via the source_runbook_id query parameter, the response now includes the full runbook object in the included array.  Note: You need at least Cutover Core version 3.67 to benefit from this enhancement.

Enhancement to Get roles for a user endpoint

We’ve enhanced the included object in the Get roles for a user  endpoint’s response to include all possible resources that the relationships object references within it.

Other minor changes

  • We've improved our User endpoint's path parameters documentation to make it clear when a user's email can be used instead of their ID. Note: You need to at least have Cutover Core version 3.67 to benefit from this improvement.

August 24, 2022

Version: 2022-08-24

This release introduces a new endpoint for retrieving information on team roles, as well as some other minor improvements and fixes.

Major changes

New Team endpoint

We've added a new Team endpoint:

This endpoint lets you retrieve the roles for a team member by their ID or email.

Note: You need to at least have Cutover Core version 3.65 for this endpoint to work.

Other minor changes 

  • We’ve renamed Team/s to Centralized Team/s where relevant in our endpoint documentation.
  • We’ve improved our JSON examples in our endpoint documentation for Create a new Centralized Team and Update a Centralized Team.
  • We’ve removed support for Cutover Core version 3.61.

August 2, 2022

Version: 2022-08-02

This release introduces a new endpoint for merging runbooks, as well as several other minor improvements and fixes.

Major changes

New Runbook endpoint

We have added a new Runbook endpoint:

This endpoint lets you merge single or multiple runbooks into the runbook that you specify in the path parameter. 

Note: You need to at least have Cutover Core version 3.65 for this endpoint to work.

Other minor changes 

  • We have added three query parameters to List Teams to improve the ability to filter returned results. Note: You need to at least have Cutover Core version 3.65 for these parameters to work:

    - page[number] (pagination)
    - query (approximate string matching by team name (also known as a ‘fuzzy’ search))
    - workspace_id
  • We have made general fixes and improvements to the Role resource. We have also added request examples to endpoint documentation that uses the resource. Note: You need to at least have Cutover Core version 3.65 to benefit from these fixes and improvements.
  • We have added the key attribute to the RoleType resource. For example, this means you can read and pass the key string workspace-stakeholder as opposed to having to look up the RoleType's id.
  • We have implemented a fix for missing custom_field_values for returned Task resources.
  • We have implemented a fix to hide a returned Runbook resource’s relationships attribute source_runbook when the attribute has not previously been set.
  • We have improved the detail given in the 400 Bad Request error, which now makes it clearer when path parameters have not been specified. The lack of details previously given was liable to lead to the incorrect assumption that the error was in the JSON payload.

July 13, 2022

Version: 2022-07-13

This release adds support for Cutover Core version 3.64, adding communication- and login-related attributes to the user resource.

Major changes

New User attributes

We have added some new attributes to the User resource to increase its comprehensiveness.

  • You can now create, update and read a user’s email and SMS acceptance settings with accept_email and accept_sms.
  • You can now read login-related activity and metrics via these meta attributes:

    - last_activity_at
    - last_sign_in_at
    - invitation_accepted_at
    - invitation_sent_at
    - sign_in_count

June 22, 2022

Version: 2022-06-22

This release adds support for Cutover Core version 3.63, introducing two new endpoints for folders.

Major changes

New Folder endpoints

We have added two new Folder endpoints:

These endpoints give you greater control and management over your folders in a specified workspace. You can create new folders and you can update the name and description of existing ones.

Other minor changes

  • We have added a runbook’s description to the List Runbooks response. Even if a runbook has not been given a description, a blank string is now returned.
  • We have added source_runbook_id as a query parameter to List Tasks in a Runbook, letting you filter your task results by it.
  • We have added the ability to pass users/{email} as well as users/{id} on all endpoints using the user path. For example, you can now call GET /core/users/user%40example%2Ecom (note that periods must be escaped).

June 3, 2022

Version: 2022-06-03

This release adds support for Cutover Core versions 3.61 and 3.62, introducing nine new endpoints covering action logs, custom fields, runbooks and tasks.

Major changes

New ActionLog endpoint

We have added a new ActionLog endpoint:

Provided you are either a Global User Admin or a Global Stakeholder, this lets you retrieve all of the action logs for your instance. Action logs provide you with a description of the action, any related changes because of the action, the author of the action, and the resource involved in the action. This information can be used for auditing purposes.

New Custom Field endpoints

We have added five new Custom Field endpoints:

These endpoints give you the ability to manage your custom fields. List Custom Fields lets you retrieve all of the custom fields in your instance, whereas Get a Custom Field lets you retrieve a specific custom field by its ID. Delete a Custom Field will in fact archive (as opposed to hard deleting) a custom field you no longer wish to make use of, meaning it is still possible to read it at a later date.

New Runbook endpoint

We have added a new Runbook endpoint:

This endpoint lets you archive a runbook, removing its visibility and access from your instance once it is no longer required or has served its purpose.

New Task endpoints

We have added two new Task endpoints:

  • Skip a Task - GET /core/runbooks/{runbook_id}/tasks/{id}/skip
  • Delete a Task - DELETE /core/runbooks/{runbook_id}/tasks/{id}

These endpoints add to the existing task endpoints, furthering your ability to control and manage tasks by being able to skip or delete a specific one in a runbook.

Other minor changes

  • We have added the forecast query parameter to the List Streams in a Runbook endpoint. This means the endpoint now has two modes - a conventional mode which only returns attributes related to the streams, and a ‘forecast’ mode which returns additional start and end time information that has been calculated from the stream’s tasks.

May 16, 2022

Version: 2022-05-16

This release adds support for Cutover Core version 3.60, introducing eight new endpoints covering role types, user app tokens, and workspaces.

Major changes

New Role Type endpoint

We have added a new Role Type endpoint:

This lets you retrieve all of the role types that are currently enabled in your instance, providing an ID and a description of the role type. You can then use role type IDs when creating, updating or simply just reading roles.

New User App Token endpoints

We have added three new User App Token endpoints:

These endpoints provide you with the ability to control and manage API access to your Cutover instance. List User App Tokens lets you retrieve all of the user app tokens belonging to a specific user. Create a New User App Token lets you create new tokens per user, and Delete a User App Token lets you delete tokens per user (effectively meaning you can revoke a user’s API access).

New Workspace endpoints

We have added four new Workspace endpoints:

These endpoints provide you with the ability to manage your workspaces. Update a Workspace lets you update the name and description of a specified workspace, Archive a Workspace lets you remove visibility and access to a specified workspace once it is no longer required or has served its purpose, while Unarchive a Workspace lets you restore it if it is needed again.

'Changelog' added to your API Portal

We have added a 'Changelog' section to your instance’s API Portal, providing you with a list of all the changes for every API version that we release.

The section is accessed by clicking on My Profile in the bottom-left corner of the app and, under where it says 'View API endpoint documentation with credentials:' in the My Details panel, click either On the Developer Portal or On your API instance

This takes you to the ‘Overview’ page, at the top of which sits the ‘Changelog’.

Other minor changes

  • We have added the ability to pass custom_field_values to the Start a Task and Finish a Task endpoints.
  • We have added example JSON requests to the documentation for Create a New Task and Create a New User. Previously these areas were blank.
  • We’ve ensured the last page link is always shown in pagination. Previously it wasn’t showing when you were on the last page itself.

Cookie consent

By clicking “Accept”, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View our Privacy Policy for more information.