uip pm apps data-model, uip pm apps model

Syntax and options for editing a Process Mining app's structural data model and semantic model — tables, fields, dashboards, and metrics — with `uip pm apps data-model` and `uip pm apps model`.

Part of the uip pm tool. This page covers the two model-editing surfaces on a process app:

• apps data-model — the structural table graph: which tables exist, their primary/foreign keys, and how they join to Cases.
• apps model — the semantic model: fields and their data kinds, calculated fields, dashboards, and metrics. Includes fields, dashboards, and metrics sub-groups for targeted edits, plus get/update for the whole document.
• apps data-mapping — the app's input data mapping: which source table/column feeds which target field. Distinct from the data model above (that's the queryable table graph after mapping).

Every write here is ETag-guarded — see Concepts on the parent page.

Synopsis

uip pm apps data-model get <app-id> [--stage dev|published] [--destination <file>]
uip pm apps data-model add-table <app-id> --file <json-file> [--stage dev|published]

uip pm apps model get <app-id> [--stage dev|published] [--destination <file>]
uip pm apps model update <app-id> --file <json-file> --etag <etag>

uip pm apps model fields list <app-id> [--stage dev|published]
uip pm apps model fields set <app-id> <field-id> [--kind <kind>] [--display-name <text>] [--expression <json>] [--table <table-id>]
uip pm apps model fields remove <app-id> <field-id>

uip pm apps model dashboards list <app-id> [--stage dev|published]
uip pm apps model dashboards get <app-id> [--dashboard <id-or-name>] [--stage dev|published] [--destination <file>]
uip pm apps model dashboards update <app-id> [--file <json-file>] [--metrics <json-file>] --etag <etag> [--dashboard <id-or-name>]

uip pm apps model metrics list <app-id> [--stage dev|published]

uip pm apps data-mapping get <app-id> [--stage dev] [--destination <file>]
uip pm apps data-mapping update <app-id> --file <json-file> --etag <etag> [--stage dev]

uip pm apps data-model get

Get the app's structural data model (tables with primary/foreign keys and column roles). Returns the model's ETag for reference; add-table itself takes no --etag because it re-reads and merges its own change.

Arguments

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

Options

Long	Value	Default	Description
--stage <stage>	dev | published	dev	App stage.
--destination <local-file>	path	—	Write the model JSON to this file instead of the output envelope.

Data shape (--output json)

{ "Code": "PmAppsDataModelGet", "Data": { "AppId": "9c46289e", "ETag": "W/\"3\"", "Model": {} } }

Destination replaces Model when --destination is passed.

uip pm apps data-model add-table

Register a custom dbt model as a queryable data-model table. Process Mining is case-centric: a queryable table must be the Cases root or link to it — give the table a (nullable) Case_ID column with a foreign key to Cases to loosely link a standalone analytical table. Re-ingest afterward to materialize it. Takes no --etag: it reads the current data model itself and merges into exactly that document, so a write landing in between still conflicts and the command simply re-runs.

Arguments

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

Options

Long	Value	Required	Description
--file <json-file>	path	yes	JSON with the table(s) to add — a single data-model table, an array, or a { tables } object. Each: { name, primaryKey, foreignKeys: [{ table: "Cases", column: "Case_ID" }] } (type defaults to "Object").
--stage <stage>	dev | published	no	Default dev.

A table is matched by name: an existing entry is replaced, a new one appended.

Example

uip pm apps data-model add-table 9c46289e --file ./Workload_weekly.table.json

Data shape (--output json)

{
  "Code": "PmAppsDataModelAddTable",
  "Data": {
    "AppId": "9c46289e",
    "AddedTables": ["Workload_weekly"],
    "IngestionNeeded": true,
    "Instructions": "Re-ingest to materialize the table(s): uip pm ingestions create 9c46289e --wait — then query them. Run 'uip pm apps publish 9c46289e' to push to dashboards."
  }
}

Fails with UserError_TableIsDeleted-style rejection at the query layer if the table has no path to Cases. A nameless table entry, or a file with no usable table, fails client-side before any write.

uip pm apps model get

Get the app's semantic model (fields with data kinds, calculated fields, metrics, and the dashboards view) — the shape update takes. Returns the model's ETag, which model update requires as --etag.

Arguments

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

Options

Long	Value	Default	Description
--stage <stage>	dev | published	dev	App stage.
--destination <local-file>	path	—	Write the model JSON to this file instead of the output envelope.

Data shape (--output json)

{ "Code": "PmAppsModelGet", "Data": { "AppId": "9c46289e", "ETag": "W/\"3\"", "Model": {} } }

uip pm apps model update

Replace the whole app model from a local JSON file. Applies on dev only. For a single field prefer apps model fields set, which edits in place; a full replace has to carry the ETag of the model get it was written from — fetching a fresh ETag here would defeat the concurrency check.

Arguments

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

Options

Long	Value	Required	Description
--file <json-file>	path	yes	Local JSON file with the full model (as returned by model get).
--etag <etag>	string	yes	ETag of the model this edit is based on.

Data shape (--output json)

{ "Code": "PmAppsModelUpdate", "Data": { "AppId": "9c46289e", "Versions": [4], "Instructions": "Model saved on dev. Run 'uip pm apps publish 9c46289e' to push it to the dashboards; if a field's data kind changed, re-ingest so the data matches: uip pm ingestions create 9c46289e --wait." } }

A stale --etag fails with a conflict — re-read via model get, redo the edit, and retry. A UnsupportedOperatorArgumentDataKind error means a dashboard filter, calculated field, or metric threshold still compares a field to a constant of its old data kind — fix or remove that comparison before changing the kind.

uip pm apps model fields list

List every field across the app's tables with its data kind and whether it's a mapped column or a calculated field.

Arguments

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

Options

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

Data shape (--output json)

{ "Code": "PmAppsFieldsList", "Data": [{ "Table": "Cases", "Id": "Case_status", "Display": "Status", "Kind": "nominal", "Type": "column" }] }

Type is "column" (mapped) or "calculated".

uip pm apps model fields set

Create or edit a field (ETag-safe internally — reads and merges its own base). Change its data kind, rename it, or turn it into a calculated field.

Arguments

Name	Required	Purpose
<app-id>	yes	Process app ID.
<field-id>	yes	Field ID.

Options

Long	Value	Description
--kind <kind>	ordinal|nominal|numeric|datetime|boolean|percentage|currency|duration	Data kind. (id/ref are structural and not settable.)
--display-name <text>	string	Display name.
--expression <json>	JSON (inline or @file.json)	Calculated-field expression node. Providing it turns the field into a calculated field.
--table <table-id>	string	Target table — required only when creating a new field.

At least one of --kind/--display-name/--expression is required. Creating a field requires --table, --expression, and --kind; mapped columns can't be created this way (they come from ingested data). Setting --expression on an existing mapped column is rejected — create a new calculated field with a different ID instead. A create whose ID collides with a field in a different table is rejected rather than silently editing that field.

Example

uip pm apps model fields set 9c46289e Case_status --kind ordinal

Data shape (--output json)

{ "Code": "PmAppsFieldsSet", "Data": { "AppId": "9c46289e", "Field": "Case_status", "Action": "updated", "Table": "Cases", "Versions": [4], "Instructions": "Model saved on dev. Run 'uip pm apps publish 9c46289e' to push it to the dashboards; if a field's data kind changed, re-ingest so the data matches: uip pm ingestions create 9c46289e --wait." } }

Action is "created" or "updated".

uip pm apps model fields remove

Remove a field from the model.

Arguments

Name	Required	Purpose
<app-id>	yes	Process app ID.
<field-id>	yes	Field ID.

Data shape (--output json)

{ "Code": "PmAppsFieldsRemove", "Data": { "AppId": "9c46289e", "Field": "Case_status", "Table": "Cases", "Versions": [4], "Instructions": "..." } }

uip pm apps model dashboards

The dashboard-shaped view of the same model document model get/update round-trip — list/get/update work on view.dashboards.

uip pm apps model dashboards list

List the dashboards of a process app.

Name/Option	Required	Purpose
<app-id>	yes	Process app ID.
--stage <stage>	no	dev | published, default dev.

{ "Code": "PmAppsDashboardsList", "Data": [{ "Id": "overview", "Name": "Overview", "Layout": "three-left-one-right", "Charts": 4, "Metrics": 5, "IsVisible": true }] }

Charts is the flattened count of the dashboard's chart-id matrix.

uip pm apps model dashboards get

Get the dashboards of a process app, with the ETag update needs.

Long	Value	Description
--stage <stage>	dev|published	Default dev.
--dashboard <id-or-name>	string	Return only this dashboard instead of the whole view section. Matched by ID first, then by exact name — an ambiguous name (more than one dashboard sharing it) fails, asking you to select by ID.
--destination <local-file>	path	Write JSON to this file instead of the envelope.

uip pm apps model dashboards get 9c46289e --dashboard 'Overview' --destination ./dashboard.json

{ "Code": "PmAppsDashboardsGet", "Data": { "Dashboard": "Overview", "ETag": "W/\"3\"", "Destination": "./dashboard.json" } }

uip pm apps model dashboards update

Update the dashboards of a process app from a local JSON file. Dev stage only.

Long	Value	Required	Description
--file <local-file>	path	no*	One dashboard when --dashboard is given, otherwise the whole view section.
--metrics <local-file>	path	no*	JSON array of metric definitions to add or replace by ID — written in the same request as --file, so a chart it introduces can reference a metric added in the same write.
--etag <etag>	string	yes	ETag of the model this edit is based on.
--dashboard <id-or-name>	string	no	Which dashboard --file replaces — requires --file; passing it without --file is rejected.

* At least one of --file/--metrics is required.

uip pm apps model dashboards update 9c46289e --dashboard 'Overview' --file ./dashboard.json --etag 'W/"3"'

{ "Code": "PmAppsDashboardsUpdate", "Data": { "Dashboard": "Overview", "Versions": [4], "Instructions": "Saved on dev. Run 'uip pm apps publish 9c46289e' to push the change to the dashboards; if the publish reports IngestionNeeded, re-ingest with 'uip pm ingestions create 9c46289e --wait'." } }

uip pm apps model metrics list

List the metrics a chart can reference, from the app's data model. Add or replace one with dashboards update --metrics.

Name/Option	Required	Purpose
<app-id>	yes	Process app ID.
--stage <stage>	no	dev|published, default dev.

{ "Code": "PmAppsMetricsList", "Data": [{ "Id": "avg_throughput", "Display": "Avg. throughput", "Aggregation": "AVERAGE", "Argument": "Case_throughput_time" }] }

uip pm apps data-mapping get

Get the app's input data mapping — the same shape apps create --data-mapping takes, so it can be edited and pushed back with data-mapping update. Returns the mapping's ETag, which that update requires as --etag.

Long	Value	Default	Description
--stage <stage>	dev | published	dev	App stage to read.
--destination <local-file>	path	—	Write the mapping JSON to this file instead of the output envelope.

uip pm apps data-mapping get 9c46289e --destination ./mapping.json

{ "Code": "PmAppsDataMappingGet", "Data": { "AppId": "9c46289e", "ETag": "W/\"639204059477096903\"", "Destination": "./mapping.json" } }

uip pm apps data-mapping update

Replace the app's input data mapping from a local JSON file (ETag-safe) — fix a wrong mapping in place instead of recreating the app. Applies on the next ingestion; unlike a transformation fix, a mapping change governs how the raw file is parsed, so transformations apply cannot apply it retroactively.

Options

Long	Value	Required	Description
--file <json-file>	path	yes	Full input data mapping ({ "Tables": [...] }) — replaces the stored mapping outright. Same per-field defaulting as apps create --data-mapping.
--etag <etag>	string	yes	ETag of the mapping this edit is based on.
--stage <stage>	dev	no	Only dev is writable — the backend serves GET on both stages but only accepts the write on dev.

uip pm apps data-mapping update 9c46289e --file ./mapping.json --etag 'W/"639204059477096903"'

{ "Code": "PmAppsDataMappingUpdate", "Data": { "AppId": "9c46289e", "Tables": ["Event_log"], "IngestionNeeded": true, "Instructions": "Re-ingest for the new mapping to take effect: uip pm ingestions create 9c46289e --wait. Re-upload first (uip pm files upload) only if the source columns changed." } }

A stale --etag fails with a conflict — re-read via data-mapping get, redo the edit, and retry. A mapping file with no tables in it fails client-side rather than wiping the app's mapping.

Related

• uip pm — overview and apps CRUD.
• ingestions & transformations — materialize a data-model or field change.
• conformance, deviations & query — analyze the resulting data.

See also

• Global options
• Exit codes