Docu updates abap steps (#2910)

* docu updates

* go generate

* remove example as better explained in scenario docu

* Update abapAddonAssemblyKitCheckCVs_generated.go

* PV Step update

* md lint

* create TV

* publish TV

* lint

* register

* release

* reserve

* yaml lint

* Update abapAddonAssemblyKitRegisterPackages_generated.go

* Update resources/metadata/abapAddonAssemblyKitCreateTargetVector.yaml

Co-authored-by: Daniel Mieg <56156797+DanielMieg@users.noreply.github.com>

* Update resources/metadata/abapAddonAssemblyKitPublishTargetVector.yaml

Co-authored-by: Daniel Mieg <56156797+DanielMieg@users.noreply.github.com>

* refer

Co-authored-by: Daniel Mieg <56156797+DanielMieg@users.noreply.github.com>

cmd/abapAddonAssemblyKitCheckCVs_generated.go

@@ -52,7 +52,7 @@ func (p *abapAddonAssemblyKitCheckCVsCommonPipelineEnvironment) persist(path, re
 	}
 }
 
-// AbapAddonAssemblyKitCheckCVsCommand This step checks the validity of Software Component Versions.
+// AbapAddonAssemblyKitCheckCVsCommand This step checks the validity of ABAP Software Component Versions.
 func AbapAddonAssemblyKitCheckCVsCommand() *cobra.Command {
 	const STEP_NAME = "abapAddonAssemblyKitCheckCVs"
 
@@ -64,9 +64,11 @@ func AbapAddonAssemblyKitCheckCVsCommand() *cobra.Command {
 
 	var createAbapAddonAssemblyKitCheckCVsCmd = &cobra.Command{
 		Use:   STEP_NAME,
-		Short: "This step checks the validity of Software Component Versions.",
+		Short: "This step checks the validity of ABAP Software Component Versions.",
-		Long: `This steps takes a list of Software Component Versions from the addonDescriptorFileName and checks whether they exist or are a valid successor of an existing Software Component Version.
+		Long: `This steps takes the list of ABAP Software Component Versions(repositories) from the addonDescriptor configuration file specified via addonDescriptorFileName (e.g. addon.yml) and checks by calling AAKaaS whether they exist or are a valid successor of an existing Software Component Version.
-It resolves the dotted version string into version, support package level and patch level and writes it to the commonPipelineEnvironment.`,
+It resolves the dotted version string into version, support package level and patch level and writes it to the addonDescriptor structure in the Piper commonPipelineEnvironment for usage of subsequent pipeline steps.
+<br />
+For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)
@@ -148,12 +150,12 @@ func abapAddonAssemblyKitCheckCVsMetadata() config.StepData {
 		Metadata: config.StepMetadata{
 			Name:        "abapAddonAssemblyKitCheckCVs",
 			Aliases:     []config.Alias{},
-			Description: "This step checks the validity of Software Component Versions.",
+			Description: "This step checks the validity of ABAP Software Component Versions.",
 		},
 		Spec: config.StepSpec{
 			Inputs: config.StepInputs{
 				Secrets: []config.StepSecrets{
-					{Name: "abapAddonAssemblyKitCredentialsId", Description: "Credential stored in Jenkins for the Addon Assembly Kit as a Service (AAKaaS) system", Type: "jenkins"},
+					{Name: "abapAddonAssemblyKitCredentialsId", Description: "CredentialsId stored in Jenkins for the Addon Assembly Kit as a Service (AAKaaS) system", Type: "jenkins"},
 				},
 				Parameters: []config.StepParameters{
 					{

cmd/abapAddonAssemblyKitCheckPV_generated.go

@@ -65,8 +65,10 @@ func AbapAddonAssemblyKitCheckPVCommand() *cobra.Command {
 	var createAbapAddonAssemblyKitCheckPVCmd = &cobra.Command{
 		Use:   STEP_NAME,
 		Short: "This step checks the validity of a Addon Product Version.",
-		Long: `This step checks whether the Addon Product Version in the addonDescriptorFileName does exist or is a valid successor of an existing Product Version.
+		Long: `This step checks by calling AAKaaS whether the Addon Product Version in the addonDescriptor configuration file specified via addonDescriptorFileName (e.g. addon.yml) does exist or is a valid successor of an existing Product Version.
-It resolves the dotted version string into version, support package stack level and patch level and writes it to the commonPipelineEnvironment.`,
+It resolves the dotted version string into version, support package stack level and patch level and writes it to the addonDescriptor structure in the Piper commonPipelineEnvironment for usage of subsequent pipeline steps.
+<br />
+For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)
@@ -153,7 +155,7 @@ func abapAddonAssemblyKitCheckPVMetadata() config.StepData {
 		Spec: config.StepSpec{
 			Inputs: config.StepInputs{
 				Secrets: []config.StepSecrets{
-					{Name: "abapAddonAssemblyKitCredentialsId", Description: "Credential stored in Jenkins for the Addon Assembly Kit as a Service (AAKaaS) system", Type: "jenkins"},
+					{Name: "abapAddonAssemblyKitCredentialsId", Description: "CredentialsId stored in Jenkins for the Addon Assembly Kit as a Service (AAKaaS) system", Type: "jenkins"},
 				},
 				Parameters: []config.StepParameters{
 					{

cmd/abapAddonAssemblyKitCreateTargetVector_generated.go

@@ -66,7 +66,9 @@ func AbapAddonAssemblyKitCreateTargetVectorCommand() *cobra.Command {
 		Short: "This step creates a Target Vector for software lifecycle operations",
 		Long: `This step takes the Product Version and the corresponding list of Software Component Versions from the addonDescriptor in the commonPipelineEnvironment.
 With these it creates a Target Vector, which is necessary for executing software lifecylce operations in ABAP Cloud Platform systems.
-The Target Vector describes the software state, which shall be reached in the managed ABAP Cloud Platform system.`,
+The Target Vector describes the software state, which shall be reached in the managed ABAP Cloud Platform system.
+<br />
+For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)

cmd/abapAddonAssemblyKitPublishTargetVector_generated.go

@@ -35,7 +35,9 @@ func AbapAddonAssemblyKitPublishTargetVectorCommand() *cobra.Command {
 		Use:   STEP_NAME,
 		Short: "This step triggers the publication of the Target Vector according to the specified scope.",
 		Long: `This step reads the Target Vector ID from the addonDescriptor in the commonPipelineEnvironment and triggers the publication of the Target Vector.
-With targetVectorScope "T" the Target Vector will be published to the test environment and with targetVectorScope "P" it will be published to the productive environment.`,
+With targetVectorScope "T" the Target Vector will be published to the test environment and with targetVectorScope "P" it will be published to the productive environment.
+<br />
+For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)

cmd/abapAddonAssemblyKitRegisterPackages_generated.go

@@ -51,7 +51,7 @@ func (p *abapAddonAssemblyKitRegisterPackagesCommonPipelineEnvironment) persist(
 	}
 }
 
-// AbapAddonAssemblyKitRegisterPackagesCommand This step uploads the SAR archives and creates physical Delivery Packages in in the File Content Management System of SAP.
+// AbapAddonAssemblyKitRegisterPackagesCommand This step uploads the SAR archives and creates physical Delivery Packages to AAKaaS.
 func AbapAddonAssemblyKitRegisterPackagesCommand() *cobra.Command {
 	const STEP_NAME = "abapAddonAssemblyKitRegisterPackages"
 
@@ -63,11 +63,13 @@ func AbapAddonAssemblyKitRegisterPackagesCommand() *cobra.Command {
 
 	var createAbapAddonAssemblyKitRegisterPackagesCmd = &cobra.Command{
 		Use:   STEP_NAME,
-		Short: "This step uploads the SAR archives and creates physical Delivery Packages in in the File Content Management System of SAP.",
+		Short: "This step uploads the SAR archives and creates physical Delivery Packages to AAKaaS.",
 		Long: `This step takes the list of Software Component Versions from the addonDescriptor in the commonPipelineEnvironment.
-For Packages in status "P"lanned it uploads the SAR archive with the data file and metadata XML of the Delivery Packages composed and exported in the Final Assembly system.
+For Packages in status "P" = planned it uploads the SAR archive with the data file and metadata XML of the Delivery Packages composed and exported in the build system
-and creates physical Delivery Packages. The Packages ares saved in the File Content Management System of SAP.
+and creates physical Delivery Package in AAKaaS.
-The new status "L"ocked is written back to the addonDescriptor in the commonPipelineEnvironment.`,
+The new status "L" = locked is written back to the addonDescriptor in the commonPipelineEnvironment.
+<br />
+For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)
@@ -148,7 +150,7 @@ func abapAddonAssemblyKitRegisterPackagesMetadata() config.StepData {
 		Metadata: config.StepMetadata{
 			Name:        "abapAddonAssemblyKitRegisterPackages",
 			Aliases:     []config.Alias{},
-			Description: "This step uploads the SAR archives and creates physical Delivery Packages in in the File Content Management System of SAP.",
+			Description: "This step uploads the SAR archives and creates physical Delivery Packages to AAKaaS.",
 		},
 		Spec: config.StepSpec{
 			Inputs: config.StepInputs{

cmd/abapAddonAssemblyKitReleasePackages_generated.go

@@ -65,8 +65,9 @@ func AbapAddonAssemblyKitReleasePackagesCommand() *cobra.Command {
 		Use:   STEP_NAME,
 		Short: "This step releases the physical Delivery Packages",
 		Long: `This step takes the list of Software Component Versions from the addonDescriptor in the commonPipelineEnvironment.
-The physical Delivery Packages in status “L” are released and uploaded to the "ABAP CP" section in the SAP artifactory object
+The physical Delivery Packages in status “L” are released. The new status "R"eleased is written back to the addonDescriptor in the commonPipelineEnvironment.
-store. The new status "R"eleased is written back to the addonDescriptor in the commonPipelineEnvironment.`,
+<br />
+For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)

cmd/abapAddonAssemblyKitReserveNextPackages_generated.go

@@ -67,9 +67,11 @@ func AbapAddonAssemblyKitReserveNextPackagesCommand() *cobra.Command {
 		Long: `This step takes the list of Software Component Versions from the addonDescriptor in the commonPipelineEnvironment and determines the ABAP delivery packages.
 If a package does not exist yet in the package registry, it is created there. The response contains detail information for this package and a package status, which determines the next actions:
 "P": Package was created in the registry; production can be started / continued
-"R": Package exists and is already released; production is not needed and must be skipped
+"R": Package exists and is already released; production is not needed and will be skipped
 The steps waits until the status "P" or "R" is achieved.
-The name, type and namespace of each package is written back to the addonDescriptor in the commonPipelineEnvironment.`,
+The name, type and namespace of each package is written back to the addonDescriptor in the commonPipelineEnvironment.
+<br />
+For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)

documentation/docs/steps/abapAddonAssemblyKitCheckCVs.md

@@ -5,22 +5,9 @@
 ## Prerequisites
 
 * The credentials to access the AAKaaS (e.g. S-User) must be stored in the Jenkins Credential Store
-* The step needs an addon.yml containing information about the Product Version and corresponding Software Component Versions/Repositories. The addon.yml should look like this:
+* The step needs an addon.yml containing information about the Product Version and corresponding Software Component Versions/Repositories
 
-```YAML
+A detailed description of all prerequisites of the scenario and how to configure them can be found in the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
----
-addonProduct: /NAMESPC/PRODUCTX
-addonVersion: 1.2.0
-repositories:
-  - name: /NAMESPC/COMPONENTA
-    branch: v1.2.0
-    version: 1.2.0
-    commitID: 7d4516e9
-  - name: /NAMESPC/COMPONENTB
-    branch: v2.0.0
-    version: 2.0.0
-    commitID: 9f102ffb
-```
 
 ## ${docGenParameters}
 
@@ -38,12 +25,13 @@ The recommended way to configure your pipeline is via the config.yml file. In th
 abapAddonAssemblyKitCheckPV script: this
 ```
 
-The config.yml should look like this:
+If the step is to be configured individually the config.yml should look like this:
 
 ```yaml
 steps:
   abapAddonAssemblyKitCheckCVs:
     abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId',
-    abapAddonAssemblyKitEndpoint: 'https://myabapAddonAssemblyKitEndpoint.com',
     addonDescriptorFileName: 'addon.yml'
 ```
+
+More convenient ways of configuration (e.g. on stage level) are described in the respective scenario/pipeline documentation.

documentation/docs/steps/abapAddonAssemblyKitCheckPV.md

@@ -5,22 +5,9 @@
 ## Prerequisites
 
 * The credentials to access the AAKaaS (e.g. S-User) must be stored in the Jenkins Credential Store
-* The step needs an addon.yml containing information about the Product Version and corresponding Software Component Versions/Repositories. The addon.yml should look like this:
+* The step needs an addon.yml containing information about the Product Version and corresponding Software Component Versions/Repositories
 
-```YAML
+A detailed description of all prerequisites of the scenario and how to configure them can be found in the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
----
-addonProduct: /NAMESPC/PRODUCTX
-addonVersion: 1.2.0
-repositories:
-  - name: /NAMESPC/COMPONENTA
-    branch: v1.2.0
-    version: 1.2.0
-    commitID: 7d4516e9
-  - name: /NAMESPC/COMPONENTB
-    branch: v2.0.0
-    version: 2.0.0
-    commitID: 9f102ffb
-```
 
 ## ${docGenParameters}
 
@@ -38,12 +25,13 @@ The recommended way to configure your pipeline is via the config.yml file. In th
 abapAddonAssemblyKitCheckPV script: this
 ```
 
-The config.yml should look like this:
+If the step is to be configured individually the config.yml should look like this:
 
 ```yaml
 steps:
-  abapAddonAssemblyKitCheckPV:
+  abapAddonAssemblyKitCheckCVs:
     abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId',
-    abapAddonAssemblyKitEndpoint: 'https://myabapAddonAssemblyKitEndpoint.com',
     addonDescriptorFileName: 'addon.yml'
 ```
+
+More convenient ways of configuration (e.g. on stage level) are described in the respective scenario/pipeline documentation.

documentation/docs/steps/abapAddonAssemblyKitCreateTargetVector.md

@@ -5,11 +5,11 @@
 ## Prerequisites
 
 * The credentials to access the AAKaaS (e.g. S-User) must be stored in the Jenkins Credential Store
-* This step needs the Product Version name and the resolved version(version, spslevel and patchlevel).
+* Product Version name and the resolved version(version, spslevel and patchlevel) must be part of the addonDescriptor structure in Piper commonPipelineEnvironment. This is the case if the step [abapAddonAssemblyKitCheckPV](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitCheckPV) has been executed before.
-* It also needs for each Software Component Version which should be part of the Target Vector, the name and the resolved version(version, splevel and patchlevel) as well as the Delivery Package.
+* For each Software Component Version which should be part of the Target Vector, the name and the resolved version(version, splevel and patchlevel) as well as the Delivery Package must be part of the addonDescriptor structure in Piper commonPipelineEnvironment. This is the case if the step [abapAddonAssemblyKitCheckCVs](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitCheckCVs) has been executed before.
-* The Delivery Packages must exist in the package registry (status "P") or already as physical packages (status "L" or "R").
+* The Delivery Packages must exist in the package registry (status "P" = planned) which is the case if step [abapAddonAssemblyKitReserveNextPackages](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitReserveNextPackages) has been executed before. Alternatively the package can already exist as physical packages (status "L" = locked or "R" = released).
-* This information is taken from the addonDescriptor in the commonPipelineEnvironment.
+
-* If you run prior to this step the steps: [abapAddonAssemblyKitCheckCVs](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitCheckCVs), [abapAddonAssemblyKitCheckPV](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitCheckPV) and [abapAddonAssemblyKitReserveNextPackages](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitReserveNextPackages) you will get the needed information.
+A detailed description of all prerequisites of the scenario and how to configure them can be found in the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
 
 ## ${docGenParameters}
 
@@ -27,56 +27,12 @@ The recommended way to configure your pipeline is via the config.yml file. In th
 abapAddonAssemblyKitCreateTargetVector script: this
 ```
 
-The config.yml should look like this:
+If the step is to be configured individually the config.yml should look like this:
 
 ```yaml
 steps:
   abapAddonAssemblyKitCreateTargetVector:
-    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId',
+    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId'
-    abapAddonAssemblyKitEndpoint: 'https://myabapAddonAssemblyKitEndpoint.com',
 ```
 
-### Input via the CommonPipelineEnvironment
+More convenient ways of configuration (e.g. on stage level) are described in the respective scenario/pipeline documentation.
-
-```json
-{"addonProduct":"/DMO/myAddonProduct",
-"addonVersion":"",
-"addonVersionAAK":"0003",
-"addonUniqueID":"",
-"customerID":"",
-"AddonSpsLevel":"0001",
-"AddonPatchLevel":"0004",
-"TargetVectorID":"",
-"repositories":[
-  {
-    "name":"/DMO/REPO_A",
-    "tag":"",
-    "branch":"",
-    "version":"",
-    "versionAAK":"0001",
-    "PackageName":"SAPK001001REPOA",
-    "PackageType":"",
-    "SpLevel":"0000",
-    "PatchLevel":"0001",
-    "PredecessorCommitID":"",
-    "Status":"L",
-    "Namespace":"",
-    "SarXMLFilePath":""
-  },
-  {
-    "name":"/DMO/REPO_B",
-    "tag":"",
-    "branch":"",
-    "version":"",
-    "versionAAK":"0002",
-    "PackageName":"SAPK002001REPOB",
-    "PackageType":"",
-    "SpLevel":"0001",
-    "PatchLevel":"0001",
-    "PredecessorCommitID":"",
-    "Status":"R",
-    "Namespace":"",
-    "SarXMLFilePath":""
-  }
-]}
-```

documentation/docs/steps/abapAddonAssemblyKitPublishTargetVector.md

@@ -9,6 +9,8 @@
 * The Target Vector ID is taken from the addonDescriptor in the commonPipelineEnvironment.
 * If you run prior to this step the step [abapAddonAssemblyKitCreateTargetVector](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitCreateTargetVector), the Target Vector will be created and its ID will be written to the commonPipelineEnvironment
 
+A detailed description of all prerequisites of the scenario and how to configure them can be found in the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
+
 ## ${docGenParameters}
 
 ## ${docGenConfiguration}
@@ -19,7 +21,7 @@
 
 ### Configuration in the config.yml
 
-The recommended way to configure your pipeline is via the config.yml file. In this case, calling the step in the Jenkinsfile looks:
+The recommended way to configure your pipeline is via the config.yml file. In this case, calling the step in the Jenkinsfile is reduced to one line:
 
 ```groovy
 abapAddonAssemblyKitPublishTargetVector(
@@ -28,58 +30,12 @@ abapAddonAssemblyKitPublishTargetVector(
                     )
 ```
 
-The config.yml should look like this:
+If the step is to be configured individually the config.yml should look like this:
 
 ```yaml
 steps:
   abapAddonAssemblyKitPublishTargetVector:
-    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId',
+    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId'
-    abapAddonAssemblyKitEndpoint: 'https://myabapAddonAssemblyKitEndpoint.com',
 ```
 
-### Input via the CommonPipelineEnvironment
+More convenient ways of configuration (e.g. on stage level) are described in the respective scenario/pipeline documentation.
-
-Mandatory fields:
-
-```json
-{"addonProduct":"",
-"addonVersion":"",
-"addonVersionAAK":"",
-"addonUniqueID":"",
-"customerID":"",
-"AddonSpsLevel":"",
-"AddonPatchLevel":"",
-"TargetVectorID":"W7Q00207512600000188",
-"repositories":[
-  {
-    "name":"",
-    "tag":"",
-    "branch":"",
-    "version":"",
-    "versionAAK":"",
-    "PackageName":"",
-    "PackageType":"",
-    "SpLevel":"",
-    "PatchLevel":"",
-    "PredecessorCommitID":"",
-    "Status":"",
-    "Namespace":"",
-    "SarXMLFilePath":""
-  },
-  {
-    "name":"",
-    "tag":"",
-    "branch":"",
-    "version":"",
-    "versionAAK":"",
-    "PackageName":"",
-    "PackageType":"",
-    "SpLevel":"",
-    "PatchLevel":"",
-    "PredecessorCommitID":"",
-    "Status":"",
-    "Namespace":"",
-    "SarXMLFilePath":""
-  }
-]}
-```

documentation/docs/steps/abapAddonAssemblyKitRegisterPackages.md

@@ -10,6 +10,8 @@
 * The information will be written to the commonPipelineEnvironment if you run prior to this step the step [abapAddonAssemblyKitReserveNextPackages](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitReserveNextPackages)
 * The SAR archive is produced if you run the step [abapEnvironmentAssemblePackages](https://sap.github.io/jenkins-library/steps/abapEnvironmentAssemblePackages)
 
+A detailed description of all prerequisites of the scenario and how to configure them can be found in the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
+
 ## ${docGenParameters}
 
 ## ${docGenConfiguration}
@@ -26,58 +28,12 @@ The recommended way to configure your pipeline is via the config.yml file. In th
 abapAddonAssemblyKitRegisterPackages script: this
 ```
 
-The config.yml should look like this:
+If the step is to be configured individually the config.yml should look like this:
 
 ```yaml
 steps:
   abapAddonAssemblyKitRegisterPackages:
-    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId',
+    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId'
-    abapAddonAssemblyKitEndpoint: 'https://myabapAddonAssemblyKitEndpoint.com',
 ```
 
-### Input via the CommonPipelineEnvironment
+More convenient ways of configuration (e.g. on stage level) are described in the respective scenario/pipeline documentation.
-
-Mandatory fields:
-
-```json
-{"addonProduct":"",
-"addonVersion":"",
-"addonVersionAAK":"",
-"addonUniqueID":"",
-"customerID":"",
-"AddonSpsLevel":"",
-"AddonPatchLevel":"",
-"TargetVectorID":"",
-"repositories":[
-  {
-    "name":,
-    "tag":"",
-    "branch":"",
-    "version":"",
-    "versionAAK":"",
-    "PackageName":"SAPK001001REPOA",
-    "PackageType":"",
-    "SpLevel":"",
-    "PatchLevel":"",
-    "PredecessorCommitID":"",
-    "Status":"P",
-    "Namespace":"",
-    "SarXMLFilePath":".pipeline/commonPipelineEnvironment/SAPK001001REPOA.SAR"
-  },
-  {
-    "name":"",
-    "tag":"",
-    "branch":"",
-    "version":"",
-    "versionAAK":"",
-    "PackageName":"SAPK002001REPOB",
-    "PackageType":"",
-    "SpLevel":"",
-    "PatchLevel":"",
-    "PredecessorCommitID":"",
-    "Status":"R",
-    "Namespace":"",
-    "SarXMLFilePath":".pipeline/commonPipelineEnvironment/SAPK002001REPOB.SAR"
-  }
-]}
-```

documentation/docs/steps/abapAddonAssemblyKitReleasePackages.md

@@ -9,6 +9,8 @@
 * The package names are taken from the addonDescriptor in the commonPipelineEnvironment together with the status of the packages.
 * The step [abapAddonAssemblyKitRegisterPackages](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitRegisterPackages) will set the status of the packages to "L"ocked and writes the needed data to the commonPipelineEnvironment.
 
+A detailed description of all prerequisites of the scenario and how to configure them can be found in the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
+
 ## ${docGenParameters}
 
 ## ${docGenConfiguration}
@@ -25,58 +27,12 @@ The recommended way to configure your pipeline is via the config.yml file. In th
 abapAddonAssemblyKitReleasePackages script: this
 ```
 
-The config.yml should look like this:
+If the step is to be configured individually the config.yml should look like this:
 
 ```yaml
 steps:
   abapAddonAssemblyKitReleasePackages:
-    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId',
+    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId'
-    abapAddonAssemblyKitEndpoint: 'https://myabapAddonAssemblyKitEndpoint.com',
 ```
 
-### Input via the CommonPipelineEnvironment
+More convenient ways of configuration (e.g. on stage level) are described in the respective scenario/pipeline documentation.
-
-Mandatory fields:
-
-```json
-{"addonProduct":"",
-"addonVersion":"",
-"addonVersionAAK":"",
-"addonUniqueID":"",
-"customerID":"",
-"AddonSpsLevel":"",
-"AddonPatchLevel":"",
-"TargetVectorID":"",
-"repositories":[
-  {
-    "name":"",
-    "tag":"",
-    "branch":"",
-    "version":"",
-    "versionAAK":"",
-    "PackageName":"SAPK001001REPOA",
-    "PackageType":"",
-    "SpLevel":"",
-    "PatchLevel":"",
-    "PredecessorCommitID":"",
-    "Status":"L",
-    "Namespace":"",
-    "SarXMLFilePath":""
-  },
-  {
-    "name":"",
-    "tag":"",
-    "branch":"",
-    "version":"",
-    "versionAAK":"",
-    "PackageName":"SAPK002001REPOB",
-    "PackageType":"",
-    "SpLevel":"",
-    "PatchLevel":"",
-    "PredecessorCommitID":"",
-    "Status":"R",
-    "Namespace":"",
-    "SarXMLFilePath":""
-  }
-]}
-```

documentation/docs/steps/abapAddonAssemblyKitReserveNextPackages.md

@@ -10,6 +10,8 @@
 * The Software Component Versions must be valid.
 * The validation is performed and the required information is written to the CommonPipelineEnvironment if you run prior to this step the step [abapAddonAssemblyKitCheckCVs](https://sap.github.io/jenkins-library/steps/abapAddonAssemblyKitCheckCVs)
 
+A detailed description of all prerequisites of the scenario and how to configure them can be found in the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
+
 ## ${docGenParameters}
 
 ## ${docGenConfiguration}
@@ -26,58 +28,12 @@ The recommended way to configure your pipeline is via the config.yml file. In th
 abapAddonAssemblyKitReserveNextPackages script: this
 ```
 
-The config.yml should look like this:
+If the step is to be configured individually the config.yml should look like this:
 
 ```yaml
 steps:
   abapAddonAssemblyKitReserveNextPackages:
-    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId',
+    abapAddonAssemblyKitCredentialsId: 'abapAddonAssemblyKitCredentialsId'
-    abapAddonAssemblyKitEndpoint: 'https://myabapAddonAssemblyKitEndpoint.com',
 ```
 
-### Input via the CommonPipelineEnvironment
+More convenient ways of configuration (e.g. on stage level) are described in the respective scenario/pipeline documentation.
-
-Mandatory fields:
-
-```json
-{"addonProduct":"",
-"addonVersion":"",
-"addonVersionAAK":"",
-"addonUniqueID":"",
-"customerID":"",
-"AddonSpsLevel":"",
-"AddonPatchLevel":"",
-"TargetVectorID":"",
-"repositories":[
-  {
-    "name":"/DMO/REPO_A",
-    "tag":"",
-    "branch":"",
-    "version":"1.0.1",
-    "versionAAK":"",
-    "PackageName":"",
-    "PackageType":"",
-    "SpLevel":"",
-    "PatchLevel":"",
-    "PredecessorCommitID":"",
-    "Status":"",
-    "Namespace":"",
-    "SarXMLFilePath":""
-  },
-  {
-    "name":"/DMO/REPO_B",
-    "tag":"",
-    "branch":"",
-    "version":"2.1.1",
-    "versionAAK":"",
-    "PackageName":"",
-    "PackageType":"",
-    "SpLevel":"",
-    "PatchLevel":"",
-    "PredecessorCommitID":"",
-    "Status":"",
-    "Namespace":"",
-    "SarXMLFilePath":""
-  }
-]}
-```

resources/metadata/abapAddonAssemblyKitCheckCVs.yaml

@@ -1,15 +1,17 @@
 metadata:
   name: abapAddonAssemblyKitCheckCVs
-  description: This step checks the validity of Software Component Versions.
+  description: This step checks the validity of ABAP Software Component Versions.
   longDescription: |
-    This steps takes a list of Software Component Versions from the addonDescriptorFileName and checks whether they exist or are a valid successor of an existing Software Component Version.
+    This steps takes the list of ABAP Software Component Versions(repositories) from the addonDescriptor configuration file specified via addonDescriptorFileName (e.g. addon.yml) and checks by calling AAKaaS whether they exist or are a valid successor of an existing Software Component Version.
-    It resolves the dotted version string into version, support package level and patch level and writes it to the commonPipelineEnvironment.
+    It resolves the dotted version string into version, support package level and patch level and writes it to the addonDescriptor structure in the Piper commonPipelineEnvironment for usage of subsequent pipeline steps.
+    <br />
+    For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
 
 spec:
   inputs:
     secrets:
       - name: abapAddonAssemblyKitCredentialsId
-        description: Credential stored in Jenkins for the Addon Assembly Kit as a Service (AAKaaS) system
+        description: CredentialsId stored in Jenkins for the Addon Assembly Kit as a Service (AAKaaS) system
         type: jenkins
     params:
       - name: abapAddonAssemblyKitEndpoint

resources/metadata/abapAddonAssemblyKitCheckPV.yaml

@@ -2,13 +2,15 @@ metadata:
   name: abapAddonAssemblyKitCheckPV
   description: This step checks the validity of a Addon Product Version.
   longDescription: |
-    This step checks whether the Addon Product Version in the addonDescriptorFileName does exist or is a valid successor of an existing Product Version.
+    This step checks by calling AAKaaS whether the Addon Product Version in the addonDescriptor configuration file specified via addonDescriptorFileName (e.g. addon.yml) does exist or is a valid successor of an existing Product Version.
-    It resolves the dotted version string into version, support package stack level and patch level and writes it to the commonPipelineEnvironment.
+    It resolves the dotted version string into version, support package stack level and patch level and writes it to the addonDescriptor structure in the Piper commonPipelineEnvironment for usage of subsequent pipeline steps.
+    <br />
+    For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
 spec:
   inputs:
     secrets:
       - name: abapAddonAssemblyKitCredentialsId
-        description: Credential stored in Jenkins for the Addon Assembly Kit as a Service (AAKaaS) system
+        description: CredentialsId stored in Jenkins for the Addon Assembly Kit as a Service (AAKaaS) system
         type: jenkins
     params:
       - name: abapAddonAssemblyKitEndpoint

resources/metadata/abapAddonAssemblyKitCreateTargetVector.yaml

@@ -5,6 +5,8 @@ metadata:
     This step takes the Product Version and the corresponding list of Software Component Versions from the addonDescriptor in the commonPipelineEnvironment.
     With these it creates a Target Vector, which is necessary for executing software lifecylce operations in ABAP Cloud Platform systems.
     The Target Vector describes the software state, which shall be reached in the managed ABAP Cloud Platform system.
+    <br />
+    For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
 spec:
   inputs:
     secrets:

resources/metadata/abapAddonAssemblyKitPublishTargetVector.yaml

@@ -4,6 +4,8 @@ metadata:
   longDescription: |
     This step reads the Target Vector ID from the addonDescriptor in the commonPipelineEnvironment and triggers the publication of the Target Vector.
     With targetVectorScope "T" the Target Vector will be published to the test environment and with targetVectorScope "P" it will be published to the productive environment.
+    <br />
+    For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
 spec:
   inputs:
     secrets:

resources/metadata/abapAddonAssemblyKitRegisterPackages.yaml

@@ -1,11 +1,13 @@
 metadata:
   name: abapAddonAssemblyKitRegisterPackages
-  description: This step uploads the SAR archives and creates physical Delivery Packages in in the File Content Management System of SAP.
+  description: This step uploads the SAR archives and creates physical Delivery Packages to AAKaaS.
   longDescription: |
     This step takes the list of Software Component Versions from the addonDescriptor in the commonPipelineEnvironment.
-    For Packages in status "P"lanned it uploads the SAR archive with the data file and metadata XML of the Delivery Packages composed and exported in the Final Assembly system.
+    For Packages in status "P" = planned it uploads the SAR archive with the data file and metadata XML of the Delivery Packages composed and exported in the build system
-    and creates physical Delivery Packages. The Packages ares saved in the File Content Management System of SAP.
+    and creates physical Delivery Package in AAKaaS.
-    The new status "L"ocked is written back to the addonDescriptor in the commonPipelineEnvironment.
+    The new status "L" = locked is written back to the addonDescriptor in the commonPipelineEnvironment.
+    <br />
+    For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
 
 spec:
   inputs:

resources/metadata/abapAddonAssemblyKitReleasePackages.yaml

@@ -3,8 +3,9 @@ metadata:
   description: This step releases the physical Delivery Packages
   longDescription: |
     This step takes the list of Software Component Versions from the addonDescriptor in the commonPipelineEnvironment.
-    The physical Delivery Packages in status “L” are released and uploaded to the "ABAP CP" section in the SAP artifactory object
+    The physical Delivery Packages in status “L” are released. The new status "R"eleased is written back to the addonDescriptor in the commonPipelineEnvironment.
-    store. The new status "R"eleased is written back to the addonDescriptor in the commonPipelineEnvironment.
+    <br />
+    For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
 spec:
   inputs:
     secrets:

resources/metadata/abapAddonAssemblyKitReserveNextPackages.yaml

@@ -5,9 +5,11 @@ metadata:
     This step takes the list of Software Component Versions from the addonDescriptor in the commonPipelineEnvironment and determines the ABAP delivery packages.
     If a package does not exist yet in the package registry, it is created there. The response contains detail information for this package and a package status, which determines the next actions:
     "P": Package was created in the registry; production can be started / continued
-    "R": Package exists and is already released; production is not needed and must be skipped
+    "R": Package exists and is already released; production is not needed and will be skipped
     The steps waits until the status "P" or "R" is achieved.
     The name, type and namespace of each package is written back to the addonDescriptor in the commonPipelineEnvironment.
+    <br />
+    For Terminology refer to the [Scenario Description](https://www.project-piper.io/scenarios/abapEnvironmentAddons/).
 spec:
   inputs:
     secrets: