Lookup Fields
A lookup field reads a value from a different blueprint's edition and displays it in the current section. Use lookup fields to avoid re-entering the same data in multiple blueprints — for example, pulling the approved budget from a project setup blueprint into a monthly reporting blueprint.
How lookup fields work
When an edition is open, lookup fields query a source blueprint and return a value from the matching edition:
- The lookup field is configured with a source blueprint, a key field, and a return field.
- When the edition is loaded, Report Forge finds the source edition that matches the current edition's key value.
- The resolved value from the return field is shown in the lookup field — read-only.
The lookup is re-evaluated each time the edition is opened, so if the source blueprint's edition data changes, the lookup field reflects the updated value on the next open.
Lookup field configuration
Open the field properties in the Blueprint Designer and set:
| Property | Description |
|---|---|
| Source blueprint | The blueprint to read data from. |
| Source section | The section within the source blueprint that contains the data. |
| Source key field | The field in the source section that identifies the matching row (e.g. Project ID). |
| Match field | The field in the current section that provides the key to match against (e.g. the current section's Project ID). |
| Source return field | The field in the source section whose value to return and display. |
| Lookup scope | Which source edition to read from — see table below. |
| Source edition | Required when Lookup scope = Specific — choose a named edition. |
Lookup scope options
| Scope | Description |
|---|---|
| latest | Returns the value from the most recently approved edition of the source blueprint. If no approved edition exists, falls back to the latest edition in any status. |
| specific | Returns the value from a named, pinned source edition. Use this for approved baseline data that should not change (e.g. contract value at award). |
| all | Returns an array of values from all matching editions. Use this for aggregated lookups (e.g. total approved variations across all editions). |
Field type compatibility
The return field in the source section must be of a compatible type for the lookup to resolve correctly:
| Source field type | Can be looked up as |
|---|---|
| Text | Text lookup |
| Number / Currency / Percent | Number lookup |
| Date / Datetime | Date lookup |
| Select / Multi-select | Text lookup (returns the label) |
| Toggle | Text ("true" / "false") |
| Computed | Number or Text |
| RAG | Text ("red" / "amber" / "green") |
Lookup fields inherit the display format of the source return field unless overridden.
Lookup in form mode
In form mode, a lookup field:
- Shows as a read-only input with a link icon indicating it is looked up.
- Displays the resolved value.
- Shows "No matching data" if no matching source edition is found.
- Shows "Source blueprint not published" if the source blueprint has no editions.
Hovering the link icon shows a tooltip with the source blueprint name, section, and edition that the value was resolved from.
Lookup in grid mode
In grid mode, lookup cells are:
- Read-only (cannot be edited inline).
- Shown with a muted cell background to distinguish them from editable cells.
- Refreshed when the grid row is opened in form mode.
Lookup in outputs
Lookup fields can be bound to any output component (table, info grid, KPI card, etc.) the same way as regular fields. The resolved value is embedded in the output at generation time.
If the lookup has not resolved (no matching data), the output component shows the configured empty value text (default: "—").
Cascading lookups
A lookup field can reference a field that is itself a lookup in the source blueprint. This allows multi-hop data flows, but keep the chain short (maximum 2 hops) to avoid unpredictable resolution order and performance delays.
Common use cases
| Use case | Source blueprint | Key field | Return field |
|---|---|---|---|
| Pull approved budget into monthly reporting | Project Setup | Project ID | Approved contract value |
| Show latest safety frequency rate in programme roll-up | Project Monthly Safety Report | Project ID | LTIFR |
| Display resource forecast from resource plan | Resource Planning Blueprint | Project ID | Forecast headcount |
| Show prior-period actuals in current edition | Same blueprint (prior edition) | Period code | Actual cost |
Limitations
- Lookup fields are read-only — contributors cannot override the resolved value.
- Lookup fields cannot be used as the match field in another lookup (circular reference prevention).
- Lookup fields are not available in the source return field list if their source is not yet published.