uipath-process-mining

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UiPath Process Mining —

uip pm

Assistant

UiPath Process Mining —

uip pm

助手

Build and operate a UiPath Process Mining process app end-to-end from the terminal with

uip pm

: from a raw CSV to a queryable process model. The whole loop — templates, data mapping, upload, ingest, the dbt/Snowflake transformation layer, and querying — is scriptable; use the CLI, don't hand-roll the Process Mining REST API.

This works for every app type, not just

uipath.custom

: the pipeline (mapping → upload → ingest → transform → data model → query) is identical across the

uipath.custom

event-log template and the source-system templates (P2P / O2C / IM / AP / … on SAP, Oracle, NetSuite, ServiceNow, Salesforce, …). Only what the data mapping / extract must contain differs. See

references/app-types.md

This skill is the process-mining domain layer — what to build and why. The low-level mechanics of driving the tool — the command-group map, the

Result

Code

Data

output envelope, the ETag get-modify-put pattern,

--wait

--stage

, and field-id discovery — are one layer down in

references/uip-pm-cli.md

. The rules below carry the headline command and link down to it and to the domain references for the full detail.

通过终端的

uip pm

工具端到端构建并运行UiPath Process Mining流程应用：从原始CSV文件到可查询的流程模型。整个流程——模板、数据映射、上传、摄取、dbt/Snowflake转换层以及查询——均可编写脚本；使用CLI工具，无需手动编写Process Mining REST API。

这适用于所有应用类型，不仅限于

uipath.custom

：从映射→上传→摄取→转换→数据模型→查询的流程在

uipath.custom

事件日志模板和源系统模板（SAP、Oracle、NetSuite、ServiceNow、Salesforce等系统上的P2P/O2C/IM/AP等流程）中完全一致。仅数据映射/提取所需包含的内容有所不同。详见

references/app-types.md

。

本技能是流程挖掘领域层——说明要构建什么以及原因。驱动工具的底层机制——命令组映射、

Result

Code

Data

输出包、ETag获取-修改-上传模式、

--wait

、

--stage

以及字段ID发现——在

references/uip-pm-cli.md

中有更详细的说明。以下规则会给出核心命令及链接，指向底层机制和领域参考文档以获取完整细节。

When to Use This Skill

何时使用本技能

Build a process app from data — you have a CSV / event log and want a mined process (throughput, variants, rework, steps-to-resolution).
Author the transformation layer — edit the dbt (Snowflake) SQL models that produce the process model, then re-run.
Query a process app — pull numbers out: aggregate group-by + metrics, raw detail rows, percentiles, root-cause analysis, process insights.
Expose custom analysis — surface your own analytical table (a weekly aggregate, an impact study) as a queryable entity.
Edit the app model — change a field's data kind, add calculated fields, or fix a data-kind mismatch that locks dashboards open (DNA-46960).
Manage the app lifecycle — stages (dev → published), RBAC, deletion.

从数据构建流程应用——你拥有CSV/事件日志，希望生成挖掘后的流程（吞吐量、变体、返工、解决步骤）。
编写转换层——编辑生成流程模型的dbt（Snowflake）SQL模型，然后重新运行。
查询流程应用——提取数据：聚合分组+指标、原始明细行、百分位数、根本原因分析、流程洞察。
展示自定义分析——将你自己的分析表（每周聚合、影响研究）作为可查询实体对外展示。
编辑应用模型——更改字段的数据类型、添加计算字段，或修复导致仪表板锁定无法关闭的数据类型不匹配问题（DNA-46960）。
管理应用生命周期——阶段（开发→已发布）、RBAC、删除。

App lifecycle

应用生命周期

An app moves through: create (from a template + data mapping) → load (upload + ingest) → transform on the dev stage (the ELT/dbt layer) → publish to the published stage → query / build dashboards. Develop against a small subset on

dev

, then publish the full dataset for real analysis (

references/lifecycle-and-rbac.md

). The ELT editor is the

transformations

command group over the dbt (Snowflake) model tree that turns loaded source tables into the process model — its command surface and the apply-vs-run distinction are in

references/transformations.md

应用会经历以下阶段：创建（从模板+数据映射）→加载（上传+摄取）→在开发阶段进行转换（ELT/dbt层）→发布到已发布阶段→查询/构建仪表板。针对

dev

阶段的小型数据集进行开发，然后发布完整数据集用于实际分析（

references/lifecycle-and-rbac.md

）。ELT编辑器是基于dbt（Snowflake）模型树的

transformations

命令组，它将加载的源表转换为流程模型——其命令界面及应用与运行的区别详见

references/transformations.md

。

Critical Rules

关键规则

To make a custom analytical table queryable, register it as a Case-linked data-model table, then RE-INGEST. Process Mining is case-centric: a queryable table must be the
```
Cases
```
root or reach
```
Cases
```
via a foreign key — an unlinked table is rejected at query time (
```
UserError_TableIsDeleted
```
). First check the built-in Case-child slots: Tags
(multi-valued per-case labels:
```
Tag
```
/
```
Tag_type
```
) and Due_dates
(per-case SLA/deadline:
```
Expected_date
```
/
```
Actual_date
```
/
```
On_time
```
/
```
Cost
```
) — populate their dbt models rather than adding a table when your data fits. Otherwise register a custom table with uip pm apps data-model add-table <app> --file <table.json>
, where the file is a DataModelDto entry
```
{ name, primaryKey, foreignKeys:[{table:"Cases",column:"Case_ID"}] }
```
(loose-link a standalone aggregate with a surrogate PK + nullable
```
Case_ID
```
).
```
add-table
```
edits
```
/dev/dataModel
```
(upsert, ETag-safe) then
```
applyCurrentDatamodel
```
; the table only becomes queryable after ingestions create --wait
(a data-model edit takes effect only on the next ingestion). Full recipe + Tags/Due_dates decision table in
```
references/data-model.md
```
.
Match the template to the data — the rest of the pipeline is identical for all app types. A single denormalized log (Case, Activity, Timestamp [+ attributes]) ⇒
```
uipath.custom
```
("Event log"). Otherwise pick the
```
<process>.<system>
```
template matching your source system AND process (Purchase-to-Pay on SAP ⇒
```
uipath.p2p.sap
```
; incidents from ServiceNow ⇒
```
uipath.im.servicenow
```
) — but only when you actually have that system's full multi-table extract, not a single log you exported from it. Every template shares the same model shape and the same mapping→ingest→transform→query machinery; only the expected input tables differ. Discover with
```
app-types list
```
, inspect a template with
```
app-types get
```
. See
```
references/app-types.md
```
.
Patch the
uipath.custom

Cases.sql
optional-column gotcha (custom-only). Source-system templates ship their own correct transformations — this gotcha is specific to the
```
uipath.custom
```
event-log template. The template's
```
models/Cases.sql
```
references
```
Event_log."Case"
```
,
```
"Case_status"
```
,
```
"Case_type"
```
,
```
"Case_value"
```
. A minimal mapping (Case_ID/Activity/timestamp only) doesn't produce those ⇒ dbt
```
000904 invalid identifier
```
. Fix: pull the file, replace the missing refs with
```
cast(null as varchar/float)
```
, push, and transformations apply
.
```
Tags.sql
```
/
```
Due_dates.sql
```
are safe
```
where 1=0
```
stubs.
After a transform-only failure,
apply
— don't re-ingest. The data is already loaded. Fix SQL (
```
transformations get
```
→ edit →
```
transformations update --etag '<the get's ETag>'
```
, or
```
create
```
for a new file, which needs none) then
```
transformations apply
```
(re-transforms loaded data). Re-ingest only when the raw data or the mapping/parse settings change.
A wrong data mapping does NOT mean recreating the app — fix it in place with
apps data-mapping
. The mapping is not create-only:
```
uip pm apps data-mapping get <app> --destination ./mapping.json
```
→ edit →
```
uip pm apps data-mapping update <app> --file ./mapping.json --etag '<etag>'
```
replaces it on an existing app. --etag
is required — pass the
```
Data.ETag
```
that your
```
get
```
returned, which is what proves the edit was based on the version you read; a lost race is refused
```
409 UserError_ETagFileConflict
```
(re-
```
get
```
for the new version and ETag, re-apply, retry), and a table-less file is refused rather than wiping the stored mapping. Unlike a SQL fix (Rule 4), a mapping change is a parse-setting change, so it takes effect only on the next ingestion — re-
```
files upload
```
if the source columns changed, then
```
ingestions create
```
. Only
```
dev
```
is writable (
```
published
```
is read-only). Facts + failure modes in
```
references/pre-flight.md
```
.
Use
--wait
on async commands.
```
ingestions create --wait
```
and
```
transformations apply --wait
```
block to a terminal state, print the dbt/loader error on failure, and exit non-zero — no hand-rolled
```
apps list
```
poll loop.

Query field ids come from
query info
, not column names.

query run

percentile

bodies take the hashed

F__<Table>__<Col>__<hash>

ids. Prefer the sugar:

query run <app> --group-by <col> --metric <col>:<fn>

resolves human names for you (fn ∈

average|count|sum|min|max

Develop on
dev
with a data subset; publish the full dataset. The
```
dev
```
stage is for iterating on the mapping and transformations — keep it fast by loading a small representative subset of the data. Once the model is right, publish so the published stage carries the full dataset for the dashboards and sharing. Query/transform against
```
--stage dev
```
; consumers read the published dashboards. Note CLI
```
query --stage published
```
is currently unreachable (no
```
uip pm
```
path completes a published-stage ingestion) — do CLI querying on
```
dev
```
(
```
references/lifecycle-and-rbac.md
```
).
RBAC is folder/role-based at the platform layer, not the process app itself. A process app lives in a folder; who can view vs. edit vs. publish is governed by Orchestrator/Identity roles and folder assignments — configure it with
```
uipath-admin
```
(roles, role assignments, effective-access) and
```
uipath-platform
```
(folders). See
```
references/lifecycle-and-rbac.md
```
.
```
uip pm
```
itself does not grant access.
Edit a field's data kind / calculated fields with
apps model fields
— and a data-kind mismatch can lock the app open. Change a field's kind (e.g. numeric→duration), rename it, or add a calculated field with
```
uip pm apps model fields set <app> <field> [--kind|--display-name|--expression]
```
(the semantic model; dev-only, and no
--etag
— it merges into the version it just read, so a lost race is fixed by re-running it; a whole-document
```
apps model update
```
does require
```
--etag
```
). Relational/arithmetic operators require both operands to share a data kind, so flipping a field to
```
duration
```
while a metric / calculated field / dashboard filter still compares it to a
```
numeric
```
constant persists an invalid model that throws at dashboard open — the "Must be duration, not numeric, for the 'lt' input" lockout (DNA-46960), which leaves only the data-upload module reachable.
```
fields set
```
/
```
update
```
validate and refuse such an edit with a hint; fix an already-broken app by making the comparison consistent (re-type the field or the constant). Full surface + the data-kind rule in
```
references/model-editing.md
```
.

要使自定义分析表可查询，请将其注册为关联Case的数据模型表，然后重新摄取。 Process Mining是以Case为中心的：可查询表必须是
```
Cases
```
根表，或通过外键关联到
```
Cases
```
——未关联的表在查询时会被拒绝（
```
UserError_TableIsDeleted
```
）。首先检查内置的Case子插槽：Tags
（每个Case的多值标签：
```
Tag
```
/
```
Tag_type
```
）和**
```
Due_dates
```
（每个Case的SLA/截止日期：
Expected_date
/
Actual_date
/
On_time
/
Cost
）——当你的数据符合要求时，填充它们的dbt模型而非添加新表。否则，使用
```
uip pm apps data-model add-table <app> --file <table.json>
```
注册自定义表，其中文件是DataModelDto条目
{ name, primaryKey, foreignKeys:[{table:"Cases",column:"Case_ID"}] }
（使用代理主键+可为空的
Case_ID
松散关联独立聚合表）。
add-table
会编辑
/dev/dataModel
（更新插入，支持ETag安全），然后执行
applyCurrentDatamodel
；只有在执行
```
ingestions create --wait
```
**后，该表才可查询（数据模型编辑仅在下次摄取时生效）。完整方案及Tags/Due_dates决策表详见
```
references/data-model.md
```
。
使模板与数据匹配——所有应用类型的其余流程完全一致。 单个非规范化日志（Case、Activity、Timestamp [+属性]）⇒
```
uipath.custom
```
（“事件日志”）。否则，选择与你的源系统和流程匹配的
```
<process>.<system>
```
模板（SAP上的采购到付款⇒
```
uipath.p2p.sap
```
；ServiceNow的事件⇒
```
uipath.im.servicenow
```
）——但仅当你实际拥有该系统的完整多表提取数据时才使用，而非从该系统导出的单个日志。每个模板共享相同的模型结构和相同的映射→摄取→转换→查询机制；仅预期的输入表有所不同。使用
```
app-types list
```
发现模板，使用
```
app-types get
```
查看模板详情。详见
```
references/app-types.md
```
。
修复
uipath.custom
的
Cases.sql
可选列陷阱（仅自定义模板）。源系统模板自带正确的转换逻辑——此陷阱仅针对
```
uipath.custom
```
事件日志模板。模板的
```
models/Cases.sql
```
引用了
```
Event_log."Case"
```
、
```
"Case_status"
```
、
```
"Case_type"
```
、
```
"Case_value"
```
。最小化映射（仅Case_ID/Activity/timestamp）不会生成这些字段⇒dbt报错
```
000904 invalid identifier
```
。修复方法：拉取文件，将缺失的引用替换为
```
cast(null as varchar/float)
```
，上传文件，然后执行**
```
transformations apply
```
**。
```
Tags.sql
```
/
```
Due_dates.sql
```
是安全的
```
where 1=0
```
存根。
仅转换失败后，执行
apply
——不要重新摄取。数据已加载。修复SQL（
```
transformations get
```
→编辑→
```
transformations update --etag '<获取到的ETag>'
```
，或使用
```
create
```
创建新文件，无需ETag），然后执行
```
transformations apply
```
（重新转换已加载的数据）。仅当原始数据或映射/解析设置更改时，才重新摄取。
错误的数据映射并不意味着要重新创建应用——使用
apps data-mapping
就地修复。映射并非仅可创建：
```
uip pm apps data-mapping get <app> --destination ./mapping.json
```
→编辑→
```
uip pm apps data-mapping update <app> --file ./mapping.json --etag '<etag>'
```
可替换现有应用的映射。--etag
是必填项——传入你的
```
get
```
命令返回的
```
Data.ETag
```
，以此证明编辑基于你读取的版本；冲突会被拒绝（
```
409 UserError_ETagFileConflict
```
，重新
```
get
```
获取新版本和ETag，重新应用更改并重试），无表的文件会被拒绝，避免擦除已存储的映射。与SQL修复（规则4）不同，映射更改属于解析设置更改，因此仅在下次摄取时生效——如果源列更改，重新执行
```
files upload
```
，然后执行
```
ingestions create
```
。仅
```
dev
```
阶段可写（
```
published
```
阶段为只读）。详情及失败模式详见
```
references/pre-flight.md
```
。
在异步命令上使用
--wait
。
```
ingestions create --wait
```
和
```
transformations apply --wait
```
会阻塞直到终端状态，失败时打印dbt/加载器错误，并返回非零退出码——无需手动编写
```
apps list
```
轮询循环。
查询字段ID来自
query info
，而非列名。
```
query run
```
/
```
percentile
```
的请求体需要哈希后的
```
F__<Table>__<Col>__<hash>
```
ID。推荐使用简化方式：
```
query run <app> --group-by <col> --metric <col>:<fn>
```
会自动解析人性化名称（fn ∈
```
average|count|sum|min|max
```
）。
在
dev
阶段使用数据子集进行开发；发布完整数据集。
```
dev
```
阶段用于迭代映射和转换逻辑——通过加载小型代表性子集保持开发速度。模型确定后，发布应用，使published阶段承载完整数据集用于仪表板和共享。针对
```
--stage dev
```
进行查询/转换；用户读取已发布的仪表板。注意当前CLI的
```
query --stage published
```
不可用（没有
```
uip pm
```
路径可完成已发布阶段的摄取）——在
```
dev
```
阶段进行CLI查询（
```
references/lifecycle-and-rbac.md
```
）。
RBAC在平台层基于文件夹/角色，而非流程应用本身。 流程应用位于文件夹中；查看、编辑、发布权限由Orchestrator/Identity角色和文件夹分配管理——使用
```
uipath-admin
```
（角色、角色分配、有效访问权限）和
```
uipath-platform
```
（文件夹）进行配置。详见
```
references/lifecycle-and-rbac.md
```
。
```
uip pm
```
本身不授予访问权限。
使用
apps model fields
编辑字段的数据类型/计算字段——数据类型不匹配会导致应用锁定。使用
```
uip pm apps model fields set <app> <field> [--kind|--display-name|--expression]
```
更改字段类型（例如numeric→duration）、重命名或添加计算字段（语义模型；仅dev阶段可用，无需
--etag
——它会合并到刚读取的版本中，冲突可通过重新运行命令修复；全文档的
```
apps model update
```
需要
```
--etag
```
）。关系/算术运算符要求两个操作数的数据类型相同，因此将字段改为
```
duration
```
时，如果指标/计算字段/仪表板筛选器仍将其与
```
numeric
```
常量比较，会保留无效模型，导致仪表板打开时抛出错误——即“'lt'输入必须为duration类型，而非numeric类型”锁定问题（DNA-46960），此时仅数据上传模块可访问。
```
fields set
```
/
```
update
```
会验证并拒绝此类编辑，并给出提示；修复已损坏的应用需使比较一致（重新设置字段类型或常量类型）。完整命令界面及数据类型规则详见
```
references/model-editing.md
```
。

Quick Start

快速开始

The end-to-end CSV → queryable-app command sequence (discover template → create → upload → ingest → patch transform / fix mapping → query) is in

references/uip-pm-cli.md

从CSV到可查询应用的端到端命令序列（发现模板→创建→上传→摄取→修补转换/修复映射→查询）详见

references/uip-pm-cli.md

。

Extending the model with custom analysis

使用自定义分析扩展模型

The killer use case is your own SQL. Add analytical dbt models with

transformations create <path> --file

(use

update

for existing files; inline intermediates as CTEs if you prefer fewer files), then register each queryable output as a Case-linked data-model table + re-ingest (Rule 1) so

query

can read it. Full recipe + the DataModelDto entry shape (

type

name

primaryKey

foreignKeys

) and the Tags/Due_dates decision table in

references/data-model.md

; the transformation dev loop and dbt/pm_utils notes in

references/transformations.md

; the query AST and sugar in

references/querying.md

核心使用场景是自定义SQL。使用

transformations create <path> --file

添加分析型dbt模型（现有文件使用

update

；如果偏好更少文件，可将中间结果内联为CTE），然后将每个可查询输出注册为关联Case的数据模型表+重新摄取（规则1），以便

query

可以读取。完整方案及DataModelDto条目格式（

type

name

primaryKey

foreignKeys

）、Tags/Due_dates决策表详见

references/data-model.md

；转换开发循环及dbt/pm_utils说明详见

references/transformations.md

；查询AST及简化方式详见

references/querying.md

。

Reference Navigation

参考文档导航

Two layers: the uip pm
CLI reference (how to drive the tool) and the process-mining domain references (what to build and why). Start with a domain reference for the decision; drop into the CLI reference for the mechanics it uses.

File	Read when
`references/uip-pm-cli.md`	CLI mechanics (low-level) — the command-group map, the `Result` / `Code` / `Data` envelope + exit codes, the ETag get-modify-put pattern, `--wait` , `--stage` , `IngestionNeeded` , field-id discovery, and the CSV→queryable-app Quick Start
`references/app-types.md`	choosing/targeting a template — custom vs source-system, why the pipeline is the same for all, what the mapping/extract must contain per family
`references/pre-flight.md`	before any upload — encoding/delimiter/date-format/empty-row checks and the minimal `mapping.json` recipe; also the post-create mapping fix loop ( `apps data-mapping get` / `update` ) and its failure modes
`references/transformations.md`	authoring/fixing dbt models — the `Cases.sql` patch, apply-vs-run, pm_utils macros, Snowflake identifier quoting
`references/data-model.md`	exposing a custom table to `query` /dashboards — the case-centric add-table pattern (DataModelDto + re-ingest) and the Tags/Due_dates decision table
`references/model-editing.md`	editing the app model — a field's data kind (e.g. numeric→duration), calculated fields, the two models (semantic `apps model` vs structural `apps data-model` ), and the data-kind comparison rule that locks an app open (DNA-46960)
`references/querying.md`	pulling numbers out — the aggregate body AST, the `--group-by/--metric` sugar, the `AggregationFunction` enum, and the event-table restriction
`references/lifecycle-and-rbac.md`	dev vs published stages, publishing, and where process-app RBAC is configured

分为两层：uip pm
CLI参考（如何驱动工具）和流程挖掘领域参考（要构建什么及原因）。先查看领域参考文档做决策，再查看CLI参考文档了解具体操作机制。

文件	阅读场景
`references/uip-pm-cli.md`	CLI底层机制——命令组映射、 `Result` / `Code` / `Data` 包+退出码、ETag获取-修改-上传模式、 `--wait` 、 `--stage` 、 `IngestionNeeded` 、字段ID发现，以及CSV→可查询应用的快速开始指南
`references/app-types.md`	选择/定位模板——自定义模板vs源系统模板，为何所有应用类型的流程一致，各类型模板的映射/提取需包含的内容
`references/pre-flight.md`	上传前准备——编码/分隔符/日期格式/空行检查，以及最小化 `mapping.json` 方案；还包括创建后映射修复循环（ `apps data-mapping get` / `update` ）及其失败模式
`references/transformations.md`	编写/修复dbt模型—— `Cases.sql` 修补、应用vs运行、pm_utils宏、Snowflake标识符引用
`references/data-model.md`	向 `query` /仪表板暴露自定义表——以Case为中心的添加表模式（DataModelDto+重新摄取）及Tags/Due_dates决策表
`references/model-editing.md`	编辑应用模型——字段的数据类型（例如numeric→duration）、计算字段、两种模型（语义 `apps model` vs结构化 `apps data-model` ），以及导致应用锁定的数据类型比较规则（DNA-46960）
`references/querying.md`	提取数据——聚合请求体AST、 `--group-by/--metric` 简化方式、 `AggregationFunction` 枚举，以及事件表限制
`references/lifecycle-and-rbac.md`	开发vs已发布阶段、发布操作，以及流程应用RBAC的配置位置

Anti-patterns — what NOT to do

反模式——请勿执行以下操作

Repurposing
Tags.sql
/
Due_dates.sql
to smuggle an unrelated analytics table through a pre-registered entity. Fine — intended, even — to populate them with their real semantics (per-case labels; per-case SLAs); wrong to jam a weekly aggregate into
```
Due_dates
```
to dodge add-table. It corrupts those features and fights their primary key. Register a real Case-linked table instead (Rule 1).
Adding a data-model table with no link to
Cases
— it registers but every query fails
```
UserError_TableIsDeleted
```
. Give a standalone table a surrogate PK + nullable
```
Case_ID
```
FK to
```
Cases
```
(Rule 1).
Forgetting to re-ingest after
add-table
. The data-model edit is inert until the next
```
ingestions create
```
re-materializes the tables (Rule 1).
Re-uploading + re-ingesting after a transform-only failure. The data is loaded; fix the SQL and
```
transformations apply
```
. Re-ingest only when raw data or parse settings change (Rule 4).
Deleting and recreating an app to fix a mapping mistake (or telling the user that's the only option). The mapping is editable after creation —
```
apps data-mapping get
```
/
```
update
```
(Rule 5). Recreating also throws away the transformations you already patched.
transformations apply
after a mapping change.
```
apply
```
only re-runs SQL over already-parsed data; a new mapping changes how the raw file is parsed, so it needs
```
ingestions create
```
(Rule 5). This is the mirror of Rule 4 — get the direction wrong and the edit silently appears to do nothing.
Re-
get
ting a resource just to harvest a fresh
--etag
for a rejected write. That defeats the
```
If-Match
```
guard — it makes the precondition pass no matter who wrote in between, silently overwriting them. A 409/412 means the resource moved: re-
```
get
```
the latest document, re-apply your change on top of that, then write with the ETag that read returned. Never pair a stale local file with a freshly fetched ETag (
```
references/uip-pm-cli.md
```
).

Hand-rolling an
apps list
poll loop. Use

--wait

ingestions create

transformations apply

(Rule 6).

Passing column names in a raw
query run
body, or hand-writing the aggregate AST. Bodies take hashed field ids from
```
query info
```
; use the
```
--group-by/--metric
```
sugar (Rule 7).
Patching
Cases.sql
on a source-system template. That gotcha is
```
uipath.custom
```
-only; source templates ship correct transformations — feed the expected extract and extend, don't rewrite (Rule 3).
Using a source template for a single flat log (or
```
uipath.custom
```
for a full multi-table extract). Match the template to the data shape (Rule 2).
Iterating on the full dataset. Develop on
```
dev
```
with a small subset; publish the full data (Rule 8).
Changing a field's data kind while a comparison still uses the old kind. Flipping a field to
```
duration
```
(or any kind) while a metric / calculated field / dashboard filter compares it to a constant of the old kind persists an invalid model that locks the app open (Rule 10). Reconcile the comparison first — re-type the field or the constant.

复用
Tags.sql
/
Due_dates.sql
将无关的分析表通过预注册实体偷偷引入。填充符合其实际语义的数据（每个Case的标签；每个Case的SLA）是可行的，甚至是预期的；但将每周聚合数据塞入
```
Due_dates
```
以避免添加新表是错误的。这会破坏这些功能，并与它们的主键冲突。应注册真正关联Case的表（规则1）。
添加未关联
Cases
的数据模型表——表会注册成功，但所有查询都会失败（
```
UserError_TableIsDeleted
```
）。为独立表添加代理主键+可为空的
```
Case_ID
```
外键关联到
```
Cases
```
（规则1）。
添加表后忘记重新摄取——数据模型编辑在下次
```
ingestions create
```
重新生成表前不会生效（规则1）。
仅转换失败后重新上传+重新摄取——数据已加载；修复SQL并执行
```
transformations apply
```
。仅当原始数据或解析设置更改时才重新摄取（规则4）。
删除并重新创建应用以修复映射错误（或告知用户这是唯一选项）。映射可在创建后编辑——使用
```
apps data-mapping get
```
/
```
update
```
（规则5）。重新创建还会丢失你已修补的转换逻辑。
映射更改后执行
transformations apply
——
```
apply
```
仅对已解析的数据重新运行SQL；新映射会更改原始文件的解析方式，因此需要执行
```
ingestions create
```
（规则5）。这是规则4的镜像——方向错误会导致编辑看似无效。
仅重新获取资源以获取新的
--etag
用于被拒绝的写入——这会破坏
```
If-Match
```
保护机制——无论期间谁进行了写入，前置条件都会通过，从而静默覆盖他人的更改。409/412错误意味着资源已更改：重新获取最新的文档，在其基础上重新应用你的更改，然后使用读取返回的ETag进行写入。切勿将过时的本地文件与新获取的ETag配对（
```
references/uip-pm-cli.md
```
）。
手动编写
apps list
轮询循环——在
```
ingestions create
```
/
```
transformations apply
```
上使用
```
--wait
```
（规则6）。
在原始
query run
请求体中传入列名，或手动编写聚合AST——请求体需要来自
```
query info
```
的哈希字段ID；使用
```
--group-by/--metric
```
简化方式（规则7）。
修补源系统模板的
Cases.sql
——该陷阱仅针对
```
uipath.custom
```
；源模板自带正确的转换逻辑——提供预期的提取数据并扩展，不要重写（规则3）。
对单个扁平日志使用源模板（或对完整多表提取数据使用
```
uipath.custom
```
）——使模板与数据结构匹配（规则2）。
在完整数据集上迭代开发——在
```
dev
```
阶段使用小型子集进行开发；发布完整数据（规则8）。
更改字段数据类型时仍使用旧类型进行比较——将字段改为
```
duration
```
（或任何类型）时，如果指标/计算字段/仪表板筛选器仍将其与旧类型的常量比较，会保留无效模型，导致应用锁定（规则10）。先调整比较逻辑——重新设置字段类型或常量类型。",