github.com/ouraigua/jenkins-library@v0.0.0-20231028010029-fbeaf2f3aa9b/documentation/docs/pipelines/abapEnvironment/extensibility.md (about)

     1  # Extensibility
     2  
     3  In general, the SAP BTP, ABAP environment pipeline supports different scenarios. The idea is that only configured stages are executed and the user is able to choose the appropriate stages.
     4  In this section, you can learn how to extend the SAP BTP, ABAP environment pipeline with our recommended and best-practice approaches.
     5  
     6  ## 1. Extend the ATC stage via the Checkstyle/Warnings Next Generation Plugin
     7  
     8  The `ATC` stage will execute ATC checks on a SAP BTP ABAP environment system via the step [abapEnvironmentRunATCCheck](https://sap.github.io/jenkins-library/steps/abapEnvironmentRunATCCheck/).
     9  These results will be pinned to the respective Jenkins Jobs as an XML file in Checkstyle format. Per default this file will be named `ATCResults.xml`. You can change the file name via the step parameter `atcResultsFileName`.
    10  Jenkins offers the possibility to  display the ATC results utilizing the checkstyle format with the [Warnings Next Generation Plugin](https://www.jenkins.io/doc/pipeline/steps/warnings-ng/#warnings-next-generation-plugin) ([GitHub Project](https://github.com/jenkinsci/warnings-ng-plugin)).
    11  
    12  To achieve this, create a file `.pipeline/extensions/ATC.groovy` with the following content:
    13  
    14  ```groovy
    15  void call(Map params) {
    16    //access stage name
    17    echo "Start - Extension for stage: ${params.stageName}"
    18  
    19    //access config
    20    echo "Current stage config: ${params.config}"
    21  
    22    //execute original stage as defined in the template
    23    params.originalStage()
    24  
    25    recordIssues tools: [checkStyle(pattern: '**/ATCResults.xml')], qualityGates: [[threshold: 1, type: 'TOTAL', unstable: true]]
    26  
    27    echo "End - Extension for stage: ${params.stageName}"
    28  }
    29  return this
    30  ```
    31  
    32  The Jenkins pipeline step [recordIssues](https://www.jenkins.io/doc/pipeline/steps/warnings-ng/#recordissues-record-compiler-warnings-and-static-analysis-results) captures the results:
    33  While `tools: [checkStyle(pattern: '**/**/ATCResults.xml')]` will display the ATC findings using the checkstyle format, `qualityGates: [[threshold: 1, type: 'TOTAL', unstable: true]]` will set the build result to UNSTABLE in case the ATC results contain at least one warning or error in total.
    34  
    35  You can define several quality gates that will be checked after the issues have been reported. For example by providing a `qualityGates` configuration with option `unstable: false` it would be possible to end the pipeline execution in case of findings. See [Quality gate configuration](https://github.com/jenkinsci/warnings-ng-plugin/blob/master/doc/Documentation.md#quality-gate-configuration) for details.
    36  
    37  If the pipeline execution should be aborted in case of ATC findings, to not continue with execution of following pipeline stages, use the [error](https://www.jenkins.io/doc/pipeline/steps/workflow-basic-steps/#error-error-signal) step in the stage extension to cause the build to stop:
    38  
    39  ```groovy
    40  if (currentBuild.result == 'FAILURE') {
    41    error('Stopping build due to ATC Check quality gate')
    42  }
    43  ```
    44  
    45  !!! caution "Local Jenkins"
    46      If you are using a local Jenkins you may have to [adapt the Jenkins URL](https://stackoverflow.com/a/39543223) in the configuration if the CheckStyle Plugin shows this error: "Can't create fingerprints for some files".
    47  
    48  ## 2. Extend the ATC stage to send ATC results via E-Mail
    49  
    50  In general when executing the `ATC` stage, the respective ATC results will normally be pinned to the Jenkins Job in a checkStyle XML format.
    51  Additionally, you can set the `generateHTML` flag to `true` for the `abapEnvironmentRunATCCheck` step. This includes the generation of an HTML document containing the ATC results for the `abapEnvironmentRunATCCheck` step that will also be pinned to the respective Jenkins Job.
    52  The ATC results can be attached to an E-Mail or being sent as the E-Mail body with the [Email Extension Plugin](https://www.jenkins.io/doc/pipeline/steps/email-ext/) ([GitHub Project](https://github.com/jenkinsci/email-ext-plugin)) using the `emailext()` method. Make sure that you have configured the Email Extension Plugin correctly before using it.
    53  
    54  In the following example we only provide a sample configuration using the Jenkins [Email Extension Plugin](https://www.jenkins.io/doc/pipeline/steps/email-ext/). The E-Mail can be fully customized to your needs. Please refer to the Email Extension Plugin Documentation to see the full list of parameter that are supported.
    55  If you haven't created it already, create/extend the file `.pipeline/extensions/ATC.groovy` with the following content:
    56  
    57  ```groovy
    58  void call(Map params) {
    59    //access stage name
    60    echo "Start - Extension for stage: ${params.stageName}"
    61  
    62    //access config
    63    echo "Current stage config: ${params.config}"
    64  
    65    //execute original stage as defined in the template
    66    params.originalStage()
    67  
    68    emailext (
    69      attachmentsPattern: 'ATCResults.html', //This will attach the ATC results to the E-Mail
    70      to: 'user@example.com, admin@example.com',
    71      subject: "ATC results Mail from latest Run in System H01",
    72      body: 'Dear User, here are the results from the latest ATC run ${env.BUILD_ID}.' + readFile('ATCResults.html') //This will parse the ATC results and send it as the E-Mail body
    73   )
    74  
    75    echo "End - Extension for stage: ${params.stageName}"
    76  }
    77  return this
    78  ```
    79  
    80  Note that in above example the ATC results, stored in the `ATCResults.html` file that is pinned to the Jenkins Job, will be sent as an attachmend using the `attachmentsPattern` parameter as well as being parsed and attached to the E-Mail body using the `body` parameter. Both methods are possible. If you chose to include the ATC results in the E-Mail body make sure to read the file content properly, e.g. using the `readFile()` method.
    81  The `subject` parameter defines the subject of the E-Mail that will be sent. The `to` parameter specifies a list of recipients separated by a comma. You can also set a Distribution Lists as a recipient.
    82  For all parameters it is also possible to use Jenkins environment variables like `${env.BUILD_ID}` or `${env.JENKINS_URL}`.
    83  
    84  ## 3. Extend the AUnit stage via the JUnit Plugin
    85  
    86  The `AUnit` stage will execute AUnit test runs on a SAP BTP ABAP environment system via the step [abapEnvironmentRunAUnitTest](https://sap.github.io/jenkins-library/steps/abapEnvironmentRunAUnitTest/).
    87  These results will be pinned to the respective Jenkins Jobs as an XML file in the JUnit format. Per default this file will be named `AUnitResults.xml`. You can change the file name via the step parameter `aUnitResultsFileName`.
    88  Jenkins offers the possibility to  display the AUnit results utilizing the JUnit format with the [JUnit Plugin](https://plugins.jenkins.io/junit/) ([GitHub Project](https://github.com/jenkinsci/junit-plugin)).
    89  
    90  To achieve this, create a file `.pipeline/extensions/AUnit.groovy` with the following content:
    91  
    92  ```groovy
    93  void call(Map params) {
    94    //access stage name
    95    echo "Start - Extension for stage: ${params.stageName}"
    96  
    97    //access config
    98    echo "Current stage config: ${params.config}"
    99  
   100    //execute original stage as defined in the template
   101    params.originalStage()
   102  
   103    junit skipPublishingChecks: true, allowEmptyResults: true, testResults: '**/AUnitResults.xml'
   104  
   105    echo "End - Extension for stage: ${params.stageName}"
   106  }
   107  return this
   108  ```
   109  
   110  You can simply use the JUnit Plugin for Jenkins in the AUnit stage within the `.pipeline/extensions/AUnit.groovy` file by using the `junit` command. You can set optional parameters like `skipPublishingChecks: true` in order to disable an integration to the GitHub Checks API. `allowEmptyResults: true` allows the build status of the Jenkins run to be `SUCCESS` even if there have been no results from the respective AUnit test run in the test results file. Vice versa, `allowEmptyResults: false` will set the build status to `FAILURE` if the test results file contains no results.
   111  The `testResults` parameter specifies the path to the AUnit test results file which has been saved and pinned to the Jenkins job in the `abapEnvironmentRunAUnitTest` step. Please refer to the documentation of the ([JUnit Plugin](https://plugins.jenkins.io/junit/#documentation)) for more detailled information on the usage and configuration of the JUnit plugin parameters.
   112  
   113  ## 4. Extend the AUnit stage to send AUnit results via E-Mail
   114  
   115  In general when executing the `AUnit` stage, the respective AUnit results will normally be pinned to the Jenkins Job in a JUnit XML format.
   116  Additionally, you can set the `generateHTML` flag to `true` for the `abapEnvironmentRunAUnitTest` step. This includes the generation of an HTML document containing the AUnit results for the `abapEnvironmentRunAUnitTest` step that will also be pinned to the respective Jenkins Job.
   117  The AUnit results can be attached to an E-Mail or being sent as the E-Mail body with the [Email Extension Plugin](https://www.jenkins.io/doc/pipeline/steps/email-ext/) ([GitHub Project](https://github.com/jenkinsci/email-ext-plugin)) using the `emailext()` method. Make sure that you have configured the Email Extension Plugin correctly before using it.
   118  
   119  In the following example we only provide a sample configuration using the Jenkins [Email Extension Plugin](https://www.jenkins.io/doc/pipeline/steps/email-ext/). The E-Mail can be fully customized to your needs. Please refer to the Email Extension Plugin Documentation to see the full list of parameter that are supported.
   120  If you haven't created it already, create/extend the file `.pipeline/extensions/AUnit.groovy` with the following content:
   121  
   122  ```groovy
   123  void call(Map params) {
   124    //access stage name
   125    echo "Start - Extension for stage: ${params.stageName}"
   126  
   127    //access config
   128    echo "Current stage config: ${params.config}"
   129  
   130    //execute original stage as defined in the template
   131    params.originalStage()
   132  
   133    emailext (
   134      attachmentsPattern: 'AUnitResults.html', //This will attach the AUnit results to the E-Mail
   135      to: 'user@example.com, admin@example.com',
   136      subject: "AUnit results Mail from latest Run in System H01",
   137      body: 'Dear User, here are the results from the latest AUnit test run ${env.BUILD_ID}.' + readFile('AUnitResults.html') //This will parse the AUnit results and send it as the E-Mail body
   138   )
   139  
   140    echo "End - Extension for stage: ${params.stageName}"
   141  }
   142  return this
   143  ```
   144  
   145  Note that in above example the AUnit test run results, stored in the `AUnitResults.html` file that is pinned to the Jenkins job, will be sent as an attachment using the `attachmentsPattern` parameter as well as being parsed and attached to the E-Mail body using the `body` parameter. Both methods are possible. If you chose to include the AUnit test run results in the E-Mail body make sure to read the file content properly, e.g. using the `readFile()` method.
   146  The `subject` parameter defines the subject of the E-Mail that will be sent. The `to` parameter specifies a list of recipients separated by a comma. You can also set a distribution list as a recipient.
   147  For all parameters it is also possible to use Jenkins environment variables like `${env.BUILD_ID}` or `${env.JENKINS_URL}`.