Skip to content

Latest commit

 

History

History
334 lines (255 loc) · 11.1 KB

im.md

File metadata and controls

334 lines (255 loc) · 11.1 KB
Raw

Instant Messaging (im)

This part of the pipeline provide steps for instant messaging.

Table of contents

im.mattermost()

The im.mattermost step uses the Mattermost Notification Plugin to send instant messages to a mattermost instance using mattermost webhooks.

Signatures:

  • void mattermost(String message, String text = null, String color = null, String channel = null, String icon = null, String endpointOrCredentialId, failOnError = false)
  • void mattermost(Map config)

Arguments

Please refer to the step documentation for details as im.mattermost is mostly forwarding the arguments: https://jenkins.io/doc/pipeline/steps/mattermost/

channel

When channel is null (default) then an auto-lookup for the channel using the Generic Configuration support is performed.

endpointOrCredentialId

When endpointOrCredentialId is null (default) then an auto-lookup for the channel using the Generic Configuration support is performed.

When endpointOrCredentialId starts with http:// or https:// the value of endpointOrCredentialId is used as mattermost endpoint.

When non of the above conditions matches the value of endpointOrCredentialId is used as credential id to retrieve the endpoint from the Jenkins credential storage

config

If you want you can also use the step with a config map.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

Map config = [
  (NOTIFY_MATTERMOST): [
    (NOTIFY_MATTERMOST_CHANNEL)               : null,
    (NOTIFY_MATTERMOST_ENDPOINT): null,
    (NOTIFY_MATTERMOST_ENDPOINT_CREDENTIAL_ID): null,
    (NOTIFY_MATTERMOST_ICON)                  : null,
    (NOTIFY_MATTERMOST_COLOR)                 : null,
    (NOTIFY_MATTERMOST_TEXT)                  : null,
    (NOTIFY_MATTERMOST_MESSAGE)               : null,
    (NOTIFY_MATTERMOST_FAIL_ON_ERROR)         : false,
  ]
]

im.mattermost(config)

Configuration options

Complete list of all configuration options.

All configuration options must be inside the NOTIFY_MATTERMOST (ConfigConstants.NOTIFY_MATTERMOST) map element to be evaluated and used by the step.

You have to provide at least a NOTIFY_MATTERMOST_CHANNEL and either a NOTIFY_MATTERMOST_ENDPOINT or a credential containing the endpoint by using NOTIFY_MATTERMOST_ENDPOINT_CREDENTIAL_ID.

channel
Constant ConfigConstants.NOTIFY_MATTERMOST_CHANNEL
Type String
Default null

The channel to post messages to.

color (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_COLOR
Type String
Default Result.getColor()

The color for the message. When using the defaults the color is retrieved from the parsed build result object. See Result.groovy for the color definition.

endpoint
Constant ConfigConstants.NOTIFY_MATTERMOST_ENDPOINT
Type String
Default null

Configures the mattermost endpoint (e.g. webhook) to use. Overwrites endpointCredentialId/ConfigConstants.NOTIFY_MATTERMOST_ENDPOINT_CREDENTIAL_ID when set. Refer to Mattermost Notification Plugin documentation for more information.

endpointCredentialId
Constant ConfigConstants.NOTIFY_MATTERMOST_ENDPOINT_CREDENTIAL_ID
Type String
Default null

Specifies a secret text (String) credential to use as the Mattermost endpoint. Will not be used when endpoint/NOTIFY_MATTERMOST_ENDPOINT is configured.

failOnError (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_FAIL_ON_ERROR
Type Boolean
Default false

Controls if the step will fail when there are issues during sending the message.

icon (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_ICON
Type String
Default null

The icon to use for the message. Refer to Mattermost Notification Plugin documentation for more information.

message (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_MESSAGE
Type String
Default `"${triggerHelper.getTrigger()} - ${env.JOB_NAME} ${env.BUILD_NUMBER} (<${env.BUILD_URL}

The message of the mattermost notification. Refer to Mattermost Notification Plugin documentation for more information.

text (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_TEXT
Type String
Default null

Optional text. Refer to Mattermost Notification Plugin.

Generic Configuration support

This step supports the Generic Configuration mechanism for loading and applying a FQJN based auto-lookup for the appropriate configuration options.

💡 FQJN = Fully-Qualified Job Name = ${JOB_NAME}@${GIT_BRANCH}

💡 This method of configuration is recommended!

When using this mechanism the step expects a YAML pipeline resource with the path resources/jenkins-pipeline-library/notify/mattermost.yaml.

💡 An example for this mattermost.yaml is here: mattermost.yaml

Examples

// message only 
im.mattermost("message")
// message and text
im.mattermost("message","text")
// message, text, channel and icon
im.mattermost("message","text","#00FF00","wcm-io-channel", "https://www.mattermost.org/wp-content/uploads/2016/04/icon.png")

im.teams()

The im.teams step uses the Office365 Connector plugin to send instant messages to a Microsoft Teams instance using webhooks.

Signatures:

  • void teams(String message = null, String webhookUrlOrCredentialId = null, String color = null)
  • void teams(Map config)

Arguments

Please refer to the step documentation for details as im.teams is mostly forwarding the arguments: https://jenkins.io/doc/pipeline/steps/Office-365-Connector/

webhookUrlOrCredentialId

When webhookUrlOrCredentialId is null (default) then an auto-lookup for the webhook URL using the Generic Configuration support is performed.

When webhookUrlOrCredentialId starts with http:// or https://, the value of webhookUrlOrCredentialId is used as MS Teams webhook URL.

When none of the above conditions match the value of webhookUrlOrCredentialId, it is used as credential ID to retrieve the endpoint from the Jenkins credential storage.

config

If you want you can also use the step with a config map.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

Map config = [
  (NOTIFY_TEAMS): [
    (NOTIFY_TEAMS_MESSAGE)                    : null,
    (NOTIFY_TEAMS_WEBHOOK_URL)                : null,
    (NOTIFY_TEAMS_COLOR)                      : null,
  ]
]

im.teams(config)

Configuration options

Complete list of all configuration options.

All configuration options must be inside the NOTIFY_TEAMS (ConfigConstants.NOTIFY_TEAMS) map element to be evaluated and used by the step.

You have to provide at least a NOTIFY_TEAMS_WEBHOOK_URL.

webhookUrl
Constant ConfigConstants.NOTIFY_TEAMS_WEBHOOK_URL
Type String
Default null

The URL of the webhook that Jenkins needs to send notifications to MS Teams. You will obtain this URL while setting up the Jenkins connector in your MS Teams channel. For more information, refer to Microsoft's documentation. When endpointOrCredentialId is null (default) then an auto-lookup for the channel using the Generic Configuration support is performed.

webhookUrlCredentialId
Constant ConfigConstants.NOTIFY_TEAMS_WEBHOOK_URL_CREDENTIAL_ID
Type String
Default null

Specifies a secret text (String) credential to use as the MS Teams webhook URL. Will not be used when endpoint/NOTIFY_TEAMS_WEBHOOK_URL is configured.

message (optional)
Constant ConfigConstants.NOTIFY_TEAMS_MESSAGE
Type String
Default null

The message of the MS Teams notification. This defaults to null since the plugin already provides a pretty detailed message by default.

color (optional)
Constant ConfigConstants.NOTIFY_TEAMS_COLOR
Type String
Default Result.getColor()

The color for the message. When using the defaults the color is retrieved from the parsed build result object. See Result.groovy for the color definition.

Generic Configuration support

This step supports the Generic Configuration mechanism for loading and applying a FQJN based auto-lookup for the appropriate configuration options.

💡 FQJN = Fully-Qualified Job Name = ${JOB_NAME}@${GIT_BRANCH}

💡 This method of configuration is recommended!

When using this mechanism the step expects a YAML pipeline resource with the path resources/jenkins-pipeline-library/notify/teams.yaml.

💡 An example for this teams.yaml is here: teams.yaml

Examples

// message only 
im.teams("message")
// message with custom color
im.teams("message", color = "ffffff")