With Vault Objects, you can configure various relationships, including parent-child (hierarchical) and reference (non-hierarchical) relationships. Reference relationships can point to another object or back to the same object (self-referencing). Parent-child relationships are typically one-to-one or one-to-many, but you can create a many-to-many relationship by using a third object.
Standard, system-managed objects can only be in reference relationships or in parent-child relationships as parents. They cannot be a child object in a relationship.
Parent-Child Relationships
Parent-child relationships are hierarchical and allow you to create a structure of dependent object records. Records for the child object do not need to be unique because they exist only within the context of a parent record.
Example: PromoMats
The custom Marketing Campaign object could be in a parent-child relationship with Product. A single product can have multiple campaigns, but each marketing campaign belongs to a single product. Marketing campaigns do not need to be unique, except where they share the same product. Marketing campaigns called Product Launch exist on multiple products.
Example: eTMF
The standard Study Site object is in a parent-child relationship with Study Country, while the Study Country object is the child of Study. Each site belongs to a single country. Each country record belongs to a single study. Study countries do not need to be unique, except where they share the same study: United States is a Study Country record that exists for every study. Likewise, there can be multiple identical sites, as long as they belong to different Study Country and Study records.
Reference Relationships
A reference relationship lets you link metadata from one object to another, without utilizing dependency behaviors of a parent-child relationship. Because these relationships are non-dependent, records in the related object must be unique.
Example: PromoMats
The Marketing Campaign object has a reference relationship to the Agency object. The agencies exist outside the context of a single marketing campaign, and one agency may relate to many campaigns. You could not create duplicate agencies because each agency is not a child of a marketing campaign, but an independent entity.
Example: eTMF
The Study Site object has a referring relationship to the Location object. While individual sites exist within a single country and study, locations exist independently. Locations themselves must be unique because they do not have their parent as an additional attribute to define them as unique.
Self-Referencing Relationships
Self-referencing relationships allow you to create a hierarchy of object records that share identical fields. Self-referencing relationships are supported for all objects. An object record cannot refer to itself.
Example: PromoMats
The custom Region object has records that represent countries, as well as records that represent larger geographical areas. France and Germany reference the Europe region as their parent, while Japan and Taiwan reference the Asia-Pac region as their parent. Rather than creating two separate objects in a parent-child relationship, this example uses a single object because the fields on these records are so similar.
Example: eTMF
The standard Milestone object works with self-referencing relationships. A site close milestone has a country close milestone as its parent, while that country close milestone has the highest-level study close as its parent. Milestones themselves have the same set of object fields (Planned Start Date, Planned Finish Date, etc.), so these are set up as a single object with self-referencing relationships, rather than multiple objects in parent-child relationships.
Many-to-Many Relationships
A many-to-many relationship lets you create dependencies between multiple records on two different objects, using a third, relational object with two parent objects. This relational object can be simple, meaning it only has the standard fields (Label, etc.) and parent object fields. Relational objects can also be complex, meaning they have additional custom fields. This way of relating objects is sometimes called “simple joins” and “complex joins”.
For the relational object to be active, both parent objects must also be active. When you change the status of one parent object to Inactive, Vault automatically cascades that status change to the relational object. If you change the status of a parent object to Active, Vault only cascades that change to the relational object if the other parent is already active.
When creating document fields for these relational objects, you select one parent object as the controlling object, making the related document fields behave as they would for any other parent-child relationship.
Example: Simple Relationship
A custom relationship could exist between the standard objects Product and Country. This relationship would link each product to specific countries where it is available or approved for sale. To create the relationship, you’d set up a new custom object, Approved Country, with parent object fields for Product and Country. Object records would include:
| Label | Product | Country |
| Spain | Nyaxa | Spain |
| Italy | Nyaxa | Italy |
| Italy | CholeCap | Italy |
| United States | CholeCap | United States |
The labels and names for Approved Country object records can be non-unique, as long as they are unique for the product-country combination.
The related document field would be set up with Product as the controlling object, so that the Approved Country field only displays countries that are related to the selected product. If the document is for Nyaxa, only Spain, Italy appear in Approved Country.
To create a simple many-to-many relationship:
- Create a new object to represent the relationship.
- Open the object’s Fields tab.
- Click Create.
- Select the Parent Object field type.
- Enter a field label. Generally, this label will match the object’s label, but this is not required.
- Select the Object you want to use as a parent. This is one of the two objects you want to create a relationship between.
- Optional: Select additional options as needed. See details below.
- Click Save.
- Create a second Parent Object-type field on the relational object.
The two objects you used for the Parent Object-type fields are now in a simple relationship. You can reference your new relational object on documents and objects in an object reference field. If you have a related object section referencing one of the parent objects, Vault displays an Add button to relate records. Vault then automatically creates the simple join object record.
Example: Complex Relationship
Much like the example above, you could set up a complex relationship between Product and Country. This relationship would still link each product to specific countries where it is available or approved for sale. However, the relational object holds additional metadata, like Approval Status and Local Name. You can add lookup or object reference fields to your relational object to collect that metadata.
| Label | Local Name | Approval Status | Product | Country |
| Spain | Nyaxá | Pending | Nyaxa | Spain |
| Italy | Nyaxa | Approved | Nyaxa | Italy |
| Italy | ColeCap | Approved | CholeCap | Italy |
| United States | CholeCap | Approved | CholeCap | United States |
The related document field would work as it does for the simple relationship, but users would have additional options to filter on (Approval Status, Local Name) when selecting the Approved Country or looking for documents.
Defining Uniqueness in Relationship Objects
Depending on whether a relational object represents a complex or simple relationship, Vault defines and enforces uniqueness differently:
- Simple: These records must be unique. Vault defines uniqueness using the parent object records only. For example, two relational object records cannot exist with the same Product and Country parents.
- Complex: These relationships require users to enter a Name for each relationship record. By default the relationship name must be unique for each separate combination of parents. Admins can configure the complex relationship object to use alternate uniqueness constraints. For example, by unchecking the Values must be unique flag on the Name field and checking the same flag on the Approval Status field, the Admin could force records to be unique for each combination of parents and Approved Status.
How to View Relationships
In Admin > Configuration > Objects, existing relationship structures are visible from the Relationships tab of the object details page.
This page displays relationships as either “inbound” or “outbound.”
- Inbound relationships: In a parent-child relationship, the object you’re viewing is the parent. In a reference relationship, another object references the object you’re viewing.
- Outbound relationships: In a parent-child relationship, the object you’re viewing is the child. In a reference relationship, the object you’re viewing references another object.
Self-referencing relationships appear as both inbound and outbound.
The relationship type Join Object indicates that the object you’re viewing is one of the parent objects in a many-to-many relationship.
How to Create Reference & Parent-Child Relationships
When creating an object relationship, you must start from the child or referring object and set up the relationship as a field within that object. In the campaign example, you would start from the Marketing Campaign object for both the parent-child relationship and the reference relationship. Both Product and Agency would be fields within the Marketing Campaign object. In the many-to-many example, you’d start from the Approved Country object and create two parent object fields.
To create a new object relationship:
- From Admin > Configuration > Objects, open the child or referring object and click into the Fields tab.
- Click Create.
- For the field type, select Object to create a reference relationship or Parent Object to create a parent-child relationship.
- Enter a field label. Generally, this label will match the object’s label, but this is not required.
- Use the Status selector to make the field (and relationship) active or inactive. You cannot make this inactive for the Parent Object field type.
- Select an Object.
- For child objects only: Select a Controlling Field. This field can be set to any Object- or Parent Object-type fields that point to a parent object of the object chosen in the previous step.
- Optional: Select the User must always enter a value (required) option to make this field required for the Admin user creating object records. For the Parent Object field type, this setting is always on.
- Optional: Select the Display in default lists and hovercards checkbox to have the field appear in the Admin area object record list view, the pop-up object details in the document fields panel, and the object lookup dialog.
- Optional: Enter custom Help Content for the Admin user creating object records.
- Click Save.
Some field attributes, like deletion rules, can only be modified once you create and save the object field. To edit these attributes:
- From the Fields tab, click into the new field and click Edit.
- Optional: Modify the Inbound Relationship Label. Vault uses this value as the tab label within the parent or referenced object’s details.
- Optional: Modify the Inbound Relationship Name. API developers can use this relationship in VQL queries.
- Optional: Modify the Deletion Rule. This rule determines the behavior for child or referring object records if an Admin deletes the parent/referenced object record.
- Optional: Select the checkbox for Allow hierarchical copy. This setting allows users who are copying a record on the parent object to also copy child records for this object.
- Optional: Enter a Criteria VQL expression to define reference constraints.
How to Add Lookup Fields
A Lookup field will propagate field values from a parent or referenced object to a child or referring object.
To create a new lookup field:
- From Admin > Configuration > Objects, open the child or referring object and click into the Fields tab.
- Click Create.
- For the field type, select Lookup.
- Enter a field label. Often, this label will match the label for the field it pulls data from, but this is not required.
- In Lookup Relationship, select the outbound relationship that you’ll utilize for this field. These are generally named for the object that they reference.
- In Lookup Source Field, select a field on the referenced/parent object. Vault displays this field’s value in the lookup field.
- Optional: Select the Display in default lists and hovercards checkbox to have the field appear in the object record list view, the pop-up object details in the document fields panel, and the object lookup dialog.
- Optional: Enter custom Help Content for the Admin creating object records.
- Click Save.
- If both objects already have records, a dialog opens to notify you that these records will automatically update. This process can take a while, but you’ll receive a notification when it is complete.
Document Reference Fields
When you configure and use document reference fields, Vault creates relationships between object records and individual documents or individual document versions. These relationships appear in the object configuration, and you can set up object page layouts to show documents in these relationships. However, the relationships do not appear in the document details, for example, in the Doc Info page or in a document report.
Limits
The following limits apply to object relationships:
- Up to 50 inbound relationships to documents.
- Up to 50 custom inbound relationships for each object.
- Up to 30 custom outbound relationships for each object.
- Up to 80 custom inbound relationships for the User object.
- Parent-child relationships support up to three levels of hierarchy.