# Relationship Graph

## Overview

The Avonni Relationship Graph component provides a powerful and intuitive way to visualize connections and hierarchical relationships between Salesforce records directly on your Lightning Pages. Go beyond simple lists and see how your data truly connects.

### Use Cases

* Visualizing Account Hierarchies with related Contacts and Opportunities.
* Displaying Organizational Charts (e.g., User hierarchies based on the `ManagerId` field).
* Mapping Product Structures (e.g., Product Bundles and their components).
* Showing Case Dependencies or related Knowledge Articles.
* Visualizing complex project structures with parent/child tasks.

***

## Configuration

Select the Relationship Graph component on the canvas to access its properties in the Properties Panel. Configuration involves connecting to data, mapping how data is displayed, and customizing its behavior.

### Connecting to Hierarchical Data (Data Source)

The Relationship Graph is designed to work with hierarchical data. The primary way to provide this data is using the **Avonni Nested Query Data Source**.

{% stepper %}
{% step %}

### **Select Data Source**

In the Properties Panel, set the **Data Source** property to `Avonni Nested Query Data Source`.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F8lMf8CXyHnoTrWdhb53N%2F2025-04-23_21-03-49.png?alt=media&#x26;token=04964073-1678-4f4b-82c6-5be188472ee2" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### **Configure Nested Query**

Click **Create Query** or **Edit Query**.

* **Parent Object Query:** Define the query for your top-level records (e.g., Object: `Account`). Add filters if needed.
* **Add Child Object(s):** Within the Nested Query builder, add child relationships.
  * Select the Child Object (e.g., `Contact`).
  * Specify the **Relationship Field** on the *child* object that links it to the *parent* (e.g., `AccountId` on Contact).

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FUPiea5KW1KQbS8Wlrj2m%2F2025-04-23_21-05-23.png?alt=media&#x26;token=2182ff19-dfcb-4b2d-9213-13ed983e892d" alt=""><figcaption></figcaption></figure>

* **Add Further Nesting (Optional):** You can potentially add another level (e.g., add `Case` as a child of `Contact`, using the `ContactId` relationship field).
* **Multiple Parent Objects (Optional):** Depending on the component's capability, you might be able to add *multiple independent parent queries* if you want to display different starting hierarchies in the same graph.
* **Save Query:** Save your Nested Query definition.
  {% endstep %}
  {% endstepper %}

### Mapping Data to Graph Nodes (Data Mappings)

This crucial section defines *how* the data from each level of your Nested Query is displayed visually on the graph nodes.

{% stepper %}
{% step %}

### **Access Data Mappings**

In the Properties Panel, find the **Data Mappings** section.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F2bmzPGdxeOhafJKFLtDW%2F2025-04-23_21-07-47.png?alt=media&#x26;token=0dfff9dd-1056-4a2b-a4a7-b3365d1b533f" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### **Select Item Level**

You will typically see sections corresponding to each level defined in your Nested Query (e.g., "Account Item," "Contact Item," "Case Item"). Select the level you want to configure.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FucwDXWhYBJIc9sz9059r%2F2025-04-23_21-08-27.png?alt=media&#x26;token=689a951b-68b7-4748-9425-d9a7cb76c260" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### **Map Attributes for Each Level**

For the selected item level (e.g., Account):

* **Label:** Select the field from the query results that should be the primary display text for the node (e.g., `Account.Name`).
* **Icon Name (Optional):** Select a field containing an SLDS icon name, or enter a static icon name (e.g., `standard:account`) to display an icon on the node.
* **Additional Fields (Optional):** Add other fields from the query that you want to display as secondary information on the node.
* **Expanded (Optional - for parent nodes):** (Boolean) Set whether this level's nodes should be expanded by default to show their children when the graph loads. Bind to a boolean field or set a static value.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FU2wRlIJzHluccqWoeLMg%2F2025-04-23_21-09-44.png?alt=media&#x26;token=cf034ea6-c1cb-4ce5-8130-4c9b34ac0a3f" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### **Repeat Mappings**

Repeat step 3 for *each item level* (e.g., configure mappings for Contacts, then for Cases).
{% endstep %}
{% endstepper %}

### Header Configuration

Customize the header displayed above the graph.

* **Title:** (Text) Enter a title for the graph (e.g., "Account Relationships").
* **Icon Name:** (Text, Optional) An icon for the header.
* **Actions:** (Actions, Optional) Add header-level buttons for actions related to the *entire graph* (e.g., "Expand All," "Collapse All," "Refresh"). These use standard Avonni Interactions.

### Node Configuration

Customize the appearance of the expand/collapse controls on nodes that have children.

* **Expand Icon Name:** (Text) Icon name for the button to expand a node (e.g., `utility:add`).
* **Collapse Icon Name:** (Text) Icon name for the button to collapse a node (e.g., `utility:dash`).

### Interaction Configuration

Add interactivity directly to the graph nodes. Interactions are typically configured within the **Data Mappings** section for each item level or, potentially, as overall component interactions.

* **Group/Parent Node Actions:** Define interactions triggered by clicking on the top-level (parent) nodes.
* **Item/Child Node Actions:** Define interactions triggered by clicking on individual child nodes.
* **Common Interaction Actions for Graph Nodes:**
  * [**Navigate**](https://docs.avonnicomponents.com/dynamic-components/component-builder/interactions/navigation-and-notifications/navigate)**:** Use this to direct the user to another page. A very common use case is to open the **record page** for the clicked node.
    * *Configuration Example:* Set Page Reference Type to `Record Page`, select the correct Object API Name for that node level, and set Record ID to the `Item Name` attribute you mapped for that node.
  * [**Open Flow Dialog**](https://docs.avonnicomponents.com/dynamic-components/component-builder/interactions/flow-builder-integration/open-flow-dialog) **/** [**Open Flow Panel**](https://docs.avonnicomponents.com/dynamic-components/component-builder/interactions/flow-builder-integration/open-flow-panel)**:** Launch a **Screen Flow** in a modal or side panel to guide the user through a process related to the clicked node (e.g., editing details, creating a related task, logging a call).
    * *Configuration Example:* Select the desired Screen Flow, and pass the clicked node's ID (using the `Item Name` attribute) as an input variable into the Flow.
  * [**Execute Flow**](https://docs.avonnicomponents.com/dynamic-components/component-builder/interactions/flow-builder-integration/execute-flow)**:** Trigger an **autolaunched Flow** for background processing related to the clicked node (e.g., updating a record status, sending an email notification, or creating a standard task).
    * *Configuration Example:* Select the relevant autolaunched Flow and pass the node's ID (from `Item Name`) as an input variable.
  * [**Show Toast**](https://docs.avonnicomponents.com/dynamic-components/component-builder/interactions/navigation-and-notifications/show-toast)**:** Display a quick informational message to the user, potentially including details from other fields mapped for the clicked node

***

## Example: Account -> Contact -> Case Hierarchy

1. **Data Source (Nested Query):**
   * Parent: `Account`
   * Child 1: `Contact` (Related via `AccountId`,&#x20;
   * Child 2 (Nested under Contact): `Case` (Related via `ContactId`,)
2. **Data Mappings:**
   * **Account Item:** `Label: Name`, `Icon Name: standard:account`, `Expanded: true`
   * **Contact Item:** `Label: Name`, `Icon Name: standard:contact`
   * **Case Item:** `Label: CaseNumber`, `Item Name: Id`, `Icon Name: standard:case`, `Additional Fields: Status`

**Result:** An interactive graph showing Accounts, expandable to show related Contacts, which are further expandable to show associated Cases. Clicking any node navigates to its record page.

***

## Key Considerations

* **Data Model:** Requires clear parent-child relationships (lookup fields) in your Salesforce data.
* **Nested Query Setup:** Correctly configuring the Nested Query Data Source is crucial.
* **Performance:** Very large or deeply nested hierarchies (containing many thousands of nodes) can significantly impact loading performance. Use filters in your query where possible.
* **Clarity:** Design your graph display, including labels and additional fields, to be clear and uncluttered.

***

## **In Summary**

The Avonni Relationship Graph provides a powerful visual way to explore and interact with hierarchical data directly on your Lightning Pages. By leveraging Nested Queries and configuring explicit data mappings, you can transform complex relationships into intuitive, actionable visualizations without code.