Package com.veeva.vault.sdk.api.notification

package com.veeva.vault.sdk.api.notification
This package provides interfaces to send Vault notifications.

Notifications

You can create notifications that Vault sends to users as both emails and in-app notifications. You can send notifications to various recipients:
  • Specific Users (user__sys)
  • All users in a group
  • All users in a role
  • Specific Persons (person__sys)
A key distinction is that Persons cannot receive in-app notifications and will only receive emails. Persons include all subtypes of the Person object.

A notification has three parts:

  • Text: The body of the notification that appears as an in-app notification in the Vault UI.
  • Message: The body of the notification email sent to users.
  • Subject: The subject of the notification email sent to users.
You can define notification content directly using NotificationMessage or use a pre-configured template with NotificationTemplate, which is ideal for multi-language support.

Tokens

Notification templates, text, messages, and subjects can all include tokens. Tokens are placeholders that Vault replaces with specific values at the time of sending. For example, ${recipientName} inserts the full name of the recipient. You can view the full list of standard tokens in Vault Help. You can also create custom tokens in the format ${Custom.tokenName}. You can set the value of a custom token using NotificationMessage.setTokenValue(java.lang.String, java.lang.String) and NotificationTemplate.setTokenValue(java.lang.String, java.lang.String). For advanced, multi-language token resolution, you can implement a Consumer of TokenResolverInput and set it on a template with NotificationTemplate.setTokenResolver(java.util.function.Consumer).

Code Examples

Example: Sending a Notification from a Template

The following example sends a notification to a list of users, a group, and a record role using a pre-configured notification template. 
 
 // Locate the NotificationService to create notification components.
 NotificationService notificationService = ServiceLocator.locate(NotificationService.class);

 // ----- 1. Define Recipients -----
 // Create a list of user IDs to receive the notification.
 List<String> userRecipients = VaultCollections.newList();
 userRecipients.add("user_id_1");

 // Retrieve a Group to use as a recipient.
 GroupService groupService = ServiceLocator.locate(GroupService.class);
 GetGroupsResponse groupResponse = groupService.getGroupsByNames(VaultCollections.asList("sdk_group__c"));
 Group sdkGroup = groupResponse.getGroupByName("sdk_group__c");

 // Retrieve a RecordRole to use as a recipient.
 RecordService recordService = ServiceLocator.locate(RecordService.class);
 Record record = recordService.newRecordWithId("study__v", "study_id_1");
 RecordRoleService recordRoleService = ServiceLocator.locate(RecordRoleService.class);
 GetRecordRolesResponse recordRoleResponse = recordRoleService.getRecordRoles(VaultCollections.asList(record));
 RecordRole recordRole = recordRoleResponse.getRecordRole(record, "viewer__v");

 // ----- 2. Set Notification Parameters -----
 // Use NotificationParameters to configure the sender, recipients, and delivery options.
 NotificationParameters notificationParameters = notificationService.newNotificationParameters();
 notificationParameters.setRecipientsByUsers(userRecipients);
 notificationParameters.setRecipientsByGroups(VaultCollections.asList(sdkGroup));
 notificationParameters.setRecipientsByRecordRoles(VaultCollections.asList(recordRole));
 notificationParameters.setSenderId("sender_user_id"); // Optional: Sets values for ${sender...} tokens.

 // ----- 3. Configure the Template -----
 // Use a NotificationTemplate to specify the template name and set values for custom tokens.
 NotificationTemplate template = notificationService.newNotificationTemplate()
 .setTemplateName("product_change_notification_template__c")
 .setTokenValue("productName", "my product name"); // Sets the value for ${Custom.productName}

 // ----- 4. Send the Notification -----
 notificationService.send(notificationParameters, template);

Example: Sending a Notification without a Template

This example sends a notification by defining the subject, message, and text directly, without using a template. This is useful for simple, non-translated notifications. 
 
 NotificationService notificationService = ServiceLocator.locate(NotificationService.class);

 // Define a list of User IDs as recipients.
 List<String> userRecipients = VaultCollections.newList();
 userRecipients.add("user_id_1");

 // Configure the sender and recipients.
 NotificationParameters notificationParameters = notificationService.newNotificationParameters();
 notificationParameters.setRecipientsByUsers(userRecipients);

 // Define the notification content directly using NotificationMessage.
 NotificationMessage message = notificationService.newNotificationMessage()
  .setSubject("Action Required: Review document ${docName}") // The subject for the email.
  .setMessage("Hello ${recipientName}, please review the document ${docName} for accuracy.") // The body of the email.
  .setNotificationText("Please review the document ${docName}.") // The text for the in-app notification.
  .setTokenValue("docName", "Q4 Report"); // Set value for the custom token ${Custom.docName}.

 // Send the notification.
 notificationService.send(notificationParameters, message);

Example: Controlling Notification Delivery

By default, notifications are sent both in-app and via email. You can control this behavior using NotificationParameters.setNotificationMode(NotificationMode...). 
 
 NotificationService notificationService = ServiceLocator.locate(NotificationService.class);
 NotificationParameters notificationParameters = notificationService.newNotificationParameters();

 // This notification will ONLY be sent as an email. No in-app notification will be created.
 notificationParameters.setNotificationMode(NotificationMode.EMAIL);

 // To send ONLY as an in-app notification:
 // notificationParameters.setNotificationMode(NotificationMode.APPLICATION);

 // The default behavior is to send both, which is equivalent to:
 // notificationParameters.setNotificationMode(NotificationMode.EMAIL, NotificationMode.APPLICATION);

Example: Dynamic Token Resolution

For complex scenarios, such as when token values depend on the recipient's language, you can provide a Consumer to resolve tokens dynamically. 
 
 // This class implements the logic to resolve token values.
 public class MyTokenResolver implements Consumer<TokenResolverInput> {

	@Override
	public void accept(TokenResolverInput tokenResolverInput) {
		TokenResolverOutput output = tokenResolverInput.getTokenResolverOutput();

		// The input provides the set of languages and tokens that need to be resolved.
		Collection<String> languages = tokenResolverInput.getLanguages();
		Collection<String> tokens = tokenResolverInput.getTokens();

		// Iterate through each required language and provide translated values.
		for (String lang : languages) {
			Map<String, String> tokenValues = VaultCollections.newMap();
			if ("es".equals(lang)) {
				tokenValues.put("productName", "my spanish product name");
			} else {
				tokenValues.put("productName", "my generic product name");
			}
			output.setTokenValues(lang, tokenValues);
		}
	}
 }

 // In your notification sending logic, set the token resolver on the template.
 NotificationTemplate template = notificationService.newNotificationTemplate()
  .setTemplateName("product_change_notification_template__c")
  .setTokenResolver(new MyTokenResolver());

 notificationService.send(notificationParameters, template);

Best Practices & Gotchas

  • Context-Specific Tokens: Many standard tokens like ${docName} or ${taskName} are specific to a document or workflow context. Because SDK-sent notifications are not associated with a context, these tokens will resolve as empty strings. Use custom tokens to pass in contextual data.
  • Person vs. User Recipients: Remember that Person records can only receive emails, not in-app notifications. If a person is also a Vault user, you must add them via NotificationParameters.setRecipientsByUsers(java.util.List) to send them an in-app notification.
  • Setting Recipients is Mandatory: A notification must have at least one recipient list set (e.g., via setRecipientsByUsers, setRecipientsByGroups, etc.). Calling send() without any recipients will result in an error.
  • Token Resolution Strategy: For simple, single-language notifications, use setTokenValue(). For notifications that need to support multiple languages or have complex logic for determining token values, use a setTokenResolver().