CTS Upload Documentation (#3059)

* CTS Upload Doc
- add documentation of the step
- yaml affected

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.",
+		Short: "This step uploads an UI5 application to the SAPUI5 ABAP repository.",
-		Long:  `This step uploads a UI5 application from your project folder to the ABAP system via CTS connections.`,
+		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.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")
+	cmd.Flags().StringVar(&stepConfig.Endpoint, "endpoint", os.Getenv("PIPER_endpoint"), "The ODATA service endpoint: https://<host>:<port>")
 	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.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 ABAP system via CTS")
+	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{

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)
+   }
+```

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

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://<host>:<port>"
         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