Field dependencies allow you to configure behavior for specific document fields, where that behavior is dependent on document lifecycle (plus state and user’s lifecycle role), document type, or the value in another document field.
Note: You cannot set up field dependencies for document fields that are Required.
Accessing Field Dependency Rules
Admins can manage field dependency rules from Admin > Configuration > Field Dependencies. This page lists all dependency rules defined for the Vault. The Condition column displays the controlling field, document type, or lifecycle and the Action column displays associated dependent fields.
From this page, you can click Export to Excel in order to export all field dependencies and sort through the details offline.
Controlled by Document Lifecycle
Field dependencies based on document lifecycle allow you to further refine access control for specific document fields based on the document’s lifecycle state and the active user’s document lifecycle roles.
Use Case: Controlled by Document Lifecycle
VeePharm may want to generally lock down all fields for documents in Approved state, but allow users in the Approver role to edit just a few fields. To accomplish this, that organization would configure security settings on the Approved state to remove Edit Fields permission on all roles except Approver. At this point, Approvers have edit access to all fields on a document in Approved state, but VeePharm wants to grant edit access on only the Document Approval Comments field and the Budget Approval Comments field.
To further restrict editing, the Administrator can configure a field dependency based on document lifecycle. That field dependency states that for the General lifecycle, the Approved document state, and the Approver role, the Document Approval Comments and Budget Approval Comments fields are Visible. This configuration does not automatically prevent editing on the other document fields. In order to set the behavior of those fields, the Administrator selects the Every field without a Lifecycle Dependency Rule checkbox and selects the is read only behavior.
How to Create Document Lifecycle-Based Dependencies
To create a new dependency rule where field behavior is controlled by document lifecycle state and user’s document lifecycle role:
- Click the Create button.
- Select the Controlled by document lifecycle option.
- Select a document lifecycle.
- Click OK to open the details page.
- Under Condition, select a Lifecycle State and Lifecycle Role.
- Under Dependency Rules, set up the dependent field actions:
- Click the Field label to select an action.
- If the controlling field has multiple dependent fields, click the + icon to add additional rows.
- When finished, click Save.
Known Issue When Reclassifying
Reclassifying moves a document to a new document type, subtype, and classification. If the new document type uses a different lifecycle, reclassifying can also change the document’s lifecycle. In these situations, Vault does not enforce the field dependencies based on the new lifecycle until the reclassifying user clicks Save, allowing users to view and edit fields that may be restricted by field dependencies on the new lifecycle.
Veeva Vault will introduce a fix for this issue (Issue No. DEV-210708) in a future release.
Controlled By Document Field
Controlling field dependencies allow you to set the behavior of a field based on the value selected for another field.
Use Case: Controlled by Document Field
The Field Readiness Date is only applicable when the Field Use field is set to Yes. Otherwise, Vault should hide the field. To configure this, the Admin would create a field dependency using the Controlled by document field setting. The Admin would select the Document Type and, because the field is defined at the classification level, the Subtype and Classification. Then, the user could select the controlling field, Field Use.
On the Create Field Dependency page, the Admin would finish defining the condition for Field Use and then choose Field Readiness Date and apply a specific behavior. When configuring dependencies that are controlled by a document field, Vault automatically applies the opposite behavior when the defined condition is not met. In this example, when Field Use is set to No, Vault hides Field Readiness Date.
How to Create Document Field-Based Dependencies
To create a new dependency rule where field behavior is controlled by another document field:
- Click the Create button.
- Select the Controlled by document field option.
- Make a document type selection. Only fields available for the selected document type will be available as controlling or dependent fields. You can set to Base Document to create a rule that applies to all documents.
- Select a controlling field from the Field picklist.
- Click OK to open the details page.
- Under Condition, set the field value that will cause the dependent field action. For example, Yes or No for a boolean field.
- Under Dependency Rules, set up the dependent field actions:
- Select Field or Picklist to indicate the type of dependent field.
- Select the field label and then select an action.
- If the controlling field has multiple dependent fields, click the + icon to add additional rows.
- When finished, click Save.
Controlled by Document Type
Field dependencies based on document type, subtype, and classification help organizations refine the fields that apply to specific document types. This is particularly useful when a Vault has fields defined at the Base Document level, but some fields are either not relevant or are required for a subset of document types.
Use Case: Controlled by Document Type
For example, the VeePharm Admin applies the Comments field at the Base Document level, meaning that it applies to all document types. In most cases, this field is optional, but the organization wants to ensure that it’s filled out for documents with the Follow Up Request document type. To configure this, the Admin creates a field dependency using the Controlled by Document Type option. The Admin then defines the dependency rule so that Comments has the Is required behavior when the document type is Follow Up Request.
How to Create Dependencies on Document Type
To create a new dependency rule controlled by document type:
- Click the Create button.
- Select the Controlled by document type option.
- Select a document type to use in the dependency rule. This selection also determines which document fields are available as dependent fields.
- Click OK to open the details page.
- Under Dependency Rules, set up the dependent field actions:
- Select Field or Picklist to indicate the type of dependent field.
- Select the field label and then select an action.
- If the controlling field has multiple dependent fields, click the + icon to add additional rows.
- When finished, click Save.
Dependent Field Behaviors
When setting up a field dependency, you’ll set the behavior for the dependent fields using one of these behaviors:
- Read Only: Dependent field is visible and read-only when the controlling conditions are met.
- Visible: Dependent field is visible and editable when the controlling conditions are met.
- Required: Dependent field is visible, editable, and required when the controlling conditions are met.
- Hidden: Dependent field is not visible when the controlling conditions are met.
Opposite Behaviors
Field dependencies using the Controlled by document field setting automatically apply the opposite behavior when the controlling conditions are not met. For example, a dependency that makes Field Readiness Date visible when Field Use is set to Yes automatically makes Field Readiness Date hidden when Field Use is set to No or is blank.
Note: This opposite behavior control does not apply to field dependencies that use the Controlled by document lifecycle setting.
The table below illustrates how Vault applies opposite behaviors on field dependencies using the Controlled by document type setting:
| If Document Type is X | If Document Type is not X |
|---|---|
| field is Hidden | field is Visible |
| field is Read Only | field is Hidden |
| field is Visible | field is Hidden |
| field is Required | field is Visible |
The table below illustrates how Vault applies opposite behaviors on field dependencies using the Controlled by document field setting:
| If Document Type is X | If Document Type is not X |
|---|---|
| field is Hidden | field is Visible |
| field is Read Only | field is Hidden |
| field is Visible | field is Hidden |
| field is Required | field is Hidden |
User Permissions & Field Behaviors
The behaviors defined through field dependencies can only further restrict access that a user already has through License Type, Security Profile, and Document Lifecycle Role. For example, making a field visible does not make it editable to a user who doesn’t have Edit Fields permission on the document.
Restrictions
Vault places some restrictions for dependencies using the Controlled by document type or Controlled by document field settings:
- In Controlled by document field dependencies, the controlling field must be boolean (yes/no), picklist, or object reference field.
- Dependent field cannot be controlled by any other field or document type. This rule is not enforced for Controlled by document lifecycle dependencies. A single field can be controlled by multiple document lifecycle dependencies, but only a single dependency based on document field or document type.
- Dependent fields cannot be defined as required in the document type hierarchy.
- Dependent fields cannot be defined as required, deleted, or lookup fields.
- Dependent fields cannot be standard Vault fields. (The Document Title field is an exception to this rule. Document Title can be made required for standard or custom document types.)
Special Considerations
There are a couple of items of note regarding dependent fields:
- Controlled field behaviors are only enforced at the UI level. The API and VQL do not use dependent field rules.
The Hidden action is generally used with document type-based rules in order to hide a field that is defined at the document type for a subset of that document type’s subtypes. You can use shared fields instead of dependency rules for these situations.
How to Create Document Type-Based Dependencies
To create a new rule where the controlling field is a document type:
- Click the Create button.
- Select the Controlled by document type option.
- Select a document type to be the controlling field in the dependency rule. This selection also determines which document fields are available as dependent fields.
- Click OK to open the Field Dependency Details page.
- Under Dependency Rules, set up the dependent field actions:
- Select Field or Picklist to indicate the type of dependent field.
- Select the field label and then select an action.
- If the controlling field has multiple dependent fields, click the + icon to add additional rows.
- When finished, click Save.
How to Create Document Field-Based Dependencies
To create a new rule where the controlling field is a document field:
- Click the Create button.
- Select the Controlled by document field option.
- Make a document type selection. Only fields available for the selected document type will be available as controlling or dependent fields. You can set to Base Document to create a rule that applies to all documents.
- Select a controlling field from the Field picklist.
- Click OK to open the Field Dependency Details page.
- Under Condition, set the field value that will cause the dependent field action. For example, Yes or No for a boolean field.
- Under Dependency Rules, set up the dependent field actions:
- Select Field or Picklist to indicate the type of dependent field.
- Select the field label and then select an action.
- If the controlling field has multiple dependent fields, click the + icon to add additional rows.
- When finished, click Save.
Special Considerations
There are a couple of items of note regarding dependent fields:
- The Required action is only enforced at the UI level. The API doesn’t use dependent field rules. Fields defined as required through the document type hierarchy apply at the UI level and in the API.
- Field dependency rules also affect the behavior of dependent fields when the conditions are not met.
- The Hidden action is generally used with document type-based rules in order to hide a field that is defined at the document type for a subset of that document type’s subtypes. You can use shared fields instead of dependency rules for these situations.
- When Read-Only is applied to a field through a security override, a field dependency cannot remove the action. You must remove the security override in order to remove the Read-Only action.
Updating Dependency Rules
Some options that you define for a field dependency rule are only available during the initial creation process. When editing an existing rule, you can only modify the controlling conditions and the dependent fields. You cannot modify the document type selection.
Note that all rule updates apply immediately upon saving.
Viewing Where Rules are Used
In addition to viewing defined rules on the Field Dependencies page, you can also view rules from the document field details page for the controlling or dependent fields.
