github.com/ouraigua/jenkins-library@v0.0.0-20231028010029-fbeaf2f3aa9b/documentation/docs/steps/transportRequestUploadFile.md (about)

     1  # ${docGenStepName}
     2  
     3  ## ${docGenDescription}
     4  
     5  **Note:** This step is deprecated. Use the transport type specific steps instead.
     6  
     7  | Type  | Step |
     8  | ------------- | ------------- |
     9  | SOLMAN  | [transportRequestUploadSOLMAN](transportRequestUploadSOLMAN.md)  |
    10  | RFC  | [transportRequestUploadRFC](transportRequestUploadRFC.md)  |
    11  | CTS  | [transportRequestUploadCTS](transportRequestUploadCTS.md)  |
    12  
    13  You can keep most of the step specific configuration parameters in your configuration file `config.yml` untouched. The new steps support the old naming convention. However, it is recommended to adjust your parameters to the new steps.
    14  
    15  Following parameters are not supported anymore. Adjust as indicated.
    16  
    17  | Unsupported Parameter | Change Notice |
    18  | ------------- | ------------- |
    19  | changeManagement/`<type>`/docker/envVars | Use `dockerEnvVars` instead. |
    20  | changeManagement/`<type>`/docker/image | Use `dockerImage` instead. |
    21  | changeManagement/`<type>`/docker/options | Use `dockerOptions` instead. |
    22  | changeManagement/`<type>`/docker/pullImage | Use `dockerPullImage` instead. |
    23  | changeManagement/git/format | This parameter has been dropped. Make sure that your change document IDs and transport request IDs are part of the Git commit message body. |
    24  
    25  ```yaml
    26  general:
    27    changeManagement:
    28      type: 'RFC'
    29  # old
    30      rfc:
    31        docker:
    32          image: 'my/rfc-client'
    33  
    34  #new
    35  steps:
    36    transportRequestUploadRFC:
    37      dockerImage: 'my/rfc-client'
    38  ```
    39  
    40  **Note:** The new steps do not comprise the retrieval of the change document ID and the transport request ID from the Git repository. Use the steps [transportRequestDocIDFromGit](transportRequestDocIDFromGit.md) and [transportRequestReqIDFromGit](transportRequestReqIDFromGit.md) instead.
    41  
    42  ## ${docGenParameters}
    43  
    44  ## ${docGenConfiguration}
    45  
    46  ## ${docJenkinsPluginDependencies}
    47  
    48  The step is configured using a customer configuration file provided as
    49  resource in an custom shared library.
    50  
    51  ```groovy
    52  @Library('piper-lib-os@master') _
    53  
    54  // the shared lib containing the additional configuration
    55  // needs to be configured in Jenkins
    56  @Library('foo@master') __
    57  
    58  // inside the shared lib denoted by 'foo' the additional configuration file
    59  // needs to be located under 'resources' ('resoures/myConfig.yml')
    60  prepareDefaultValues script: this,
    61                               customDefaults: 'myConfig.yml'
    62  ```
    63  
    64  Example content of `'resources/myConfig.yml'` in branch `'master'` of the repository denoted by
    65  `'foo'`:
    66  
    67  ```yaml
    68  general:
    69    changeManagement:
    70      changeDocumentLabel: 'ChangeDocument\s?:'
    71      cmClientOpts: '-Djavax.net.ssl.trustStore=<path to truststore>'
    72      credentialsId: 'CM'
    73      type: 'SOLMAN'
    74      endpoint: 'https://example.org/cm'
    75      git:
    76        from: 'HEAD~1'
    77        to: 'HEAD'
    78        format: '%b'
    79  ```
    80  
    81  The properties configured in section `'general/changeManagement'` are shared between all change management related steps.
    82  
    83  The properties can also be configured on a per-step basis:
    84  
    85  ```yaml
    86    [...]
    87    steps:
    88      transportRequestUploadFile:
    89        applicationId: 'FOO'
    90        changeManagement:
    91          type: 'SOLMAN'
    92          endpoint: 'https://example.org/cm'
    93          [...]
    94  ```
    95  
    96  The parameters can also be provided when the step is invoked. For examples see below.
    97  
    98  ## CTS Uploads
    99  
   100  In order to be able to upload the application, it is required to build the application, e.g. via [npmExecuteScripts](npmExecuteScripts.md). The content of the app needs to be provided in a folder named `dist` in the root level of the project.
   101  
   102  **Note:** Do not use the `mtaBuild` step. The MTA Build Tool `mta` is dedicated to the SAP Business Technology Platform. It does neither create the expected `dist` folder nor the compliant content.
   103  
   104  Although the name of the step `transportRequestUploadFile` might suggest something else, in this case a folder needs
   105  to be provided. The application, which is provided in the `dist` folder is zipped and uploaded by the fiori toolset
   106  used for performing the upload.
   107  
   108  For `CTS` related uploads we use a node based toolset. When running in a docker environment a standard node
   109  image can be used. In this case the required deploy tool dependencies will be installed prior to the deploy.
   110  It is also possible to provide a docker image which already contains the required deploy tool
   111  dependencies (`config.changeManagement.cts.nodeDocker.image`). In this case an empty list needs to be provided
   112  as `config.changeManagement.cts.deployToolDependencies`. Using an already pre-configured docker image speeds-up
   113  the deployment step, but comes with the disadvantage of having
   114  to maintain and provision the corresponding docker image.
   115  
   116  When running in an environment without docker, it is recommanded to install the deploy tools manually on the
   117  system and to provide an empty list for the deploy tool dependencies (`config.changeManagement.cts.deployToolDependencies`).
   118  
   119  ### Examples
   120  
   121  #### Upload based on preconfigured image
   122  
   123  ```groovy
   124  transportRequestUploadFile script: this,
   125              changeManagement: [
   126                  credentialsId: 'CRED_ID', // credentials needs to be defined inside Jenkins
   127                  type: 'CTS',
   128                  endpoint: 'https://example.org:8000',
   129                  client: '001',
   130                  cts: [
   131                      nodeDocker: [
   132                          image: 'docker-image-name',
   133                          pullImage: true,  // needs to be set to false in case the image is
   134                                            // only available in the local docker cache (not recommended)
   135                      ],
   136                      npmInstallOpts: [],
   137                  deployToolDependencies: [], // empty since we use an already preconfigured image
   138                  ],
   139              ],
   140              applicationName: 'APP',
   141              abapPackage: 'ABABPACKAGE',
   142              transportRequestId: 'XXXK123456', // can be omitted when resolved via commit history
   143              applicationDescription: 'An optional description' // only used in case a new application is deployed
   144                                                                // description is not updated for re-deployments
   145      }
   146  
   147  ```
   148  
   149  #### Upload based on a standard node image
   150  
   151  ```groovy
   152          transportRequestUploadFile script: this,
   153              changeManagement: [
   154                  credentialsId: 'CRED_ID', // credentials needs to be defined inside Jenkins
   155                  type: 'CTS',
   156                  endpoint: 'https://example.org:8000',
   157                  client: '001',
   158                  cts: [
   159                      npmInstallOpts: [
   160                          '--verbose', // might be benefical for troubleshooting
   161                          '--registry', 'https://your.npmregistry.org/', // an own registry can be specified here
   162                      ],
   163                  ],
   164              ],
   165              applicationName: 'APP',
   166              abapPackage: 'ABABPACKAGE',
   167              transportRequestId: 'XXXK123456', // can be omitted when resolved via commit history
   168              applicationDescription: 'An optional description' // only used in case a new application is deployed
   169                                                                // description is not updated for re-deployments
   170      }
   171  
   172  ```
   173  
   174  ## Exceptions
   175  
   176  * `IllegalArgumentException`:
   177    * If the change id is not provided (`SOLMAN` only).
   178    * If the transport request id is not provided.
   179    * If the application id is not provided (`SOLMAN` only).
   180    * If the file path is not provided.
   181  * `AbortException`:
   182    * If the upload fails.
   183  
   184  ## Example
   185  
   186  ```groovy
   187  // SOLMAN
   188  transportRequestUploadFile(
   189    script: this,
   190    changeDocumentId: '001',   // typically provided via git commit history
   191    transportRequestId: '001', // typically provided via git commit history
   192    applicationId: '001',
   193    filePath: '/path',
   194    changeManagement: [
   195      type: 'SOLMAN'
   196      endpoint: 'https://example.org/cm'
   197    ]
   198  )
   199  // CTS
   200  
   201  transportRequestUploadFile(
   202    script: this,
   203    transportRequestId: '001', // typically provided via git commit history
   204    changeManagement: [
   205      type: 'CTS'
   206      endpoint: 'https://example.org/cm',
   207      client: '099',
   208    ],
   209    applicationName: 'myApp',
   210    abapPackage: 'MYPACKAGE',
   211  )
   212  ```