git:20260728.7eb51c8 to git:20260820.4d41b4b

---

name: add-dataverse

description: Use when the user wants to add Dataverse tables (existing or new) to a Power Apps mobile app, extend an existing Dataverse table with new columns, or apply an approved data model plan.

user-invocable: true

allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, EnterPlanMode, ExitPlanMode, Task

model: opus

---

**📋 Shared instructions: [shared-instructions.md](${CLAUDE_SKILL_DIR}/../../shared/shared-instructions.md)** — read first.

# Add Dataverse

Two paths:

- **Existing tables only** — skip to Step 5 (just runs `npx power-apps add-data-source` per table)

- **New / extended tables** — full workflow with Web API mutations in dependency order

## Workflow

---

### Step 1 — Verify project & auth

Confirm Power Apps mobile app:

```bash

test -f power.config.json && test -f app.config.js

node "${CLAUDE_SKILL_DIR}/../../scripts/resolve-environment.js" "$(node -e \"console.log(require('./power.config.json').environmentId)\")"

```

Capture the **environment URL** (`https://orgXXX.crm.dynamics.com`), **environment ID**, and **tenant ID** from `resolve-environment.js` — needed for Step 3. If only the environment URL is available, pass that URL instead of the ID.

### Step 2 — Resolve plan

Look for `native-app-plan.md` in the project root:

```bash

test -f native-app-plan.md

```

- The Mermaid ER diagram (informational)

- The "Creation Order" tier list

**If absent:** check `$ARGUMENTS` for diagram hints (`*.png`, `*.jpg`, `*.jpeg` filename, `erDiagram` keyword, `||--o{` cardinality syntax).

- **Diagram hint present** → Path A (Step 2.5).

- **No hint AND `$ARGUMENTS` describes what the app does** (the typical case) → silently take Path B (Step 2.6 — spawn architect). No prompt.

- **No hint AND `$ARGUMENTS` is empty / non-descriptive** → only then prompt with `AskUserQuestion`:

> "How would you like to define the data model?

> (a) I have an existing ER diagram to upload (PNG/JPG path, Mermaid syntax, or text description)

> (b) Let the data-model-architect agent analyze and propose one (default)

> (c) Cancel — I'll plan it elsewhere first"

Default the answer to (b) so empty/cancel input auto-proceeds. The 99% case (user gave a description but no diagram) skips this prompt entirely.

### Step 2.5 — Path A: Parse user-provided diagram

Used when the user has an existing diagram from another tool (Visio, dbdiagram.io, screenshot, hand-drawn).

Accept three input formats:

| Format | How |

|---|---|

| **Image path** (`*.png` / `*.jpg` / `*.jpeg`) | Use `Read` on the file path. The vision-capable model extracts entities, columns, relationships. |

| **Mermaid syntax** | User pastes a `erDiagram` block in chat. Parse the entities, columns, and `\|\|--o{` cardinalities directly. |

| **Text description** | User types a structured description ("Account has many ServiceVisits; each ServiceVisit has many WorkItems and Photos"). Spawn `data-model-architect` agent in `parse-only` mode with the text as input. |

Whichever format, normalize into the same structure used by the planner agent:

```yaml

publisherPrefix: <from detected publisher prefix or user>

tables:

- logicalName: contoso_servicevisit

displayName: Service Visit

status: new # new | extend | reuse

columns: [...]

relationships: [...]

```

Then:

1. Query existing Dataverse (Step 4 logic) to mark each table as `new`, `modified`, or `reused`.

2. Generate a Mermaid ER diagram from the parsed structure for visual confirmation.

3. Present back to the user via `EnterPlanMode` for approval.

4. On `ExitPlanMode`, write the approved data model into `native-app-plan.md` `## Data Model` section (creating the file if it doesn't exist).

5. Continue to Step 3.

### Step 2.6 — Path B: Spawn architect agent

If the user picked Path B (or the user-provided diagram parse failed), spawn the `mobile-app:data-model-architect` agent via `Task` (the `mobile-app:` plugin-name prefix is required) with the user's high-level requirements as input. The agent returns `_dm_section.md`. Embed it in `native-app-plan.md`, present via `EnterPlanMode` for approval, then continue to Step 3.

If they need new tables and refuse both paths, recommend they run `/setup-datamodel` (alias of this skill) explicitly, or `native-app-planner` for a full app-level plan. STOP if neither.

### Step 3 — Setup Dataverse Web API auth

Required only if creating or extending tables. Skip to Step 5 for read-only `add-data-source`.

#### Step 3a — Environment consistency check

`npx power-apps` and `az` authenticate independently — they can point to different accounts. Verify `power.config.json` resolves and `az` can token for the target tenant before making any Dataverse API calls:

```bash

ENV_JSON=$(node "${CLAUDE_SKILL_DIR}/../../scripts/resolve-environment.js" "$(node -e \"console.log(require('./power.config.json').environmentId)\")")

echo "$ENV_JSON"

az account show --query "{user: user.name, tenant: tenantId}" -o json

```

Compare the resolved environment URL with `<envUrl>` captured in Step 1. If they differ, **STOP** and warn:

> "⚠️ Environment mismatch detected:

> - resolver reports: `<resolved_env_url>`

> - This project targets: `<envUrl>`

>

> The Dataverse API token comes from `az`, which must target the same tenant as the selected environment. Run:

> ```bash

> az login --tenant <tenant-id> # switch az to the right tenant

> ```

> Then re-run `/add-dataverse`."

**Do NOT proceed with table creation if environments don't match** — you'll create tables in the wrong org.

#### Step 3b — Acquire token

```bash

az account show --query "user.name" -o tsv

```

If empty, instruct `az login` and stop.

**Script invocation contract — read this once, all subsequent calls in this skill follow it:**

```bash

```

- Three positional args, in order: `<envUrl>`, `<METHOD>` (GET / POST / PATCH / DELETE), `<apiPath>` (everything after `/api/data/v9.2/`).

- **Body is a flag, not positional.** `--body '<json>'` — required for POST/PATCH, never for GET/DELETE. Forgetting `--body` and passing the JSON as a 4th positional arg returns a usage error.

- `--include-headers` adds response headers (needed for `OData-EntityId` after a record create).

- Output is JSON: `{ "status": <code>, "data": <body> }`. Token refresh on 401 and back-off on 429 are automatic — never wrap with manual retry.

Acquire a Dataverse access token and verify connectivity:

```bash

```

`WhoAmI` is the Dataverse identity endpoint — capital W/A/I (case-sensitive). The response gives `UserId`, `BusinessUnitId`, `OrganizationId` but **does NOT include the publisher prefix**. To get the publisher prefix, query the solution's publisher (defaults to `Default`; pass a different solution name if the env uses a custom solution):

```bash

# solutionName defaults to "Default" if omitted

```

This runs the OData query:

`/api/data/v9.2/solutions?$select=uniquename&$expand=publisherid($select=customizationprefix)&$filter=uniquename eq '<solutionName>'`

Capture `customizationprefix` from the solution's publisher (typical value: `cr123` → schema names like `cr123_jobsite`). Also capture the solution `uniquename` — needed for the `--solution` flag on every Step 5 / 5b POST so artifacts land in our solution rather than landing wherever Dataverse defaults. Write both to `memory-bank.md` Power Platform context block.

Requires the user to hold **System Administrator** or **System Customizer** in this environment.

**Print before starting:**

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \

```

```

### Step 5 — Create / extend tables

**Print before starting:**

> "→ Creating/extending <N> tables in tier order (sequential — Dataverse serializes metadata writes). For each: pre-flight check, then 'Creating <table>…' before the POST and '✓ <table>' on 2xx response."

>

> Specifically:

> - **Within a tier:** create tables one at a time.

> - **Across tiers:** Tier 0 fully done (all tables + all columns committed) before any Tier 1 POST.

> - **Lookups:** POST to `/RelationshipDefinitions` only **after** both endpoint tables exist and have returned 2xx.

> - **Extensions:** column POSTs to an existing table are also serial — same lock applies.

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \

```

|---|---|---|

| **5xx** with `0x80060890` or message `"object with same name exists in solution"` | Tombstone (soft-deleted, ~30 min purge TTL) | Auto-recover via rename (see below). |

#### Auto-recovery — reuse/extend first, rename as last resort

**Priority order when Step 5a hits a name collision:**

2. **Adopt as Reuse** — if the existing table's schema already covers all planned columns: skip Step 5b for this entry, keep it in Step 6 for service generation. No prompt. Log `→ Reusing existing <original> (all required columns present).`

3. **Rename and Create (last resort)** — only when the existing table is a fundamentally different entity (e.g., planned table is an inspection log but existing `<original>` is a payroll record — incompatible concept, incompatible columns). Prompt the user before proceeding.

**When to auto-decide vs. prompt:**

| Situation | Action |

|---|---|

| Foreign collision + all planned columns present | Auto-Reuse (no prompt) |

| Foreign collision + incompatible concept | Prompt (see below) |

| Reserved system name | Auto-rename (no prompt) |

| Tombstone (0x80060890 / same-name-exists) | Auto-rename (no prompt) |

**For the incompatible-concept case only** — prompt via `AskUserQuestion`:

```

| Option | What it means |

|---|---|

```

Maintain a run-level logical-name alias map for every auto-rename. Example:

```json

{ "cr3e9_aircraft": "cr3e9_aircraftv2" }

```

Before building any later table, column, lookup relationship, sample-data payload, service-reference text, or screen data spec, resolve logical names through this map. A rename that only changes the table POST but leaves relationships/screens/sample data pointing at the old name is a bug.

**Auto-rename probe sequence** (cap at 4 probes — only used for reserved/tombstone cases):

```

<original>v2 → <original>v3 → <original>2 → <original>copy

```

For each candidate in order, GET `EntityDefinitions(LogicalName='<candidate>')?$select=MetadataId,IsCustomEntity`:

- 404 → free, **take it**, stop probing.

- 200 or 5xx (collision) → next candidate.

**On a successful auto-rename, do these in order BEFORE the POST:**

1. **Update `native-app-plan.md`** — `Edit` with `replace_all: true` to swap the old logical name for the new one across the entire `## Data Model` section (Mermaid ER, Reuse/Extend/Create table, Creation Order, Notes). This catches downstream relationship POSTs in this same Step 5 too.

2. **Update `## Screens` per-screen specs** — same `replace_all` sweep for any service / data-source references using the old name.

3. **Append to `memory-bank.md` Collision history** — `<original> → <new>` with reason (foreign / reserved / tombstone) and timestamp.

4. **Update the run-level alias map** — every later metadata payload and plan edit resolves `<original>` to `<new>` before use.

5. **Inform the user — single line, no prompt:**

> `→ Collision on <original> (<foreign|reserved|tombstone>). Renamed to <new> and updated plan + memory-bank. Continuing.`

Then proceed with the POST using `<new>`.

#### Post-create collision rescue — hidden tombstone / recent delete

If the Step 5b table POST fails after a 404 preflight with any Dataverse name-collision signature, **do not fail the run**:

- HTTP `400` with code `0x80044363`

- message contains `schema name` and `not unique`

- message contains `same name already exists`

- message contains `object with same name exists in solution`

> `→ Dataverse still has <original> reserved from a recent delete/hidden collision. Using <new> and continuing.`

**On successful POST**, immediately re-GET to capture the server-assigned `MetadataId` and write it to memory-bank (Step 6d updates `.datamodel-manifest.json`; you also append to `memory-bank.md` under "Created tables" with the GUID and solution name). This lets future `/add-dataverse` runs distinguish "we own this" from "name collision."

#### Step 5b — Create / extend

For each `Create` decision, in **tier order** (Tier 0 → Tier 1 → Tier 2 → …), POST a new EntityDefinition. Skip if Step 5a returned a known-self match (idempotent).

> **⚠️ Inline ALL planned columns into the Create POST body — do NOT POST columns individually.**

>

>

> **Wrong** (N round trips):

> ```json

> { "SchemaName": "...", "Attributes": [{ /* primary only */ }] }

> // then 4× POST /Attributes for the rest

> ```

>

> **Right** (1 round trip):

> ```json

> {

> "SchemaName": "...",

> "Attributes": [

> { /* primary name */ },

> { /* column 2 */ },

> { /* column 3 */ },

> { /* column 4 */ },

> { /* column 5 */ }

> ]

> }

> ```

>

> The per-column POST path remains valid for two cases only: (1) Extend on an existing table, (2) retry-after-partial-failure when Step 5a's pre-flight shows the table exists but some columns don't.

**Solution targeting (HARD):** every Step 5 / 5b POST MUST pass `--solution <uniquename>` so Dataverse routes the new artifact into our solution rather than the unmanaged default. Read the solution name from `memory-bank.md` Power Platform context (captured in Step 3b). Without this flag, multi-project environments end up with cross-solution leakage and the foreign-collision class of bug returns. The script translates `--solution` to the `MSCRM.SolutionUniqueName` HTTP header.

**Scratch files:** When writing request body JSON to disk (e.g. table definitions, column metadata, relationship payloads), always write to `<working_dir>/.tmp/`, never to `/tmp/`. Keeping request bodies project-local prevents cross-project writes and makes cleanup deterministic. Create the folder if it doesn't exist: `mkdir -p <working_dir>/.tmp`.

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST EntityDefinitions \

--body '<json-body-with-all-columns-inline>' \

```

Body skeleton — **all planned columns inline in `Attributes: [...]`** (this example shows primary + 3 additional; expand the array to fit every column from the plan):

> **⚠️ `IsAvailableOffline` + `ChangeTrackingEnabled` MUST be set to `true` at create time** for any table the app intends to make available offline. Without these two flags the table cannot be added to a `mobileofflineprofile`, and `/setup-offline-profile` will have to fix them via a separate metadata PUT (the `/enable-tables-offline` skill handles that, but it doubles the metadata-lock-serialized round trips). Empirically verified 2026-05-18 in the chanel-rm demo: 7 custom tables created without these flags caused 7 prereq-revert drift entries; fixed by post-hoc enablement. Default these to `true` for all UserOwned tables created by `/add-dataverse` unless the user has explicitly opted out of offline support. The flags are no-ops at runtime for apps that don't use offline profiles.

```json

{

"@odata.type": "Microsoft.Dynamics.CRM.EntityMetadata",

"SchemaName": "cr123_jobsite",

"DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Job Site", "LanguageCode": 1033 }] },

"DisplayCollectionName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Job Sites", "LanguageCode": 1033 }] },

"OwnershipType": "UserOwned",

"HasActivities": false,

"HasNotes": false,

"IsAvailableOffline": true,

"ChangeTrackingEnabled": true,

"PrimaryNameAttribute": "cr123_sitename",

"Attributes": [

{

"@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",

"SchemaName": "cr123_sitename",

"DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Site Name", "LanguageCode": 1033 }] },

"MaxLength": 200,

"FormatName": { "Value": "Text" },

"RequiredLevel": { "Value": "ApplicationRequired" },

"IsPrimaryName": true

},

{

"@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",

"SchemaName": "cr123_address",

"DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Address", "LanguageCode": 1033 }] },

"MaxLength": 500,

"FormatName": { "Value": "Text" },

"RequiredLevel": { "Value": "None" }

},

{

"@odata.type": "Microsoft.Dynamics.CRM.IntegerAttributeMetadata",

"SchemaName": "cr123_squarefeet",

"DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Square Feet", "LanguageCode": 1033 }] },

"RequiredLevel": { "Value": "None" },

"MinValue": 0,

"MaxValue": 2147483647,

"Format": "None"

},

{

"@odata.type": "Microsoft.Dynamics.CRM.BooleanAttributeMetadata",

"SchemaName": "cr123_active",

"DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Active", "LanguageCode": 1033 }] },

"RequiredLevel": { "Value": "None" },

"DefaultValue": true,

"OptionSet": {

"@odata.type": "Microsoft.Dynamics.CRM.BooleanOptionSetMetadata",

"TrueOption": { "Value": 1, "Label": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Yes", "LanguageCode": 1033 }] } },

"FalseOption": { "Value": 0, "Label": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "No", "LanguageCode": 1033 }] } }

}

}

]

}

```

For each `Extend` decision, POST a new column to the existing table.

>

> ```bash

> node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \

> ```

>

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST \

"EntityDefinitions(LogicalName='<table>')/Attributes" \

--body '<column-json>' \

```

Column shapes that have non-obvious gotchas (handle carefully):

- **Lookup** — POST to `/RelationshipDefinitions`, not `/Attributes`.

> **⚠️ Do NOT improvise the body. Copy the skeleton below verbatim and replace only the placeholders in `<>` brackets.**

>

> Fields that cause silent failure if added:

> - **Do NOT include `ReferencingAttribute`.** Dataverse auto-creates the foreign-key column from `Lookup.SchemaName`. Including it causes `404: Could not find an attribute with specified name` because the column doesn't exist yet at POST time.

> - **Do NOT include `Lookup.LogicalName`.** It's read-only metadata; including it returns `400 Bad Request`.

> - **Do NOT include `ReferencedAttribute`.** Dataverse resolves the primary key of the referenced entity automatically. The reference is optional and omitting it is the correct default.

>

> Required fields: `SchemaName`, `ReferencedEntity`, `ReferencingEntity`, `Lookup.{@odata.type, SchemaName, DisplayName, RequiredLevel}`, `AssociatedMenuConfiguration`, `CascadeConfiguration` (including `RollupView`). Anything else is invented — drop it.

```json

{

"@odata.type": "Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata",

"SchemaName": "<prefix>_<Parent>_<Child>",

"ReferencedEntity": "<parent_table_logical_name>",

"ReferencingEntity": "<child_table_logical_name>",

"Lookup": {

"@odata.type": "Microsoft.Dynamics.CRM.LookupAttributeMetadata",

"SchemaName": "<Prefix>_<Parent>Id",

"DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel", "Label": "<Parent Display Name>", "LanguageCode": 1033 }] },

"RequiredLevel": { "Value": "None" }

},

"AssociatedMenuConfiguration": { "Behavior": "UseCollectionName", "Group": "Details", "Order": 10000 },

"CascadeConfiguration": {

"Assign": "NoCascade",

"Delete": "RemoveLink",

"Merge": "NoCascade",

"Reparent": "NoCascade",

"Share": "NoCascade",

"Unshare": "NoCascade",

"RollupView": "NoCascade"

}

}

```

Invocation (apiPath is `RelationshipDefinitions`, body via `--body`, always pass `--solution`):

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST \

RelationshipDefinitions \

--body '<json-body-from-skeleton-above>' \

```

- **Many-to-Many (M:N)** — also POST to `/RelationshipDefinitions`, but with `ManyToManyRelationshipMetadata`. Dataverse creates an auto-named intersect table.

> **⚠️ Do NOT improvise the body.** Required fields: `SchemaName`, `Entity1LogicalName`, `Entity2LogicalName`, `IntersectEntityName`, and the two `AssociatedMenuConfiguration` blocks. Do not include lookup or cascade fields — those are 1:N concepts.

```json

{

"@odata.type": "Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata",

"SchemaName": "<prefix>_<table1>_<table2>",

"Entity1LogicalName": "<table1_logical_name>",

"Entity2LogicalName": "<table2_logical_name>",

"IntersectEntityName": "<prefix>_<table1>_<table2>",

"Entity1AssociatedMenuConfiguration": {

"Behavior": "UseLabel",

"Group": "Details",

"Label": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel", "Label": "<Table2 Plural>", "LanguageCode": 1033 }] },

"Order": 10000

},

"Entity2AssociatedMenuConfiguration": {

"Behavior": "UseLabel",

"Group": "Details",

"Label": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel", "Label": "<Table1 Plural>", "LanguageCode": 1033 }] },

"Order": 10000

}

}

```

- **Column `@odata.type` and required fields — reference table (verified against Dataverse OData API):**

| Dataverse type | `@odata.type` | Required extra fields |

|---|---|---|

| Single-line text | `Microsoft.Dynamics.CRM.StringAttributeMetadata` | `MaxLength` (200), `FormatName: { "Value": "Text" }` — values: `Text`, `Email`, `Url`, `Phone`, `TextArea` |

| Multi-line text | `Microsoft.Dynamics.CRM.MemoAttributeMetadata` | `MaxLength` (10000), `Format: "TextArea"` |

| Whole number | `Microsoft.Dynamics.CRM.IntegerAttributeMetadata` | `MinValue`, `MaxValue`, `Format: "None"` |

| Decimal | `Microsoft.Dynamics.CRM.DecimalAttributeMetadata` | `MinValue`, `MaxValue`, `Precision` (2) |

| Currency (Money) | `Microsoft.Dynamics.CRM.MoneyAttributeMetadata` | `MinValue`, `MaxValue`, `Precision` (2), `PrecisionSource` (2) |

| Date/Time | `Microsoft.Dynamics.CRM.DateTimeAttributeMetadata` | `Format: "DateAndTime"` or `"DateOnly"`, `DateTimeBehavior: { "Value": "UserLocal" }` |

| Boolean | `Microsoft.Dynamics.CRM.BooleanAttributeMetadata` | `DefaultValue`, `OptionSet` with `TrueOption`/`FalseOption` |

| Choice (picklist) | `Microsoft.Dynamics.CRM.PicklistAttributeMetadata` | `OptionSet` with `IsGlobal: false`, `OptionSetType: "Picklist"`, `Options[]` — **option integer values start at `100000000` and increment by 1** |

| Lookup | via `RelationshipDefinitions` — see 1:N skeleton above | — |

| Image | `Microsoft.Dynamics.CRM.ImageAttributeMetadata` | `MaxHeight`, `MaxWidth` |

| File | `Microsoft.Dynamics.CRM.FileAttributeMetadata` | `MaxSizeInKB` |

**Common mistake:** omitting `FormatName` on String columns and `DateTimeBehavior` on DateTime columns. Both are required — Dataverse rejects the POST without them.

- **Choice (option set)** — set `OptionSet.IsGlobal: false` for local picklists. Full body (option values start at `100000000` and increment by 1):

```json

{

"@odata.type": "Microsoft.Dynamics.CRM.PicklistAttributeMetadata",

"SchemaName": "<Prefix>_<ColumnName>",

"DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel", "Label": "<Display Name>", "LanguageCode": 1033 }] },

"RequiredLevel": { "Value": "None" },

"OptionSet": {

"@odata.type": "Microsoft.Dynamics.CRM.OptionSetMetadata",

"IsGlobal": false,

"OptionSetType": "Picklist",

"Options": [

{ "Value": 100000000, "Label": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel", "Label": "Option 1", "LanguageCode": 1033 }] } },

{ "Value": 100000001, "Label": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel", "Label": "Option 2", "LanguageCode": 1033 }] } }

]

}

}

```

- **Image** — `@odata.type: Microsoft.Dynamics.CRM.ImageAttributeMetadata`, `MaxHeight`/`MaxWidth` required

- **File** — `@odata.type: Microsoft.Dynamics.CRM.FileAttributeMetadata`, `MaxSizeInKB` required

If the column type is not a simple string/int/boolean, surface a one-line confirmation to the user before posting.

After all mutations, re-run the existing-tables query (Step 4) to confirm everything landed.

### Step 5d — Create alternate keys for unique business identifiers

**Print before starting:**

> "→ Creating alternate keys for columns marked unique in the data model (one HTTP call per key). Skip if no unique columns are planned."

**Run condition:** the `## Data Model` section marks a non-primary column as unique / alternate key / natural key. Common examples: QR Code Value, SKU, external ID, employee number, asset tag. Skip primary IDs and skip columns whose type Dataverse cannot index as an alternate key (file/image, memo/long text, multi-select choice, calculated/rollup, customer/owner lookups).

**Ordering:** run after the target table and target columns exist, and before Step 6b publish. Alternate-key index activation is asynchronous; creation may return success while the key status is `Pending`.

**Do NOT use the `CreateEntityKey` action route.** In practice it can return 404 depending on route shape / environment. The reliable metadata route is POSTing to the table's `Keys` navigation collection:

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST \

"EntityDefinitions(LogicalName='<table>')/Keys" \

--body '<entity-key-json>' \

```

Body skeleton:

```json

{

"@odata.type": "Microsoft.Dynamics.CRM.EntityKeyMetadata",

"SchemaName": "<prefix>_<table>_<column>_key",

"DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "<Column display> Key", "LanguageCode": 1033 }] },

"KeyAttributes": ["<column_logical_name>"]

}

```

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \

```

| Existing key state | Action |

|---|---|

| Same `SchemaName` or same `KeyAttributes` exists with `Active` / `Pending` | Skip POST; record the key in `.datamodel-manifest.json`. |

| Same `SchemaName` exists with `Failed` | Surface the failure and stop; Dataverse requires deleting/recreating the key manually or changing the planned key name. |

| No matching key | POST to `EntityDefinitions(LogicalName='<table>')/Keys`. |

**After POST:** a `204` response is success. Re-query the `Keys` expand above and capture `EntityKeyIndexStatus`. If it is `Pending`, continue the scaffold but add a memory-bank follow-up: `alternate key <schema> pending index activation`. Do not rely on duplicate enforcement in manual tests until the status reaches `Active`.

Add alternate keys to `.datamodel-manifest.json` for the table:

```json

"alternateKeys": [

{ "schemaName": "cr123_item_code_key", "keyAttributes": ["cr123_code"], "indexStatus": "Pending" }

]

```

### Step 6 — Add data sources

**Print before starting:**

> "→ Generating TypeScript services for <N> tables via `npx power-apps add-data-source` (sequential). Print '✓ <table>Service.ts' after each."

```bash

npx power-apps add-data-source --api-id dataverse --org-url <envUrl> --resource-name <table-logical-name>

```

Run **one at a time — sequentially**, not in parallel. The Power Apps CLI writes `src/generated/connectorSchemas.ts` and other generated files non-atomically; concurrent invocations corrupt them.

### Step 6b — Publish customizations

**Print before starting:**

> "→ Publishing customizations (PublishXml) so new tables/columns become queryable. ~5–20 seconds."

Only after **every** Step 5 metadata POST and **every** Step 6 `npx power-apps add-data-source` has returned successfully, publish so the new tables and columns are available to the runtime. `PublishXml` takes the same exclusive metadata lock as the create/extend calls — do not run it concurrently with anything from Steps 5 or 6.

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST \

"PublishXml" \

```

Build the entity list from all tables that were **created or extended** in Steps 4–5. Skip reused-as-is tables — they don't need republishing.

If the publish call returns a non-2xx status, report the error and stop — do not proceed. The user must resolve before the tables are usable.

### Step 6c — Verify tables exist

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \

```

### Step 6d — Write `.datamodel-manifest.json`

After all tables are verified, write the manifest to the project root using the `Write` tool:

```json

{

"environmentUrl": "<envUrl>",

"generatedAt": "<ISO timestamp>",

"tables": [

{

"logicalName": "cr123_jobsite",

"displayName": "Job Site",

"status": "new",

"metadataId": "<server-assigned GUID from Step 5a re-GET>",

"solution": "<solution unique name, e.g. PowerAppsDefault>",

"columns": [

{ "logicalName": "cr123_sitename", "type": "String" },

{ "logicalName": "cr123_address", "type": "String" }

]

}

]

}

```

`metadataId` and `solution` are required for `status: "new"` or `"extended"` entries — they're how Step 5a distinguishes "we own this on a re-run" from "name collision." Reused tables can omit both.

Include only tables confirmed in Step 6c. Do NOT include tables reused with no schema changes.

### Step 7 — Inspect generated files

```text

Glob: src/generated/services/*Service.ts

Glob: src/generated/models/*Model.ts

```

For each table, check the generated service exposes the expected methods:

```text

Grep pattern="async (create|getAll|getById|update|delete|upload|downloadFile|downloadImage)" path="src/generated/services/<Table>Service.ts"

```

If the table has file or image columns, confirm the service includes `upload`, `downloadFile`, `downloadImage`, `deleteFileOrImage` — and the model exposes `<Table>FileColumnName` / `<Table>ImageColumnName` union types.

**File/image column UI controls:** When a generated table has File or Image columns, note this in the summary so screen-builders apply the host controls from `@microsoft/power-apps-native-host`:

- **File columns** → `<FilePicker>`; upload bytes separately via the generated service's upload method after the main create/update.

- **Image columns** → `<ImagePicker>`; capture `PickedImageInfo` via `onImageChange` and persist through generated `upload(...)` after the main create/update.

- **Read/view flows** → use generated `downloadFile(...)` / `downloadImage(...)` helpers for existing attachments/previews.

Full usage pattern and the native-wrapper boundary live in [`/add-native`](../add-native/SKILL.md#fileimage-picker-ownership); screen-builder keeps only the concise JSX enforcement rule.

**PDF/signature artifact schema guidance:** If the approved plan mentions generated PDFs, PDF evidence packets, approvals, signatures, sign-off, ink, or drawings, preserve the storage decision in the Dataverse model instead of defaulting to text fields.

| User need | Dataverse shape | Write pattern |

|---|---|---|

| Generated PDF report that must be retained | File column on the parent record, or child Evidence/Attachment table with a File column | Create/update parent row first, then call generated `Service.upload(parentId, '<fileColumn>', file)` |

| Generated PDF report that is only transient | No Dataverse column required | Generate locally with `expo-print` only when present; share with `expo-sharing` only when present; do not route local URI to native PDF viewer |

| Captured signature/sign-off image | Image column when the latest signature belongs on the parent row | Strip `data:image/png;base64,` if the generated service expects raw base64, then include image payload in the update body |

| Multiple signatures, sketches, evidence images, or audit attachments | Child Evidence/Attachment table with Image/File columns and lookup to parent | Create child row first, then include Image payload or upload File bytes through generated service helpers |

Signature image normalization example:

```ts

const signatureBase64 = signatureDataUri.replace(/^data:image\/png;base64,/, '');

const result = await Cr123_approvalService.update(approvalId, {

cr123_signatureimage: signatureBase64,

cr123_signedat: new Date().toISOString(),

});

if (!result.success) {

throw new Error(result.error?.message ?? 'Signature image was not saved.');

}

```

File upload after parent row exists example:

```ts

const save = await Cr123_inspectionService.update(inspectionId, {

cr123_reportgeneratedat: new Date().toISOString(),

});

if (!save.success) {

throw new Error(save.error?.message ?? 'Inspection was not saved.');

}

const upload = await Cr123_inspectionService.upload(inspectionId, 'cr123_reportfile', reportFile);

if (!upload.success) {

throw new Error(upload.error?.message ?? 'Inspection report was not uploaded.');

}

```

### Step 8 — Type-check

**Print before starting:**

> "→ Regenerating connector schemas + running tsc to verify generated services compile (~15–30 seconds)."

`npx power-apps add-data-source` (Step 5) wrote new files into `.power/schemas/<connector>/`. The `connectorSchemas.ts` consumed by `app/_layout.tsx` is now stale — regenerate it before type-checking, otherwise the new tables won't be wired into the runtime schema map and `tsc` will pass against an out-of-date snapshot:

```bash

npm run generate-schemas

npx tsc --noEmit

```

Fix any errors. Common: missing peer dependencies — `npx expo install <package>`.

### Step 8.5 — Offline profile reconciliation

A schema change here (new table or new column) can leave an existing Mobile Offline Profile behind — new tables never sync to devices and new columns come down blank. Reconcile the profile with what you just created.

**Skip this step entirely when `$ARGUMENTS` contains `--skip-planning`** (the orchestrator-invoked path). `/create-mobile-app`, `/setup-datamodel`, and `/edit-app` own offline reconciliation in their own flow, so running it here too would double-prompt.

Otherwise (manual `/add-dataverse`), run the local, no-network delta check:

```bash

node "${CLAUDE_SKILL_DIR}/../../scripts/offline-profile-delta.js"

```

Branch on the JSON `status` per [offline-profile-reconciliation.md](${CLAUDE_SKILL_DIR}/../../shared/references/offline-profile-reconciliation.md):

| `status` | Action |

|---|---|

| `no-manifest` / `no-profile` / `in-sync` | Continue to Step 9 silently. For `no-profile` (no offline profile exists) do not nag — the app may not use offline. |

| `error` | `offline-profile.json` is unreadable — the script prints `status: error` and **exits non-zero**. Do NOT treat this as an `/add-dataverse` failure (the tables are already created): surface the `error` string, **skip reconciliation** (never drive the update workflows against a corrupt file), and finish with `DONE_WITH_CONCERNS` telling the user to fix `offline-profile.json`. |

| `delta` | Prompt the user (one `AskUserQuestion`, default = update now) to add the missing tables / new columns. For `missingTables[]`, read and execute `${CLAUDE_SKILL_DIR}/../add-table-to-offline-profile/SKILL.md`; for `tablesWithNewColumns[]`, read and execute `${CLAUDE_SKILL_DIR}/../edit-offline-profile/SKILL.md` with `--table <t> --columns add:<newColumns>`. Re-run the delta check; it should read `in-sync`. Follow the exact prompt + ordering in the reconciliation reference. |

### Step 9 — Summary

```

✅ Dataverse added

─────────────────────────────────────────────

Environment : <envUrl>

Tables reused : <list>

Tables extended: <list (columns added)>

Tables created : <list (in tier order)>

Generated services:

src/generated/services/<Table>Service.ts × N

Generated models:

src/generated/models/<Table>Model.ts × N

Type-check: PASS

Sample usage:

import { Cr123_jobsiteService } from '../../src/generated/services/Cr123_jobsiteService';

const result = await Cr123_jobsiteService.getAll({

select: ['cr123_sitename', 'cr123_address'],

filter: 'statecode eq 0',

orderBy: ['cr123_sitename asc'],

top: 50,

});

const sites = result.data ?? [];

⚠️ First call triggers Dataverse OAuth consent via the native player's

`<scheme>://oauth-callback` deep link.

Next:

/add-sample-data # Seed each new table with 5-10 realistic rows so the

# app's home screen shows real-looking data on first launch.

─────────────────────────────────────────────

```

After printing the summary, **offer one-click sample-data seeding** — but only when invoked manually (not from `/create-mobile-app`, which handles this in its own Step 8.5).

- **If `$ARGUMENTS` contains `--skip-planning`** (the orchestrator-invoked path): skip the prompt. The orchestrator invokes `/add-sample-data` separately.

- **Otherwise (manual invocation)**, if the manifest contains any tables, ask:

> "Seed <N> tables with sample records so the app shows real-looking data on first launch? (yes / no — default: yes)"

Default to "yes" so empty input auto-proceeds. On "yes", invoke `/add-sample-data`. On "no", print "→ Skipped sample data. Run `/add-sample-data` later to populate." and stop.

## Key Rules

- **Always** use generated services (e.g., `Cr123_jobsiteService.getAll()`) — never `fetch` / `axios` directly.

- Result data lives at `result.data`, not `result` itself.

- Don't edit files under `src/generated/` — they are regenerated on every `npx power-apps add-data-source`.

- Picklist (Choice) fields, virtual fields, lookups, and file/image columns each have non-obvious gotchas. Keep `references/dataverse-reference.md` aligned with this skill.

- **When a Dataverse Web API behavior is uncertain (lookup write syntax, `$expand` nav property names, choice column shape, batch semantics, error format), query the `microsoft-learn` MCP server before guessing.** See [shared/shared-instructions.md → Microsoft Learn MCP](../../shared/shared-instructions.md#microsoft-learn-mcp-authoritative-microsoft-docs). Guessed Dataverse syntax silently 400s.

## Reference

- [`scripts/dataverse-request.js`](../../scripts/dataverse-request.js) — bundled in this plugin

- [shared/references/offline-profile-reconciliation.md](../../shared/references/offline-profile-reconciliation.md) — Step 8.5 offline delta check + reconciliation flow