Matching Sharing Rules are part of Dynamic Access Control for objects. These rules allow assignment of users to Auto Managed groups and dynamic assignment of those groups to roles on specific object records.
Note: When implementing any custom security or access control, Admins should perform UAT (User Acceptance Testing) before making these changes on a production site. Some changes can affect application-specific functionality in ways that make Vault difficult to use.
Configuration Overview
There are two kinds of configuration to think about with Matching Sharing Rules: The first is your initial configuration and periodic re-configurations. The second is ongoing maintenance.
Initial & Periodic Configuration
Before starting any Matching Sharing Rules implementation, plan out your access control model. For example, across all of the roles, what criteria (up to six fields) will be necessary to match users to object records? You don’t need to complete this process for all objects that will use Matching Sharing Rules: you can configure individual objects at different times. During this phase, we recommend that you consult Veeva Services.
Once your organization has a plan in place, you can begin configuring. We recommend enabling Configuration Mode while completing the following tasks. Once you enable Matching Sharing Rules for an object, all users will lose access to the object records until you’ve fully configured the rules.
- From Admin > Configuration > Objects, review the User Role Setup object. You can add or remove fields from this object or create a new object with the User Role Setup class. Vault uses the field values in this object to match Auto Managed user groups to specific object records. Vault can only use certain fields for matching. Each field must exist on both the User Role Setup object and the secured 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 with Matching Sharing Rules configuration. Note that Application Role always goes at the end of the name.
- From Admin > Configuration > Objects > [Object] > Details, enable Matching Sharing Rules. Select the specific User Role Setup object that the secured object will use. Select a Lifecycle for the object. You may need to configure a new lifecycle.
- Optional: Select the Use Action Security to control Sharing Settings checkbox. This allows you to configure action security on sharing settings to control users’ access to sharing settings for each record, role, and lifecycle state.
- Optional: From Admin > Configuration > Object Lifecycles > [Lifecycle] > Roles, set up any additional roles that you want to use with Matching Sharing Rules.
- From Admin > Configuration > Objects > [Object], navigate to the Sharing Rules tab. Set up Matching Sharing Rules to dictate how Vault matches and assigns groups to object records.
- Navigate to Business Admin > Objects and create the initial set of User Role Setup records (for the User Role Setup object that you’re using). In most Vaults, there will be more than one record per user. Because of the large number of records, you should consider using Vault Loader to create the initial set. Note: If enabled, an Admin can configure User Role Constraints to limit user role assignments.
Note: If the object uses Custom Sharing Rules, enabling Matching Sharing Rules does not affect the existing role assignments. Assignments that happen as a result of Matching Sharing Rules are in addition to existing assignments.
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 roles on the correct object records. 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 object records affected, the delay may take up to several minutes. A notification banner displays in the configuration screen while this operation is in progress.
User Role Setup & Object Class
If any of your objects use Matching Sharing Rules, your Vault will either include one User Role Setup object or multiple objects with the User Role Setup object class. DAC for documents always uses the original User Role Setup object, but Matching Sharing Rules for object records can use multiple objects with this class.
There are several situations in which creating multiple objects with this class is necessary:
- If your Vault uses Dynamic Access Control for documents.
- If you need to set up Matching Sharing Rules for multiple objects and these objects require more than six (6) matching fields among them. For example, your Vault matches users to Country records based on Region values, but matches users to Product records based on Therapeutic Area, Status, and several other fields. Since the rules involve more than six (6) different fields, you must create an object with the User Role Setup class for each secured object configuration.
When you’re creating multiple objects with the User Role Setup class, we recommend using a naming convention that makes it clear which objects each supports, for example, “URS Country” and “URS Product.”
Application Roles
The Application Role object provides an “application-level” role that you can add to the object lifecycle. Viewer, Editor, and Owner roles are set up by default. Within the object configuration, you can define permissions for each role you add. These role permissions only apply that object.
Although you can select any application roles when creating User Role Setup records, not all roles will be valid. Matching Sharing Rules can only use the standard Viewer, Editor, and Owner roles plus any application roles that you have added to the object lifecycle.
Note that an Application Role can reference a permission set in its Permission Set field. This field is for use in role permissions. The permission set in this field is only granted when the user is associated with the Application Role via a User Role record, and is not applied when a user is added to the role via sharing settings or a matching sharing rule.
Matching Fields
Dynamic Access Control uses matching fields as the criteria for Matching Sharing Rules. Any matching fields must exist on both the secured object and the User Role Setup object. For example, a rule assigns to the Editor role on Product based on Therapeutic Area values. This rule can only work if there is a Therapeutic Area field on both Product and User Role Setup.
How to Set Up Matching Fields
To define matching fields:
- Find fields on the object you’re securing, for example, Product.
- Note the field names, for example,
therapeutic_area__candproduct_family__v. - Navigate to the User Role Setup object configuration. This may be a custom object with the User Role Setup class.
- Create new object fields corresponding to the fields on the secured object. Vault maps the fields to each other using the underlying object or picklist. In case there are multiple fields that match the underlying component, Vault allows you to select one, which is used for all matching rules on the object.
Valid Field Types
Not all fields are valid as matching fields. You must use the following field types:
- Picklist (must be single-select on user role setup and single -select or multi-select on the secured object)
- Object reference (must be single-select on both User Role Setup and secured object)
- Lookup (must point to a valid single or multi-value picklist, or an object reference field)
- Name (
name__v) on the secured object - Name (
name__c) on an object referenced by the secured object
About the Source and Source Reference Fields
There are two non-required, non-editable fields on objects with the User Role Setup class:
- Source (
user_source__sys) picklist - Source Reference (
user_source_ref__sys) text field.
Vault applications may use these fields in future releases to track the origination of User Role Setup records. Although Vault prevents users from saving values in the Source and Source Reference fields, the fields do appear as editable when working with User Role Setup objects. We recommend using field-level security to make these fields read-only for all security profiles except Vault Owner.
About Rule Criteria Field Mapping Flexibility
By default, when defining rule criteria, Vault maps User Role Setup fields to object fields with the same name (excluding suffix). If more than one active object field references the same object, picklist, or lookup field, you can select from the available fields in the drop-down. Note that once you define a sharing rule that maps such a field, that mapping will carry through to all subsequent sharing rule definitions.
Matching on Lookup Fields
Matching Sharing Rules support matching on Lookup-type fields. In this situation, the field on the User Role Setup object would be a picklist or object reference field and the field name would correspond to the name of the field that the Lookup field “looks up.”
For example, VeePharm secures the Marketing Campaign object using Therapeutic Area, a picklist field on the Product object and a Lookup field on the Marketing Campaign object. To set this up, the Vault needs the following fields:
| Field Label & Name | Field Type | On Object | Comments |
Therapeutic Area (therapeutic_area__c)
|
Picklist | Product | |
Product (product__v)
|
Object Reference | Marketing Campaign | Establishes a relationship between Marketing Campaign and Product |
Therapeutic Area (therapeutic_area__c)
|
Lookup | Marketing Campaign | Pulls in a value from the related Product object record |
Therapeutic Area (therapeutic_area__c)
|
Picklist | User Role Setup | Creates the corresponding field on User Role Setup for matching |
Matching on Name Fields
You can use Name fields to create rules that secure individual records and their child records by name. For example, a User Role Setup record could assign Thomas Chung to the Editor role on Study VVT485-301. This reduces the setup needed to secure object records and is particularly useful for securing records in a parent-child relationship, like Study > Study Country > Study Site.
Behind the scenes, Vault uses an object record’s ID, rather than actual Name value. This prevents access control setup from breaking if the record’s Name value changes.
Matching on Blank Values
Dynamic Access Control matching rules look for exact matches between field values. When a field is included in a 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 object records where the Country field is blank. Blank values used in a rule are treated like other values, not like wildcards for matching.
Limits
A User Role Setup object can have up to six (6) custom fields for matching.
Your Vault can have up to eight (8) sharing rules per secured object, per role. For example, Product may have a total of 32 rules: 8 for Owner, 8 for Editor, 8 for Viewer, and 8 for the custom Reviewer role.
Creating Matching Sharing Rules
When creating a sharing rule, you’ll select matching fields. Vault uses the values in these fields as matching criteria for an Auto Managed group. For example, the sharing rule defines matching on Therapeutic Area (therapeutic_area__c). When the rule is active, Vault checks if the Therapeutic Area value for a given object record matches the Therapeutic Area value for a User Role Setup record.
If your role should give access based on a very specific match as well as a looser “partial” match, you can set up multiple sharing rules. For example, Viewers could get access through matching criteria on just Therapeutic Area fields, whereas Editors could get access through matching criteria on Therapeutic Area, plus Product Family.
How to Create Rules
To create a sharing rule:
- Navigate to the object configuration: Admin > Configuration > Objects > [Object], and then click into the Sharing Rules tab.
- Click Create.
- Enter a descriptive Label for the rule. The label will be visible in the object record’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 details page.
- Select a Role for the rule to apply to.
- Under Rule Criteria, define the matching parameters by selecting fields. 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 rules. This may take up to several hours. A yellow bar appears at the top of the screen to indicate progress.
How to Modify Rules
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.
Related Permissions
To enable Matching Sharing Rules and create rules, your security profile must grant the Admin > Object > Edit permission.