Package com.veeva.vault.sdk.api.role

package com.veeva.vault.sdk.api.role
This package provides interfaces to retrieve and manage role membership for a document or object record.

The interfaces in this package allow you to:

  • Create triggers on direct role assignments which execute code before or after roles are manually assigned or unassigned on an object record.
  • Check if a user is in a particular role on a record. This includes users assigned through manual assignment or Dynamic Access Control.
  • Check if a user is in a particular application role on an object record or lifecycle role on a document. This includes users assigned through manual assignment or Dynamic Access Control.
  • Retrieve users and groups directly assigned to a role on a record or document.
  • Add and remove users and groups from a role on a record or document. Note that you can only remove manually assigned users and groups from roles.
  • Check which users, records, or documents are missing assignments in a particular role, and then add those missing assignments.

Record Role Triggers

The following example illustrates a trigger which sends a notification to users when they are assigned to the Editor role on a Product record. 
     @RecordRoleTriggerInfo(object = "product__v", events = RecordRoleEvent.AFTER, order = TriggerOrder.NUMBER_1)
     
      public class SendRoleAssignmentNotification implements RecordRoleTrigger {
          public void execute(RecordRoleTriggerContext recordRoleTriggerContext) {
              RecordRoleService recordRoleService = ServiceLocator.locate(RecordRoleService.class);
              NotificationService notifService = ServiceLocator.locate(NotificationService.class);

              // Get Record Role changes
              List <RecordRoleChange> roleChangesList = recordRoleTriggerContext.getRecordRoleChanges();

              for (RecordRoleChange roleChange : roleChangesList) {
                  // Trigger the code only for the editor role
                  if (roleChange.getRecordRole().getRole().getRoleName().equals("editor__v")) {
                      RecordRole role = roleChange.getRecordRole();
                      Record record = role.getRecord();
                      List<String> userAdded = roleChange.getUsersAdded();

                      for (String userID : userAdded) {
                          boolean isInRole = recordRoleService.getUserInRecordRoles(userID,
                               VaultCollections.asList(role))
                               .isUserInRecordRole(role);

                          // Send a notification only if the user is not an Editor yet
                          if (!isInRole) {
                              // Send a notification to inform the user has been added in the role
                              NotificationMessage msg = notifService.newNotificationMessage();

                              String recordID = record.getValue("id", ValueType.STRING);

                              msg.setSubject("You were added in Record:" + recordID);
                              msg.setNotificationText("Record" + recordID);
                              msg.setMessage("Record: " + recordID);

                              Set<String> userIDsList = VaultCollections.newSet();
                              userIDsList.add(userID);

                              NotificationParameters notifParam =
                              notifService.newNotificationParameters();
                              notifParam.setRecipientsByUserIds(userIDsList);
                              notifParam.setSenderId(userID);
                              notifService.send(notifParam, msg);
                          }
                      }
                  }
              }
           }
        }

Object Records

The following example illustrates checking role membership on a record and adding a user to a role. 
     
      // Role to check on the Record
      String ROLE_TO_CHECK = "approver__c";

      // Locate services
      LogService logService = ServiceLocator.locate(LogService.class);
      RecordRoleService recRoleService = ServiceLocator.locate(RecordRoleService.class);

      // Get record from the recordActionContext (One record for user action)
      List<Record> recList = recordActionContext.getRecords();
      Record rec = recList.get(0);

      // Get current user ID
      String currentUserID = RequestContext.get().getCurrentUserId();

      // Get approver role for the record
      GetRecordRolesResponse recRolesResp = recRoleService.getRecordRoles(recList, ROLE_TO_CHECK);
      RecordRole approverRole = recRolesResp.getRecordRole(rec);

      // Check if current user is in Approver role
      boolean isUserInApproverRole = recRoleService
          .getUserInRecordRoles(currentUserID, VaultCollections.asList(approverRole))
          .isUserInRecordRole(approverRole);

      // Add current user to Approver role
      if (!isUserInApproverRole) {
          // Create new RecordRoleUpdate and add users
          RecordRoleUpdate recRoleUpdate = recRoleService.newRecordRoleUpdate(ROLE_TO_CHECK, rec);
              recRoleUpdate.addUsers(VaultCollections.asList(currentUserID));

          // Execute the role update
          recRoleService.batchUpdateRecordRoles(VaultCollections.asList(recRoleUpdate))
              .rollbackOnErrors()
              .execute();
      }

Documents

The following example illustrates checking role membership on a document for the current user and adding the user to a role if not already assigned. 
     
      // Role to check on the Document
      String ROLE_TO_CHECK = "approver__c";

      // Locate services
      LogService logService = ServiceLocator.locate(LogService.class);
      DocumentRoleService docRoleService = ServiceLocator.locate(DocumentRoleService.class);

      // Assuming this is a Document user action, there is one document in the documentActionContext
      List<DocumentVersion> docVersionList = documentActionContext.getDocumentVersions();
      List<DocumentRoleUpdate> docRoleUpdList = VaultCollections.newList();
      DocumentVersion docVersion = docVersionList.get(0);

      // Get current user ID
      String currentUserID = RequestContext.get().getCurrentUserId();

      // Get Approver document role
      GetDocumentRolesResponse docRolesResp = docRoleService.getDocumentRoles(docVersionList, ROLE_TO_CHECK);
      DocumentRole approverRole = docRolesResp.getDocumentRole(docVersion);

      // Check if current user is in Approver role
      boolean isUserInApproverRole = docRoleService
          .getUserInDocumentRoles(currentUserID, VaultCollections.asList(approverRole))
          .isUserInDocumentRole(approverRole);

      // Add current user to Approver role
      if (!isUserInApproverRole) {
          DocumentRoleUpdate docRoleUpdate = docRoleService.newDocumentRoleUpdate(ROLE_TO_CHECK, docVersion);
              docRoleUpdate.addUsers(VaultCollections.asList(currentUserID));

          // Execute the role update
          docRoleService.batchUpdateDocumentRoles(VaultCollections.asList(docRoleUpdate))
              .rollbackOnErrors()
              .execute();
      }

Performance Considerations

Avoid retrieving or updating roles one at a time in a loop. Instead, process multiple records or documents in a single service method call.