> For the complete documentation index, see [llms.txt](https://docs.labii.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labii.com/widgets/section-widgets/diagram/relation-flowchart.md). # 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 %}
### 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.