Digital Product Release Implementation & Configuration Guide

[gregholevas]

Digital Product Release Foundational Implementation & Configuration Guide

 

Contents

• Guide objectives & pre-requisites
  • Steps for demo Azure DevOps (ADO) Organization
• Setup/configuration steps:
  • Section 1: Define Approval Definitions
  • Section 2: Activate Release Policies
  • Section 3: Define a Release Template
  • Section 4: Create Release Readiness Targets
  • Section 5: Connect to external CI/CD tools (ADO)
  • Section 6: Manage a product and plan for a realse
  • Section 7: Create release and track progress
  • Section 8: Creating a change request

Guide objectives

You will achieve the following objectives:

• Review Digital Product Release Workspace
• Define release readiness target
• Define approval definitions, activate policies, and create a release template
• Configure product and plan for a release
• Create release and track release progress
• Create change request

Guide pre-requisites

Install the following plugins from the ServiceNow App Store:

• Digital Product Release (latest version)
• Digital Product Release Policy Content Pack (latest version)

In this guide, we walk through how to connect to an Azure DevOps Project to import in relevant product features for release planning. Other planning tool connection experiences should be similar. If you do not have a planning tool available to connect, you can follow the below steps to set up a free Azure DevOps (ADO) Organization with some demo data to see how the integration works.

Steps for demo Azure DevOps (ADO) Organization

First you’ll need to create a free Azure DevOps account with Parallelism. This will allow a limited amount of DevOps pipeline executions in the cloud.

1. If you don't have one, create a Microsoft account now.
2. Go to Azure DevOps and select Start free.
3. Enter your account credentials and go through the sign-up process.
4. Create an organization with any name you choose but make sure to use the correct name in the next step.
5. Request Free Parallelism for your Azure DevOps organization: Azure DevOps Parallelism Request Form and make sure the organization name matches exactly that which you created in step 4. It takes a day or two.

Next, install the PartsUnlimited Project into your Organization (do this for demo data)

1. Log into the Azure DevOps Demo Generator using the same Microsoft ID used to create the organization https://azuredevopsdemogenerator.azurewebsites.net
2. Click on Choose template, then Private. Upload a template archive from a URL Right click and copy the following and paste it into the URL field and click ‘Submit’: https://dev.azure.com/sndevopspov/af77a4da-9d9f-4b2f-b979-053dc65c62f1/_apis/git/repositories/14ea02...
3. Select the organization you created and provide a project name (we recommend starting with Parts Unlimited to make it easier to search for later). Click Create Project.
4. Log back into your Azure DevOps Organization and ensure the Project is created:  https://dev.azure.com/<your organization>
5. Sometimes the demo generator fails to import the workshop repo. Confirm that the Repo now has file in it by selecting the Repos tab on the left. If you see the message that your repo is empty “Add some code!”, click on the Import button. Select Repository type Git and use the URL and click ‘Import’: https://dev.azure.com/sndevopspov/workshop/_git/PartsUnlimited
6. Create a pipeline by clicking on the pipeline in the left tab of the project and select Create Pipeline
7. Select Azure Repos Git, then select PartsUnlimited.           
8. If parallelism is enabled for your organization, you should be able to run the first pipeline without error and click ‘run’. 

Next, install the ServiceNow DevOps Extension into your Azure DevOps Organization

1. Log into the Visual Studio Marketplace using the same Microsoft account as your Azure organization login
   https://marketplace.visualstudio.com
2. Search for “ServiceNow DevOps” under the Azure DevOps Tab
3. Click on “Get it free” and select your Organization.  If you are logged in with the same credentials used to create your Azure DevOps Organization or if you have permission to install Extensions, you should see an “Install Button”
4. Then click Install

That’s all to get this demo ADO organization ready to integrate with Digital Product Release.

Section 1: Define Approval Definitions

Role required: sn_dpr_model.release_admin, admin

Goal (~5 mins): Set up an approval definition

About this task: Release phases often require manual approvals from various stakeholders to qualify readiness for stage gates. The approvals can be required from an individual or a group, both of which can be either static or dynamic.

    Procedure:

1. Log in to your ServiceNow lab instance with a user account that has the sn_dpr_model.release_admin role
2. Navigate to Workspaces > Digital Product Release Workspaces OR All > Digital Product Release Workspace
3. On the home page, you’ll see a welcome message and a guided prompt setup to help release admins set up DPR. Click on Define approval definition in the guided setup promptsNote: You can also click on the Release Administration icon and select Approval definitions tab
4. You’ll be creating two new approval definitions. One dynamic approval definition seeking the Product Owner approval and the other a static group approval definition.
5. Let’s start with the Product Owner approval. Click on the New button to create a new Approval Definition.
   1. Give the approval definition a name describing who is providing the approval (e.g., Product Owner Approval)
   2. Set the Approver source as Digital Product and Approval action as User.
      1. Note: The ‘Approver source’ field defines the source of the approver details. If you set the ‘Approver source’ to ‘Approval Definition’, you’ll be able to pick a specific user or group and thus the approver(s) for this definition will be static. Selecting ‘Digital Product’ allows us to dot walk from the Digital Product record to look up the “who” should be the approver, thus making this a dynamic approver based on the record. Customers can extend the Digital Product table to add additional user fields (e.g., QE) that could be accessible.
   3. In the User field scroll down and select Product Owner
      1. Note: You can click the small arrow next to Product Owner and then scroll down in the next list and select Manager. This would select the manager of a product owner in the Digital Product record.
   4. Click Save to save the definition.
6. Next let’s create the approval definition for a group. Navigate back to Release Administration and click New button.
   1. Give the approval definition a name describing who is providing the approval (e.g., CAB (Change Advisory Board) Approval, AppDev Approval)
   2. Set the Approver source as Approval Definition and Approval action as Group
   3. Search for a relevant group to direct the approval decision toward (e.g. CAB Approval, Application Development)
   4. Leave Wait for as First Response
      1. Note: You can use the Wait for drop down to see other options for how to get necessary approvals from groups.                       
   5. Click Save to save the definition.
7. Navigate back to Release Administration and you should now see 2 different approval definitions. That’s it, let’s move on!

Section 2: Activate Release Policies

Role required: sn_dpr_model.release_admin, admin

Goal (~7 mins): Activate integration test pass policy with 80% threshold. Understand how to duplicate, modify, and publish release policies.

About this task: Policies help automate the release phase stage gates. In Washingon, DPR is launching with a policy content pack (Digital Product Release Policy Content Pack) that has 10 OOTB (Out of the Box) policies enabling customers to check for development related compliance using DevOps Data Model. We will activate one of the policies in this exercise.

      Procedure:

1. Navigate back to Home and click on Activate policies in the guided setup prompts
   1. Note: You can also click on the Policy Administration icon.
2. Go to All Policies and under ‘Inactive’ open the policy integration_test_pass_threshold
   1. Note: To maintain the integrity of the OOTB policies, users are unable to directly edit the policies shipped with the DPR Policy Content Pack. To activate a policy users must first create a copy of the desired policy
3. Click on the ellipses and select Duplicate
   1. Provide a name and select the version V1.0
   2. Click on Duplicate to create a copy of the policy
   3. The new policy will be created and you’ll be redirected to the new policy page

4. You should be on the Details tab. Update the Policy name to describe this new policy (e.g., integration_test_pass_threshold_80%).
5. Now, click on the Versions tab and open the version Draft-V1.0 and go to Policy Builder tab.
   1. Note: This policy is pre-configured to return “Compliant” if the integration test pass percentage is over a certain threshold. We only need to set the threshold value for the policy to work.
   2. Navigate to Config Parameters and click on minTestPassThreshold parameter
   3. Replace the Default value of 100 with 80
   4. Click on Save button within the modal
6. Click on Publish in the top right
   1. A modal will open, select Activate this policy and click on Publish to activate the policy

Section 3: Define a Release Template

Role required: sn_dpr_model.release_admin, admin

Goal (~10 mins): Define release process as a reusable template

About this task: Release managers define processes and guidelines that product teams must follow to ensure auditory requirements compliance. Release organization can standardize these processes in Digital Product Release using release templates.

Procedure:

1. Navigate back to Home and click on Create template in the guided setup promp
   1. Note: You can also click on the Release administration icon and Release templates tab
2. Click New button to get started with creating a template
3. In the Create release template modal, give a Name (e.g. Major Release, Minor Release), select Type and click Create
   1. Note: Currently, the Type field does not have a specific function. In the future we possibly see this field in assisting in categorizing for reporting.
4. In the template creation playbook, define the release phases you’d like to track in this template (e.g., Planning, Design, Development, UAT, Deployment) by providing the Phase name and Duration in days
   1. Note: You are only able to click + Add new phase after providing the name and duration for the previous phase
5. Select one of the phases as the Release readiness target phase
   1. The Release readiness target phase is the phase in which the release needs to be fully compliant/validated. This typically is the phase before the release is deployed.
6. When all phases, duration, and the release readiness target phase have been defined, click Mark as done
7. In the Tasks stage of the playbook, you’ll see a tab for each release phase you defined.
   1. For each phase, create tasks by providing the Task name. Some example tasks across the 5 phases shown above:
      1. Planning: Feature prioritization, scope validation, risk assessment, budget and resource allocation, market research and user analysis, technology stack selection
      2. Design: Architecture review, accessibility and usability testing, performance design verification, security design assessment
      3. Development: Design signoff for dev, peer review of source code
      4. Testing: Legal review, validate manual test results, documentation and training
      5. Deployment: Performance tests, validate rollback procedures, post-deployment smoke testing, post-launch evaluation
   2. For a task in the first phase, set Need approval to Yes and assign the Product Owner Approval definition available
      1. If using example tasks above, set scope validation and risk assessment as needing approval
   3. Click Next phase until you create template tasks for every phase. And when you’re done, click on Mark as done to assign policies.
8. In the Policies stage of the wizard, you'll have a tab for each phase like the Tasks stage.
   1. Click on + Map policies, select the policies you’d like to link to the phase and click Map policies again.
      1. We’ve activated one policy from the Policy Content Pack that is relevant to the development phase. For other phases you can map the policies for ‘All approval tasks are complete’ and ‘All phase tasks are complete’
      2. You’d need to activate additional policies before being able to associate them to phases in release templates.
   2. Click on Next phase until you map policies to each phase and click Mark as done when you’re done
9. A modal will prompt you to publish the template. Click Publish and the template is live. We’re done with the template!

Section 4: Create Release Readiness Targets

Role required: sn_dpr_model.release_admin, admin

Goal (~5 mins): Define the release readiness target date that product teams must align with to be ready for a release.

About this task: Enterprise release teams often look at planned maintenance windows and blackout windows to identify a set of dates in which product teams can execute/deploy their releases. The expectation is that product teams must be ready with their deliverables, release compliance validations, and approved change requests before a release readiness target date, or “go-no-go” date, so that the release can be executed seamlessly on the scheduled date.

Note: The “release readiness target” is a required field out of the box. However, for customers who don’t have fixed release dates (operate on a more flexible release cadence), customers can adjust the sn_dpr.out_of_band_release_allowed property to enable product teams to create releases with arbitrary release dates.

  Procedure:

1. Navigate back to Home and click on Create readiness target in the guided setup promp
   1. Note: You can also click on the Release readiness target calendar icon in the left navigation pane
2. Click on the Create action (top right corner) to initiate the release creation
3. Populate the Name field (e.g., Bi-weekly Thursday release)
4. The Release admin field will be populated with the logged in user. You can update it to the desired release manager.
5. Provide a Description as required
6. Set the Start date to the first release target date
7. For this example, check the Recurring flag
   1. Set Repeat to Weekly and Every 2 Weeks
   2. Select Thursday and set Ends on to be a date of your choice (by default goes out 1 year from Start date)
8. Click on Confirm
9. This will create a release target every other Thursday starting the Start date until the Ends on date. You will see this reflected on the calander view.

Section 5: Connect to external CI/CD tools (ADO)

Role required: sn_dpr_model.release_admin, admin

Goal (~7 mins): Integrate DPR with Azure DevOps

About this task: Organizations perform their release planning across a variety of planning tools (e.g., Jira, SPM, ADO). In DPR, we want to integrate with the planning tools products teams already use and import in the top-level features/epics to plan into product versions that will be released. In this step, we will use the DevOps tool integration playbook to connect to the ADO project you created as a part of the pre-work.

Also worth noting, many of the OOTB policies part of the DPR policy content pack require data from external CI/CD tools to check for development related compliance.

   Procedure:

1. Navigate back to Home and click on Connect a tool in the guided setup prompts
   1. Note: You can also click on the Tools icon
2. Log into your Azure DevOps project and have the URL handy: https://dev.azure.com/[your organization]/[your project name]

3. Back in Digital Product Release, click on Connect a tool to start the tool connection playbook (this can take a few moments to load)
   1. Within the Orchestration tab, select Azure DevOps
   2. In the first drop down, select ‘Connect a project’
   3. Copy and paste the URL of your ADO project and give the tool connection a name
   4. Click Next
4. In ADO, go to User settings (upper right next to your account icon) and click Personal access tokens
   1. Click + New Token
   2. Pick a name for your token and under Scopes allow for Full access
      1. Note: In practice, tool admins wouldn’t want to provide full access to users of DPR, but this simplifies defining the right permissions for this guide.
   3. Click Create and copy the token to your clipboard
5. Back in DPR, go to copy the ADO token in the ‘Password or access token’ field, leave Use MID Server unchecked, and click Connect
   1. This will start the tool connection playbook permission checks. If you allowed full access this check should be successful
   2. If successful, click Next
   3. Skip the ‘Specify tool access’ step
      1. Note: This is an optional step to restrict access to the tool
   4. Next, you’ll be asked if the ServiceNow DevOps extension has been installed in ADO – this was done as part of the prework. Assuming you did this step, click Mark as installed.
      1. If you didn’t do this step, review the last step of creating an ADO Organization in the prerequisites
   5. Next the playbook will prompt you to automatically configure webhooks in ADO to allow for real-time notifications and updates between ADO and ServiceNow. Click Configure and wait a minute or two.
   6. If all worked as expected, you’ll see completion summary
      1. Clicking View tool record will take you to see the details of the ADO project you just connected
6. ADO is now successfully connected. Let’s move on to the next step.
7. That completes the foundational setup experience for Digital Product Release. Next we’ll cover some usage examples of how a product manager or release coordinator would use DPR to plan and execute a release.

Section 6: Manage product and plan for a release

Role required: sn_dpr_model.product_manager

Goal (~7 mins): Create and configure a product and plan features in release

About this task: For a release to be planned, product teams need to finalize on the scope of work. The product manager is primary persona responsible for planning product scope and features into upcoming versions to be developed and released. In DPR, there we have a light-weight release planning KanBan board view for product managers to plan product features into upcoming versions.

Additional Info: As many organizations perform their product planning outside of ServiceNow, we’ve leveraged the DevOps data model to allow for integration with planning tools (e.g., Jira, ADO) so product managers can import in their relevant product features.

    Procedure:

1. Log in to your ServiceNow lab instance with a user account that has the sn_dpr_model.product_manager role
2. Navigate to Workspaces > Digital Product Release Workspaces OR All > Digital Product Release Workspace
3. Navigate to Products icon in the DPR workspace
4. Click on Request product, define the Product name (e.g., Parts Unlimited) and Short description in the modal and click Submit
   1. This will initiate a catalog request which, by default, will be auto approved to create the product. Click on refresh to display the new product.
   2. Note: We’ve built a catalog request flow for new product requests that by default auto approves. If a company wants to have more governance over the creation of new products, that catalog request can be changed to route to the proper approvers before the product is created.
5. Open the product you just created and navigate to External tools to configure the DevOps integrations.
6. In the Plans tab, click on Associate plans to associate a project
   1. Find the ADO project you created and click on Associate plans button
      1. Note: If needed, you can search for this project by clicking in the ellipses next to Name
7. In the next screen in the modal, select a start and end date and click on Import data. This will import work items from Azure DevOps and Product Features will be created for all top-level epics.
1. Note #1: This import will take a few minutes (~3-5 minutes)
2. Note #2: The start and end date look for when a feature/epic was last updated. If you recently cloned the ADO project per the prework, the default start and end dates should be sufficient to import in features. If you are using your own ADO project, check for update dates of your features
3. 
8. Navigate to Release planning to plan versions and scope product features.
   1. If you connected to an external tool and successfully imported in features (this will take a few minutes), you’ll see those top-level features/epics in the Backlog
   2. To begin planning those features into upcoming releases we need to create versions. Click on Request version and populate the Name, Version fields (e.g. Q2 2024 Release, V1.1) and click Submit to create the version.
      1. Create more than one version for your product. Example versions could be planned quarterly or monthly releases. The screenshot below we are looking at a quarterly release cadence.
      2. Note: Like requesting a new product, requesting a product version is done using a catalog request flow that by default auto approves. If a company wants to have more governance over creating new product versions, that catalog request can be changed to route to the proper approvers before the version is created.
   3. Users can manually add more features by clicking on Add Feature button and providing the Feature name and a description. Click Confirm to create the feature.
      1. By default, adding a feature adds it to the Backlog unless you select the version when creating the feature
      2. Note: We don’t expect most customers to manually create features in DPR. Most customers will likely integrate with their planning tool(s) of choice and those top-level Epics/features will show up in DPR. Product managers will still need to manually drag and drop those imported features to the right version.
   4. Plan features into the versions by dragging and dropping the cards in the board
9. And when you’re ready, you can create the release (next section).

Section 7: Create release and track progress

Role required: sn_dpr_model.product_manager

Goal (~10 mins): Create a release and track progress

About this task: Once the relevant product features are planned the upcoming version, product managers can create a release and begin tracking release execution. The version is a feature plan for a release not yet associated to specific timelines. Product managers will be able to associate the version to a timeline by mapping the version to the appropriate release template and release readiness target (“go-no-go” date). The release start date will be calculated using the release target date and duration of the phases defined in the template.

   Procedure:

1. Navigate to the Releases section in the DPR workspace
2. Click on New to create a release
3. Provide a Release name (Parts Unlimited Q2 Release), pick a Product (Parts Unlimited), Version (V1.0), Release template (Major Release Template), and Release readiness target (aim for a date in Q2) and click on Confirm. All the fields are required.
   1. Note: You can search for a suitable release readiness target by typing “YYYY-Month”.

   2. You can also create the release from the Release planning Kanban board as shown below and when you do that, Product and Version will be pre-populated.

4. The release will be created and the user will be redirected to the newly created release. The dashboard provides a snapshot of the overall release progress.
5. The release will start automatically on the Release start date with a schedule job.
   1. If you want to start the release earlier, you can do so by clicking on the ellipses and clicking on Start release. Do this for this guide. This will keep the same Release Readiness Target and accommodate by increasing the duration of the very first phase in the release.
6. When you start the release, the first phase of the release is started automatically and all approvals for the phases are requested.
   1. Note: DPR is leveraging the standard ServiceNow notification system. Notifications can be configured based to modify how approvers are notified.
7. As a Product Manager, there are three ways to view tasks requiring your approval:
   1. The first is by natigating to the Home page and looking under Approval tasks. You can click View all to expand. Clicking into tasks allows you to approve and this will automatically mark the Approval task as completed.
   2. The second is via the release Dashboard page, by scrolling to the bottom of the dashboard page you’ll see an Approvals section. Clicking into tasks allows you to approve and this will automatically mark the Approval task as completed.
   3. The third method is via the Release execution page. On this page you’ll need to click into the phase of interest and the Tasks tab to see open tasks. Clicking into a task will allow you to approve and this will automatically move the task to Closed Complete.
      1.      Note: If you don’t see all the tasks you expect, confirm that the default filtering is not hiding a subset of tasks.
8. Non-approval release tasks can be updated as the release work is progressing on the Release execution tab in the Kanban board or list view  
9. You can also check for stage gate compliance by navigating to the policies tab under Planning. The policies are run every hour with a schedule job. Click on Run policies button in the upper right of the workspace to execute the policies.
10. The phase will automatically close when two conditions are met: 1) all policies are compliant and 2) the phase end date has been reached. The next phase in the release will start automatically once the prior phase is complete.

Section 8: Creating a change request

Role required: sn_dpr_model.product_manager

Goal (~5 mins): Create a change request for the release and request approval

About this task: After development work is complete and the team is ready to seek authorization to push the new code to production, they can raise a change request from within the DPR workspace and submit it for approval. If a customer is leveraging DevOps Change Velocity, they can also raise the change request from their pipeline and associate it with the release, this however is not in scope of this document.

Procedure:

1. Navigate to the Releases section in the DPR workspace
2. Open the release you created in the previous step and navigate to the Change requests section in the secondary navigation as shown below
3. Click on the New button to create a change request. This will bring you to the same change experience as found in Service Operations Workspace.
   1. Note: If using DevOps Change Velocity, change requests can be automatically created via pipeline executions. This is a more advanced use case not covered in this guide.
4. Select the type of change request and fill in the necessary information and request for approval
   1. Note: You can submit multiple change requests for the same release. Often change requests are submitted whenever code is moved from one environment to another. Additionally, if a product is being deployed to multiple locations you may require multiple change requests.
5. When all change requests are approved, the release is approved to be deployed to production and the release can be marked as complete.
6. This is the last step in this guide