Getting started in Report Workbench

Report Workbench is the screen for editing calculation context, authored values and tables, and the positions where results will appear in one Report. Send Report sources to public PXFLOW inputs, then display named results from the Flow Run at selected Report positions as read-only content. The Python SDK can author the same .pxreport document with px.Report.

Dotted lines are Report-to-Flow mappings owned by `.pxreport`; the solid line is the internal Flow connection owned by `.pxflow` and `flow.connect(...)`. Creating a Report connection does not change the Flow Python source.

One Report–Flow connection can contain several inputs for one Run and several results returned by that Run. Report Workbench edits sources and result positions. PXFLOW Studio edits the Flow's public ports, Nodes, and calculation route.

Complete one connection end to end

To send span and load_cases to a Girder check Flow and receive utilization and case_checks:

1. Open the Report from Project Home → Report, then enter the span.
2. Select the span and connect it through @ Insert → PXFLOW → Use report input to span.
3. At an empty paragraph, confirm the load_cases Table input through @, enter its values, then edit its field and row-key mapping under Connection → Table mapping in the same connection.
4. Place the caret in the summary sentence and insert utilization through Insert Flow result.
5. Insert the case_checks Table result in an empty result area.
6. Choose Apply in the connection editor, then Save for the Report.
7. Choose Run for the saved connection.
8. Open the Run in Project Activity and review both results and the Flow revision and inputs that produced them.

Both inputs enter one input set and one Run. The two named results from that Run appear at their selected Report positions.

Open Report Workbench

1. Open a Project from Project Home.
2. Choose Report.
3. Select New Report or open an existing Report.
4. Write the title and body, then choose Save.

Follow the first Project and Report steps

Find the main controls

Screen area	What you do there
Outline	Move between headings and review the Report structure
Connections	Show or hide @ connection marks, I input mappings, and R result mappings
@ Insert	Start a PXFLOW input or result connection or insert Project data and evidence
Report only / Report + PDF	Focus on the Report or show the PDF workspace alongside it
Report body	Write text, values, Records, and tables and select result positions
Project Activity	Review each connection's Run state and recent Result

In the example above the Report owns the authored span and load_cases values, while utilization and case_checks return from the same connection as read-only result positions.

Create the first PXFLOW connection

Both directions start by typing @ at the caret or choosing @ Insert → PXFLOW.

Goal	Choose	Relationship saved by the Report
Use a Report value, table, or attachment in a calculation	Use report input	Report source → public Flow input
Display a calculation result in the Report	Insert Flow result	Public Flow result → Report position

When a connected input is created

The final Resolver confirmation creates the connected input. At an empty caret, type @ and confirm Connect input. 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 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 an authored value to a Flow input

1. 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.
2. For an inline input, type @ or choose @ Insert. For a selected Record field or attachment, keep the selection and use @ Insert.
3. Under PXFLOW, choose the Project and Flow.
4. Choose Use report input.
5. Choose a compatible public input after reviewing its type, unit, and value shape.
6. For a Record, List, or Table, confirm field mappings and the stable row key under Connection.
7. Choose Review connection → Connect input.

If the same Run needs another value, select that source and add it to the same connection. Follow the complete Report-to-Flow input path

Display a Flow result at the current position

1. Place the caret in the sentence, table, blank line, or artifact position where the Result should appear.
2. Under @ Insert → PXFLOW, choose the Project and Flow.
3. Choose Insert Flow result.
4. Select a public result and its presentation.
5. For a Record or Table result, map source fields to Report fields.
6. Choose Review connection → Insert result.

The same named result can appear at several Report positions. Every projection references one Result, so one Run refreshes them together. Follow the complete Flow-result-to-Report path

Choose the value shape and presentation

Public Flow input or result	How the Report uses it
number	Authored value with a unit or an inline Result
text	Authored text or an inline Result
boolean	Authored true/false value or a status Result
Record	Named field mappings or a Record result block
List	Several items as one collection or a List result block
Table	A table with stable row keys and field mappings
artifact	A Report attachment as input or a Result at an artifact position

See structured field mapping for Record, List, and Table examples.

Follow the mapping ownership rules

Configuration	Result
Reuse one Report source for different inputs	Add one mapping per destination
Map different sources to the same input	Choose one source under Duplicate destination
Display one named result at several Report positions	Every position references the same Result and provenance
Map several results to the same Report position	Choose the one result that owns that position

See connection rules for the complete examples.

Review and edit a saved connection

Double-click an @ mark or connected result block to open its connection editor.

Tab	What you review or change
Overview	The read-only route between Report positions and public Flow ports
Connection	Report sources or result positions, Project, Flow, and public ports
Settings	This connection's Run policy and Report input values
Advanced	Exact Flow revision, stable keys, and schema contract

Apply saves the reviewed changes as one Report edit. Cancel and Esc preserve the saved connection. Choose Open in PXFLOW Studio from Overview when the Flow itself needs editing.

Review the connection editor and Overview

Know what each screen can edit

The Flow view in Report Workbench is a read-only route preview. Use Pan or Fit view to inspect the connected public ports and Node path, then choose Open standalone or Open in PXFLOW Studio for full Flow editing.

Report Workbench	PXFLOW Studio
Edit Report sources and result positions	Edit public input and result contracts
Edit Report–Flow mappings and presentation	Edit connections between Nodes
Review connection Runs and Results	Edit Node code, Function references, and Component settings

When a public Flow port changes, review each affected Report connection before selecting the new Flow revision.

Save and run

In the formal server implementation, reading a Report requires its Project's read permission; saving requires both read and write permissions. Checking an existing save receipt also checks current access. With a host that verifies the user, subsequent save requests stay bound to that user and are refused if the account changes. Service account integration and deployment verification remain separate work.

A save response that does not match the original document and edit is not accepted as saved. When the outcome is uncertain, Retry save checks the original request again. Text entered while saving belongs to the next Save after that check completes.

With a verified host user and browser Storage/Web Locks support, the submitted document and unconfirmed request are retained. After reloading, choose Restore submitted document to review the original submission and retry its save. A confirmed save only needs its stored revision reloaded. Another user's or Project's request is not restored. New edits and runs wait until recovery is reviewed.

Recovery covers the document captured when you chose Save. Later unsubmitted typing and the full Undo history are not automatically saved. The restored edit can be undone once to return to its base document. Storage, document-validation, and reload failures retain the recovery record.

1. Choose Apply for the connection and Save for the Report. These authoring actions do not start a calculation.
2. Review validation for the exact Flow revision, public ports, and required inputs.
3. Choose Run for the selected connection.
4. Follow progress in Project Activity.
5. Review the named results and provenance at their Report positions.

All input mappings in one connection enter one Run, and its result mappings share one Result. If a Report value, mapping, or Flow revision changes, the result positions show Stale. Choose Run again to create a Result from the current inputs.

Run several connections together

Choose Run for one connection or Run selected for several. Each selected connection then starts an independent Flow Run. Independent Runs execute in bounded parallel when capacity is available, and their completion order is unspecified.

• Project Activity shows each connection's Run and Result state.
• Cancel and Retry apply only to the selected Run.
• After a newer Run becomes current, a late older Run remains in history and cannot overwrite the current Report result.
• If calculations have a data dependency, model it inside one Flow with Node connections or a subflow. The Runtime follows that Flow-owned dependency order.

Learn more about independent connection Runs

Choose one collection or several calculation cases

Connecting selected rows to a List<T> or Table<Record> input sends one collection value in one Run.

• One cell → scalar input
• Several rows from one field → List<T> input
• Stable row key and several fields → Table<Record> input

Use an explicit Batch Run when every row is an independent scalar input set. Batch creates one child Run per stable case key and reports succeeded, failed, or cancelled cases individually. Completed Results remain available when only some cases finish, and you can Cancel or Retry only the necessary Runs.

Compare one collection Run with one Batch and its child Runs

Understand saved ownership

The Report owns its body, authored values, result positions, and Report–Flow connections. The Flow owns public ports, Nodes, and internal connections. The Runtime owns Runs and immutable Results. These three boundaries are enough for everyday work.

See the exact Report–Flow storage contract when you need the .pxreport fields and mapping schema.

Continue

• Connect a Report and PXFLOW
• Map Report values and tables to Flow inputs
• Review Runs, Results, and recovery

Saved images and calculation figures

Image attachments and PNG results applied from a Run are read through the saved Report revision's file references. The editable body, the body shown when the editor is unavailable, and snapshot-based previews display the same original image. Fitting an image to the page changes neither its stored bytes nor its result provenance.

If the file reader is unavailable, access is refused, or image decoding fails, the image name and an unavailable message are shown. Changing the displayed revision or removing the view cancels old image requests and releases temporary URLs. Reading a figure does not rerun the calculation. Other generated formats, Runtime-rendered pages, and PDF output retain their separate support boundaries.