# Relation Flowchart

## Specs

| Label                     | Value                         |
| ------------------------- | ----------------------------- |
| **Version**               | 2.2.0 (updated on 2023-07-05) |
| **Developer**             | Labii Inc.                    |
| **Type**                  | Section                       |
| **Support Configuration** | Yes                           |

## Overview

The Relation Flowchart section widget visualizes how Labii records connect to one another through [ForeignKey](/widgets/column-widgets/form/dropdown.md#foreignkey) and [ForeignKeys](/widgets/column-widgets/form/dropdown.md#foreignkeys) columns. It converts linked records into a flowchart so users can quickly understand upstream and downstream relationships, such as where an item is stored, how a sample moves through processing steps, or which records contribute to a final result. The widget is especially useful for sample lineage, storage hierarchy, inventory relationships, process traceability, and any workflow where record context matters.

## Use Cases

* **Sample Lineage**: Track how a sample connects to derived materials, assays, libraries, results, or reports.
* **Storage Hierarchy**: Visualize relationships such as lab, freezer, rack, box, and sample location.
* **Inventory Traceability**: Show how batches, lots, reagents, and consumables connect to experiments or production records.
* **Process Documentation**: Map upstream and downstream records involved in an experimental or operational workflow.
* **Data Review**: Help reviewers inspect connected records without manually opening each table and relationship column.

## Interface

### Read-only View

The read-only view displays the configured record relationships as a flowchart. Each box represents a Labii record, and each connector represents the selected ForeignKey or ForeignKeys relationship.

* **Record Nodes**: Displays linked records as boxes in the flowchart.
* **Relationship Lines**: Shows how records refer to one another through the configured relationship column.
* **Connector Text**: Displays optional text between boxes when a text column is configured.
* **Clickable Records**: Opens record details when users click a box in the flowchart.
* **Directional Layout**: Uses the configured chart direction and arrow direction to show the relationship path.

{% hint style="info" %}
The widget searches connected records in real time. Large relationship networks may take longer to load than simple one-to-one paths.
{% endhint %}

<figure><img src="/files/5nc0ajR75e0nSRdgEteh" alt=""><figcaption></figcaption></figure>

### Edit View

The edit view is used to configure which relationship column the flowchart should follow and how the chart should display those connections.

* **Column**: Select the ForeignKey or ForeignKeys column used to build the flowchart.
* **Text Column**: Select the text shown between connected boxes.
* **Direction**: Choose the flowchart direction.
* **Should reverse arrow**: Reverse the connector arrow direction when the default relationship direction does not match the way you want to present the workflow.
* **Submit**: Save the configuration and return to the rendered flowchart.

## Configuration

### Initial Setup

{% stepper %}
{% step %}
Confirm that the table contains a [ForeignKey](/widgets/column-widgets/form/dropdown.md#foreignkey) or [ForeignKeys](/widgets/column-widgets/form/dropdown.md#foreignkeys) column.
{% endstep %}

{% step %}
Confirm that multiple records refer to one another through the same relationship column.
{% endstep %}

{% step %}
Add a section with the **Relation Flowchart** widget to the record where you want to visualize relationships.
{% endstep %}

{% step %}
Click **Edit** to open the widget configuration.
{% endstep %}

{% step %}
Select the relationship **Column**, choose the optional **Text Column**, set the chart **Direction**, and decide whether to enable **Should reverse arrow**.
{% endstep %}

{% step %}
Click **Submit** to save the configuration and generate the flowchart.
{% endstep %}
{% endstepper %}

### Required Settings

* **Column**: Select the ForeignKey or ForeignKeys column that defines the record relationship to visualize.

### Optional Settings

* **Text Column**: Select a text column to display labels between connected records. Choose **Self** to use the relationship column name, or choose **None** to hide connector text.
* **Direction**: Set the flowchart direction so the relationship reads naturally for the workflow, such as top-to-bottom or left-to-right.
* **Should reverse arrow**: Reverse the arrow direction when the visual flow should point opposite the stored relationship direction.

{% hint style="warning" %}
The selected column must contain valid record references. If records are not linked through the same ForeignKey or ForeignKeys column, the flowchart may appear incomplete.
{% endhint %}

## Additional Functions

### Visualize a Single Relationship Path

Use a **ForeignKey** column when each record should refer to one related record. This creates a single relationship path, which is useful for storage hierarchies, parent-child relationships, or records with one direct source.

### Visualize Multiple Relationship Paths

Use a **ForeignKeys** column when each record can refer to multiple related records. This can create multiple paths in the flowchart, which is useful for sample pooling, multi-input workflows, shared reagents, or records connected to several upstream sources.

### Open Related Records

Click a box in the flowchart to open more details about the associated record. This makes the flowchart useful as both a visualization and a navigation tool for connected data.

### Reverse Arrow Direction

Enable **Should reverse arrow** when the stored relationship direction is correct for the data model but the opposite direction is clearer for readers. For example, a storage record may point to its parent location, while the visual chart may be easier to read from location to contents.

## Best Practices

* Use clear record names so each flowchart box is meaningful without extra context.
* Choose **ForeignKey** for simple one-to-one or child-to-parent relationships.
* Choose **ForeignKeys** when records can connect to multiple upstream or downstream records.
* Add connector text when the relationship meaning is not obvious from the record names alone.
* Keep very large relationship networks focused by selecting the most relevant relationship column.
* Review arrow direction from the perspective of the reader, especially for sample lineage and storage hierarchy diagrams.

{% hint style="success" %}
For traceability workflows, combine consistent relationship columns with clear record naming. The flowchart becomes much easier to audit when each node and connector explains its role at a glance.
{% endhint %}

## Related Widgets

* [**Record List by ForeignKey**](/widgets/section-widgets/data-display/record-list/record-list-by-foreignkey.md): Display records that reference the current record through a ForeignKey or ForeignKeys column.
* [**Record List by Column**](/widgets/section-widgets/data-display/record-list/record-list-by-column.md): Display records organized by values in a ForeignKey or ForeignKeys column.
* [**Record Timeline by ForeignKey**](/widgets/section-widgets/data-display/record-list/record-timeline-by-foreignkey.md): Display linked records in chronological order when time sequence is the primary concern.
* [**Section Display By ForeignKey**](/widgets/section-widgets/data-display/sections/section-display-by-foreignkey.md): Display sections from related records through ForeignKey or ForeignKeys references.
* [**Stage Flowchart**](/widgets/section-widgets/diagram/stage-flowchart.md): Visualize progress through predefined status stages rather than record-to-record relationships.
* [**Mermaid**](/widgets/section-widgets/diagram/mermaid.md): Create custom diagrams manually when the relationship structure is not stored in Labii columns.


---

# 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://docs.labii.com/widgets/section-widgets/diagram/relation-flowchart.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.