add-dataverse

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.

Jump to install

Repository: microsoft/power-platform-skills
Last source activity: July 28, 2026 at 12:00
Detected SKILL.md language: English
Stars: 721
Forks: 150

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/microsoft/power-platform-skills --skill add-dataverse

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

File Explorer

2 files

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

File Explorer

2 files

SKILL.md

Source instructions · Read-only preview

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 — 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

Verify project & auth → 2. Resolve plan → 3. Setup Dataverse Web API auth → 4. Review existing tables → 5. Create / extend tables → 5d. Create alternate keys → 6. Add data sources → 6b. Publish customizations → 6c. Verify tables → 6d. Write manifest → 7. Inspect generated files → 8. Type-check → 8.5. Offline profile reconciliation → 9. Summary

Step 1 — Verify project & auth

Confirm Power Apps mobile app:

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:

test -f native-app-plan.md

If present: read the ## Data Model section. Extract:

The reuse / extend / create table
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:

publisherPrefix: <from detected publisher prefix or user>
tables:
  - logicalName: contoso_servicevisit
    displayName: Service Visit
    status: new   # new | extend | reuse
    columns: [...]
    relationships: [...]

Then:

Query existing Dataverse (Step 4 logic) to mark each table as new, modified, or reused.
Generate a Mermaid ER diagram from the parsed structure for visual confirmation.
Present back to the user via EnterPlanMode for approval.
On ExitPlanMode, write the approved data model into native-app-plan.md ## Data Model section (creating the file if it doesn't exist).
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:

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:
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

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:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> <METHOD> <apiPath> [--body '<json>'] [--include-headers]

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:

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

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

node "${CLAUDE_SKILL_DIR}/../../scripts/detect-publisher-prefix.js" <envUrl> [solutionName]
# 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.

Step 4 — Review existing tables

Print before starting:

"→ Querying existing custom tables in the environment…"

Always query before creating:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions?\$filter=IsCustomEntity eq true&\$select=SchemaName,LogicalName,DisplayName"

For each plan entry classified Reuse or Extend, fetch the table's columns to confirm the match:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<table>')/Attributes?\$select=LogicalName,AttributeType,RequiredLevel"

Schema divergence handling is in Step 5b's per-column pre-flight (not a Step 4 prompt). The pre-flight auto-skips columns that already exist with the same type, and STOPs only on incompatible type drift — no separate confirmation needed here.

Step 5 — Create / extend tables

Print before starting:

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

⚠️ Concurrency rule — do not violate. All Dataverse metadata operations in Steps 5, 6, and 6b are strictly sequential: issue one HTTP request, wait for a 2xx response, then issue the next. Do NOT batch, parallelize, or fire concurrent requests. Dataverse serializes metadata writes via an exclusive lock; parallel calls return 429 TooManyRequests, MetadataLockHeldException, or 404 EntityNotFound for lookups whose parent hasn't committed yet.

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.

Step 5a — Pre-flight collision check (per table, before each POST)

Step 4 listed known custom tables you intend to reuse. Step 5a probes for unknown problems on a per-create basis: name-prefix collisions from stale solutions, soft-deleted tombstones, and reserved system names. Skipping this check costs ~1 minute per failed POST (Dataverse takes its time returning the conflict error) and can leave Tier 0 partially created when a Tier 1 lookup fails on a phantom parent.

For every Create entry, before its POST, probe the target logical name:
node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<prefix>_<table>')?\$select=MetadataId,LogicalName,IsCustomEntity"
Branch on the response:

Status / body Meaning Action
404 NotFound Name is free Proceed with POST.
200 OK + IsCustomEntity: true + matches memory-bank

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 — 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

Verify project & auth → 2. Resolve plan → 3. Setup Dataverse Web API auth → 4. Review existing tables → 5. Create / extend tables → 5d. Create alternate keys → 6. Add data sources → 6b. Publish customizations → 6c. Verify tables → 6d. Write manifest → 7. Inspect generated files → 8. Type-check → 8.5. Offline profile reconciliation → 9. Summary

Step 1 — Verify project & auth

Confirm Power Apps mobile app:

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)\")"

Step 2 — Resolve plan

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

test -f native-app-plan.md

If present: read the ## Data Model section. Extract:

The reuse / extend / create table
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:

publisherPrefix: <from detected publisher prefix or user>
tables:
  - logicalName: contoso_servicevisit
    displayName: Service Visit
    status: new   # new | extend | reuse
    columns: [...]
    relationships: [...]

Then:

Query existing Dataverse (Step 4 logic) to mark each table as new, modified, or reused.
Generate a Mermaid ER diagram from the parsed structure for visual confirmation.
Present back to the user via EnterPlanMode for approval.
On ExitPlanMode, write the approved data model into native-app-plan.md ## Data Model section (creating the file if it doesn't exist).
Continue to Step 3.

Step 2.6 — Path B: Spawn architect agent

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

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:
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

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:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> <METHOD> <apiPath> [--body '<json>'] [--include-headers]

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:

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

node "${CLAUDE_SKILL_DIR}/../../scripts/detect-publisher-prefix.js" <envUrl> [solutionName]
# 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>'

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

Step 4 — Review existing tables

Print before starting:

"→ Querying existing custom tables in the environment…"

Always query before creating:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions?\$filter=IsCustomEntity eq true&\$select=SchemaName,LogicalName,DisplayName"

For each plan entry classified Reuse or Extend, fetch the table's columns to confirm the match:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<table>')/Attributes?\$select=LogicalName,AttributeType,RequiredLevel"

Step 5 — Create / extend tables

Print before starting:

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

⚠️ Concurrency rule — do not violate. All Dataverse metadata operations in Steps 5, 6, and 6b are strictly sequential: issue one HTTP request, wait for a 2xx response, then issue the next. Do NOT batch, parallelize, or fire concurrent requests. Dataverse serializes metadata writes via an exclusive lock; parallel calls return 429 TooManyRequests, MetadataLockHeldException, or 404 EntityNotFound for lookups whose parent hasn't committed yet.

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.

Step 5a — Pre-flight collision check (per table, before each POST)

Step 4 listed known custom tables you intend to reuse. Step 5a probes for unknown problems on a per-create basis: name-prefix collisions from stale solutions, soft-deleted tombstones, and reserved system names. Skipping this check costs ~1 minute per failed POST (Dataverse takes its time returning the conflict error) and can leave Tier 0 partially created when a Tier 1 lookup fails on a phantom parent.

For every Create entry, before its POST, probe the target logical name:
node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<prefix>_<table>')?\$select=MetadataId,LogicalName,IsCustomEntity"
Branch on the response:

Status / body Meaning Action
404 NotFound Name is free Proceed with POST.
200 OK + IsCustomEntity: true + matches memory-bank

MetadataId

Situation	Action
Foreign collision + schema overlap ≥50%	Auto-Extend (no prompt)
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)

| Option | What it means |
|---|---|
| Extend existing (default) | Add required columns to <original>. Safer — avoids duplicate tables. |
| Rename and Create | Auto-renamed to <new>. Existing table left untouched. |

{ "cr3e9_aircraft": "cr3e9_aircraftv2" }

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

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

Dataverse processes the Attributes: [...] array atomically with the table create. Inline form: 1 round trip, ~3-8s. Per-column form: N+1 round trips, each ~3-8s. For a 5-column table that's 24s saved per table on the lock-serialized metadata path.

Wrong (N round trips):
{ "SchemaName": "...", "Attributes": [{ /* primary only */ }] }
// then 4× POST /Attributes for the rest
Right (1 round trip):
{
  "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.

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST EntityDefinitions \
  --body '<json-body-with-all-columns-inline>' \
  --solution '<solution-uniquename-from-memory-bank>'

{
  "@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 }] } }
      }
    }
  ]
}

⚠️ Per-column pre-flight (HARD — required for idempotent re-runs). Before each column POST, probe whether the column already exists. This catches:

Partial failures from a prior EntityDefinitions POST that created the table + some columns but not all (the body is non-atomic — server commits each Attribute one at a time).

User re-runs after fixing a typo in one column's metadata.

Re-applying a plan after a network drop mid-Step-5b.

Without this check, the second POST returns 400: attribute already exists (0x80044153) and the run aborts mid-tier.
node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<table>')/Attributes(LogicalName='<column>')?\$select=LogicalName,AttributeType"
Status Meaning Action
404 Column doesn't exist Proceed with POST.
200 + AttributeType matches the spec Already created (idempotent re-run) Skip the POST, log ↻ <column> (already exists, skipped), continue.
200 + AttributeType differs from the spec Schema drift — column type was changed manually OR plan changed since last run STOP and surface to user: "Column <column> exists but is <existingType>, plan expected <plannedType>. Dataverse does NOT allow column-type changes via API — you must delete the column manually and re-run." Do NOT silently overwrite.

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST \
  "EntityDefinitions(LogicalName='<table>')/Attributes" \
  --body '<column-json>' \
  --solution '<solution-uniquename-from-memory-bank>'

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.

{
  "@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):

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST \
  RelationshipDefinitions \
  --body '<json-body-from-skeleton-above>' \
  --solution '<solution-uniquename-from-memory-bank>'

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.

{
  "@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":

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"`, —

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

{
  "@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"

Image — @odata.type: Microsoft.Dynamics.CRM.ImageAttributeMetadata, MaxHeight/MaxWidth required
File — @odata.type: Microsoft.Dynamics.CRM.FileAttributeMetadata, MaxSizeInKB required

Parse the ### Cross-entity Reads table. Each row has columns: Calc column | On table | Type | Resolves | Driven by.
Run AFTER all regular columns + relationships from Step 5b have been created (the formula chain references real columns + lookups; creating the calc column before its dependencies returns HTTP 400 from Dataverse).

Per row, invoke the helper:

node "${PLUGIN_ROOT}/scripts/create-calculated-column.js" <envUrl> \
  --table <on-table> \
  --column <calc-column-logical-name> \
  --type <Type column verbatim: string|datetime|decimal|integer|boolean> \
  --formula "<dotted path from Resolves column, e.g. cr3e9_flightid.cr3e9_gateid.cr3e9_gatename>" \
  --display "<human-friendly label inferred from the column name minus _calc suffix>" \
  --solution '<solution-uniquename-from-memory-bank>'

One at a time, sequentially. Calc-column creation is metadata mutation — same concurrency rule as table creation. Print ✓ <calc-column> after each success.
On failure — the helper script prints the OData error inline. Common cases:
- 400 — formula references unknown attribute → the relationship or column the formula needs has not been created yet. Verify Step 5b finished cleanly before retrying.
- 400 — calculated formula not allowed on this navigation → the dotted path tries to traverse 1:many or M:N. The architect should have caught this at Step 6a; flag in summary, skip the row, continue.
- Surface non-recoverable errors to the user with the offending row, then proceed to the next row. Do NOT abort the whole step on one bad row.
After all rows are processed, the publish step (Step 6b) below picks up calc columns automatically — no extra publish call needed.

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST \
  "EntityDefinitions(LogicalName='<table>')/Keys" \
  --body '<entity-key-json>' \
  --solution '<solution-uniquename-from-memory-bank>'

{
  "@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>"]
}

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<table>')?\$select=LogicalName&\$expand=Keys(\$select=SchemaName,KeyAttributes,EntityKeyIndexStatus)"

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

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

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

For each table the app will use (regardless of reuse/extend/create), generate the TS layer from the app root. The CLI reads the environment ID from power.config.json; pass the environment URL resolved earlier in the skill:
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.
node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> POST \
  "PublishXml" \
  --body "{\"ParameterXml\":\"<importexportxml><entities><entity>cr123_table1</entity><entity>cr123_table2</entity></entities></importexportxml>\"}"
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

For each created or extended table, confirm it is queryable after publish:
node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<table>')?\\$select=LogicalName,DisplayName"
200 → confirmed.

404 → table missing after publish — report and stop.

Step 6d — Write .datamodel-manifest.json

After all tables are verified, write the manifest to the project root using the Write tool:
{
  "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
Glob: src/generated/services/*Service.ts
Glob: src/generated/models/*Model.ts
For each table, check the generated service exposes the expected methods:
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; 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:
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:
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:
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:
node "${CLAUDE_SKILL_DIR}/../../scripts/offline-profile-delta.js"
Branch on the JSON status per 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 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. Guessed Dataverse syntax silently 400s.

Reference

scripts/dataverse-request.js — bundled in this plugin

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

Options[]

Status / body	Meaning	Action
404 NotFound	Name is free	Proceed with POST.
200 OK + `IsCustomEntity: true` + matches memory-bank

Status	Meaning	Action
404	Column doesn't exist	Proceed with POST.
200 + `AttributeType` matches the spec	Already created (idempotent re-run)	Skip the POST, log `↻ <column> (already exists, skipped)`, continue.
200 + `AttributeType` differs from the spec	Schema drift — column type was changed manually OR plan changed since last run	STOP and surface to user: "Column `<column>` exists but is `<existingType>`, plan expected `<plannedType>`. Dataverse does NOT allow column-type changes via API — you must delete the column manually and re-run." Do NOT silently overwrite.

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

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

add-dataverse

Source facts

Install options

Review the source files

More from this repository

Add Dataverse

Workflow

Step 1 — Verify project & auth

Step 2 — Resolve plan

Step 2.5 — Path A: Parse user-provided diagram

Step 2.6 — Path B: Spawn architect agent

Step 3 — Setup Dataverse Web API auth

Step 3a — Environment consistency check

Step 3b — Acquire token

Step 4 — Review existing tables

Step 5 — Create / extend tables

Step 5a — Pre-flight collision check (per table, before each POST)

Add Dataverse

Workflow

Step 1 — Verify project & auth

Step 2 — Resolve plan

Step 2.5 — Path A: Parse user-provided diagram

Step 2.6 — Path B: Spawn architect agent

Step 3 — Setup Dataverse Web API auth

Step 3a — Environment consistency check

Step 3b — Acquire token

Step 4 — Review existing tables

Step 5 — Create / extend tables

Step 5a — Pre-flight collision check (per table, before each POST)

More from this repository

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

Post-create collision rescue — hidden tombstone / recent delete

Step 5b — Create / extend

Step 5c — Create calculated columns from ### Cross-entity Reads

Step 5d — Create alternate keys for unique business identifiers

Step 6 — Add data sources

Step 6b — Publish customizations

Step 6c — Verify tables exist

Step 6d — Write .datamodel-manifest.json

Step 7 — Inspect generated files

Step 8 — Type-check

Step 8.5 — Offline profile reconciliation

Step 9 — Summary

Key Rules

Reference

Step 5c — Create calculated columns from `### Cross-entity Reads`

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