Notifications

You can create notifications that Vault sends to users as both emails and in-app notifications. You can send notifications to:

Specific Users (user__sys)
All users in a group
All users in a role
Specific Persons (person__sys)

Persons cannot receive in-app notifications and receive email notifications only. Persons include all subtypes of the Person object. For example, Case Contacts (case_contact__v) in Medical Vaults.

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 also set templates for your notifications, which is useful for translating your notifications across multiple languages. Learn more about creating message templates in Vault Help.

Tokens

Notification templates, text, messages, and subjects can all include tokens. Tokens are written in a specific format which Vault replaces with the values the token represents. For example, ${recipientName} inserts the Name value of the recipient. You can view the full list of tokens in Vault Help.

Note that many standard tokens are specific to some context. For example, ${docName}, ${Object.name__v}, and ${taskName} are specific to a document, object, or workflow, respectively. Because notifications created with the SDK are not associated with a context, these tokens will resolve as empty Strings.

You can also create custom tokens, which must be in the format ${Custom.tokenName}. You can set the value of a custom token in NotificationMessage.setTokenValue(java.lang.String, java.lang.String) and NotificationTemplate.setTokenValue(java.lang.String, java.lang.String).

You can also resolve token values by implementing a Consumer of TokenResolverInput, and setting the Consumer to the NotificationTemplate with NotificationTemplate.setTokenResolver(java.util.function.Consumer). In your implementation, the resolved token values should be set to TokenResolverOutput.

If the message recipient is a Person (person__sys), recipient tokens resolve to System values. For example, ${recipientFirstName} will resolve as "System", and ${recipientMobilePhone} will resolve as an empty String. To include information about a Person such as Person.first_name_sys, use RecordService to retrieve the Person record and Record.getValue(java.lang.String, com.veeva.vault.sdk.api.core.ValueType) to get the field value. Then you can add this value to your NotificationMessage or NotificationTemplate as a custom token.

Learn more about tokens in NotificationMessage.

Example Notification

The following example sends a notification from a template, both as an email and within the Vault UI.

 
          //Get your recipient userIds, Groups, and RecordRoles
          Set<String> recipients = VaultCollections.newSet();
          recipients.add(currentUserId);

          GroupService groupService = ServiceLocator.locate(GroupService.class);
          List groupNames = VaultCollections.newList();
          groupNames.add("sdk_group__c");
          GetGroupsResponse groupResponse = groupService.getGroupsByNames(groupNames);
          Group group = groupResponse.getGroupByName("sdk_group__c");
          List groups = VaultCollections.newList();
          groups.add(group);

          RecordService recordService = ServiceLocator.locate(RecordService.class);
          Record record = recordService.newRecordWithId("study__v", studyId);
          List records = VaultCollections.newList();
          records.add(record);

          RecordRoleService recordRoleService = ServiceLocator.locate(RecordRoleService.class);
          GetRecordRolesResponse recordRoleResponse = recordRoleService.getRecordRoles(records);
          RecordRole recordRole = recordRoleResponse.getRecordRole(record, "viewer__v");
          List recordRoles = VaultCollections.newList();
          recordRoles.add(recordRole);

          //NotificationService
          NotificationService notificationService = ServiceLocator.locate(NotificationService.class);

          //NotificationParameters
          NotificationParameters notificationParameters = notificationService.newNotificationParameters();
          notificationParameters.setRecipientsByUserIds(recipients);
          notificationParameters.setRecipientsByGroups(groups);
          notificationParameters.setRecipientsByRecordRoles(recordRoles);
          notificationParameters.setSenderId(senderId);
          notificationParameters.setReplyToByUserId(userId);

          //NotificationTemplate
          NotificationTemplate template = notificationService.newNotificationTemplate()
          .setTemplateName("product_change_notification_template__c")
          .setTokenValue("productName", productName);

          //Send Notification with a NotificationTemplate
          notificationService.send(notificationParameters, template);

Example Notification Template

In the example above, the templateName product_change_notification_template__c is the name of a template created by an Admin in Vault. Below is an example of what this template may look like:

         Hello ${recipientName},

         The product ${Custom.productName} profile has been modified. Please review the changes.

         Regards,
         ${senderName}

Example Token Resolver Consumer

The following example implements a Consumer to resolve token values.

      @UserDefinedClassInfo
      public class NotificationTokenResolver implements Consumer<TokenResolverInput> {

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

              // resolve tokens for template "product_change_notification_template__c".
              Map<String, String> tokenValues = VaultCollections.newMap();
              tokenValues.put("productName", productName);
              output.setTokenValues("en", tokenValues);
          }
      }

Example Set Consumer

In the Notification example above, you can set the Consumer to the NotificationTemplate, instead of calling setTokenValue.

           //NotificationTemplate
           NotificationTemplate template = notificationService.newNotificationTemplate()
           .setTemplateName("product_change_notification_template__c")
           .setTokenResolver(new NotificationTokenResolver());