Plug-in Documentation

ServiceNow for UrbanCode Release

 

Overview

The ServiceNow plug-in includes steps that automate creating, reading, updating, and deleting ServiceNow records.

This plugin includes one or more steps, click Steps for step details and properties.

Compatibility

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

Installation

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

History

Version 7

  • Add property resolver

Version 6

  • Initial release

Usage

The following use cases demonstrate using the ServiceNow plug-in.

Step palette

To access this plug-in in the palette, click Change.

Use Case 1: Create SNOW records when UrbanCode Release deployments are created

This case describes how to create ServiceNow records when UrbanCode Release deployments are created. This is useful when UrbanCode Release is used as the main entry point for change management activities. When a deployment is scheduled, this creates a change request in ServiceNow. The resulting change request includes information about the deployment and is updated as the deployment progresses and completes.

Set up the integration

  1. Create an integration using the Create SNOW Record when Deployment is Created step.


    Provide information about the ServiceNow server.

    Name Description
    ServiceNow user name The ServiceNow user that is used to authenticate with the ServiceNow server.
    ServiceNow password The password associated with the ServiceNow user
    Table Name The ServiceNow table for which a resource is to be created. Generally, change_request is the appropriate value.
    Type Workflow There are multiple workflows that a change request can go through, select the type of workflow for the change request. If the dynamically generated dropdown is not populating, check your server URL and authentication.
    Proxy configuration Configure the outbound proxy if required.
  2. Select the phases to trigger the ticket creation. Not every deployment to every environment might require a change request. With this in mind, select which UrbanCode Release phases per lifecycle to perform this action.


  3. Optionally, you can configure an UrbanCode Release approval. The ServiceNow change request can have a series of approvals that must be executed. These SNOW approvals can automatically approve an UrbanCode Release Phase Approval. To configure, navigate to the Release Detail page of a release and add the approval within a phase under the Release Pipeline section of the page. In the integration configuration provide the name of the approval in the Approval Name field. When a deployment is created with that UrbanCode Release Phase Approval, the approval is completed when the recurring integration detects the approvals are complete in ServiceNow.

  4. Specify the ServiceNow Assigned Group. This is a required field.

  5. When a deployment is created, started, and ended the status of the associated Service Now change request is updated. Provide the change request status that should result from each of those events.

Try it out

  1. Create a deployment for a selected phase in the integration.
    Navigate into that deployment and after a moment you will see a link to the SNOW change request.


  2. Navigate to the SNOW change request and execute all the necessary approvals. After the integration runs (this is the only action in this use case that requires the recurring integration to execute), the approval in the deployment that you specified in the integration is approved automatically.


  3. Start the deployment and navigate back to the SNOW change request to notice that the status is updated to Implement.


  4. Finish the deployment by executing or skipping all the tasks and navigate back to the SNOW change request. Notice that the status is now updated to Review.

Notes

This use case does not work on the Derby database because of Derby database limitations. This is a permanent restriction. The Derby database is not a production supported database for UrbanCode Release.

If the status of the change request does not update to the state you specified, check to see if anything in the change request workflow is blocking the promotion to that state. That is, the change request must pass approvals or be put in another state first.

Use Case 2: Fetch SNOW records and create UrbanCode Release deployments

This use case describes how to fetch ServiceNow records and create deployments in UrbanCode Release. This is useful when your team typically initiates change requests in ServiceNow. When a change request is created in ServiceNow, UrbanCode Release schedules a deployment based on the inputs of the change request. When the deployment is started and finished, the status of the change request is updated according to your configuration.

Set up the integration

1. Create the integration using the Fetch SNOW Records and Create Deployments step.

Provide the basic server and authentication information. Include the table for which deployments are created. See Create SNOW records when UrbanCode Release deployments are created for property details.

2. This use case requires some custom fields in ServiceNow. You can edit the form layout of the change request to include new fields to indicate the Urbancode Release release and environment.

One method for adding the custom fields is to add a custom section called UrbanCode Release and then adding two new fields Release and Environment.

3. Return to the UrbanCode Release integration configuration and provide the names of the custom fields you created. The names of these fields can be confirmed if you export a SNOW change request as XML, if you used the suggested field names above, the names are u_release and u_environment.

You can also specify a default environment, if the environment is not provided.

4. The approval configuration is the same as the use case: Create SNOW records when UrbanCode Release deployments are created.

5. Specify the state of the change request that would indicate that the integration should create the deployment. Also specify the state to which the change request should be set when the deployment is started and closed.

6. Ensure the integration frequency is not set to manual.

Try it out

1. Create a ServiceNow Change Request and provide valid input to the two custom fields previously created.

2. Ensure that the integration runs in UrbanCode Release.
After a successful integration navigate to the deployments and verify that a new deployment has been created.

3. Complete any approvals in Service Now, run and complete the UrbanCode Release deployment, and verify the synced statuses throughout the process.

Use Case 3: Create and update snow records as deployment tasks

This use case demonstrates how to create tickets, update tickets, and wait for approvals of tickets as a part of an UrbanCode Release deployment plan.

Set Up Integration

1. Even though the executions of this use case are within the deployment plan, an integration to configure the server URL and authentication is required. Create an integration using the Create SNOW Record when Deployment is Created step.

Provide the basic server and authentication information. See Create SNOW records when UrbanCode Release deployments are created for property details.

Do not specify any phases to create change requests; that way the only tickets created are from tasks in the deployment plan.

2. The Plugin Task Support feature flag must be enabled. Feature flags are located on the System Settings page. Click Settings > System Settings to set the feature flag. To save your setting, click Save.

3. Navigate to a deployment plan and add a new
Plugin Task type task. You can choose one of the following for the task:

  • Open Service Now Ticket
  • Wait for Approval of Service Now Ticket
  • Close Service Now Ticket

4. Edit the task you just created and go to the Advanced tab. There you can configure the details of the ticket that is created.

The values for the Short Description, Description, and Plugin properties can be dynamically resolved from the Scheduled Deployment (sd) or the Task (task) as seen below. This convention follows the standard fields available on the ScheduledDeployment and TaskExecution api entities.

Try it out

Whenever these tasks execute, a comment is left with a link to the associated ServiceNow ticket.

When running the Wait for Approval of Service Now Ticket task, the task starts and remains in progress until the approvals are complete in ServiceNow.

Steps

Process steps in the Service Now Plugin plug-in

Close Service Now Ticket

Closes

Input properties for the Close Service Now Ticket step
Name Type Description Required Property Name
Close Service Now ticket Properties This task closes a Service Now ticket. If the record ID field is provided, that ticket is closed; otherwise, the ticket opened in a previous Open Service Now Ticket task is closed. If multiple Open Service Now Ticket(s) exist, then reference
the one for which you intend to close by using a direct prerequisite task dependency. If no such task exists, this task is skipped.
No OpenServiceNowTicketDescription
Close Ticket Notes String Notes that are required to close the ticket No closeTicketNotes
New Ticket State ID of the state that the ticket will move to ex: -5 to 5 No newStatus
Record Id String The record ID for which this task will wait for its approval (Example: CHG0030037). No record_id

 

Create SNOW Record when Deployment is Created

The ServiceNow plugin allows for the easy automation of CRUD operations on ServiceNow
records.

Input properties for the Create SNOW Record when Deployment is Created step
Name Type Description Required Property Name
Additional Properties String If there are required custom fields, you may provide the values for them here. This is a line-delimited set of properties. (key=value) No additionalProperties
Approval Configuration When a scheduled deployment is created with an approval with that name, the integration
will handle its completion by looking at the corresponding approval in ServiceNow
No approvalConfiguration
Approval Name String Approval with this name will be handled in Service Now No approvalName
Authentication Configuration No authentication
Change Information Change information fields can be defined in this section No changeInformation
Create SNOW Record when Deployment is Created <div style=” margin-left: 25px; “><ul style=”list-style-type: disc;”><li>Create record
of a specified type when a deployment to specified phase is created </li><li>Updates
the record’s state when deployment starts and finishes</li><li>Uses SNOW approvals
to complete phase approvals (optional)</li></ul></div>
No createSNOWRecordLabel
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No proxyHost
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No proxyPass
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No proxyPort
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No proxyUser
Phases to Trigger Work Item Creation The lifecycle phases for which deployments will create Service Now work items. This
is broken out into phases per lifecycle, so as to select lifecycles used by specfic
releases. Example: PROD – Mobile Team Lifecycle, would be selected so as to trigger
work items created for deployments to the PROD phase for any release using the lifecycle
named Mobile Team Lifecycle.
No phasesSelected
Release Configuration Defines what release and what phases will trigger the creation of a ticket No releaseConfiguration
Service Now Assigned Group Group assigned to this work item in ServiceNow No serviceNowAssignedGroup
ServiceNow Server Url String Service-now Server Url Yes serverUrl
ServiceNow password Password Provide the password to authenticate with ServiceNow. Yes password
ServiceNow user name String Provide the user name to authenticate with ServiceNow. Yes username
Table Name String The name of the table to update when deployments are started and ended (Example: change_request).
To find this value, search for System Definition > Table and Columns in the left navigation
pane in ServiceNow. Once there, find the name column and enter that value here.
The most common use case for this plugin is to create change_request items.
Yes table
Type Worflow ex: standard or normal (with approvals) Yes workflow
When deployment is created ID of the state that the ticket will move to ex: -5 to 5 No deploymentCreatedState
When deployment is ended ID of the state that the ticket will move to ex: -5 to 5 No deploymentEndedState
When deployment is started ID of the state that the ticket will move to ex: -5 to 5 No deploymentStartedState
Workflow Configuration This section defines what state the ServiceNow work item should change to when the
scheduled deployment is created, started, completed
No stateConfiguration

 

Fetch SNOW Records and Create Deployments

The ServiceNow plugin allows for the easy automation of CRUD operations on ServiceNow
records.

Input properties for the Fetch SNOW Records and Create Deployments step
Name Type Description Required Property Name
Approval Configuration When a scheduled deployment is created with an approval with that name, the integration
will handle its completion by looking at the corresponding approval in ServiceNow
No approvalConfiguration
Approval Name String Approval with this name will be handled in Service Now No approvalName
Authentication Configuration No authentication
Custom Field Configuration In Service Now, it is best to create custom fields to indicate for which release and
environment a deployment will be made. This section allows you to input the names
of those fields for UCR to retrieve.
No customFieldSection
Default environment if none is specified in SNOW String This environment will be used if a release is specified but an environment is not. No defaultEnv
Fetch SNOW Records and Create Deployments <div style=” margin-left: 25px; “><ul style=”list-style-type: disc;”><li>Creates UCR
Deployment when a SNOW record reaches a specified state</li><li>Updates the record’s
state when deployment starts and finishes</li><li>Uses SNOW approvals to complete
phase approvals (optional)</li></ul></div>
No createSNOWRecordLabel
Field to use for environemnt String This field in SNOW will contain the name of the UCR environment to which this integration
will create a deployment.
No envField
Field to use for release String This field in SNOW will contain the name of the UCR release for which this integration
will create a deployment.
No releaseField
HTTP Proxy Host String Provide the hostname of the HTTP proxy to use to connect to ServiceNow. Eg proxy.domain.com No proxyHost
HTTP Proxy Password Password Provide the password to authenticate with HTTP proxy. No proxyPass
HTTP Proxy Port String Provide the port number of the HTTP proxy to use to connect to ServiceNow. No proxyPort
HTTP Proxy User name String Provide the user name to authenticate with HTTP proxy. No proxyUser
ServiceNow Server Url String Service-now Server Url Yes serverUrl
ServiceNow password Password Provide the password to authenticate with ServiceNow. Yes password
ServiceNow user name String Provide the user name to authenticate with ServiceNow. Yes username
Table Name String The name of the table to update when deployments are started and ended (Example: change_request).
To find this value, search for System Definition > Table and Columns in the left navigation
pane in ServiceNow. Once there, find the name column and enter that value here.
The most common use case for this plugin is to create change_request items.
Yes table
When deployment is ended ID of the state that the ticket will move to ex: -5 to 5 No deploymentEndedState
When deployment is started ID of the state that the ticket will move to ex: -5 to 5 No deploymentStartedState
When record is in this state, the deployment will be created ID of the state that the ticket must be in to create a deplopyment ex: -5 to 5 No deploymentCreatedState
Workflow Configuration This section defines what state the ServiceNow work item needs to to reach to trigger
the creation of a deployment. This section also defines the state the Service Now
work item should change to when the scheduled deployment is started and completed
No stateConfiguration

 

GetUCRPhaseModels

Check Connection

This step has no input properties.

 

Open Service Now Ticket

Creates a Service Now change request

Input properties for the Open Service Now Ticket step
Name Type Description Required Property Name
Description String The name of the table to update when deployments are started and ended (Example: change_request).
To find this value, search for System Definition > Table and Columns in the left navigation
pane in ServiceNow. Once there, find the name column and enter that value here.
The most common use case for this plugin is to create change_request items.
No description
Open Service Now Ticket Properties This task will open a Service Now ticket. If these fields are not provided, the default
values will be retrieved from the integration provider that was created for this plugin.
For instance, if you do not provide a value for table, it will default to the value
provided in the integration provider.
No OpenServiceNowTicketDescription
Service Now Assigned Group Group assigned to this work item in ServiceNow No serviceNowAssignedGroup
Short Description String The name of the table to update when deployments are started and ended (Example: change_request).
To find this value, search for System Definition > Table and Columns in the left navigation
pane in ServiceNow. Once there, find the name column and enter that value here.
The most common use case for this plugin is to create change_request items.
No shortDescription
Table Name String The name of the table to update when deployments are started and ended (Example: change_request).
To find this value, search for System Definition > Table and Columns in the left navigation
pane in ServiceNow. Once there, find the name column and enter that value here.
The most common use case for this plugin is to create change_request items.
No table
Type Worflow ex: standard or normal (with approvals) No workflow
When deployment is created ID of the state that the ticket will move to ex: -5 to 5 No deploymentCreatedState

 

ServiceNowUpdate

Service Now Update

This step has no input properties.

 

Wait for Approval of Service Now Ticket

Wait for the approval of the Service Now ticket

Input properties for the Wait for Approval of Service Now Ticket step
Name Type Description Required Property Name
New Ticket State (optional) ID of the state that the ticket will move to ex: -5 to 5 No newStatus
Record Id String The record ID for which this task will wait for its approval (Example: CHG0030037). No record_id
Wait for the approval of the Service Now ticket Properties This task will complete when the field ‘approval’ equals ‘approved’ in a Service Now
ticket. If the record ID field is provided, it will search for that ticket; otherwise,
it will wait for the ticket opened in a previous ‘Open Service Now Ticket’ task.
If multiple ‘Open Service Now Ticket(s)’ exist, then reference the one for which you
intend to wait for approval by using a direct prerequisite task dependency. If no
such task exists, this task will skip.
No OpenServiceNowTicketDescription

 

groups

Groups

This step has no input properties.

 

states

Gets available states for workflows

This step has no input properties.

 

workflows

Gets available states for workflows

This step has no input properties.