Updates

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.

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}.

Major changes

New ^RunbookTeam endpoints

We've added three new ^RunbookTeam endpoints:

• Create a new Runbook Team - ^{POST /core/runbooks/{runbook_id}/runbook_teams}
• Delete a Runbook Team - ^{DELETE /core/runbooks/{runbook_id}/runbook_teams/{id}}‍
• Unlink a Runbook Team - ^{PATCH /core/runbooks/{runbook_id}/runbook_teams/{id}/unlink}

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.
  

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.

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.

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.

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:

• List Runbook Teams in a Runbook - ^{GET /core/runbooks/{id}/runbook_teams}

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.

Major changes

New ^Team endpoint

We've added a new ^Team endpoint:

• Delete a Centralized Team - ^{DELETE /core/teams/{id}}

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:

• Get roles for a runbook - ^{GET /core/runbooks/{id}/roles}
  

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 of^{500 Internal Server Error}.
• We’ve now removed support for Cutover Core version 3.63.0.

‍

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.

‍

Major changes

New ^Team endpoint

We've added a new ^Team endpoint:

• Get roles for a team - ^{GET /core/teams/{id}/roles}

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.

‍

‍

Major changes

New ^Runbook endpoint

We have added a new ^Runbook endpoint:

• Merge Runbook(s) - ^{PATCH /core/runbooks/{id}/merge}

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.

‍

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}

‍

Major changes

New ^Folder endpoints

We have added two new ^Folder endpoints:

• Create a new Folder - ^{POST /core/workspaces/{workspace_id}/folders}
• Update a Folder - ^{PATCH /core/workspaces/{workspace_id}/folders/{id}}

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).

‍

Major changes

New ^ActionLog endpoint

We have added a new ^ActionLog endpoint:

• List Action Logs - ^{GET /core/action_logs}

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:

• List Custom Fields - ^{GET /core/custom_fields}
• Get a Custom Field - ^{GET /core/custom_fields/{id}}
• Create a new Custom Field - ^{POST /core/custom_fields}
• Update a Custom Field - ^{PATCH /core/custom_fields/{id}}
• Delete a Custom Field - ^{PATCH /core/custom_fields/{id}/archive}

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:

• Archive a Runbook - ^{POST /core/runbooks/{id}/archive}

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.

‍

Major changes

New ^{Role Type} endpoint

We have added a new ^{Role Type} endpoint:

• List Role Types - ^{GET /core/role_types}
  

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:

• List User App Tokens - ^{GET /core/users/{user_id}/user_app_tokens}
• Create a New User App Token - ^{POST /core/users/{user_id}/user_app_tokens}
• Delete a User App Token - ^{DELETE /core/users/{user_id}/user_app_tokens/{id}}‍

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:

• Create a New Workspace - ^{POST /core/workspaces}
• Update a Workspace - ^{PATCH /core/workspaces/{id}}
• Archive a Workspace - ^{PATCH /core/workspaces/{id}/archive}
• Unarchive a Workspace - ^{PATCH /core/workspaces/{id}/unarchive}
  

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.

‍