pipefy-reports

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reports

报告

Pipe reports and organization reports: discovery, CRUD, and async exports. 17 MCP tools.

管道报告（pipe reports）与组织报告（organization reports）：发现、CRUD操作及异步导出。17个MCP工具。

Cross-cutting patterns

通用模式

Build

ReportCardsFilter

using

get_pipe_report_columns

and

get_pipe_report_filterable_fields

; use

introspect_type

for uncommon inputs.

```
get_pipe_reports
```
omits
```
cardCount
```
in the query (Pipefy can error when resolving it).
```
debug=true
```
on writes like other mutation tools.

使用

get_pipe_report_columns

和

get_pipe_report_filterable_fields

构建

ReportCardsFilter

；对于特殊输入，使用

introspect_type

。

```
get_pipe_reports
```
在查询中省略了
```
cardCount
```
字段（Pipefy解析此字段时可能会报错）。
与其他变更工具一样，写入操作时设置
```
debug=true
```
。

Pipe report tools

管道报告工具

Tool (MCP)	CLI	Read-only	Purpose
`get_pipe_reports`	`pipefy report-pipe list`	Yes	List all reports for a pipe.
`get_pipe_report`	`pipefy report-pipe get`	Yes	Single report data.
`get_pipe_report_columns`	`pipefy report-pipe columns`	Yes	Discover available columns for a report filter.
`get_pipe_report_filterable_fields`	`pipefy report-pipe filterable-fields`	Yes	Discover filterable fields for a report.
`create_pipe_report`	`pipefy report-pipe create`	No	Create a new pipe report.
`update_pipe_report`	`pipefy report-pipe update`	No	Update report name or filters.
`delete_pipe_report`	`pipefy report-pipe delete`	No	Two-step destructive.
`export_pipe_report`	`pipefy report-pipe export`	No	Trigger async export.

工具（MCP）	CLI命令	只读	用途
`get_pipe_reports`	`pipefy report-pipe list`	是	列出某个管道的所有报告。
`get_pipe_report`	`pipefy report-pipe get`	是	获取单个报告的数据。
`get_pipe_report_columns`	`pipefy report-pipe columns`	是	发现报告筛选器可用的列。
`get_pipe_report_filterable_fields`	`pipefy report-pipe filterable-fields`	是	发现报告的可筛选字段。
`create_pipe_report`	`pipefy report-pipe create`	否	创建新的管道报告。
`update_pipe_report`	`pipefy report-pipe update`	否	更新报告名称或筛选条件。
`delete_pipe_report`	`pipefy report-pipe delete`	否	需两步确认的破坏性操作。
`export_pipe_report`	`pipefy report-pipe export`	否	触发异步导出。

Organization report tools

组织报告工具

Tool (MCP)	CLI	Read-only	Purpose
`get_organization_reports`	`pipefy report-org list`	Yes	List all org-level reports.
`get_organization_report`	`pipefy report-org get`	Yes	Single org report data.
`create_organization_report`	`pipefy report-org create`	No	Create an org-wide report.
`update_organization_report`	`pipefy report-org update`	No	Update report config.
`delete_organization_report`	`pipefy report-org delete`	No	Two-step destructive.
`export_organization_report`	`pipefy report-org export`	No	Trigger async export.

工具（MCP）	CLI命令	只读	用途
`get_organization_reports`	`pipefy report-org list`	是	列出所有组织级报告。
`get_organization_report`	`pipefy report-org get`	是	获取单个组织报告的数据。
`create_organization_report`	`pipefy report-org create`	否	创建全组织范围的报告。
`update_organization_report`	`pipefy report-org update`	否	更新报告配置。
`delete_organization_report`	`pipefy report-org delete`	否	需两步确认的破坏性操作。
`export_organization_report`	`pipefy report-org export`	否	触发异步导出。

Export status & download

导出状态与下载

Tool (MCP) CLI Purpose

Tool (MCP)	CLI	Purpose
`get_pipe_report_export`	poll via `pipefy report-pipe export --format json`	Poll pipe report export status (after `export_pipe_report` ).
`get_organization_report_export`	poll via `pipefy report-org export --format json`	Poll org report export status (after `export_organization_report` ).
`export_pipe_audit_logs`	`pipefy audit export`	Export pipe audit logs (separate from card report exports).

get_pipe_report_export

poll via

pipefy report-pipe export --format json

Poll pipe report export status (after

export_pipe_report

get_organization_report_export

poll via

pipefy report-org export --format json

Poll org report export status (after

export_organization_report

export_pipe_audit_logs

pipefy audit export

Export pipe audit logs (separate from card report exports).

工具（MCP）	CLI命令	用途
`get_pipe_report_export`	通过 `pipefy report-pipe export --format json` 命令进行轮询	在执行 `export_pipe_report` 后，轮询管道报告的导出状态。
`get_organization_report_export`	通过 `pipefy report-org export --format json` 命令进行轮询	在执行 `export_organization_report` 后，轮询组织报告的导出状态。
`export_pipe_audit_logs`	`pipefy audit export`	导出管道审计日志（与卡片报告导出相互独立）。

Steps — export a pipe report

步骤 — 导出管道报告

List available reports:
MCP:
```
get_pipe_reports pipe_id=67890
```
Trigger the export:
MCP:
```
export_pipe_report report_id=123
```
Poll until finished:
MCP:
```
get_pipe_report_export export_id=<EXPORT_ID>
```
Repeat every 5–10 seconds until the response indicates
```
finished
```
(or
```
failed
```
).
Download: use the signed
```
fileUrl
```
from the finished export response over HTTPS (the MCP tool surfaces it in the payload).

列出可用报告：
MCP命令：
```
get_pipe_reports pipe_id=67890
```
触发导出：
MCP命令：
```
export_pipe_report report_id=123
```
轮询直至完成：
MCP命令：
```
get_pipe_report_export export_id=<EXPORT_ID>
```
每5-10秒重复执行一次，直到响应显示
```
finished
```
（或
```
failed
```
）状态。
下载： 通过HTTPS使用完成导出响应中的签名
```
fileUrl
```
进行下载（MCP工具会在返回结果中提供该链接）。

Steps — create a filtered pipe report

步骤 — 创建带筛选条件的管道报告

Discover filterable fields:

MCP:

get_pipe_report_filterable_fields pipe_id=67890

Create the report with a
ReportCardsFilter
shape (not a top-level

current_phase

array):

MCP:

create_pipe_report pipe_id=67890 name="Phase subset" filter='{"operator":"and","queries":[{"field":"current_phase","operator":"eq","type":"select","value":"<phase_id>"}]}'

Use the exact

field

string from step 1. Invalid shapes are rejected before GraphQL with a message pointing at

get_pipe_report_filterable_fields

发现可筛选字段：

MCP命令：

get_pipe_report_filterable_fields pipe_id=67890

使用
ReportCardsFilter
结构创建报告（而非顶层的

current_phase

数组）：

MCP命令：

create_pipe_report pipe_id=67890 name="Phase subset" filter='{"operator":"and","queries":[{"field":"current_phase","operator":"eq","type":"select","value":"<phase_id>"}]}'

使用步骤1中获取的精确

field

字符串。若结构无效，会在GraphQL执行前被拒绝，并提示参考

get_pipe_report_filterable_fields

。

Success criteria

成功标准

get_pipe_report_export

(or

get_organization_report_export

) reaches a terminal

finished

failed

state.

Downloaded export contains the expected card/report data.

get_pipe_report_export

（或

get_organization_report_export

）进入最终的

finished

或

failed

状态。

下载的导出文件包含预期的卡片/报告数据。

Failure modes

失败场景

Export stuck in
processing
: large pipes with many cards can take minutes. Wait at least 60 seconds per poll. Retry the export trigger if still
```
processing
```
after several minutes.
get_pipe_reports
returns
null
for
cardCount
: known Pipefy API behavior; the tool omits that field automatically.
Filter rejected before GraphQL: do not pass
```
{"current_phase":["id"]}
```
; use
```
operator
```
+
```
queries
```
(see step 2 above).
Filter not working after create: use
```
get_pipe_report_filterable_fields
```
to confirm the exact
```
field
```
string and
```
value
```
format.

导出卡在
processing
状态：包含大量卡片的大型管道可能需要数分钟处理时间。每次轮询至少间隔60秒。若数分钟后仍处于
```
processing
```
状态，可重新触发导出。
get_pipe_reports
返回的
cardCount
为
null
：这是Pipefy API的已知行为；工具会自动省略该字段。
筛选条件在GraphQL执行前被拒绝： 请勿传入
```
{"current_phase":["id"]}
```
格式；需使用
```
operator
```
+
```
queries
```
结构（参见上述步骤2）。
创建后筛选条件不生效： 使用
```
get_pipe_report_filterable_fields
```
确认精确的
```
field
```
字符串和
```
value
```
格式。

另请参阅

```
skills/observability/
```
— export automation job history (different from pipe reports).
```
skills/introspection/
```
— discover
```
ReportCardsFilter
```
input shape for complex filters.

```
skills/observability/
```
— 导出自动化任务历史（与管道报告不同）。
```
skills/introspection/
```
— 为复杂筛选条件探索
```
ReportCardsFilter
```
的输入结构。