setup-datamodel

Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

Set Up Dataverse Data Model

Guide the user through creating Dataverse tables, columns, and relationships for their Power Pages site. Follow a systematic approach: verify prerequisites, obtain a data model (via AI analysis or user-provided diagram), review and approve, then create all schema objects via OData API.

Core Principles

• Never create without approval: Always present the full data model proposal and get explicit user confirmation before making any Dataverse changes.
• Use TaskCreate/TaskUpdate: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.
• Resilient execution: Refresh tokens proactively, check for existing tables before creating, and report failures without automated rollback.

Initial request: $ARGUMENTS

---

Phase 1: Verify Prerequisites

Goal: Confirm PAC CLI authentication, acquire an Azure CLI token, and verify API access

Actions:

1. Create todo list with all 8 phases (see Progress Tracking table)
2. Follow the prerequisite steps in ${PLUGIN_ROOT}/references/dataverse-prerequisites.md to verify PAC CLI auth, acquire an Azure CLI token, and confirm API access. Note the environment URL as <envUrl> for subsequent script calls.

Output: Verified PAC CLI auth, valid Azure CLI token, confirmed API access, <envUrl> noted

---

Phase 2: Choose Data Model Source

Goal: Determine whether the user will upload an existing ER diagram or let AI analyze the site

Actions:

🚦 Gate (plan · setup-datamodel:2.source): Decide whether the user uploads an existing ER diagram or the data-model-architect agent infers the model. Choice routes the rest of the skill into Path A vs Path B.

Trigger: Entering Phase 2. Why we ask: Auto-picking either path can run a multi-minute architect agent against the wrong intent (Path B) or skip Dataverse-existence checks (Path A). Cancel leaves: Nothing — no Dataverse calls made yet.

1. Ask the user how they want to define the data model using the AskUserQuestion tool:

   Question: "How would you like to define the data model for your site?"

   Option	Description
   Upload an existing ER diagram	Provide an image (PNG/JPG) or Mermaid diagram of your existing data model
   Let the Data Model Architect figure it out	The Data Model Architect will analyze your site's source code and propose a data model automatically

2. Route to the appropriate path:

Path A: Upload Existing ER Diagram

If the user chooses to upload an existing diagram:

1. Ask the user to provide their ER diagram. Supported formats:

   • Image file (PNG, JPG) — Use the Read tool to view the image and extract tables, columns, relationships, and cardinalities from it
   • Mermaid syntax — The user can paste Mermaid ER diagram text directly in chat
   • Text description — A structured list of tables, columns, and relationships

2. Parse the diagram into the same structured format used by the data-model-architect agent:

   • Publisher prefix (ask the user, or retrieve from the environment via pac env who)
   • Table definitions: logicalName, displayName, status (new/modified/reused), columns, relationships
   • Column definitions: logicalName, displayName, type, required
   • Relationship definitions: type (1:N or M:N), referenced/referencing tables

3. Query existing Dataverse tables (same as Phase 3 would) to mark each table as new, modified, or reused.

4. Generate a Mermaid ER diagram from the parsed data (if the user provided an image or text) for visual confirmation.

5. Proceed directly to Phase 4: Review Proposal with the parsed data model.

Path B: Let the Data Model Architect Figure It Out

If the user chooses to let the Data Model Architect figure it out, proceed to Phase 3: Invoke Data Model Architect (the existing automated flow).

Output: Data model source chosen and, for Path A, parsed data model ready for review

---

Phase 3: Invoke Data Model Architect

Goal: Spawn the data-model-architect agent to autonomously analyze the site and propose a data model

Actions:

1. Use the Task tool to spawn the data-model-architect agent. This agent autonomously:

   • Analyzes the site's source code to infer data requirements
   • Queries existing Dataverse tables via OData GET requests
   • Identifies reuse opportunities (reuse, extend, or create new)
   • Proposes a complete data model with an ER diagram

2. Spawn the agent:

   Task tool:
     subagent_type: general-purpose
     prompt: |
       You are the data-model-architect agent. Follow the instructions in
       the agent definition file at:
       ${PLUGIN_ROOT}/agents/data-model-architect.md
   
       Analyze the current project and Dataverse environment, then propose
       a complete data model. Return:
       1. Publisher prefix
       2. Table definitions (logicalName, displayName, status, columns, relationships)
       3. Mermaid ER diagram
   

3. Wait for the agent to return its structured proposal before proceeding.

Output: Structured data model proposal from the agent (publisher prefix, table definitions, ER diagram)

---

Phase 4: Review Proposal

Goal: Present the data model proposal to the user and get explicit approval before creating anything

Actions:

4.1 Present Proposal

Present the data model proposal directly to the user as a formatted message, including:

• Publisher prefix
• All proposed tables with columns (logical names + display names)
• Relationship descriptions
• Mermaid ER diagram
• Which tables are new vs. modified vs. reused

4.2 Get User Approval

🚦 Gate (plan · setup-datamodel:4.2.approval): Final sign-off on the data model proposal before any Dataverse write. Cancel here stops the skill with zero side effects.

Trigger: Phase 4.1 rendered the proposal (tables, columns, relationships, ER diagram). Why we ask: Tables and columns get created in Dataverse against the user's actual schema intent — column types and relationship cardinalities are awkward to undo. Cancel leaves: Nothing — no EntityDefinitions POST yet, no .datamodel-manifest.json write.

Use AskUserQuestion to get approval:

• If "Approve and create tables (Recommended)": Proceed to Phase 5
• If "Request changes": Ask what they want changed, modify the proposal, and re-present for approval
• If "Cancel": Stop the skill

Only proceed to creation after explicit user approval.

Output: User-approved data model proposal

---

Phase 5: Pre-Creation Checks

Goal: Refresh the token, verify what already exists in Dataverse, and build the creation plan to avoid duplicates

Actions:

5.1 Refresh Token

Re-acquire the auth token (tokens expire after ~60 minutes):

node "${PLUGIN_ROOT}/scripts/verify-dataverse-access.js" <envUrl>

5.2 Query Existing Tables

For each table in the approved proposal marked as new, check whether it already exists:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET "api/data/v9.2/EntityDefinitions(LogicalName='<table_logical_name>')"

• If 404: Table does not exist, proceed to create it
• If 200: Table already exists — skip creation, warn the user

For tables marked as modified, verify the table exists (it should) and check which columns are missing.

5.3 Build Creation Plan

From the pre-creation checks, build a list of:

• Tables to create (new tables that don't exist yet)
• Columns to add (new columns on existing/modified tables)
• Relationships to create
• Tables/columns to skip (already exist)

Inform the user of any skipped items.

Output: Finalized creation plan with tables, columns, and relationships to create or skip

---

Phase 6: Create Tables & Columns

Goal: Create each approved table and its columns using the Dataverse OData Web API

Actions:

Refer to references/odata-api-patterns.md for full JSON body templates.

6.1 Create Tables

For each new table, POST to the EntityDefinitions endpoint:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST "api/data/v9.2/EntityDefinitions" --body '<JSON body from references/odata-api-patterns.md>'

Use the deep-insert pattern to create the table and its columns in a single POST request. See references/odata-api-patterns.md for the complete JSON structure.

6.2 Add Columns to Existing Tables

For tables marked as modified, add new columns one at a time:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST "api/data/v9.2/EntityDefinitions(LogicalName='<table>')/Attributes" --body '<column JSON from references/odata-api-patterns.md>'

6.3 Track Progress

Track each creation attempt and its result (success/failure/skipped). Do NOT attempt automated rollback on failure — report failures and continue with remaining items.

6.4 Refresh Token if Needed

If creating many tables, the dataverse-request.js script handles 401 token refresh automatically. No manual refresh is needed between batches.

Output: All approved tables and columns created (or failures reported)

---

Phase 7: Create Relationships

Goal: Create all relationships between the newly created and existing tables

Actions:

7.1 One-to-Many Relationships

Create lookup columns that establish 1:N relationships:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST "api/data/v9.2/RelationshipDefinitions" --body '<relationship JSON from references/odata-api-patterns.md>'

7.2 Many-to-Many Relationships

Create M:N relationships (intersect tables are created automatically):

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST "api/data/v9.2/RelationshipDefinitions" --body '<M:N relationship JSON from references/odata-api-patterns.md>'

7.3 Track Relationship Creation

Track each relationship creation attempt. Report failures without rolling back.

Output: All approved relationships created (or failures reported)

---

Phase 8: Publish & Verify

Goal: Publish all customizations, verify tables exist, write the manifest, and present a summary

Actions:

8.1 Publish Customizations

Publish all customizations so the new tables and columns become available:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST "api/data/v9.2/PublishXml" --body '{"ParameterXml":"<importexportxml><entities><entity>cr123_project</entity><entity>cr123_task</entity></entities></importexportxml>"}'

See references/odata-api-patterns.md for the full PublishXml pattern.

8.2 Verify Tables Exist

For each created table, run a verification query:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET "api/data/v9.2/EntityDefinitions(LogicalName='<table>')?$select=LogicalName,DisplayName"

8.3 Write Manifest

After successful verification, write .datamodel-manifest.json to the project root. This file records which tables and columns were verified to exist, and is used by the validation hook.

{
  "environmentUrl": "https://org12345.crm.dynamics.com",
  "tables": [
    {
      "logicalName": "cr123_project",
      "displayName": "Project",
      "status": "new",
      "columns": [
        { "logicalName": "cr123_name", "type": "String" },
        { "logicalName": "cr123_description", "type": "Memo" }
      ]
    }
  ]
}

Use the Write tool to create this file at <PROJECT_ROOT>/.datamodel-manifest.json. Only include tables and columns that were confirmed to exist in Step 8.2. See ${PLUGIN_ROOT}/references/datamodel-manifest-schema.md for the full schema specification.

8.4 Record Skill Usage

Reference: ${PLUGIN_ROOT}/references/skill-tracking-reference.md

Follow the skill tracking instructions in the reference to record this skill's usage. Use --skillName "SetupDatamodel".

8.5 Present Summary

Present a summary to the user:

Include:

• Total tables created/modified/reused/failed
• Total columns created/skipped/failed
• Total relationships created/failed
• Any errors encountered with details
• Location of the manifest file (.datamodel-manifest.json)

8.6 Suggest Next Steps

After the summary, suggest:

• Review created tables in the Power Pages maker portal
• Populate tables with sample data for testing: /add-sample-data
• Integrate tables with your site's frontend via Web API: /integrate-webapi
• If the site is not yet built: /create-site
• If the site is ready to deploy: /deploy-site

Output: Published customizations, verified tables, manifest written, summary presented

---

Important Notes

Throughout All Phases

• Use TaskCreate/TaskUpdate to track progress at every phase
• Ask for user confirmation at key decision points (see list below)
• Token refresh is automatic — the dataverse-request.js script handles 401 token refresh and 429/5xx retry internally
• Report failures without rollback — track each creation attempt and continue with remaining items on failure

Key Decision Points (Wait for User)

1. After Phase 2: Data model source chosen (upload vs. AI)
2. After Phase 4: Approve data model proposal before any creation
3. After Phase 5: Acknowledge any skipped items before proceeding
4. After Phase 8: Review summary and choose next steps

Progress Tracking

Before starting Phase 1, create a task list with all phases using TaskCreate:

Mark each task in_progress when starting it and completed when done via TaskUpdate. This gives the user visibility into progress and keeps the workflow deterministic.

---

Begin with Phase 1: Verify Prerequisites