From 478a73f8f32ef2b6d4ad4584a6349504918aa76d Mon Sep 17 00:00:00 2001 From: Roland Stengel Date: Thu, 22 Apr 2021 09:40:26 +0200 Subject: [PATCH] Add documentation for transportRequestUploadSOLMAN (#2754) --- cmd/transportRequestUploadSOLMAN_generated.go | 28 ++-- .../steps/transportRequestUploadSOLMAN.md | 135 ++++++++++++++++++ .../transportRequestUploadSOLMAN.yaml | 26 ++-- 3 files changed, 164 insertions(+), 25 deletions(-) create mode 100644 documentation/docs/steps/transportRequestUploadSOLMAN.md diff --git a/cmd/transportRequestUploadSOLMAN_generated.go b/cmd/transportRequestUploadSOLMAN_generated.go index 9727182d9..66cc31fa2 100644 --- a/cmd/transportRequestUploadSOLMAN_generated.go +++ b/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", - Long: `Uploads content to a transport request which is associated with a change document in SAP Solution Manager`, + Short: "Uploads a specified file into a given transport via 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.Password, "password", os.Getenv("PIPER_password"), "Password for the deploy user") - cmd.Flags().StringVar(&stepConfig.ApplicationID, "applicationId", os.Getenv("PIPER_applicationId"), "Id of the application.") - 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.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.Username, "username", os.Getenv("PIPER_username"), "Service user for uploading to the Solution Manager") + 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. 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 which the file is uploaded") + 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.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.TransportRequestLabel, "transportRequestLabel", `TransportRequest`, "Pattern used for identifying lines holding the 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.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. 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{ diff --git a/documentation/docs/steps/transportRequestUploadSOLMAN.md b/documentation/docs/steps/transportRequestUploadSOLMAN.md new file mode 100644 index 000000000..70361e475 --- /dev/null +++ b/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 ..`. +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' +) +``` diff --git a/resources/metadata/transportRequestUploadSOLMAN.yaml b/resources/metadata/transportRequestUploadSOLMAN.yaml index 43fb40701..03cde40fa 100644 --- a/resources/metadata/transportRequestUploadSOLMAN.yaml +++ b/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