Plug-in Documentation

ServiceNow

Overview

ServiceNow supports application delivery by integrating service management processes, social collaboration for IT departments, software-as-a-service delivery, and web functionality.

The ServiceNow plug-in includes steps that check approvals and set the status of change requests.

To add the ServiceNow plug-in steps to processes, click ITSM Process > ServiceNow in the step palette of the process editor.

Compatibility

This plug-in requires version 6.0 or later of IBM UrbanCode Deploy.

This plug-in works with the Eureka release of ServiceNow and later.

Interface

This plug-in integrates with ServiceNow by using version 1 of the ServiceNow REST API. The plug-in requires that the user account has access to the REST API and to the relevant tables.

Installation

No special steps are required for installation. See Installing plug-ins in IBM UrbanCode Deploy.

History

Version 28

RFE 122276: Add property to each step to allow invalid SSL certs.

Version 27

RFE 116821 Added the ability to specify custom date fields in the Check Deployment Window step.

Version 26

Added URL output property to create, check, and update records steps.

Version 25

Fixes APAR PI90696 Added apache commons lang3 dependency for proxy issue.

Version 24

Updated Check Deployment Window to compare times in UTC before converting to local system time.

Version 23

  • Fix APAR PI87057 Set Task Status to accept Task Number instead of SysId.
  • Updated Check Change Requests Child Tasks States to accept multiple states.

Version 22

Fix generic CRUD steps to work correctly for all tables, other than change_request. Minor naming and documentation updates.

Version 21

Version 21 of the plug-in now supports the following features:

  • RFE 105985: Steps now use Record Number instead of sys_id.
  • Step names now more consistent with Service Now field values.
  • New step for checking if time falls within deployment window.
  • Plug-in no longer supports Service Now Dublin release.

Version 20

Fixes APAR PI83136. Improved plug-in error logging.

Version 19

Update check specific methods to accept release names: Geneva, Helsinki, and Istanbul.

Version 18

Added Check Change Request Fields step.

Version 17

Fixed bug when checking for fields and value equality in Check Records step.

Version 16

Improved error logging and various bug fixes.

Version 15

Support property file encryption.

Version 14

Deprecated steps are no longer deprecated.

Version 13

This version supports full record create, read, update and delete (CRUD) operations as well as query operations. Steps and properties were renamed for clarity and consistency. The following steps were added:

  • Check Records
  • Query Records
  • Update Records

The following steps are deprecated:

  • Check Approval Status
  • Check Change Request Status
  • Check Change Requests Child Tasks Statuses
  • Delete Multiple Table Records
  • Set Change Request Status
  • Update Tasks Statuses

Version 11

This version uses manual API checking. This version also enforces tighter passing constraints to protect against false positives in some scenarios.

Version 10

This version includes a fix for a defect related to the ServiceNow REST API in the Eureka and Fuji releases. This version of the plug-in automatically checks the ServiceNow API version.

Usage

Configuring Service Now to Trigger Deployments in UCD

Service Now can be configured so that making a change to a Change Request, Incident, or any other table can kick off a deployment in UrbanCode Deploy automatically. This can be done by the following steps:

1. Under System Web Services -> Outbound -> REST Message, Create a new REST Message for calling your UCD Application Process.

Screenshot showing a new outbound UCD REST Message Object

2. Name the message, and set up the Endpoint field to direct to your UrbanCode Deploy server, using the proper path for requesting an Application Process. This can also be used with any other UCD REST Endpoint if desired.

3. Create a New HTTP Method. Define the parameters based on the UrbanCode Deploy CLI References for your rest call. For this case of requesting an application process, the HTTP Method will look something like this using requestApplicationProcess template:

Example HTTP Method for Requesting Application Process

4. Now that we have our Outbound REST Message, we need to configure a Business Rule. In the side panel, under System Definition -> Business Rules. Here we can configure a table that we want to trigger the REST Call from, as well as the conditions to do so. This depends on user preferences. For this case, the following parameters are set to trigger a deployment when a Change Request table has its approval status set to Approved.

Business Rule for Deployment to UCD

5. To reference the REST Message within the Business Rule, ensure that the Advanced box is checked. Now, under the Advanced tab, a Script box can be seen. To retrieve the script required to call our REST Message, we must return to our Http Method, scroll down to Related Links, and select Preview Script Usage. From here, we copy and paste the script as is, and paste it over the // Add your code here text.

6. Now our settings are complete. We can go into a Change Request item, change its approval status to Approved using the proper roles, and we can see that our REST call was made and our Deployment started in UrbanCode Deploy.

Example: Check the status of a Change Request

Note: For checking records in the change_request table, this process was combined into one step in Version 18 of the ServiceNow plug-in, in the step Check Change Request Fields.

  1. Open the change record that contains the child change tasks to check.
  2. Right-click the child task to check, and then click Show Matching.
  3. Copy the query. Right-click the end of the query and then select Copy Query.
  4. In the process editor, add a Run Encoded Query step.
  5. Paste the query into the step.
  6. Add a Check Records step.
  7. Enter {p:EncodedQueryStepName/recordSystemIDs} in the Record System IDs field.
  8. For Check Fields, enter status=1.

The final process design should look like this:

Note: The status value in the last step is an integer key that corresponds to the state value-key pair that is used by ServiceNow. By default, -5 is Pending, 1 is Open, 2 is Work in Progress, 3 is Closed Complete, 4 is Closed Incomplete, and 7 is Closed Skipped. To find your specific key-value pairs, open a task in ServiceNow. Click Additional actions next to the task title, then click Configure > Form Design. Click edit this field, which is displayed when you select the state field.

Component and Agent Configuration

Defining the ServiceNow plug-in as a separate component to interface your ServiceNow environment allows you to reuse the ServiceNow steps in other processes. You can map components to an agent or agent pool that has access to the ServiceNow environment.

  • Agent pools distribute work among all pool members and reduce congestion that can occur when using a single agent.
  • Agent pools are also used to limit access to specific agents. For example, agents that are associated with a different owner or agents used for production deployment.

Additional information on agent pools can be found on the Creating and managing agent pools topic in the Knowledge Center.

We will use the JPetStore Application in the graphic below to demonstrate the use of the ServiceNow agent pool in a deployment. The JPetStore Application example represents a project deployment strategy with three environments. The environments are shown on the Applications tab: Dev, QA, and Prod. The Components tab contains the various deployable items and concepts, that make up the application. In this example, it contains the ServiceNow component. The Processes tab contains deployment flows, when combined with the other component processes used to make dynamic decisions based on ServiceNow queried responses.

jpetstoreapp

The Resource Tree tab shows a typical design for an agent pool. Notice the high-level folder called ServiceNow Agents. The folder contains three agent pools: Dev Pool, Prod Pool and QA Pool. Agents are assign to a pool and configured for the environment.

resourcetree-1024x255

The Environments page for a specific environment displays the agent pools associated with the environment. As shown in the graphic below, the agent pool named Dev Pool is mapped to the Dev environment. With this configuration, the application process runs only on the available agents in the Dev Pool agent pool associated with the environment.

sampleenvironment

Troubleshooting

You can use HTTP status codes to troubleshoot issues when using the plug-in. Status codes are displayed in the console. For more information on status codes, see the REST API topic in the ServiceNow documentation.

ServiceNow Administrators

  1. Ensure that you have REST access in ServiceNow. If you do not have REST access, complete the following steps:
    1. Click User Administration > Users.
    2. Click your user record. The user record opens.
    3. In the Roles related list, click Edit.
    4. Select rest_service.
    5. Click Add.
    6. Click Save.
  2. Ensure that the user account has table access. To learn more about table access, see the REST API topic in the ServiceNow documentation.

IBM UrbanCode Deploy Administrators

  1. Test using the REST API Explorer.
    1. Click System Web Services > REST API Explorer.
    2. Select Table API from the drop-down list.
    3. Under Table API, select v1 from the drop-down list.
    4. Under v1, click Retrieve Records from a table (GET).
    5. In the Prepare request section, configure the following fields.
      1. In the Request Format list, select JSON.
      2. In the Response Format list, select JSON.
      3. In the Authorization list, select Send as another user.
      4. In the User Name field under Basic Authorization, type your user name.
      5. In the Password field under Basic Authorization, type your password.
      6. In the tableName list, select change_request.
    6. Click Change > All.
    7. Ensure that there is at least one change request. If there is not a change request, take the following steps:
      1. Click Change > Create new.
      2. Click Submit.
      3. Close the page.
    8. Click Send.
    9. The Request and Response sections are displayed. Record the URL and header information in the Request section. You will need use the URL and header information in the following troubleshooting steps.
    10. If the Status code is not 200 OK, the test was unsuccessful. If the test did not succeed, doublecheck the previous steps and run the test again. If the test fails a second time, continue on to the second test.
    11. Leave the page with the Request and Response sections open.
  2. Test using the curl command. If this test works, then the plug-in should work.
      1. Open a text editor and type your username and password in the following format: username:password
      2. Save the file without a file extension.
      3. Use the following openssl command to encode the file in Base64 format:
        openssl enc -base64 -in full_path_of_the_text_file -out full_path_of_new_encoded_file
      4. Open the encoded file in a text editor and remove any newline characters, so that the text is continuous.
      5. Create a new process with a Shell step.
      6. Use the curl command to create a request similar to the following example. Use the URL and headers from the previous test.

    curl URL_from_previous_test --header "Accept:application/json" --request GET --header "Content-Type :application/json " --header "Authorization: Base Base64_encoded_username:password_text"

    1. Optionally, to add a proxy, add the argument --proxy [protocol://][user:password@]proxyhost[:port] to the end of the curl command.
    2. Save the process, and then run the process using the same resource and agent that the ServiceNow step uses.

Steps

Process steps in the ServiceNow plug-in

Check Change Request Approval

Check that the Approval field of a record.

Input properties for the Check Change Request Approval step
Name Type Description Required
Approval String The Change Requests Approval field value you are checking against (approved, rejected,
requested, not yet requested).
Yes
Change Request Number String The value of the Number field for the relevant Change Request. Yes
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. No
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. No

Check Change Request State

Check that the State field of a change record.

Input properties for the Check Change Request State step
Name Type Description Required
Change Request Number String The value of the Number field for the relevant Change Request. Yes
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. No
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
State integer String The state you want to ensure the Change Request has. This is an integer key corresponding
to the state value-key pair used by ServiceNow. By default -5 is Pending, 1 is Open,
2 is Work in Progress, 3 is Closed Complete, 4 is Closed Incomplete, and 7 is Closed
Skipped. You can find your particular key-value pairs by opening a task in ServiceNow,
clicking on Additional actions button by the title, Configure->Form Design,
and then clicking the edit this field settings button that appears when selecting
the state field.
Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. No

Check Change Requests Child Tasks States

Check the states of the tasks related to a given Change Request.

Input properties for the Check Change Requests Child Tasks States step
Name Type Description Required
Change Request Number String The value of the Number field for the relevant Change Request. Yes
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. No
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
State integer String The state you want to ensure that the children Change Tasks of the Change Request
request have. To specify multiple acceptable states, use a comma , delimited list.
This is an integer key corresponding to the state value-key pair used by ServiceNow.
By default -5 is Pending, 1 is Open, 2 is Work in Progress, 3 is Closed Complete,
4 is Closed Incomplete, and 7 is Closed Skipped. You can find your particular key-value
pairs by opening a task in ServiceNow, clicking on Additional actions button by
the title, Configure->Form Design, and then clicking the edit this field settings
button that appears when selecting the state field.
Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. No

Check Deployment Window

Check that the current time falls within the start and end date of the change request.

Input properties for the Check Deployment Window step
Name Type Description Required
Change Request Number String The value of the Number field for the relevant Change Request. Yes
End Date Field String The ServiceNow field name for the end date to check between. Defaults to end_date. No
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. No
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
Start Date Field String The ServiceNow field name for the start date to check between. Defaults to start_date. No
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. No

Check Records

Check records in a specified table against specified field values.

Input properties for the Check Records step
Name Type Description Required
Check Fields String Newline seperated list of field value pairs. You may use the
Name, what you see in the XML export, of the field. The record(s) will be checked
to ensure that the values of the inputed field match and that the fields exist.
For example: description=This is a high valued task
Yes
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. Yes
Record Number String Newline separated list of unique IDs of record to check. Represents the record number
(ex. CHG0040001).
Yes
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
Table Name String The Name, what you see in the XML export, of the table to be updated.
Example: change_request
Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. Yes

Create Records

Creates records by table name and specified fields.

Input properties for the Create Records step
Name Type Description Required
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Row Fields String The Fields to insert for this row. Each name-value pair should be on a separate line.
A = separates the name and value. Example: name=value
No
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
ServiceNow password Password Provide the password to authenticate with ServiceNow. Yes
ServiceNow user name String Provide the user name to authenticate with ServiceNow. Yes
Table Name String The Name (not the Label) of the table to be updated. Example: change_request Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No

Delete Multiple Table Records with Query

Deprecated. Please use the Run Encoded Query and Delete Records step instead.

Input properties for the Delete Multiple Table Records with Query step
Name Type Description Required
CMDB Row Condition String The Encoded Query a row must match for deletion. See http://wiki.servicenow.com/index.php?title=Embedded:Encoded_Query_Strings
for examples
Yes
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
ServiceNow Password Password Provide the password to authenticate with ServiceNow. Yes
ServiceNow User name String Provide the user name to authenticate with ServiceNow. Yes
Table Name String The name of the table to update. Example: change_request Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No

Delete Records

Deletes records by table name and record number.

Input properties for the Delete Records step
Name Type Description Required
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Record Number String Newline separated list of unique IDs of record to check. Represents the record number
(ex. CHG0040001).
Yes
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
ServiceNow Password Password Provide the password to authenticate with ServiceNow. Yes
ServiceNow User name String Provide the user name to authenticate with ServiceNow. Yes
Table Name String The Name (not the Label) of the table to update. Example: change_request Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No

Run Encoded Query

Run an encoded query and receive a newline list of record system IDs to pass to subsequent
steps.

Input properties for the Run Encoded Query step
Name Type Description Required
Encoded Query String The query value of your encoded query. Use the copy query function in ServiceNow. Yes
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. Yes
ServiceNow URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
Table Name String The Name, what you see in the XML export, of the table to be updated.
Example: change_request
Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. Yes

Set Change Request State

Set the status field of a change request.

Input properties for the Set Change Request State step
Name Type Description Required
Change Request Number String The value of the Number field for the relevant Change Request. Yes
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. No
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
State integer String The state you want to set on the Change Request. This is an integer key corresponding
to the state value-key pair used by ServiceNow. By default -5 is Pending, 1 is Open,
2 is Work in Progress, 3 is Closed Complete, 4 is Closed Incomplete, and 7 is Closed
Skipped. You can find your particular key-value pairs by opening a task in ServiceNow,
clicking on Additional actions button by the title, Configure->Form Design,
and then clicking the edit this field settings button that appears when selecting
the state field.
Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. No

Set Task Status

Update the state of a task item.

Input properties for the Set Task Status step
Name Type Description Required
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. No
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
State integer String The state you want apply to the listed Tasks. This is an integer key corresponding
to the state value-key pair used by ServiceNow. By default -5 is Pending, 1 is Open,
2 is Work in Progress, 3 is Closed Complete, 4 is Closed Incomplete, and 7 is Closed
Skipped. You can find your particular key-value pairs by opening a task in ServiceNow,
clicking on Additional actions button by the title, Configure->Form Design,
and then clicking the edit this field settings button that appears when selecting
the state field.
Yes
Task ID List String A comma-separated list of the Task Number field value of the Change Tasks to be updated.
(ex. CTASK0010071)
Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. No

Update Records

Update records by specifying field values.

Input properties for the Update Records step
Name Type Description Required
Fields to Update String Newline separated list of field value pairs. You may use the
Name, what you see in the XML export, of the field. Fields described here will be
updated on each record to specified value. If the field does not exist the step will
fail. For example: description=This is a high valued task
Yes
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No
Password Password The password to be used to connect to the ServiceNow server. Yes
Record Number String Newline separated list of unique IDs of record to check. Represents the record number
(ex. CHG0040001).
Yes
Server URL String The URL of your ServiceNow portal. Example: https://myaccount.service-now.com Yes
Table Name String The Name, what you see in the XML export, of the table to be updated.
Example: change_request
Yes
Trust All Certificates Boolean Select to trust all unsecure certificates. No
User Name String The user name to be used to connect to the ServiceNow server. Yes