${docGenStepName}

${docGenDescription}

Prerequisites

You have an SAP Solution Manager user account and the roles required for uploading. See SAP Solution Manager Administration.
You have a change document to which your transport request is coupled.
You have a transport request, which is the target container of the upload.
You have installed the Change Management Client with the needed certificates.

Change Management Client

The Change Management Client (CM Client) handles the access to SAP Solution Manager. The CM Client is a software running under Linux, which can initiate basic change management tasks in the Solution Manager as well as in the CTS. The client is used by default as a Docker image, but can also be installed as a command line tool.

Certificates

It is expected that the Solution Manager endpoint is secured by SSL and sends a certificate accordingly. The certificate is verified by the CM Client. If the publisher of this certificate is unknown, the connection will be rejected. The client implemented in Java uses the underlying JDK procedures for the verification. Accordingly, the issuer must be specified in the truststore of the JDK. In the case of the Docker image a clone of the image must be created with the necessary certificate added to its truststore. In the case of the immediate command line tool, only the truststore of the environment needs to be extended.

Specifying the Change document and transport request

The target of the upload is a Transport Request, which is determined by the identifiers (ID) of the Request and the associated Change Document. transportRequestUploadSOLMAN allows to set these IDs by parameter or to use Git commit messages. As an additional option, IDs can be passed in via the Common Pipeline Environment. For example through a step that generates the IDs or obtains them differently.

By Step Parameter

A parameterized pipeline allows to specify the IDs with the launch of the build instead of entering them statically into the pipeline.

transportRequestUploadSOLMAN(
    script: this,
    changeDocumentId: ${CHANGE_DOCUMENT_ID},
    transportRequestId: ${TRANSPORT_REQUEST_ID},
    ...
)

The Jenkins pipeline input step allows to specify the IDs at runtime of the pipeline.

def ids = input( message: "Upload?",
    parameters: [
        string(name: 'CHANGE_DOCUMENT_ID',description: 'Change Document ID'),
        string(name: 'TRANSPORT_REQUEST_ID',description: 'Transport Request ID')
    ]
)

transportRequestUploadSOLMAN(
    script:this,
    changeDocumentId: ids['CHANGE_DOCUMENT_ID'],
    transportRequestId: ids['TRANSPORT_REQUEST_ID'],
    ...
)

By Git Commit Message

If the identifiers are neither defined as step parameters nor by the Common Pipeline Environment, the Git commit messages (git log) of the project are searched for lines that follow a defined pattern. The pattern is specified by the label changeDocumentLabel (default=ChangeDocument) resp. transportRequestLabel (default=TransportRequest). Behind the label a colon, any blanks and the identifier are expected.

Release - define IDs for upload to Solution Manager

    ChangeDocument: 1000001234
    TransportRequest: ABCD10005E

The IDs dont need to be defined in the same commit message.

The Git commit messages to be considered are determined by the parameters gitFrom (default=origin/master) and gitTo (default=HEAD). The naming follows the Git revision range representation git log <gitFrom>..<gitTo>. All commit messages accessible from gitTo but not from gitFrom are taken into account. If the scanner detects multiple IDs, it fails. So the commit range has to be chosen accordingly.

In case of a pull request of a feature branch, the default should be sufficient as long as the transport request isn't changed. Only the commits (HEAD) that have not yet entered the main branch origin/master would be scanned.

If uploading from the main branch, it must be assumed that former change document and transport request IDs are already contained in the history. In this case the new IDs should be maintained in the HEAD and gitFrom be set to HEAD~1.

general:
  changeManagement:
    git:
      from: 'HEAD~1'

Common Pipeline Environment

If changeDocumentId and transportRequestId are determined during runtime via the Git commit messages, they are entered into the commonPipelineEnvironment and can be retrieved accordingly.

  this.commonPipelineEnvironment.getValue('changeDocumentID')
  this.commonPipelineEnvironment.getValue('transportRequestID')

${docGenParameters}

${docGenConfiguration}

${docJenkinsPluginDependencies}

Example

transportRequestUploadSOLMAN(
  script: this,
  endpoint: 'https://example.org/cm/solman/endpoint'
  applicationId: 'ABC',
  uploadCredentialsId: "SOLMAN_CRED_ID"
  changeDocumentId: '12345678',
  transportRequestId: '87654321',
  filePath: '/path/file.ext',
  cmClientOpts: '-Dkey=value'
)

5.2 KiB Raw Blame History