# uip pm

> Commands for managing Process Mining process apps, data ingestion, transformations, and analysis using the `uip pm` tool.

`uip pm` is the Process Mining tool: it creates and manages process apps (mined process models built from event-log data), uploads and ingests source data, runs dbt transformations, and analyzes the result (conformance against a reference model, accepted deviations, ad hoc queries). `pm` is the command prefix; the underlying package is `@uipath/pm-tool`.

A process app moves through a `dev` stage (where you author its structure) and a `published` stage (what dashboards/consumers see) — most verbs take `--stage dev|published` (default `dev`). Every command requires `uip login` first.

## This resource spans four pages

- **This page** — concepts, `apps` (create/list/get/delete/publish), `app-types`, `files`, `simulations`.
- [`apps model`](./uip-pm-apps-model.md) — the ETag-guarded structural/semantic model editing surface: `apps data-model`, `apps model` (get/update/fields/dashboards/metrics).
- [`ingestions` & `transformations`](./uip-pm-ingestion.md) — trigger and inspect data loads and dbt builds.
- [`conformance`, `deviations` & `query`](./uip-pm-analysis.md) — analyze a mined app: conformance rate, accepted deviations, ad hoc data queries.

## Concepts

- **ETag-guarded writes.** Every write to an app's data model, semantic model, or a transformation file requires an `--etag` from a prior `get` (or is itself a read-modify-write that fetches its own base). A stale ETag fails with a conflict; the fix is to re-read, redo the edit, and retry — never re-fetch a fresh ETag just to force the write through, since that silently clobbers whatever changed in between.
- **Dev vs. published.** Structural/semantic edits, ingestion, and transformations only apply to `dev`. `apps publish` pushes dev's current model to the published/dashboard layer; `apps changes` previews what would move.
- **`--wait` polling.** `ingestions create` and `transformations apply`/`run` accept `--wait` (`--timeout`, default `1800`s; `--poll-interval`, default `5`s) to block until the run reaches a terminal state, printing the real dbt/loader error on failure instead of just exiting.

## Synopsis

```text
uip pm apps list [--stage dev|published]
uip pm apps get <app-id> [--stage dev|published]
uip pm apps create <name> --type <app-type-key> [--type-version <v>] [--miner directly-follows|inductive|bpmn] [--description <text>] [--data-mapping <json-file>]
uip pm apps delete <app-id> -y
uip pm apps publish <app-id>
uip pm apps changes <app-id>
uip pm apps publications <app-id> [--limit <n>] [--since-version <v>]
uip pm app-types list
uip pm app-types get <app-type-key> <app-type-version>
uip pm files upload <app-id> <file-path> [--stage dev|published] [--input-table <name>]
uip pm simulations list <app-id> [--stage dev|published]
```

## uip pm apps list

List process apps.

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` \| `published` | `dev` | App stage to list. |

### Example

```bash
uip pm apps list
```

### Data shape (--output json)

```json
{ "Code": "PmAppsList", "Data": [{ "Id": "9c46289e", "Name": "Sample dataset" }] }
```

## uip pm apps get

Get one process app: its status, last ingestion, and build state.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` \| `published` | `dev` | App stage to read. |

### Example

```bash
uip pm apps get 9c46289e
```

### Data shape (--output json)

```json
{
  "Code": "PmAppsGet",
  "Data": {
    "Id": "9c46289e",
    "Name": "Sample dataset",
    "AppStatus": "CREATED",
    "LastIngestion": { "Id": "1d7e1421", "Status": "SUCCESS" }
  }
}
```

## uip pm apps create

Create a process app from an app template (see `app-types list`).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<name>` | yes | App name. |

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--type <app-type-key>` | string | **yes** | App template key, e.g. `uipath.custom`. |
| `--type-version <version>` | string | no | Template version. Defaults to the latest available. |
| `--miner <miner>` | `directly-follows` \| `inductive` \| `bpmn` | no | Process miner. Default `directly-follows`. Only `inductive`/`bpmn` produce a reference model, which `conformance`/`deviations` need. |
| `--description <text>` | string | no | App description. |
| `--data-mapping <json-file>` | path | no | JSON file with the input data mapping (tables/fields). Missing `IsNotNull`/`IsUnique`/`DataTypeSettings` per field are defaulted automatically. |

### Example

```bash
uip pm apps create "Sample dataset" --type uipath.custom --data-mapping ./mapping.json
```

### Data shape (--output json)

```json
{
  "Code": "PmAppsCreate",
  "Data": { "AppId": "9c46289e-e2e3-4da4-a2ea-95c98f719ff7", "Name": "Sample dataset", "Type": "uipath.custom" }
}
```

## uip pm apps delete

Delete a process app.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |

### Options

| Long | Value | Description |
|---|---|---|
| `-y, --yes` | flag | Confirm this irreversible operation. Required — the CLI never prompts. |

### Example

```bash
uip pm apps delete 9c46289e --yes
```

### Data shape (--output json)

```json
{ "Code": "PmAppsDelete", "Data": { "AppId": "9c46289e", "Status": "Deleted" } }
```

## uip pm apps publish

Publish dev changes to the dashboards/query layer.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |

### Example

```bash
uip pm apps publish 9c46289e
```

### Data shape (--output json)

```json
{ "Code": "PmAppsPublish", "Data": { "AppId": "9c46289e", "Changes": {}, "IngestionNeeded": true, "Hint": "Published changes need data — run 'uip pm ingestions create <app> --wait' to load them into the dashboards." } }
```

`Hint` is present only when `IngestionNeeded` is `true`.

## uip pm apps changes

Show which parts of dev are not published yet (dashboards, transformations, BPMN).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |

### Example

```bash
uip pm apps changes 9c46289e
```

### Data shape (--output json)

```json
{ "Code": "PmAppsChanges", "Data": { "AppId": "9c46289e", "ModelVersion": 3, "Changes": {}, "IngestionNeeded": false } }
```

## uip pm apps publications

List the publish history of a process app.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |

### Options

| Long | Value | Description |
|---|---|---|
| `--limit <number>` | integer | Max publications to return. |
| `--since-version <model-version>` | integer | Only return publications newer than this model version. |

### Data shape (--output json)

```json
{ "Code": "PmAppsPublications", "Data": [] }
```

## uip pm app-types

Discover process app templates. Not stage-scoped — templates are tenant-global.

### uip pm app-types list

List available app templates at their latest version.

```bash
uip pm app-types list
```

```json
{ "Code": "PmAppTypesList", "Data": [{ "AppTypeKey": "uipath.custom", "Version": "2604.192.1-ci.5" }] }
```

### uip pm app-types get

Get the full app model of a template version.

| Name | Required | Purpose |
|---|---|---|
| `<app-type-key>` | yes | App template key. |
| `<app-type-version>` | yes | Template version. |

```bash
uip pm app-types get uipath.custom 2604.192.1-ci.5
```

```json
{ "Code": "PmAppTypesGet", "Data": {} }
```

## uip pm files upload

Upload a data file to a process app via chunked blob upload (5 MB parts, 4 concurrent).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |
| `<file-path>` | yes | Local path to the data file. |

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` \| `published` | `dev` | App stage to upload to. |
| `--input-table <name>` | string | — | Target input table the file belongs to (e.g. `Event_log`). |

### Example

```bash
uip pm files upload 9c46289e ./Event_log.csv --input-table Event_log
```

### Data shape (--output json)

```json
{
  "Code": "PmFilesUpload",
  "Data": { "Filename": "Event_log/.../Event_log.csv", "UploadId": "...", "Size": 12345, "Parts": 1, "InputTable": "Event_log" }
}
```

## uip pm simulations list

Read the process simulations (what-if scenarios) saved on a process app. Read-only — there is no `create`/`update`/`delete`; simulations are authored elsewhere and only listed here. Served by a different API (app-scoped PMT, token-exchanged) than the rest of this tool.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` \| `published` | `dev` | App stage. |

### Example

```bash
uip pm simulations list 9c46289e
```

### Data shape (--output json)

```json
{
  "Code": "PmSimulationsList",
  "Data": [
    {
      "DefinitionMetadata": { "Name": "Two more approvers", "SimulationId": "bfd3d274-...", "IngestionId": "7792c4cd-...", "ProcessId": "Process" },
      "RunMetadata": { "Status": "successWithWarnings", "NumberOfCases": 1000, "NumberOfRuns": 40 }
    }
  ]
}
```

## Related

- [`apps model`](./uip-pm-apps-model.md) — edit the data model, semantic model, fields, dashboards, and metrics.
- [`ingestions` & `transformations`](./uip-pm-ingestion.md) — load data and run dbt.
- [`conformance`, `deviations` & `query`](./uip-pm-analysis.md) — analyze a mined app.

## See also

- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)