Refine Hybrid Development Documentation (#462)

documentation/docs/scenarios/changeManagement.md

@@ -15,26 +15,29 @@ Set up an agile development process with Jenkins CI, which automatically feeds c
 
 In many SAP development scenarios, it is vital to synchronize both backend and frontend deliveries. These deliveries are typically an SAP UI5 application and an ABAP backend from which it is served. The SAP UI5 parts are often developed using agile practices and use Continuous Integration pipelines that automatically build, test, and deploy the application.
 
+**Note:** This scenario description is an example. You can apply the process to other scenarios and component sets, as well.
+
 In this scenario, we want to show how an agile development process with Jenkins CI can automatically feed changes into SAP Solution Manager. In SAP Solution Manager, all parts of the application stack come together and can be subject to classic change and transport management.
 
 The basic workflow is as follows:
 
-1. The pipeline scans the Git commit messages between `origin/master` and `HEAD` for a line like `ChangeDocument : <changeDocumentId>`, and validates that the change is in the correct status `in development`.The template for the commit message looks as follows:
+1. The pipeline scans the Git commit messages for a line like `ChangeDocument : <changeDocumentId>`, and validates that the change is in the correct status `in development`. For more information, see [checkChangeInDevelopment](https://sap.github.io/jenkins-library/steps/checkChangeInDevelopment/). An example for the commit message looks as follows:
 
     ```
-    <Commit Message Header>
-
-    <Commit Message Description>
+    Fix terminology in documentation
 
+    Terminology must be consistent with official channels.
     ChangeDocument: <Your Change Document ID>
     ```
 
-2. To communicate with SAP Solution Manager, the pipeline uses credentials that must be stored on Jenkins under the label `CM`.
-3. The required transport request is created on the fly. However, the change document can contain more components (for example, UI and backend components).
+    **Note:** The blank line between message header and message description is mandatory.
+
+2. To communicate with SAP Solution Manager, the pipeline uses credentials that must be stored on Jenkins using the credential ID `CM`. For more information, see [checkChangeInDevelopment](https://sap.github.io/jenkins-library/steps/checkChangeInDevelopment/).
+3. The required transport request is created on the fly. **Note:** The change document can contain various components (for example, UI and backend components).
 4. The changes of your development team trigger the Jenkins pipeline. It builds and validates the changes and attaches them to the respective transport request.
 5. As soon as the development process is completed, the change document in SAP Solution Manager can be set to status `to be tested` and all components can be transported to the test system.
 
-![Hybrid Application Development Workflow](../images/SolMan_Scenario.png "Hybrid Application Development Workflow")
+![Hybrid Application Development Workflow](../images/Scenario_SolMan.png "Hybrid Application Development Workflow")
 ##### Hybrid Application Development Worflow
 
 ## Example
@@ -77,6 +80,8 @@ general:
 steps:
   mtaBuild:
     buildTarget: 'NEO'
+  transportRequestCreate:
+    developmentSystemId: '<value for developmentSystemId>'
   transportRequestUploadFile:
     applicationId: 'HCP'
 ```

documentation/docs/steps/transportRequestCreate.md

@@ -30,6 +30,7 @@ The id of the transport request is availabe via [commonPipelineEnvironment.getTr
 | `changeManagement/changeDocumentLabel`        | no        | `ChangeDocument\s?:`                                   | regex pattern      |
 | `changeManagement/git/format`        | no        | `%b`                                                   | see `git log --help` |
 | `changeManagement/type`           | no        | `SOLMAN`                                               | `SOLMAN`, `CTS`    |
+| `developmentSystemId` | for `SOLMAN` |         | |
 
 * `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the `this` parameter, as in `script: this`. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for retrieving, for example, configuration parameters.
 * `changeDocumentId` - for `SOLMAN` only. The id of the change document to that the transport request is bound to. Typically this value is provided via commit message in the commit history.
@@ -44,7 +45,7 @@ The id of the transport request is availabe via [commonPipelineEnvironment.getTr
 * `description` - for `CTS` only. The description of the transport request.
 * `targetSystem` - for `CTS` only. The system receiving the transport request.
 * `transportType` - for type `CTS` only. Typically `W` (workbench) or `C` customizing.
-
+* `developmentSystemId`- for `SOLMAN` only. The logical system id for which the transport request is created. The format is `<SID>~<TYPE>(/<CLIENT>)?`. For ABAP Systems the `developmentSystemId` looks like `DEV~ABAP/100`. For non-ABAP systems the `developmentSystemId` looks like e.g. `L21~EXT_SRV` or `J01~JAVA`. In case the system type (in the examples provided here: `EXT_SRV` or `JAVA`) the information can be retrieved from the Solution Manager instance.
 ## Step configuration
 
 The step is configured using a customer configuration file provided as