uipath-process-mining

name	uipath-process-mining
description	UiPath Process Mining via `uip pm` — build and operate a process app end-to-end from a CSV / event log: templates, data mapping, upload, ingest, the dbt (Snowflake) transformation layer, publish, and query it (metrics, percentiles, RCA). Covers `uipath.custom`, the `Cases.sql` optional-column gotcha, Case-linked data-model tables (add-table + re-ingest), the apply-not-reingest fix loop, fixing a wrong mapping in place via `apps data-mapping get|update` (no app rebuild), and editing the app model via `apps model fields` — a field's data kind / calculated fields, including the numeric→duration mismatch that locks dashboards open. For Orchestrator/Data Fabric/Integration Service→uipath-platform. For `.flow`/Maestro→uipath-maestro-flow. For IXP→uipath-ixp.
when_to_use	User mentions process mining, a process app, an event log, `uip pm`, mining a CSV/log, ingesting data into one, dbt/SQL transformations, steps-to-resolution / throughput / variant / rework analysis, or querying one. Also 'build a process app from this data', 'ingest this log', 'fix my Cases.sql', 'why can't I query my custom table', 'add a table to the data model', 'group by X average Y', 'fix/change/read my data mapping', 'wrong date format in the mapping', 'change a field's data kind', 'set a field to duration', 'add a calculated field/metric', 'my dashboards won't open', 'Must be duration not numeric'. For Orchestrator/Data Fabric→uipath-platform; `.flow`→uipath-maestro-flow; IXP→uipath-ixp.
allowed-tools	Bash, Read, Write, Glob, Grep

UiPath Process Mining — uip pm Assistant

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.

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.
• Manage the app lifecycle — stages (dev → published), RBAC, deletion.

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.

Critical Rules

1. 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.

2. 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 .

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.

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.

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

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-getting 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 on / (Rule 6).