# 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. When a parent-child relationship exists, if the Status of the parent is made _Inactive_, the child records automatically become _Inactive_ as well.


### 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.


<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: <a href="/en/lr/811001/">Action Triggers</a>, <a href="/en/lr/15057/#roll-up-fields">Roll-up field calculations</a>, and <a href="/en/lr/46866/">Validation Rules</a> are disabled when <em>Status</em> updates cascade from the parent record to child records. This cascade operation can affect up to 1,500 child records.</p>
    </div>
  </div>
</div>



## Reference Relationships {#object-reference}

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 {#many_to_many}

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 {#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_.

### How to Create Simple Relationships {#create-simple-relationship}

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. See [details][0] below.
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 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 {#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 | CholeCap | 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.

### How to Create Complex Relationships {#create-complex-relationship}

To create a complex many-to-many relationship:

1. Navigate to a simple join object.
2. Open the object's **Fields** tab.
3. Click **Create**.
4. Create a new <a href="/en/lr/15057/#how_to_add_object_fields">custom field</a> on the object.
5. Complete required and optional fields as necessary.
6. Click **Save**.

An **Affected Layouts** dialog displays alerting you that by adding a new field, the parent objects will now enter a complex relationship. The **Affected Layouts** dialog provides the option to update all referencing related object sections to use <a href="/en/lr/18769/#display-complex-as-simple">**Display as Simple**</a> or to continue to display them as complex join sections. In addition, you can download a CSV file containing all referencing related object sections.

If you delete the last custom field on the complex join object, the relationship returns to simple. A **Deleting "Role"** dialog displays explaining that the deletion removes field level security on the object. In addition, if the complex join object is referenced in a related object section, the **Deleting Role** dialog provides a downloadable CSV file containing all referencing related object sections.

### Defining Uniqueness in Relationship Objects {#define-uniqueness-relationships-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 {#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 {#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. You cannot make this inactive for the **Parent Object** field type.
6. Select an **Object**.
7. <a id="field_options"></a>For child objects only: Select a <a href="/en/lr/32567/">**Controlling Field**</a>. 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.
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, the pop-up object details in the document fields panel, and the object lookup dialog.
10. Optional: Enter custom **Help Content** for the Admin user creating object records.
11. Click **Save**.

Some field attributes, like deletion rules, can only be modified once you create and save the object field. To edit these attributes:

1. From the **Fields** tab, click into the new field and click **Edit**.
2. Optional: Modify the **Inbound Relationship Label**. Vault uses this value as the tab label within the parent or referenced object's details.
3. Optional: Modify the **Inbound Relationship Name**. Vault API developers can use this relationship in VQL queries.
4. Optional: Modify the **Deletion Rule**. This rule determines the behavior for child or referring object records if an Admin <a href="/en/lr/15057/#relationships_deletion">deletes the parent/referenced object record</a>.
5. Optional: Select the checkbox for **Allow hierarchical copy**. This setting allows users who are copying a record on the parent object to also <a href="/en/lr/32218/">copy child records for this object</a>.
6. Optional: Enter a Criteria VQL expression to define <a href="/en/lr/75340/">reference constraints</a>.

## How to Add Lookup Fields {#How_to_Add_Lookup_Fields}

A <a href="/en/lr/34072/">_Lookup_ field</a> 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, the pop-up object details in the document fields panel, 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.

## Document Reference Fields

When you configure and use <a href="/en/lr/35045/">document reference fields</a>, 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 {#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.

[0]: #field_options
[1]: #define-uniqueness-relationships-objects
[2]: #simple-relationship
[3]: #complex-relationship