ServiceNow CI/CD

Version: 1.0Minimum Jenkins requirement: 2.176.1ID: servicenow-cicd
Installs: 5
Last released:
Maintainers
ServiceNow

Documentation GitHub release Jenkins CI Jenkins Plugin Installs Contributors

About the plugin

This plugin provides build steps with easy parameter setup to help you get started faster with setting up a CI and CD pipeline for developing apps on the Now Platform.

This plugin integrates with Jenkins the Now Platform from ServiceNow. For bug reports, see bugs or all open issues. For documentation, see official plugin site.


Table of contents generated with markdown-toc

CI/CD integration with platform NOW

The plugin delivers additional build steps that can be used in order to integrate CI / CD actions made on NOW platform using Jenkins as main Ci / CD tool. There are currently 7 build steps that can execute remotely action on the platform NOW. All of them starts from the phrase "SN" (like ServiceNow).

Build Steps

Build steps

SN: Apply changes

Starts applying changes from a remote source control to a specified local application. The source control must be configured on the platform. There is available a bunch of configuration together with the build step:

Apply changes

  Description
Url ServiceNow instance url, where an application will be published
Credentials User name and password defined in global credentials and configured in Jenkins (credentials ID is required here)
API version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.
Application scope Required if Application system id is not specified. The scope name of the application for which to apply the changes, such as x_aah_custom_app. You can locate this value in the scope field in the Custom Application [sys_app] table.
Application system id Required if Application scope is not specified. The system id of the application for which to apply the changes. You can locate this value in the Sys ID field in the Custom Application [sys_app] table.
Branch name Name of the branch in the source control system from which to acquire the application.

SN: Publish application

Publishes the specified application and all of its artifacts to the application repository.

Publish application

  Description
Application version Version under which to store the application. Provide 2 significant numbers separated by '.' eg. 1.0 (the third number will be automatically added with build number, what gives eg. 1.0.106).
If the version number is passed, the publish process uses that version and updates the local application version if different. If the version number is not passed, the publish process uses the current version of the local application.
Calculate next application version Calculate next application version that will be published. Retrieve it in smart way using API or source control (if SCM is configured for the build). API has the highest priority, then SCM will be used.
The value from 'Application version' will be ignored.
Url ServiceNow instance url, where an application will be published
Credentials User name and password defined in global credentials and configured in Jenkins (credentials ID is required here)
API version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.
Application scope Required if Application system id is not specified. The scope name of the application for which to apply the changes, such as x_aah_custom_app. You can locate this value in the scope field in the Custom Application [sys_app] table.
Application system id Required if Application scope is not specified. The system id of the application for which to apply the changes. You can locate this value in the Sys ID field in the Custom Application [sys_app] table.
Developer notes Developer notes to store with the application.

SN: Install application

Installs the specified application from the application repository onto the local instance, the instance defined in the field Url. The application must have been previously published, using the build step SN: Publish application.

Install application

  Description
Application version Version of the application to install. If empty, the published version will be used.
Url ServiceNow instance url, where an application will be published.
Credentials User name and password defined in global credentials and configured in Jenkins (credentials ID is required here).
API version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.
Application scope Required if Application system id is not specified. The scope name of the application for which to apply the changes, such as x_aah_custom_app. You can locate this value in the scope field in the Custom Application [sys_app] table.
Application system id Required if Application scope is not specified. The system id of the application for which to apply the changes. You can locate this value in the Sys ID field in the Custom Application [sys_app] table.

SN: Roll back application

Initiates a rollback of a specified application to a specified version, according to the configuration done in the build step. If the field Application rollback version is empty and one of the previous steps was SN: Install application, then the downgrade version will be the one before the installation of the application.

Roll back application

  Description
Application rollback version Expected rollback version. This version is compared to the version that is included in the last rollback context, if they don't match, the build step fails.
If empty, last installed version from previous step will be taken.
  Other parameters like described above.

SN: Run test suite with results

Starts a specified automated test suite. The test suite runs on the instance pointed in Url or configured via ServiceNow Parameters in Installation instance.

Run test suite

  Description
Test suite name Required if Test suite sys_id is not specified. The name of the test suite to run. This value is located in the Test [sys_atf_test_suite] table.
Test suite sys_id Required if Test suite name is not specified. The sys_id of the test suite to run. This value is located in the Test [sys_atf_test_suite] table.
OS name Name of the operating system under which to run the test suite. This value must match what is specified in the scheduled client test runner.
OS version Starting value of the version of the operating system under which to run the test suite. For example, if you enter "8", that would enable all 8.x.x.x versions. This value must match what is specified in the scheduled client test. runner.
Browser name Name of the browser to use to run the client test. This value must match what is specified in the scheduled clienttest runner. For additional information on scheduled client test runners, see Scheduled Client Test Runners.

Valid values:
  • Any
  • Chrome
  • Firefox
  • Edge
  • IE
  • Safari
Browser version Starting value of the version of the browser specified in browser_name to use to run the test. For example, if you enter "9", that would enable all 9.x.x.x versions. This value must match what is specified in the scheduled client test runner.
Show results If the checkbox is checked, then results from ServiceNow will be visible in Output Console, together with the link to the visualization on the NOW platform.
  Other parameters like described above.

SN: Activate plugin

Activates the specified plugin.

Activate plugin

  Description
Plugin identifier Unique identifier of the plugin. You can locate this identifier on the Plugins page within the card of the desired plugin; identified with the name "ID".
Url Url of the instance where the plugin should be activated. The field cannot be empty. The url is not taken from ServiceNow Parameters!
Credentials The field cannot be empty. Credentials are not taken from ServiceNow Parameters!

SN: Roll back plugin

Rolls back the specified plugin to the previous installed version. If no prior version has been installed, the build step will fail.

Roll back plugin

Description of the fields is exactly the same as in the section SN: Activate plugin

Global build parameters

Together with the plugin comes additional parameter ServiceNow Parameters under the checkbox This project is parameterized in General section of the build configuration.

ServiceNow Parameters

This new parameter or - better to say - set of configuration variables allows user to configure most of the steps (integrated with the platform NOW) in convenient way from one place. You can find below description of each field, that was implemented here:

Configuration of ServiceNow Parameters

  Description
Credentials for publishing instance Credentials ID configured in Jenkins and used to get access to the instance were an application will be or is already published.
Publishing instance ServiceNow instance url where the application will be published to.
Credentials for installation instance User name and password defined in global credentials (credentials ID is required here) used for the instance where the application will be installed.
Installation instance ServiceNow instance url where the application will be installed.
System ID The system id of the application for which to apply the changes. You can locate this value in the Sys ID field in the Custom Application [sys_app] table.
Application scope The scope name of the application for which to apply the changes, such as x_aah_custom_app. You can locate this value in the scope field in the Custom Application [sys_app] table.
Published application version Version number of published application (that will be also installed if appropriate build step will be used). Do not fill the field up if you want to get the number automatically (depends on the build step Publish application).
Rolled back application version Version number of the application used by the step Roll back application. Do not fill this field up if the version should be obtained automatically.
Progress check interval Time in milliseconds between one and another progress check set up for all build steps of ServiceNow. Leave it empty to use default value.

How to use

All build steps delivered by ServiceNow except SN: Activate plugin and SN: Roll back plugin use some variables defined under ServiceNow Parameters.

System ID and Application scope are used by all SN build steps related to an application, only then when local parameters of those build steps are not configured (are blank).

Url and Credentials for publishing instance are used only by SN: Apply changes and SN: Publish application, if they do not have specified local adequate parameters.

Url and Credentials for installation instance are used only by SN: Install application, SN: Roll back application and SN: Run test suite with results, if they do not have specified local adequate parameters.


One thing is worth to mention. There are some dependencies between following 3 build steps:

When an application is published, and the new version is calculated automatically (Calculate next application version is checked in the publishing step), the published version of the application must be stored for the installation step. This stored variable will be used as information what version of the application should be installed. The field from ServiceNow Parameters - Published application version - is used for this purpose. It means, that in most cases the field will be empty and not used by a user. However, the field can be used if we want to specify what exactly version should be used for publishing and/or installation (we do not have to combine these 2 steps together, they can be used separately in a build configuration).
Similar case concerns also steps regarding installation and rolling back of the application. When an application is installed, the installation step receives also information about previously installed version, so the Roll back application step can downgrade successfully the application if needed. That information is stored in the field Rolled back application version and can be used with provided value as described in previous case, if the user knows exactly what version should be there.

Scripting

Build steps

There is also possibility to write pipeline scripts using integrated build steps. You can find keywords of all steps described above, together with configuration parameters. All names should be self-explanatory.
There is also Pipeline Syntax in Jenkins with Snippet Generator to make easy translation from UI configuration into scripting language.

Build step Parameters
snApplyChanges
  • apiVersion
  • appScope
  • appSysId
  • branchName
  • credentialsId
  • url
snPublishApp
  • apiVersion
  • appScope
  • appSysId
  • appVersion
  • credentialsId
  • devNotes
  • obtainVersionAutomatically
  • url
snInstallApp
  • apiVersion
  • appScope
  • appSysId
  • appVersion
  • credentialsId
  • url
snRollbackApp
  • apiVersion
  • appScope
  • appSysId
  • credentialsId
  • rollbackAppVersion
  • url
snRunTestSuite
  • apiVersion
  • browserName
  • browserVersion
  • credentialsId
  • osName
  • osVersion
  • testSuiteName
  • testSuiteSysId
  • url
  • withResults
snActivatePlugin
  • apiVersion
  • credentialsId
  • pluginId
  • url
snRollbackPlugin
  • apiVersion
  • credentialsId
  • pluginId
  • url

ServiceNow Parameters

ServiceNow Parameters can be also used in a pipeline scripting. They should be defined within parameters section and the parameter named as snParam. Some examples of defined SN Parameters can be found in the paragraph Samples.
The parameter includes following arguments (names should be self-explanatory):

  • credentialsForPublishedApp
  • instanceForPublishedAppUrl
  • credentialsForInstalledApp
  • instanceForInstalledAppUrl
  • sysId
  • appScope
  • publishedAppVersion
  • rollbackAppVersion
  • progressCheckInterval

Samples

The section covers pipeline scripting with 3 examples using features like build steps and the parameter developed by ServiceNow. All examples can be used in Pipeline type job or as independent Jenkinsfile in a source control connected with NOW platform.

  1. Simple script with one step Apply changes under a stage called preparation.
pipeline {
    agent any

    stages {
        stage('preparation') {
            steps {
                snApplyChanges url: "https://cicdjenkinsapppublish.service-now.com", credentialsId: "88dbbe69-0e00-4dd5-838b-2fbd8dfedeb4", appScope: "x_sofse_cicdjenkins"
            }
        }
    }
}

Link to the example.

  1. The same script with one step Apply changes but using ServiceNow Parameters defined in the block parameters. Additionally, the content of the parameter snParam will be displayed in console output. The content will be represented in json format.
pipeline {
    agent any

    parameters {
            snParam(credentialsForPublishedApp: "88dbbe69-0e00-4dd5-838b-2fbd8dfedeb4", instanceForPublishedAppUrl: "https://cicdjenkinsapppublish.service-now.com", appScope: "x_sofse_cicdjenkins")
    }

    stages {
        stage('preparation') {
            steps {
                echo "${params.snParam}"

                snApplyChanges()
            }
        }
    }
}

Link to the example.

  1. Advanced pipeline script with workflow of publishing and installing an application on NOW platform. The build was devided into 2 stages: publishing and installation. The last stage runs additionally test suite to check newly installed application.
pipeline {
    agent any

    parameters {
            snParam(credentialsForPublishedApp: "88dbbe69-0e00-4dd5-838b-2fbd8dfedeb4", instanceForPublishedAppUrl: "https://cicdjenkinsapppublish.service-now.com",
                    credentialsForInstalledApp:"88dbbe69-0e00-4dd5-838b-2fbd8dfedeb4", instanceForInstalledAppUrl:"https://cicdjenkinsappinstall.service-now.com",
                    appScope: "x_sofse_cicdjenkins")
    }

    stages {
        stage('publishing') {
            steps {
                snPublishApp obtainVersionAutomatically: true
            }
        }
        stage('installation') {
            steps {
                snInstallApp()
                snRunTestSuite browserName: 'Firefox', osName: 'Windows', osVersion: '10', testSuiteName: 'My CHG:Change Management', withResults: true
            }
        }
    }
}

Link to the example.

Integration tests

Integration tests using the NOW's API are located in two classes: ServiceNowAPIClientIntegrationTest and SNStepsIntegrationTest. All of the tests have the annotation Ignore, because they are not reliable for daily testing and require credentials. Following steps should be done to activate integration tests:

  • remove the annotation Ignore from all tests you want to run
  • setup NOW's API credentials by setting up following environment variables USERNAME and PASSWORD (urls of appropriate instances are already configured in test classes, what can be also changed manually in the code). This setup can be done in two ways:
    • (1) creating pipeline scripting on private Jenkins instance with junit tests execution:
    pipeline {
        agent any
    
        environment {
                USERNAME = 'api-username'
                PASSWORD = 'api-password'
            }
    
        tools {
            // Install the Maven version configured as "M3" and add it to the path.
            maven "M3"
        }
    
        stages {
            stage('Test') {
                steps {
                    git url: 'https://github.com/jenkinsci/servicenow-cicd-plugin.git'
                    
                    // Run Maven on a Unix agent.
                    sh "mvn -Dmaven.test.failure.ignore=true test"
    
                    // To run Maven on a Windows agent, use
                    // bat "mvn -Dmaven.test.failure.ignore=true test"
                }
    
                post {
                    // If Maven was able to run the tests, even if some of the test
                    // failed, record the test results and archive the jar file.
                    success {
                        junit '**/target/surefire-reports/TEST-*.xml'
                        archiveArtifacts 'target/*.jar'
                    }
                }
            }
        }
    }
    • (2) together with buildPlugin in Jenkinsfile (eg. on ci.jenkins.io)
      • create global credentials with user name and password on Jenkins instance
      • uncomment lines in Jenkinsfile and replace the credentialsId value 482fa2bf-73b5-489a-8f9e-62004e01f10b by the ID of newly created credentials

Troubleshouting

Known issues:

  • Publishing an application does not make changes in linked repository as it is done directly from UI of NOW platform.
  • Following step Roll back plugin should not be placed directly after Activate plugin, because finalizing the activation of a plugin happens also after the build step Activate plugin (although it was completed with success). Trying to roll it back may lead to unclear status of the plugin on specified instance. Generally the use case will not happen, because usually a plugin is activated once and nobody would like to deactivate it just after activation.
ArchivesGet past versions
Links
Labels
This plugin has no labels