Skip to main content

Notifications

This page documents how to handle workflow events and send notifications.

Workflow handlers​

Completion handler​

Due to the asynchronous nature of Nextflow, the termination of a script does not correspond to the termination of the running workflow. Thus some information, only available on execution completion, needs to be accessed by using an asynchronous handler.

Nextflow invokes the onComplete event handler when the workflow execution is completed. It allows one to access the workflow termination status and other useful information. For example:

workflow.onComplete {
    println "Pipeline completed at: $workflow.complete"
    println "Execution status: ${ workflow.success ? 'OK' : 'failed' }"
}
Added in version 25.10

Entry workflows can define an onComplete section instead of using workflow.onComplete:

workflow {
    main:
    // ...

    onComplete:
    println "Pipeline completed at: $workflow.complete"
    println "Execution status: ${ workflow.success ? 'OK' : 'failed' }"
}

Error handler​

Nextflow invokes the onError event handler when a runtime or process error caused the pipeline execution to stop. For example:

workflow.onError {
    println "Error: Pipeline execution stopped with the following message: ${workflow.errorMessage}"
}
note

Both the onError and onComplete handlers are invoked when an error condition is encountered. The onError handler is called as soon as the error is raised, while onComplete is called just before the pipeline execution is about to terminate.

Added in version 25.10

Entry workflows can define an onError section instead of using workflow.onError:

workflow {
    main:
    // ...

    onError:
    println "Error: Pipeline execution stopped with the following message: ${workflow.errorMessage}"
}

Mail​

Use the sendMail function to send a mail message from a workflow script.

For example:

sendMail(
    to: 'you@gmail.com',
    subject: 'Catch up',
    body: 'Hi, how are you!',
    attach: '/some/path/attachment/file.txt'
)

You can also specify mail options using a closure:

sendMail {
    to 'you@gmail.com'
    from 'me@gmail.com'
    attach '/some/path/attachment/file.txt'
    attach '/other/path/image.png'
    subject 'Catch up'

    // string expression is treated as the mail body
    '''
    Hi there,
    Look! Multi-lines
    mail content!
    '''
}

Attach multiple files with custom headers:

sendMail {
    to 'you@dot.com'
    attach '/some/file.txt', fileName: 'manuscript.txt'
    attach '/other/image.png', disposition: 'inline'
    subject 'Sending documents'
    '''
    the mail body
    '''
}

See sendMail for the full reference.

Mail configuration​

If no mail server configuration is provided, Nextflow tries to send the email using the external mail command eventually provided by the underlying system (e.g. sendmail or mail).

If your system does not provide access to any of the above you can configure a SMTP server in the nextflow.config file. For example:

mail {
    smtp.host = 'your.smtp-server.com'
    smtp.port = 475
    smtp.user = 'my-user'
}
note

Some versions of Java (e.g. Java 11 Corretto) do not default to TLS v1.2, and as a result may have issues with 3rd party integrations that enforce TLS v1.2 (e.g. Azure Active Directory OIDC). This problem can be addressed by setting the following config option:

mail {
    smtp.ssl.protocols = 'TLSv1.2'
}

See the mail scope section to learn more the mail server configuration options.

AWS SES configuration​

Added in version 23.10

Nextflow supports the AWS Simple Email Service API as an alternative provider to send emails in place of an SMTP server.

To enable this feature, set the following environment variable in the launch environment:

export NXF_ENABLE_AWS_SES=true

Make also sure to add the following AWS IAM permission to the AWS user (or role) used to launch the pipeline execution:

ses:SendRawEmail

The following snippet shows how to configure Nextflow to send emails through SES:

mail {
    smtp.host = 'email-smtp.us-east-1.amazonaws.com'
    smtp.port = 587
    smtp.user = '<Your AWS SES access key>'
    smtp.password = '<Your AWS SES secret key>'
    smtp.auth = true
    smtp.starttls.enable = true
    smtp.starttls.required = true
}

Mail notification​

You can use the sendMail function with a workflow completion handler to notify a workflow completion. For example:

workflow.onComplete {

    def msg = """\r
        Pipeline execution summary
        ---------------------------
        Completed at: ${workflow.complete}
        Duration    : ${workflow.duration}
        Success     : ${workflow.success}
        workDir     : ${workflow.workDir}
        exit status : ${workflow.exitStatus}
        """
        .stripIndent()

    sendMail(to: 'you@gmail.com', subject: 'My pipeline execution', body: msg)
}

This is useful to send a custom notification message. Note however that Nextflow includes a built-in notification mechanism which is the most convenient way to notify the completion of a workflow execution in most cases. Read the following section to learn about it.

Workflow notification​

Nextflow includes built-in workflow notification features that automatically sends a notification message when a workflow execution terminates.

To enable simply specify the -N option when launching the pipeline execution. For example:

nextflow run <pipeline name> -N <recipient address>

It will send a notification mail when the execution completes.

warning

By default the notification message is sent with the sendmail system tool, which is assumed to be available in the environment where Nextflow is running. Make sure it's properly installed and configured. Alternatively, you can provide the SMTP server configuration settings to use the Nextflow built-in mail support, which doesn't require any external system tool.

See the Mail configuration section to learn about the available mail delivery options and configuration settings.

See Completion handler to learn more about the workflow notification configuration details.

On this Page