# Object Relationships

{% hint style="success" %}
**Audience:** Admins, Developers, Solution Architects

**Purpose:** Explains how <code class="expression">space.vars.object</code> relationships work in <code class="expression">space.vars.Kizen\_company\_name</code> and helps admins and solution architects design connected data models that improve usability, visibility, and access control.
{% endhint %}

## Overview

<code class="expression">space.vars.object</code> Relationships let you connect records across <code class="expression">space.vars.objects</code> so users can navigate related data, share context (such as timeline activity), and control access through team associations. In <code class="expression">space.vars.Kizen\_company\_name</code>, relationships are configured at the <code class="expression">space.vars.object</code> level through <code class="expression">space.vars.object</code> Settings and are represented as relationship fields on <code class="expression">space.vars.entities</code>.

During <code class="expression">space.vars.object</code> configuration, Related <code class="expression">space.vars.objects</code> appears as Step 2. If Workflows are enabled, it becomes Step 3.

1. General Settings
2. <mark style="color:$success;">**Related Objects**</mark>
3. Customize Fields
4. Customize Layout
5. Permissions

***

## What's an Object Relationship

An <code class="expression">space.vars.object</code> relationship defines how <code class="expression">space.vars.entities</code> connect to one another across different <code class="expression">space.vars.objects</code> or on the same <code class="expression">space.vars.object</code> depending on configuration. Relationships make your data navigable, meaningful, and usable in real workflows rather than isolated lists of <code class="expression">space.vars.entities</code>.

When you create a relationship, <code class="expression">space.vars.Kizen\_company\_name</code> adds a relationship field to each <code class="expression">space.vars.object</code> so users can link related <code class="expression">space.vars.entities</code> together. For example, a Location can be linked to a Company, a Deal can be linked to a primary Contact, or an Asset can be linked to a Location.

By default, relationships are created in both directions. This means each side gets its own field (for example, *Related Company* on Locations and *Company Locations* on Companies), allowing users to move naturally between related <code class="expression">space.vars.entities</code>. You can choose to hide the reverse field if it is not useful for your use case.

***

## Team Associations

Team Associations determine how access to <code class="expression">space.vars.entities</code> is granted when relationships exist between <code class="expression">space.vars.objects</code>. In other words, this setting controls whether users can see and work with a <code class="expression">space.vars.entity</code> because they are directly involved with it, because they are involved with a related <code class="expression">space.vars.entity</code>, or both. Team Associations are configured using the **Where does this object get its team associations?** selector.

If this setting is misconfigured, users may run into situations where they can create <code class="expression">space.vars.entities</code> but cannot see or access them later. Taking the time to choose the right option here helps prevent confusion and reduces the need for manual permission management.

{% hint style="warning" %}
**Caution:** Misconfiguration in this section is often a cause of <code class="expression">space.vars.object</code> visibility issues. If you are unable to see an <code class="expression">space.vars.object</code> or its <code class="expression">space.vars.entities</code>, please ensure this configuration is correct.
{% endhint %}

### Direct

Access is based only on a user’s direct connection to the <code class="expression">space.vars.entity</code>. For example, a user can access the <code class="expression">space.vars.entity</code> if they:

* Own the <code class="expression">space.vars.entity</code>
* Are assigned to the <code class="expression">space.vars.object</code> or <code class="expression">space.vars.entity</code>
* Are explicitly added to a Team Association for the <code class="expression">space.vars.object</code> or <code class="expression">space.vars.entity</code>&#x20;

Use this when the <code class="expression">space.vars.object</code> should stand on its own and should not inherit access from other <code class="expression">space.vars.objects</code>. This is the most restrictive but safest option.

### Related

Access is inherited from related <code class="expression">space.vars.entities</code>. For example, if a user has access to a Location, they automatically gain access to all related Assets, even if they are not directly assigned to each Asset.

Use this option when the <code class="expression">space.vars.object</code> behaves like a “child” <code class="expression">space.vars.object</code> and should consistently follow the access rules of its parent.

{% hint style="warning" %}
**Caution:** Broad relationships can introduce unintended access. If users are granted access to a highly shared parent <code class="expression">space.vars.entity</code>, they may automatically gain access to many related <code class="expression">space.vars.entities</code>. For example, if all Assets are linked to a shared Location like “Headquarters,” giving a user access to that Location would also grant access to every Asset stored there.
{% endhint %}

### Direct and Related

Access can come from either source. Users can access the <code class="expression">space.vars.entity</code> if they are directly associated with it **or** if they are associated with a related <code class="expression">space.vars.entity</code>.

Use this when you want maximum flexibility and want users to be able to work naturally across related data without constantly managing assignments. This is the most permissive option and may require more governance for larger teams.

***

## Primary vs Additional Relationships

<code class="expression">space.vars.Kizen\_company\_name</code> provides two ways to relate <code class="expression">space.vars.entities</code>, based on whether users need to select one related <code class="expression">space.vars.entity</code> or multiple related <code class="expression">space.vars.entities</code>.

### Primary Relationships

Use a Primary relationship when each <code class="expression">space.vars.entity</code> should be connected to only one main related <code class="expression">space.vars.entity</code>.

Best for:

* A deal with one primary company
* A ticket with one requester
* A location with one owning company

Each <code class="expression">space.vars.entity</code> gets a single-select field, so users can choose only one related <code class="expression">space.vars.entity</code>. This improves clarity and consistency across the platform. By enforcing a single primary relationship, reporting, automation, and filtering behave predictably because there is always one authoritative related <code class="expression">space.vars.entity</code> rather than multiple competing values.

### Additional Relationships

Use an Additional relationship when each <code class="expression">space.vars.entity</code> may need to be connected to multiple related <code class="expression">space.vars.entities</code>.

Best for:

* A deal with multiple stakeholders
* A project with several contributors
* A location with many assets

Each <code class="expression">space.vars.entity</code> gets a multi-select field, allowing users to link several related <code class="expression">space.vars.entities</code>.

### When To Use Both

Many real-world processes need both a clear “main” relationship and supporting relationships. In these cases, use both types together.

Example: Deals and Contacts

* Primary relationship: *Primary Contact* (single-select)
* Additional relationship: *Additional Contacts* (multi-select)

This keeps the most important relationship clear, while still allowing flexibility.

***

## Relationship Types

When you create a relationship between two <code class="expression">space.vars.objects</code>, <code class="expression">space.vars.Kizen\_company\_name</code> asks you to choose a relationship type. This setting simply describes how many <code class="expression">space.vars.entities</code> can be connected on each side of the relationship.

You will see options like:

* One-to-One
* One-to-Many
* Many-to-One
* Many-to-Many (through Additional relationships)

Rather than thinking in database theory, it helps to read the setting like this: “From the <code class="expression">space.vars.entity</code> I’m editing, how many of the other related <code class="expression">space.vars.entities</code> should I be able to connect?”

<details>

<summary>Examples</summary>

#### Example 1: Locations and Companies

If you configure: **Locations → Companies = Many-to-One**

That means:

* A single Location can be connected to one Company
* A Company can be connected to many Locations

In the UI, this typically results in:

* A single-select field on Location (for Company)
* A list of related Locations on the Company record

#### Example 2: Locations and IT Assets

If you configure: **Locations → IT Assets = One-to-Many**

That means:

* One Location can be connected to many IT Assets
* Each IT Asset links back to one Location

In the UI, this typically results in:

* A multi-select or related list of Assets on the Location
* A single Location field on each Asset

</details>

With <code class="expression">space.vars.object</code> relationships, you are not choosing a technical structure. You are choosing how users will connect <code class="expression">space.vars.entities</code> in the interface:

* Choose **“one”** when users should only pick one related <code class="expression">space.vars.entity</code>
* Choose **“many”** when users should be able to pick multiple related <code class="expression">space.vars.entities</code>

***

## Relationship Name vs Reverse Relationship Name

When you create a relationship, <code class="expression">space.vars.Kizen\_company\_name</code> asks you to name the fields that users will see on both sides of the connection.

* **Relationship Name**: label for the field that appears on the <code class="expression">space.vars.object</code> you are currently editing. This is the field users will use to link a <code class="expression">space.vars.entity</code> to another <code class="expression">space.vars.entity</code>. For example, on a Location <code class="expression">space.vars.entity</code>, this might be labeled **Related Company**.
* **Reverse Relationship Name**: label for the field that appears on the related <code class="expression">space.vars.object</code>. This allows users to see and navigate back to related <code class="expression">space.vars.entities</code>. For example, on a Company record, this might appear as **Company Locations**.

Choosing clear, natural names here matters. These labels appear throughout the interface, including on <code class="expression">space.vars.entity</code> detail pages and when users search for and select related <code class="expression">space.vars.entities</code>, so they should match the language your team already uses.

***

## Sharing & Options

Each relationship includes options that control whether certain information appears across related <code class="expression">space.vars.entities</code>. These settings help you decide how much context users should see when moving between <code class="expression">space.vars.entities</code>.

### Timeline Sharing

Timeline sharing determines whether activity from one <code class="expression">space.vars.entity</code> appears on another <code class="expression">space.vars.entity</code>’s Timeline.

You can control this in two directions:

* **Share Timeline To Related:** Activity from this <code class="expression">space.vars.entity</code> appears on the related <code class="expression">space.vars.entity</code>s Timeline.
* **Share Timeline From Related:** Activity from the related <code class="expression">space.vars.entity</code> appears on this <code class="expression">space.vars.entity</code>’s Timeline.

Enable timeline sharing when you want users to be able to see meaningful activity without having to jump between related <code class="expression">space.vars.entities</code>. For example, it can be helpful to surface deal activity directly on a Company record, or to allow a Project to reflect what is happening across its related Tasks.

You may want to leave Timeline sharing turned off when it begins to create unnecessary noise. This often occurs when a <code class="expression">space.vars.entity</code> is related to many other <code class="expression">space.vars.entities</code>, each generating frequent updates, which can make the Timeline harder to scan and use effectively. As an alternative to disabling Timeline sharing entirely, Object Type filters can be used to temporarily hide updates from specific related <code class="expression">space.vars.objects</code> while preserving visibility into others.

### Lead Source Sharing

Lead Source sharing controls whether lead source information passes between related <code class="expression">space.vars.entities</code>.

You can enable this in either direction:

* **Share Lead Sources To Related:** Lead source values on this <code class="expression">space.vars.entity</code> are applied to the related <code class="expression">space.vars.entity</code>.
* **Share Lead Sources From Related:** Lead source values from the related <code class="expression">space.vars.entity</code> are applied to this <code class="expression">space.vars.entity</code>.

Enable lead source sharing when you want attribution to stay consistent across related <code class="expression">space.vars.entities</code>. For example, if a Contact, Deal, and Company are all part of the same customer journey, sharing the lead source ensures they each reflect the same original origin without requiring users to manually keep those fields in sync.

### Suppress Related Field

**Suppress Related Field?** hides the relationship field on the related <code class="expression">space.vars.object</code> and prevents updates from appearing in the Timeline.&#x20;

{% hint style="danger" %}
**Warning:** Suppression is **not reversible**.
{% endhint %}

Use this when:

* The reverse relationship would confuse users (example: reference data like States).
* You do not want users navigating “backwards” from the related <code class="expression">space.vars.object</code>.
* You want to reduce clutter in layouts and timelines.

***

## What Gets Created When You Add A Relationship

When you save a relationship between two <code class="expression">space.vars.objects</code>, <code class="expression">space.vars.Kizen\_company\_name</code> automatically sets up the fields users need to link <code class="expression">space.vars.entities</code> together. You do not need to manually create anything else.

First, <code class="expression">space.vars.Kizen\_company\_name</code> adds a relationship field to the <code class="expression">space.vars.object</code> you are editing, using the **Relationship Nam**e you provided. This is the field users will use to connect <code class="expression">space.vars.entities</code> (for example, selecting a Company on a Location <code class="expression">space.vars.entity</code>).

At the same time, <code class="expression">space.vars.Kizen\_company\_name</code> creates a corresponding field on the other <code class="expression">space.vars.object</code> using the **Reverse Relationship Name**. This allows users to see and navigate the relationship from the other side as well (for example, viewing all related Locations on a Company <code class="expression">space.vars.entity</code>).

The type of field users see depends on how the relationship was configured:

* If the relationship allows only one related <code class="expression">space.vars.entity</code>, the field appears as a **single-select**.
* If the relationship allows multiple related <code class="expression">space.vars.entities</code>, the field appears as a **multi-select**.

Once the relationship is created, both <code class="expression">space.vars.objects</code> immediately gain new fields that make it easy to connect and navigate related <code class="expression">space.vars.entities</code>.

***

## Additional Information

<details>

<summary>Best Practices for Relationship Design</summary>

### Best Practices for Relationship Design

#### 1. Start with the user workflow, not the database terms

Ask:

* “On this <code class="expression">space.vars.entity</code>, do users need to pick one related <code class="expression">space.vars.entity</code> or many?”
* “Which direction will users navigate most often?”
* “Should timeline activity roll up, roll down, or stay isolated?”

#### 2. Use Primary for the “main” link, Additional for “others”

This matches <code class="expression">space.vars.Kizen\_company\_name</code>’s guidance for common CRM patterns (Company ↔ Contacts, Deal ↔ Contacts).

#### 3. Be intentional about timeline sharing

* Turn it on when you want “context at a glance.”
* Keep it off when it creates noise, especially when many child <code class="expression">space.vars.entities</code> will generate frequent updates.

#### 4. Use Suppress Related Field sparingly

Because it is not reversible, treat it like a structural decision, not a cosmetic one.

</details>

<details>

<summary>Common Mistakes to Avoid</summary>

### Common Mistakes to Avoid

**Can’t find Records you just created?**\
Check **Team Associations**. Try **Direct and Related**.

**The relationship feels backwards?**\
You likely picked the wrong direction. Recheck which side should allow **one** vs **many**.

**Timelines look noisy?**\
Turn off timeline sharing from high-volume child <code class="expression">space.vars.entities</code>.

**Labels feel confusing?**\
Rename fields to match real language (e.g., *Primary Company*, not *Related Record*).

**Thinking about suppressing the reverse field?**\
Only do this if you are certain users will never need to navigate from the other side.

</details>

***

## What's Next

Continue to the [Object Data Model ](/docs/concepts/objects/object-data-model.md)topic to see how relationships fit into the overall structure of your data.

You can also revisit [Object Core Concepts](/docs/concepts/objects/object-core-concepts.md) for foundational terminology or review the [Records](/docs/concepts/objects/records.md) topic to understand how users create and work with data in the platform.

<details>

<summary>Related Topics</summary>

* [Object Core Concepts](/docs/concepts/objects/object-core-concepts.md)
* [Object Data Model](/docs/concepts/objects/object-data-model.md)
* [Object Layout Customization](/docs/concepts/objects/object-configuration/object-layout-customization.md)
* [Object Permissions](/docs/concepts/objects/object-configuration/object-permissions.md)
* [Object APIs](/docs/concepts/objects/object-apis.md)

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.kizen.com/docs/concepts/objects/object-configuration/object-relationships.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.