# Configuring Matching Sharing Rules for Objects 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.
## 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][1]. Vault uses the field values in this object to match Auto Managed user groups to specific object records. Vault can only use [certain fields][2] 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.
### 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 {#urs-objects} 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: 1. Find fields on the object you're securing, for example, _Product_. 2. Note the field names, for example, `therapeutic_area__c` and `product_family__v`. 3. Navigate to the _User Role Setup_ object configuration. This may be a custom object with the _User Role Setup_ class. 4. 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 {#field-mapping} 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 {#create} 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: 1. Navigate to the object configuration: **Admin** > **Configuration** > **Objects** > **[Object]**, and then click into the **Sharing Rules** tab. 2. Click **Create**. 3. Enter a descriptive **Label** for the rule. The label will be visible in the object record's **Sharing Settings**. 4. Optional: Edit the **Name**. This is automatically assigned based on the label, but you can update if needed. This will be visible through the Vault API. 5. Optional: Enter a **Description**. The description only appears in the sharing rule details page. 6. Select a **Role** for the rule to apply to. 7. Under **Rule Criteria**, define the matching parameters by selecting fields. See [details][3] about field mapping. The pattern for the corresponding Auto Managed group appears below the criteria. 8. Click **Save**. 9. Click **Create** to add any additional sharing rules as needed. 10. 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. [1]: #urs-objects [2]: #matching-fields [3]: #field-mapping