Add documentation for transportRequestUploadSOLMAN (#2754)

cmd/transportRequestUploadSOLMAN_generated.go

@@ -60,7 +60,7 @@ func (p *transportRequestUploadSOLMANCommonPipelineEnvironment) persist(path, re
 	}
 }
 
-// TransportRequestUploadSOLMANCommand Uploads content to a transport request
+// TransportRequestUploadSOLMANCommand Uploads a specified file into a given transport via Solution Manager
 func TransportRequestUploadSOLMANCommand() *cobra.Command {
 	const STEP_NAME = "transportRequestUploadSOLMAN"
 
@@ -71,8 +71,10 @@ func TransportRequestUploadSOLMANCommand() *cobra.Command {
 
 	var createTransportRequestUploadSOLMANCmd = &cobra.Command{
 		Use:   STEP_NAME,
-		Short: "Uploads content to a transport request",
+		Short: "Uploads a specified file into a given transport via Solution Manager",
-		Long:  `Uploads content to a transport request which is associated with a change document in SAP Solution Manager`,
+		Long: `Uploads the specified file into the given transport request via Solution Manager.
+The mandatory change document ID points to the associate change document item.
+The application ID specifies how the file needs to be handled on server side.`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)
@@ -122,17 +124,17 @@ func TransportRequestUploadSOLMANCommand() *cobra.Command {
 
 func addTransportRequestUploadSOLMANFlags(cmd *cobra.Command, stepConfig *transportRequestUploadSOLMANOptions) {
 	cmd.Flags().StringVar(&stepConfig.Endpoint, "endpoint", os.Getenv("PIPER_endpoint"), "Service endpoint")
-	cmd.Flags().StringVar(&stepConfig.Username, "username", os.Getenv("PIPER_username"), "Operating system user for triggering the deployment")
+	cmd.Flags().StringVar(&stepConfig.Username, "username", os.Getenv("PIPER_username"), "Service user for uploading to the Solution Manager")
-	cmd.Flags().StringVar(&stepConfig.Password, "password", os.Getenv("PIPER_password"), "Password for the deploy user")
+	cmd.Flags().StringVar(&stepConfig.Password, "password", os.Getenv("PIPER_password"), "Service user password for uploading to the Solution Manager")
-	cmd.Flags().StringVar(&stepConfig.ApplicationID, "applicationId", os.Getenv("PIPER_applicationId"), "Id of the application.")
+	cmd.Flags().StringVar(&stepConfig.ApplicationID, "applicationId", os.Getenv("PIPER_applicationId"), "Id of the application. Specifies how the file needs to be handled on server side")
-	cmd.Flags().StringVar(&stepConfig.ChangeDocumentID, "changeDocumentId", os.Getenv("PIPER_changeDocumentId"), "Id of the change document to upload the file. This parameter is only taken into account when provided via signature to the step.")
+	cmd.Flags().StringVar(&stepConfig.ChangeDocumentID, "changeDocumentId", os.Getenv("PIPER_changeDocumentId"), "ID of the change document to which the file is uploaded")
-	cmd.Flags().StringVar(&stepConfig.TransportRequestID, "transportRequestId", os.Getenv("PIPER_transportRequestId"), "Id of the transport request to upload the file. This parameter is only taken into account when provided via signature to the step.")
+	cmd.Flags().StringVar(&stepConfig.TransportRequestID, "transportRequestId", os.Getenv("PIPER_transportRequestId"), "ID of the transport request to which the file is uploaded")
 	cmd.Flags().StringVar(&stepConfig.FilePath, "filePath", os.Getenv("PIPER_filePath"), "Name/Path of the file which should be uploaded")
 	cmd.Flags().StringSliceVar(&stepConfig.CmClientOpts, "cmClientOpts", []string{}, "Additional options handed over to the cm client")
-	cmd.Flags().StringVar(&stepConfig.GitFrom, "gitFrom", `origin/master`, "GIT starting point for retrieving the change document and transport request id")
+	cmd.Flags().StringVar(&stepConfig.GitFrom, "gitFrom", `origin/master`, "GIT starting point for retrieving the change document and transport request ID")
-	cmd.Flags().StringVar(&stepConfig.GitTo, "gitTo", `HEAD`, "GIT ending point for retrieving the change document and transport request id")
+	cmd.Flags().StringVar(&stepConfig.GitTo, "gitTo", `HEAD`, "GIT ending point for retrieving the change document and transport request ID")
-	cmd.Flags().StringVar(&stepConfig.ChangeDocumentLabel, "changeDocumentLabel", `ChangeDocument`, "Pattern used for identifying lines holding the change document id")
+	cmd.Flags().StringVar(&stepConfig.ChangeDocumentLabel, "changeDocumentLabel", `ChangeDocument`, "Pattern used for identifying lines holding the change document ID. The GIT commit log messages are scanned for this label")
-	cmd.Flags().StringVar(&stepConfig.TransportRequestLabel, "transportRequestLabel", `TransportRequest`, "Pattern used for identifying lines holding the transport request id")
+	cmd.Flags().StringVar(&stepConfig.TransportRequestLabel, "transportRequestLabel", `TransportRequest`, "Pattern used for identifying lines holding the transport request ID. The GIT commit log messages are scanned for this label")
 
 	cmd.MarkFlagRequired("endpoint")
 	cmd.MarkFlagRequired("username")
@@ -148,7 +150,7 @@ func transportRequestUploadSOLMANMetadata() config.StepData {
 		Metadata: config.StepMetadata{
 			Name:        "transportRequestUploadSOLMAN",
 			Aliases:     []config.Alias{{Name: "transportRequestUploadFile", Deprecated: false}},
-			Description: "Uploads content to a transport request",
+			Description: "Uploads a specified file into a given transport via Solution Manager",
 		},
 		Spec: config.StepSpec{
 			Inputs: config.StepInputs{

documentation/docs/steps/transportRequestUploadSOLMAN.md

@@ -0,0 +1,135 @@
+# ${docGenStepName}
+
+## ${docGenDescription}
+
+## Prerequisites
+
+* You have an SAP Solution Manager user account and the roles required for uploading. See [SAP Solution Manager Administration](https://help.sap.com/viewer/c413647f87a54db59d18cb074ce3dafd/7.2.12/en-US/11505ddff03c4d74976dae648743e10e.html).
+* You have a change document to which your transport request is coupled.
+* You have a transport request, which is the target container of the upload.
+* You have installed the Change Management Client with the needed certificates.
+
+## Change Management Client
+
+The Change Management Client (CM Client) handles the access to SAP Solution Manager.
+The CM Client is a software running under Linux, which can initiate basic change management tasks
+in the Solution Manager as well as in the CTS. The client is used by default
+as  a [Docker image](https://hub.docker.com/r/ppiper/cm-client),
+but can also be installed as a [command line tool](https://github.com/SAP/devops-cm-client).
+
+### Certificates
+
+It is expected that the Solution Manager endpoint is secured by SSL and sends a certificate accordingly.
+The certificate is verified by the CM Client. If the publisher of this certificate is unknown,
+the connection will be rejected. The client implemented in Java uses
+the underlying JDK procedures for the verification. Accordingly, the issuer must be specified in the
+truststore of the JDK. In the case of the [Docker image](https://hub.docker.com/r/ppiper/cm-client)
+a clone of the image must be created with the necessary certificate added to its truststore.
+In the case of the immediate [command line tool](https://github.com/SAP/devops-cm-client),
+only the truststore of the environment needs to be extended.
+
+## Specifying the Change document and transport request
+
+The target of the upload is a Transport Request, which is determined by the identifiers (ID)
+of the Request and the associated Change Document.
+`transportRequestUploadSOLMAN` allows to set these IDs by parameter or to use Git commit messages.
+As an additional option, IDs can be passed in via the Common Pipeline Environment. For example through a
+step that generates the IDs or obtains them differently.
+
+### By Step Parameter
+
+A parameterized pipeline allows to specify the IDs with the launch of the build
+instead of entering them statically into the pipeline.
+
+```groovy
+transportRequestUploadSOLMAN(
+    script: this,
+    changeDocumentId: ${CHANGE_DOCUMENT_ID},
+    transportRequestId: ${TRANSPORT_REQUEST_ID},
+    ...
+)
+```
+
+The Jenkins pipeline `input` step allows to specify the IDs at runtime of the pipeline.
+
+```groovy
+def ids = input( message: "Upload?",
+    parameters: [
+        string(name: 'CHANGE_DOCUMENT_ID',description: 'Change Document ID'),
+        string(name: 'TRANSPORT_REQUEST_ID',description: 'Transport Request ID')
+    ]
+)
+
+transportRequestUploadSOLMAN(
+    script:this,
+    changeDocumentId: ids['CHANGE_DOCUMENT_ID'],
+    transportRequestId: ids['TRANSPORT_REQUEST_ID'],
+    ...
+)
+```
+
+### By Git Commit Message
+
+If the identifiers are neither defined as step parameters nor by the Common Pipeline Environment,
+the Git commit messages (`git log`) of the project are searched for lines that follow a defined pattern.
+The pattern is specified by the label _changeDocumentLabel_ (default=`ChangeDocument`) resp.
+_transportRequestLabel_ (default=`TransportRequest`). Behind the label a colon,
+any blanks and the identifier are expected.
+
+```
+Release - define IDs for upload to Solution Manager
+
+    ChangeDocument: 1000001234
+    TransportRequest: ABCD10005E
+```
+
+The IDs dont need to be defined in the same commit message.
+
+The Git commit messages to be considered are determined by the parameters _gitFrom_ (default=`origin/master`)
+and _gitTo_ (default=`HEAD`). The naming follows the Git revision range representation `git log <gitFrom>..<gitTo>`.
+All commit messages accessible from _gitTo_ but not from _gitFrom_ are taken into account. If the scanner
+detects multiple IDs, it fails. So the commit range has to be chosen accordingly.
+
+In case of a pull request of a feature branch, the default should be sufficient as long as the transport request
+isn't changed. Only the commits (`HEAD`) that have not yet entered the main branch `origin/master` would be scanned.
+
+If uploading from the main branch, it must be assumed that former change document and transport request IDs
+are already contained in the history. In this case the new IDs should be maintained in the `HEAD` and
+_gitFrom_ be set to `HEAD~1`.
+
+```yaml
+general:
+  changeManagement:
+    git:
+      from: 'HEAD~1'
+```
+
+## Common Pipeline Environment
+
+If `changeDocumentId` and `transportRequestId` are determined during runtime via the Git commit messages, they are entered into the `commonPipelineEnvironment` and can be retrieved accordingly.
+
+```
+  this.commonPipelineEnvironment.getValue('changeDocumentID')
+  this.commonPipelineEnvironment.getValue('transportRequestID')
+```
+
+## ${docGenParameters}
+
+## ${docGenConfiguration}
+
+## ${docJenkinsPluginDependencies}
+
+## Example
+
+```groovy
+transportRequestUploadSOLMAN(
+  script: this,
+  endpoint: 'https://example.org/cm/solman/endpoint'
+  applicationId: 'ABC',
+  uploadCredentialsId: "SOLMAN_CRED_ID"
+  changeDocumentId: '12345678',
+  transportRequestId: '87654321',
+  filePath: '/path/file.ext',
+  cmClientOpts: '-Dkey=value'
+)
+```

resources/metadata/transportRequestUploadSOLMAN.yaml

@@ -2,14 +2,16 @@ metadata:
   name: transportRequestUploadSOLMAN
   aliases:
     - name: transportRequestUploadFile
-  description: "Uploads content to a transport request"
+  description: "Uploads a specified file into a given transport via Solution Manager"
   longDescription: |
-    Uploads content to a transport request which is associated with a change document in SAP Solution Manager
+    Uploads the specified file into the given transport request via Solution Manager.
+    The mandatory change document ID points to the associate change document item.
+    The application ID specifies how the file needs to be handled on server side.
 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 backend
         type: jenkins
         aliases:
           - name: changeManagement/credentialsId
@@ -28,7 +30,7 @@ spec:
       - name: username
         type: string
         mandatory: true
-        description: "Operating system user for triggering the deployment"
+        description: "Service user for uploading to the Solution Manager"
         secret: true
         scope:
           - PARAMETERS
@@ -42,7 +44,7 @@ spec:
       - name: password
         type: string
         mandatory: true
-        description: "Password for the deploy user"
+        description: "Service user password for uploading to the Solution Manager"
         secret: true
         scope:
           - PARAMETERS
@@ -53,7 +55,7 @@ spec:
       - name: applicationId
         type: string
         mandatory: true
-        description: "Id of the application."
+        description: "Id of the application. Specifies how the file needs to be handled on server side"
         scope:
           - PARAMETERS
           - STAGES
@@ -64,7 +66,7 @@ spec:
           - name: commonPipelineEnvironment
             param: custom/changeDocumentId
         type: string
-        description: "Id of the change document to upload the file. This parameter is only taken into account when provided via signature to the step."
+        description: "ID of the change document to which the file is uploaded"
         scope:
           - PARAMETERS
       - name: transportRequestId
@@ -72,7 +74,7 @@ spec:
           - name: commonPipelineEnvironment
             param: custom/transportRequestId
         type: string
-        description: "Id of the transport request to upload the file. This parameter is only taken into account when provided via signature to the step."
+        description: "ID of the transport request to which the file is uploaded"
         scope:
           - PARAMETERS
       - name: filePath
@@ -103,7 +105,7 @@ spec:
         aliases:
           - name: changeManagement/git/from
         type: "string"
-        description: "GIT starting point for retrieving the change document and transport request id"
+        description: "GIT starting point for retrieving the change document and transport request ID"
         scope:
           - PARAMETERS
           - STAGES
@@ -114,7 +116,7 @@ spec:
         aliases:
           - name: changeManagement/git/to
         type: "string"
-        description: "GIT ending point for retrieving the change document and transport request id"
+        description: "GIT ending point for retrieving the change document and transport request ID"
         scope:
           - PARAMETERS
           - STAGES
@@ -125,7 +127,7 @@ spec:
         aliases:
           - name: changeManagement/changeDocumentLabel
         type: "string"
-        description: "Pattern used for identifying lines holding the change document id"
+        description: "Pattern used for identifying lines holding the change document ID. The GIT commit log messages are scanned for this label"
         scope:
           - PARAMETERS
           - STAGES
@@ -136,7 +138,7 @@ spec:
         aliases:
           - name: changeManagement/transportRequestLabel
         type: "string"
-        description: "Pattern used for identifying lines holding the transport request id"
+        description: "Pattern used for identifying lines holding the transport request ID. The GIT commit log messages are scanned for this label"
         scope:
           - PARAMETERS
           - STAGES