From 3921c563c957a3aba142862b51e528dfa3cd900e Mon Sep 17 00:00:00 2001 From: Roland Stengel Date: Wed, 8 Sep 2021 12:38:33 +0200 Subject: [PATCH] CTS Upload Documentation (#3059) * CTS Upload Doc - add documentation of the step - yaml affected --- cmd/transportRequestUploadCTS_generated.go | 17 +- .../docs/steps/transportRequestUploadCTS.md | 173 ++++++++++++++++++ documentation/mkdocs.yml | 1 + .../metadata/transportRequestUploadCTS.yaml | 13 +- 4 files changed, 190 insertions(+), 14 deletions(-) create mode 100644 documentation/docs/steps/transportRequestUploadCTS.md diff --git a/cmd/transportRequestUploadCTS_generated.go b/cmd/transportRequestUploadCTS_generated.go index 32f94e3c3..e1be0436d 100644 --- a/cmd/transportRequestUploadCTS_generated.go +++ b/cmd/transportRequestUploadCTS_generated.go @@ -59,7 +59,7 @@ func (p *transportRequestUploadCTSCommonPipelineEnvironment) persist(path, resou } } -// TransportRequestUploadCTSCommand Uploads a UI5 application from your project folder to the ABAP system via CTS connections. +// TransportRequestUploadCTSCommand This step uploads an UI5 application to the SAPUI5 ABAP repository. func TransportRequestUploadCTSCommand() *cobra.Command { const STEP_NAME = "transportRequestUploadCTS" @@ -71,8 +71,9 @@ func TransportRequestUploadCTSCommand() *cobra.Command { var createTransportRequestUploadCTSCmd = &cobra.Command{ Use: STEP_NAME, - Short: "Uploads a UI5 application from your project folder to the ABAP system via CTS connections.", - Long: `This step uploads a UI5 application from your project folder to the ABAP system via CTS connections.`, + Short: "This step uploads an UI5 application to the SAPUI5 ABAP repository.", + Long: `This step uploads an UI5 application from your project folder to the SAPUI5 ABAP repository of the SAPUI5 ABAP back-end infrastructure using the SAPUI5 Repository OData service. +It processes the results of the ` + "`" + `ui5 build` + "`" + ` command of the SAPUI5 toolset.`, PreRunE: func(cmd *cobra.Command, _ []string) error { startTime = time.Now() log.SetStepName(STEP_NAME) @@ -138,11 +139,11 @@ func TransportRequestUploadCTSCommand() *cobra.Command { } func addTransportRequestUploadCTSFlags(cmd *cobra.Command, stepConfig *transportRequestUploadCTSOptions) { - cmd.Flags().StringVar(&stepConfig.Description, "description", `Deployed with Piper based on SAP Fiori tools`, "The description of the application. The desription is only taken into account for a new upload. In case of an update the description will not be updated.") - cmd.Flags().StringVar(&stepConfig.Endpoint, "endpoint", os.Getenv("PIPER_endpoint"), "The ODATA service endpoint") + cmd.Flags().StringVar(&stepConfig.Description, "description", `Deployed with Piper based on SAP Fiori tools`, "The description of the application. The description is only taken into account for a new upload. In case of an update the description will not be updated.") + cmd.Flags().StringVar(&stepConfig.Endpoint, "endpoint", os.Getenv("PIPER_endpoint"), "The ODATA service endpoint: https://:") cmd.Flags().StringVar(&stepConfig.Client, "client", os.Getenv("PIPER_client"), "The ABAP client") - cmd.Flags().StringVar(&stepConfig.Username, "username", os.Getenv("PIPER_username"), "Service user for uploading to the ABAP system via CTS") - cmd.Flags().StringVar(&stepConfig.Password, "password", os.Getenv("PIPER_password"), "Service user password for uploading to the ABAP system via CTS") + cmd.Flags().StringVar(&stepConfig.Username, "username", os.Getenv("PIPER_username"), "Service user for uploading to the SAPUI5 ABAP repository") + cmd.Flags().StringVar(&stepConfig.Password, "password", os.Getenv("PIPER_password"), "Service user password for uploading to the SAPUI5 ABAP repository") cmd.Flags().StringVar(&stepConfig.ApplicationName, "applicationName", os.Getenv("PIPER_applicationName"), "Name of the UI5 application") cmd.Flags().StringVar(&stepConfig.AbapPackage, "abapPackage", os.Getenv("PIPER_abapPackage"), "ABAP package name of the UI5 application") cmd.Flags().StringVar(&stepConfig.OsDeployUser, "osDeployUser", `node`, "Docker image user performing the deployment") @@ -164,7 +165,7 @@ func transportRequestUploadCTSMetadata() config.StepData { Metadata: config.StepMetadata{ Name: "transportRequestUploadCTS", Aliases: []config.Alias{{Name: "transportRequestUploadFile", Deprecated: false}}, - Description: "Uploads a UI5 application from your project folder to the ABAP system via CTS connections.", + Description: "This step uploads an UI5 application to the SAPUI5 ABAP repository.", }, Spec: config.StepSpec{ Inputs: config.StepInputs{ diff --git a/documentation/docs/steps/transportRequestUploadCTS.md b/documentation/docs/steps/transportRequestUploadCTS.md new file mode 100644 index 000000000..7d44f2e8b --- /dev/null +++ b/documentation/docs/steps/transportRequestUploadCTS.md @@ -0,0 +1,173 @@ +# ${docGenStepName} + +## ${docGenDescription} + +## Prerequisites + +* You have installed the [SAP component SAP_UI 7.53](https://help.sap.com/viewer/6f3c61a7a5b94447b80e72f722b0aad7/202009.002/en-US/35828457ed26452db8d51c840813f1bb.html) or higher on your ABAP system. +* You have enabled the OData Service to load data to the [SAPUI5 ABAP repository](https://sapui5.hana.ondemand.com/#/topic/a883327a82ef4cc792f3c1e7b7a48de8.html). +* You have the [S_DEVELOP authorization](https://sapui5.hana.ondemand.com/#/topic/a883327a82ef4cc792f3c1e7b7a48de8.html) to perform operations in your SAPUI5 ABAP repository. +* You have created a transport request on the ABAP system, which is the target container of the SAPUI5 application for your upload. + +## Setting Up an Upload Client + +The step `transportRequestUploadCTS` uses the [Node.js](https://nodejs.org)-based [SAP Fiori tools](https://help.sap.com/viewer/product/SAP_FIORI_tools/Latest/en-US) to upload your SAPUI5 application to the UI5 repository service of your ABAP back-end infrastructure. It performs the deployment command [Fiori deploy](https://www.npmjs.com/package/@sap/ux-ui5-tooling#fiori-deploy---performs-the-deployment-of-the-application-into-an-abap-system) on a Docker image. + +By default, a plain [node.js Docker image](https://hub.docker.com/_/node) is pulled and equipped with the SAPUI5 toolset during runtime of the pipeline. +Alternatively, you can provide your own, fully equipped Docker image. This speeds up the upload process, but requires you to maintain and provision the image on a Docker registry. + +### Creating a Fully Equipped Docker Image + +To create an own Docker image with the [SAP Fiori tools](https://help.sap.com/viewer/product/SAP_FIORI_tools/Latest/en-US), proceed as follows: + +1. Create a node.js based Docker image with the SAP Fiori tools installed: + + ```Dockerfile + FROM node + USER root + RUN npm install -global @ui5/cli @sap/ux-ui5-tooling @ui5/logger @ui5/fs + USER node + ``` + + ```/bin/bash + docker build -t my/fiori-node . + ``` + +1. Push your image to your private [Docker Hub registry](https://hub.docker.com/): + + ```/bin/bash + docker push my/fiori-node + ``` + +1. Add the following content to your `config.yml` file: + + ```yaml + steps: + transportRequestUploadCTS: + dockerImage: 'my/fiori-node' + deployToolDependencies: [] + ``` + +## Building an SAPUI5 Application + +Build your SAPUI5 application with the build command of the SAPUI5 toolset and use the step [npmExecuteScripts](npmExecuteScripts.md) to run the build command. Proceed as follows to do so: + +1. Configure the steps in the `package.json` file of your project as follows: + + ```json + { + ... + "scripts": { + "start": "ui5 serve", + "test": "npm run lint", + "build": "ui5 build --clean-dest", + ... + }, + "dependencies": {}, + "devDependencies": { + "@ui5/cli": "^2.11.2", + ... + } + } + ``` + +1. Configure the execution step in the pipeline as follows: + + ```groovy + stage('Build') { + npmExecuteScripts(script: this, runScripts: ['build']) + } + ``` + +**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. + +## Uploading an SAPUI5 Application + +The Fiori toolset uses the [ODATA service](https://ui5.sap.com/#/topic/a883327a82ef4cc792f3c1e7b7a48de8) to upload your UI5 application to the SAPUI5 ABAP repository. It controls access by [Basic Authentication](https://help.sap.com/viewer/e815bb97839a4d83be6c4fca48ee5777/202009.002/en-US/43960f4a527b58c1e10000000a422035.html?q=basic%20authentication) (user/password based authentication). + +**Note:** Do not upload your application to SAP Business Technology Platform. The SAP BTP does not support `Basic Authentication`. + +**Note:** Use an HTTPS endpoint to ensure the encryption of your credentials. + +## Specifying the Transport Request + +The target of the upload is a transport request, identified by an identifier (ID). + +The step `transportRequestUploadCTS` allows you to set the ID by parameter. + +Alternatively, you can pass the ID through the parameter `commonPipelineEnvironment`. +For example, by performing a step that generates the ID or obtains it differently. +For more information, see [transportRequestReqIDFromGit](transportRequestReqIDFromGit.md). + +### Adding a Parameter + +A parameterized pipeline allows you to specify the ID with the launch of each build instead of entering it statically into the pipeline. + +```groovy +transportRequestUploadCTS( + script: this, + transportRequestId: ${TRANSPORT_REQUEST_ID}, + ... +) +``` + +The Jenkins pipeline `input` step allows you to specify the ID at runtime of the pipeline. + +```groovy +def ids = input( message: "Upload?", + parameters: [ + string(name: 'TRANSPORT_REQUEST_ID',description: 'Transport Request ID') + ] +) + +transportRequestUploadCTS( + script:this, + transportRequestId: ids['TRANSPORT_REQUEST_ID'], + ... +) +``` + +## Common Pipeline Environment + +Use the step [transportRequestReqIDFromGit](transportRequestReqIDFromGit.md) to obtain the `transportRequestId` value from your Git commit messages. + +This step extracts the ID from the commit messages of your project repository and enters it into the `commonPipelineEnvironment`. In turn, the upload step `transportRequestUploadCTS` picks it up from there. + +```groovy +transportRequestReqIDFromGit( script: this ) +transportRequestUploadCTS( script: this, ... ) +``` + +## ${docGenParameters} + +## ${docGenConfiguration} + +## ${docJenkinsPluginDependencies} + +## Example + +```yaml +# config.yaml +steps: + transportRequestUploadCTS: + changeManagement: + credentialsId: 'CTS_CREDENTIALS_ID' + endpoint: 'https://example.org' + client: '001' + abapPackage: 'PACK' + applicationName: 'APP' + applicationDescription: 'Lorem ipsum' +``` + +```groovy +// pipeline script + stage('Init') { + transportRequestReqIDFromGit( script: this ) + } + stage('Build') { + npmExecuteScripts( script: this, runScripts: ['build']) + } + stage('Upload') { + transportRequestUploadCTS( script: this) + } +``` diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 4ab5332dc..c7cff7be1 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -151,6 +151,7 @@ nav: - transportRequestDocIDFromGit: steps/transportRequestDocIDFromGit.md - transportRequestRelease: steps/transportRequestRelease.md - transportRequestReqIDFromGit: steps/transportRequestReqIDFromGit.md + - transportRequestUploadCTS: steps/transportRequestUploadRFC.md - transportRequestUploadFile: steps/transportRequestUploadFile.md - transportRequestUploadRFC: steps/transportRequestUploadRFC.md - transportRequestUploadSOLMAN: steps/transportRequestUploadSOLMAN.md diff --git a/resources/metadata/transportRequestUploadCTS.yaml b/resources/metadata/transportRequestUploadCTS.yaml index f3fa21948..4506cffd8 100644 --- a/resources/metadata/transportRequestUploadCTS.yaml +++ b/resources/metadata/transportRequestUploadCTS.yaml @@ -2,9 +2,10 @@ metadata: name: transportRequestUploadCTS aliases: - name: transportRequestUploadFile - description: Uploads a UI5 application from your project folder to the ABAP system via CTS connections. + description: This step uploads an UI5 application to the SAPUI5 ABAP repository. longDescription: | - This step uploads a UI5 application from your project folder to the ABAP system via CTS connections. + This step uploads an UI5 application from your project folder to the SAPUI5 ABAP repository of the SAPUI5 ABAP back-end infrastructure using the SAPUI5 Repository OData service. + It processes the results of the `ui5 build` command of the SAPUI5 toolset. spec: inputs: secrets: @@ -16,7 +17,7 @@ spec: params: - name: description type: string - description: "The description of the application. The desription is only taken into account for a new upload. In case of an update the description will not be updated." + description: "The description of the application. The description is only taken into account for a new upload. In case of an update the description will not be updated." default: "Deployed with Piper based on SAP Fiori tools" scope: - PARAMETERS @@ -25,7 +26,7 @@ spec: - GENERAL - name: endpoint type: string - description: "The ODATA service endpoint" + description: "The ODATA service endpoint: https://:" aliases: - name: changeManagement/endpoint - name: changeManagement/cts/endpoint @@ -48,7 +49,7 @@ spec: - name: username type: string mandatory: true - description: "Service user for uploading to the ABAP system via CTS" + description: "Service user for uploading to the SAPUI5 ABAP repository" secret: true scope: - PARAMETERS @@ -58,7 +59,7 @@ spec: - name: password type: string mandatory: true - description: "Service user password for uploading to the ABAP system via CTS" + description: "Service user password for uploading to the SAPUI5 ABAP repository" secret: true scope: - PARAMETERS