Query a ServiceNow change request for approval

Use this functionality to query an existing ServiceNow change request for approval.

The user must provide:

Valid credentials (Basic authentication or OAuth authentication) and the ServiceNow host URL are required.
The cr-number auto-generated during change request creation.
At least one of the following options to poll for these fields until they reach the specified values:
- The current state of the change request (specified by state-field-value).
- The value of the approval field in ServiceNow (specified by approval-field-value-approved and approval-field-value-rejected).

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

Inputs

Inputs for querying a change request for approval are listed below.

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

Outputs for the poll for approval 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.
`approval`	String	The value of the approval field in ServiceNow.
`state`	String	The current status of the change request.

Usage example: Both state and approval values

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▼

Usage example: State value

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"▼

Usage example: Approval value

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▼

Usage example: Refer to creation step output

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"▼