Uipath Process Mining

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 references/app-types.md.

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

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

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

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

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

8. 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. Iterate with --stage dev; consumers read the published dashboards. query --stage published works once that stage has a completed ingestion — after apps publish reports IngestionNeeded: true, run ingestions create <app> --stage published --wait. Querying published is optional, not a required step (references/lifecycle-and-rbac.md).

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

10. 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, 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.