# ServiceNow plugin 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](https://www.servicenow.com). [](#_cloudbees_cdro_integration_to_servicenow)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](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6), 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.7.2025031056 Revised on February 22, 2024 [](#_updated_perl_version_required)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)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 [](#setupconfig)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: 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 plugin configuration parameters. 8. 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](/docs/cloudbees-cd-plugin-docs/latest/#plugin-ui-differences). ### [](#servicenow-plugin-configuration)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 application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) is installed on the target instance. Otherwise, no native application-specific APIs are used. The procedures affected by this selection are: * [CreateChangeRequest](#CreateChangeRequest) * [CreateChangeTask](#CreateChangeTask) If using a non-admin user in your ServiceNow instance with the **CloudBees CD application**, ensure the user has the following required roles: * `import_transformer` * `EFImportTableAdmin` Login as * **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. [](#procedures)Create ServiceNow plugin procedures -------------------------------------------------- Plugin procedures can be used in [procedure steps](/docs/cloudbees-cd/latest/procedures/), [process steps](/docs/cloudbees-cd/latest/applications-processes/plugin-process-steps), and [pipeline tasks](/docs/cloudbees-cd/latest/pipelines/example-plugin-task), allowing you to orchestrate third-party tools at the appropriate time in your component, application process, or pipeline. 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](/docs/cloudbees-cd-plugin-docs/latest/#plugin-ui-differences). * [AddRecord](#AddRecord) * [ApproveOrRejectPipelineGate](#ApproveOrRejectPipelineGate) * [AttachChangeTasksToChangeRequest](#AttachChangeTasksToChangeRequest) * [CheckApprovalStatus](#CheckApprovalStatus) * [CheckChangeRequestStatus](#CheckChangeRequestStatus) * [CollectReportingData](#CollectReportingData) * [CreateChangeRequest](#CreateChangeRequest) * [CreateChangeTask](#CreateChangeTask) * [CreateIncident](#CreateIncident) * [CreateRecord\_NextGen](#CreateRecord_NextGen) * [DeleteIncident](#DeleteIncident) * [DeleteRecord\_NextGen](#DeleteRecord_NextGen) * [GetRecord](#GetRecord) * [GetRecords\_NextGen](#GetRecords_NextGen) * [GetChangeTasks](#GetChangeTasks) * [SetChangeRequestStatus](#SetChangeRequestStatus) * [UpdateIncident](#UpdateIncident) * [UpdateRecord](#UpdateRecord) * [UpdateRecord\_NextGen](#UpdateRecord_NextGen) * [UpdateTasksStatuses](#UpdateTasksStatuses) ### [](#AddRecord)AddRecord Adds a record to ServiceNow. #### [](#_addrecord_input_parameters)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`. ### [](#ApproveOrRejectPipelineGate)ApproveOrRejectPipelineGate Approve or reject a CloudBees CD/RO pipeline gate to trigger an action in ServiceNow. The `ServiceNowChangeApprovers` group must be added as an approver for the gate. This approver was created when the [CloudBees CD application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) was installed in your ServiceNow instance. If you are using a legacy plugin configuration, ensure the `ServiceNowChangeApprovers` group is configured with permissions for your current **EC-ServiceNow** project. #### [](#_approveorrejectpipelinegate_input_parameters)ApproveOrRejectPipelineGate input parameters Table 2. ApproveOrRejectPipelineGate input parameters Parameter Description Correlation ID Required. Provide the path for the REST call using the pattern: /flowRuntime/$[/myPipelineRuntime/id]/stage//gate/POST/taskName/ For example, `/flowRuntime/$[/myPipelineRuntime/id]/stage/Stage-1/gate/POST/taskName/out1`, where: * `$[/myPipelineRuntime/id]`: Property for the current runtime ID. * `stage/Stage-1`: Pipeline stage name **Stage-1**. * `gate/POST/taskName/out1`: **POST** call for the **out1** gate. Action Required. To approve the gate, enter `1`. To reject the gate, enter `0`. ### [](#AttachChangeTasksToChangeRequest)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)AttachChangeTasksToChangeRequest input parameters Table 3. 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)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)CheckApprovalStatus input parameters Table 4. 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)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)CheckChangeRequestStatus input parameters Table 5. 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)CollectReportingData Creates an incident report and sends it to CloudBees CD/RO. #### [](#_collectreportingdata_input_parameters)CollectReportingData input parameters Table 6. 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](https://docs.servicenow.com/en-US/bundle/utah-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html) (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](#filter-field-usage). 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)CreateChangeRequest Creates a new change request in the ServiceNow instance. * If the **Correlation ID** and **Correlation Display** parameters are specified and the [CloudBees CD application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) 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 application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) on your ServiceNow instance from the ServiceNow Store and the **Use CloudBees CD Application?** parameter must be selected in the [ServiceNow plugin configuration parameters](#servicenow-plugin-configuration). If you have not installed the [CloudBees CD application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6), you can disable the **Use CloudBees CD Application?** parameter or use the [AddRecord](#AddRecord) procedure to create a change request. If you decide to use a non-admin user in the ServiceNow instance with the enabled CloudBees CD application, you must ensure that the user has the required **import\_transformer** and **EFImportTableAdmin** roles. #### [](#_createchangerequest_input_parameters)CreateChangeRequest input parameters Table 7. 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 1` 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 application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6). * For integration, the **Correlation Display** parameter must also be configured. Correlation Display Triggers the native ServiceNow [CloudBees CD application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6). * This parameter is only used for bidirectional integration with the native ServiceNow CloudBees CD application and the parameter value must be set to `ElectricFlow Pipeline Task`, to trigger the native ServiceNow CloudBees CD 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)CreateChangeTask Creates a new Change Task in the ServiceNow instance. * If the **Correlation ID** and **Correlation Display** parameters are specified and the [CloudBees CD application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) 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 application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) on your ServiceNow instance from the ServiceNow Store and the **Use CloudBees CD Application?** must be selected in the [ServiceNow plugin configuration parameters](#servicenow-plugin-configuration). If you have not installed the [CloudBees CD application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6), you can disable the **Use CloudBees CD Application?** parameter or use the [AddRecord](#AddRecord) procedure to create a change request. If you decide to use a non-admin user in the ServiceNow instance with the enabled CloudBees CD application, you must ensure that the user has the required **import\_transformer** and **EFImportTableAdmin** roles. #### [](#_createchangetask_input_parameters)CreateChangeTask input parameters Table 8. 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 1` 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 application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6). * For integration, the **Correlation Display** parameter must also be configured. Correlation Display Triggers the native ServiceNow [CloudBees CD application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6). * This parameter is only used for bidirectional integration with the native ServiceNow CloudBees CD application and the parameter value must be set to `ElectricFlow Pipeline Task`, to trigger the native ServiceNow CloudBees CD 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)CreateIncident Creates an incident in ServiceNow. #### [](#_createincident_input_parameters)CreateIncident input parameters Table 9. 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)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)CreateRecord\_NextGen input parameters Table 10. 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)DeleteIncident Deletes an incident in ServiceNow. #### [](#_deleteincident_input_parameters)DeleteIncident input parameters Table 11. DeleteIncident input parameters Parameter Description Configuration Name Required. Name of the configuration. Sys ID Required. `sys_id` of the incident. ### [](#DeleteRecord_NextGen)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)DeleteRecord\_NextGen input parameters Table 12. 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)GetChangeTasks Retrieves change tasks from the ServiceNow change tasks table. #### [](#_getchangetasks_input_parameters)GetChangeTasks input parameters Table 13. 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)GetRecord Returns a record from ServiceNow. #### [](#_getrecord_input_parameters)GetRecord input parameters Table 14. 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](#filter-field-usage). 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)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)GetRecords\_NextGen input parameters Table 15. 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)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)SetChangeRequestStatus input parameters Table 16. 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)UpdateIncident Creates an incident in ServiceNow. #### [](#_updateincident_input_parameters)UpdateIncident input parameters Table 17. 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)UpdateRecord Returns a record from ServiceNow. #### [](#_updaterecord_input_parameters)UpdateRecord input parameters Table 18. 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"}`. 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 [Use the ServiceNow plugin’s **Filter** field](#filter-field-usage). 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)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)UpdateRecord\_NextGen input parameters Table 19. 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)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)UpdateTasksStatuses input parameters Table 20. 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. [](#example)ServiceNow plugin use cases --------------------------------------- ### [](#filter-field-usage)Use the ServiceNow plugin’s **Filter** field The following examples illustrate how to use the ServiceNow plugin **Filter** field: * [Basic **Filter** field usage](#basic-filter-usage) * [Find the actual names of columns in ServiceNow tables](#find-servicenow-column-names) * [Use ServiceNow operators in filters](#use-servicenow-operators) #### [](#basic-filter-usage)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](https://docs.servicenow.com/en-US/bundle/utah-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html) 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](#use-servicenow-operators). 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-servicenow-column-names). #### [](#find-servicenow-column-names)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. You must always use actual names when constructing your simple or complex filters. #### [](#use-servicenow-operators)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](https://docs.servicenow.com/en-US/bundle/utah-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html). [](#native-extension)ServiceNow CloudBees CD application -------------------------------------------------------- The [CloudBees CD application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) 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 application](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) and the ServiceNow plugin to provide bidirectional integration between CloudBees CD/RO and ServiceNow. To configure bidirectional integration between CloudBees CD/RO and ServiceNow: 1. Install the CloudBees CD application available in the [ServiceNow Store](https://store.servicenow.com/sn_appstore_store.do#!/store/application/41108e84dbe1e60060dff5f0cf9619d6) in your ServiceNow instance as an **Admin** user. * If you do not install the CloudBees CD application as an **Admin** user, it must have the following rights to function: * `import_transformer` * `EFImportTableAdmin` 2. Upon installation, the application creates a special user group named **ServiceNowChangeApprovers** with appropriate access rights in CloudBees CD/RO. 3. Activate the CloudBees CD application in ServiceNow. 4. In CloudBees CD/RO, use the [CreateChangeRequest](#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 5. Create a pipeline gate with an approval step for that pipeline. 6. Create a pipeline task that should be performed only if the pipeline gate has been approved. 7. Create a change request on the ServiceNow instance using the ServiceNow plugin in CloudBees CD/RO. 8. 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. 9. The ServiceNow plugin uses an internal procedure to approve or reject the pipeline gate that is waiting on manual approval. 10. 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)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](#self-signed-certificate-single-file) * [Install a folder with your self-signed certificates](#self-signed-certificate-folder) ### [](#self-signed-certificate-single-file)Install your self-signed certificate as a single file To 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 [Configure agent environment variables](/docs/cloudbees-cd/latest/set-up-cdro/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. ### [](#self-signed-certificate-folder)Install a folder with your self-signed certificates To install a folder with your self-signed certificates: 1. 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. 2. Ensure the certificates in the folder are properly hashed. For more information, refer to [openssl certhash command reference](https://man.openbsd.org/openssl.1#certhash). 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 [Configure agent environment variables](/docs/cloudbees-cd/latest/set-up-cdro/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. [](#rns)ServiceNow plugin release notes --------------------------------------- ### [](#_3_2_7)3.2.7 * Fixed an encoding issue with ServiceNowQL parameters. ### [](#_3_2_6)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)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)3.2.4 * Updated tooltips and added use cases for the **Filter** field used in the **GetRecord**, **CollectReportingData**, and **UpdateRecord** procedures. ### [](#_3_2_3)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)3.2.2 * Fixed an issue with proxies using SSL. ### [](#_3_2_1)3.2.1 * Fixed an issue with parameters retrieval for new plugin configurations. ### [](#_3_2_0)3.2.0 * Added a new **Ignore SSL Errors** checkbox to the plugin configuration. ### [](#_3_1_1)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)3.1.0 * The plugin has been improved to support the new plugin management system and new configurations. * Added session validation. ### [](#_3_0_1)3.0.1 * The minimum required CloudBees CD/RO version is now 10.3. ### [](#_3_0_0)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)2.10.2 * Fixed an issue where the plugin improperly ignored proxy URL settings. ### [](#_2_10_1)2.10.1 * Updated the plugin documentation. ### [](#_2_10_0)2.10.0 * The plugin configuration has been improved to support external credentials. ### [](#_2_9_1)2.9.1 * The documentation has been migrated to the main documentation site. ### [](#_2_9_0)2.9.0 * Support for the Table API and dot-walking feature have been added to the **CollectReportingData** procedure. ### [](#_2_8_1)2.8.1 * Renamed to "CloudBees CD". ### [](#_2_8_0)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)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)2.6.0 * The **Log Level** parameter has been added to the plugin configuration. ### [](#_2_5_0)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)2.4.1 * Updated the documentation. ### [](#_2_4_0)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)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)2.2.1 * Fixed an issue where the **ApproveOrRejectPipelineGate** was unable to approve or reject pipeline gates. ### [](#_2_2_0)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)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)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)2.1.2 * Added drill-down support. * Fixed non-Ascii characters in procedure forms. ### [](#_2_1_1)2.1.1 * Added support for the **CollectReportingData** procedure. * Miscellaneous bug fixes and improvements. ### [](#_2_0_3)2.0.3 * Miscellaneous bug fixes and improvements. ### [](#_2_0_1)2.0.1 * The **Content** parameter was replaced with the **Tagsmap** parameter in the **CreateIncident** and **UpdateIncident** procedures. ### [](#_2_0_0)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)1.0.6 * Added support for the **AddRecord**, **CreateIncident**, **DeleteIncident**, **GetRecord**, **UpdateIncident**, and **UpdateRecord** procedures. ### [](#_1_0_3)1.0.3 * Fixed an issue with configurations being cached for Internet Explorer®. ### [](#_1_0_0)1.0.0 * Initial release.