The following plugin provides functionality available through
Pipeline-compatible steps. Read more about how to integrate steps into your
Pipeline in the
Steps
section of the
Pipeline Syntax
page.
For a list of other such plugins, see the
Pipeline Steps Reference
page.
ServiceNow DevOps Plugin
snDevOpsArtifact
: ServiceNow DevOps - Register Artifact step
Artifact registration
Configure artifact registration in a scripted pipeline or freestyle job using th DevOps API/artifact/registration endpoint. Multiple artifact versions are supported.
artifactsPayload : String
(optional)
ArtifactPayload
"name" --> Artifact name for which different builds (artifact versions) are generated.
"version" --> Specific version of the artifact. Deployable component of an application generated by a CI build. When provided, semantic version is used.
"semanticVersion" --> Optional attribute of an artifact version that, when provided, is used to determine commits for a change. Semantic version format is (MAJOR.MINOR.PATCH).
"repository" --> Target for artifacts generated in a build, and also a source of artifacts required by a build.
Example:
{"artifacts":[{"name": "sa-web.jar", "version": "1.9", "repositoryName": "services-1031"}, {"name": "sa-db.jar", "version": "1.3.2", "repositoryName": "services-1032"}], "branchName": "master"}
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
ignoreErrors : boolean
(optional)
ignoreErrors specifies the setting to prevent job failure if there is an error (true/false)
snDevOpsChange
: ServiceNow DevOps - Change Control step
snDevOpsChange
Enables change control for each root-level stage that is mapped to a DevOps step.
abortOnChangeCreationFailure : boolean
(optional)
Abort or Resume pipeline if the change is not created till the change creation timeout.
Checked: Abort (default, when change creation timeout specified).
Unchecked: Resume
abortOnChangeStepTimeOut : boolean
(optional)
Abort or Resume pipeline if the change step is still in progress on change step timeout.
Checked: Abort (default, when change creation timeout specified)
Unchecked: Resume
applicationName : String
(optional)
Specifies the application to where config data will be uploaded.
changeCreationTimeOut : Object
(optional)
Timeout value in seconds. Upon timeout, Jenkins checks the Change creation status in ServiceNow and if it failed to create the CHG, it resumes or aborts the pipeline based on the flag abortOnChangeCreationFailure. By default it aborts, when timeout is specified.
changeRequestDetails : String
(optional)
changeRequestDetails specifies closure code and change request fields from within the pipeline (starting with version 1.24).
Example:
{ "attributes": { "short_description": "Test description", "priority": "1", "start_date": "2021-02-05 08:00:00", "end_date": "2022-04-05 08:00:00", "justification": "test justification", "description": "test description", "cab_required": <true/false>, "comments": "This update for work notes is from jenkins file", "work_notes": "test work notes", "assignment_group": "<SYS_ID>" }, "setCloseCode": <true/false> }
changeStepTimeOut : Object
(optional)
Timeout value in seconds. Upon timeout, if the Change step is still in progress, it resumes or aborts the pipeline based on the flag abortOnChangeStepTimeout. By default it aborts, when timeout is specified.
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
ignoreErrors : boolean
(optional)
ignoreErrors specifies the setting to prevent job failure if there is an error (true/false)
pollingInterval : Object
(optional)
Frequency at which Jenkins polls ServiceNow for the Change status and update the console logs only on Change state transitions, Asssignment Group updates, Approval updates, Planned Start/End date updates. Specify time in seconds.
snapshotName : String
(optional)
Specifies snapshot from which to export data.
snDevOpsConfig
: ServiceNow DevOps - DevOps Configuration Pipeline
This action streamlines and enhances the functionality of DevOps Config by integrating multiple operations into a single action.
The revamped process follows these steps:
Upload: The action begins by uploading files specified in a regex format.
Validation and Publishing: Config data validation and publishing can be customized through arguments provided for this action.
Snapshot Retrieval: After the upload, the action retrieves the created snapshots and waits for the validation process to complete. It generates test results based on user input.
Changeset Registration: The action registers the changeset with the pipeline execution.
Finally, the action returns a list of snapshot objects.
applicationName : String
Specifies the application to where config data will be uploaded.
target : String
Specifies the data model target to where config data will be uploaded (for example, component, collection, deployable).
namePath : String
Specifies the name path in the data model to where config data will be uploaded.
Note: When uploading to a vars folder, you must start the name path with "vars/" to specifiy the variable folder path.
configFile : String
Specifies the configuration data file to upload to the component or deployable path in the data model.
dataFormat : String
Specifies the data format of the config file (for example, JSON, YAML, XML, etc.)
autoCommit : String
(optional)
Specifies whether to commit configuration data after upload (true/false). Default is false.
autoPublish : String
(optional)
Specifies whether to auto publish for a snapshot for the given application and deployable (true/false). Default is false.
autoValidate : String
(optional)
Specifies whether to validate configuration data during commit (true/false). Default is false.
changesetNumber : String
(optional)
Output variable
Specifies the (open) changeset to which this upload activity is associated.
collectionName : String
(optional)
Name of the collection to upload to (required if target is collection).
convertPath : boolean
(optional)
Specifies whether to preserve the directory structure of configuration files (with respect to the workspace) and convert the directory to paths within the data model.
deployableName : String
(optional)
Name of the deployable to upload to (required if target is deployable).
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
ignoreErrors : boolean
(optional)
Specifies the setting to prevent job failure if there is an error
isValidated : boolean
(optional)
Specifies to only retrieve the latest validated snapshots, with or without exceptions.
markFailed : boolean
(optional)
Fail the pipeline in the event that the validation attempt failed (due to a backend issue).
showResults : boolean
(optional)
Specifies the expected data format of the returned configuration data.
testResultFormat : String
(optional)
Specifies the format of the test results(xml or json).
snDevOpsConfigExport
: ServiceNow DevOps - DevOps Configuration Export
This action exports a snapshot for the given application and deployable.
The user should specify the exporter, relevant exporter arguments, the export format (for example, YAML, JSON, etc.), and output location for the exported config data.
From here, the config data can be used directly as an input for a deployment or provisioning tool downstream in the pipeline.
Example:
snDevOpsConfigExport(
applicationName: 'PaymentDemo',
deployableName: 'Production',
snapshotName: 'Production-v23.dpl',
exporterFormat: 'yaml',
exporterName: 'returnAllData-now',
exporterArgs: '',
fileName: 'exported_file-Production-20220302.yml'
)
applicationName : String
Specifies the application to where config data will be uploaded.
deployableName : String
Name of the deployable to upload to (required if target is deployable).
exporterName : String
Specifies the exporter to apply to the snapshot (for example, UniqueCDIs).
exporterFormat : String
Specifies the format to export the snapshot data (For example, INI, YAML, PROPS).
fileName : String
Specifies the file to be used from the workspace to store the exported config data. (Example: stagingConfig.json)
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
exporterArgs : String
(optional)
Specifies arguments to be used along with the exporter.
ignoreErrors : boolean
(optional)
Specifies the setting to prevent job failure if there is an error
markFailed : boolean
(optional)
Fail the pipeline in the event that the validation attempt failed (due to a backend issue).
showResults : boolean
(optional)
Specifies the expected data format of the returned configuration data.
snapshotName : String
(optional)
Specifies snapshot from which to export data.
snDevOpsConfigGetSnapshots
: ServiceNow DevOps - Get latest and validated snapshots
- Retrieve all snapshots for any impacted deployables.
When config files are uploaded to an application data model, the system will create snapshots for any deployables determined to be impacted by the upload. Following along the CI flow, assuming the last Upload call had validation enabled, the next step would be to iterate through the list of snapshots and ensure they all passed validation.
- Retrieve a specific snapshot.
Following the CD flow, a specific snapshot is retrieved so it can be published and then exported to be consumed downstream (for example, to provision out infrastructure or application).
- Show policy validation results in a pipeline execution.
View policy validation results as test results on the Jenkins build tests results page, including compliant with exception, when getting a snapshot.
Example:
- Specific snapshot (specified):
$snapshots = snDevOpsConfigGetSnapshots(
applicationName: 'PaymentDemo',
deployableName: 'Production',
changesetNumber: 'Chset-16'
)
- Latest validated snapshot (returns the latest snapshot for application and deployable combination):
$snapshots = snDevOpsConfigGetSnapshots(
applicationName: 'PaymentDemo',
deployableName: 'Production',
isValidated: 'true'
)
- All changeset snapshots (returns all snapshots for application and deployable combination):
$snapshots = snDevOpsConfigGetSnapshots(
applicationName: 'PaymentDemo',
changesetNumber: 'Chset-16',
)
- Show policy validation results in a pipeline execution.
- Assign a variable to the path of the file that contains the snapshot validation results generated during the snDevOpsConfigGetSnapshots action.
- Call the JUnit action to load the snapshot validation results into the pipeline execution test section.
stage('Validate') {
steps {
script {
changeSetResults = snDevOpsConfigGetSnapshots( … )
if (!changeSetResults) {
echo "No snapshots were created"
} else {
def changeSetResultsObject = readJSON text: changeSetResults
changeSetResultsObject.each {
snapshotName = it.name
snapshotObject = it
}
// STEP 1
validationResultsPath = "${snapshotName}_${currentBuild.projectName}_${currentBuild.number}.xml"
}
}
}
}
post {
always {
// STEP 2
junit testResults: "${validationResultsPath}", skipPublishingChecks: true
}
}
applicationName : String
Specifies the application to where config data will be uploaded.
deployableName : String
(optional)
Name of the deployable to upload to (required if target is deployable).
changesetNumber : String
(optional)
Output variable
Specifies the (open) changeset to which this upload activity is associated.
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
ignoreErrors : boolean
(optional)
Specifies the setting to prevent job failure if there is an error
isValidated : boolean
(optional)
Specifies to only retrieve the latest validated snapshots, with or without exceptions.
markFailed : boolean
(optional)
Fail the pipeline in the event that the validation attempt failed (due to a backend issue).
outputFormat : String
(optional)
Specifies the format of the test results(xml or json).
showResults : boolean
(optional)
Specifies the expected data format of the returned configuration data.
snDevOpsConfigPublish
: ServiceNow DevOps - DevOps Configuration Publish
This action publishes a snapshot for the given application and deployable. From here, the snapshot can be consumed through the Export process.
Example:
snDevOpsConfigPublish(
applicationName: 'PaymentDemo',
deployableName: 'Production',
snapshotName: 'Production-v23.dpl',
)
applicationName : String
Specifies the application to where config data will be uploaded.
deployableName : String
Name of the deployable to upload to (required if target is deployable).
snapshotName : String
Specifies snapshot from which to export data.
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
ignoreErrors : boolean
(optional)
Specifies the setting to prevent job failure if there is an error
markFailed : boolean
(optional)
Fail the pipeline in the event that the validation attempt failed (due to a backend issue).
showResults : boolean
(optional)
Specifies the expected data format of the returned configuration data.
snDevOpsConfigRegisterPipeline
: ServiceNow DevOps - DevOps Configuration Register Pipeline
This action ties a changeset and/or snapshot to the pipeline so that it can be tracked during the pipeline execution. In DevOps Change Velocity, this is shown in the Pipeline UI.
See Accelerating your DevOps change process for more information regarding the DevOps Change Acceleration feature.
Example:
- Input:
Here is an example of the snDevOpsConfigRegisterPipeline action. For the sake of illustration, we’ll assign the response to a variable, changeSetRegResult, which could be echoed out to our console log for debugging scenarios.
changeSetRegResult = snDevOpsConfigRegisterPipeline(
applicationName: "PaymentDemo",
changesetNumber: "Chset-122"
)
echo "Pipeline registration result: ${changeSetRegResult}"
applicationName : String
(optional)
Specifies the application to where config data will be uploaded.
changesetNumber : String
(optional)
Output variable
Specifies the (open) changeset to which this upload activity is associated.
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
ignoreErrors : boolean
(optional)
Specifies the setting to prevent job failure if there is an error
markFailed : boolean
(optional)
Fail the pipeline in the event that the validation attempt failed (due to a backend issue).
showResults : boolean
(optional)
Specifies the expected data format of the returned configuration data.
snapshotName : String
(optional)
Specifies snapshot from which to export data.
snDevOpsConfigUpload
: ServiceNow DevOps - DevOps Configuration Upload
This action uploads a configuration file to a given location within an application data model.
It is meant to be used in an iterative nature for all config files to upload to the application data model during the pipeline run.
Supports:
- Upload to:
- A component, collection, or deployable.
- The variable (vars) folder of a component, collection, or deployable.
- Regex pattern for config file input.
- Ability to be called multiple times in the same pipeline.
- Input:
Here is an example of the snDevOpsConfigUpload action. For the sake of illustration, we’ll assign the response to a variable, changeSetId, which could be echoed out to our console log for debugging scenarios.
changeSetId = snDevOpsConfigUpload(
applicationName: "PaymentDemo",
target: 'component',
namePath: "web-api-v1.0",
configFile: "k8s/helm/values.yml",
dataFormat: "json",
autoCommit: 'true',
autoValidate: 'true'
)
echo "Changeset: $changeSetId created"
Example - Multiple uploads (component)
You can call the upload action more than once to upload configuration data in different file formats from different locations, while still keeping the uploads part of one changeset.
- In the first upload, name the action so the changesetNumber output variable can be reused in subsequent uploads.
YAML file upload:
$changeset = snDevOpsConfigUpload(
applicationName: 'PaymentDemo',
target: 'component',
namePath: 'wep-api-v1.0',
configFile: 'k8s/helm/values.yml',
dataFormat: 'yaml',
autoCommit: 'false',
autoValidate: 'false'
)
- In subsequent uploads, reference the changesetNumber output variable from the first upload as an input variable.
3 JSON files upload:
snDevOpsConfigUpload(
applicationName: 'PaymentDemo',
target: 'component',
namePath: 'wep-api-v1.0',
configFile: 'infra/*.json',
dataFormat: 'json',
autoCommit: 'false',
autoValidate: 'false',
changesetNumber: ”${changeset}”
)
- In the final call, in addition to referencing the changesetNumber output variable from the first upload as an input variable, set autoCommit and autoValidate to true.
INI file upload:
snDevOpsConfigUpload(
applicationName: 'PaymentDemo',
target: 'component',
namePath: 'wep-api-v1.0',
configFile: 'featureToggles/set1.ini',
dataFormat: 'ini',
autoCommit: 'true',
autoValidate: 'true',
changesetNumber: ”${changeset}”
)
Example - Multiple uploads (collection and vars)
You can call the upload action more than once to upload configuration data in different file formats from different locations, while still keeping the uploads part of one changeset.
- In the first upload, create a variable (for example, $changeset), and assign the return value of the step to it so it can be reused in subsequent uploads.
XML file upload:
$changeset = snDevOpsConfigUpload(
applicationName: 'PaymentDemo',
target: 'collection',
collectionName: 'release-v1.0',
namePath: 'v1-common-configs',
configFile: 'infra/v1/config.xml',
dataFormat: 'xml',
autoCommit: 'false',
autoValidate: 'false'
)
- In subsequent uploads, use the variable as an input.
JSON file upload:
snDevOpsConfigUpload(
applicationName: 'PaymentDemo',
target: 'deployable',
deployableName: 'Production',
namePath: 'vars/dbSettings',
configFile: 'infra/prod/dbConfig.json',
dataFormat: 'json',
autoCommit: 'true',
autoValidate: 'true',
changesetNumber: ”${changeset}”
)
Note: To upload to a variable folder, uploadTarget must be set to deployable, and the correct values must be set for deployableName and changesetNumber.
applicationName : String
Specifies the application to where config data will be uploaded.
target : String
Specifies the data model target to where config data will be uploaded (for example, component, collection, deployable).
namePath : String
Specifies the name path in the data model to where config data will be uploaded.
Note: When uploading to a vars folder, you must start the name path with "vars/" to specifiy the variable folder path.
configFile : String
Specifies the configuration data file to upload to the component or deployable path in the data model.
autoCommit : boolean
Specifies whether to commit configuration data after upload (true/false). Default is false.
autoValidate : boolean
Specifies whether to validate configuration data during commit (true/false). Default is false.
dataFormat : String
Specifies the data format of the config file (for example, JSON, YAML, XML, etc.)
autoPublish : boolean
Specifies whether to auto publish for a snapshot for the given application and deployable (true/false). Default is false.
changesetNumber : String
(optional)
Output variable
Specifies the (open) changeset to which this upload activity is associated.
collectionName : String
(optional)
Name of the collection to upload to (required if target is collection).
convertPath : boolean
(optional)
Specifies whether to preserve the directory structure of configuration files (with respect to the workspace) and convert the directory to paths within the data model.
deployableName : String
(optional)
Name of the deployable to upload to (required if target is deployable).
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
ignoreErrors : boolean
(optional)
Specifies the setting to prevent job failure if there is an error
markFailed : boolean
(optional)
Fail the pipeline in the event that the validation attempt failed (due to a backend issue).
showResults : boolean
(optional)
Specifies the expected data format of the returned configuration data.
snDevOpsConfigValidate
: ServiceNow DevOps - DevOps Configuration Validate
Validate config data against your organization policies.
Example:
- Specific snapshot (specified):
snDevOpsConfigValidate(
applicationName: 'PaymentDemo',
deployableName: 'Production',
snapshotName: 'Production-v23.dpl',
)
- Latest snapshot (retrieves and validates the latest snapshot for application and deployable combination):
$changeset = snDevOpsConfigValidate(
applicationName: 'PaymentDemo',
deployableName: 'Production'
)
applicationName : String
Specifies the application to where config data will be uploaded.
deployableName : String
Name of the deployable to upload to (required if target is deployable).
enabled : boolean
(optional)
Enabled specifies the setting for build notifications property (true/false)
ignoreErrors : boolean
(optional)
Specifies the setting to prevent job failure if there is an error
markFailed : boolean
(optional)
Fail the pipeline in the event that the validation attempt failed (due to a backend issue).
showResults : boolean
(optional)
Specifies the expected data format of the returned configuration data.
snapshotName : String
(optional)
Specifies snapshot from which to export data.
snDevOpsGetChangeNumber
: ServiceNow DevOps - get Change Number step
snDevOpsGetChangeNumber
Returns the DevOps change request number based on the inputs provided.
For more information, see click here
changeDetails : String
(optional)
Pipeline Name, Build Number, Stage Name are mandatory input parameters to retrieve the change request number. If these input field parameters are not provided, the change request number for the current Pipeline Name, Build Number, Stage Name will be retrieved. For multi-branch pipelines, you must provide the Branch Name as an input parameter as well. (starting with version 1.37).
Example:
{ "pipeline_name": "Test Pipeline", "build_number": "1", "stage_name": "ChangeStage", "branch_name": "master" }
snDevOpsPackage
: ServiceNow DevOps - Register Package step
Artifact package creation
Configure artifact package creation in a scripted pipeline or freestyle job using the DevOps API /package/registration endpoint.
name : String
(optional)
Collection of artifact versions used as input to a CD pipeline, or for associating test results.
artifactsPayload : String
(optional)
ArtifactPayload
"name" --> Artifact name for which different builds (artifact versions) are generated.
"version" --> Specific version of the artifact. Deployable component of an application generated by a CI build. When provided, semantic version is used.
"semanticVersion" --> Optional attribute of an artifact version that, when provided, is used to determine commits for a change. Semantic version format is (MAJOR.MINOR.PATCH).
"repository" --> Target for artifacts generated in a build, and also a source of artifacts required by a build.
Example:
{"artifacts":[{"name": "sa-web.jar", "version": "1.9", "repositoryName": "services-1031"}, {"name": "sa-db.jar", "version": "1.3.2", "repositoryName": "services-1032"}], "branchName": "master"}
snDevOpsSecurityResult
: Servicenow Register Security Step
snDevOpsSecurityResults - Retrieves and stores the security scan results
securityResultAttributes : String
(optional)
Enter the security result attributes.
scanner // Scanning tool and is required e.g. Veracode.
applicationName // Name of your Veracode application and is required. This attribute is applicable only for Veracode.
buildVersion // Veracode Scan name / build version and is optional. This attribute is applicable only for Veracode.
securityToolId // Security tool onboarded in ServiceNow (sys_id of the onboarded security tool).
Example:
{"scanner":"Veracode", "applicationName": "", "buildVersion": ${BUILD_TAG}, "securityToolId": ""}
snDevOpsStep
: ServiceNow DevOps - Mapping step
enabled : boolean
(optional)
ignoreErrors : boolean
(optional)
snDevOpsUpdateChangeInfo
: ServiceNow DevOps - Update Change Request Info
snDevOpsUpdateChangeInfo
Updates the details of the DevOps change request number provided. Returns true/false based on the status of Update (true if update is successful, else false).
For more information, see click here
changeRequestDetails : String
(optional)
Change request details to be updated must be provided as Key:Value pairs in the following format:
Example:
{ "short_description": "Test description", "priority": "1", "start_date": "2021-02-05 08:00:00", "end_date": "2022-04-05 08:00:00", "justification": "test justification", "description": "test description", "cab_required": <true/false>, "comments": "This update for work notes is from jenkins file", "work_notes": "test work notes", "assignment_group": "<SYS_ID>", "state":"<STATE_CODE>", "close_code":"<successful/successful_issues/unsuccessful>", "reason":"<As per Choice List>" }
- Key:Value pairs provided as input parameters must match with the Change_request table's field column values.
- For choice type of fields, the field value must match with the appropriate choice value (Ex: close_code)
- For State Transition to 'Close' of Change, 'close_code' and 'close_notes' are mandatory, and to 'Cancel' of Change, 'reason' is mandatory.
changeRequestNumber : String
(optional)
Change request number to be updated.
step([$class: 'DevOpsCreateArtifactPackageBuildStep'])
: ServiceNow DevOps - Register Package step
name : String
(optional)
Collection of artifact versions used as input to a CD pipeline, or for associating test results.
artifactsPayload : String
(optional)
ArtifactPayload
"name" --> Artifact name for which different builds (artifact versions) are generated.
"version" --> Specific version of the artifact. Deployable component of an application generated by a CI build. When provided, semantic version is used.
"semanticVersion" --> Optional attribute of an artifact version that, when provided, is used to determine commits for a change. Semantic version format is (MAJOR.MINOR.PATCH).
"repository" --> Target for artifacts generated in a build, and also a source of artifacts required by a build.
Example:
{"artifacts":[{"name": "sa-web.jar", "version": "1.9", "repositoryName": "services-1031"}, {"name": "sa-db.jar", "version": "1.3.2", "repositoryName": "services-1032"}], "branchName": "master"}
step([$class: 'DevOpsFreestyleRegisterSecurityStep'])
: snDevOpsSecurityResult
securityResultAttributes : String
(optional)
Enter the security result attributes.
scanner // Scanning tool and is required e.g. Veracode.
applicationName // Name of your Veracode application and is required. This attribute is applicable only for Veracode.
buildVersion // Veracode Scan name / build version and is optional. This attribute is applicable only for Veracode.
securityToolId // Security tool onboarded in ServiceNow (sys_id of the onboarded security tool).
Example:
{"scanner":"Veracode", "applicationName": "", "buildVersion": ${BUILD_TAG}, "securityToolId": ""}
securityToolId : String
(optional)
step([$class: 'DevOpsRegisterArtifactBuildStep'])
: ServiceNow DevOps - Register Artifact step
artifactsPayload : String
(optional)
ArtifactPayload
"name" --> Artifact name for which different builds (artifact versions) are generated.
"version" --> Specific version of the artifact. Deployable component of an application generated by a CI build. When provided, semantic version is used.
"semanticVersion" --> Optional attribute of an artifact version that, when provided, is used to determine commits for a change. Semantic version format is (MAJOR.MINOR.PATCH).
"repository" --> Target for artifacts generated in a build, and also a source of artifacts required by a build.
Example:
{"artifacts":[{"name": "sa-web.jar", "version": "1.9", "repositoryName": "services-1031"}, {"name": "sa-db.jar", "version": "1.3.2", "repositoryName": "services-1032"}], "branchName": "master"}
Was this page helpful?
Please submit your feedback about this page through this
quick form.
Alternatively, if you don't wish to complete the quick form, you can simply
indicate if you found this page helpful?
See existing feedback here.