This article was originaly published in 2017.08.31
Orchestrating Deployments with ServiceNow Using IBM UrbanCode Deploy
ServiceNow is a cloud-based IT Service Management (ITSM) platform. ITSM software allows users to consolidate fragmented and legacy systems into a single configurable and scalable solution to business needs. IBM UrbanCode has supported integration with the ServiceNow platform since the early days of the tool. In the initial release of the UrbanCode Deploy (UCD) Automation plug-in, the older and grungier ServiceNow SOAP API contained steps to insert, delete, update, and check changes in the ServiceNow Dublin release. With the release of Eureka, ServiceNow introduced a newer or more versatile REST API for integration purposes. IBM UrbanCode has invested heavily in ServiceNow integration since then. With the ServiceNow release of Jakarta in 2017, specific integrations exist for both UrbanCode Deploy and UrbanCode Release (UPDATE: IBM UrbanCode Velocity provides also integration into ServiceNow, the screenshots taken here are from IBM UrbanCode Velocity), as well as a built-in orchestrating mechanism within the Bluemix Continuous Release service. This blog will go into details and examples of how to orchestrate deployments from ServiceNow by invoking outbound UCD REST services, as well as how to configure UCD to call back to ServiceNow to update changes, incidents, tasks, or other ServiceNow table records. The product versions used in the screenshots below are ServiceNow Jakarta Release and IBM UrbanCode Deploy 6.2.5.
Contents
Getting Started
Compatibility
The following software products and versions are required for running the ServiceNow plug-in on an IBM UrbanCode Deploy server:
- IBM UrbanCode Deploy 6.0 or later
- ServiceNow Eureka Release and later
Creating an Outbound Integration with UrbanCode Deploy
ServiceNow must be setup to contain the custom fields, REST messages and business processes in order to interact with UCD. In this example, we will show how to configure Change Requests to contain the necessary UCD fields, the REST Message to kick off deployments on the UCD Server, and the Business Rule specifying what changes will trigger the action.
Configuring ServiceNow
Work Items In order to start creating an outbound integration for UCD, it's best to have our work item types configured to contain the necessary UCD fields which they will reference. This can be done on the work item page configuration. For this entire example, we will work with Change Requests. After opening a Change Request, select Settings box -> Configure -> Form Layout. Here, we see the following window where we can create new fields for our work items.
In this case, we create a field for Application, Environment, and Version, because our Change Requests will be specifically tied to versions. These fields may vary, depending how your instance of ServiceNow is associated with the versions and artifacts you are deploying. Components, Processes, and other UCD fields can be specified here as well. REST Message A REST Message can now be configured to reference the properties in the work items we created above, which will be passed to the UCD Server REST API. To create a REST Message, we select on the ServiceNow panel, System Web Services -> Outbound -> REST Message. In this case, we will call the message 'Start UCD Application'.
Within the REST Message, we reference the requestApplicationProcess CLI command in order to trigger a deployment through the UCD REST API. We can use the JSON template to specify whichever parameters we would like to run. Here is the example we use in this case.
In order to reference these variables, we can select 'Auto-generate variables' under 'Related Links', which will create them in the below table, as shown here.
Business Rule Now that our Change Requests are configured to contain the UCD parameters, and a REST Message is created on our ServiceNow instance, we can create a Business Rule to define when this command is triggered. Business Rules can be found in the panel under System Definition -> Business Rules. In this case, we named it 'Start Deployment after Scheduling', and linked it to the Change Request table.
The Business Rule we will use in this case will start a deployment for a Change Request whenever the state of the change request is set to 'Scheduled'. To do this, we create the following conditions on the Business Rule configuration.
It's important that we set the 'Active' checkbox in order for the rule to occur when triggered, as well as select the boxes specifying what ServiceNow triggers we want to start the process. In this case, insert and update are selected. We must also select 'Advanced' in order to specify a custom script to call the REST Message we previously created. Now, under the advanced tab, we will see a field to enter our script. This script can be generated from the REST Message page, under Related Links, by selecting 'Preview Script Usage'. For our case, here is the example which was generated and will be used.
Here is the text version of the code:
(function executeRule(current, previous /null when async/)
{ try
{ var r = new sn_ws.RESTMessageV2('Start UCD Application', 'Request Process');
r.setStringParameterNoEscape('ucd_environment', current.u_ucd_environment);
r.setStringParameterNoEscape('ucd_version', current.u_ucd_version);
r.setStringParameterNoEscape('ucd_application', current.u_ucd_application);
r.setStringParameterNoEscape('change_number', current.number);
var response = r.execute();
var responseBody = response.getBody();
var httpStatus = response.getStatusCode();
}
catch(ex)
{ var message = ex.getMessage();
}
})(current, previous);
At this point, we have configured ServiceNow with all of the necessary functions to perform UCD deployments simply by changing Change Requests. The next section will show an example of such a scenario.
Trigger Deployments
For this example deployment, we have an Web Application titled JKE-Banking. We will create a Change Request which is linked to a specific version of our jke.war component on UCD. When we set the state of the Change Request to Scheduled, the UCD values will be passed through to our Business Rule script and REST Message, and we will see that this version of jke.war gets deployed to our specified DEV environment.
After setting the state to Scheduled, we can jump over to our UCD Server, and navigate to our 'JKE-Banking' Application. Selecting the 'History' tab, we see the following deployment is running, which was triggered directly by ServiceNow.
Using the Automation Plug-in
The ServiceNow Automation plug-in is the key to orchestrating changes to ServiceNow throughout the deployment process. In the previous example, we showed how ServiceNow can be configured to trigger deployments and pass the necessary parameters to UrbanCode Deploy. In this example, we will show how the deployment process can be configured to send updates back to the ServiceNow work item, including checks and updates to to the relevant items.
Installing
Once you have downloaded the plug-in from the download page, it can be installed on UCD through Settings -> Automation Plugins -> Load Plugin.
Steps
The ServiceNow Plug-in offers the following steps to be executed on the ServiceNow platform.
Example Verification and Deployment Process
In this example deployment, we will go through the steps necessary to deploy the jke.war component mentioned before. The application, processes, and workflows documented here are designed to be called by the ServiceNow process presented above. First, we will assume that we already have a deployable Application, which is tied to the necessary resources and components. In this case, they are the application, 'JKE-Banking', with an environment, 'DEV', component, 'jke.war', version '1.969', and process, 'Deploy', with a local agent resource. From this starting point, we will create two generic processes for interacting with ServiceNow. One will be for checking the values on a given Change Request, and one for updating the state, which will be done after deployment succeeds. Notice that these steps are designated specifically for Change Requests within ServiceNow. It is also possible to check any values of an Incident, Change Task, or other table type using the 'Check Records' step, and defining which table and fields will be checked. These Change Request steps are specifically defined simply because they are the most common checks to be made in typical DevOps pipelines which incorporate ServiceNow. The first generic process will contain four steps, one for checking a different aspect of the change request to ensure that it is ready for deployment. These aspects are in this example:
- The deployment falls within the start and end date of the request.
- The approval status is set to 'Approved'.
- The state is set to 'Scheduled'.
- All child change tasks associated with the change request are closed.
The process workflow will look something like this:
Diving deeper into the configuration, we can see that we are referencing properties associated with our ServiceNow designated resource within the plugin step. These are defined under the 'Resources' tab. All of the steps shown above will look similar to these, with the whatever values we are looking to check against.
Also notice that the Change Request Number has been specified with a property, '${p:SN_Change}. This property is passed from ServiceNow in our REST Message from earlier, and must be defined both on our Application Process, and our Generic Processes. This can be done under the configuration tab of these processes, as shown below.
The second generic process we will create will be to close our ServiceNow ticket after deployment. Similar to the checking process, we will utilize the ServiceNow properties defined on our resource. Each of these steps is a different implementation of the plugin step, 'Update Records'. We must use three steps to iterate through the closing of our Change Request. This is because ServiceNow requires a sequential changing of state, rather than jumping from one state to another. For example, the ServiceNow API does not allow a Change Request to immediately go from 'Scheduled' to 'Closed' without first being set to 'Implement' and 'Review'. The steps for this process in this case are as follows:
- Set the state to 'Implement'
- Set the state to 'Review'
- Set the state to 'Closed'
Here is an example of the process workflow:
During each update of the Change Request, we can set other field values as well, such as comments or notes. The following shows the example configuration for the 'Set to Closed' step, where we specify the 'Close Code' and 'Close Notes' in addition to the updated 'State'.
Now that we have defined our generic ServiceNow processes, including all necessary fields and properties, we can update our Application Process to call these processes. This can simply by done by adding 'Run Generic Process' before and after the 'Install Component' step, where we are running the Deployment of 'jke.war'. The following shows the resulting Application Process workflow:
If we have properly defined the 'SN_Change' property on both the Application Process and the Generic Processes, we should see this in the parameters for the 'Run Generic Process' step, as shown below.
Deployment Verification
This concludes the configuration for our ServiceNow integration with UrbanCode Deploy. Now, we can set a Change Request within ServiceNow to 'Scheduled', and the integration will provide the end-to-end solution for deploying our application. To test the configuration, perform the following steps:
1. In ServiceNow, set the state of a configured Change Request to 'Scheduled'.
2. In UCD, check that the appropriate process has kicked off.
3. Wait for the process to succeed and check the status of the steps.
4. Check that the designed Change Request in ServiceNow has been updated and closed.
This concludes this post discussing the integration between ServiceNow and IBM UrbanCode Deploy. Please contact IBM Support for any use case issues. Thank you for reading.
#UrbanCodeDeploy#ServiceNow