Create a ServiceNow change request

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

Valid credentials (Basic authentication or OAuth authentication) and the ServiceNow host URL.
The create action type.

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

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

    steps:
      - name: Create 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: "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: 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 }}▼

You can use the Workflow composer to configure input parameters for a manually triggered workflow, as in the example below.

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 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: 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 planned-start-date and planned-end-date are evaluated to be in the time zone set in your user profile.