API Reference

Complete API reference for nf-slack plugin configuration options and functions.

Quick Links:

• Usage Guide - Learn how to send custom messages
• Examples - See practical examples

---

Configuration

slack

Property	Type	Default	Required	Description
enabled	Boolean	true	No	Master switch to enable/disable the plugin
bot	Closure	-	No*	Bot configuration block (see slack.bot)
webhook	Closure	-	No*	Webhook configuration block (see slack.webhook)
onStart	Closure	See slack.onStart	No	Configuration for workflow start notifications
onComplete	Closure	See slack.onComplete	No	Configuration for workflow completion notifications
onError	Closure	See slack.onError	No	Configuration for workflow error notifications

*Either webhook or bot is required. If neither is configured, the plugin will automatically disable itself.

Example

slack {
    enabled = true
    bot { /* ... */ }
    onStart { /* ... */ }
    onComplete { /* ... */ }
    onError { /* ... */ }
}

---

slack.bot

Property	Type	Default	Required	Description
token	String	-	Yes	Bot User OAuth Token (starts with xoxb-)
channel	String	-	Yes	Channel ID (e.g., C12345678) or Name (e.g., general) to send messages to
useThreads	Boolean	false	No	Group all workflow messages (including custom slackMessage() calls) in threads (bot tokens only)

Example

bot {
    token = 'xoxb-your-token'
    channel = 'general'
    useThreads = true  // Optional: group messages in threads
}

---

slack.webhook

Property	Type	Default	Required	Description
url	String	-	Yes	Slack Incoming Webhook URL (must start with https://hooks.slack.com/)

Example

webhook {
    url = 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL'
}

---

slack.onStart

Configuration for workflow start notifications.

Properties

Property	Type	Default	Description
enabled	Boolean	true	Send notification when workflow starts
message	String or Map	'🚀 *Pipeline started*'	Start notification message
includeCommandLine	Boolean	true	Include command line in message
showFooter	Boolean	true	Show timestamp footer in message

Message Available Fields

• runName - Workflow run name
• status - Current status (always "Running" for start messages)
• commandLine - Full Nextflow command
• workDir - Working directory path

Example

onStart {
    message = [
        text: '🚀 *Production Pipeline Starting*',
        color: '#3AA3E3',
        includeFields: ['runName', 'status', 'commandLine'],
        customFields: [
            [title: 'Environment', value: 'Production', short: true],
            [title: 'Priority', value: 'High', short: true]
        ]
    ]
}

---

slack.onComplete

Configuration for workflow completion notifications.

Properties

Property	Type	Default	Description
enabled	Boolean	true	Send notification when workflow completes
message	String or Map	'✅ *Pipeline completed successfully*'	Completion notification message
includeCommandLine	Boolean	true	Include command line in message
includeResourceUsage	Boolean	true	Include task statistics and resource usage
showFooter	Boolean	true	Show timestamp footer in message

Note: includeResourceUsage is only available in the onComplete scope.

Message Available Fields

• runName - Workflow run name
• status - Final status (e.g., "OK")
• duration - Total workflow runtime
• commandLine - Full Nextflow command
• tasks - Task execution statistics (count, succeeded, failed, cached)

Example

onComplete {
    message = [
        text: '✅ *Analysis Complete*',
        color: '#2EB887',
        includeFields: ['runName', 'duration', 'tasks'],
        customFields: [
            [title: 'Results', value: 's3://bucket/results/', short: false],
            [title: 'Cost', value: '$12.50', short: true]
        ]
    ]
    includeResourceUsage = true
}

---

slack.onError

Configuration for workflow error notifications.

Properties

Property	Type	Default	Description
enabled	Boolean	true	Send notification when workflow fails
message	String or Map	'❌ *Pipeline failed*'	Error notification message
includeCommandLine	Boolean	true	Include command line in message
showFooter	Boolean	true	Show timestamp footer in message

Message Available Fields

• runName - Workflow run name
• status - Error status
• duration - Time before failure
• commandLine - Full Nextflow command
• errorMessage - Error details
• failedProcess - Name of the process that failed

Example

onError {
    message = [
        text: '❌ *Pipeline Failed*',
        color: '#A30301',
        includeFields: ['runName', 'duration', 'errorMessage', 'failedProcess'],
        customFields: [
            [title: 'Support', value: 'support@example.com', short: true],
            [title: 'On-Call', value: '@devops', short: true]
        ]
    ]
}

---

slack.<scope>.message (String)

Use a string for quick, simple message customization. Supports Slack markdown (*bold*, _italic_, `code`), emojis, and newlines (\n).

Example

onStart {
    message = '🚀 *Pipeline started*\nRunning on cluster'
}

---

slack.<scope>.message (Map)

Use a map for full control with colors, fields, and custom data.

Properties:

• text (required) - Main message text
• color - Hex color code (e.g., #2EB887)
• includeFields - List of default fields (see slack.<scope>.message.includeFields)
• customFields - List of custom fields with title, value, and optional short (boolean for 2-column layout)

Example

onComplete {
    message = [
        text: '✅ *Analysis Complete*',
        color: '#2EB887',
        includeFields: ['runName', 'duration', 'status'],
        customFields: [
            [title: 'Sample Count', value: '150', short: true],
            [title: 'Output Location', value: 's3://bucket/results/', short: false]
        ]
    ]
}

---

slack.<scope>.message.includeFields

The following fields can be included in the includeFields array when using map format:

Field Name	Description	Available In
runName	Nextflow run name (e.g., tiny_euler)	All scopes
status	Workflow status with emoji	All scopes
duration	Total workflow runtime (e.g., 2h 30m 15s)	onComplete, onError
commandLine	Full Nextflow command used to launch workflow	All scopes
workDir	Working directory path	onStart
errorMessage	Error details and stack trace	onError
failedProcess	Name and tag of the process that failed	onError
tasks	Task execution statistics	onComplete

---

Color Reference

Standard color codes for Slack message attachments:

Name	Hex Code	Use Case
Success Green	#2EB887	Successful completions
Error Red	#A30301	Failures and errors
Info Blue	#3AA3E3	Informational, start messages
Warning Orange	#FFA500	Warnings
Neutral Gray	#808080	Neutral information

---

Functions

slackMessage(String message)

Parameter	Type	Required	Description
message	String	Yes	Text to send to Slack

Example

slackMessage("Processing sample ${sample_id}")

slackMessage(Map options)

Property	Type	Required	Description
message	String	Yes	Message text (supports Slack markdown)
color	String	No	Hex color code (e.g., "#2EB887")
fields	List\<Map>	No	Array of custom field objects

Example

slackMessage([
    message: "Analysis complete!",
    color: "#2EB887",
    fields: [
        [
            title: "Status",
            value: "Success",
            short: true
        ],
        [
            title: "Samples Processed",
            value: "42",
            short: true
        ]
    ]
])

Fields

When using the map format with custom fields, each field object supports:

Property	Type	Required	Description
title	String	Yes	Field label/name
value	String	Yes	Field content
short	Boolean	No	Layout: true = 2 columns, false = full width

With workflow metadata:

workflow {
    workflow.onComplete = {
        def status = workflow.success ? "✅ SUCCESS" : "❌ FAILED"
        def color = workflow.success ? "#2EB887" : "#A30301"

        slackMessage([
            message: "Workflow ${status}",
            color: color,
            fields: [
                [title: "Duration", value: "${workflow.duration}", short: true],
                [title: "Exit Status", value: "${workflow.exitStatus}", short: true]
            ]
        ])
    }
}

Return Value

The function does not return anything.

---