About Dynamic Access Control for Documents

Dynamic Access Control (DAC) is an access control model for documents, which automates the assignment of users to document roles. In previous releases, you had to manage groups and override rules when using DAC. Unlike role defaulting with the previous access control model, DAC can add and remove users from a role without any trigger action on the document by editing users’ membership in new Auto Managed groups.

In this model, Admins control user role assignment by managing records in the new User Role Setup object. These records correspond to Auto Managed groups. The User Role Setup object can be administered by IT administrators or end users, like country teams. A User Role Setup record includes a user, role, and several object reference field values (for fields that are on both documents and the User Role Setup records) which further qualify the user’s context for the role.

For example, Thomas is a Reviewer for the CholeCap product in the United States and Amir is a Reviewer for the CholeCap product in Canada. Based on the sharing rules for the Reviewer role, Thomas would only get access to documents for the United States and Amir would only get access to documents for Canada.

Note: When implementing any custom security or access control, Admins should perform UAT (User Acceptance Testing) before making changes on a production site. Some changes can affect application-specific functionality in ways that make Vault difficult to use.

Setup Overview

There are two kinds of setup to think about with DAC for documents. The first is your initial configuration and subsequent periodic re-configurations. The second is ongoing maintenance.

Initial & Periodic Configuration

Before starting any DAC configuration project, think through your access control model. For example, across all of the roles automated through DAC, what criteria (up to five fields) will be necessary to match users to documents? During this phase, you may want to consult Veeva Services for additional recommendations.

Once your organization has a plan in place, you can begin configuring. We recommend enabling Configuration Mode while completing the following setup tasks.

From Admin > Configuration > Objects, review and edit the User Role Setup object. If needed, you can add or remove fields. Vault uses the values in these fields to match groups to specific documents. By default, Vault pairs the object field to the document field based on the field name (excluding suffix), not label, for example, product__v document field and product__c object field. Although you can add any kind of field to this object, Vault can only use object reference fields or single-value picklists applied to both this object and documents for matching. There is a limit of five (5) custom fields for this object.
From Admin > Settings > Security Settings, review the order of fields in the Auto Managed Group Field Order setting. This setting controls how Vault names Auto Managed groups. If needed, you can reorder these fields at any time, but doing so will only affect groups created after the change, so we recommend making your changes before continuing DAC configuration. The application role always goes at the end of the name.
From Admin > Configuration > Document Lifecycles > [Lifecycle] > Roles > [Role] > Details, enable DAC for any lifecycle roles that will use it. When you enable, you can also select an Allowed Group, which restricts manual assignments through the document’s Sharing Settings panel. You can enable DAC on each lifecycle role individually, but we recommend that you use DAC for all roles in a given lifecycle. Single-user roles (Owner and Coordinator) cannot use DAC. Once you enable DAC for a given role, you cannot disable it for that role.
Review how your lifecycle roles are mapped to application roles. When creating User Role Setup records, users will select application roles, not lifecycle roles. It is possible that multiple lifecycle roles use a single application role.
From Admin > Configuration > Document Lifecycles > [Lifecycle] > Roles. Open each lifecycle role that uses DAC and navigate to the Sharing Rules section. Set up rules to dictate how groups are matched to documents and assigned.
Navigate to Business Admin > Objects and create the initial set of User Role Setup records. In most Vaults, there will be more than one record per user. Because of the large number of records, we recommend that you use Vault Loader to create the initial set.

Note: Any role assignment that occurred before DAC (through defaulting or editing in a document’s Sharing Settings panel) is considered a manual assignment. Enabling DAC on a role does not affect any assignments that have already occurred.

Ongoing Maintenance

As new users come on-board, existing users change roles, and other users leave, you’ll need to maintain your access control settings by creating, updating, and deleting User Role Setup records. When this happens, Vault automatically recalculates group membership to make sure that these users have the correct lifecycle roles on the correct documents. If these edits result in the creation of a new Auto Managed group, there will be a delay as Vault calculates access for the new group. Depending on the number of documents affected, the delay may take up to several minutes. A notification banner displays in the configuration screen while this operation is in progress.

Run-Time Behavior

Role reassignment happens automatically when a document’s field values change, which can occur as part of a lifecycle state change, a workflow, or a user edit. This does not require any Admin action. For example, a sharing rule that applies to DOC-1039 uses the Country field value to determine and assign access. The Country field on Doc-1039 is blank, which affects which users have access. When Doc-1039 goes through a workflow in which a user updates the Country field, Vault automatically reassesses and changes the document’s role assignments.

Note: Role assignment is based on document field values for the latest document version. Role assignments on previous versions of a document will lose permissions once document field values change on the latest version or the role is not available on the latest lifecycle state. When opening a previous document version, keep in mind that any role permissions on that version may not be applicable if the lifecycle state classification is different from the current version.

Application Roles

The Application Role object maps lifecycle roles to a higher “application-level” role. The Application Role object does not have any special functionality by itself. However, various other features utilize it, including DAC for documents.

The Application Roles object is active and available in all Vaults. Each lifecycle role (custom or standard) is automatically mapped to an Application Role record. You can review and update these role mappings at any time from the lifecycle role details. If needed, you can also create or modify Application Role records from Admin > Users & Groups > Application Roles.

When you select a role in a User Role Setup record, the list shows application roles, rather than lifecycle roles. This means that sharing rules for multiple lifecycle roles may use the same Auto Managed groups, depending on how your lifecycle roles are mapped to application roles.

If enabled, an Admin can configure User Role Constraints to control user role assignments.

Example

The Promo Binder and Promotional Pieces lifecycles both include a role called Reviewer and both roles use DAC. Those two lifecycle roles map to the same Application Role record: Reviewer AR. Both lifecycle roles have sharing rules that match based on Product and Country fields.

When an Admin creates User Role Setup records, she makes the following selections:

User = Thomas Chung
Product = CholeCap
Country = United States
Role = Reviewer AR

Vault puts Thomas into the Auto Managed group CholeCap - United States - Reviewer AR, which gets the Reviewer roles for matching Promo Binders and Promotional Pieces.

Lifecycle Role Conflicts

If you map one application role to multiple lifecycle roles and those lifecycle roles use Dynamic Access Control, you may see warnings in the lifecycle role Sharing Rules tab (Admin > Configuration > Document Lifecycles). These warnings indicate that the sharing rules differ between the lifecycle roles that use the same application role.

If you are working on a new implementation, we strongly recommend aligning the configurations for any lifecycle roles that use the same application role. This will allow you to benefit from future enhancements that will simplify administration.

In existing implementations, you can leave your configuration as is. Your Vault will continue to work as expected.

Sharing rules provide a dynamic way of controlling which users are in which roles. When creating a sharing rule, you’ll define object reference or single-value picklist fields on both the document and the User Role Setup object. Vault uses the values in these fields as matching criteria for an Auto Managed group to get access through the lifecycle role you’re configuring. For example, both the User Role Setup object and documents have the Product (product__c) field set up. The sharing rule defines matching on this field. When the rule is active, Vault checks if the Product value for the current document version matches the Product value for a User Role Setup record.

If your role should give access based on a very specific match as well as a “partial” match, you can set up multiple sharing rules. For example, Site Managers could get Approver access through matching criteria on Study, Study Country, and Site fields, whereas Study Managers could get access through matching criteria on just Study.

Sharing rules can match on a document’s object lookup field, as long as the field it points to is an object reference or a single-value picklist. For example, to support a rule that matches on Product: Therapeutic Area, you’d need to create a Lookup-type field on the document. On the User Role Setup object, you’d create a Picklist-type field that uses the existing Therapeutic Area picklist.

To create a sharing rule:

Navigate to the role’s details: Admin > Configuration > Document Lifecycles > [Lifecycle] > Roles, and then click on the specific role.
Click into the Sharing Rules tab.
Click Create.
Enter a descriptive Label for the rule. The label will be visible in the document’s Sharing Settings.
Optional: Edit the Name. This is automatically assigned based on the label, but you can update if needed. This will be visible through the API.
Optional: Enter a Description. The description only appears in the sharing rule’s details page.
Under Rule Criteria, define the matching parameters by selecting fields on the User Role Setup object and on documents. See details about field mapping. The pattern for the corresponding Auto Managed group appears below the criteria.
Click Save.
Click Create to add any additional sharing rules as needed.

When you initially create or modify a rule, Vault must reindex records to apply the new settings. This may take up to several hours.

To modify a sharing rule, return to the Sharing Rules tab on the object configuration and click into a specific rule:

Click Edit to change the label, name, description, or criteria.
Click Delete to permanently remove the rule.

About Rule Criteria Field Mapping Flexibility

By default, when defining rule criteria, Vault maps User Role Setup fields to document fields with the same name (excluding suffix). If more than one active document field references the same object, picklist, or lookup field, you can select from the available fields in the drop-down. Once you define a sharing rule that maps such a field, that mapping will carry through to all subsequent sharing rule definitions.

Matching on Blank Values

Dynamic Access Control matching rules look for exact matches between field values. When a field is included in a sharing rule, blank field values will only match to other blank field values. For example, a User Role Setup record where the Country field is blank will only match documents where the Country field is blank. Blank values used in a rule are treated like other values, not like wildcards for matching. Vault does not consider values for fields not included in a rule.

Limits

Your Vault can have up to eight (8) sharing rules per role.

Manual Assignment

When you enable DAC for a role, users with the required permissions can still manually share a document by adding another user to a role. Users can also add users to roles when starting a workflow. Manual assignment respects the Allowed Group setting on the role configuration.

Users can never use manual assignment options to remove groups assigned through sharing rules from their roles.

Document Type Groups

Vault provides the Document Type Group object to help you streamline User Role Setup record creation in Vaults where you need to base sharing rules on document types. If you don’t base sharing rules on document type, you can skip this setup.

Setting Up Document Type Groups

To use this, you’ll first need to create Document Type Group records. Then, edit the document type configurations and select specific document type groups.

When you select a Document Type Group for base document, a document type, or a subtype, all child levels inherit that lifecycle. You can change which group is selected at any level. When you do so, any children of the edited type or subtype will now inherit the new value.

Selecting Multiple Document Type Groups

For a given document type, subtype, or classification, you can select multiple Document Type Group records. Doing so can help you support more complex sharing rules.

For example, Miki is an Editor on documents for Japan where the document type is Advertising - Web, but the United States has less stringent access control. John is an Editor on documents for United States where the document type is Advertising - Web, Advertising - Print, or Advertising - Radio. To set this up, you could to apply a document type group to Advertising - Web and another group to all three document types. You could then create a single User Role Setup record to support Miki’s access and a single record to support John’s access. Otherwise, you’d need to create three User Role Setup records for John and one for Miki.