When you create a field that results in a document reference, object reference, or parent relationship, you can also constrain the available records. You can set up either static or dynamic reference constraints on parent and reference fields.
Static Reference Constraints
Static reference constraints allow you to apply a constraint on a reference field with a defined value during configuration. This restricts the list of available records in a referenced field based on the defined value.
Dynamic Reference Constraints
Dynamic reference constraints allow you to apply a constraint on reference fields based on values that aren’t defined until a user provides input. This restricts the list of available records in a referenced field based on a controlling field. Object references support dynamic constraints by object reference or picklist fields, while document references only support dynamic constraints by object reference fields. When you apply a dynamic reference constraint, Vault displays text in the referenced field specifying the dependency on the controlling field and does not allow you to enter a value.
You can only set up dynamic reference constraints using a VQL query. The constraint criteria may contain a simple query condition or complex relationship query condition. Additionally, the criteria VQL for dynamic reference constraints must contain the token for a valid configuration.
How to Constrain Related Records
To set up a constraint:
- Open an existing document reference, object reference, or parent field in edit mode. You cannot filter when initially creating the field.
- Scroll down to the Constrain Referenced Document or Constrain Records in Referenced Object section.
- Use a VQL query to define the conditions in the Criteria VQL field.
- Optional: Click Validate to confirm if your criteria VQL is valid.
- Optional: Click Preview to see how field selection will look once your filter rule is in place. This option is not available for dynamic constraints.
- Click Save.
Limitations
When you set up a constraint, Vault only applies filters going forward. If an object record is already saved with now unavailable values, Vault does not update that record. Additionally, Vault does not apply reference constraints to object records created in migration mode. However, if a user later edits a controlled or controlling field in the record, the user will need to select a valid option.
When a document reference field links to the latest version and has the status__v = STEADYSTATE() reference constraint, up-versioning the referenced document will violate the constraint.
For a document reference field bound to the latest steady state version, a document is selectable if any previous steady state version matches the reference constraint criteria. However, after saving, the field displays the document’s latest steady state version even if that version does not match the criteria. For example, if a document has a past steady state version of 1.0 and latest steady state version of 1.2, the document is selectable for a constraint of minor_version_number__v = 0. The saved field will then display the latest steady state version, 1.2.
Note: Use caution when editing pre-configured constraints on standard reference fields. Vault does not display a warning message when editing default constraints and you may inadvertently break existing configurations.
Example: Static Reference Constraint on Relationship Records
RIM Vaults use an object called Controlled Vocabularies to represent various entities, including Species, Application Types, and Submission Types. One of the fields on the object is Type, which identifies whether the record is a species, application type, etc. Since these records all share similar fields (Name, Abbreviation, Health Authority Code, Health Authority Source, etc.), using the single object is more efficient. However, filtering records by Type still matters. Organizations don’t want users to accidentally associate a Submission Type record with an application. To facilitate this, an Admin can set up filters on actual object reference fields. The Application object includes an object field called Application Type, pointing to the Controlled Vocabularies object. That field is filtered to only show records where the Type value is Application Type.
controlled_vocabulary_type__rim = 'application_type__rim'
Example: Static Reference Constraint on Parent Relationship Records
Promomats vaults provide the Product object to maintain records of various products used for promotional and marketing purposes. One of the fields in the Product object is Therapeutic Area, which identifies whether the record belongs to a specific area of study such as oncology, neurology, pediatrics, etc. The custom Marketing Campaign object is a related child object of Product. When users create a new Marketing Campaign, an organization may want to only allow creating marketing campaigns around products focused specifically on neurology. To facilitate this, an Admin can set up filters on the Product parent field within Marketing Campaign to only show records where the Therapeutic Area value is Neurology.
therapeutic_area__c = 'neurology__c'
Example: Static Reference Constraint on Document State and Type
In some PromoMats Vaults, the Product object contains a Logo document reference field that points to the document with the product logo. To ensure users can only select product logos when editing the Logo field, an Admin could create a Logo File document type and add a filter to the Logo field that excludes all other document types. Additionally, setting the Document Version Reference to Latest version may include newer versions of the logo that aren’t yet approved for public use. To prevent users selecting unapproved versions of the logo, an Admin could set up filters on the Logo field to ensure that users can only select from documents in the Steady state.
type__v = 'Logo File' AND status__v = STEADYSTATE()
Example: Dynamic Reference Constraint on Relationship Records
In some Promomats Vaults, the Marketing Campaign object may reference the Country and Region fields to identify where the campaign will take place. To create a more relevant list of countries for a user to choose from, an Admin can apply a dynamic constraint on the Country field so the list of records are constrained by region the user selects. For example, if a user selects the Europe region, the Country field only displays countries in the European region. See details about dynamic reference constraint queries.
region__v = {{this.region__v}}
Example: Dynamic Reference Constraint on Many-to-Many Relationships
Some Promomats Vaults use the Survey object to maintain records of survey data used to gather information. This object may reference the Product and Therapeutic Area objects, which identifies the information the survey data was collected for. If a relational object is used to join the references between Product and Therapeutic Area, an Admin can apply a dynamic reference constraint on the Product field in the Survey object so the list of product records are constrained by the selected Therapeutic Area. This is especially useful for objects with various records with several references. See details about dynamic reference constraint queries.
therapeutic_area__c = {{this.therapeutic_area__c}}
Example: Dynamic Reference Constraint on Documents
In the static example of a Logo field, users would still see Steady state Logo File type documents for products other than the one being configured. To avoid this, an Admin could use a dynamic filter to exclude documents where the Product field value does not match the current Product object record. See details about dynamic reference constraint queries.
type__v = 'Logo' AND status__v = STEADYSTATE() AND product__v = {{this.id}}
If a document reference field uses the Latest steady state version, you will get a warning when you use the VQL query status__v. The document reference field will filter to display only documents with a steady state (Approved, Approved for Use, etc.). Therefore, using a constraint on the status will return no results.
The reference constraint may behave unexpectedly if all of the following conditions are met:
- The document has more than one steady state version
- These steady state versions have different document metadata
- The constraint is based on this document metadata
Users may be able to select an invalid document if a reference constraint is used when all conditions occur at once. This problem can happen because when a user selects a document in this situation, the latest steady state may not meet the constraint’s criteria while an older steady state does meet the criteria.