|
| 1 | +# Trace Decisions (`uip traces decisions`) |
| 2 | + |
| 3 | +Record who decided what on a trace, field by field, and read it back. A decision holds the accepted outcome, the decided fields (proposed value, final value, disposition, proposer), the actor, and optional process context. |
| 4 | + |
| 5 | +## Commands |
| 6 | + |
| 7 | +| Command | Purpose | |
| 8 | +|---------|---------| |
| 9 | +| `create` | Write one or more decisions to a trace. Writing an existing `decisionId` replaces it | |
| 10 | +| `get <id>` | Read one decision by decision ID | |
| 11 | +| `list` | Query decisions by trace, process, instance, element, platform, actor, outcome, origin, or time | |
| 12 | + |
| 13 | +Output keeps the API's camelCase keys, so `get` output is valid `create --input` data. |
| 14 | + |
| 15 | +## Critical rules |
| 16 | + |
| 17 | +1. `create` always needs `--trace-id` (32-char hex or GUID) and `--folder-key`. Take the folder key from the user or from `uip or folders get`; never invent one. |
| 18 | +2. Every field in a decision needs `proposedBy` (`identity` + `kind`). Without it the API returns HTTP 400. |
| 19 | +3. `decisionId` is 16 lowercase hex characters (an OTEL span ID). Omit `--id` to get a generated one. Any other format returns HTTP 400. |
| 20 | +4. Pass `--input <file>` for batches or decisions with `sourceAsset`, `implicitSignals`, or dispositions that differ per field. Use flags only for one decision whose fields share a disposition and proposer. The two forms cannot be mixed. |
| 21 | +5. Reuse a `decisionId` only to replace that decision. A second write with the same ID overwrites the first. |
| 22 | +6. Read the `create` result: it returns one `{ decisionId, feedbackId }` per decision. Confirm with `get` or `list` before reporting success. |
| 23 | +7. On HTTP 500 repeat the identical command once. A write is idempotent per `decisionId`, so a repeat does not duplicate. |
| 24 | +8. Use only the logged-in session. Never ask for, paste, or echo a token. |
| 25 | + |
| 26 | +## create |
| 27 | + |
| 28 | +From a file (one decision object or an array; `-` reads stdin): |
| 29 | + |
| 30 | +```bash |
| 31 | +uip traces decisions create \ |
| 32 | + --trace-id <TRACE_ID> \ |
| 33 | + --input <DECISIONS_FILE> \ |
| 34 | + --folder-key <FOLDER_KEY> \ |
| 35 | + --output json |
| 36 | +``` |
| 37 | + |
| 38 | +From flags (one decision; every `--field` shares the disposition and proposer): |
| 39 | + |
| 40 | +```bash |
| 41 | +uip traces decisions create \ |
| 42 | + --trace-id <TRACE_ID> \ |
| 43 | + --outcome "<ACCEPTED_OUTCOME>" \ |
| 44 | + --actor <ACTOR_IDENTITY> \ |
| 45 | + --field <FIELD_NAME>=<VALUE> \ |
| 46 | + --folder-key <FOLDER_KEY> \ |
| 47 | + --output json |
| 48 | +``` |
| 49 | + |
| 50 | +| Flag | Required | Notes | |
| 51 | +|------|----------|-------| |
| 52 | +| `--trace-id` | Yes | 32-char hex or GUID | |
| 53 | +| `--folder-key` | Yes | | |
| 54 | +| `--input` | One of `--input` or flags | JSON file; `-` for stdin | |
| 55 | +| `--outcome` | With flags | Accepted outcome | |
| 56 | +| `--actor` | With flags | Identity of whoever decided | |
| 57 | +| `--field name=value` | With flags, repeatable | Value read as JSON when valid (`1065` is a number), else text | |
| 58 | +| `--id` | No | Decision ID, 16 lowercase hex characters. Default: generated | |
| 59 | +| `--actor-kind` | No | `Automation`, `Human`, `Rule`, `Agent`. Default `Human` | |
| 60 | +| `--platform` | No | `ActionCenter`, `CodedApp`, `VerticalUi`. Default `ActionCenter` | |
| 61 | +| `--disposition` | No | `Accepted`, `LightlyEdited`, `Rewritten`, `Rejected`, `Ignored`. Default `Accepted` | |
| 62 | +| `--proposed-by` | No | Who proposed the `--field` values. Default: the actor | |
| 63 | +| `--proposed-by-kind` | No | `Automation`, `Person`, `Agent`, `Team`. Default `Person` | |
| 64 | +| `--rejected-outcome` | No | Repeatable | |
| 65 | +| `--evidence` | No | Repeatable explicit evidence line | |
| 66 | +| `--timestamp` | No | ISO 8601. Default: now | |
| 67 | +| `--process-key` / `--process-version` / `--instance-id` / `--element-id` | No | Process context | |
| 68 | +| `--profile <name>` | No | Named login profile | |
| 69 | + |
| 70 | +## Input file shape |
| 71 | + |
| 72 | +```json |
| 73 | +[ |
| 74 | + { |
| 75 | + "decisionId": "<DECISION_ID>", |
| 76 | + "data": { |
| 77 | + "<FIELD_NAME>": { |
| 78 | + "proposedValue": "<PROPOSED>", |
| 79 | + "finalValue": "<FINAL>", |
| 80 | + "disposition": "Rewritten", |
| 81 | + "proposedBy": { "identity": "<PROPOSER>", "kind": "Agent" }, |
| 82 | + "sourceAsset": { "kind": "Process", "id": "<ASSET_ID>", "version": "<VERSION>" } |
| 83 | + } |
| 84 | + }, |
| 85 | + "actor": { "identity": "<ACTOR_IDENTITY>", "kind": "Human" }, |
| 86 | + "acceptedOutcome": "<ACCEPTED_OUTCOME>", |
| 87 | + "rejectedOutcomes": ["<REJECTED_OUTCOME>"], |
| 88 | + "decisionTimestamp": "<ISO_8601_TIMESTAMP>", |
| 89 | + "explicitEvidences": ["<EVIDENCE>"], |
| 90 | + "implicitSignals": { "<KEY>": "<VALUE>" }, |
| 91 | + "processInstanceMetadata": { |
| 92 | + "processKey": "<PROCESS_KEY>", |
| 93 | + "processVersion": "<PROCESS_VERSION>", |
| 94 | + "instanceId": "<INSTANCE_ID>", |
| 95 | + "elementId": "<ELEMENT_ID>" |
| 96 | + }, |
| 97 | + "platform": "ActionCenter" |
| 98 | + } |
| 99 | +] |
| 100 | +``` |
| 101 | + |
| 102 | +Required per decision: `decisionId`, `data`, `actor`, `acceptedOutcome`, `decisionTimestamp`, `platform`. Required per field: `disposition`, `proposedBy`. `sourceAsset.kind` is one of `Agent`, `Automation`, `Process`, `Rule`, `Ontology`, `Knowledge`. |
| 103 | + |
| 104 | +Unlike the flag form, where omitting `--id` generates one, the JSON input file has no equivalent default: every decision object in it must carry its own `decisionId`. |
| 105 | + |
| 106 | +Field names under `data` are the caller's; the CLI never changes their casing. |
| 107 | + |
| 108 | +## get |
| 109 | + |
| 110 | +```bash |
| 111 | +uip traces decisions get <DECISION_ID> --folder-key <FOLDER_KEY> --output json |
| 112 | +``` |
| 113 | + |
| 114 | +`--include-spans` adds the span that carries the decision. An unknown ID exits 1 with `Decision <id> not found.`. |
| 115 | + |
| 116 | +## list |
| 117 | + |
| 118 | +```bash |
| 119 | +uip traces decisions list \ |
| 120 | + --trace-id <TRACE_ID> \ |
| 121 | + --folder-key <FOLDER_KEY> \ |
| 122 | + --output json |
| 123 | +``` |
| 124 | + |
| 125 | +| Flag | Required | Notes | |
| 126 | +|------|----------|-------| |
| 127 | +| `--trace-id` | No | 32-char hex or GUID | |
| 128 | +| `--process-key` / `--process-version` / `--instance-id` / `--element-id` | No | Process context filters | |
| 129 | +| `--platform` | No | `ActionCenter`, `CodedApp`, `VerticalUi` | |
| 130 | +| `--actor` / `--actor-kind` | No | Identity and kind (`Automation`, `Human`, `Rule`, `Agent`) | |
| 131 | +| `--outcome` | No | Accepted outcome | |
| 132 | +| `--origin` | No | Origin value | |
| 133 | +| `--from` / `--to` | No | ISO 8601 time bounds | |
| 134 | +| `--include-spans` | No | Include the carrying span | |
| 135 | +| `--limit` | No | Default 20 | |
| 136 | +| `--offset` | No | Row offset, default 0 | |
| 137 | + |
| 138 | +`Data` is an array (empty when nothing matches). `Pagination.Total` is the match count; page with `--offset` while `Pagination.HasMore` is true. |
| 139 | + |
| 140 | +## Error handling |
| 141 | + |
| 142 | +| Symptom | Action | |
| 143 | +|---------|--------| |
| 144 | +| `--trace-id is required` / `--folder-key is required` | Add the flag. Take the folder key from the user | |
| 145 | +| `Invalid trace ID format` | Pass 32 hex characters or a GUID | |
| 146 | +| HTTP 400 naming `proposedBy` | Add `proposedBy` to every field in `data` | |
| 147 | +| HTTP 400 naming `OTEL SpanId` | Use a 16-char lowercase hex `decisionId` | |
| 148 | +| `Not authenticated` | Run `uip login --authority <AUTHORITY> --organization <ORG> --tenant <TENANT>`; never ask for a token | |
| 149 | +| `Insufficient permissions` | The user needs Logs permissions on the folder; stop and report | |
| 150 | + |
| 151 | +## Anti-patterns |
| 152 | + |
| 153 | +- Reusing one `decisionId` for different decisions in the same trace; the second replaces the first. |
| 154 | +- Building the JSON by string concatenation. Write the file with a JSON-aware tool. |
| 155 | +- Putting a token in a command, file, or message. |
0 commit comments