Send notifications from workflows

This tutorial explains how to use the notificationApi bean to send notifications from Groovy script tasks in Collibra workflows. The notificationApi delivers notifications from a single API call to multiple channels: email, the Notification Center in the Collibra UI, Slack, and Microsoft Teams.

Learning objectives

• Use the notificationApi bean to send notifications from a Groovy script task.
• Set recipients, subjects, and rich content using a fluent builder.
• Associate a Collibra resource with a notification.
• Use translation keys for multilingual notifications.
• Understand delivery behavior, guardrails, and error handling.
• Migrate existing mailBean notifications to the notificationApi.

Prerequisites

• Access to a Collibra environment with the Workflow Designer.
• A global role with Logs > View global permission for troubleshooting.
• Familiarity with creating and deploying workflows.
• Basic understanding of Groovy scripting.

Overview

Similar to workflow beans, the notificationApi is automatically available in any Groovy script task, without the need to import, configure, or initialize it. It allows you to compose notifications inline in Groovy using a fluent builder method. The API handles formatting, translation, and delivery across all configured channels.

Every notification is built with the same four parts:

Recipients

A required list of users or groups who receive the notification.

Subject

A required subject line shown in email and the Notification Center.

Content

A required body of the message, composed of ordered building blocks.

Resource

An optional Collibra resource, such as an asset, domain, or community that the notification is about.

Set recipients

You can send notifications to individual users, to user groups, or to both. You must provide Collibra user IDs or group IDs as UUID collections. The two recipient methods are cumulative and calling them multiple times adds to the existing set rather than replacing it.

notificationApi.send { builder -> builder
    .recipientUsers([userId1, userId2])
    .subject { s -> s.text("Update available") }
    .content { c -> c.text { t -> t.text("A new version is ready for your review.") } }
}

notificationApi.send { builder -> builder
    .recipientGroups([stewardsGroupId])
    .subject { s -> s.text("Update available") }
    .content { c -> c.text { t -> t.text("A new version is ready for your review.") } }
}

notificationApi.send { builder -> builder
    .recipientUsers([reviewerId])
    .recipientGroups([stewardsGroupId, managersGroupId])
    .subject { s -> s.text("Approval required") }
    .content { c -> c.text { t -> t.text("An asset requires your approval.") } }
}

Recipients must be Collibra users or groups. You cannot send notifications to arbitrary external email addresses. All recipient user IDs and group IDs must exist in Collibra.

Set the subject

The subject supports two modes: literal text and translation keys. Use translation keys in multilingual environments so that each recipient sees the subject in their own locale.

.subject { s -> s.text("Review request for Finance Domain") }

.subject { s -> s.textKey("workflow.review.subject", communityName) }

Calling .subject() more than once means the last call replaces the previous one.

Build the content body

The content body is composed of ordered building blocks. Blocks are rendered in the order you add them. Each block has the text defined using either .text() for a literal value or .textKey() for a translation key.

Mixed formatting example:

def baseUrl = collibraConfiguration.getApplicationUrl()

.content { c -> c
    .text { t -> t.text("The asset ") }
    .bold { t -> t.text(assetName) }
    .text { t -> t.text(" has been submitted for review.") }
    .newLine()
    .italic { t -> t.text("Review before the deadline.") }
    .newLine()
    .link(new URI("${baseUrl}/asset/${assetId}")) { t -> t.text("Open in Collibra") }
}

Calling .content() more than once means the last call replaces the previous one. Each content block uses either .text() or .textKey() and if you call both on the same block, the last one replaces the previous one.

Associate a resource

You can optionally link your notification to a Collibra resource such as an asset, domain, or community. Associating a resource enriches the notification across channels:

• Notification Center: The resource appears as a named, clickable entry, letting recipients navigate directly to it.
• Slack and Microsoft Teams: A "View in Collibra" button is added to the message.
• Email: The resource context is included in the email body.

The .resource() method accepts the resource ID, display name, and resource type. You can optionally pass a relative navigation path that controls where recipients are taken when they click the resource link.

.resource(assetId, "Legal and Ethics", "ASSET")

.resource(assetId, "Legal and Ethics", "ASSET", "/asset/${assetId}")

The supported resource type values are:

Using an unsupported resource type value prevents the notification from being sent and causes a validation error.

Send the notification

Wrap all parts in the notificationApi.send call. The notification is queued and delivered after the current workflow transaction commits.

notificationApi.send { builder -> builder
    .recipientUsers([userId])
    .subject { s -> s.text("Review complete") }
    .content { c -> c
        .text { t -> t.text("The review has been completed.") }
    }
    .resource(assetId, assetName, "ASSET")
}

Complete examples

def approverId = users.getUserIds("user(${currentUserId})").first()

notificationApi.send { builder -> builder
    .recipientUsers([approverId])
    .subject { s -> s.text("Asset approved") }
    .content { c -> c
        .text { t -> t.text("Your asset ") }
        .bold { t -> t.text(item.getName()) }
        .text { t -> t.text(" has been approved by the review committee.") }
    }
    .resource(item.getId(), item.getName(), "ASSET")
}

def baseUrl = collibraConfiguration.getApplicationUrl()

notificationApi.send { builder -> builder
    .recipientUsers(users.getUserIds("role(Steward)"))
    .recipientGroups([stewardsGroupId])
    .subject { s -> s.text("Review requested: ${item.getName()}") }
    .content { c -> c
        .text { t -> t.text("A new asset requires your review.") }
        .newLine()
        .newLine()
        .bold { t -> t.text("Asset: ") }
        .text { t -> t.text(item.getName()) }
        .newLine()
        .bold { t -> t.text("Domain: ") }
        .text { t -> t.text(item.getDomainName()) }
        .newLine()
        .bold { t -> t.text("Submitted by: ") }
        .text { t -> t.text(item.getCreatedBy()) }
        .newLine()
        .newLine()
        .italic { t -> t.text("Complete your review within 5 business days.") }
        .newLine()
        .link(new URI("${baseUrl}/asset/${item.getId()}")) { t ->
            t.text("Open asset in Collibra")
        }
    }
    .resource(item.getId(), item.getName(), "ASSET", "/asset/${item.getId()}")
}

notificationApi.send { builder -> builder
    .recipientUsers(reviewerIds)
    .subject { s -> s.textKey("workflow.review.subject", item.getName()) }
    .content { c -> c
        .text { t -> t.textKey("workflow.review.intro", submitterName) }
        .newLine()
        .bold { t -> t.textKey("workflow.review.asset.label") }
        .text { t -> t.text(item.getName()) }
        .newLine()
        .text { t -> t.textKey("workflow.review.deadline.message", dueDateFormatted) }
        .newLine()
        .link(new URI("${baseUrl}/asset/${item.getId()}")) { t ->
            t.textKey("workflow.review.open.link")
        }
    }
    .resource(item.getId(), item.getName(), "ASSET")
}

notificationApi.send { builder -> builder
    .recipientGroups([UUID.fromString(dataOwnersGroupId)])
    .subject { s -> s.text("New data quality issue reported") }
    .content { c -> c
        .text { t -> t.text("A data quality issue has been reported for ") }
        .bold { t -> t.text(item.getName()) }
        .text { t -> t.text(". Investigate and take appropriate action.") }
        .newLine()
        .link(new URI("${baseUrl}/asset/${item.getId()}")) { t ->
            t.text("View details")
        }
    }
    .resource(item.getId(), item.getName(), "ASSET")
}

Using translations

The notificationApi supports two ways to set text in subjects and content blocks:

Add custom translation keys

To add your own translation keys, go to Settings → General → Customizations → Custom Strings. There you can define keys and their translations for each supported language. The keys become available immediately for use with .textKey() in your workflows.

Parameters passed to .textKey() are substituted into the translated template using positional placeholders, such as {0}, {1}, and so on. You can pass up to 10 parameters per block. Each parameter value is cut off at 250 characters.

Example of mixing literal and translated text:

.content { c -> c
    .text { t -> t.textKey("workflow.review.intro") }    // translated
    .bold { t -> t.text(item.getName()) }                 // literal (asset name)
    .newLine()
    .italic { t -> t.textKey("workflow.review.deadline") } // translated
}

Delivery behavior

Notifications are designed to be safe additions to your workflow and never block or break workflow execution.

Notifications are sent after the workflow transaction commits. If the transaction fails for any reason after your script task, the notification is not sent.

Notification preferences

All notifications sent through the notificationApi are filed under the Custom Notifications category in the notification settings for each user at Settings → General → Notifications → Tasks and Issues Management → Custom Notifications. Recipients can independently enable or disable delivery per channel. If a recipient has disabled a channel, they will not receive your notification through it.

Guardrails and limitations

The API enforces built-in limits to ensure safe delivery. Values that exceed these limits are silently trimmed rather than causing errors, with two exceptions: missing required parts and invalid resource types, which cause validation errors.

Content limits

Other limitations

• No arbitrary email addresses. Recipients must be existing Collibra users or groups.
• No file attachments. The API does not support attaching files to notifications.
• Recipient list limits. The notification service enforces maximum sizes on recipient lists. Exceeding these limits causes the request to be rejected.
• One subject and one content per notification. Calling .subject() or .content() more than once means the last call replaces the previous one.

Rate limits on Slack and Microsoft Teams

Slack and Microsoft Teams apply their own rate limits on incoming messages. Workflows that send a large burst of notifications in a short period may see delayed delivery on those channels. On Slack, this can appear as a Slackbot message in the recipient's channel reading "Due to a high volume of activity, we are not displaying some messages sent by this application". Microsoft Teams applies comparable limits.

The Notification Center respects channel retry signals and retries throttled requests where possible, so throttling generally results in delayed delivery rather than lost messages. However, during sustained high volume, some messages may still be suppressed by the channel.

Prefer a single summary notification that lists all affected resources over one notification per item. This reduces recipient noise and stays well within external channel rate limits.

Error handling

There are two categories of errors to be aware of. They behave differently and surface in different places.

Validation errors

If you misconfigure a notification, for example forgetting to set the subject, the API throws a NotificationException synchronously during the send() call. This exception propagates to the workflow engine and causes the workflow to enter an error state. The workflow instance stops and is flagged as failed in the Collibra workflow administration UI.

The Collibra UI and the Workflow Instances view show only a generic "workflow failed" message. To see the specific NotificationException message, check the Collibra logs for the workflow run. Always start debugging a failed workflow from the logs: Settings → Logs.

Always test your workflow in a development environment to catch validation errors before deploying to production.

Delivery errors

Delivery errors occur asynchronously after the workflow transaction commits. These errors are logged but do not affect workflow execution. Your workflow continues normally even if a notification fails to deliver.

Migrating from the mailBean

If you currently use the mailBean, which is available as mail in workflow scripts, the following shows how to migrate to the notificationApi.

The mailBean and the notificationApi can coexist. You do not need to migrate all workflows at once so migrate at your own pace, workflow by workflow.

// Requires a Velocity template file at:
// /email-templates/workflow-notifications/myWorkflow/approved-en.vm

def userIds = users.getUserIds("role(Steward)")
mail.sendMails(userIds, "approved", "myWorkflow", execution)

def baseUrl = collibraConfiguration.getApplicationUrl()
def userIds = users.getUserIds("role(Steward)")

notificationApi.send { builder -> builder
    .recipientUsers(userIds)
    .subject { s -> s.text("Asset approved") }
    .content { c -> c
        .text { t -> t.text("The asset ") }
        .bold { t -> t.text(item.getName()) }
        .text { t -> t.text(" has been approved and is now published.") }
        .newLine()
        .link(new URI("${baseUrl}/asset/${item.getId()}")) { t ->
            t.text("View asset")
        }
    }
    .resource(item.getId(), item.getName(), "ASSET")
}

Comparison

Migration tips

1. Map your Velocity template content to builder blocks. Review your existing templates and translate the content into .text(), .bold(), .italic(), .link(), and .newLine() calls.
2. Replace template variables with builder parameters. If your Velocity template used $item.name, use item.getName() directly in Groovy and pass it to .text() or as a .textKey() parameter.
3. Consider adding translation keys. Migration is a good opportunity to make your notifications multilingual by using .textKey() instead of hardcoded strings.
4. Test in your development environment. Verify that notifications appear correctly across email, the Notification Center, and any connected messaging platforms.

API reference

The following tables summarize the methods available in the notificationApi builder DSL. For the complete Javadoc, consult the API documentation:

• In your Collibra environment at https://<your-collibra-url>/javadocs/java-workflow-api/com/collibra/workflow/notifications/api/notification/package-summary.html.
• On the Workflow API reference page, see the com.collibra.workflow.notifications.api.notification package.

NotificationApi

Bean name: notificationApi. Available automatically in all Groovy script tasks with no import required.

NotificationBuilder

ContentBlockBuilder

TextContentBuilder

Additional resources

• Read the Getting started with workflows documentation section.
• Read the Introduction to builders tutorial.
• Learn about the Notification Center.
• Learn more about custom strings.