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);
                          }
                      }
                  }
              }
           }
        }
     
      

Reading and managing object record role membership

The following example illustrates checking role membership on a record and adding a user to a role. This example runs in the context of a record action.

     
      // 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();
      }

 

Checking for missing user sharing setting assignments and updating sharing settings for records

The following example checks to see if users 2, 3, and 4 are not assigned to the editor__v role in record sharing settings. If they are not currently assigned to the editor__v role, it assigns the missing users to that role.

 
 @RecordTriggerInfo(object = "test_assign_roles__c", events = { RecordEvent.AFTER_INSERT, RecordEvent.AFTER_UPDATE })
 @RunAs(RunAsUser.REQUEST_OWNER)
 public class TestVobjectTrigger implements RecordTrigger {

     @Override
     public void execute(RecordTriggerContext recordTriggerContext) {
         RecordRoleService recordRoleService = ServiceLocator.locate(RecordRoleService.class);

         // Retrieve Records from recordChanges
         List<Record> recordsToCheck = VaultCollections.newList();
         for (RecordChange recordChange : recordTriggerContext.getRecordChanges()) {
             recordsToCheck.add(recordChange.getNew());
         }

         // Check missing assignments for users 2, 3, 4 in the editor__v role
         GetMissingAssignmentsRecordResponse response = recordRoleService.getMissingAssignments(recordsToCheck, "editor__v", VaultCollections.asList("2", "3", "4"));

         // Add missing users to sharing settings for the record being processed
         List<RecordRoleUpdate> recordRoleUpdatesToPersist = VaultCollections.newList();
         for (Record record : response.getRecords()) {

             // Assign missing users to editor__v role if any of the users aren't already assigned in sharing settings
             if (!response.getUsers().isEmpty()) {
                RecordRoleUpdate recordRoleUpdate = recordRoleService.newRecordRoleUpdate("editor__v", record);
                recordRoleUpdate.addUsers(response.getUsers());
                recordRoleUpdatesToPersist.add(recordRoleUpdate);
             }
         }

         // Persist the records role updates
         recordRoleService.batchUpdateRecordRoles(recordRoleUpdatesToPersist).rollbackOnErrors().execute();
     }
 }
 

 

Reading and managing document role membership

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. This example is implemented as part of a document user action.

     
      // 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);
      LifecycleRole approverLifecycleRole = approverRole.getLifecycleRole();
      logService.info("Checking if current user is in {} lifecycle role for document ID: {}", approverLifecycleRole.getLifecycleRoleLabel(), docVersion.getValue("id", ValueType.STRING));

      // 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();
      }

 

Checking for missing user sharing setting assignments and updating sharing settings for documents

The following example checks to see if users 2, 3, and 4 are not assigned to the editor__v role in document sharing settings. If they are not currently assigned to the editor__v role, it assigns the missing users to that role.

 
 @DocumentTypeTriggerInfo(
         events = {DocumentVersionEvent.AFTER_UPDATE},
         level = DocumentVersionEventLevel.DOCUMENT_VERSION,
         documentType = "testDocumentType__c",
         order = TriggerOrder.NUMBER_1, eventSegment = EventSegment.POST_CUSTOM
 )
 public class DocumentVersionTriggerTest implements DocumentTypeTrigger {

     @Override
     public void execute(DocumentTypeTriggerContext documentTypeTriggerContext) {
         DocumentRoleService documentRoleService = ServiceLocator.locate(DocumentRoleService.class);

         // Retrieve document versions from context
         List<DocumentVersion> documentVersions = VaultCollections.newList();
         for (DocumentVersionChange documentVersionChange : documentTypeTriggerContext.getDocumentVersionChanges()) {
             documentVersions.add(documentVersionChange.getNew());
         }

         // Check missing assignments for users 2, 3, 4 in the editor__v role
         GetMissingAssignmentsDocumentResponse response = documentRoleService.getMissingAssignments(documentVersions, "editor__v", VaultCollections.asList("2", "3", "4"));

         // Add missing sharing settings for the documents being processed
         List<DocumentRoleUpdate> documentRoleUpdates = VaultCollections.newList();
         for (DocumentVersion documentVersion : response.getDocumentVersions()) {

             // Assign missing users to editor__v role if any of the users aren't already assigned in sharing settings
             DocumentRoleUpdate docRoleUpdate = documentRoleService.newDocumentRoleUpdate("editor__v", documentVersion);
             if (!response.getUsers().isEmpty()) {
                 docRoleUpdate.addUsers(response.getUsers());
                 documentRoleUpdates.add(docRoleUpdate);
             }
         }

         // Persist document role updates
         documentRoleService.batchUpdateDocumentRoles(documentRoleUpdates).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.

Class	Description
DocumentRole	Provides methods to retrieve information in a DocumentRole.
DocumentRoleService	Provides methods to read and update DocumentRoles.
DocumentRoleUpdate	Provides methods to add or remove users and groups in a DocumentRole.
GetDocumentRolesResponse	Provides methods to retrieve DocumentRole, returned from DocumentRoleService.getDocumentRoles(List, String).
GetGroupInDocumentRolesResponse	Provides methods to check if a particular group is assigned to a given document role, returned from DocumentRoleService.getGroupInDocumentRoles(Group, List).
GetGroupInRecordRolesResponse	Provides methods to check group membership in a RecordRole, returned from RecordRoleService.getGroupInRecordRoles(Group, List).
GetMissingAssignmentsDocumentResponse	Provides methods to check which users or documents are missing assignments in a particular role.
GetMissingAssignmentsRecordResponse	Provides methods to check which users or records are missing assignments in a particular role.
GetRecordRolesResponse	Provides methods to retrieve RecordRoles, returned from RecordRoleService.getRecordRoles(List, String).
GetUserInDocumentRolesResponse	Provides methods to check if a particular user is assigned to a given document role.
GetUserInRecordRolesResponse	Provides methods to check user membership in RecordRole.
LifecycleRole	Provides methods to retrieve role information for a document or object lifecycle.
RecordRole	Provides methods to retrieve information in a RecordRole.
RecordRoleChange	Represents changes applied to a record role.
RecordRoleEvent	Contains valid Event values to specify when the trigger occurs.
RecordRoleService	Provides methods to retrieve and update RecordRoles.
RecordRoleTrigger	Invoked to start a trigger; takes RecordRoleTriggerContext as input.
RecordRoleTriggerContext	Input to a RecordRoleTrigger.
RecordRoleTriggerInfo	Indicates a class is a RecordRoleTrigger.
RecordRoleUpdate	Provides methods to perform updates on a RecordRole.
Role	Provides methods to retrieve application role information.