Change sets
A change set collects every resource Catalyst modified in a chat session: workflows, help desk skills, Catalyst skills, dashboards, and more. You can view the change set in the collapsible changes slip above the chat composer. Until you publish (or a review is approved and published), changes exist only as drafts tied to the chat session.Apply or reject a promotion
When choosing resources for a promotion, open Filter resources and choose Additions, Edits, or Deletions under Change type. You can select multiple change types and combine them with resource types and search. Reset filters clears the filters without clearing your resource selections. When choosing resources for a promotion, a resource with a reported configuration problem shows a slashed checkbox and Needs fixing. Hover over or click that control to see the problem and recovery guidance. Opens in [workspace] identifies the workspace that needs repair; follow Edit [resource name] to open the resource in a new tab. After correcting the problem and saving or publishing the resource, reload the page to update the comparison and make it selectable. Only resources with their own reported errors have disabled checkboxes. Other resources remain selectable, including those that reference a blocked resource. Staging and applying the promotion still validate prerequisites and group references. Conflicting integration or access-resource IDs block the affected promotion items, including roles whose parent access resource has a conflicting ID. You can still promote other resources. Contact support to repair the conflicting IDs. Access-profile promotions include user-field matching rules, such as email conditions, including their condition groups and excluded values. A profile that references custom roles cannot be promoted between workspaces. Its selection control shows the reason, and other resources remain selectable. Custom roles are not created in the receiving workspace. When you choose Propose, an access profile whose name conflicts with a different profile in the receiving workspace or another selected profile blocks the proposal. Choose Fix with Catalyst to investigate the conflict with the affected resource and source and receiving workspace context. This action is available when you have permission to start a Catalyst chat. Give the source profile an unused name, refresh the comparison, and select the renamed profile before proposing again. Ask a source-workspace manager if you can’t edit profiles. To reuse a name freed by a rename or deletion, apply that change in a separate review first. Pull latest also checks access-profile names: rename the conflicting profile in the branch or ask a parent-workspace manager to rename the incoming profile, then refresh the comparison and pull again. Conflicts between incoming profiles must be corrected in the parent workspace. When you select Propose, Serval checks selected workflow names against the published receiving-workspace resources in the comparison, deployed workflows including imports, and your selected changes. If a name conflicts, the dialog identifies the workflow and blocks the proposal. Rename the workflow in the source workspace, publish it, reload the page to update the comparison, and propose again. You can also deselect the conflicting workflow and propose the remaining changes. To reuse a name freed by a rename or deletion, apply that change in a separate review first. Pull latest also checks names before staging. If a branch resource owns the incoming name, the error identifies it: rename that resource in the branch, publish, and pull latest again. Conflicts solely between incoming changes must be corrected in the parent workspace. When you choose Propose, a status name that conflicts with a different status group in the receiving workspace blocks the selected batch. The error identifies the status and both groups. Rename the source status under Settings → Ticket Types, reload the page to update the comparison, and propose again. You can also deselect that status set and propose the remaining resources. Propose also blocks a status set that adds new statuses when its ticket type is disabled in the receiving workspace. Edits to existing statuses remain allowed. A workspace administrator can enable standard or Journey ticket types under Settings → Capabilities in the receiving workspace, then propose again. For custom ticket types, open Settings → Ticket Types in the receiving workspace and select Enable custom types. You can also deselect a blocked status set and propose the remaining resources. Enabling a capability in the source workspace does not enable it in the receiving workspace. If an omitted status is used by tickets, rules, ticket type lifecycles, or transitions in the receiving workspace, Propose blocks the change. To preserve that status, an administrator with access to both workspaces can first promote the receiving workspace’s statuses back to the source workspace. This replaces the entire status set for that ticket type, so review the comparison and preserve any source statuses you still need. Alternatively, move or remove the receiving workspace’s references. Refresh the comparison and propose the updated change. Apply checks references again because they can change after the review is proposed. The comparison also identifies workflows being created in the receiving workspace with a slash or backslash in the name, workflows with no published code, and help desk skills that exceed the content limit. Updates to existing workflows preserve the accepted name rules. Follow the resource’s guidance to correct it in the source workspace, publish it, and reload the page to update the comparison. Other healthy resources can still be promoted. A workflow whose approval procedure is missing or belongs to another workspace shows Needs fixing without hiding the other resources. Select an approval procedure owned by the workflow’s workspace, publish the workflow, and reload the page to update the comparison. Contact support if the approval configuration cannot be repaired in the editor. A skill that references a missing workflow shows Needs fixing without hiding the other resources. Edit the skill to replace or remove the invalid workflow reference, publish it, and reload the page to update the comparison. An evaluation whose participants cannot be resolved shows Needs fixing without hiding the other resources. Choose valid participants permitted by your organization’s user settings, save the evaluation, and reload the page to update the comparison. An app instance or app resource whose custom service is unavailable shows Needs fixing without hiding the other resources. Restore the custom service or update the affected configuration to use an active service, then reload the page to update the comparison. Contact support if the unavailable service prevents editing the resource. Open a promotion from either the sending or receiving workspace to apply or reject it. Apply promotion and Reject both require configuration-transfer permission in the receiving workspace, which workspace managers have. Managing only the sending workspace doesn’t grant either action. If you lack this permission, both buttons stay visible but disabled. Hover over a disabled button to see which receiving workspace requires permission. When a promotion doesn’t require approval, Review ready notifications go to receiving-workspace members with configuration-transfer permission, excluding the requester. Open the review to inspect the changes before applying or rejecting them. Required approvals, promotion checks, and user matches must still be complete before you can apply the promotion. If a resource reference can’t be resolved, Preview keeps the resource’s other details visible and marks the unavailable reference with a placeholder, such as Group unavailable. If the reference lookup fails, choose Try again in the warning banner. Code shows the stored configuration. Placeholders don’t change the configuration or bypass validation when you apply the review. Where cross-organization promotions are enabled, you can use Preview from the sending workspace for resources whose staged changes and before-and-after states don’t reference users. If either state references a user, open the promotion in the receiving workspace with review permission to preview matched users. The sending workspace still shows the staged configuration. For promotions within your organization, reviewers in the receiving workspace can choose Review users to inspect users referenced by the remaining changes and the resources that use them. If a required user isn’t a member of the receiving workspace, add them under Settings → Your Workspace → Users in that workspace. If the user is deactivated, reactivate them or select an active user in the source resource and submit an updated change. Return to the review to check eligibility before applying. While an apply attempt is running or has failed, the review shows Apply attempted by with the person’s name. Published by identifies the person whose apply completed. Check the review status and resource results to see which changes reached the receiving workspace. Where workspace environments are enabled, the workspace’s Reviews page remembers your promotion path, application status, author, and title search when you return from a review or reload the page. These filters are saved in your browser separately for each signed-in user and workspace. With Test & Release enabled, you can choose Withdraw on a promotion you proposed and confirm Withdraw promotion. The review moves to Closed. If no resource changes have been applied, its header shows Withdrawn even if an approval is still pending. The receiving workspace can’t apply the withdrawn promotion. Its recorded failures remain available for investigation, but fixing a dependency doesn’t make it retryable. Submit a new promotion from the source workspace; Catalyst uses the review’s withdrawal state when explaining this next action.Promotion check changes
Catalyst can stage your workspace’s promotion check settings as a portable resource. Where promotion checks are enabled, choose Open resource → Promotion checks to view required workflows and evaluation suites. In a Catalyst session, you can stage changes to these checks and inspect additions and removals before proposing or publishing them. Find the policy under SDLC settings in the review’s resource list, or enter that name in Search resources. You can also open Promotion checks from Test & Release → Reviews. Promotion links open Reviews with promotions selected. The dialog identifies the workspace whose policy you’re viewing. Users with permission to manage that workspace’s SDLC settings can select checks and choose Save checks; users with settings-view permission can inspect the policy without editing it. Each check run captures the checks it runs and their results. The review’s check list links to the resulting workflow or evaluation-suite run so reviewers can inspect the evidence before publishing. In the workflow summary, a workflow that requires promotion check context and has no explicit trigger shows Promotion check. Its trigger card explains that it runs when promotion checks start for a review, instead of showing a requester audience. Promotion workflow checks run in the source workspace before the promotion is applied. A target workspace’s policy can require checks, but those workflows still execute in the source workspace. Resource lookups within a check use the workspace specified by the workflow;ctx.currentTeam refers to the source workspace. To investigate a failure, open the linked run and inspect its error rather than inferring the cause from the target workspace’s configuration.
For each selected evaluation suite, choose Minimum pass to set a whole-number percentage from 1% to 100%, then choose Apply and save the policy. The default is 100%. This threshold belongs to that suite’s entry in the promotion check configuration; workflow checks still have to pass individually.
The suite check waits for the run to finish and divides evaluations that met their expected result by all evaluations in that run. Missing scores count against the total. An empty suite or an execution error fails the check regardless of the percentage. The linked suite run shows this check result separately from the Scored evaluation pass rate, which considers only scored evaluations.
For promotions between linked workspaces, including workspaces that aren’t branches, required checks come from the receiving workspace’s current policy plus any promotion check configuration included in the review. Unrelated checks in the source workspace’s policy do not block the promotion. Checks run against the source workspace’s published configuration, using the stricter minimum pass percentage when both policies require the same suite. Removing a selected check from the source workspace’s live policy does not stop it from running for that review. Reviewers can inspect suite changes and percentage changes in the promotion diff. Removing a receiving-workspace requirement from the selected policy cannot bypass it; unavailable required workflows or evaluation suites still fail the checks.
The review’s Rerun all action creates a fresh check run and reruns the full required suites. Rerunning checks requires permission to author promotions in the source workspace; a workspace link alone doesn’t grant it. Rerunning an individual evaluation separately does not update an earlier check run’s result. Each attempt retains the threshold used for that attempt.
Checks not started means required checks haven’t started; open the checks and choose Start checks. Checks need rerunning means the last attempt doesn’t cover the current policy, and Checks failed means a required check failed. Apply promotion stays disabled until the required checks pass. Linking workspaces in both directions applies the receiving workspace’s requirements to each promotion.
If promotion checks are enabled after you create a promotion, ask a user with permission to author promotions in the source workspace to choose Start checks on the existing review. You don’t need to recreate the promotion. The receiving workspace can apply it after the required checks pass.
For branches, Pull latest rebases the branch on its parent’s changes and is exempt from promotion checks. Its review shows Checks not required. If a required workflow or suite is missing from the branch, pull and apply the parent’s changes, then choose Rerun all on the original promotion review. Pulling the policy doesn’t replace the original review’s check results. An ordinary promotion in the reverse direction still runs checks.
Publishing and discarding individual changes
You don’t have to publish an entire change set at once. When approval isn’t required, you can publish or discard individual changes from the changes slip above the composer, or from a resource’s own tab. Publishing a change also applies any drafts it depends on; discarding one also discards the drafts that depend on it, so the change set stays consistent. If Catalyst reports that a resource already has a pending deletion, review and publish that existing deletion instead of asking for another one. If the deletion failed to publish, open its failed change, fix the reported publish error, and retry the same deletion through your workspace’s normal review process. Choose Discard only if you intend to keep the resource. If a workflow in a saved review has already been deleted separately, publishing its deletion completes with the workflow remaining deleted. You can retry that deletion on the same approved review; other errors still need the reported repair before publishing succeeds.Direct publish vs review
Which path you use depends on the Catalyst review approval settings. Workspace managers configure the policy in Approval settings → Catalyst, opened from Settings → Catalyst or from the Reviews page under Test & Release.- If Require approval before publishing is off, users with Builder permissions or higher can directly publish changes drafted by Catalyst.
- If Require approval before publishing is on, users with Builder permissions or higher must propose the change set for review. The approvers in the selected approval procedure must sign off before anyone can publish.
When approval is required, per-resource Publish buttons are hidden.
Publishing happens only after a review is approved and someone clicks
Publish.
Workspace settings for reviews
Managers can configure review behavior by clicking Approval settings under Settings → Catalyst, or on the Reviews page under Test & Release. If you can view workspace settings but can’t update them, you can open Approval settings to inspect the saved policy. The policy is read-only, with no editing or save controls. In the Approval settings dialog, select Catalyst to open Catalyst review approvals and configure publishing approvals for Catalyst changes. Select Incoming promotions to configure approval for configuration received through Workspace Links. Saving this policy leaves the Catalyst approval requirement unchanged.Require approval before publishing
When enabled:- Builders must propose change sets for review rather than publishing directly from the chat.
- The approvers in the selected approval procedure must approve or deny each review.
- After approval, an authorized user clicks Publish on the review to apply the change set.
- Turn on Require approval before publishing. Builders then see Propose for review instead of Publish.
- Under Approval procedure (in beta), select one of your workspace’s approval procedures, or click Create approval procedure to add one.
- Click Save changes. You can’t save while approval is on and no procedure is selected; the dialog shows Select an approval procedure to save.
Propose for review
When approval is required and you have pending changes:- Finish staging changes: Confirm every resource in the change set shows the state you expect.
- Click Propose for review: In the collapsible bar above the composer, click Propose for review.
- Add title and description: Enter a short title (required) and optional description explaining what changed and why. Click Propose.
- Notify reviewers: The review appears in the Reviews view of the Catalyst page for teammates with access. They can inspect changes without opening your private chat (unless you shared it as a workspace chat).
Reviewer workflow
Slack change set approval messages show the Target environment, so you can check where the changes will apply before approving. When email notifications are enabled, designated approvers receive a Change set approval email for Catalyst changes. The email includes the review title, a summary of up to 500 characters, requester, and resource count. Click Open review to read the full description, inspect the changes, and approve or deny them in Serval.- Open the Catalyst page from the sidebar and switch to the Reviews view, or open Reviews under Test & Release. Reviews show a title, proposer, linked resources, and status.
- Select a review to see title and description (editable by reviewers with access), Catalyst session link that opens the originating chat if you have access, per-resource diffs (workflow code changes, skill content, etc.)
- Approve or deny the review
After publishing
- Resources show as Published in the originating chat session
- Workflows appear in Workflows, skills in Skills, and dashboards in Analytics
- The review status updates to Published
- Select Fix with Catalyst. The error context includes the form’s identity and the failed review. If the action is unavailable, ask a workspace administrator to recover the review using Catalyst.
- Have Catalyst read the current form and reapply the review’s intended changes in a fresh draft, preserving other current edits.
- Select Propose for review, then follow the new review’s approval and publishing steps.
HttpIntegration alias is incorrect, correct it to match a configured app and submit an updated change.
The review keeps successfully applied changes separate from failed changes. Follow the failed resource’s guidance before retrying. For an unknown failure, choose Copy support reference and include the reference when you contact support.
If a promotion is missing a required custom service, access policy, access profile, provisioning workflow, or linked role on the target workspace, the failed resource identifies the missing reference and explains what to include or publish. A role can reference a linked group owned by the target workspace or available through an app connection shared for use with that workspace. Referencing a shared group doesn’t let the promotion update that group. If multiple shared connections contain the same group identity, resolve that ambiguity before retrying. If the target workspace has neither an owned nor an accessible shared group, share the appropriate app connection or connect and sync the matching target app. For an access profile referencing an unavailable group, share that group with the target workspace when appropriate, or select an organization-owned group available to both workspaces. Keep the intended access restrictions when fixing missing dependencies.
Sharing is checked again before a linked group grants new access. If the app is no longer shared with the role’s workspace, restore sharing before retrying the access request. For apps that allow only one role per user, this check also happens before removing the user’s previous role. Revoking a share does not remove existing group members or prevent removal of previously granted access.
If a workflow’s required approval procedure is removed from the receiving workspace after staging, applying the workflow fails. Promote the procedure to the receiving workspace again, then retry the original review. You can also select an available procedure on the source workflow and submit an updated promotion. The workflow isn’t published without its required approval.
Choose Investigate with Catalyst in the review footer to start a new private chat in the source workspace. The button remains available while the review has failed changes, alongside the secondary retry action. It is available from either workspace’s review view when you have permission to view, create, and edit Catalyst chats in the source workspace. The chat includes a review mention that links back to the original review. Catalyst reads the failed items and proposed changes to help you prepare a repair. Create a new review for corrected source resources. Retrying the original review attempts its failed changes again, which can help after resolving a conflict in the target workspace. A successful simulation run doesn’t establish that other draft changes published. Check the remaining drafts before discarding them.
If a promoted skill or access policy has a name already used on the target workspace, rename the source resource and submit an updated change. To update an existing resource, preserve its original identity instead of creating a separate copy. A conflicting workflow identity identifies the existing target workflow; use that workflow or restore it from Recently deleted when applicable.
Read reviews through the API
Use the read-only/v2/reviews API to inspect an existing review from an integration or approval workflow. It supports reviews from Catalyst sessions, background-agent sessions, and promotions.
- Call
GET /v2/reviews?teamId=TEAM_IDto find reviews owned by a workspace. Useoutgoing=trueto list promotions from that workspace. - Call
GET /v2/reviews/REVIEW_IDfor the source and target organizations and workspaces, session context, current approval status, and change-set apply status.originisREVIEW_ORIGIN_CATALYSTfor session-owned reviews (including background-agent sessions) orREVIEW_ORIGIN_PROMOTIONfor config pushes. If a source or target workspace has been deleted, its organization ID is omitted. - Call
GET /v2/reviews/REVIEW_ID/itemsfor item metadata. PassnextPageTokenback aspage_tokenuntil it is empty. Both list endpoints default to 50 results and accept apage_sizeup to 100. - Call
POST /v2/reviews/REVIEW_ID/items:batchGetwith{"itemIds":["ITEM_ID", "OTHER_ITEM_ID"]}for up to 20 unique items’beforeandafterresource documents. Results follow request order; a missing item or an item from another review fails the entire request. You can also read one item withGET /v2/reviews/REVIEW_ID/items/ITEM_ID. Creates have nobeforedocument; deletes have noafterdocument. Updates merge the proposed patch onto the comparison’s before state.
contentStatus is REVIEW_ITEM_CONTENT_STATUS_MISSING_BASE or REVIEW_ITEM_CONTENT_STATUS_UNSUPPORTED, stop automated approval and send the item for manual inspection.
Each item’s resourceKind uses the backend’s canonical kind, such as workflow or skill. Its applyResult contains exactly one outcome: pending: {}, applied: {}, or failed: {"reason": "…"}. This is the result of applying the staged change, not the resource’s runtime status. Failure reasons are redacted. contentStatus separately describes whether its comparison documents are available; an applied item can still have unavailable documents.
Scoped API keys need Read reviews (reviews:read) and access to the source or target workspace. A workflow in either workspace can read the promotion’s details, items, and comparison documents. Session reviews require access to the session’s workspace. Cross-organization programmatic reads aren’t supported.
approval.status, approval.required, review.applyStatus, and review.closedAt describe separate states. An approved review is not necessarily published. A nonempty review.closedAt means the review was withdrawn and cannot be retried, even if its saved apply status is failed. Catalyst uses this state and the operation kind to recommend an available replacement, such as a new promotion or a fresh Pull latest. These endpoints don’t create, approve, close, or publish reviews.
Read a review in an approval workflow
Get the review ID from the approval context and call the public API withserval.apiRequest. It uses the workflow’s authenticated connection and existing retry handling.
Ask Catalyst to inspect a review
In a workspace for shared work, give Catalyst a review link, ID, or title and ask it to identify behavioral risks. The review-reading skill isn’t available in personal workspaces. Catalyst finds the review, reads its item pages, and fetches before/after documents in batches. It reports what it inspected, any unavailable content, and questions a human should resolve before approving. Review text and code are treated as untrusted content. Catalyst respects access restrictions and does not approve or publish the review. Continue in Reviews to make the human decision.Temporary comparison failures
If group permissions cannot be loaded because the authorization service is temporarily at capacity, wait a moment, then choose Retry comparison if it appears or reload the page. Contact support if the error continues. You do not need to edit your groups to retry this temporary service failure.Related
Catalyst overview
What Catalyst can do
Catalyst workspace
Get familiar with the Catalyst interface
Getting started
Open your first session and publish a change
Tutorial
Using Catalyst to analyze ServiceNow tickets and build automations
Building workflows
Natural language prompting, manual edits, versioning
Dashboards
Building analytics dashboards with Catalyst

