jenkins/sap-jenkins-library
1
0
Fork 0
mirror of https://github.com/SAP/jenkins-library.git synced 2025-01-18 05:18:24 +02:00
Code Issues Releases Activity

Add documentation for transportRequestUploadSOLMAN (#2754)

Browse Source
This commit is contained in:
Roland Stengel 2021-04-22 09:40:26 +02:00 committed by GitHub
parent 9168757810
commit 478a73f8f3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 164 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
cmd/transportRequestUploadSOLMAN_generated.go
View File

@ -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{

135
documentation/docs/steps/transportRequestUploadSOLMAN.md Normal file
View File

@ -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'
)
```

26
resources/metadata/transportRequestUploadSOLMAN.yaml
View File

@ -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