jenkins/sap-jenkins-library
1
0
Fork 0
mirror of https://github.com/SAP/jenkins-library.git synced 2025-03-03 15:02:35 +02:00
Code Issues Releases Activity

mailSendNotification: generate documentation (#584)

Browse Source
This commit is contained in:
Christopher Fenner 2019-03-25 14:34:48 +01:00 committed by GitHub
parent 208e1a4241
commit f138ae1499
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 70 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
documentation/docs/steps/mailSendNotification.md
View File

@ -1,14 +1,6 @@
# mailSendNotification
# ${docGenStepName}
## Description
Sends notifications to all potential culprits of a current or previous build failure plus to fixed list of recipients.
It will attach the current build log to the email.
Notifications are sent in following cases:
* current build failed or is unstable
* current build is successful and previous build failed or was unstable
## ${docGenDescription}
## Prerequsites
@ -22,60 +14,9 @@ Usage of pipeline step:
mailSendNotification script: this
```
## Parameters
## ${docGenParameters}
| parameter | mandatory | default | possible values |
| ----------|-----------|---------|-----------------|
|script|yes|||
|buildResult|no|||
|gitCommitId|no|`script.commonPipelineEnvironment.getGitCommitId()`||
|gitSshKeyCredentialsId|no|``||
|gitUrl|no|||
|notificationAttachment|no|`true`||
|notificationRecipients|no|||
|notifyCulprits|no|`true`||
|numLogLinesInBody|no|`100`||
|projectName|no|||
|wrapInNode|no|`false`||
### Details
* `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration.
* `buildResult` may be used to overrule the build result coming from `currentBuild.result`. This is for example used in the step `pipelineRestartSteps`
* `gitCommitId` defines a dedicated git commitId for culprit retrieval.
* `gitUrl` and `gitCommitId` are used to retrieve culprit information.
* `gitSshKeyCredentialsId` only required if your git repository is protected. It defines the credentialsId for the git ssh credentials.
* `notificationAttachment` defines if the console log file should be attached to the notification mail.
* `notificationRecipients` defines the fixed list of recipient that always get the notification. In case you want to send the notification to the culprits only set it to an empty string `''`.
!!! note
Multiple recipients need to be separated with the `space` character.
In case you do not want to have any fixed recipients of the notifications leave the property empty.
* `notifyCulprits` defines if potential culprits should receive an email.
* `numLogLinesInBody` defines the number of log lines (=last lines of the log) which are included into the body of the notification email.
* `projectName` may be used to specify a different name in the email subject.
* `wrapInNode` needs to be set to `true` if step is used outside of a node context, e.g. post actions in a declarative pipeline script.
## Step configuration
We recommend to define values of step parameters via [config.yml file](../configuration.md).
In following sections the configuration is possible:
| parameter | general | step | stage |
| ----------|-----------|---------|-----------------|
|script||||
|buildResult||X|X|
|gitCommitId||X|X|
|gitSshKeyCredentialsId|X|X|X|
|gitUrl||X|X|
|notificationAttachment||X|X|
|notificationRecipients||X|X|
|notifyCulprits||X|X|
|numLogLinesInBody||X|X|
|projectName||X|X|
|wrapInNode||X|X|
## ${docGenConfiguration}
## Side effects

78
vars/mailSendNotification.groovy
View File

@ -1,26 +1,80 @@
import static com.sap.piper.Prerequisites.checkScript
import com.sap.piper.ConfigurationHelper
import com.sap.piper.GenerateDocumentation
import com.sap.piper.Utils
import groovy.text.SimpleTemplateEngine
import groovy.transform.Field
@Field String STEP_NAME = getClass().getName()
@Field Set GENERAL_CONFIG_KEYS = ['gitSshKeyCredentialsId']
@Field Set STEP_CONFIG_KEYS = [
'projectName',
'buildResult',
'gitUrl',
'gitCommitId',
'gitSshKeyCredentialsId',
'wrapInNode',
'notifyCulprits',
'notificationAttachment',
'notificationRecipients',
'numLogLinesInBody'
@Field Set GENERAL_CONFIG_KEYS = [
/**
* Only if `notifyCulprits` is set:
* Credentials if the repository is protected.
* @possibleValues Jenkins credentials id
*/
'gitSshKeyCredentialsId'
]
@Field Set STEP_CONFIG_KEYS = GENERAL_CONFIG_KEYS.plus([
/**
* Set the build result used to determine the mail template.
* default `currentBuild.result`
*/
'buildResult',
/**
* Only if `notifyCulprits` is set:
* Defines a dedicated git commitId for culprit retrieval.
* default `commonPipelineEnvironment.getGitCommitId()`
*/
'gitCommitId',
/**
* Only if `notifyCulprits` is set:
* Repository url used to retrieve culprit information.
* default `commonPipelineEnvironment.getGitSshUrl()`
*/
'gitUrl',
/**
* defines if the console log file should be attached to the notification mail.
* @possibleValues `true`, `false`
*/
'notificationAttachment',
/**
* A space-separated list of recipients that always get the notification.
*/
'notificationRecipients',
/**
* Notify all committers since the last successful build.
* @possibleValues `true`, `false`
*/
'notifyCulprits',
/**
* Number of log line which are included in the email body.
*/
'numLogLinesInBody',
/**
* The project name used in the email subject.
* default `currentBuild.fullProjectName`
*/
'projectName',
/**
* Needs to be set to `true` if step is used outside of a node context, e.g. post actions in a declarative pipeline script.
* default `false`
* @possibleValues `true`, `false`
*/
'wrapInNode'
])
@Field Set PARAMETER_KEYS = STEP_CONFIG_KEYS
/**
* Sends notifications to all potential culprits of a current or previous build failure and to fixed list of recipients.
* It will attach the current build log to the email.
*
* Notifications are sent in following cases:
*
* * current build failed or is unstable
* * current build is successful and previous build failed or was unstable
*/
@GenerateDocumentation
void call(Map parameters = [:]) {
handlePipelineStepErrors (stepName: STEP_NAME, stepParameters: parameters, allowBuildFailure: true) {
def script = checkScript(this, parameters) ?: this