ServiceNow plugin

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, 2024

Updated Perl version required

This plugin is using an updated version of Perl, cb-perl shell (instead of old ec-perl). This means that it requires CloudBees CD/RO agent version v10.3 or higher to work.

Integrated version

This plugin was developed and tested against following ServiceNow versions:

Washington DC
Vancouver
Utah
Paris
Orlando
New-York
Madrid (Deprecated)
London (Deprecated)
Kingston (Deprecated)
Jakarta (Deprecated)
Istanbul (Deprecated)
Helsinki (Deprecated)
Geneva (Deprecated)
Fuji (Deprecated)
Eureka (Deprecated)

Create ServiceNow plugin configurations

Plugin configurations are sets of parameters that can be applied across some, or all, 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. The following steps illustrate how to create a plugin configuration that can be used by one or more plugin procedures.

To create a plugin configuration:

Navigate to DevOps Essentials Plugin Management Plugin configurations.
Select Add plugin configuration to create a new configuration.
In the New Configuration window, specify a Name for the configuration.
Select the Project that the configuration belongs to.
Optionally, add a Description for the configuration.
Select the appropriate Plugin for the configuration.
Configure the plugin configuration parameters.
Select OK.

Depending on your plugin configuration and how you run procedures, the Input parameters Configuration name field may behave differently in the CloudBees CD/RO UI. For more information, refer to Differences in plugin UI behavior.

ServiceNow plugin configuration parameters

Parameter Description

Configuration Name

Required. Name of the plugin configuration.

Host

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

Test connection?

If selected, the connection endpoint and credentials are tested.

Use CloudBees CD Application?

If selected, EC-ServiceNow assumes the CloudBees CD/RO application is installed on the target instance. Otherwise, no native application-specific APIs are used. The procedures affected by this selection are:

CreateChangeRequest
CreateChangeTask

If you decide to use a non-admin user in the ServiceNow instance with the enabled CloudBees CD/RO application, you must ensure that the user has the required import_transformer and EFImportTableAdmin roles.

User Name: Required. Enter the username. This parameter is case-sensitive.
Password: Required. Enter the password. This parameter is case-sensitive.
Retype Password: Required. Re-enter the password. This parameter is case-sensitive.

Log Level

This option sets the debug level for logs. If Info is selected, only a summary is displayed. If Debug is selected, debug information is displayed.

HTTP Proxy

HTTP proxy used for connections.

Proxy Authorization

Username and password used to connect to the HTTP proxy.

Create ServiceNow plugin procedures

Plugin procedures can be used in procedure steps, process steps, and pipeline tasks, allowing you to orchestrate third-party tools at the appropriate time in your component, application process, or pipeline.

AddRecord
AttachChangeTasksToChangeRequest
CheckApprovalStatus
CheckChangeRequestStatus
CollectReportingData
CreateChangeRequest
CreateChangeTask
CreateIncident
CreateRecord_NextGen
DeleteIncident
DeleteRecord_NextGen
GetRecord
GetRecords_NextGen
GetChangeTasks
SetChangeRequestStatus
UpdateIncident
UpdateRecord
UpdateRecord_NextGen
UpdateTasksStatuses

AddRecord

Adds a record to ServiceNow.

AddRecord input parameters

Table 1. AddRecord input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Record ID	Required. Record ID of the incident, such as a table or number.
Content	Required. JSON representation of the request content. To add a short description, use the following JSON: `{"short_description":"New Short Description"}`.
PropertySheet for procedure result	Property sheet where the procedure results should be saved. The default is `/myJobStep`.

AttachChangeTasksToChangeRequest

Attaches one or more change tasks to a change request.

All change requests and tasks must already exist, or the procedure will fail.

AttachChangeTasksToChangeRequest input parameters

Table 2. AttachChangeTasksToChangeRequest input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Change Request Record Id	Required. Record ID of the change request to attach to the change task.
Change Tasks Record Ids	Required. Comma-separated change task record IDs of existing change tasks that should be linked to an existing change request.

CheckApprovalStatus

Checks the status of one or more approvals.

When you select the Check All parameter, all the approvals are retrieved. When you select or specify the other parameters, specific approvals are retrieved. When both the Approval For and Approver parameters are specified, CloudBees CD/RO searches for and retrieves approvals that match both parameters. When 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.

CheckApprovalStatus input parameters

Table 3. CheckApprovalStatus input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Check All	If selected, all approvals are retrieved.
Approval For	Identifier for the approval. An example of a change request is `CHG0000009`.
Approver	User or group who approves the requests.
System ID(s)	Comma-separated list of unique identifiers for an approval.

CheckChangeRequestStatus

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.

CheckChangeRequestStatus input parameters

Table 4. CheckChangeRequestStatus input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Check All	If selected, all change requests are retrieved.
Number(s)	Comma-separated list of change request numbers.
Requested By	`sys_id` of the user who requested the change request.
Assigned to	`sys_id` of the user who is assigned the change request.
Configuration Item	`sys_id` of the configuration item associated with the change request.
Category	Category assigned to the change request.
Priority	Priority assigned to the change request.
Risk	Risk assigned to the change request.
Type	Type of change request.

CollectReportingData

Creates an incident report and sends it to CloudBees CD/RO.

CollectReportingData input parameters

Parameter Description

Configuration Name

Required. Name of the configuration.

Source table

Servicenow table to retrieve reporting data from. It should be the ServiceNow table name, with no label. For example, for an incident table, it should be incident and for a 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 the ServiceNow query language (for example, priority=1^ORpriority=2).

When using JSON or the 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. For more information, refer to Use the ServiceNow plugin’s Filter field.

Preview mode

Special mode that is designed to help with report configurations. If selected, no reports are sent, no metadata is set, and high verbosity is enabled. In this mode, you can configure mappings and set the transformation before enabling automatic reporting. In this mode, each object retrieved from ServiceNow is displayed, including transformation, mapping, and final payload.

Use Table API

If selected, the ServiceNow REST Table API is used for data retrieval, instead of the default JSONv2 API. The REST Table API returns data with a different structure, thus the default mappings in the Field mapping parameter do not work. The default mappings for the REST Table API are:

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▼

When the REST Table API is enabled, you can use ServiceNow’s dot-walking feature to specify chains of field names, separated by escaped dots (periods) in the Field mapping parameter. For example:

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

Field mapping

Allows you to map custom fields to the payload, or modify the payload values. For example:

"MyApplication":releaseName maps the "MyApplication" value to the payload releaseName field.
lastBuiltRevision.SHA1:myLastRevision maps the SHA1 field from the lastBuiltRevision object to myLastRevision.
lastBuiltRevision.branch[0].SHA1:myLastRevision maps the SHA1 field from the first element of the branch array of the lastBuiltRevision object to myLastRevision.

Transform script

Allows you to provide Perl script for payload customization. This method is invoked by the plugin with two parameters; the first parameter is the context object and the second parameter is the payload object. The method should be named "transform", and should return the payload object. In this example, the 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 the property sheet used to store metadata. If omitted, the path is used depending on the context; either a schedule or procedure.

Base URL for drill-down

Drill-down URL for the records in ServiceNow.

Release Filter URI

URI used with the Base URL for drill-down, to build a drill-down URL for records in ServiceNow.

Debug

If selected, the debug level is set to Debug.

CreateChangeRequest

Creates a new change request in the ServiceNow instance.

If the Correlation ID and Correlation Display parameters are specified and the CloudBees CD/RO application is installed and enabled on the ServiceNow side, it is possible to approve the gate task in CloudBees CD/RO automatically after approval in ServiceNow.
To use this procedure for bidirectional integration, you must install the CloudBees CD/RO application on your ServiceNow instance from the ServiceNow Store and the Use CloudBees CD Application? parameter must be selected in the ServiceNow plugin configuration parameters. If you have not installed the CloudBees CD/RO application, you can disable the Use CloudBees CD Application? parameter or use the AddRecord procedure to create a change request.

CreateChangeRequest input parameters

Parameter Description

Configuration Name

Required. Name of the configuration.

Description

Required. Short description for the new change request.

Correlation ID

Used for pipeline gates, by approving or rejecting the change request on the ServiceNow side. It must contain the path for the completeManualTask REST call.

For example, /flowRuntime/$[/myPipelineRuntime/id]/stage/Stage 1/gate/POST/taskName/out1, where:

$[/myPipelineRuntime/id] is a property with the current runtime ID
stage is a pipeline stage name
out1 is the gate name with a POST type.

This parameter is only used for bidirectional integration with the native ServiceNow CloudBees CD/RO application.
For integration, the Correlation Display parameter must also be configured.

Correlation Display

Triggers the native ServiceNow CloudBees CD/RO application.

This parameter is only used for bidirectional integration with the native ServiceNow CloudBees CD/RO application and the parameter value must be set to ElectricFlow Pipeline Task, to trigger the native ServiceNow CloudBees CD/RO application.
For integration, the Correlation ID parameter must also be configured.

Content

Additional change_request table parameters.

Result Property Sheet

Property sheet where procedure results should be stored.

CreateChangeTask

Creates a new Change Task in the ServiceNow instance.

If the Correlation ID and Correlation Display parameters are specified and the CloudBees CD/RO application is installed and enabled on the ServiceNow side, it is possible to approve the gate task in CloudBees CD/RO automatically after approval in ServiceNow.
To use this procedure for bidirectional integration, you must install the CloudBees CD/RO application on your ServiceNow instance from the ServiceNow Store and the Use CloudBees CD Application? must be selected in the ServiceNow plugin configuration parameters. If you have not installed the CloudBees CD/RO application, you can disable the Use CloudBees CD Application? parameter or use the AddRecord procedure to create a change request.

CreateChangeTask input parameters

Parameter Description

Configuration Name

Required. Name of the configuration.

Description

Required. Short description for the new change task.

Correlation ID

Used for pipeline gates, by approving or rejecting the change request on the ServiceNow side. It must contain the path for the completeManualTask REST call.

For example, /flowRuntime/$[/myPipelineRuntime/id]/stage/Stage 1/gate/POST/taskName/out1, where:

$[/myPipelineRuntime/id] is a property with the current runtime ID
stage is a pipeline stage name
out1 is the gate name with a POST type.

This parameter is only used for bidirectional integration with the native ServiceNow CloudBees CD/RO application.
For integration, the Correlation Display parameter must also be configured.

Correlation Display

Triggers the native ServiceNow CloudBees CD/RO application.

This parameter is only used for bidirectional integration with the native ServiceNow CloudBees CD/RO application and the parameter value must be set to ElectricFlow Pipeline Task, to trigger the native ServiceNow CloudBees CD/RO application.
For integration, the Correlation ID parameter must also be configured.

Change Task Details

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

Change Request Record ID

Record ID of the change request to attach to the change task. The change request number or sys_id of the change request are required. Validation of this change request is performed before change task creation and the procedure fails if it does not exist.

Result Property Sheet

Property sheet where procedure results should be stored.

CreateIncident

Creates an incident in ServiceNow.

CreateIncident input parameters

Table 8. CreateIncident input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Description	Required. Short description of the incident.
Assignee	User or group to which the incident is assigned.
Impact	Impact an incident has on business. Specify the impact level as an integer.
Urgency	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. To add a short description, use the following JSON: `{"short_description":"New Short Description"}`.
PropertySheet for procedure result	Property sheet where the procedure results should be saved. The default is `/myJobStep`.

CreateRecord_NextGen

Creates records in ServiceNow in place of granular procedures that have already been exposed in this plugin. This procedure integrates with ServiceNow using the REST Table API and supports the scenario where you can optionally pass display values instead of sys_id values.

CreateRecord_NextGen input parameters

Parameter Description

Configuration Name

Required. Name of the configuration.

Table

Target table on the ServiceNow instance, where records 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 records.

Some ServiceNow tables do not have a short_description field.

Content

JSON representation of the request content. To add a short description, use the following JSON: {"short_description":"New Short Description"}.

Get Display Values

Retrieves the display value and/or the actual value in records fields.

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 selected, the input values are treated as display values.

DeleteIncident

Deletes an incident in ServiceNow.

DeleteIncident input parameters

Table 10. DeleteIncident input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Sys ID	Required. `sys_id` of the incident.

DeleteRecord_NextGen

Deletes records in ServiceNow in place of granular procedures that have already been exposed in this plugin. This procedure integrates with ServiceNow using the REST Table API.

DeleteRecord_NextGen input parameters

Table 11. DeleteRecord_NextGen input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Table	Target table on the ServiceNow instance, where the 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.

GetChangeTasks

Retrieves change tasks from the ServiceNow change tasks table.

GetChangeTasks input parameters

Table 12. GetChangeTasks input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Change Task Retrieval Type	Type used for change task retrieval. Available types: Record ID: Look up by record ID. Change Request Record ID: Look up by change request record ID. ServiceNow QL: Look up by ServiceNow QL.
Record ID	A Record ID of ServiceNow change task to retrieve.
Change Request Record ID	Record ID of the change request to attach to the change task. The change request number or `sys_id` of the change request are required. Validation of this change request is performed before change task creation and the procedure fails if it does not exist.
ServiceNow QL	A ServiceNow QL query, that can be copied in the ServiceNow instance table navigation by using the Copy query link.
Result Property Sheet	Property sheet where procedure results are saved.

GetRecord

Returns a record from ServiceNow.

GetRecord input parameters

Parameter Description

Configuration Name

Required. Name of the configuration.

Record ID

Universal field for ServiceNow records identification. The ServiceNow sys_id, number, or table may be specified. For example:

INC00001 is parsed as a number.
The incident is parsed as a table.
d1552ef84f0e4200a94bdd211310c79f is parsed as the sys_id.
incident.d1552ef84f0e4200a94bdd211310c79f is parsed as the sys_id from the incident table.

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

INC00001,

INC00002,

d1552ef84f0e4200a94bdd211310c79f,

incident.d1552ef84f0e4200a94bdd211310c79f,

incident

my_table.MYPREFIX0123456▼

Filter

Filters, formatted 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 Use the ServiceNow plugin’s Filter field.

Content

JSON representation of the request content. To add a short description, use the following JSON: {"short_description":"New Short Description"}.

PropertySheet for procedure result

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

GetRecords_NextGen

Retrieves records from ServiceNow in place of granular procedures that have already been exposed in this plugin. This procedure integrates with ServiceNow using the REST Table API and supports the scenario where you can optionally pass display values instead of sys_id values.

GetRecords_NextGen input parameters

Table 14. GetRecords_NextGen input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Retrieval type	Type that is used for record retrieval. Sys ID: Retrieve using one or more `sys_id` values. 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 for a change request. Table = `change_task`, if you are searching for a change task.
Sys IDs	`sys_id` values of the target records, separated by a comma, whitespace, and/or a newline.
Numbers	Numbers of the target records, separated by a comma, whitespace, and/or a newline.
ServiceNow QL	A ServiceNow QL query that can be copied in a ServiceNow instance table navigation by using the Copy query link.
Get Display Values	Retrieves the display value and/or the actual value in records fields. true: Returns the display values for all fields. false: Returns the actual values from the database. all: Returns both actual and display values.

SetChangeRequestStatus

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.

SetChangeRequestStatus input parameters

Table 15. SetChangeRequestStatus input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
New State	Required. New state for one or more change requests that match the search criteria.
Number(s)	Comma-separated list of change request numbers.
Requested By	`sys_id` of the user who requested the change request.
Assigned to	`sys_id` of the user assigned to the change request.
Configuration Item	`sys_id` of the configuration item associated with the change request.
Category	Category assigned to the change request.
Priority	Priority assigned to the change request.
Risk	Risk assigned to the change request.
Type	Type of change request.

UpdateIncident

Creates an incident in ServiceNow.

UpdateIncident input parameters

Table 16. UpdateIncident input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Description	Required. Short description of the incident.
Sys ID	Required. `sys_id` of the incident.
Assignee	User or group assigned to the incident.
Impact	Effect an incident has on business. Specify the impact level as an integer.
Urgency	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. To add a short description, use the following JSON: `{"short_description":"New Short Description"}`.
PropertySheet for procedure result	Property sheet where the procedure results should be saved. The default is `/myJobStep`.

UpdateRecord

Returns a record from ServiceNow.

UpdateRecord input parameters

Parameter Description

Configuration Name

Required. Name of the configuration.

Record ID

Universal field for ServiceNow records identification. sys_id, number, or table may be specified. For example:

INC00001 is parsed as a number.
The incident is parsed as a table.
d1552ef84f0e4200a94bdd211310c79f is parsed as the sys_id.
incident.d1552ef84f0e4200a94bdd211310c79f is parsed as the sys_id from the incident table.

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

INC00001,

INC00002,

d1552ef84f0e4200a94bdd211310c79f,

incident.d1552ef84f0e4200a94bdd211310c79f,

incident

my_table.MYPREFIX0123456▼

Filter

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

Content

JSON representation of the request content. To add a short description, use the following JSON: {"short_description":"New Short Description"}.

PropertySheet for procedure result

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

UpdateRecord_NextGen

Updates records in ServiceNow in place of granular procedures that have already been exposed in this plugin. This procedure integrates with ServiceNow using the REST Table API and supports the scenario where you can optionally pass display values instead of sys_id values.

UpdateRecord_NextGen input parameters

Table 18. UpdateRecord_NextGen input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
Table	Target table on ServiceNow instance, where the record should be updated. For example: Table = `change_request`, if you are creating a change request. Table = `change_task`, if you are creating a change task.
Sys ID	`sys_id` of the target record on ServiceNow instance.
Content	JSON representation of the request content. To add a short description, use the following JSON: `{"short_description":"New Short Description"}`.
Get Display Values	Retrieves the display value and/or the actual value in records fields. 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 selected, treat input values as display values.

UpdateTasksStatuses

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.

UpdateTasksStatuses input parameters

Table 19. UpdateTasksStatuses input parameters
Parameter	Description
Configuration Name	Required. Name of the configuration.
New State	Required. New state for one or more change requests that match the search criteria. The default is Pending.
Number(s)	Comma-separated list of change request numbers.
Requested Item	`sys_id` of the requested item associated with the task.
Requested for	`sys_id` of the user that the request was created for.
Assignment Group	`sys_id` of the group assigned to the task.
Approval	Approval value for the task.

ServiceNow plugin use cases

Use the ServiceNow plugin’s Filter field

The following examples illustrate how to use the ServiceNow plugin Filter field:

Basic Filter field usage
Find the actual names of columns in ServiceNow tables
Use ServiceNow operators in filters

Basic Filter field usage

The Filter field is used in the CollectReportingData, GetRecord, and UpdateRecord procedures. Valid 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 cannot 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 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 Find the actual names of columns in ServiceNow tables.

Find the actual names of columns in ServiceNow tables

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

In ServiceNow, navigate to System Definition Tables & Columns.
In the Table Names list, find the table type you want to filter for, and select its name. The Column Names list opens.
In the Column Names list, find the column you need the name attribute for, and select its name. The Column Attributes list opens.
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.

You must always use actual names when constructing your simple or complex filters.

Use ServiceNow operators in filters

When writing complex filters using the 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 Operators available for filters and queries.

Native ServiceNow CloudBees CD/RO application

The CloudBees CD/RO application 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 (via a Rest API call) based on a business rule associated with a change_request table. This integration calls a run procedure API and runs a job on the CloudBees CD/RO server. This job approves a specified stage’s exit gate and moves a pipeline to the next stage.

The following steps demonstrate how to use the CloudBees CD/RO application and the ServiceNow plugin to provide bidirectional integration between CloudBees CD/RO and ServiceNow.

To configure bidirectional integration between CloudBees CD/RO and ServiceNow:

Install the CloudBees CD/RO application available in the ServiceNow Store in your ServiceNow instance as an admin user.
Upon installation, the application creates a special user group named ServiceNowChangeApprovers with appropriate access rights in CloudBees CD/RO.
Activate the CloudBees CD/RO application in ServiceNow.
In CloudBees CD/RO, use the CreateChangeRequest procedure to create a change request as the first pipeline task.
1. Set the Correlation ID parameter as follows, where %StageName% is the name of the stage that contains your gate, and %GateName% is your gate’s name.
  /flowRuntime/$[/myPipelineRuntime/id]/stage/%StageName%/gate/POST/taskName/%GateName%
2. Set the Correlation Display parameter as follows:
  ElectricFlow Pipeline Gate
Create a pipeline gate with an approval step for that pipeline.
Create a pipeline task that should be performed only if the pipeline gate has been approved.
Create a change request on the ServiceNow instance using the ServiceNow plugin in CloudBees CD/RO.
After the change request is approved or rejected on the ServiceNow side, ServiceNow sends a notification to the CloudBees CD/RO server where the ServiceNow plugin is installed.
The ServiceNow plugin uses an internal procedure to approve or reject the pipeline gate that is waiting on manual approval.
The pipeline continues if the pipeline gate is approved or is aborted if the pipeline gate is rejected.

Configure self-signed certificates for the ServiceNow plugin

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.

Typically, ServiceNow instances are running on ServiceNow hardware, where their certificates are valid, and those instances are generally available online. 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
Install a folder with your self-signed certificates

Install your self-signed certificate as a single file

To install your self-signed certificate as a single file:

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.

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 Configure agent environment variables.

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

To install a folder with your self-signed certificates:

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

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

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 Configure agent environment variables.

ServiceNow plugin release notes

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.

3.2.5

Updated tooltips and documentation for the Filter field in the GetRecord and UpdateRecord procedures, to designate that only JSON can be used.
Updated the ServiceNow Store application link for CloudBees CD/RO in the plugin configuration.
Tested the plugin with ServiceNow Vancouver.

3.2.4

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

3.2.3

Starting from v3.2.3, legacy plugin configurations are deprecated and disabled. Additionally, the Automation Platform UI no longer supports creating new plugin configurations. Selecting Create Configuration in the Automation Platform UI redirects you to the Configure Plugin page within the updated UI where you can configure the plugin. To migrate any needed configurations, refer to the plugin configuration migration item in the service catalog.

3.2.2

Fixed an issue with proxies using SSL.

3.2.1

Fixed an issue with parameters retrieval for new plugin configurations.

3.2.0

Added a new Ignore SSL Errors checkbox to the plugin configuration.

3.1.1

Fixed an issue where the Use CloudBees CD Application? parameter was selected in the plugin configuration, but did not have any effect.

3.1.0

The plugin has been improved to support the new plugin management system and new configurations.
Added session validation.

3.0.1

The minimum required CloudBees CD/RO version is now 10.3.

3.0.0

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

2.10.2

Fixed an issue where the plugin improperly ignored proxy URL settings.

2.10.1

Updated the plugin documentation.

2.10.0

The plugin configuration has been improved to support external credentials.

2.9.1

The documentation has been migrated to the main documentation site.

2.9.0

Support for the Table API and dot-walking feature have been added to the CollectReportingData procedure.

2.8.1

Renamed to "CloudBees CD".

2.8.0

Added support for the following new procedures to provide a robust integration with ServiceNow using the REST Table API. In addition, you can now optionally pass display values instead of sys_id values.
- CreateRecord_NextGen
- GetRecords_NextGen
- UpdateRecord_NextGen
- DeleteRecord_NextGen
The AttachChangeTasksToChangeRequest and GetRecord procedures have been updated to properly handle ServiceNow instances that do not have AgileManagement tables.

2.7.0

Added support for the AttachChangeTasksToChangeRequest and GetChangeTasks procedures.
Improved the CreateConfiguration and EditConfiguration procedures. Now it is possible to test connections to endpoints.
Improved the CreateChangeTask procedure. Now it is possible to attach a change task to an existing change request during creation.
Fixed an issue with the plugin configuration, where a warning was incorrectly displayed when the widget was opened.
Fixed an issue with logging to a property.
Fixed a missing newline in log messages.

2.6.0

The Log Level parameter has been added to the plugin configuration.

2.5.0

Added support for the CreateChangeTask procedure.
Improved the CreateConfiguration and CreateChangeRequest procedures. Now it is possible to use the CreateChangeRequest and CreateChangeTask procedures without installing the ElectricFlow Release application to the ServiceNow instance.
Improved the ApproveOrRejectPipelineGate procedure by adding the option to approve manual tasks in pipeline steps.

2.4.1

Updated the documentation.

2.4.0

Added support for the ServiceNow Agile/Release Module Objects.
Improved an error message that is returned when using an unknown record ID number prefix.
Fixed creating configuration by user with "@" in username.

2.3.0

The Filter parameter in the CollectReportingData procedure now supports the ServiceNow query language.
Added support for the Release Command Center (RCC) v9.0.

2.2.1

Fixed an issue where the ApproveOrRejectPipelineGate was unable to approve or reject pipeline gates.

2.2.0

Added support for HTTP proxy. Customers who use HTTP proxy can now specify proxy information (host, port and credentials at the configuration level) and all procedures now use the proxy as secondary credentials for authentication.

2.1.4

Configured the plugin to allow the ElectricFlow UI to create configurations inline of the procedure form.
Added an icon for ElectricFlow dashboards.

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 inline when defining an application process step or a pipeline stage task.

2.1.2

Added drill-down support.
Fixed non-Ascii characters in procedure forms.

2.1.1

Added support for the CollectReportingData procedure.
Miscellaneous bug fixes and improvements.

2.0.3

Miscellaneous bug fixes and improvements.

2.0.1

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

2.0.0

The plugin procedures now use the ServiceNow REST API instead of SOAP.
The plugin now is incompatible with previous releases.
Added support for the UpdateIncident procedure.
The plugin code was refactored.

1.0.6

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

1.0.3

Fixed an issue with configurations being cached for Internet Explorer®.

1.0.0

Initial release.