Manage ServiceNow change requests

Use the CloudBees ServiceNow actions to create and manage ServiceNow change requests from CloudBees Unify workflows. Two actions are available:

service-now: create, update/close, and get change requests.
service-now-poll-for-approval: query a change request for approval.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Authentication methods

The ServiceNow actions support both basic and OAuth authentication methods for connecting to ServiceNow.

Basic authentication: Provide a ServiceNow URL, a valid username, and a password to connect to the ServiceNow application.
OAuth authentication: In addition to a ServiceNow URL, a valid username, and a password, provide a ClientId and Client Secret for generating a bearer access token with an expiration date. This method is more secure.

Supported versions

CloudBees has tested and supports the following ServiceNow releases:

Other versions of ServiceNow may work with CloudBees Unify. If you are using a version of ServiceNow not listed above, submit a feature request with CloudBees Support.

Create a change request

Use this functionality to create a new change request in ServiceNow. You must provide valid credentials (basic or OAuth authentication) and the ServiceNow host URL, and set action-type to create.

Inputs

Table 1. Input details
Change request model field	Data type	Required?	Description
`action-type`	String	Yes	The operation type must be "create".
`url`	String	Yes	The ServiceNow host URL.
`username`	String	Yes	The username used for authentication.
`password`	String	Yes	The password used for authentication.
`client-id`	String	Required only for OAuth-based authentication.	The unique identification number of the client.
`client-secret`	String	Required only for OAuth-based authentication.	The client secret used for authentication.
`short-description`	String	No	A brief title to identify the change request.
`long-description`	String	No	Additional information about the change request ticket.
`cr-type`	String	No	The type of change request. The default value is "normal".
`state`	String	No	The current status of the change request.
`priority`	String	No	The priority of the change request.
`risk`	String	No	The risk involved in the change request.
`impact`	String	No	The impact of the change request.
`category`	String	No	The change request ticket category.
`requested-by`	String	No	The user that requested the change.
`assignment-group`	String	No	The assignment group to which the change request must be mapped.
`assigned-to`	String	No	The user to whom the change request ticket must be assigned in the assignment group.
`validate-blackout-window-conflict`	Boolean	No	Whether to check if there is a blackout window conflict. The default value is false.
`planned-start-date`	String	Required if `validate-blackout-window-conflict` is true.	The scheduled start date and time of the change request, formatted as `yyyy-mm-dd hh:mm:ss`.
`planned-end-date`	String	Required if `validate-blackout-window-conflict` is true.	The scheduled end date and time of the change request, formatted as `yyyy-mm-dd hh:mm:ss`.
`additional-parameters`	JSON string	No	Any additional parameters apart from the list provided above. Refer to the ServiceNow documentation for more information.

Unique identifiers generated by ServiceNow

Unique cr-number and sys_id identifiers are generated by ServiceNow when the ticket is successfully created.

The sys_id is a unique 32-character identifier required to update or close the ticket.
The cr-number is required to get the current state of a change request and to query a change request for approval.

Outputs

Table 2. Output details
Change request model field	Data type	Description
`number`	String	The unique change request number auto-generated during change request creation.
`sys_id`	String	The identifier auto-generated during change request creation.
`state`	String	The current status of the change request.

Usage examples

The following is an example payload for creating a change request using basic authentication:

    steps:
      - name: Create ServiceNow CR with basic auth
        id: create_cr
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ secrets.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          action-type: "create"
          cr-type: "normal"
          short-description: "Title of the CR ticket"▼

If your workflow uses a manual trigger, you can configure input parameters for the ServiceNow change request fields in the format ${{ inputs.MY_PARAMETER }}, which can then be passed to the action inputs. The following is an example payload for creating a change request using basic authentication and input parameters:

    steps:
      - name: Create ServiceNow CR with manual trigger
        id: create_cr
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ secrets.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          action-type: create
          cr-type: Normal
          short-description: ${{ inputs.Short_Description }}
          description: ${{ inputs.Description }}▼

Use the Workflow composer to configure input parameters for a manually triggered workflow.

The following is an example payload for creating a change request using OAuth-based authentication and checking for any blackout windows within the planned change request start and end dates:

    steps:
      - name: Create ServiceNow CR and check for blackout window
        id: create_cr
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ vars.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          client-id: ${{ secrets.MY_CLIENT_ID }}
          client-secret: ${{ secrets.MY_CLIENT_SECRET }}
          action-type: create
          cr-type: Normal
          short-description: 'check for blackout window'
          validate-blackout-window-conflict: true
          planned-start-date: "2025-03-06 17:00:00"
          planned-end-date: "2025-03-06 17:59:59"▼

Times specified in the planned-start-date and planned-end-date fields are evaluated to be in the UTC time zone by default. If the time zone is already configured in the ServiceNow instance, then the fields are evaluated to be in the ServiceNow-configured time zone.

If validate-blackout-window-conflict is set to true, the action performs an additional check before creating the change request. You must input both planned start and end dates and times. The action checks ServiceNow for the configuration of a blackout window during the planned start and end dates provided:

If a blackout window exists during the scheduled dates, the action fails and the change request is not created.
If no blackout window conflict is detected, the action creates the change request.

Get the current state of a change request

Use this functionality to get the current state, including any blackout window conflict status, of a ServiceNow change request. You must provide valid credentials (basic or OAuth authentication), the ServiceNow host URL, action-type: get, and the cr-number auto-generated during change request creation.

Inputs

Table 3. Input details
Change request model field	Data type	Required?	Description
`url`	String	Yes	The ServiceNow host URL.
`username`	String	Yes	The username used for authentication.
`password`	String	Yes	The password used for authentication.
`client-id`	String	Required only for OAuth-based authentication.	The unique identification number of the client.
`client-secret`	String	Required only for OAuth-based authentication.	The client secret used for authentication.
`action-type`	String	Yes	The type of operation must be "get".
`cr-number`	String	Yes	The unique number auto-generated during change request creation.

Outputs

Table 4. Output details
Change request model field	Data type	Description
`number`	String	The change request number.
`sys_id`	String	The identifier used to update the change request.
`state`	String	The current status of the change request.
`conflict_status`	String	The current conflict status of the planned dates.

Usage examples

The following is an example payload with basic authentication to get the current change request state:

    steps:
      - name: Get ServiceNow CR state with basic auth
        id: get
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ vars.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          action-type: "get"
          cr-number: "Unique ServiceNow-generated number"▼

The following is an example payload referring to the output parameter number from the change request creation step as input in the get step:

    steps:
      - name: Get ServiceNow CR with output parameter ref
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ vars.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          action-type: "update"
          cr-number: ${{ fromJSON(steps.get.outputs.servicenow_output).number }}
          description: "Updated description from CBP workflow"▼

Update or close a change request

Use this functionality to update or close an existing ServiceNow change request. You must provide valid credentials (basic or OAuth authentication), the ServiceNow host URL, action-type: update, and the sys-id returned by the change request creation response.

Inputs

Table 5. Input details
Change request model field	Data type	Required?	Description
`url`	String	Yes	The ServiceNow host URL.
`username`	String	Yes	The username used for authentication.
`password`	String	Yes	The password used for authentication.
`client-id`	String	Required only for OAuth-based authentication.	The unique identification number of the client.
`client-secret`	String	Required only for OAuth-based authentication.	The client secret used for authentication.
`action-type`	String	Yes	The type of operation must be "update" for both updating and closing a change request.
`sys-id`	String	Yes	The identifier auto-generated during change request creation.
`close-code`	String	Required for the close operation only if configured as mandatory fields in ServiceNow for closing a ticket.	The code assigned to the change request by the user closing it. For example, "successful", "successful with issues", or "unsuccessful".
`close-notes`	String	Required for the close operation only if configured as mandatory fields in ServiceNow for closing a ticket.	The notes entered by the user closing the change request.
`short-description`	String	No	A short title for easy identification.
`description`	String	No	Additional information about the change request ticket.
`cr-type`	String	No	The type of change request. The default value is "normal".
`state`	String	No	The current status of the change request (matches the ServiceNow configuration).
`priority`	String	No	The priority of the change request.
`risk`	String	No	The risk involved in the change request.
`impact`	String	No	The impact of the change request.
`category`	String	No	The change request ticket category.
`requested-by`	String	No	The user that requested the change.
`assignment-group`	String	No	The assignment group to which the change request must be mapped.
`assigned-to`	String	No	The user to whom the change request ticket must be assigned in the assignment group.
`additional-parameters`	JSON String	No	Any additional parameters apart from the list provided above. Refer to the ServiceNow documentation for more information.

Outputs

Table 6. Output details
Change request model field	Data type	Description
`sys_id`	String	The identifier used for change request updates.
`state`	String	The current status of the change request.

Usage examples: Update a change request

The following is an example payload for updating a change request using basic authentication:

      - name: Update ServiceNow CR with basic auth
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ secrets.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          action-type: "update"
          sys-id: "the unique system-generated string"
          description: "Updated description from CBP workflow"
          priority: "3 - Moderate"
          risk: "Low"
          additional-parameters : '{"risk_impact_analysis":"Describe the risks here","implementation_plan": "Describe the implementation plan here"}'▼

The following is an example payload referring to the output parameter sys_id from the change request creation step as input in the update step:

      - name: Update ServiceNow CR with output parameter ref
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ secrets.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          action-type: "update"
          sys-id: ${{ fromJSON(steps.create_cr.outputs.servicenow_output).sys_id }}
          description: "Updated description from CBP workflow"
          priority: "3 - Moderate"
          risk: "Low"
          additional-parameters : '{"risk_impact_analysis":"Describe the risks here","implementation_plan": "Describe the implementation plan here"}'▼

Usage examples: Close a change request

The following is an example payload for closing a change request:

      - name: Close ServiceNow CR with mandatory close fields
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ vars.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          client-id: ${{ secrets.MY_CLIENT_ID }}
          client-secret: ${{ secrets.MY_CLIENT_SECRET }}
          action-type: "update"
          sys-id: "Unique ServiceNow-generated identifier"
          state: "close"
          close-code: "successful"
          close-notes: "Change request closed in successful state"▼

The following is an example payload referring to the output parameter sys_id from the change request creation step as input in the close step:

      - name: Close ServiceNow CR with output parameter ref
        uses: https://github.com/cloudbees-io/service-now@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ secrets.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          client-id: ${{ secrets.MY_CLIENT_ID }}
          client-secret: ${{ secrets.MY_CLIENT_SECRET }}
          action-type: "update"
          sys-id: ${{ fromJSON(steps.create_cr.outputs.servicenow_output).sys_id }}
          state: "close"
          close-code: "successful"
          close-notes: "Change request closed in successful state"▼

For information about using input parameters in a manually triggered workflow, refer to the Create change request usage example.

Query a change request for approval

Use this functionality to query an existing ServiceNow change request for approval. You must provide valid credentials (basic or OAuth authentication), the ServiceNow host URL, the cr-number auto-generated during change request creation, and at least one of the following:

The current state to poll for, specified by state-field-value.
The approval and rejection values to poll for, specified by approval-field-value-approved and approval-field-value-rejected.

Inputs

Table 7. Input details
Change request model field	Data type	Required?	Description
`url`	String	Yes	The ServiceNow host URL.
`username`	String	Yes	The username used for authentication.
`password`	String	Yes	The password used for authentication.
`client-id`	String	Required only for OAuth-based authentication.	The unique identification number of the client.
`client-secret`	String	Required only for OAuth-based authentication.	The client secret used for authentication.
`cr-number`	String	Yes	The unique number auto-generated during change request creation.
`poll-interval`	String	No	The polling interval, in minutes, for the action to periodically check the approval status in ServiceNow. Default is `3`, and the maximum interval time allowed is `5760` minutes.
`poll-duration`	String	No	The maximum time duration, in minutes, for the action to continue polling for approval status in ServiceNow. Default is `60`, and the maximum duration allowed is `5760` minutes.
`state-field-value`	String	Required if `approval-field-value-approved` and `approval-field-value-rejected` are not specified.	The value of the state field in ServiceNow. The action continues to poll until the state field in ServiceNow matches `state-field-value`.
`approval-field-value-approved`	String	Required if `approval-field-value-rejected` is specified.	The value of the approval field in ServiceNow that indicates the change request is approved. The action continues to poll until the approval field in ServiceNow is either "approved" or "rejected".
`approval-field-value-rejected`	String	Required if `approval-field-value-approved` is specified.	The value of the approval field in ServiceNow which indicates that the change request is rejected. The action continues to poll until the approval field in ServiceNow is either "approved" or "rejected".

Outputs

Table 8. Output details
Change request model field	Data type	Description
`number`	String	The unique change request number auto-generated during change request creation.
`sys_id`	String	The identifier auto-generated during change request creation.
`approval`	String	The value of the approval field in ServiceNow.
`state`	String	The current status of the change request.

Usage examples

The following is an example payload for querying a change request for approval using OAuth-based authentication and both state and approval values:

      - name: Query ServiceNow CR with state and approval fields
        uses: https://github.com/cloudbees-io/service-now-poll-for-approval@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ vars.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          client-id: ${{ secrets.MY_CLIENT_ID }}
          client-secret: ${{ secrets.MY_CLIENT_SECRET }}
          cr-number: "Unique ServiceNow-generated number"
          poll-interval: 5
          poll-duration: 120
          state-field-value: "Ready for deploy"
          approval-field-value-approved: approved
          approval-field-value-rejected: rejected▼

The following is an example payload for querying a change request for approval using basic authentication and the state value:

      - name: Query ServiceNow CR with state field
        uses: https://github.com/cloudbees-io/service-now-poll-for-approval@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ vars.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          cr-number: "Unique ServiceNow-generated number"
          poll-interval: 3
          poll-duration: 60
          state-field-value: "Ready for deploy"▼

The following is an example payload for querying a change request for approval using OAuth-based authentication and approval values:

      - name: Query ServiceNow CR with approval fields
        uses: https://github.com/cloudbees-io/service-now-poll-for-approval@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ vars.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          client-id: ${{ secrets.MY_CLIENT_ID }}
          client-secret: ${{ secrets.MY_CLIENT_SECRET }}
          cr-number: "Unique ServiceNow-generated number"
          poll-interval: 15
          poll-duration: 2000
          approval-field-value-approved: approved
          approval-field-value-rejected: rejected▼

The following is an example referring to the output parameter number from the change request creation step as input in the poll for approval step:

      - name: Query ServiceNow CR with output parameter ref
        uses: https://github.com/cloudbees-io/service-now-poll-for-approval@v1
        with:
          url: ${{ vars.SERVICENOW_URL }}
          username: ${{ vars.MY_SERVICENOW_USERNAME }}
          password: ${{ secrets.MY_SERVICENOW_PASSWORD }}
          client-id: ${{ secrets.MY_CLIENT_ID }}
          client-secret: ${{ secrets.MY_CLIENT_SECRET }}
          cr-number: ${{ fromJSON(steps.create_cr.outputs.servicenow_output).number }}
          poll-interval: 3
          poll-duration: 60
          state-field-value: "Ready for deploy"▼

Manage ServiceNow change requests

Authentication methods

Supported versions

Create a change request

Inputs

Unique identifiers generated by ServiceNow

Outputs

Usage examples

Get the current state of a change request

Inputs

Outputs

Usage examples

Update or close a change request

Inputs

Outputs

Usage examples: Update a change request

Usage examples: Close a change request

Query a change request for approval

Inputs

Outputs

Usage examples

Related pages