Create a ServiceNow change request

4 minute read

Use this functionality to create a new change request in ServiceNow. The user must provide:

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

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 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.

Outputs

Outputs for the create change request functionality are listed below.

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 example: Basic

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"

Usage example: Configure input parameters

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, as in the example below.

Edit parameters
Figure 1. Editing parameters in a manually triggered workflow

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 the 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 creates the change request.

Usage example

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.