ServiceNow plugin

25 minute readExtensibilityDeveloper productivity

ServiceNow is a software-as-a-service (SaaS) provider of IT service management (ITSM) software. It creates a single system of record for all IT processes within a company. This system brings together IT strategy, design, transition and operation on a powerfully simple cloud platform.

ServiceNow is built to be a productivity tool for all types of business users including the CIO, service desk staff, application developers, IT finance, IT operations and business people. ServiceNow applications are built on a single platform as a service. The platform offers a consistent and intuitive user experience through the entire IT Infrastructure Library (ITIL) service life-cycle. For more information about ServiceNow, refer to the ServiceNow home page.

CloudBees CD/RO integration to ServiceNow

ServiceNow supports calling both inbound services, leveraging the ServiceNow REST API to perform actions such as:

  • Queries and updates

  • Calling outbound web services, such as the CloudBees CD/RO Rest API, upon a user action in ServiceNow such as an Approval or Rejection of a change request.

The ServiceNow plugin supports the inbound interaction with ServiceNow, by calling provider web services such as creating a change request, creating an incident, and getting the status of an approval.

The CloudBees CD/RO native extension plugin, which is installed in a ServiceNow instance, supports the outbound consumer web service interaction and is available in the ServiceNow Marketplace. This plugin is documented here for no purpose other than cross-referencing CloudBees CD/RO capabilities for both inbound and outbound interactions.

  • The Native Extension plugin is not required to be installed in ServiceNow if there is no need for the outbound interaction.

  • If you have not installed a CloudBees CD/RO ServiceNow application, you cannot use the bidirectional integration features in the CreateChangeRequest and CreateChangeTask procedures.

Plugin Version 3.2.6.2024020845

Revised on February 22, 2021

Updated Perl version required

This plugin is using an updated version of Perl, cb-perl shell (instead of ec-perl). Therefore, CloudBees CD/RO agent version 10.3+ is required.

Integrated version

This plugin was developed and tested against following ServiceNow versions:

  • Eureka (Deprecated)

  • Fuji (Deprecated)

  • Geneva (Deprecated)

  • Helsinki (Deprecated)

  • Istanbul (Deprecated)

  • Jakarta (Deprecated)

  • Kingston (Deprecated)

  • London (Deprecated)

  • Madrid (Deprecated)

  • New-York

  • Paris

  • Orlando

  • Utah

  • Vancouver

For all parameter descriptions in this document, required parameters are shown in bold italics.
In the CloudBees CD/RO UI, go to the Home page, open the Main Menu, and click Admin > Plugins to open the Plugin Manager.

Plugin configurations

Plugin configurations are sets of parameters that can be applied across some, or all, of the plugin procedures. They can reduce the repetition of common values, create predefined parameter sets, and securely store credentials. Each configuration is given a unique name that is entered in the designated parameter for the plugin procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD/RO, complete the following steps:

  1. Navigate to DevOps Essentials  Plugin Management  Plugin configurations.

  2. Select Add plugin configuration to create a new configuration.

  3. In the New Configuration window, specify a Name for the configuration.

  4. Select the Project that the configuration belongs to.

  5. Optionally, add a Description for the configuration.

  6. Select the appropriate Plugin for the configuration.

  7. Configure the parameters per the descriptions below.

Parameter Description

Name

Name of the plugin configuration. (Required)

Host

Host machine, such as /https://demo10.service-now.com. (Required)

Ignore SSL errors

Turn SSL verification off for instances with self-signed certificates.

Use CloudBees CD/RO Application?

If checked, EC-ServiceNow will assume that CloudBees CD/RO Native Application is installed on target instance. Otherwise, no native application specific APIs would be used. Procedures affected by this checkbox:

  • CreateChangeRequest

  • CreateChangeTask

Login as:

  • Runtime credential

    • Username: Enter the username. This parameter is case-sensitive. (Required)

    • Password: Enter the password. This parameter is case-sensitive. (Required)

    • Retype Password: Re-enter the password. This parameter is case-sensitive. (Required)

  • Credential reference

    • Select project: Select the reference project of the credential from the drop-down list. (Required)

    • Select Credential: Select the credential you wish to use.

Log Level

This option sets debug level for logs. If info is selected, only summary information will be shown; for debug, there will be some debug information.

HTTP Proxy

A HTTP proxy that should be used for connections.

Proxy authorization

  • Runtime credential

    • Proxy username: Enter the proxy username. This parameter is case-sensitive. (Required)

    • Proxy password: Enter the password. This parameter is case-sensitive. (Required)

    • Retype Proxy Password: Re-enter the password. This parameter is case-sensitive. (Required)

  • Credential reference

    • Select project: Select the reference project of the credential from the drop-down list. (Required)

    • Select Credential: Select the credential you wish to use.

Using non-admin users on ServiceNow instance

If your ServiceNow instance with the CloudBees CD/RO application uses a non-admin user, ensure the user has the following required roles:

  • import_transformer

  • EFImportTableAdmin

Output

The ServiceNow Configurations page now shows the new configuration.

Plugin procedures

AddRecord

This procedure adds a record to ServiceNow.

Parameter Description

Configuration Name

Name of the configuration. (Required)

Record ID

Record ID of the incident, such as a table or number.

Content

JSON representation of the request content that will be used as content. To add a short description, you can use next JSON:\{"short_description":"New Short Description"}.

PropertySheet for procedure result

The property sheet where the procedure results should be saved. The default is /myJobStep.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the AddRecord step, click the Log button to see the diagnostic information:

AttachChangeTasksToChangeRequest

This procedure attaches one or more change tasks to a change request (CR). All CRs and Tasks should exist already, else procedure will fail.

Parameter Description

Configuration Name

Provide the name of the configuration to use.

Change Request Record Id

A Change Request Record Id to which previously existing Change Tasks should be linked.

Change Tasks Record Ids

A comma-separated Change Task Record Ids of existing Change Tasks that should be linked to existing Change Request.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the AttachChangeTasksToChangeRequest step, click the Log button to see the diagnostic information.

CheckApprovalStatus

This procedure checks the status of one or more approvals.

  • If you select the Check All parameter, all the approvals are retrieved.

  • If you select or specify the other parameters, specific approvals are retrieved.

  • If both the Approval For and Approver parameters are specified, CloudBees CD/RO searches for and retrieves approvals that match both parameters.

  • If the same approvals are retrieved using either the System ID(s) parameters or the Approval For and Approver parameters, CloudBees CD/RO retrieves and displays them once.

Parameter Description

Configuration Name

Name of the configuration. (Required)

Check All

If selected, all approvals are retrieved.

Approval For

The identifier for what the approval is for. An example of a change request is CHG0000009.

Approver

The user or group who approves the approval requests.

System ID(s)

The unique identifier for an approval. You can specify more than one ID, separating them with commas.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the CheckApprovalStatus step, click the Log button to see the diagnostic information:

CollectReportingData

This procedure creates incident report and sends it to CloudBees CD/RO.

Parameter Description

Configuration name

Required. Provide the name of the configuration to use.

Source table

Servicenow table to get reporting data from. It should be ServiceNow table name, but with no label. For example, for Incident table it should be incident, for Change Request it should be change_request.

Filter

Simple filters can be written in JSON. For example: {"number": "CR1938910"}.

Complex filters must be written in ServiceNow query language. For example: priority=1^ORpriority=2.

Regardless of using JSON or ServiceNow query language, all field names must be the actual field names from ServiceNow and not display names. There are references, descriptions, and use case examples for this field in the plugin documentation. For more information, refer to Using the EC-ServiceNow Filter field.

Preview mode

Special CollectReportingData procedure mode. This mode is designed to help with report configurations. If enabled, no reports will be sent and no metadata will be set. High verbosity will be enabled instead. In that mode user can configure mappings, transformation before set before enabling automatic reporting. In this mode each object, retrieved from servicenow will be displayed, transformation, mapping and final payload will be displayed also.

Use Table API

If checked, ServiceNow Table API will be used instead of JSONv2 API for data retrieval. Table API returns data with a different structure, thus default mappings in "Field mapping" won’t work. Default mappings for Table API are available in the Table API Field Mapping help section.

Field mapping

Allows user to place custom fields to payload, or modify payload values. Examples: "MyApplication":releaseName - map value "MyApplication" to payload releaseName field. lastBuiltRevision.SHA1:myLastRevision - map SHA1 field from lastBuiltRevision object to myLastRevision. lastBuiltRevision.branch[0].SHA1:myLastRevision - map SHA1 field from first element of branch array of lastBuiltRevision object to myLastRevision.

Transform script

Allows user to provide perl script for payload customization. This method will be invoked by plugin with 2 parameters. 1st parameter is context object, 2nd is payload object. Method should be named "transform", and should return payload object. In this example myTimestamp field will be added to payload object:

sub transform { my ($context, $payload) = @_; $payload->{myTimestamp} = $context->one(); return $payload; } sub one { my ($context) = @_; return time(); }

Metadata propertysheet path

Path to propertysheet which will be used to store metadata. If omitted, path will be used depending on context: schedule or procedure.

Base URL for drill-down

Drill-down URL for the records in ServiceNow.

Release Filter URI

URI that will be used with the base Url to build a drill-down URL for records in ServiceNow.

Debug

If checked, the debug level will be set to "Debug".

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

Table API field mapping

If "Use Table API" checkbox is checked, ServiceNow Table API will be used instead of JSONv2 API for data retrieval. Table API returns data with a different structure, thus default mappings in "Field mapping" won’t work. Default mappings for Table API:

--- number.display_value:incidentId, category.display_value:category, subcategory.value:subCategory, cmb_ci.display_value:configurationItem, priority.display_value:priority, state.display_value:status, opened_by.display_value:reportedBy, resolved_at.value:resolvedOn, sys_created_on.value:createdOn, sys_updated_on.value:modifiedOn, cmdb_ci.display_value:releaseName, "Enter-release-project-name-here":releaseProjectName ----

Dot-walking feature

With enabled Table API you can use ServiceNow "dot-walking" feature. You can specify chains of field names separated by escaped dots (periods) in Field Mapping parameter:

assigned_to.company.display_value:company,
opened_by.manager.value:manager,
opened_by.department.dept_head.display_value:department_head

CreateChangeRequest

This procedure creates new Change Request in the ServiceNow instance. If Correlation ID and Correlation Display is specified and CloudBees CD/RO Integration Scoped Application is installed and enabled on ServiceNow side it’s possible to approve gate task in the CloudBees CD/RO automatically after approval in the ServiceNow.

To use this procedure for bi-directional integration, a CloudBees CD/RO application should be installed on your ServiceNow instance from ServiceNow Store and the Use CloudBees CD/RO Application? parameter enabled in the EC-ServiceNow configuration. If you have not installed the Native Extension plugin, you can disable parameter Use CloudBees CD/RO Application? in configuration or use the AddRecord procedure instead to create a change request.
Ensure users in your ServiceNow instance has the required roles. For more information, refer to Using non-admin users on ServiceNow instance with CloudBees CD/RO application.
Parameter Description

Configuration Name

Name of the configuration. (Required)

Description

Short description for new change request. (Required)

Correlation ID

Used only for bi-directional integration with native ServiceNow plugin "CloudBees CD/RO".

Parameter for CloudBees CD/RO ServiceNow scoped application. Should contain path for the completeManualTask REST call. This parameter will be used for pipeline gate approval or reject by approving or rejecting change request at the servicenow side.

Example: /flowRuntime/$[/myPipelineRuntime/id]/stage/Stage 1/gate/POST/taskName/out1

Where:

  • $[/myPipelineRuntime/id] is a property with current runtime id

  • stage is a Pipeline Stage name

  • out1 is gate name with type POST

For integration, the Correlation Display parameter should be also provided.

Correlation Display

Used only for bi-directional integration with native ServiceNow plugin "CloudBees CD/RO".

Parameter for CloudBees CD/RO servicenow scoped application. Should be set to ElectricFlow Pipeline Task to trigger CloudBees CD/RO ServiceNow scoped application. Also, for integration, proper Correlation ID must be set.

Content

Additional change_request table parameters.

PropertySheet for procedure result

Property Sheet where procedure results should be stored.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

CreateChangeTask

This procedure creates new Change Task in the ServiceNow instance. If Correlation ID and Correlation Display is specified and CloudBees CD/RO Integration Scoped Application is installed and enabled on ServiceNow side it’s possible to approve gate task in the CloudBees CD/RO automatically after closing task in the ServiceNow.

To use this procedure for bi-directional integration, a CloudBees CD/RO application should be installed on your ServiceNow instance from ServiceNow Store and the Use CloudBees CD/RO Application? parameter enabled in the EC-ServiceNow configuration. If you have not installed the Native Extension plugin, you can disable parameter Use CloudBees CD/RO Application? in configuration or use the AddRecord procedure instead to create a change request.
Ensure users in your ServiceNow instance has the required roles. For more information, refer to Using non-admin users on ServiceNow instance with CloudBees CD/RO application.
Parameter Description

Configuration Name

Name of the configuration. (Required)

Description

Short description for new change task. (Required)

Correlation ID

Used only for bi-directional integration with native ServiceNow plugin "CloudBees CD/RO".

Parameter for CloudBees CD/RO ServiceNow scoped application. Should contain path for the completeManualTask REST call. This parameter will be used for pipeline gate approval or reject by approving or rejecting change request at the servicenow side.

Example: /flowRuntime/$[/myPipelineRuntime/id]/stage/Stage 1/gate/POST/taskName/out1

Where:

  • $[/myPipelineRuntime/id] is a property with current runtime id

  • stage is a Pipeline Stage name

  • out1 is gate name with type POST

For integration, the Correlation Display parameter should be also provided.

Correlation Display

Used only for bi-directional integration with native ServiceNow plugin "CloudBees CD/RO".

Parameter for CloudBees CD/RO servicenow scoped application. Should be set to ElectricFlow Pipeline Task to trigger CloudBees CD/RO ServiceNow scoped application. Also, for integration, proper Correlation ID must be set.

Change Task Details

Specify values for various ServiceNow Change Task fields using JSON format. For e.g. {"description": "This is change task description", "comments":"This is a comment"}

Change Request Record Id

Specify the record Id of change request to which change task should be attached. Number or sys id of change request are expected. Validation of this change request will be performed before change task creation and procedure will fail if it does not exist.

PropertySheet for procedure result

Property Sheet where procedure results should be stored.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

CheckChangeRequestStatus

This procedure checks the status of one or more change requests. When you select the "Check All" parameter, all the change requests are retrieved. When you select and specify other parameters, specific change requests are retrieved. When the "Requested By", "Assigned To", "Configuration Item", "Category", "Priority", "Risk", and "Type" parameters are all specified, CloudBees CD/RO searches for and retrieves change requests that match all of these parameters. When the same change requests are retrieved using either the "Number(s)" parameters or a combination of the other parameters as the search criteria, CloudBees CD/RO retrieves the change requests once.

Parameter Description

Configuration Name

The name of the configuration. (Required)

Check All

If selected, all change requests are retrieved.

Number(s)

The change request number. You can specify more than one change request number, separating them with commas.

Requested By

The sys_id of user who requested the change request.

Assigned to

The sys_id of user who is assigned the change request.

Configuration Item

The sys_id of configuration item associated with the change request.

Category

The category assigned to the change request.

Priority

The priority assigned to the change request.

Risk

The risk assigned to the change request.

Type

The type of change request.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the CheckChangeRequestStatus step, click the Log button to see the diagnostic information:

CreateIncident

This procedure creates an incident in ServiceNow.

Parameter Description

Configuration Name

The name of the configuration. (Required)

Description

Short description of the incident. (Required)

Assignee

User or group to which the incident is assigned.

Impact

The effect an incident has on business. Specify the impact level as an integer.

Urgency

The extent to which the incident’s resolution can be delayed. Specify the urgency level as an integer.

Priority

How quickly the service desk should address the incident. Specify the priority level as an integer.

Content

JSON representation of the request content that will be used as content. To add a short description, you can use next JSON: {"short_description":"New Short Description"}.

PropertySheet for procedure result

The property sheet where the procedure results should be saved. The default is /myJobStep.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the CreateIncident step, click the Log button to see the diagnostic information:

DeleteIncident

This procedure deletes an incident in ServiceNow.

Parameter Description

Configuration Name

The name of the configuration. (Required)

Sys ID

The Sys ID (sys_id) of the incident. (Required)

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the DeleteIncident step, click the Log button to see the diagnostic information:

GetChangeTasks

This procedure is designed to retrieve change tasks from ServiceNow Change Tasks table.

Parameter Description

Configuration Name

Provide the name of the configuration to use.

Change Task Retrieval Type

A type which will be used for change task retrieval. Available types:

  • Record Id: Lookup by record ID.

  • Change Request Record ID: Lookup by change request record id

  • ServiceNow QL: Lookup by ServiceNow QL

Record Id

A Record Id of ServiceNow ChangeTask to retrieve.

Change Request Record Id

Specify the record Id of change request to which change task should be attached. Number or sys id of change request are expected. Validation of this change request will be performed before change task creation and procedure will fail if it does not exist.

ServiceNow QL

A ServiceNow QL query, that could be copied in ServiceNow instance table navigation by "Copy query" link.

Result Property Sheet

Property sheet where procedure results should be saved.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the GetChangeTasks step, click the Log button to see the diagnostic information:

GetRecord

This procedure returns a record from ServiceNow.

Parameter Description

Configuration Name

Name of the configuration. (Required)

Record ID

Universal field for ServiceNow records identification. SysID, Number, or Table may be specified.

For example, INC00001 will be parsed as number, incident will be parsed as table, d1552ef84f0e4200a94bdd211310c79f as sys_id and incident.d1552ef84f0e4200a94bdd211310c79f as sys_id from incident table.

Few identifiers also may be specified. Numbers should be separated by comma. For unsupported or custom tables and prefixes should be used format "table.number". For example:

INC00001,

INC00002,

d1552ef84f0e4200a94bdd211310c79f,

incident.d1552ef84f0e4200a94bdd211310c79f,

incident

my_table.MYPREFIX0123456

Filter

Filters must be written in JSON. For example: {"number": "CR1938910"}.

All field names must be the actual field names from ServiceNow and not display names. There are references, descriptions, and use case examples for this field in the plugin documentation. For more information, refer to JSON filters in Using the EC-ServiceNow Filter field.

Content

JSON representation of the request content that will be used as content. To add a short description, you can use next JSON: {"short_description":"New Short Description"}.

PropertySheet for procedure result

The property sheet where the procedure results should be saved. The default is /myJobStep.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the GetRecord step, click the Log button to see the diagnostic information:

SetChangeRequestStatus

This procedure sets the status of one or more change requests. When the "Requested By", "Assigned To", "Configuration Item", "Category", "Priority", "Risk", and "Type" parameters are all specified, CloudBees CD/RO retrieves the change requests that match all of these parameters and updates their status. When the same change requests are retrieved using either the "Number(s)" parameters or a combination of the other parameters as the search criteria, CloudBees CD/RO retrieves, updates, and displays them once.

Parameter Description

Configuration Name

The name of the configuration. (Required)

New State

The new state for one or more change requests that match the search criteria: Pending, Open, Work in Progress, Closed Complete, Closed Incomplete, and Closed Skipped. The default is Pending. (Required)

Number(s)

One or more change request numbers. You can specify more than one change request number, separating them with commas.

Requested By

The sys_id of user who requested the change request.

Assigned to

The sys_id of user assigned to the change request.

Configuration Item

The sys_id of configuration item associated with the change request.

Category

The category assigned to the change request: Software, Hardware, Business Service, Systems Software, Applications Software, Network, Telecom, Documentation, or Other.

Priority

The priority assigned to the change request: 1 - Critical, 2 - High, 3 - Moderate, 4-Low, 5-Planning, or None.

Risk

The risk assigned to the change request: Very High, High, Moderate, Low, or None.

Type

The type of change request: Routine, Comprehensive, Emergency, or None.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the SetChangeRequestStatus step, click the Log button to see the diagnostic information:

UpdateIncident

This procedure creates an incident in ServiceNow.

Parameter Description

Configuration Name

The name of the configuration. (Required)

Description

Short description of the incident. (Required)

Sys ID

The Sys ID (sys_id) of the incident. (Required)

Assignee

User or group to which the incident is assigned.

Impact

The effect an incident has on business. Specify the impact level as an integer.

Urgency

The extent to which the incident’s resolution can be delayed. Specify the urgency level as an integer.

Priority

How quickly the service desk should address the incident. Specify the priority level as an integer.

Content

JSON representation of the request content that will be used as content. To add a short description, you can use next JSON: {"short_description":"New Short Description"}.

PropertySheet for procedure result

The property sheet where the procedure results should be saved. The default is /myJobStep.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the UpdateIncident step, click the Log button to see the diagnostic information:

UpdateRecord

This procedure returns a record from ServiceNow.

Parameter Description

Configuration Name

Name of the configuration. (Required)

Record ID

Universal field for ServiceNow records identification. SysID, Number, or Table may be specified.

For example, INC00001 will be parsed as number, incident will be parsed as table, d1552ef84f0e4200a94bdd211310c79f as sys_id and incident.d1552ef84f0e4200a94bdd211310c79f as sys_id from incident table.

Few identifiers also may be specified. Numbers should be separated by comma. For unsupported or custom tables and prefixes should be used format "table.number". For example:

INC00001,

INC00002,

d1552ef84f0e4200a94bdd211310c79f,

incident.d1552ef84f0e4200a94bdd211310c79f,

incident

my_table.MYPREFIX0123456

Filter

Filters must be written in JSON. For example: {"number": "CR1938910"}.

All field names must be the actual field names from ServiceNow and not display names. There are references, descriptions, and use case examples for this field in the plugin documentation. For more information, refer to JSON filters Using the EC-ServiceNow Filter field.

Content

JSON representation of the request content that will be used as content. To add a short description, you can use next JSON: {"short_description":"New Short Description"}.

PropertySheet for procedure result

The property sheet where the procedure results should be saved. The default is /myJobStep.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the UpdateRecord step, click the Log button to see the diagnostic information:

UpdateTasksStatuses

This procedure sets the status of one or more tasks. When the "Requested By", "Requested For", "Assignment Group", and "Approval" parameters are all specified, CloudBees CD/RO retrieves the tasks that match all of these parameters and updates their status. When the same change requests are retrieved using either the "Number(s)" parameters or a combination of the other parameters as the search criteria, CloudBees CD/RO retrieves, updates, and displays them once.

Parameter Description

Configuration Name

The name of the configuration. (Required)

New State

The new state for one or more change requests that match the search criteria: Pending, Open, Work in Progress, Closed Complete, Closed Incomplete, and Closed Skipped. The default is Pending. (Required)

Number(s)

One or more change request numbers. You can specify more than one change request number, separating them with commas.

Requested Item

The sys_id of requested item associated with the task.

Requested for

The sys_id of user for whom the request was created.

Assignment Group

The sys_id of group assigned to the task.

Approval

The approval value for the task: Not Yet Requested, Requested, Approved, or Rejected.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the UpdateTasksStatuses step, click the Log button to see the diagnostic information:

CreateRecord_NextGen

This general-purpose procedure can be used to create records in ServiceNow in place of granular procedures that have been already exposed in this plugin. This procedure integrates with ServiceNow using the REST Table API and supports the scenario wherein a User can optionally pass Display Values as opposed to System Identifiers.

Parameter Description

Configuration Name

Previously defined configuration for the plugin.

Table

Target table on ServiceNow instance, where record should be created. For example,

Table = change_request, if you are creating a Change Request

Table = change_task, if you are creating a Change Task

Short description

Short description for creating record. Note: some tables doesn’t have "short_description" field.

Content

JSON representation of the request content. Will be used as content. For example, you can set short_description with next JSON: {"short_description" : "New Short Description"}

Get Display Values

Based on this value, retrieve the display value and/or the actual value in records fields.

Possible values:

  • true: returns the display values for all fields.

  • false: returns the actual values from the database.

  • all: returns both actual and display values.

Use Input Display Values

If checked treat input values as display values.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the CreateRecord_NextGen step, click the Log button to see the diagnostic information:

GetRecords_NextGen

This general-purpose procedure can be used to retrieve records from ServiceNow in place of granular procedures that have been already exposed in this plugin. This procedure integrates with ServiceNow using the REST Table API and supports the scenario wherein a User can optionally pass Display Values as opposed to System Identifiers.

Parameter Description

Configuration Name

Previously defined configuration for the plugin.

Retrieval type

A type which will be used for records retrieval.

Possible values:

  • Sys ID - retrieve by one or more Sys IDs.

  • Number - retrieve by number.

  • ServiceNow QL - search records via ServiceNow Query Language.

Table

Table on ServiceNow instance, where records should be searched. For example,

Table = change_request, if you are searching a Change Request

Table = change_task, if you are searching a Change Task

Sys IDs

SysIDs of the target records, separated by comma, whitespace and/or newline.

Numbers

Numbers of the target records, separated by comma, whitespace and/or newline.

ServiceNow QL

A ServiceNow QL query, that could be copied in ServiceNow instance table navigation by "Copy query" link.

Get Display Values

Based on this value, retrieve the display value and/or the actual value in records fields.

Possible values:

  • true: returns the display values for all fields.

  • false: returns the actual values from the database.

  • all: returns both actual and display values.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the GetRecords_NextGen step, click the Log button to see the diagnostic information:

UpdateRecord_NextGen

This general-purpose procedure can be used to update records in ServiceNow in place of granular procedures that have been already exposed in this plugin. This procedure integrates with ServiceNow using the REST Table API and supports the scenario wherein a User can optionally pass Display Values as opposed to System Identifiers.

Parameter Description

Configuration Name

Previously defined configuration for the plugin.

Table

Target table on ServiceNow instance, where record should be updated. For example,

Table = change_request, if you are updating a Change Request

Table = change_task, if you are updating a Change Task

Sys ID

Sys ID of the target record on ServiceNow instance.

Content

JSON representation of the request content. Will be used as content. For example, you can set short_description with next JSON: \{"short_description" : "New Short Description"}

Get Display Values

Based on this value, retrieve the display value and/or the actual value in records fields.

Possible values:

  • true: returns the display values for all fields.

  • false: returns the actual values from the database.

  • all: returns both actual and display values.

Use Input Display Values

If checked treat input values as display values.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the UpdateRecord_NextGen step, click the Log button to see the diagnostic information:

DeleteRecord_NextGen

This general-purpose procedure can be used to delete records in ServiceNow in place of granular procedures that have been already exposed in this plugin. This procedure integrates with ServiceNow using the REST Table API.

Parameter Description

Configuration Name

Previously defined configuration for the plugin.

Table

Target table on ServiceNow instance, where record should be deleted. For example,

Table = change_request, if you are deleting a Change Request

Table = change_task, if you are deleting a Change Task

Sys ID

Sys ID of the target record on ServiceNow instance.

Output

After the job runs, you can view the results on the Job Details page in CloudBees CD/RO.

In the DeleteRecord_NextGen step, click the Log button to see the diagnostic information:

Examples and use cases

Using the EC-ServiceNow Filter field

The following explains:

Basic Filter field usage

The Filter field is used in the GetRecord, CollectReportingData, and UpdateRecord procedures. Filter entries can either be:

  • JSON filters: These are simple JSON filters consisting of a ServiceNow table column actual name, and a value or label. For example, {"assigned_to": "user123"}, where:

    • assigned_to is the actual name of a table column display name.

    • user123 is a username value.

      JSON based filters can not use complex filtering syntax.
  • ServiceNow query language filters: These can be either simple or complex filters consisting of ServiceNow table column actual names, values or labels, and optional operators. For example, short_descriptionISEMPTY^ORdescriptionISEMPTY^priority=1, where:

  • short_description, description, and priority are actual names of table columns display names.

  • ISEMPTY and 1 are values and labels.

  • ^OR and ^ are operators.

    For complex filters, you must use ServiceNow operators. For more information, refer to How to use ServiceNow operators in filters.

When using either filter type, always ensure you are using the actual name of the table column you want to filter for. For more information, refer to How to find the actual names of columns in ServiceNow tables.

How to find the actual names of columns in ServiceNow tables

To find the actual names of table columns in your ServiceNow tables:

  1. In ServiceNow, navigate to System Definition  Tables & Columns

  2. In the Table Names list, find the table type you want to filter for, and select its name. The Column Names list opens.

  3. In the Column Names list, find the column you need the name attribute for, and select its name. The Column Attributes list opens.

  4. In the Column Attributes list, find the name attribute in this list, and to the right of it, is the actual name of the column.

Always use actual names when constructing your simple or complex filters.

How to use ServiceNow operators in filters

When writing complex filters using ServiceNow query language, the Filters field supports using ServiceNow operators to construct complex queries. The following examples demonstrate basic usage:

  • To return only the results for incidents that are both "critical": "1" and "impact": "1" using and:

    priority=1^impact=1
  • To return the results for incidents that are either "critical": "1" and "impact": "1" using or:

    priority=1^ORimpact=1
  • To return the results for incidents that are "critical": "1" but not "impact": "1" using is not:

    priority=1^impact!=1
For a complete list of ServiceNow operators and examples, refer to the ServiceNow Operators available for filters and queries documentation.

Creating a configuration

Stored configurations are available here

Executing CheckApprovalStatus

Expected output when there are no errors

Expected log file content when approvals are found

Previous task state

Executing UpdateTasksStatuses

Expected output when there are no errors

Expected log file content when tasks were updated

Resulting task state

ServiceNow native extension plugin

Refer to the ServiceNow Marketplace for more details about this plugin. The following information is provided for the purposes of cross referencing.

This plugin refers to the CloudBees CD/RO plugin that is installed in ServiceNow to facilitate an Approval or Rejection of a Change Request by a ServiceNow user to perform an action in CloudBees CD/RO (through a Rest API call to CloudBees CD/RO) based on a Business Rule associated with change_request table. This integration would call run procedure API and run a job on CloudBees CD/RO server. This job would approve a specified stage’s Exit Gate and move a pipeline to the next stage.

Setup steps

  • Install the CloudBees CD/RO Application available in ServiceNow Store in your ServiceNow Instance going as an Admin user.

  • Upon installation the plugin will create a special user group called ServiceNowChangeApprovers with appropriate access rights in CloudBees CD/RO.

  • Activate your application.

The following demo CloudBees CD/RO and the setup required for it, is provided to illustrate the bidirectional integration between CloudBees CD/RO and ServiceNow.

Demo CloudBees CD/RO setup

Create a pipeline in CloudBees CD/RO as follows:

  • Create Change Request as first pipeline task using CreateChangeRequest procedure. Set Correlation Id and Correlation display as follows:

    • Correlation id:

/flowRuntime/$[/myPipelineRuntime/id]/stage/%StageName%/gate/POST/taskName/%GateName%

Where %StageName% is the name of the stage that contains your gate, and %GateName% is your gate’s name. Ensure the gate has the proper type: PRE or POST. No other options are allowed.

  • Correlation display:

ElectricFlow Pipeline Gate
  • Create gate with approve step on that pipeline.

  • Create task that should be performed only if pipeline gate has been approved.

servicenow add change approvers

Demo CloudBees CD/RO

  • User creates change request on ServiceNow instance using EC-ServiceNow plugin on CloudBees CD/RO.

  • After change request becomes approved (or rejected) on ServiceNow side, ServiceNow, using CloudBees CD/RO application, sends notification to CloudBees CD/RO where EC-ServiceNow is installed.

  • EC-ServiceNow, using an internal procedure, approves (or rejects) Pipeline Gate, that is waiting on decision.

  • Pipeline is continued or aborted.

Configure self-signed certificates for EC-ServiceNow

This section is only applicable when your ServiceNow instance is installed on your hardware, within your environment, and disabling SSL validation goes against your policies.

Normally, ServiceNow instances are running on ServiceNow hardware, where their certificates are valid, and those instances are generally available through the internet. However, in cases where you must install and configure your certificate(s) on an agent, you can either:

  • Install your self-signed certificate as a single file:

    1. Copy your certificate file to the agent filesystem that runs your plugin procedures/pipelines.

      All follow-on steps that refer to an agent are referring to this agent.
    2. Set the environment variable PERL_LWP_SSL_CA_FILE or HTTPS_CA_FILE with the path to your agent certificate file location. For information on how to set an environment variable on your agent, refer to SDA Documentation.

PERL_* environment variables take priority over HTTPS_* environment variables. If both are set, PERL_* variables override HTTPS_* variables and are used by the plugin. It is recommended to use PERL_* environment variables as the default type for your environment variables.
  • Install a folder with your self-signed certificates:

    1. Copy your certificates folder to the filesystem of the agent that runs your plugin procedures/pipelines.

      All follow-on steps that refer to an agent are referring to this agent.
    2. Ensure the certificates in the folder are properly hashed. For more details, refer to openssl certhash command reference.

    3. Set the environment variable PERL_LWP_SSL_CA_FILE or HTTPS_CA_FILE with the path to your agent certificate folder location. For information on how to set an environment variable on your agent, refer to SDA Documentation.

PERL_* environment variables take priority over HTTPS_* environment variables. If both are set, PERL_* variables override HTTPS_* variables and are used by the plugin. It is recommended to use PERL_* environment variables as the default type for your environment variables.

Release notes

EC-ServiceNow 3.2.6

  • Improved SSL/TLS certificate validation to ensure that when the Ignore SSL issues parameter is selected that SSL/TLS validation is properly disabled.

EC-ServiceNow 3.2.5

  • Update tooltips and documentation for Filter field in GetRecord and UpdateRecord procedures to designate only JSON can be used.

  • Updated the ServiceNow Store application link for CloudBees CD/RO in the plugin configuration.

  • Tested plugin with ServiceNow Vancouver.

EC-ServiceNow 3.2.4

  • Updated tooltips and added uses cases for the Filter field used in the GetRecord, CollectReportingData, and UpdateRecord procedures.

EC-ServiceNow 3.2.3

  • Old configurations are deprecated and disabled. Starting with EC-ServiceNow 3.2.3, the Platform UI does not allow you to create new plugin configurations. Selecting the "Create Configuration" link in the Platform UI now redirects to "Configure Plugin" of the new CloudBees CD/RO UI.

EC-ServiceNow 3.2.2

  • An issue with proxies using SSL bump has been fixed.

EC-ServiceNow 3.2.1

  • An issue with parameters retrieval for new plugin configurations has been fixed.

EC-ServiceNow 3.2.0

  • The plugin configuration has been improved. A new Ignore SSL Errors checkbox has been added to the plugin configuration.

EC-ServiceNow 3.1.1

  • If the Use CloudBees CD Application? checkbox was selected, it did not have any effect on the configuration. This issue has been resolved.

EC-ServiceNow 3.1.0

  • Plugin has been improved to support new plugin management system and new configurations.

  • Added session validation.

EC-ServiceNow 3.0.1

  • The minimal required CloudBees CD/RO version has been set to 10.3.

EC-ServiceNow 3.0.0

  • The plugin is switched to new Perl now. No backward compatibility with releases prior 10.3. Starting from this release new agent is required to run this plugin’s procedures.

EC-ServiceNow 2.10.2

  • Fixed a bug when plugin was ignoring proxy url settings.

EC-ServiceNow 2.10.1

  • Updated plugin documentation.

EC-ServiceNow 2.10.0

  • Plugin configuration has been improved to support external credentials.

EC-ServiceNow 2.9.1

  • The documentation has been migrated to the main documentation site.

EC-ServiceNow 2.9.0

  • New features have been added to CollectReportingData procedure: TableAPI support and "dot-walking" feature.

EC-ServiceNow 2.8.1

  • Renaming to "CloudBees CD/RO".

EC-ServiceNow 2.8.0

The following new procedures have been added to provide a Robust Integration with ServiceNow using Rest Table API. In addition, a user can optionally pass Display Values as opposed to system identifiers.

  • CreateRecord_NextGen

  • GetRecords_NextGen

  • UpdateRecord_NextGen

  • DeleteRecord_NextGen

AttachChangeTasksToChangeRequest procedure has been fixed to handle the scenario wherein the ServiceNow instance does not have AgileManagement tables.

GetRecord procedure has been fixed to handle the scenario wherein the ServiceNow instance does not have AgileManagement tables.

EC-ServiceNow 2.7.0

  • Added AttachChangeTasksToChangeRequest procedure.

  • Added GetChangeTasks procedure.

  • Improved CreateConfiguration and EditConfiguration procedures. Now it is possible to test connection to endpoint.

  • Improved CreateChangeTask procedure. Now it is possible to attach Change Task to existing Change Request during creation.

  • Fixed minor issue with a configuration form when warning was displayed when the widget was opened.

  • Fixed logging to property.

  • Fixed missing newline in log messages.

EC-ServiceNow 2.6.0

  • "Log Level" parameter has been added to the plugin configuration.

EC-ServiceNow 2.5.0

  • Added CreateChangeTask procedure.

  • Improved CreateConfiguration and CreateChangeRequest procedures. Now it is possible to use CreateChangeRequest and CreateChangeTask procedures without installed ElectricFlow Release application on ServiceNow side.

  • Improved ApproveOrRejectPipelineGate procedures. Added possibility to approve manual tasks in pipeline steps.

EC-ServiceNow 2.4.1

  • Updated documentation.

EC-ServiceNow 2.4.0

  • Added support for ServiceNow Agile/Release Module Objects.

  • Improved error message when using unknown record ID number prefix.

  • Fixed creating configuration by user with "@" in username.

EC-ServiceNow 2.3.0

  • Filter field of CollectReportingData procedure now supports ServiceNow query language.

  • Support of Release Command Center 9.0 has been added.

EC-ServiceNow 2.2.1

  • Fixed a bug when ApproveOrRejectPipelineGate was not able to approve or reject pipeline gate sometimes.

EC-ServiceNow 2.2.0

  • Support for HTTP Proxy has been provided. Customers who use HTTP proxy can specify Proxy Information (Host, Port and Credentials at the configuration level) and all procedures will use the Proxy as second credentials for authentication.

EC-ServiceNow 2.1.4

  • Configured the plugin to allow the ElectricFlow UI to create configs inline of procedure form.

  • Icon for ElectricFlow Dashboards has been added.

EC-ServiceNow 2.1.3

  • Configured the plugin to allow the ElectricFlow UI to render the plugin procedure parameters entirely using the configured form XMLs.

  • Enabled the plugin for managing the plugin configurations in-line when defining an application process step or a pipeline stage task.

EC-ServiceNow 2.1.2

  • Added drill-down support.

  • Fixed non-ascii characters in procedure forms.

EC-ServiceNow 2.1.1

  • CollectReportingData procedure has been added.

  • Bugfixes and improvements.

EC-ServiceNow 2.0.3

  • A lot of bugfixes and improvements.

EC-ServiceNow 2.0.1

  • The Content parameter was replaced with the Tagsmap parameter in the CreateIncident and UpdateIncident procedures.

EC-ServiceNow 2.0.0

  • The Plugin procedures now use the ServiceNow REST API instead of SOAP.

  • Plugin now is incompatible with previous releases.

  • Added the UpdateIncident procedures.

  • The Plugin was rewritten from scratch.

EC-ServiceNow 1.0.6

  • Added the AddRecord, CreateIncident, DeleteIncident, GetRecord, UpdateIncident, and UpdateRecord procedures.

EC-ServiceNow 1.0.3

  • Fixed the issue with configurations being cached for IE.

EC-ServiceNow 1.0.0

  • New Integration: EC-ServiceNow.