종단 간 예제: Report와 Flow 연결

이 예제에서는 Report에 입력값을 작성하고 girder_check Flow와 연결한 뒤, 계산 결과를 같은 Report의 검토 위치에 표시합니다.

Flow는 PXFLOW Studio에서 직접 만들거나 Python SDK에서 작성할 수 있습니다. 두 방식을 함께 수행하는 절차가 아니라, Project와 팀의 작업 방식에 맞춰 authoring owner 하나를 선택합니다. 이 예제의 코드 절은 SDK를 선택했을 때 Studio Canvas와 어떻게 대응하는지 보여 줍니다.

점선은 `.pxreport`가 소유하는 Report↔Flow mapping이고, 실선은 `.pxflow`와 `flow.connect(...)`가 소유하는 Flow 내부 연결입니다. Report 연결을 만들어도 Flow Python source는 바뀌지 않습니다.

완성할 연결

시작 위치	연결 대상	저장 owner
Report의 span 작성값	Flow input span	.pxreport inputMappings
Report의 design_moment 작성값	Flow input design_moment	.pxreport inputMappings
Flow result utilization	Report의 check_summary.utilization 위치	.pxreport resultMappings

Flow 안에서는 span과 design_moment가 resistance_check Node로 연결됩니다. 이 내부 연결은 .pxflow 또는 SDK source가 소유합니다.

1. Report에서 입력과 결과 위치 준비

1. Project Home에서 Report를 선택합니다.
2. New Report를 만들고 key를 girder_review로 정합니다.
3. 본문에 span = 24.0 m와 design_moment = 1820 kN·m를 typed value로 입력합니다.
4. 검토 요약 아래에 utilization result를 표시할 빈 위치를 둡니다.

Report 본문과 작성값은 .pxreport가 소유합니다. 계산 연결을 추가해도 Flow source의 Node와 내부 연결은 그대로 유지됩니다.

2. Flow 작성 방식 선택

PXFLOW Studio에서 시작

1. Project Home에서 PXFLOW를 선택합니다.
2. New Flow를 만들고 key를 girder_check로 정합니다.
3. public input span, design_moment를 추가합니다.
4. Definitions → Functions에서 Project Function을 고르거나 Components dock에서 built-in Component를 Canvas에 놓습니다. 설치형 third-party Component 배치는 V2 계약이 구현·활성화된 뒤 제공할 계획입니다.
5. result port에서 input port로 연결선을 만들고 public result utilization을 추가합니다.
6. Validate → Save로 .pxflow revision을 저장합니다.

이 경로에서는 .pxflow가 authoring owner입니다.

Python SDK에서 시작

SDK-linked Flow가 필요한 Project에서는 다음처럼 작성합니다.

from pipelinexlab import px


class GirderResults(px.Results):
    utilization: float


@px.function(
    key="check_resistance",
    version="1.0.0",
    description="Checks girder design moment against resistance.",
)
def check_resistance(span: float, design_moment: float) -> GirderResults:
    resistance = span * 100.0
    return GirderResults(utilization=design_moment / resistance)


flow = px.Flow(
    "girder_check",
    label="Girder check",
    description="Checks girder demand against resistance.",
)

span = flow.input("span", float, unit="m", description="Clear span.")
design_moment = flow.input(
    "design_moment",
    float,
    unit="kN.m",
    description="Factored design moment.",
)
check = flow.node("resistance_check", check_resistance)

flow.connect(span, check.inputs.span)
flow.connect(design_moment, check.inputs.design_moment)
flow.result(
    "utilization",
    check.results.utilization,
    description="Demand divided by resistance.",
)

SDK 표현	PXFLOW Studio에서 보이는 것
flow = px.Flow("girder_check")	girder_check Flow
flow.input("span", ...)	public input span
flow.node("resistance_check", ...)	Project Function Reference Node 하나
flow.connect(span, check.inputs.span)	public input에서 Node input으로 이어지는 연결선
flow.result("utilization", ...)	public result utilization

이 경로에서는 Python source가 authoring owner이고 Studio는 materialize된 같은 Flow를 Canvas에 표시합니다.

resistance_check Node의 Function source는 읽기 전용으로 보입니다. Function을 바꾸려면 Node의 Open Function으로 Definitions를 열어 모든 사용처와 연결 영향을 확인합니다. 이 Node만 다른 계산을 사용해야 하면 Duplicate / Branch Function으로 새 Function을 만든 뒤 resistance_check의 target만 교체합니다.

3. 내부 연결과 Report 연결 구분

girder_check의 public port와 내부 NodeReport mapping과 Flow 내부 연결은 서로 다른 owner에 저장됩니다.

Flow public inputs

spanfloat64 · m

design_momentfloat64 · kN·m

flow.connect(...)

Function Reference Noderesistance_checkcheck_resistance@1.0.0의 읽기 전용 계약을 참조

flow.result(...)

Flow public results

utilizationfloat64 · 1

Report의 .pxreport inputMapping은 작성값을 public input에 연결하고, resultMapping은 public result를 Report result slot에 표시합니다. Python SDK와 Workbench가 같은 mapping을 편집합니다.

• flow.connect(...)는 같은 Flow 내부의 exact port 두 개를 연결합니다.
• Report input mapping은 Report 작성값과 Flow public input을 연결합니다.
• Report result mapping은 Flow public result와 Report 표시 위치를 연결합니다.

따라서 Report 연결을 만들 때 Python source에 Report block key나 셀 위치를 추가하는 절차가 생기지 않습니다.

4. Report 작성값을 Flow input에 연결

Report Workbench로 돌아가 다음 순서로 연결합니다.

1. 24.0 m typed value를 선택합니다.
2. @ Insert → PXFLOW를 선택합니다.
3. Project의 girder_check Flow를 고릅니다.
4. Input · span을 선택합니다.
5. type float64, unit m, scalar shape를 확인하고 Apply를 누릅니다.
6. 1820 kN·m도 같은 방식으로 Input · design_moment에 연결합니다.

연결을 고르면 Report 값 옆에 @가 표시되고, 같은 행에서 Report → Flow 방향과 exact input을 확인할 수 있습니다. Report 아래 연결 요약에는 Flow와 input/result 위치 수가 표시됩니다.

저장 결과의 핵심은 다음과 같습니다.

{
  "connectionKey": "girder_check",
  "mappingGeneration": 2,
  "flowTarget": {
    "scope": {
      "kind": "project",
      "workspaceKey": "structural_team",
      "projectKey": "bridge_design"
    },
    "flowKey": "girder_check",
    "revisionRef": "sha256:flow-revision-digest"
  },
  "inputMappings": [
    {
      "mappingKey": "span_input",
      "portKey": "span",
      "source": {
        "kind": "reportValue",
        "blockKey": "design_basis",
        "fieldKey": "span"
      }
    },
    {
      "mappingKey": "design_moment_input",
      "portKey": "design_moment",
      "source": {
        "kind": "reportValue",
        "blockKey": "design_basis",
        "fieldKey": "design_moment"
      }
    }
  ],
  "resultMappings": [],
  "runPolicy": "manual"
}

5. Flow result를 Report 위치에 연결

1. Report의 검토 요약에서 결과를 표시할 위치에 caret를 둡니다.
2. @ Insert → PXFLOW를 선택합니다.
3. 같은 girder_check connection을 고릅니다.
4. Result · utilization을 선택합니다.
5. 숫자 표시 형식과 unit 1을 확인하고 Insert를 누릅니다.

이 동작은 같은 connection에 다음 resultMappings 항목을 추가합니다.

{
  "mappingKey": "utilization_result",
  "portKey": "utilization",
  "target": {
    "kind": "reportResultSlot",
    "blockKey": "check_summary",
    "slotKey": "utilization"
  }
}

이 mapping을 connection에 추가한 저장 revision에서는 mappingGeneration이 3으로 증가합니다. 같은 connection의 mappingKey는 input과 result 전체에서 중복되지 않습니다.

결과 위치는 Run이 만든 immutable Result를 읽기 전용으로 표시합니다.

같은 연결은 작성값 여러 개를 한 Run에 보내고 result 여러 개를 각 Report 위치로 돌려줄 수 있습니다. 위 girder_check 예제도 같은 input/result mapping 규칙을 사용합니다.

6. Validate, Save, Run

1. Report Workbench의 연결 검증에서 exact Flow revision과 두 input mapping을 확인합니다.
2. Save로 새 Report revision을 만듭니다.
3. girder_check connection에서 Run을 누릅니다.
4. Report Activity에서 ordinary Flow Run 하나의 상태를 확인합니다.
5. Run이 완료되면 utilization result가 check_summary 위치에 표시됩니다.

이 예제의 Validate · Save · Run

1. 1Saved Report revision두 input mapping과 result mapping
2. 2Flow 계약 검증exact revision · mapping
3. 3Input materialize두 Report 값을 payload 하나로 구성
4. 4Run · Resultordinary Run 1회와 immutable utilization 저장
5. 5Report projectionresult slot에 읽기 전용 표시

Report에서 서로 다른 Flow connection 두 개를 고르고 Run selected를 선택하면 connection마다 독립 Flow Run 하나가 시작됩니다. Report Activity는 한 번의 사용자 동작 아래에서 각 Run 상태를 함께 보여 줍니다.

7. 표를 연결할 때

여러 행을 한 번에 계산하려면 Flow가 collection input을 공개합니다.

cases = flow.input(
    "cases",
    list[DesignCase],
    description="Design cases evaluated together in one Run.",
)

Report 표의 stable row와 field를 cases에 연결하면 List<DesignCase> 하나가 Flow Run 한 번에 전달됩니다. Table<Record> input도 같은 원칙을 사용합니다.

Scalar input에 여러 행을 연결해 각각 실행하는 작업은 Batch Run에서 case 수와 결과 merge 방식을 먼저 확인합니다. Report 표를 선택하는 동작만으로 여러 Run을 만들지 않습니다.

8. Studio 변경이 SDK에 돌아가는 방식

Flow authoring owner	Studio에서 변경할 때	저장 결과
PXFLOW-native	Studio가 direct Flow command를 적용	새 .pxflow revision
SDK-linked	source-safe diff와 영향을 먼저 확인	Python source 수정 → rematerialize → 새 revision

SDK-linked Flow의 Studio 변경은 Python으로 손실 없이 표현할 수 있는 범위에서 source-safe diff를 사용합니다. 직접 표현하기 어려운 변경은 Python source에서 편집하거나 명시적으로 PXFLOW-native copy를 만드는 선택지를 제공합니다.

Report mapping은 두 authoring 방식 모두 .pxreport가 소유합니다. Report에서 input/result 연결을 바꿀 때 Flow Python source는 변경 대상에 포함되지 않습니다.

최종 확인

• Report Workbench에서 본문, typed value, 표와 결과 위치를 작성했습니다.
• Flow는 Studio 또는 SDK 중 선택한 authoring owner에서 만들었습니다.
• flow.input, flow.connect, flow.result의 역할을 구분했습니다.
• Report input/result mapping을 .pxreport에 저장했습니다.
• exact revisionRef, portKey, type, unit과 shape를 검증했습니다.
• connection 하나를 ordinary Flow Run 한 번으로 실행했습니다.
• immutable Result를 Report 위치에 읽기 전용으로 표시했습니다.

이어서 보기

• Report Workbench
• Report와 Flow 연결
• SDK와 PXFLOW Studio
• Report ↔ Flow 연결 명세
• 실행과 결과