github.com/jaylevin/jenkins-library@v1.230.4/documentation/docs/scenarios/upload-to-transportrequest/Readme.md (about)

     1  # Build an SAP Fiori Application and Attach It to a Transport Request on an ABAP System
     2  
     3  Build an application based on SAPUI5 or SAP Fiori with Jenkins and attach the build result to a transport request in an SAP ABAP system.
     4  
     5  Generally, you can choose between two technical ways to attach a binary to an ABAP transport request: We support uploads through RFC and through OData. Which option to use depends on the version of your ABAP system. For AS ABAP 7.50 SP08, 7.51 SP07, or 7.52 SP03 and newer, use the OData-based upload, for older versions, use the RFC-based upload.
     6  
     7  ## Prerequisites
     8  
     9  * You have set up your [Docker environment](https://docs.docker.com/get-started/).
    10  * You have set up project “Piper”. See [guided tour](../../../guidedtour/).
    11  * You have a transport request. In General it is possible to create a transport request on the fly. But the example here is based on an already existing transport request.
    12  * Depending on the version of the ABAP system: Docker image for attaching binaries to transport requests via RFC available. Due to legal reasons there is no pre-build docker image. How to create the docker image is explained [here](https://github.com/SAP/devops-docker-images/tree/master/node-rfc)
    13  
    14  ### Project Prerequisites
    15  
    16  This scenario requires additional files in your project and in the execution environment on your Jenkins instance.
    17  
    18  On the project level, provide and adjust the following template:
    19  
    20  | File Name | Description | Position |
    21  |-----|-----|-----|
    22  | [`mta.yaml`](https://github.com/SAP/jenkins-library/blob/master/documentation/docs/scenarios/rfc-upload/files/mta.yaml) | This file controls the behavior of the multitarget application (MTA) toolset. | Place the `mta.yaml` file in your application root folder and adjust the values in brackets with your data. |
    23  
    24  Depending on the modules in your MTA, additional configuration files are required, e.g. `pom.xml`  or `package.json`.
    25  
    26  ## Context
    27  
    28  This scenario combines various different steps to create a complete pipeline.
    29  
    30  In this scenario, we want to show how to build an application based on SAPUI5 or SAP Fiori by using the MTA concept and how to attach the build result to a transport request inside an ABAP system. This document comprises the [mtaBuild](../../../steps/mtaBuild/) step and the [transportRequestUploadRFC](../../../steps/transportRequestUploadRFC/) respectively the [transportRequestUploadCTS](../../../steps/transportRequestUploadCTS/) step.
    31  
    32  In case of an RFC based upload the binary is not streamed to the ABAP endpoint. Instead an URL pointing to the binary needs to be provided. Hence the binary must be published first so that it can be accessed via HTTP. This can happen by uploading the binary to a blob store or by archiving the artifact on Jenkins. The corresponding URL needs to be provided when the artifact is attached to the transport request.
    33  
    34  The transport request can be created on the fly (see [transportRequestCreate](../../../steps/transportRequestCreate/)) or we can use an already existing transport request. In case we use an already existing transport request Id the transport request Id needs to be provided in the git commit history (see  [transportRequestReqIDFromGit](../../../steps/transportRequestReqIDFromGit/)) or the transport request Id needs to be provided inside the job (e.g. as a job parameter).
    35  
    36  The transport request can be closed by the pipeline job (see [transportRequestRelease](../../../steps/transportRequestRelease/)).
    37  
    38  This is an example of a Git commit message containing the transport request ID:
    39  
    40  ```
    41  The headline
    42  
    43  The body. The blank line above is mandatory (Git standard).
    44  TransportRequest: <YOUR TRANSPORT REQUEST ID>
    45  ```
    46  
    47  By default, the Git commits between the merge base with the base branch (default: `master`) and the current branch head are traversed.
    48  
    49  ![This pipeline in Jenkins Blue Ocean](images/pipeline.png)
    50  
    51  **Screenshot: Build and Deploy Process in Jenkins**
    52  
    53  ## Examples
    54  
    55  ### Upload via RFC
    56  
    57  #### Jenkinsfile
    58  
    59  Following the convention for pipeline definitions, use a `Jenkinsfile`, which resides in the root directory of your development sources.
    60  
    61  ```groovy
    62  @Library('piper-lib-os') _
    63  
    64  
    65  pipeline {
    66  
    67      agent any
    68  
    69      stages {
    70          stage("prepare") {
    71              steps {
    72                  deleteDir()
    73                  checkout scm
    74                  setupCommonPipelineEnvironment script: this
    75              }
    76          }
    77  
    78          stage('build') {
    79              steps {
    80                  // It depends on your project, what needs to be done here. Maybe it's sufficient to zip the sources
    81                  mtaBuild script: this
    82              }
    83          }
    84  
    85          stage('publish') {
    86              steps {
    87                  // This uploads the binary into a blob store so that it can be attached to a transport request later
    88                  sh "curl --upload-file <deployable> <BLOB_STORE/path/to/application>"
    89  
    90                  // OR (in case there is no BLOB_STORE available)
    91  
    92                  // This makes the artifact available on Nexus. The URL is the following:
    93                  // <JENKINS_URL>/job/<JOB_NAME>/<BUILD_NUMBER>/artifact/<DEPLOYABLE>. Nota bene: this format is not an Jenkins API.
    94                  // The build number can be retrieved during the build through ${currentBuild.number}
    95                  archiveArtifacts artifacts: <deployable>
    96              }
    97          }
    98  
    99          // This attaches the deployable to a transport request
   100          stage('attach') {
   101              steps {
   102                  transportRequestUploadRFC script: this,
   103                                             transportRequestId: '<TRANSPORT_REQUEST_ID>', // This can be omitted if present inside a Git commit message
   104                                             applicationUrl: '<THE_URL_TO_THE_DEPLOYABLE_ACCORDING_TO_PUBLISH_STAGE>'
   105              }
   106          }
   107      }
   108  }
   109  ```
   110  
   111  #### Configuration (`.pipeline/config.yml`)
   112  
   113  This is a basic configuration example, which is also located in the sources of the project.
   114  
   115  ```yaml
   116  steps:
   117    transportRequestUploadRFC:
   118      changeManagement:
   119        endpoint: 'https://your.rfc.endpoint.com/' # e.g. example.com'
   120        credentialsId: 'RFC' # The ID under which the credentials are provided on Jenkins defaults to 'CM'
   121        instance: '01' # needs to be adjusted
   122        client: '001' # needs to be adjusted
   123      abapPackage: 'YOURPACK'
   124      applicationName: 'YOURAPP'
   125      applicationDescription: 'Your application description'
   126      dockerImage: 'my/rfc-client'
   127  ```
   128  
   129  ### Upload via ODATA
   130  
   131  #### Jenkinsfile
   132  
   133  Following the convention for pipeline definitions, use a `Jenkinsfile`, which resides in the root directory of your development sources.
   134  
   135  ```groovy
   136  @Library('piper-lib-os') _
   137  
   138  
   139  pipeline {
   140  
   141      agent any
   142  
   143      stages {
   144          stage("prepare") {
   145              steps {
   146                  deleteDir()
   147                  checkout scm
   148                  setupCommonPipelineEnvironment script: this
   149              }
   150          }
   151  
   152          stage('build') {
   153              steps {
   154                  // It depends on your project, what needs to be done here.
   155                  // Use the SAPUI5 toolset to build your SAPUI5 application
   156                  // and run the build command of the npmExecuteScripts step.
   157                  npmExecuteScripts(script: this, runScripts: ['build'])
   158              }
   159          }
   160          // Get the transport request id from your git commit message.
   161          stage('request') {
   162              steps {
   163                  transportRequestReqIDFromGit( script: this )
   164              }
   165          }
   166          // This attaches the deployable to a transport request.
   167          // Note: ODATA/CTS does not support the mtaBuild tool.
   168          stage('attach') {
   169              steps {
   170                  transportRequestUploadCTS script: this)
   171              }
   172          }
   173      }
   174  }
   175  ```
   176  
   177  #### Configuration (`.pipeline/config.yml`)
   178  
   179  This is a basic configuration example, which is also located in the sources of the project.
   180  
   181  ```yaml
   182  steps:
   183    transportRequestUploadCTS:
   184      changeManagement:
   185        endpoint: 'http://your.odata.endpoint/'
   186        credentialsId: 'CTS' # The ID under which the credentials are provided on Jenkins defaults to 'CM'
   187        clientOpts: '' # additional java options, e.g. '-Djavax.net.ssl.trustStore=/path/to/truststore.jks'
   188        client: '001'
   189      abapPackage: 'YOURPACK'
   190      applicationName: 'YOURAPP'
   191      applicationDescription: 'Your description'
   192  ```
   193  
   194  ## Parameters
   195  
   196  For the detailed description of the relevant parameters, see:
   197  
   198  * [transportRequestUploadCTS](../../../steps/transportRequestUploadCTS/)
   199  * [transportRequestReqIDFromGit](../../../steps/transportRequestReqIDFromGit/)
   200  * [npmExecuteScripts](../../../steps/npmExecuteScripts/)