checkChangeInDevelopment¶
Description¶
Checks if a Change Document in SAP Solution Manager is in status 'in development'. The change document id is retrieved from the git commit history. The change document id
can also be provided via parameter changeDocumentId
. Any value provided as parameter has a higher precedence than a value from the commit history.
By default the git commit messages between origin/master
and HEAD
are scanned for a line like ChangeDocument : <changeDocumentId>
. The commit
range and the pattern can be configured. For details see 'parameters' table.
Migration Guide¶
Note: This step has been deprecated. Use the new step isChangeInDevelopment instead.
Adjust your parameters to the naming convention of the new step. Adjust the unsupported parameters as indicated in the table below:
Unsupported Parameter | New Parameter |
---|---|
changeManagement/type | This parameter has been removed. SOLMAN is the only backend type supported. |
changeManagement/<type> /docker/envVars |
dockerEnvVars |
changeManagement/<type> /docker/image |
dockerImage |
changeManagement/<type> /docker/options |
dockerOptions |
changeManagement/<type> /docker/pullImage |
dockerPullImage |
changeManagement/git/format | This parameter has been removed. Make sure that the IDS of your change document and transport request are part of the Git commit message body. |
Your config.yml file should look as follows:
general:
# new naming convention
steps:
isChangeInDevelopment:
dockerImage: 'ppiper/cm-client:3.0.0.0'
Note: The new step does not comprise the retrieval of the change document ID from the Git repository anymore. Use the step transportRequestDocIDFromGit instead.
Parameters¶
name | mandatory | default | possible values |
---|---|---|---|
changeDocumentId |
yes | ||
changeManagement/changeDocumentLabel |
no | ChangeDocument\s?: |
regex pattern |
changeManagement/clientOpts |
no | `` | |
changeManagement/credentialsId |
no | CM |
|
changeManagement/endpoint |
yes | ||
changeManagement/git/format |
no | %b |
see git log --help |
changeManagement/git/from |
no | origin/master |
|
changeManagement/git/to |
no | HEAD |
|
failIfStatusIsNotInDevelopment |
no | true |
true , false |
script |
yes |
changeDocumentId
- The id of the change document to transport. If not provided, it is retrieved from the git commit history.changeManagement/changeDocumentLabel
- A pattern used for identifying lines holding the change document id.changeManagement/clientOpts
- Additional options for cm command line client, e.g. JAVA_OPTS.changeManagement/credentialsId
- The id of the credentials to connect to the Solution Manager. The credentials needs to be maintained on Jenkins.changeManagement/endpoint
- The service endpoint, e.g. Solution Manager, ABAP System.changeManagement/git/format
- Specifies what part of the commit is scanned. By default the body of the commit message is scanned.changeManagement/git/from
- The starting point for retrieving the change document id.changeManagement/git/to
- The end point for retrieving the change document id.failIfStatusIsNotInDevelopment
- When set tofalse
the step will not fail in case the step is not in status 'in development'.script
- The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with thethis
parameter, as inscript: this
. This allows the function to access thecommonPipelineEnvironment
for retrieving, e.g. configuration parameters.
Step configuration¶
We recommend to define values of step parameters via config.yml file.
In following sections of the config.yml the configuration is possible:
parameter | general | step/stage |
---|---|---|
changeDocumentId |
||
changeManagement/changeDocumentLabel |
X | X |
changeManagement/clientOpts |
X | X |
changeManagement/credentialsId |
X | X |
changeManagement/endpoint |
X | X |
changeManagement/git/format |
X | X |
changeManagement/git/from |
X | X |
changeManagement/git/to |
X | X |
failIfStatusIsNotInDevelopment |
X | |
script |
Dependencies¶
The step depends on the following Jenkins plugins
- badge
- credentials-binding
- docker
- kubernetes
- pipeline-utility-steps
- ssh-agent
- workflow-basic-steps
- workflow-cps-global-lib
- workflow-durable-task-step
The kubernetes plugin is only used if running in a kubernetes environment. Transitive dependencies are omitted.
The list might be incomplete.
Consider using the ppiper/jenkins-master docker image. This images comes with preinstalled plugins.
Exceptions¶
AbortException
:- If the change id is not provided via parameter and if the change document id cannot be retrieved from the commit history.
- If the change is not in status
in development
. In this case no exception will be thrown whenfailIfStatusIsNotInDevelopment
is set tofalse
. IllegalArgumentException
:- If a mandatory property is not provided.
Examples¶
The step is configured using a customer configuration file provided as resource in an custom shared library.
@Library('piper-lib-os@master') _
// the shared lib containing the additional configuration
// needs to be configured in Jenkins
@Library('foo@master') __
// inside the shared lib denoted by 'foo' the additional configuration file
// needs to be located under 'resources' ('resoures/myConfig.yml')
prepareDefaultValues script: this, customDefaults: 'myConfig.yml'
Example content of 'resources/myConfig.yml'
in branch 'master'
of the repository denoted by
'foo'
:
general:
changeManagement:
changeDocumentLabel: 'ChangeDocument\s?:'
cmClientOpts: '-Djavax.net.ssl.trustStore=<path to truststore>'
credentialsId: 'CM'
endpoint: 'https://example.org/cm'
git:
from: 'HEAD~1'
to: 'HEAD'
format: '%b'
The properties configured in section 'general/changeManagement'
are shared between all change management related steps.
The properties can also be configured on a per-step basis:
[...]
steps:
checkChangeInDevelopment:
changeManagement:
endpoint: 'https://example.org/cm'
[...]
failIfStatusIsNotInDevelopment: true
The parameters can also be provided when the step is invoked:
// simple case. All mandatory parameters provided via
// configuration, changeDocumentId provided via commit
// history
checkChangeInDevelopment script:this
// explicit endpoint provided, we search for changeDocumentId
// starting at the previous commit (HEAD~1) rather than on
// 'origin/master' (the default).
checkChangeInDevelopment(
script: this
changeManagement: [
endpoint: 'https:example.org/cm'
git: [
from: 'HEAD~1'
]
]
)