snowtify

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

Usage

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

As a Drone Plugin

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.

As a Docker container

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

Input options

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

ServiceNow target instance

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

ServiceNow endpoints

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.

SNOW_ENDPOINT | PLUGIN_ENDPOINT

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

SNOW_PROTOCOL | PLUGIN_PROTOCOL

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

SNOW_PROD_HOST | PLUGIN_PROD_HOST

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.

SNOW_TEST_HOST | PLUGIN_TEST_HOST

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.

SNOW_PATH | PLUGIN_PATH

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

SNOW_DEPLOY_TO | DRONE_DEPLOY_TO

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.

PLUGIN_SEND_TO_PROD

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.

SNOW_PROXY | PLUGIN_PROXY

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

Authentication options

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

SNOW_USER | PLUGIN_USERNAME

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

SNOW_TEST_USER | PLUGIN_TEST_USER

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

SNOW_PROD_USER | PLUGIN_PROD_USER

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

SNOW_PASS | PLUGIN_PASSWORD

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

SNOW_TEST_PASS | PLUGIN_TEST_PASS

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

SNOW_PROD_PASS | PLUGIN_PROD_PASS

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

Message content and other options

REPO_NAME | DRONE_REPO_NAME

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.

BUILD_NUMBER | DRONE_BUILD_NUMBER

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.

SNOW_EXTERNAL_ID | PLUGIN_EXTERNAL_ID

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.

SNOW_INT_ID_FILE | PLUGIN_INTERNAL_ID_FILE

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.

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.

SNOW_NOTIFICATION_TYPE | PLUGIN_NOTIFICATION_TYPE

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.

SNOW_TITLE | PLUGIN_TITLE

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.

SNOW_START_TIME | PLUGIN_START_TIME

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.

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.

SNOW_DESC_FILE | PLUGIN_DESCRIPTION_FILE

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.

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.

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

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.

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

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.

SNOW_STATUS | PLUGIN_DEPLOYMENT_OUTCOME

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.

SNOW_DISABLED | PLUGIN_SNOW_DISABLED

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

Contributing

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.

Useful links

• Quay.io

License

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