RFC Upload Documentation (#2922)

RFC Upload Doc
- add RFC upload document

cmd/transportRequestReqIDFromGit_generated.go

@@ -64,7 +64,7 @@ func TransportRequestReqIDFromGitCommand() *cobra.Command {
 		Use:   STEP_NAME,
 		Short: "Retrieves the transport request ID from Git repository",
 		Long: `This step scans the commit messages of the Git repository for a pattern to retrieve the transport request ID.
-It is primarily made for the transportRequestUploadSOLMAN step to provide the transport reques ID by Git means.`,
+It is primarily made for the transport request upload steps to provide the transport request ID by Git means.`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)

cmd/transportRequestUploadRFC_generated.go

@@ -60,7 +60,7 @@ func (p *transportRequestUploadRFCCommonPipelineEnvironment) persist(path, resou
 	}
 }
 
-// TransportRequestUploadRFCCommand Uploads a UI5 application as ZIP file to the ABAP system via RFC connections.
+// TransportRequestUploadRFCCommand This step uploads a UI5 application as ZIP file to the ABAP system via RFC connections.
 func TransportRequestUploadRFCCommand() *cobra.Command {
 	const STEP_NAME = "transportRequestUploadRFC"
 
@@ -72,7 +72,7 @@ func TransportRequestUploadRFCCommand() *cobra.Command {
 
 	var createTransportRequestUploadRFCCmd = &cobra.Command{
 		Use:   STEP_NAME,
-		Short: "Uploads a UI5 application as ZIP file to the ABAP system via RFC connections.",
+		Short: "This step uploads a UI5 application as ZIP file to the ABAP system via RFC connections.",
 		Long:  `This step uploads a UI5 application as ZIP file to the ABAP system via RFC connections.`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
@@ -139,13 +139,13 @@ func TransportRequestUploadRFCCommand() *cobra.Command {
 func addTransportRequestUploadRFCFlags(cmd *cobra.Command, stepConfig *transportRequestUploadRFCOptions) {
 	cmd.Flags().StringVar(&stepConfig.Endpoint, "endpoint", os.Getenv("PIPER_endpoint"), "Service endpoint, Application server URL")
 	cmd.Flags().StringVar(&stepConfig.Instance, "instance", os.Getenv("PIPER_instance"), "AS ABAP instance number")
-	cmd.Flags().StringVar(&stepConfig.Username, "username", os.Getenv("PIPER_username"), "Service user for uploading to the ABAP backend via RFC")
+	cmd.Flags().StringVar(&stepConfig.Username, "username", os.Getenv("PIPER_username"), "Service user for uploading to the ABAP system via RFC")
-	cmd.Flags().StringVar(&stepConfig.Password, "password", os.Getenv("PIPER_password"), "Service user password for uploading to the ABAP backend via RFC")
+	cmd.Flags().StringVar(&stepConfig.Password, "password", os.Getenv("PIPER_password"), "Service user password for uploading to the ABAP system via RFC")
 	cmd.Flags().StringVar(&stepConfig.Client, "client", os.Getenv("PIPER_client"), "AS ABAP client number")
 	cmd.Flags().StringVar(&stepConfig.ApplicationName, "applicationName", os.Getenv("PIPER_applicationName"), "Name of the UI5 application")
 	cmd.Flags().StringVar(&stepConfig.ApplicationDescription, "applicationDescription", os.Getenv("PIPER_applicationDescription"), "Description 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.ApplicationURL, "applicationUrl", os.Getenv("PIPER_applicationUrl"), "URL of the UI5 application package to upload to the ABAP backend via RFC")
+	cmd.Flags().StringVar(&stepConfig.ApplicationURL, "applicationUrl", os.Getenv("PIPER_applicationUrl"), "URL of the UI5 application package to upload to the ABAP system via RFC")
 	cmd.Flags().StringVar(&stepConfig.CodePage, "codePage", `UTF-8`, "Code page")
 	cmd.Flags().BoolVar(&stepConfig.AcceptUnixStyleLineEndings, "acceptUnixStyleLineEndings", true, "If unix style line endings should be accepted")
 	cmd.Flags().BoolVar(&stepConfig.FailUploadOnWarning, "failUploadOnWarning", true, "If the upload should fail in case the log contains warnings")
@@ -166,12 +166,12 @@ func transportRequestUploadRFCMetadata() config.StepData {
 		Metadata: config.StepMetadata{
 			Name:        "transportRequestUploadRFC",
 			Aliases:     []config.Alias{{Name: "transportRequestUploadFile", Deprecated: false}},
-			Description: "Uploads a UI5 application as ZIP file to the ABAP system via RFC connections.",
+			Description: "This step uploads a UI5 application as ZIP file to the ABAP system via RFC connections.",
 		},
 		Spec: config.StepSpec{
 			Inputs: config.StepInputs{
 				Secrets: []config.StepSecrets{
-					{Name: "uploadCredentialsId", Description: "Jenkins 'Username with password' credentials ID containing user and password to authenticate against the ABAP backend", Type: "jenkins", Aliases: []config.Alias{{Name: "changeManagement/credentialsId", Deprecated: false}}},
+					{Name: "uploadCredentialsId", Description: "Jenkins 'Username with password' credentials ID containing user and password to authenticate against the ABAP system", Type: "jenkins", Aliases: []config.Alias{{Name: "changeManagement/credentialsId", Deprecated: false}}},
 				},
 				Parameters: []config.StepParameters{
 					{

documentation/docs/steps/transportRequestUploadRFC.md

@@ -0,0 +1,105 @@
+# ${docGenStepName}
+
+## ${docGenDescription}
+
+## Prerequisites
+
+* You have enabled RFC on the ABAP system.
+* You have a user account on the ABAP system where you have assigned the required roles for uploading via RFC.
+* You have created a transport request on the ABAP system, which is the target container of the upload.
+
+## RFC Client
+
+The RFC Client connects to your ABAP system using the [SAP NetWeaver RFC SDK](https://support.sap.com/en/product/connectors/nwrfcsdk.html).
+
+For more information, see [classical SAP connectivity technology RFC](https://help.sap.com/viewer/753088fc00704d0a80e7fbd6803c8adb/1709%20000/en-US/4888068ad9134076e10000000a42189d.html).
+
+To install an RFC library based Connector Client, proceed as follows:
+
+1. Create a Docker image as described in the Git repository [devops-docker-images/node-rfc](https://github.com/rodibrin/devops-docker-images/tree/master/node-rfc).
+1. Push your image to your private [Docker Hub registry](https://hub.docker.com/).
+1. Add the following to your config.yml file:
+
+```yaml
+steps:
+  transportRequestUploadRFC:
+    dockerImage: 'my/rfc-client'
+```
+
+## Specifying the Transport Request
+
+The target of the upload is a transport request, identified by an identifier (ID).
+
+The step `transportRequestUploadRFC` allows you to set the ID by parameter.
+
+Alternatively, you can pass the ID through the `commonPipelineEnvironment`.
+For example, by performing a step that generates the ID or obtains it differently.
+See [transportRequestReqIDFromGit](transportRequestReqIDFromGit.md).
+
+### Adding a Parameter
+
+A parameterized pipeline allows you to specify the ID with the launch of the build instead of entering it statically into the pipeline.
+
+```groovy
+transportRequestUploadRFC(
+    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')
+    ]
+)
+
+transportRequestUploadRFC(
+    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 `transportRequestUploadRFC` picks it up from there.
+
+```groovy
+transportRequestReqIDFromGit( script: this )
+transportRequestUploadRFC( script: this, ... )
+```
+
+## ${docGenParameters}
+
+## ${docGenConfiguration}
+
+## ${docJenkinsPluginDependencies}
+
+## Example
+
+```yaml
+# config.yaml
+steps:
+  transportRequestUploadRFC:
+    changeManagement:
+      credentialsId: 'RFC_CREDENTIALS_ID'
+      endpoint: 'https://example.org/cm/rfc/endpoint'
+      instance: '00'
+      client: '001'
+    abapPackage: 'PACK'
+    applicationDescription: 'Lorem ipsum'
+    applicationName: 'APP'
+    dockerImage: 'my/rfc-client'
+```
+
+```groovy
+// pipeline script
+transportRequestReqIDFromGit( script: this )
+transportRequestUploadRFC( script: this, applicationUrl: 'https://example.org/appl/url/archive.zip')
+```

documentation/mkdocs.yml

@@ -148,6 +148,7 @@ nav:
         - transportRequestRelease:  steps/transportRequestRelease.md
         - transportRequestReqIDFromGit: steps/transportRequestReqIDFromGit.md
         - transportRequestUploadFile: steps/transportRequestUploadFile.md
+        - transportRequestUploadRFC: steps/transportRequestUploadRFC.md
         - transportRequestUploadSOLMAN: steps/transportRequestUploadSOLMAN.md
         - uiVeri5ExecuteTests: steps/uiVeri5ExecuteTests.md
         - vaultRotateSecretId: steps/vaultRotateSecretId.md

resources/metadata/transportRequestReqIDFromGit.yaml

@@ -3,7 +3,7 @@ metadata:
   description: "Retrieves the transport request ID from Git repository"
   longDescription: |
     This step scans the commit messages of the Git repository for a pattern to retrieve the transport request ID.
-    It is primarily made for the transportRequestUploadSOLMAN step to provide the transport reques ID by Git means.
+    It is primarily made for the transport request upload steps to provide the transport request ID by Git means.
 spec:
   inputs:
     params:

resources/metadata/transportRequestUploadRFC.yaml

@@ -2,14 +2,14 @@ metadata:
   name: transportRequestUploadRFC
   aliases:
     - name: transportRequestUploadFile
-  description: Uploads a UI5 application as ZIP file to the ABAP system via RFC connections.
+  description: This step uploads a UI5 application as ZIP file to the ABAP system via RFC connections.
   longDescription: |
     This step uploads a UI5 application as ZIP file to the ABAP system via RFC connections.
 spec:
   inputs:
     secrets:
       - name: uploadCredentialsId
-        description: Jenkins 'Username with password' credentials ID containing user and password to authenticate against the ABAP backend
+        description: Jenkins 'Username with password' credentials ID containing user and password to authenticate against the ABAP system
         type: jenkins
         aliases:
           - name: changeManagement/credentialsId
@@ -39,7 +39,7 @@ spec:
       - name: username
         type: string
         mandatory: true
-        description: "Service user for uploading to the ABAP backend via RFC"
+        description: "Service user for uploading to the ABAP system via RFC"
         secret: true
         scope:
           - PARAMETERS
@@ -53,7 +53,7 @@ spec:
       - name: password
         type: string
         mandatory: true
-        description: "Service user password for uploading to the ABAP backend via RFC"
+        description: "Service user password for uploading to the ABAP system via RFC"
         secret: true
         scope:
           - PARAMETERS
@@ -102,7 +102,7 @@ spec:
       - name: applicationUrl
         type: string
         mandatory: true
-        description: "URL of the UI5 application package to upload to the ABAP backend via RFC"
+        description: "URL of the UI5 application package to upload to the ABAP system via RFC"
         scope:
           - PARAMETERS
           - STAGES