About Object Relationships

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 Parent-Child Relationship

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 Reference Relationship

The Product object has a reference relationship to the Study object. The products exist outside the context of a single study, and one product may relate to many studies. You could not create duplicate products because each study is not a child of a product, but an independent entity.

Self-Referencing Relationships

Self-referencing relationships allow you to create a hierarchy of object records where the parent and child share identical object fields. Individual object records in a self-referencing relationship must be unique. You cannot create a “circular” relationship.

Example Self-Referencing Relationship

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.

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.

Many-to-Many Relationship Between Campaign and Keyword Objects

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.

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

Note that the labels and names for Approved Country object records can be non-unique, as long as they are unique for the product-country combination.

To create a simple many-to-many relationship:

  1. Create a new object to represent the relationship.
  2. Open the object’s Fields tab.
  3. Click Create.
  4. Select the Parent Object field type.
  5. Enter a field label. Generally, this label will match the object’s label, but this is not required.
  6. Select the Object you want to use as a parent. This is one of the two objects you want to create a relationship between.
  7. Optional: Select additional options as needed. 
  8. Click Save.
  9. 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 objects in an object reference field. Note that 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 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.

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.

Note that 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 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:

  1. From Admin > Configuration > Objects, open the child or referring object and click into the Fields tab.
  2. Click Create.
  3. For the field type, select Object to create a reference relationship or Parent Object to create a parent-child relationship.
  4. Enter a field label. Generally, this label will match the object’s label, but this is not required.
  5. Use the Status selector to make the field (and relationship) active or inactive. Note that you cannot make this inactive for the Parent Object field type.
  6. Select an Object.
    Create a New Reference Relationship

  7. Optional: Select a Controlling Field.
  8. 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.
  9. Optional: Select the Display in default lists and hovercards checkbox to have the field appear in the Admin area object record list view and the object lookup dialog.
  10. Optional: Enter custom Help Content for the Admin user creating object records.
  11. Click Save. Note that some attributes, like deletion rules, can only be modified once the object field is saved.
  12. From the Fields tab, click into the new field and click Edit.
      Available Object Field Options

  13. Optional: Modify the Inbound Relationship Label. Vault uses this value as the tab label within the parent or referenced object’s details.
  14. Optional: Modify the Inbound Relationship Name. API developers can use this relationship in VQL queries.
  15. 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.
  16. 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.

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:

  1. From Admin > Configuration > Objects, open the child or referring object and click into the Fields tab.
  2. Click Create.
  3. For the field type, select Lookup.
  4. Enter a field label. Often, this label will match the label for the field it pulls data from, but this is not required.
  5. In Lookup Relationship, select the outbound relationship that you’ll utilize for this field. These are generally named for the object that they reference.
  6. In Lookup Source Field, select a field on the referenced/parent object. Vault displays this field’s value in the lookup field.
  7. Optional: Select the Display in default lists and hovercards checkbox to have the field appear in the object record list view and the object lookup dialog.
  8. Optional: Enter custom Help Content for the Admin creating object records.
  9. Click Save.
  10. 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.

Constraining Related Object Records

When you create a field that results in an 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 object 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. 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.  

A Dynamically Constrained Field is Dependant on the Controlling Field

You can only set up dynamic reference constraints using a VQL query in advanced mode. 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 Object Records

To set up a constraint:

  1. Open an existing object reference or parent field in edit mode. You cannot filter when initially creating the field.
  2. Scroll down to the  Constrain Records in Referenced Object section.
  3. Select a field on the object you’re referencing, a condition, and an expected value.
  4. Optional: Click the plus + icon to add additional conditions.
  5. Optional: Click Advanced to use a VQL query to define the conditions. A VQL query allows you more options than the basic mode, particularly in how multiple conditions interact. 
  6. Optional: Click Preview to see how field selection will look once your filter rule is in place.
  7.  Click Save.


  • Filtering is only available for custom object reference and parent fields on objects. 
  • Vault only applies filters going forward. If an object record is already saved with now unavailable values, Vault does not update that record. However, if a user edits the record later, the user will need to select a valid option.
  • When users create reports, the same filters applied here are automatically applied to the reports, but users may remove them.


By default, you can configure up to 20 object relationships for each object. If your organization needs higher limits, please contact Veeva Support.