Get Started With Update Set Automations in Yokohama - Astrid on ALM

• 2025-02-9
• 11-minute read

Table of Contents

About this post

This is the first in a series of articles, Astrid on ALM, discussing application lifecycle management in ServiceNow. This article discusses the new Update Set automations introduced in the Yokohama release, and provides a guide to setting up and using the new retrieve actions to move your update sets between instances. Further articles will:

• Take a deep dive into all the new Update Set functionality introduced in Yokohama,
• Guide you through setting up remote tables to complement the new Update Set capabilities,
• Guide you through setting up a full CI/CD pipeline with Update Sets, Instance Scan, ATF to move code from Development to Test to Production,
• Discuss different deployment approaches (App Repo, Source Control, and Update Sets), and designing with these in mind,
• and more!

Ready, Update Set, Go!

Update Sets. They are the most popular and well-known method of collecting configuration changes to move between instances in ServiceNow. Whether you are a junior admin, a seasoned developer, a product owner, or a platform owner, you will be familiar with the use of update sets, as well as some of their limitations. One of the biggest pain points experienced with Update Sets is the manual nature of their management and movement through instances, resulting in measurable productivity losses for developers and admins. With the Yokohama release, ServiceNow has introduced Update Set activities and support to the Continuous Integration and Continuous Delivery (CI/CD) Spoke and API. I will refer to both technologies as CICD Activites throughout this post for brevity. These new tools allow customers to regain productivity while streamlining and standardising their migrations and releases, and improving the developer experience!

Before I walk through the steps to set up this capability, I’d like to provide some insight to a real life example of the opportunity and value the new activities present.

Throw me a lifeline pipeline

One day, on a flight from Brisbane to Sydney, a platform owner asked how we could solve challenges in configuration testing and deployment across the instance stack. Code migration and releases were becoming troublesome, time-consuming, and rife with human error. She wanted an evidence-based process that minimised the effort the development team had to spend on this, and allow them to instead focus on delivering high value work. On that flight, I laid out a CI/CD pipeline the organisation could use, taking advantage of ServiceNow’s Static Code Analysis tool, Instance Scan, Automated Testing, Code Review, and Test Management.

There was a problem though. This organisation would need to migrate to Source Control or App Repo for some of the proposed automations. While these technologies had definite benefits, they also held drawbacks and represented a paradigm shift in how apps are designed and their configurations are moved. Fast forward to today: that same pipeline can be made real with Update Sets, allowing the full gamut of customers to get real value from CI/CD automation!

Now, let’s discuss how to approach CICD Activities, and then tackle our first challenge: moving update sets between ServiceNow instances - without having to retrieve or import by hand!

Understanding CICD Activities

To be successful with the CICD Activities, it is important to consider how they work. I suggest thinking of this in a mental model like the below:

• The CICD Activities use a point-to-point integration between source and target environments
• The source environment (ServiceNow instance or CI/CD platform) is where you trigger CICD Activities from
• The target environment of a CI/CD spoke action or API call will always be the instance where any activities are performed

This model is important to remember for the CICD Activities that retrieve update sets. These activities will also run against our target instance. As such, this will be the instance that update sets are retrieved to, not the instance they are being retrieved from. This is reflected in the below diagram.

Got that? Then lets go!

How to set up and automate Update Set movement between instances

1. Configuring connections

Role required for connection accounts:

• Update Source: admin
• CICD Spoke: sn_cicd.sys_ci_automation (recommended), or admin

Retrieving Update Sets through CICD Activities requires the configuration of an Update Source. If you are using ServiceNow to trigger this action, then you also need to configure credentials for the CI/CD Spoke. I recommend creating service accounts to ensure you have a dedicated user for each of these functions.

Steps: Creating an Update Source

1. In the instance you wish to retrieve Update Sets from, create a sys_user record. Set a descriptive name and User ID indicating the intent of this user profile, and indicating it is a service account. As it is not going to need to be interactive, set the Web Service Access Only checkbox to true/marked. Make sure to generate a strong password for this source and keep it for reference in a secure repository like a password locker.
2. Edit the roles provided to the user you just created, and provide it with the admin role.
3. In your target instance, where you will retrieve Update Sets to, navigate to Update Sources from the All menu/filter navigator. Click the New UI Action.
4. Populate the new record with a descriptive name, the instance URL, the Active checkbox set to true/marked, setting the most appropriate type (note: this does not have any functional impact). Populate the username and password with the details created in 1.
5. Click Test Connection. This must return as successful for you to save, so double check the details you provided if you do not get a positive result. Click Submit to save the record.

Important: Once you have created the Update Source, you need to copy and note its Sys ID value for use in our next steps. Alternatively, you can view the XML of this record and instead note the Instance ID value. You may choose to surface this field on the form or list view, if desired. You will be using one of these values to trigger the Update Set retrieval.

Once created, your Update Source and User records will resemble the following:

Steps: Creating a CI/CD-capable account

1. In the target instance for your CICD Activities, create a sys_user record. Set a descriptive name and User ID indicating the intent of this user profile, and indicating it is a service account. As it is not going to need to be interactive, set the Web Service Access Only checkbox to true/marked. Make sure to generate a strong password for this source and keep it for reference in a secure repository like a password locker.
2. Edit the roles provided to the user you just created, and provide it with the sn_cicd.sys_ci_automation role.

Once created, your user record will resemble the following:

Steps: Configure the Continuous Integration and Continuous Delivery (CI/CD) Spoke Basic Authentication Credential (Optional)

Note: Follow these steps when your source environment is a ServiceNow instance. For brevity, this guide includes the Basic Authentication steps. You may instead opt to create an OAuth 2.0 configuration to perform this authentication.

1. In your source instance, navigate to Connections & Credentials -> Credentials from the All menu/filter navigator. Click the New UI Action.
2. On the resulting Wizard page, select Basic Auth Credentials
3. Populate the new record with a descriptive name, an order value (100 is fine), and the Active checkbox set to true/marked. Populate the username and password with the details created in the previous set of steps. Set the Credential Alias to be the CICD record. Click Submit to save the record.

Once created, your Credential record will resemble the following:

2. Leveraging CICD Activities

CICD Activities involved:

• Retrieve Update Set with Instance ID (Flow Action and Subflow)
• Retrieve Update Set With Update Set Source ID (Flow Action and Subflow)
• Retrieve and Auto Preview Multiple Update Sets (Subflow)
• POST /sn_cicd/update_set/retrieve (API)

Steps: Using the Retrieve Subflows and Actions

Note: This example will use the Retrieve Update Set with Instance ID action. The other actions and subflows behaviour very similarly, changing and/or reducing the number of available inputs.

1. Open Workflow Studio and navigate to the Retrieve Uodate Set with Instance ID action. Open this Action and click the Test button.
2. In the resulting model, populate the following properties:
   • Instance URL (mandatory): The URL of the target environment of your CICD Activities.
   • Credential Alias _(mandatory)_: The Connection & Credential Alias record you have configured with a credential. This will be sn_cicd.CICD` if configured per above steps. Alternative records can be created and used.
   • Instance Id (mandatory*): The value of the Instance ID field on the Update Source you will use to retrieve the update set, from your target environment.
   • Update Set Id (mandatory): The Sys ID of the Update Set you want to retrieve, from your Update Source’s target instance.
   • Auto Preview (optional): The boolean value indicating whether you want the update set to be previewed
   • Clean Up Retrieved (optional - recommended): The boolean value indicating whether any prior retrieved instances of this update set in your target environment should be deleted.
   • API version (optional): The pinned version of the API you would like to use. This should be set to v1 or blank at this point in time.
3. Trigger the test of this action, and open the resulting execution record. Observe the successful result. Check your target environment for retrieved update sets, and note your new update set is available!

Congratulations! You have now moved your first update set via automation using the new actions!

Steps: Using the Retrieve API

Note: This example will use Postman. GitHub Actions, GitLab Jobs, and Azure DevOps Tasks (amongst other tooling) will be able to leverage the same through HTTP/REST-capable objects

1. Using the guide from my prior article, set up an OAuth Entity for Client Credential authentication, using your CI/CD-capable account from the steps above
2. Open Postman, and create a new request. This is a POST request, calling https://{{yourTargetEnvironmentUrl}}/api/sn_cicd/update_set/retrieve, where {{yourTargetEnvironmentUrl}} refers to the target environment of your CICD Activities.
3. Use the OAuth 2.0 details from step 1 to retrieve a Bearer token you can use for API calls
4. Add 5 query parameters:
   • update_set_id (mandatory): The Sys ID of the Update Set you want to retrieve, from your Update Source’s target instance.
   • update_source_id (mandatory*): The Sys ID of the Update Source you will use to retrieve the update set, from your target environment. When this value is set, update_source_instance_id is not required.
   • update_source_instance_id (mandatory*): The value of the Instance ID field on the Update Source you will use to retrieve the update set, from your target environment. When this value is set, update_source_id is not required.
   • auto_preview (optional): The boolean value indicating whether you want the update set to be previewed
   • cleanup_retrieved (optional - recommended): The boolean value indicating whether any prior retrieved instances of this update set in your target environment should be deleted.
5. Populate either Update Source ID or Update Source Instance ID with the Sys IDs you have retained from above. Both values can be populated without issue, but this is not necessary. Populate the Update Set ID with a desired update set from your instance you wish to retrieve update sets from.
6. Send this API query. Note that a payload will be returned indicating the retrieval job has been started. Check your target environment for retrieved update sets, and note your new update set is available.

Your resulting Postman configuration and API response will resemble the following:

Congratulations! You have now moved your first (or second) update set via automation using the new API!

First Impressions

I really appreciate the introduction of these capabilities to the platform, and they work well. The use of Update Sources does limit this component of the process to Basic Authentication, but I appreciate the use of platform-level capability. The documentation ServiceNow has published directs users to use Basic Authentication for the Spoke, but testing has validated that OAuth 2.0 is able to be used. This indicates that other authentication methods should be successful as well, allowing teams to leverage the appropriate authentication method(s) required for their security posture.

Alongside Update Sources, I hope we see support for Pipeline and Deployment environments in upcoming store and platform releases for customers taking advantage of these applications, and that we see some investment in alternative authentication solutions if this approach continues to use Update Sources.

One gap that users need to address is record update activities and particularly query activities, in order to retrieve Sys IDs for Update Sets from another instance. This is a great opportunity to use a Remote Table, and to take advantage of Yokohama’s new Remote Table capabilities for record updates.

With the Spoke support, I am excited to see organisations start automating their SDLC processes, and even production releases!

Closing Notes

I hope this article gives you the tools to get started building your update set automations and control towers. Please share your experiences with this process with me, I am excited to see what you do with this capability!

Thank you for reading, and I hope you enjoyed/found value in this article. As always, I am open to feedback and can be reached via Slack, LinkedIn, or email.

Posts in this series

• Get Started With Update Set Automations in Yokohama - Astrid on ALM