Skip to content

transportRequestUploadFile

Description

Uploads a file to a Transport Request.

CTS upload is currently not supported. We are working on a new way to handle CTS uploads.

Prerequisites

Parameters

name mandatory default possible values
abapPackage yes
acceptUnixStyleLineEndings no true
applicationDescription yes
applicationId yes
applicationName yes
applicationUrl yes
changeDocumentId yes
changeManagement/changeDocumentLabel no ChangeDocument\s?: regex pattern
changeManagement/client yes
changeManagement/clientOpts no ``
changeManagement/credentialsId no CM
changeManagement/cts/deployConfigFile no ui5-deploy.yaml
changeManagement/cts/deployToolDependencies no [@ui5/cli, @sap/ux-ui5-tooling, @ui5/logger, @ui5/fs]
changeManagement/cts/nodeDocker/image no node
changeManagement/cts/npmInstallOpts no
changeManagement/cts/osDeployUser no node
changeManagement/endpoint yes
changeManagement/git/format no %b see git log --help
changeManagement/git/from no origin/master
changeManagement/git/to no HEAD
changeManagement/rfc/developmentClient yes
changeManagement/rfc/developmentInstance yes
changeManagement/rfc/docker/envVars no [:]
changeManagement/rfc/docker/image no rfc
changeManagement/rfc/docker/options no []
changeManagement/rfc/docker/pullImage no true
changeManagement/transportRequestLabel no TransportRequest\s?:
changeManagement/type no NONE SOLMAN, CTS, RFC
codePage no UTF-8
failOnWarning no true
filePath yes
script yes
transportRequestId yes
verbose no false
  • abapPackage - The ABAP package name of your application.
  • acceptUnixStyleLineEndings -
  • applicationDescription - The application description, RFC and CTS only. For CTS: the desription is only taken into account for a new upload. In case of an update the description will not be updated.
  • applicationId - The id of the application. Only for SOLMAN.
  • applicationName - The name of the application. RFC and CTS only.
  • applicationUrl - The URL where to find the UI5 package to upload to the transport request. Only for RFC.
  • changeDocumentId - The id of the change document to that the transport request is bound to. Typically this value is provided via commit message in the commit history. Only for SOLMAN.
  • changeManagement/changeDocumentLabel - A pattern used for identifying lines holding the change document id.
  • changeManagement/client - The ABAP client. Only for CTS
  • 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/cts/deployConfigFile - The file handed over to fiori deploy with flag -c --config.
  • changeManagement/cts/deployToolDependencies - By default we use a standard node docker iamge and prepare some fiori related packages performing the deployment. The additional dependencies can be provided here. In case you use an already prepared docker image which contains the required dependencies, the empty list can be provide here. Caused hereby installing additional dependencies will be skipped.
  • changeManagement/cts/nodeDocker/image - Some CTS related transport related steps are cm_client based, others are node based. For the node based steps the docker image is specified here.
  • changeManagement/cts/npmInstallOpts - A list containing additional options for the npm install call. -g, --global is always assumed. Can be used for e.g. providing custom registries (--registry https://your.registry.com) or for providing the verbose flag (--verbose) for troubleshooting.
  • changeManagement/cts/osDeployUser - By default we use a standard node docker image and prepare some fiori related packages before performing the deployment. For that we need to launch the image with root privileges. After that, before actually performing the deployment we swith to a non root user. This user can be specified here.
  • 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.
  • changeManagement/rfc/developmentClient - AS ABAP client number. Only for RFC.
  • changeManagement/rfc/developmentInstance - AS ABAP instance number. Only for RFC.
  • changeManagement/rfc/docker/envVars -
  • changeManagement/rfc/docker/image -
  • changeManagement/rfc/docker/options -
  • changeManagement/rfc/docker/pullImage -
  • changeManagement/transportRequestLabel - A pattern used for identifying lines holding the transport request id.
  • changeManagement/type - Defines where the transport request is created, e.g. SAP Solution Manager, ABAP System.
  • codePage - The code page of your ABAP system. E.g. UTF-8.
  • failOnWarning -
  • filePath - The path of the file to upload, Only for SOLMAN.
  • script - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.
  • transportRequestId - The id of the transport request to upload the file. This parameter is only taken into account when provided via signature to the step.
  • verbose - Provides additional details. Only for RFC.

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
abapPackage X
acceptUnixStyleLineEndings X
applicationDescription X
applicationId X
applicationName X
applicationUrl X
changeDocumentId
changeManagement/changeDocumentLabel X X
changeManagement/client X X
changeManagement/clientOpts X X
changeManagement/credentialsId X X
changeManagement/cts/deployConfigFile X X
changeManagement/cts/deployToolDependencies X X
changeManagement/cts/nodeDocker/image X X
changeManagement/cts/npmInstallOpts X X
changeManagement/cts/osDeployUser X X
changeManagement/endpoint X X
changeManagement/git/format X X
changeManagement/git/from X X
changeManagement/git/to X X
changeManagement/rfc/developmentClient X X
changeManagement/rfc/developmentInstance X X
changeManagement/rfc/docker/envVars X X
changeManagement/rfc/docker/image X X
changeManagement/rfc/docker/options X X
changeManagement/rfc/docker/pullImage X X
changeManagement/transportRequestLabel X X
changeManagement/type X X
codePage X
failOnWarning
filePath X
script
transportRequestId
verbose X

Dependencies

The step depends on the following Jenkins plugins

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.

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'
    type: 'SOLMAN'
    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:
    transportRequestUploadFile:
      applicationId: 'FOO'
      changeManagement:
        type: 'SOLMAN'
        endpoint: 'https://example.org/cm'
        [...]

The parameters can also be provided when the step is invoked. For examples see below.

CTS Uploads

In order to be able to upload the application, it is required to build the application, e.g. via npmExecute or mtaBuild. The content of the app needs to be provided in a folder named dist in the root level of the project. Although the name of the step transportRequestUploadFile might suggest something else, in this case a folder needs to be provided. The application, which is provided in the dist folder is zipped and uploaded by the fiori toolset used for performing the upload.

For CTS related uploads we use a node based toolset. When running in a docker environment a standard node image can be used. In this case the required deploy tool dependencies will be installed prior to the deploy. It is also possible to provide a docker image which already contains the required deploy tool dependencies (config.changeManagement.cts.nodeDocker.image). In this case an empty list needs to be provided as config.changeManagement.cts.deployToolDependencies. Using an already pre-configured docker image speeds-up the deployment step, but comes with the disadvantage of having to maintain and provision the corresponding docker image.

When running in an environment without docker, it is recommanded to install the deploy tools manually on the system and to provide an empty list for the deploy tool dependencies (config.changeManagement.cts.deployToolDependencies).

Examples

Upload based on preconfigured image

transportRequestUploadFile script: this,
            changeManagement: [
                credentialsId: 'CRED_ID', // credentials needs to be defined inside Jenkins
                type: 'CTS',
                endpoint: 'https://example.org:8000',
                client: '001',
                cts: [
                    nodeDocker: [
                        image: 'docker-image-name',
                        pullImage: true,  // needs to be set to false in case the image is
                                          // only available in the local docker cache (not recommended)
                    ],
                    npmInstallOpts: [],
                deployToolDependencies: [], // empty since we use an already preconfigured image
                ],
            ],
            applicationName: 'APP',
            abapPackage: 'ABABPACKAGE',
            transportRequestId: 'XXXK123456', // can be omitted when resolved via commit history
            applicationDescription: 'An optional description' // only used in case a new application is deployed
                                                              // description is not updated for re-deployments
    }

Upload based on a standard node image

        transportRequestUploadFile script: this,
            changeManagement: [
                credentialsId: 'CRED_ID', // credentials needs to be defined inside Jenkins
                type: 'CTS',
                endpoint: 'https://example.org:8000',
                client: '001',
                cts: [
                    npmInstallOpts: [
                        '--verbose', // might be benefical for troubleshooting
                        '--registry', 'https://your.npmregistry.org/', // an own registry can be specified here
                    ],
                ],
            ],
            applicationName: 'APP',
            abapPackage: 'ABABPACKAGE',
            transportRequestId: 'XXXK123456', // can be omitted when resolved via commit history
            applicationDescription: 'An optional description' // only used in case a new application is deployed
                                                              // description is not updated for re-deployments
    }

Exceptions

  • IllegalArgumentException:
  • If the change id is not provided (SOLMAN only).
  • If the transport request id is not provided.
  • If the application id is not provided (SOLMAN only).
  • If the file path is not provided.
  • AbortException:
  • If the upload fails.

Example

// SOLMAN
transportRequestUploadFile(
  script: this,
  changeDocumentId: '001',   // typically provided via git commit history
  transportRequestId: '001', // typically provided via git commit history
  applicationId: '001',
  filePath: '/path',
  changeManagement: [
    type: 'SOLMAN'
    endpoint: 'https://example.org/cm'
  ]
)
// CTS

transportRequestUploadFile(
  script: this,
  transportRequestId: '001', // typically provided via git commit history
  changeManagement: [
    type: 'CTS'
    endpoint: 'https://example.org/cm',
    client: '099',
  ],
  applicationName: 'myApp',
  abapPackage: 'MYPACKAGE',
)