A utility to connect a CD pipeline to the ServiceNow API (often referred to here as snow for short).

The utility is configured via environment variables - see the config.js tests here, and the Input options section below for more details.

This utility has been designed to be used (with minimal configuration) as a drone.io plugin. The following configuration gives a basic example template of a deployment pipeline using the plugin:

matrix:                 # setup some common env vars
  SNOW_USER:            # username for basic auth
    - my-CD-robot
  SNOW_INT_ID_FILE:     # file containing ServiceNow ID for this change
    - './internal-id'

pipline:
  setup:
    ...
  
  open-snow-change:
    image: quay.io/repository/ukhomeofficedigital/snowtify
    secrets: [ snow_pass ]
    description: "Look out! We're hitting the big red button..."
  
  deploy:
    ...
  
  complete-snow-change:
    image: quay.io/repository/ukhomeofficedigital/snowtify
    secrets: [ snow_pass ]
    comments: "Yay, it worked!"
    deployment_outcome: success
  
  cancel-snow-change:
    image: quay.io/repository/ukhomeofficedigital/snowtify
    secrets: [ snow_pass ]
    comments: "Oooops, something went wrong!"
    deployment_outcome: fail

In the example above, the plugin is configured 3 times: first to send a notification of a new change (the open-snow-change job), then to report either a successfully completed or failed deployment (the complete-snow-change and cancel-snow-change jobs respectively). The options description, comments, and deployment_outcome are set as part of the plugin's configuration - these options correspond to the following environment variables: PLUGIN_DESCRIPTION, PLUGIN_COMMENTS, PLUGIN_DEPLOYMENT_OUTCOME. All of the variable names listed in the Input options section that start with PLUGIN_ can be configured directly against the drone job (without the PLUGIN_ prefix).

The .drone.yml file for this project (here) can also be used as a real example of how to notify ServiceNow as part of a deployment. The "end-to-end" test jobs give an example of sending a change creation and completion notification.

The utility can also be run as a standard docker container, as shown in the following example which sends a notification of a new change:

docker run quay.io/repository/ukhomeofficedigital/snowtify \
    -e SNOW_USER=username \
    -e SNOW_PASS=password \
    -e SNOW_EXTERNAL_ID=my-project-id \
    -e SNOW_TITLE="Another deployment" \
    -e SNOW_DESC="It's time to release that thing we changed..."

The following options exist to control - the kind of notification, and the details - that get sent to ServiceNow (snow):

It is possible to switch between the "production" and "testing" ServiceNow instances - or to specify completely custom instance endpoints. The authentication details can be explicitly specified, or a set can be provided, and the utility will guess which username and password best suit the notification (based on the SNOW_DEPLOY_TO | DRONE_DEPLOY_TO or PLUGIN_SEND_TO_PROD settings).

The endpoint (and thus the ServiceNow instance) can be set explicitly using the following option (SNOW_ENDPOINT | PLUGIN_ENDPOINT), otherwise the utility will choose the endpoint based on the other options in this section.

This defines the full exact endpoint for the ServiceNow API. If set it will override the other options in this section.

The protocol part of the URL for the ServiceNow API endpoint - the default is "https".

The host part of the URL for the production version of the ServiceNow API endpoint - the default is "lssiprod.service-now.com". Whether this host, or the Test host (described below) is used to construct the URL used for the ServiceNow API endpoint can be configured by the DEPLOY_TO settings. See

• SNOW_TEST_HOST | PLUGIN_TEST_HOST,
• SNOW_DEPLOY_TO | DRONE_DEPLOY_TO, and
• PLUGIN_SEND_TO_PROD.

The host part of the URL for the sandbox version of the ServiceNow API endpoint - the default is "lssitest.service-now.com". Whether this host, or the Production host (described above) is used to construct the URL used for the ServiceNow API endpoint can be configured by the DEPLOY_TO settings. See

• SNOW_PROD_HOST | PLUGIN_PROD_HOST,
• SNOW_DEPLOY_TO | DRONE_DEPLOY_TO, and
• PLUGIN_SEND_TO_PROD.

The path part of the URL for the ServiceNow API endpoint - the default is "api/fho/siam_in/create_transaction".

If set to "prod" (case insensitive), specifies the notification is to be sent to the production URL - the default is to send notifications to the test URL. This setting can be overridden by the drone plugin setting DEPLOY_TO_PROD. See

• PLUGIN_SEND_TO_PROD,
• SNOW_PROD_HOST | PLUGIN_PROD_HOST, and
• SNOW_TEST_HOST | PLUGIN_TEST_HOST.

If set to "true" (case insensitive), specifies the notification is to be sent to the production URL - the default is to send notifications to the test URL. If set to "true", it will override the SNOW_DEPLOY_TO and DEPLOY_TO settings. See

• SNOW_DEPLOY_TO | DRONE_DEPLOY_TO,
• SNOW_PROD_HOST | PLUGIN_PROD_HOST, and
• SNOW_TEST_HOST | PLUGIN_TEST_HOST.

Optional.

If set, this is the http proxy to use, in situations where an outbound proxy is required.

e.g. SNOW_PROXY=http://168.63.43.102:3128

The utility will decide which credentials to use based on the following order of preference:

1. USERNAME, PASSWORD configured directly against the drone plugin
2. PROD_USER, PROD_PASS configured directly against the drone plugin, but only for "production" deployments
3. SNOW_PROD_USER, SNOW_PROD_PASS environment variables are set, but only for "production" deployments
4. TEST_USER, TEST_PASS configured directly against the drone plugin, whenever not deploying to "production"
5. SNOW_TEST_USER, SNOW_TEST_PASS environment variables are set, whenever not deploying to "production"
6. SNOW_USER, SNOW_PASS environment variables are set

The username used for (basic) authentication to the ServiceNow API.

The username used for (basic) authentication to the "TEST" instance of ServiceNow API.

The username used for (basic) authentication to the "PROD" instance of ServiceNow API.

The password used for (basic) authentication to the ServiceNow API.

The password used for (basic) authentication to the "TEST" instance of ServiceNow API.

The password used for (basic) authentication to the "PROD" instance of ServiceNow API.

When run as a drone plugin, drone sets this automatically. Otherwise this can be set to indicate the project repository name, which is used to build a default external ID and change title if either are not explicitly provided. See

• SNOW_EXTERNAL_ID | PLUGIN_EXTERNAL_ID, and
• SNOW_TITLE | PLUGIN_TITLE.

When run as a drone plugin, drone sets this automatically. Otherwise this can be set to indicate the build number for the current CD pipeline, which is used to build a default external ID and change title if either are not explicitly provided. See

• SNOW_EXTERNAL_ID | PLUGIN_EXTERNAL_ID, and
• SNOW_TITLE | PLUGIN_TITLE.

A project/build ID for the current CD pipeline. If not provided a default is constructed using the template ${snow_username}-${REPO_NAME}-${BUILD_NUMBER}. See

• Authentication options for the "snow_username",
• REPO_NAME | DRONE_REPO_NAME, and
• BUILD_NUMBER | DRONE_BUILD_NUMBER.

Path to a file for storing the internal ID (when opening a new change), or retrieving the ID of the target change (when updating its status). If this is not provided when opening a new change, be sure to take note of the ID when it is printed, after the new change is successfully created. See also SNOW_INTERNAL_ID | PLUGIN_INTERNAL_ID.

Used to identify a previously opened change when updating the status and closing. Setting this will override the equivalent file-based option. See SNOW_INT_ID_FILE | PLUGIN_INTERNAL_ID_FILE.

Indicates whether opening a new change (if set to "deployment"), or closing an existing one (if set to "update" or "status update"). The value is not case sensitive. If omitted, the type will be assumed to be a "deployment", unless the "status update" comments have been set. See

• SNOW_COMMENTS | PLUGIN_COMMENTS, and
• SNOW_COMMENTS_FILE | PLUGIN_COMMENTS_FILE.

The title for the new change being opened. If not provided a default is constructed using the template: Deployment #${BUILD_NUMBER} of ${REPO_NAME}. See

• BUILD_NUMBER | DRONE_BUILD_NUMBER, and
• REPO_NAME | DRONE_REPO_NAME.

The expected time the change will commence. This value is expected to be a date-time string with the format: YYYY-MM-DD HH:mm:ss. If omitted, the current time is used as a default. See SNOW_END_TIME | PLUGIN_END_TIME.

The expected completion time of the change. This value is expected to be a date-time string with the format: YYYY-MM-DD HH:mm:ss. If omitted, a default calculated from the start time plus 30 minutes will be used, otherwise if the start time is also omitted the default will be the current time plus 30 minutes. See SNOW_START_TIME | PLUGIN_START_TIME.

NOTE: it is possible to provide an end time in the past, however to do so a start time MUST also be provided, and the start time MUST be [chronologically] before the end time.

Path to a file containing the full description of the new change - e.g. the relevant commit history, user stories, etc. See SNOW_DESC | PLUGIN_DESCRIPTION.

The full description of the new change - e.g. the relevant commit history, user stories, etc. Setting this will override the equivalent file-based option. See SNOW_DESC_FILE | PLUGIN_DESCRIPTION_FILE.

Path to a file containing any unit/integration/end-to-end testing result logs to support the new change. This is optional, as such there is no default value. See SNOW_TESTING | PLUGIN_TESTING.

Any unit/integration/end-to-end testing result logs to support the new change. This is optional, as such there is no default value. Setting this will override the equivalent file-based option. See SNOW_TESTING_FILE | PLUGIN_TESTING_FILE.

Path to a file containing more information about the outcome of the change that is being closed. Comments must be provided for a status update, either using this option or the non-file-based option. See SNOW_COMMENTS | PLUGIN_COMMENTS.

More information about the outcome of the change that is being closed. Comments must be provided for a status update, either using this option or the file-based option. Setting this will override the equivalent file-based option. See SNOW_COMMENTS_FILE | PLUGIN_COMMENTS_FILE.

This is used to indicate the outcome of a change. Set it to "success" (case insensitive) if the deployment succeeded, otherwise the change will be marked as a failure. If the utility is running as a drone plugin (as in the example above), this option can be omitted and the value will instead be picked up from the drone environment variable DRONE_BUILD_STATUS.

Setting this option to true (case insensitive), will cause snowtify to exit immediately without sending any notification.

Please feel free to add to snowtify and raise PRs with your changes. Please make sure you provide appropriate tests for changes. Snowtify follows the sem-ver versioning scheme.

• Quay.io

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.