Connect a Report and PXFLOW
One Report–Flow connection stores both sides of a calculation: the values entering one Flow Run and the results returning to the Report. It can gather several Report sources into different public Flow inputs, then project several named results from that Run to different Report positions.
Connections store calculation setup. Choose Run for one connection or Run selected for several; each selected connection then starts an independent Run. Values needed by one calculation stay together, while unrelated calculations can run, cancel, and retry independently.
Example: connect one girder check
Suppose the Girder check Flow exposes these public inputs and results.
| Report source | Public Flow input | Value shape |
|---|---|---|
24.0 m | span | number |
S355 | steel_grade | text |
true | include_self_weight | boolean |
width and depth fields | section | Record |
| Selected rows from a factor field | factors | List |
A table with case_key, G, and Q fields | load_cases | Table |
| An analysis-model attachment | analysis_model | artifact |
Add these sources to one Girder check connection. Report Workbench sends them as one input set and starts one Run. The Flow can return several named results from that same Run, such as utilization, passed, case_checks, calculation_note, section_summary, and checked_model.
- Show the
utilizationnumber in both the summary sentence and the cover-page metric. - Show the
passedboolean andcalculation_notetext in the review summary. - Show the
section_summaryRecord andcase_checksTable in field-mapped result blocks. - Open the
checked_modelartifact from a dedicated artifact position.
If utilization appears at two Report positions, both positions reference the same Result and provenance. One Run refreshes them together.
Connection rules at a glance
| Configuration | Supported? | What to review |
|---|---|---|
| One Report source → several public Flow inputs | Yes | A separate mapping for each destination input |
| Several Report sources → one public Flow input | Compose first | Use a Record, List, Table, or composition inside the Flow |
| One named Flow result → several Report positions | Yes | Every position references the same Result |
| Several named Flow results → one Report position | Compose first | Use named slots or expose one composite result from the Flow |
| Several input and result mappings in one connection | Yes | All share the same Flow revision and Run |
| Several connections in one Report | Yes | Each has its own Run and state |
Prepare the connection
- Open the Report with edit access.
- Save the target Flow and confirm that the required public inputs and results are visible.
- Compare the source and port types, units, and value shapes.
- Confirm permission to run the Flow and read its Result.
Flows authored with the Python SDK and Flows authored in PXFLOW Studio expose the same public-port list. See SDK and PXFLOW Studio for the code-to-screen relationship.
Choose a connection target with @
Type @ at a Report value or result position to open a resolver narrowed to the selected context. When the Report already has an automation Flow, the resolver starts with compatible inputs or result fields instead of making you browse the full product tree again.
When you select an existing value, its range remains selected while the resolver shows the selected public input's stable key, type, and unit together.
| Goal | Choose | Direction |
|---|---|---|
| Use a Report value in a calculation | Use report input | Report source → public Flow input |
| Display a calculation result | Insert Flow result | Public Flow result → Report position |
Use the arrow keys and Enter to choose an item. Esc closes the menu, restores the caret, and creates no input region or binding. To enter a literal @, press Backspace immediately after the menu opens.
When a connected input is created
At an empty caret, type @ and confirm Connect input in the Resolver. That one confirmation creates the editable input region and Flow input binding together. You can also start from selected ordinary text or a number. The selection initializes the new input but remains ordinary Report content until confirmation. A blank required input is connected but incomplete and becomes ready to run only after its value is committed.
When several named values belong to one structured value and appear at separate positions in a sentence or list, confirm @ once at each visible position. Connections made this way belong to the same structured value, so they are stored together as one mapping. Esc, Cancel, or the guide's Exit before confirmation creates neither object at that position. An earlier position already confirmed in the same action remains connected. Undo or Disconnect removes both in one edit and unwraps the value as ordinary Report content. Surrounding prose, lists, and tables stay unchanged.
Start a new table connection with @ at an empty caret. Connection → Table mapping then edits the fields and row keys of that connected table or one supplied by the SDK or import. Direct @ promotion of an existing ordinary table range is planned.
For example, to send a permanent load G and a variable load Q as one structured input, confirm @ at each position to create a blank connected input and type its value. Each position is confirmed on its own, and because both belong to the same structured value they are stored together as one mapping.
Send authored values to Flow inputs
- For a new inline input, place the caret at an empty position. To use existing content as the initial value, select its text or number. Select a Record field or attachment when that object is the source. Create a new table input with
@at an empty paragraph; direct connection of an existing ordinary range follows the planned boundary above. - For an inline input, type
@or choose @ Insert. For a selected Record field or attachment, keep the selection and use @ Insert. - For the first connection, open PXFLOW → Project → Flow. A Report with a current Flow skips this browse step.
- Choose Use report input.
- Select a compatible public input.
- Confirm the
new input or selected Report source → Flow inputroute in Review connection. - Choose Connect input.
If the same Run needs another input, select its Report source and add it to the same connection. You can also reuse one Report source for another public input. Each input has one active source, so if Review connection shows a conflict, choose which source should own that destination.
At an empty caret, the final Connect input confirmation creates the empty inline input region and its binding together. Enter the value in that region next.
A compact @ mark appears beside a connected value. Turn on Connections to inspect the port and status, or hide authoring marks while continuing to write.
Display Flow results in the Report
- Place the caret in the intended sentence, blank line, table field, or artifact position.
- Open @ Insert → PXFLOW → Project → Flow.
- Choose Insert Flow result.
- Select a public result.
- Review its inline, Record, List, Table, or artifact presentation.
- Confirm the
Flow result → Report positionroute in Review connection. - Choose Insert result.
To show the same named result elsewhere, repeat these steps at the new position and select the same connection and result. Every projection reads one Result, so values and provenance refresh together. If another result already owns the position, choose the one that should remain.
Number, text, and boolean results can appear as connected values inside a sentence. Record and List results can appear by selected field or in a result block. Table and artifact results use dedicated result blocks. Result positions are read-only; edit the Report input or Flow and start a new Run to refresh them.
When several result positions are selected, the resolver shows the matching typed result fields together.
Map Record, List, and Table fields
Map structured values explicitly by field name and type.
| Value shape | What to set in Review connection | Example |
|---|---|---|
| Record | Report field → Flow Record field | section_width → width, section_depth → depth |
List<T> | Report field supplying each item and the item type | Selected factor rows → List<number> |
List<Record> | Record field mapping for each item | case_id → case_key, load → value |
Table<Record> | Stable row key and Report field → Flow column | case_key, G → permanent_g, Q → variable_q |
| Table result | Result row key and result field → Report field | case_key, utilization → ratio, passed → status |
The same screen shows required fields, units, and nullability. Table mappings use stable row keys, not current row numbers, so the same cases still match after sorting. See Map Report values and tables to Flow inputs for the selection workflow and input and result types and units for the exact type rules.
Review the connection summary before saving
After target selection, the Report table shows each direction and exact field. The summary below the table names the Flow and counts its input and result positions. Waiting for Flow remains in the result cells until the calculation runs. Check:
- the Report source or result position;
- the selected Project, Flow, and public input or result;
- the number, text, boolean, Record, List, Table, or artifact shape;
- type, unit, field mapping, and stable row key;
- the selected Flow and access state;
- the number of input mappings and result positions;
- conflicts at the same input or Report position.
Save the connection after reviewing it. Closing the resolver with Esc preserves the saved Report state.
Confirm each row's Report → Flow or Flow → Report direction and verify in the summary how many positions belong to the same connection.
Edit a saved connection
Turn on Connections, then select the @ mark on the value or result cell to reopen its resolver. Confirm the replacement target, type, and unit, apply the change, and Save the Report to create a new revision. Use Open Flow when the Node layout or internal connections must change in PXFLOW Studio.
Immediately after creation, Undo removes the input region and binding in one edit. For a saved connection, Disconnect does the same and leaves the value as ordinary Report content.
Run connections independently
All input mappings in one connection enter one Run together, and all its result mappings display the same Result. If a Report has three selected connections, Run selected starts three independent Runs. Adding or saving a connection only prepares the calculation.
- Independent Runs execute in bounded parallel when capacity is available.
- Start order does not guarantee completion order; Project Activity shows each Run's state.
- After a newer Run becomes current, a late older Run remains in history and cannot overwrite the current Report positions.
- Cancel and Retry apply to the selected Run, leaving other connections and Results intact.
- If calculation B depends on calculation A, model both steps inside one Flow with Node connections or a subflow. The Runtime follows those Flow-owned dependencies.
If a Report value, Flow revision, or mapping changes, its result position shows Stale. The last accepted Result remains visible read-only; choose Run again to create a Result from the current inputs.
Choose one collection Run or one Batch with child Runs
The destination shape—not the selected row count—determines how many Runs start.
| Task | Public Flow input | Run count | Case and partial status |
|---|---|---|---|
| Calculate one collection | List<T> or Table<Record> | 1 | One Result can include stable row keys and row statuses |
| Repeat scalar cases | Scalar inputs in an explicit Batch Run | One child Run per confirmed case | Each stable case key has its own Run state and Result |
For example, connecting ULS-01, ULS-02, and SLS-01 to a Table input starts one Run with one Table value. Preparing the same rows as a Batch starts three child Runs, each with a stable case key and complete input set. If only some cases finish, the Batch summary reports succeeded, failed, and cancelled cases by key while preserving completed Results. Select individual Runs to Cancel or Retry them.
See Map Report values and tables to Flow inputs for the field and case setup.
Move between Report Workbench and PXFLOW Studio
Choose Open in PXFLOW Studio from Overview to edit the selected Flow full screen. The read-only Flow preview in the Report also provides Open standalone.
| Report Workbench edits | PXFLOW Studio edits |
|---|---|
| Report sources and result positions | Public input and result contracts |
| Input and result mappings and presentation | Connections between Nodes |
| Connection Run policy | Node code, Function references, and Component settings |
When a public-port contract changes, PXFLOW Studio first shows the Reports and connections that will be affected.
Understand where connections are stored
| Relationship | Authoring surface | Owner |
|---|---|---|
| Report value, table, or attachment → public Flow input | Report Workbench, Python px.Report, or AI/MCP | Report flowConnections |
| Public Flow result → Report position | Report Workbench, Python px.Report, or AI/MCP | Report flowConnections |
| Flow input → Node input | PXFLOW Studio, Python px.Flow, or AI/MCP | Flow internal connection |
| Node result → next Node input | PXFLOW Studio, Python px.Flow, or AI/MCP | Flow internal connection |
When the Report is saved, .pxreport records the Report positions, exact Flow revision, and stable public-port keys. The Flow's Nodes and internal connections remain in .pxflow or Python source. In Python, connection = report.connect_flow(...) returns a Connected Flow handle; its .bind() and .show() methods create these Report mappings. flow.connect(...) creates only Flow-internal connections.
See the exact Report–Flow storage contract for fields, mapping identity, and validation rules, and Report Table connections and multiple cases for the Table field schema.
Resolve connection states
| State | Review | Next action |
|---|---|---|
| Draft | Pending choices in the connection editor | Apply or Cancel |
| Review update | Changed Flow or port contract | Compare the revision and mapping, then Apply |
| Incompatible | Source and port type, unit, or shape | Choose a compatible public input or result |
| Duplicate destination | Two mappings target the same input or Report position | Choose one source or result |
| Permission required | Report edit, Flow read/run, or Result read access | Request access |
| Stale | Report input, mapping, or Flow revision changed | Run again |
| Choose revision | Available saved Flow revisions | Select the exact revision |
A similarly named port does not replace the saved target automatically. Use Review update to compare the new port name and contract before changing the connection.