CloudBees action: ServiceNow operations

Use this action to perform the following ServiceNow operations using the CloudBees platform:

• Create a change request.

• Update or close a change request.

• Get the current state of a change request.

Authentication methods

The ServiceNow action supports both basic and OAuth authentication methods to connect with 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:

• Xanadu

• Washington DC

• Vancouver

Other versions of ServiceNow may work with the CloudBees platform. 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. The user must provide:

• Valid credentials and the ServiceNow host URL.

• The create action type.

Inputs

Inputs for the create change request functionality are listed below.

Table 1. Input details

Change request model field	Data type	Required?	Description
action-type	String	Yes	The type of operation is "create".
url	String	Yes	The ServiceNow host URL.
username	String	Yes	The username for authentication.
password	String	Yes	The password 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 for authentication.
short-description	String	No	A short title for easy identification.
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.

Usage examples: Creating

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

    steps:
      - name: Create ServiceNow CR with basic auth
        uses: 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
        uses: 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 }}

Check for a blackout window

If the parameter validate-blackout-window-conflict is set to true, the action performs an additional check before creating the change request.

When this parameter is set to true, you must input both planned start and end dates and times. The action checks ServiceNow for configuration of a blackout window during the planned start and end dates provided in the change request.

• If a blackout window exists during the scheduled dates, then the action fails and the change request is not created.

• If no blackout window conflict is detected, the action then proceeds to create the change request.

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
        uses: 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"

Note	Times specified in planned-start-date and planned-end-date are evaluated to be in the time zone set in your user profile.

Update or close a change request

Use this functionality to update or close an existing ServiceNow change request. The user must provide:

• Valid credentials and the ServiceNow host URL.

• The update action type.

• The unique sys_id attribute returned by the change request response.

Inputs

Inputs for the change request functionality are listed below.

Table 2. Input details

Change request model field	Data type	Required	Description
url	String	Yes	The ServiceNow host URL.
username	String	Yes	The username for authentication.
password	String	Yes	The password 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 for authentication.
action-type	String	Yes	The type of operation is "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.

Usage example: Updating

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

      - name: Update ServiceNow CR with basic auth
        uses: 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"}'

Usage example: Closing

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

      - name: Close ServiceNow CR with mandatory close fields
        uses: 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"

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

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. The user must provide:

• Valid credentials and the ServiceNow host URL.

• The get action type.

• The cr-number auto-generated during change request creation.

Inputs

Inputs for the get change request functionality are listed below.

Table 3. Input details

Change request model field	Data type	Required	Description
url	String	Yes	The ServiceNow host URL.
username	String	Yes	The username for authentication.
password	String	Yes	The password 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 for authentication.
action-type	String	Yes	The type of operation is "get".
cr-number	String	Yes	The unique number auto-generated during change request creation.

Usage example: Getting the current state

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
        uses: 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"

License

This code is made available under the MIT license.

References

• Learn more about using actions in CloudBees workflows.

• Learn about the CloudBees platform.