Microsoft Dataverse plugin for coding agents, covering record CRUD, bulk data operations, advanced queries, schema and metadata, administration, security, environment management, and solution lifecycle through MCP, CLI, and SDK workflows.

GitHub stars
260

Install

/plugin install dataverse@dataverse-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add microsoft/Dataverse-skills.

Contents

Discovered from source

Skills 10

Skill: Environment Admin — Bulk Delete, Retention, Org Settings, OrgDB, Recycle Bin

⚠️ Critical safety rules — read first

  1. Bulk delete is irreversible and bypasses the recycle bin. pac data bulk-delete schedule without --fetchxml deletes every record in the table. Refuse to run until the user explicitly says ALL (or ALL RECORDS) and the entity logical name — e.g., "yes, delete ALL records in contact". Bare "yes" rejected. Empty-filter FetchXML does NOT bypass this gate. See Bulk Delete Commands for the full rule and disambiguation flow.
  2. Settings allowlist is hard. Only the 37 PPAC toggles in Allowed settings may be read or updated. Any other setting must be refused: "That setting is out of scope for dv-admin. Use the Power Platform admin center."
  3. Recycle bin disable is PATCH, never DELETE. PATCH statecode=1, statuscode=2, isreadyforrecyclebin=false. DELETE enqueues async opt-out and orphans per-entity configs — see references/recycle-bin.md.
  4. System tables warning. Unfiltered bulk delete on systemuser, businessunit, organization, or role breaks the environment. Warn additionally before running.

Four mechanisms — pick based on where the setting lives:

MechanismUse forHow
PAC CLI (pac org update-settings / list-settings)Columns on the organization entity (audit, plugin trace, typeahead, quick find, canvas/flow solutions, email validation, audit retention)--name <column> --value <value> — accepts any org column, not just the legacy audit ones
Python SDK — OrgDB XMLKeys inside the orgdborgsettings XML blob (MCP, search, Fabric, Work IQ, TDS endpoint, attachment security, ownership, address records, block unmanaged, delete users, Excel AI)Read XML → parse → modify → PATCH whole blob back on organizations({id})
Python SDK — recyclebinconfigsRecycle bin on/off + retention daysCREATE/PATCH recyclebinconfigs entity record
Python SDK — settingdefinition + organizationsettingsApp-level / plan-level security role togglesLook up settingdefinition by uniquename → CREATE or PATCH organizationsettings row with value

ERP batch admin: see references/erp-batch.md. Planning-only ERP requests may read skills/references, but make no environment calls or file writes.

Do NOT write Python scripts for operations PAC CLI can handle. Do NOT mix mechanisms (e.g., don't hand-PATCH an org column that PAC CLI already covers).

Skill boundaries

Use dv-data for record CRUD and sample data, dv-metadata for tables / columns / relationships, dv-query for reading records, dv-solution for solution export/import, dv-security for roles and self-elevate, pac admin --help for tenant governance (DLP, env lifecycle).

Allowed settings — hard allowlist

The 37 PPAC toggles below are the only ones this skill may read or update (35 unique backend keys — SearchAndCopilotIndexMode and auditretentionperiodv2 each cover two toggles). Examples that are out of scope and must be refused per the safety rule above: sessiontimeoutinmins, isautosaveenabled, IsShadowLakeEnabled, IsArchivalEnabled. Do not run pac org list-settings without --filter, and do not dump the whole orgdborgsettings XML for a non-allowlisted setting.

Organization entity columns — use PAC CLI (14)

Use pac org list-settings --filter <column> to read, pac org update-settings --name <column> --value <value> to write. PAC CLI accepts any column on the organization entity — not just the legacy audit ones.

#PPAC labelColumnType
1Start Auditingisauditenabledbool
2Audit user access (Log access)isuseraccessauditenabledbool
3Start Read Auditing (Read logs to Purview)isreadauditenabledbool
4Plugin trace log settingplugintracelogsettingint: 0 Off, 1 Exception, 2 All
5Single table search optiontablescopeddvsearchinappsbool
6Prevent slow keyword filter for quick find termsallowleadingwildcardsinquickfindint: 0 prevent, 1 allow (UI "prevent=On" flips to 0)
7Quick Find record limitsquickfindrecordlimitenabledbool
8Use quick find view for searching on grids/subgridsusequickfindviewforgridsearchbool
9Canvas apps in Dataverse solutions by defaultenablecanvasappsinsolutionsbydefaultbool
10Cloud flows in Dataverse solutions by defaultenableflowsinsolutionbydefaultbool (note: solution singular)
11Enable email address validation (preview)isemailaddressvalidationenabledbool
12Minimum number of characters to trigger typeaheadlookupcharactercountbeforeresolveint (0–MAX_INT, null = feature off)
13Delay between character inputs that trigger a searchlookupresolvedelaymsint ms (default 250)
14Audit log retention policy / Custom retention period (days)auditretentionperiodv2int days (-1 = Forever; presets 30/90/180/365/730/2555; max 365000)

OrgDB XML keys — use Python SDK on orgdborgsettings blob (17)

PascalCase is significant (IsMCPEnabled, not IsMcpEnabled). Full key list with PPAC labels and types lives in references/orgdb-settings.md. Notable keys: IsMCPEnabled, IsMCPPreviewEnabled, SearchAndCopilotIndexMode, IsLinkToFabricEnabled, IsFabricVirtualTableEnabled, ShowDataInM365Copilot, EnableWorkIQ, IsLockdownOfUnmanagedCustomizationEnabled, EnableSecurityOnAttachment, EnableTDSEndpoint, AllowAccessToTDSEndpoint, EnableOwnershipAcrossBusinessUnits, CreateOnlyNonEmptyAddressRecordsForEligibleEntities, EnableDeleteAddressRecords, BlockDeleteManagedAttributeMap, EnableSystemUserDelete, IsExcelToExistingTableWithAssistedMappingEnabled.

SearchAndCopilotIndexMode is one int (0–3) that encodes two UI toggles — Dataverse search × M365 Copilot search:

ValueDataverse searchM365 Copilot search
0OffOn
1OnOn
2OffOff
3OnOff

recyclebinconfigs entity — use Python SDK (2, org-level only)

Two toggles operate on the org-level recyclebinconfigs row (filtered by the organization entity's MetadataId): on/off (statecode + statuscode + isreadyforrecyclebin) and cleanup days (cleanupintervalindays). Per-table toggles are out of scope — refuse requests like "enable recycle bin for contact only". Full lifecycle in references/recycle-bin.md.

settingdefinition + organizationsettings — use Python SDK (2)

Two allowlisted toggles, both bool stored as string: PowerAppsAppLevelSecurityRolesEnabled (canvas apps), PlanShareSecurityRolesEnabled (plan designer). Read default from settingdefinition, CREATE/PATCH organizationsettings for the override. Full Python in references/settings-overrides.md.

Preview Before Running

  • Destructive / stateful (bulk delete schedule/cancel/pause/resume, settings updates, recycle bin toggle, role assignment, self-elevate, retention set) — preview in prose: what's changing, new value, target environment(s). Use placeholders (<ENV_URL>) for unknowns and ask for missing values in the same turn. Skip the raw CLI block.
  • Read-only (list-settings, show job, read OrgDB / recycle bin status) — one-sentence prose preview is enough.

The user must be able to evaluate the action from your first response. A bare "which environment?" fails; a one-line prose preview passes.

Examples

Pause bulk delete (destructive, ID supplied):

  • ❌ "The command requires approval. Please confirm to pause the job."
  • ✅ "I'll pause bulk delete job <job-id> on the active environment. Confirm to proceed."

Audit status across N environments (read-only, multi-call):

  • ❌ Sequential pac org fetch per env, or starting with Python/SDK because it "feels like a query."
  • ✅ "I'll run pac org list-settings --filter audit in parallel across all N environments (one &-batch, single wait)."

How to Read or Update Org Settings

Org settings always go through pac org list-settings / pac org update-settings — never raw Web API, FetchXML, PowerShell, or Python for org columns. Use --filter <substring> for category reads in one call. Multi-environment work runs in parallel via & + wait in ONE bash call.

Single setting:

pac org list-settings --filter isauditenabled --environment <url>

Category read (returns every match, e.g. all audit settings in one call):

pac org list-settings --filter audit --environment <url>

Multi-environment — parallel in ONE bash call:

pac org list-settings --filter audit --environment <url1> &
pac org list-settings --filter audit --environment <url2> &
pac org list-settings --filter audit --environment <url3> &
wait

If pac org list-settings fails for a setting, that setting is NOT an org column — check the mechanism routing in the four-mechanism table at the top, then use the appropriate Python pattern. Do NOT fall back to Web API, PowerShell, FetchXML, or pac org fetch for org columns.


Prerequisites

  • PAC CLI latest .NET Framework build — pac data bulk-delete/pac data retention are only in the .NET Framework build (not the dotnet tool version). Check pac help; if it shows .NET 10/.NET 8, run pac install latest && pac use latest.
  • Authenticated (pac auth create), active profile (pac auth list), and System Administrator privilege on the target environment.
  • Headless hosts: SDK handles most settings (they are organization records); service principal for PAC-only ones. See dv-connect/references/headless-hosts.md.

Multi-Environment Operations — Always Parallel

The same & + wait pattern from list-settings applies to every multi-env operation (update-settings, bulk-delete, etc.) — N backgrounded calls in ONE bash call, never sequential or for loops.


Common Mistakes — Do NOT Use These

These flags do not exist. Using them will produce errors.

Bulk Delete

WrongCorrect
--filteruse --fetchxml with a FetchXML string
--query / --where / --conditionuse --fetchxml
--date / --before / --older-thanencode date in FetchXML <condition>
--job-iduse --id
--all / --purge / --truncateomit --fetchxml to target all records (warn user first)

Retention

WrongCorrect
--fetchxmluse --criteria (same FetchXML format, different flag name)
--filter / --query / --policyuse --criteria
--enable / --activateuse pac data retention enable-entity
--tableuse --entity
--operation-id / --job-id / --guiduse --id

Org Settings

WrongCorrect
--enable-audit / --audituse --name isauditenabled --value true
--trace / --plugin-trace / --logginguse --name plugintracelogsetting --value 2
--setting / --key / --flaguse --name
String values like "all" or "enabled" for option setsuse integers: 0, 1, 2

Bulk Delete Commands

Schedule a Bulk Delete Job

pac data bulk-delete schedule --entity activitypointer \
    --fetchxml "<fetch><entity name='activitypointer'><filter><condition attribute='createdon' operator='lt' value='2024-01-01'/></filter></entity></fetch>"
pac data bulk-delete schedule --entity email \
    --fetchxml "<fetch><entity name='email'><filter><condition attribute='createdon' operator='lt' value='2024-06-01'/></filter></entity></fetch>" \
    --job-name "Cleanup old emails" --recurrence "FREQ=DAILY;INTERVAL=1"
ArgumentAliasRequiredDescription
--entity-eYesLogical name of the table
--fetchxml-fxNoFetchXML filter. See the hard-stop rule below — if omitted, ALL records in the table are deleted.
--job-name-jnNoDescriptive name for the job
--start-time-stNoISO 8601 start time. Defaults to now
--recurrence-rNoRFC 5545 pattern (e.g., FREQ=DAILY;INTERVAL=1)
--environment-envNoTarget environment URL

Hard stop: no --fetchxml means ALL records

pac data bulk-delete schedule without --fetchxml targets every record in the table and is irreversible (does not go through recycle bin). Required gate:

  1. Refuse until the user explicitly acknowledges with the word ALL (or ALL RECORDS) and the entity logical name — e.g., "yes, delete ALL records in contact". Bare "yes" rejected.
  2. Disambiguate vague asks ("clean up old emails") — propose a FetchXML filter with date / statecode / owner conditions before showing any command.
  3. Empty-filter FetchXML doesn't bypass the gate — <filter/> or <filter><condition><value/></condition></filter> still targets every record.
  4. Scope: applies to bulk-delete schedule only. cancel, pause, resume, show, list don't need it.

For system tables (systemuser, businessunit, organization, role), additionally warn that unfiltered bulk delete breaks the environment.

Manage Jobs

pac data bulk-delete list --environment https://myorg.crm.dynamics.com
pac data bulk-delete show --id <job-id>
pac data bulk-delete pause --id <job-id>
pac data bulk-delete resume --id <job-id>
pac data bulk-delete cancel --id <job-id>

Retention / Archival Commands

Data retention moves old records to long-term storage without permanently deleting them.

Agentic Flow

Step 1: pac data retention enable-entity --entity activitypointer
Step 2: pac data retention list
Step 3: pac data retention set --entity activitypointer --criteria "<fetchxml>..."
Step 4: pac data retention show --id <config-id>

Commands

pac data retention enable-entity --entity activitypointer --environment https://myorg.crm.dynamics.com
pac data retention set --entity activitypointer \
    --criteria "<fetch><entity name='activitypointer'><filter><condition attribute='createdon' operator='lt' value='2023-01-01'/></filter></entity></fetch>"
pac data retention list --environment https://myorg.crm.dynamics.com
pac data retention show --id <config-id>
pac data retention status --id <operation-id>
ArgumentAliasRequiredDescription
--entity-eYesLogical name of the table
--criteria-cYesFetchXML defining which records to archive
--start-time-stNoISO 8601 start time. Defaults to now
--recurrence-rNoRFC 5545 recurrence pattern
--environment-envNoTarget environment URL

Retention vs Bulk Delete

ScenarioUse
Data no longer needed, permanently deleteBulk Delete
Data must be preserved for complianceRetention (archive)

Organization Settings Commands

List Settings

pac org list-settings --environment https://myorg.crm.dynamics.com
pac org list-settings --filter isauditenabled --environment https://myorg.crm.dynamics.com

Update a Setting

pac org update-settings --name isauditenabled --value true --environment https://myorg.crm.dynamics.com
pac org update-settings --name plugintracelogsetting --value 2 --environment https://myorg.crm.dynamics.com

Args: --name <column> (required), --value <value> (required; true/false for bool, int for option sets), --environment <url> (optional). Allowed columns are the 14 listed in Allowed settings — anything else is out of scope.

Batch workflow: pac admin list → filter targets → confirm → run all update-settings calls in parallel (& + wait) → render summary table.


Advanced Settings (Python SDK — PAC CLI Cannot Handle These)

OrgDB, recycle bin, and settings-definition overrides each need raw Web API or the Python SDK — PAC CLI does not cover them. The four-mechanism routing table at the top of this skill (§ Skill) maps each setting to its mechanism. Sub-sections below summarise the patterns and link to the references for full Python.

OrgDB Settings (orgdborgsettings XML)

OrgDB settings live as PascalCase XML elements inside the orgdborgsettings column of the organizations entity. PAC CLI cannot read or write these — use raw Web API.

Quick reference: GET /organizations?$select=organizationid,orgdborgsettings → parse XML with xml.etree.ElementTree → modify or SubElement → PATCH /organizations({id}) with the serialized XML.

For the read / update / remove Python patterns and the 17-key allowlist, see references/orgdb-settings.md. Keys are case-sensitive (IsMCPEnabled, not IsMcpEnabled).

Recycle Bin Configuration

Recycle bin settings live in the recyclebinconfigs entity (NOT orgdborgsettings). PAC CLI cannot manage them — use raw Web API.

Quick reference: filter recyclebinconfigs by _extensionofrecordid_value eq <ORG_ENTITY_METADATA_ID> (the org-level metadata ID is a system constant: e1bd1119-6e9d-45a4-bc15-12051e65a0bd).

  • Enable: PATCH statecode=0, statuscode=1, isreadyforrecyclebin=true (or POST a new config). isreadyforrecyclebin: true is required to force the synchronous opt-in path.
  • Disable: PATCH statecode=1, statuscode=2, isreadyforrecyclebin=false. Do NOT DELETE — it enqueues async opt-out and orphans per-entity configs.
  • Drain in-flight ProcessRecycleBin async jobs (operationtype eq 50, statecode ne 3) before any second toggle.

For the full Python lifecycle (read / enable / disable / async-drain helper), the cache-vs-DB race explanation, and the per-table out-of-scope rule, see references/recycle-bin.md.

Settings-Definition Overrides (app/plan security roles)

Two allowlisted toggles (PowerAppsAppLevelSecurityRolesEnabled, PlanShareSecurityRolesEnabled) live in a join: settingdefinition (defaults) + organizationsettings (overrides). PAC CLI doesn't manage these.

Quick reference: look up the settingdefinitionid by uniquename, then either CREATE an organizationsettings row with value (string "true"/"false") or PATCH the existing row. DELETE on the override row reverts to the default.

For the read + idempotent CREATE/PATCH Python and the gating notes, see references/settings-overrides.md.

Operational confirmation rules

The four rules in the safety callout at the top of this file cover the irreversible / destructive cases. The rules below cover the non-destructive but still impactful operations:

  • Confirm before changing org settings that affect all users.
  • For multi-environment updates, show the list of target environments and get confirmation first.
  • For OrgDB settings, warn that incorrect values can break environment features.
  • For recycle bin cleanup interval changes, warn that reducing the interval permanently deletes recycled records sooner.
  • For recycle bin enable/disable specifically: always set isreadyforrecyclebin explicitly (true on enable, false on disable), and drain any in-flight ProcessRecycleBin async jobs before any second toggle. Omitting these can produce EntityBinUpdateAction called for entity <x> which is not enabled for RecycleBin on unrelated platform operations.

Skill: Connect

One-step, idempotent Dataverse connection. Each step checks if it's already done and skips.

Environment-First Rule — All metadata and plugin registrations are created in the environment via API/scripts, then pulled into the repo. Never hand-write solution XML to create components.

Execute steps in order; do not skip ahead. Exception: Step 0 can short-circuit the flow if the workspace is already set up.

Host entry test (FIRST — before Step 0). A local Windows/macOS host is capable by default, whichever agent drives it — it can run the CLIs, use persistent credentials, and host local MCP servers; an approval/sandbox gate isn't a constraint, and a missing CLI = install it. Constrained only when a runtime can't start, auth can't persist, or the host is explicitly ChatGPT Work Mode / Codex cloud / CI / no-keyring Linux (deterministic table: headless-hosts.md). Constrained → install only Python + pip deps, .env, scripts/auth.py, verify python scripts/auth.py --check, skip CLI / PAC / MCP. Capable → normal flow below.


Step 0: Detect existing setup (run this first)

Before touching anything, check whether this workspace is already connected to a Dataverse environment. Repeating setup on an already-configured workspace overwrites .env, re-registers MCP, and wastes time.

Gemini supports GA only. If Preview is requested, explain and stop before setup shortcuts.

Run these checks in order. If all four pass, skip straight to Step 7 (final verification) and stop there.

  1. .env is present and complete — file exists at the workspace root and contains non-empty values for DATAVERSE_URL, TENANT_ID, and MCP_CLIENT_ID
  2. MCP is registered — the host MCP list has a dataverse-* entry, or Gemini has its bundled dataverse entry, pointing at DATAVERSE_URL
  3. Both auth surfaces match .env — dataverse auth who shows a profile whose Environment Url matches DATAVERSE_URL, AND pac org who against a PAC profile for the same URL succeeds. (DV CLI auth covers Connect / Data / Query / Metadata / MCP / Python; PAC auth covers dv-solution and dv-admin. Both are front-loaded at connect time so neither prompts later.)
  4. Python SDK is importable and current — python -c "from PowerPlatform.Dataverse.client import DataverseClient; import pandas; from importlib.metadata import version; v=version('PowerPlatform-Dataverse-Client'); parts=tuple(int(p) for p in v.split('.')[:2]); assert parts>=(1,1), f'SDK {v} is outdated, need >=1.1.0'" exits 0

If all pass: First ensure .env has valid attribution — set DATAVERSE_PLUGIN_VERSION to the loaded manifest version and add DATAVERSE_PLUGIN_AGENT (detected host, per Step 3) if absent or a stale unknown/placeholder. Confirm the detected setup (URL, profile, MCP server), and jump to Step 7. Do not otherwise rewrite .env, re-register MCP, or re-run pip install.

If any check fails: Proceed through the normal flow (Steps 1–7), but still use each step's own skip condition. A partially-configured workspace doesn't need a full redo — e.g., if only .env and MCP are missing but tools and auth are fine, start at Step 2 or Step 3.


Step 1: Ensure tools are installed

Check each tool independently -- report all missing tools at once. See tools-setup.md for install commands.

ToolCheck
Python 3python --version
Gitgit --version
Node.jsnode --version
PAC CLIpac (prints version banner; pac --version is not valid) (see tools-setup.md if not in PATH)
Dataverse CLInpm list -g @microsoft/dataverse
.NET SDKdotnet --version
Azure CLIaz --version

.NET SDK is needed for PAC CLI but NOT for the Dataverse CLI (the npm package bundles its own runtime). Node.js powers the Dataverse CLI npm package (@microsoft/dataverse), which is used as the MCP proxy and for scripted data plane actions. Azure CLI is used as a fallback for environment discovery when PAC CLI isn't available (see mcp-configuration.md Step 3b). GitHub CLI is not needed for connecting — it's used later for ALM/CI/CD scenarios (see dv-solution).

If any tool is missing, install it (see tools-setup.md), then verify. If winget installs a tool but it's not in PATH, ask the user to restart the terminal.

After Python is confirmed, check if deps are already present before installing:

python -c "from PowerPlatform.Dataverse.client import DataverseClient; import azure.identity, msal, msal_extensions, requests, pandas; print('OK')"

If it prints OK, skip pip. Otherwise:

pip install --upgrade azure-identity requests PowerPlatform-Dataverse-Client pandas msal msal-extensions

msal + msal-extensions let scripts/auth.py reuse the dataverse auth create cache -- one sign-in for CLI, MCP, Python.

After Node.js is confirmed, install the Dataverse CLI only if missing (do not re-run on every connect -- on managed devices each @latest fetch can trigger npm-registry security prompts; see tools-setup.md):

npm install -g @microsoft/dataverse@latest

Skip condition: All tools present, Python SDK installed, and pandas importable (python -c "import pandas").


Step 2: Discover and select the environment

Before asking the user for a URL, check what's already available.

Auth tool choice. Two tools, two AAD apps, two caches — front-load both at connect:

  1. dataverse auth create (app 0c412cc3-…) covers DV CLI + MCP + Python.
  2. pac auth create (PAC's own app) covers dv-solution + dv-admin.

Check for an existing DV CLI profile first, then fall back to PAC for environment discovery if needed:

dataverse auth list
dataverse auth who
pac auth list   # PAC profiles are still useful for env discovery / pac org list

If dataverse auth who shows a profile and its environment matches the user's target:

  • Reuse it. Set DATAVERSE_URL and TENANT_ID from the profile.

If no DV CLI profile exists (or it points at the wrong environment):

  • Ask: "Do you want to connect to an existing environment or create a new one?"

Before selecting, check for tenant/region mismatch. If the target URL uses a different region than the authenticated account's environments, create a new profile for the correct tenant rather than reuse the old one:

dataverse auth create --environment <url>          # interactive (WAM broker on Windows → no browser tab)
dataverse auth create --environment <url> --deviceCode   # headless / remote / SSH

If the user hits an admin-consent error, the CLI prints the correct scope-scoped consent URL to share with a tenant admin — do not synthesize one.

To switch between existing DV CLI profiles:

dataverse auth select --name <profile-name>

To create a new environment (requires admin permissions):

pac admin create --name "<name>" --type "<type>" --region "<region>"

If this fails with permissions error, guide the user to Power Platform Admin Center to create it, then connect.

Confirm connection:

dataverse auth who
dataverse org who --context "app=dataverse-skills/<ver>;skill=dv-connect;agent=<agent>"

Parse the output to extract DATAVERSE_URL, TENANT_ID, and — on ERP-linked envs — ERP_URL (see erp-detection.md).

If neither command shows a tenant ID, fall back to:

curl -sI https://<org>.crm.dynamics.com/api/data/v9.2/ \
  | grep -i "WWW-Authenticate" \
  | sed -n 's|.*login\.microsoftonline\.com/\([^/]*\).*|\1|p'

Step 2b: Front-load PAC CLI auth for the same environment

PAC uses its own AAD app, so a separate sign-in is required for dv-solution and dv-admin — do it now.

pac auth list                                       # skip if a profile for $DATAVERSE_URL exists
pac auth create --name <orgid> --environment <DATAVERSE_URL>

Use the same account as Step 2. If PAC CLI is not installed, skip with a note that dv-solution / dv-admin will need it later.


Step 3: Create .env

Present authentication options:

How would you like to authenticate with Dataverse?

  1. Interactive login (recommended) — Sign in via browser. No app registration needed. Token stays cached across sessions.
  2. CI/CD service principal — Use CLIENT_SECRET or CLIENT_CERTIFICATE_PATH.

Write .env directly — do not instruct the user to create it:

Use one detected tool_type to derive both MCP_CLIENT_ID and canonical attribution. Set PLUGIN_VERSION from the loaded manifest; Antigravity uses .claude-plugin/plugin.json because native plugin.json has none.

tool_type = "<copilot | claude | cursor | codex | gemini | antigravity | unknown>"
plugin_version = "<plugin manifest version, e.g. 1.5.0>"
mcp_client_id = "aebc6443-996d-45c2-90f0-388ff96faa56" if tool_type == "copilot" else "0c412cc3-0dd6-449b-987f-05b053db9457"
agent_host = {
    "copilot": "copilot", "claude": "claude-code", "cursor": "cursor",
    "codex": "codex", "gemini": "gemini-cli",
    "antigravity": "antigravity-cli",
}.get(tool_type, "unknown")
ide = "<jetbrains if a JetBrains install, else empty; see references/helper-scripts.md>"
agent_host += f"/{ide}" if ide else ""

with open(".env", "w") as f:
    f.write(f"DATAVERSE_URL={dataverse_url}\n")
    f.write(f"TENANT_ID={tenant_id}\n")
    f.write(f"MCP_CLIENT_ID={mcp_client_id}\n")
    f.write(f"DATAVERSE_PLUGIN_VERSION={plugin_version}\n")
    f.write(f"DATAVERSE_PLUGIN_AGENT={agent_host}\n")
    f.write(f"SOLUTION_NAME={solution_name}\n")
    f.write(f"PUBLISHER_PREFIX=\n")  # filled in when solution is created
    f.write(f"PAC_AUTH_PROFILE=nonprod\n")
    if client_id:
        f.write(f"CLIENT_ID={client_id}\n")
    if client_secret:
        f.write(f"CLIENT_SECRET={client_secret}\n")

Ensure .env is in .gitignore:

import os

GITIGNORE_ENTRIES = [
    ".env", ".vscode/settings.json", ".claude/mcp_settings.json",
    ".token_cache.bin", ".dataverse/", "*.snk", "__pycache__/", "*.pyc",
    "solutions/*.zip", "plugins/**/bin/", "plugins/**/obj/",
]
gitignore = open(".gitignore").read() if os.path.exists(".gitignore") else ""
missing = [e for e in GITIGNORE_ENTRIES if e not in gitignore]
if missing:
    with open(".gitignore", "a") as f:
        f.write("\n" + "\n".join(missing) + "\n")

Skip condition: .env already exists with all required values.


Step 4: Set up project structure (new projects only)

If this is a new project (no scripts/ directory):

mkdir -p solutions plugins scripts

Ensure scripts/auth.py and scripts/enable-mcp-client.py exist -- see references/helper-scripts.md.

Copy templates/CLAUDE.md to the repo root if it doesn't exist. Replace placeholders ({{DATAVERSE_URL}}, {{SOLUTION_NAME}}, {{PUBLISHER_PREFIX}}) with values from .env.


Step 5: Verify the connection

dataverse auth who
pac org who
python scripts/auth.py --check

--check makes a real data-plane call (not just a token) — the only proof the org is actually reachable; a token can be minted while the org domain is blocked. All must resolve the same user/environment, proving the DV CLI cache, the PAC profile (Step 2b), and Python's reuse of the shared cache are wired.

If any fail:

  • dataverse auth who fails → re-run Step 2.
  • pac org who fails → re-run Step 2b.
  • python scripts/auth.py --check prints a device-code URL → browser/WAM cache has no Python-reusable token. Auto-fix: re-run dataverse auth create --environment <url> --deviceCode, then retry. If it still prompts, check pip show msal msal-extensions. Headless hosts (ChatGPT / Codex cloud / CI): dataverse auth create can't persist here — don't loop (see headless-hosts.md).
  • python scripts/auth.py --check prints NOT REACHABLE with a connection/timeout error → the org domain is blocked by network egress, not auth. Do NOT report success or a count — see headless-hosts.md remediation.
  • Other Python error → check SDK install and .env.

Before metadata work, also confirm the account has the prvCreateEntity customization privilege — see tools-setup.md.


Step 6: Configure MCP server

Skip this step only when the current host points to the selected environment:

  • Gemini: gemini mcp list resolves bundled server dataverse to the selected URL
  • Antigravity: agy mcp list contains the selected environment
  • Other hosts: their MCP list or config contains a Dataverse server for the selected URL

If MCP is not configured, follow mcp-configuration.md:

  1. Detect which tool the user is running (Copilot, Claude, Cursor, Codex, Gemini, or Antigravity) from context
  2. Set MCP_CLIENT_ID based on tool choice
  3. Get environment URL from .env
  4. Default to GA endpoint (/api/mcp)
  5. Register the MCP server per host (see the per-host blocks below)
  6. Handle Dataverse admin consent and allowlist — prefer dataverse mcp allow <MCP_CLIENT_ID> over the portal (one-time per tenant/environment)
  7. If ERP_URL exists, separately allowlist and validate ERP

Plugin attribution for MCP: This plugin uses the stdio proxy transport (npx @microsoft/dataverse mcp <url>). When registering it, include DATAVERSE_OPERATION_CONTEXT in the env block so the CLI appends it to its User-Agent on requests to /api/mcp. Build the value from .env:

DATAVERSE_OPERATION_CONTEXT=app=dataverse-skills/{DATAVERSE_PLUGIN_VERSION};skill=mcp-direct;agent={DATAVERSE_PLUGIN_AGENT}

For Claude Code (claude mcp add -t stdio), pass it via -e DATAVERSE_OPERATION_CONTEXT=.... For JSON/TOML hosts, add it to the server's environment block.

Important: MCP configuration requires an editor/CLI restart.

For Copilot: Write the JSON config, then:

✅ Dataverse MCP server configured. Restart your editor for changes to take effect.

For Claude: Run the claude mcp add command, then warn the user about the auth popup that will appear on next launch:

✅ Dataverse MCP server registered. Restart Claude Code to enable MCP tools. Remember to use claude --continue to resume the session without losing context.

On restart, a browser window may open to sign in to your Dataverse environment (the MCP proxy authenticating on your behalf). See mcp-configuration.md for details.

For Cursor: Write the JSON config, then:

✅ Dataverse MCP server dataverse-{orgid} configured in ~/.cursor/mcp.json. Reload the Cursor window (Ctrl+Shift+P → "Developer: Reload Window") for the new MCP server to appear under Settings → Tools & MCPs.

On first use the npx @microsoft/dataverse proxy signs in via browser device code, then reuses the shared cache silently. See mcp-configuration.md.

For Codex: Write the TOML config to ~/.codex/config.toml. Codex loads MCP tools only at startup, so don't claim they're callable until the user restarts. Tell the user:

✅ Dataverse MCP server dataverse-{orgid} configured in ~/.codex/config.toml. Restart Codex (CLI) or reload the Codex IDE to load the MCP tools.


Step 7: Final verification

After the editor/CLI restarts, both of these must succeed before declaring the setup complete:

Check 1: the host's MCP list shows the Dataverse server connected

  • Claude: claude mcp list
  • Gemini: gemini extensions list, then gemini mcp list
  • Antigravity: agy mcp list; after restart, /mcp This proves the MCP server starts, but not that data operations work.

Check 2: Agent successfully lists tables via describe/search and returns data

"List the tables in my Dataverse environment."

This proves end-to-end wiring: auth, tenant consent, environment allowlist, and endpoint reachability are all correct. If the agent falls back to PAC CLI or Web API, see mcp-configuration.md troubleshooting.

Only when both checks pass is the setup verified.

Interpreting failures:

  • If Check 1 fails (server not ✓ Connected): the MCP server itself cannot start. Re-run Step 6 and check that npx/Node.js are installed and the MCP registration succeeded.
  • If Check 1 passes but Check 2 fails (server starts but describe/search errors): the server can speak MCP but cannot reach or read Dataverse. Run --validate below to diagnose.

Diagnostic — --validate (for failure investigation only):

npx @microsoft/dataverse mcp {DATAVERSE_URL} --validate

This exercises two Dataverse MCP endpoints with a fresh authentication handshake and reports detailed errors (auth, allowlist, consent, endpoint reachability):

  • GA / Production endpoint — {DATAVERSE_URL}/api/mcp. This is the one the plugin actually uses at runtime.
  • Preview endpoint — {DATAVERSE_URL}/api/mcp_preview. Opt-in per environment; not used by the plugin.

Do not use --validate as a success gate on first-time setup. On a freshly configured workspace, the token cache hasn't warmed up, so --validate can fail with MsalClientException or 403 while MCP is actually working fine on subsequent real calls. Reserve --validate for diagnosing a confirmed failure in Check 1 or Check 2.

How to read --validate output:

  • Look at the GA / Production endpoint (/api/mcp) result first. If this passes, MCP will work for normal plugin usage regardless of what the Preview endpoint reports.
  • A 403 Forbidden on the Preview endpoint (/api/mcp_preview) is expected for most environments. Preview is opt-in per environment; if your environment hasn't enabled it, the Preview check will always fail. This does not indicate a broken setup.
  • Ignore the overall exit code and the ⚠ Partial success warning in this case. The validator returns exit code 1 (failure) unless BOTH /api/mcp and /api/mcp_preview pass. Because most environments don't enable the Preview endpoint, --validate will exit 1 even when MCP is fully functional via the GA endpoint. Focus on per-endpoint results, not the aggregate status.
  • If the GA endpoint (/api/mcp) fails: that's the real signal to investigate — auth, tenant consent, environment allowlist, or endpoint reachability.

MCP Server Capabilities

For what MCP can and can't do (data CRUD + batch up to 25, table/column creation incl. choice/lookup, search/describe, file upload/download) versus the SDK / Web API, see the overview skill's Tool Capabilities matrix.

After verifying MCP works, tell the user:

✅ Connected to Dataverse at {DATAVERSE_URL}. Tools installed, authenticated, MCP live.

You can now:

  • Create tables, columns, and relationships (dv-metadata)
  • Write and import data (dv-data)
  • Query and analyze data (dv-query)
  • Export and promote solutions (dv-solution)

To create your first solution, see the dv-solution skill. To load sample data (accounts, contacts, opportunities), ask: "Load demo data into my Dataverse environment."


Supported Agents

This plugin's skills are natively loaded by GitHub Copilot CLI, Claude Code CLI, Gemini CLI, and Antigravity CLI when installed as a plugin. No manual context loading is needed.

The PAC CLI commands, Python scripts, and XML templates work identically across hosts.

Skill: Data — Create, Update, Delete, and Bulk Import

This skill uses Python and the Dataverse CLI. Do not use Node.js, JavaScript, or any other language for Dataverse scripting. If you are about to run npm install or write a .js file, STOP — you are going off-rails. See the overview skill's Hard Rules.

ERP exception, including planning-only requests: load dv-overview, then read references/erp-writes.md. ERP writes and DMF imports do not use the Dataverse SDK guidance below. A request not to execute operations still permits loading skills and reading local references.

Use the official Microsoft Power Platform Dataverse Client Python SDK for all data write operations.

Official SDK: https://github.com/microsoft/PowerPlatform-DataverseClient-Python PyPI package: PowerPlatform-Dataverse-Client (this is the only official one — do not use dataverse-api or other unofficial packages) Status: GA (1.1.0, Production/Stable)

Skill boundaries

NeedUse instead
Query or read recordsdv-query
Create tables, columns, relationships, forms, viewsdv-metadata
Export or deploy solutionsdv-solution
ERP writesSee references/erp-writes.md

Choosing MCP, CLI, or SDK for writes

CLI fast path: If dataverse auth who shows an active profile, CLI commands (data create/update/delete/upsert/associate/upload) work immediately — no .env, auth.py, or pip needed. SDK and bulk operations still need workspace setup.

If MCP tools are available (create_record, update_record, delete_record), they are the quickest path for a small, interactive set of writes — up to 25 records per call, no script needed. The Dataverse CLI (dataverse data create/update/upsert/delete) handles single-record writes, associate/disassociate, and file uploads as headless one-liners. The SDK is the default for bulk writes beyond 25, data transformation, retry logic, CSV import, or SDK-only operations (upsert with alternate keys — MCP has no upsert tool). Pick the surface that fits the volume and shape of the work.

When you script a write, use the SDK — not hand-rolled HTTP

The MCP/CLI/SDK choice is capability-based (above; and see the overview's Tool Capabilities / Hard Rule 2). This section is narrower: once you've decided to write via a script, use the SDK for anything in its "supports" list rather than hand-rolled urllib/requests — the SDK carries the auth, paging, and retry those re-implement. For the rare operation the SDK doesn't cover, use the dataverse api escape hatch — not hand-rolled urllib.

Correct import (always preceded by sys.path.insert in a full script — see Setup below):

from auth import get_client

WRONG for SDK-supported operations:

from auth import get_token, load_env  # WRONG for SDK-supported ops
import requests                        # WRONG for SDK-supported ops

get_token() and requests exist ONLY for genuine gaps with no managed path (global option sets, unbound actions) — and even then prefer the managed dataverse api escape hatch. Forms/views, aggregation, and N:N reads are all covered by the SDK; see dv-query and dv-metadata.


What This SDK Supports (Data Operations)

  • Record writes: create, update, delete
  • Record reads within write workflows (e.g., lookup resolution) — for standalone queries see dv-query
  • Upsert (with alternate key support)
  • Bulk operations: CreateMultiple, UpdateMultiple, UpsertMultiple, bulk delete (records.delete(table, [ids]) runs the server-side BulkDelete action), multi-operation batching (client.batch)
  • File column uploads (chunked for files >128MB)
  • Context manager with HTTP connection pooling

What This SDK Does NOT Support

Forms/views (systemform/savedquery) are ordinary records — create/modify them with client.records.* (see dv-metadata), and read N:N with records.list(expand=...). For the genuine gaps below, prefer the managed dataverse api escape hatch over raw urllib:

  • Global option sets — see dv-metadata
  • N:N record association — CLI dataverse data associate, or POST /api/data/v9.2/<entity>(<id>)/<nav-property>/$ref
  • $apply aggregation — use client.query.fetchxml(); see dv-query
  • Unbound actions (e.g., PublishXml, InstallSampleData) — dataverse api request/invoke

Dataverse CLI data examples (copy-paste ready)

All dataverse commands take --context for skill attribution (global flag).

# Create a record (--table is the EntitySet name)
dataverse data create --table accounts --data '{"name":"Contoso"}' --return --json --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Update by GUID
dataverse data update --table accounts --id <guid> --data '{"name":"Contoso (updated)"}' --json --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Upsert by alternate key (idempotent — safe to re-run)
dataverse data upsert --table accounts --key "accountnumber='ACC-001'" --data '{"name":"Contoso Ltd"}' --json --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Delete (--no-confirm skips the prompt)
dataverse data delete --table accounts --id <guid> --no-confirm --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Associate two records (N:N or lookup)
dataverse data associate --table accounts --id <guid> --relationship contact_customer_accounts --related contacts --related-id <contact-guid> --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Disassociate (N:N — pass --related-id; clear a lookup — omit --related-id)
dataverse data disassociate --table accounts --id <guid> --relationship contact_customer_accounts --related-id <contact-guid> --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Upload a file to a file column (--table takes LogicalName, not EntitySet)
dataverse data upload --table account --id <guid> --column new_document --file report.pdf --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Describe entity schema (attributes, relationships, actions)
dataverse data describe --table account --include all --json --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Invoke a discovered custom API by name (use 'api list' to find names)
dataverse api invoke <CustomApiName> --target dataverse --param Input=value --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

# Raw API escape hatch for built-in actions (--target is required)
dataverse api request --target dataverse --path "/api/data/v9.2/WhoAmI" --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"

Setup

import os, sys
sys.path.insert(0, os.path.join(os.getcwd(), "scripts"))
from auth import get_client

# get_client sets a plugin attribution context on the User-Agent header.
# Do not modify the context value — it is a closed schema for server-side
# telemetry (app/skill/agent). Never include secrets or PII.
client = get_client("dv-data")

get_client(skill) handles auth, environment URL, and plugin attribution (User-Agent tagging). See scripts/auth.py.

For scripts that run to completion: wrap in with DataverseClient(...) as client: for automatic connection cleanup (recommended). For notebooks and interactive sessions, the explicit client above is simpler.


Field Name Casing Rule

Getting this wrong causes 400 errors.

Property typeConventionExampleWhen used
Structural (columns)LogicalName — always lowercasenew_name, new_priorityRecord payload keys
Navigation (lookups)Navigation Property Name — case-sensitive, matches $metadatanew_AccountId@odata.bind keys

The SDK lowercases structural keys automatically but preserves @odata.bind key casing.


Create a Record

guid = client.records.create("new_ticket", {
    "new_name": "Ticket 001",
    "new_priority": 100000002,          # choice column — integer value, not string
    "new_AccountId@odata.bind": "/accounts(<account-guid>)",
})
print(f"Created: {guid}")

@odata.bind notes:

  • Key is the Navigation Property Name: new_AccountId@odata.bind (the SDK preserves casing automatically, but matching the schema name is still the correct form)
  • Value is "/<EntitySetName>(<guid>)" — e.g., "/accounts(<guid>)"
  • If you just created the lookup column, wait 5–10 seconds before inserting. Metadata propagation delays cause "Invalid property" errors.
  • Choice columns use integer values, not strings: "new_priority": 100000002 (not "High")

Common @odata.bind patterns

LookupCorrect keyWrong
Custom: new_AccountIdnew_AccountId@odata.bindnew_accountid@odata.bind
System polymorphic: customeridcustomerid_account@odata.bindcustomerid@odata.bind
System: parentcustomeridparentcustomerid_account@odata.bind_parentcustomerid_value@odata.bind

Find the Navigation Property Name

After creating a lookup via SDK: result.lookup_schema_name is the navigation property name.

For existing system tables, query:

GET /api/data/v9.2/EntityDefinitions(LogicalName='<entity>')/ManyToOneRelationships
  ?$select=ReferencingEntityNavigationPropertyName,ReferencedEntity

Update a Record

client.records.update("new_ticket", "<record-guid>",
    {"new_status": 100000001})

Delete a Record

# Single record
client.records.delete("new_ticket", "<record-guid>")

# Bulk delete — pass a list of ids; runs the server-side BulkDelete action (one async job, not N calls)
job_id = client.records.delete("new_ticket", [id1, id2, id3])
# use_bulk_delete=False deletes each id sequentially instead

Bulk Create (SDK uses CreateMultiple internally)

records = [{"new_name": f"Ticket {i}", "new_priority": 100000000} for i in range(500)]
guids = client.records.create("new_ticket", records)
print(f"Created {len(guids)} records")

Volume guidance: CLI dataverse data create for one-off records. MCP create_record batches up to 25 per call. SDK CreateMultiple for larger bulk.

Important: The SDK sends all records in a single POST to CreateMultiple. It does not chunk automatically. Dataverse has no fixed record count limit — the constraints are payload size and request timeout (SDK default: 120s for POST). For larger datasets, you must chunk in your script. The bulk_upsert and bulk_create helpers below use adaptive chunking: start at 1,000, double on success (up to 4,000), halve on payload/timeout failure, and cap at the last successful size. Tables with few columns can handle larger chunks than tables with many columns.


Bulk Update

# Broadcast same change to multiple records
client.records.update("new_ticket",
    [id1, id2, id3],
    {"new_status": 100000001})

DataFrame Write-Back

To create or update records from a pandas DataFrame, use the client.dataframe namespace (create/update). This is documented in dv-query but is a write operation — include it in your data write workflow:

# Update records — DataFrame must include the primary key column
client.dataframe.update("opportunity", df_updates, id_column="opportunityid")

# Create records — returns a Series of new GUIDs
guids = client.dataframe.create("opportunity", df_new_records)

See dv-query for the full client.dataframe write reference; for reads use client.query.builder(...).execute().to_dataframe().


Upsert (Alternate Keys)

Idempotent — re-running the same import does not create duplicates. The alternate key must be defined on the table first — see dv-metadata.

Do NOT include alternate key columns in the record body. The alternate key identifies the record; the record body contains the data to set. If the same column appears in both, UpsertMultiple fails with "An unexpected error occurred" (single upsert tolerates it, bulk does not).

from PowerPlatform.Dataverse.models.upsert import UpsertItem

client.records.upsert("account", [
    UpsertItem(
        alternate_key={"accountnumber": "ACC-001"},
        record={"name": "Contoso Ltd", "description": "Primary account"},
    ),
    UpsertItem(
        alternate_key={"accountnumber": "ACC-002"},
        record={"name": "Fabrikam Inc"},
    ),
])

Bulk Import from CSV

For imports that may be re-run (most real-world cases), use UpsertItem with alternate keys instead of create() — see references/multi-table-fk-import.md. The create() pattern here is for one-shot loads only.

VolumeToolWhy
1 recordCLI dataverse data create or MCP create_recordNo script needed
2–25 recordsMCP create_recordBatches up to 25 per call
25+ recordsSDK client.records.create(table, list)Uses CreateMultiple; chunk large datasets (start at 1K, adapt)
import csv, os, sys
sys.path.insert(0, os.path.join(os.getcwd(), "scripts"))
from auth import get_client

# get_client sets a plugin attribution context on the User-Agent header.
# Do not modify the context value — it is a closed schema for server-side
# telemetry (app/skill/agent). Never include secrets or PII.
client = get_client("dv-data")

with open("data/customers.csv", newline="", encoding="utf-8") as f:
    rows = list(csv.DictReader(f))

records = [{"new_name": row["name"], "new_email": row["email"]} for row in rows]

# SDK sends all in one POST — chunk to avoid payload/timeout limits
# Start at 1000; for narrow tables (few columns) you can go higher
chunk_size = 1000
for i in range(0, len(records), chunk_size):
    guids = client.records.create("new_customer", records[i:i + chunk_size])
    print(f"Imported {i + len(guids)}/{len(records)} customers", flush=True)

Lookup resolution during import

If the CSV has a human-readable key (e.g., customer_email) but Dataverse needs a GUID, pre-resolve with a lookup dict:

# Build email -> GUID map first
email_to_guid = {}
for r in client.records.list("new_customer", select=["new_customerid", "new_email"]):
    email_to_guid[r["new_email"]] = r["new_customerid"]

# Use it during import
records = []
for row in rows:
    customer_guid = email_to_guid.get(row["customer_email"])
    if not customer_guid:
        print(f"Skipping row — unknown email: {row['customer_email']}")
        continue
    records.append({
        "new_channel": row["channel"],
        "new_CustomerId@odata.bind": f"/new_customers({customer_guid})",  # verify entity set name via EntityDefinitions
    })

guids = client.records.create("new_interaction", records)

Required field discovery for system tables

Before bulk-creating in a system table (account, contact, opportunity):

  1. Create a single test record with your intended minimal payload
  2. If HttpError 400 is raised, the error message names the missing required field
  3. Some required fields are plugin-enforced and not visible in describe
  4. Delete the test record, then proceed with bulk create

Multi-Table Import with FK Dependencies

When importing data across multiple tables with foreign key relationships, the import must run in dependency order with UpsertItem + alternate keys (idempotent, safe for re-runs).

Quick reference:

  1. Create tables with source ID columns + alternate keys + lookup relationships (see dv-metadata).
  2. Import Level 0 (no FK deps) tables in parallel via ThreadPoolExecutor. Sequential chunks within each table (concurrent writes deadlock).
  3. Build source-ID → GUID maps by querying back (upsert doesn't return GUIDs).
  4. Repeat per dependency level — Level 1 needs Level 0's maps for @odata.bind.

For the full pattern — adaptive bulk_upsert helper, composite-key handling, post-import verification, and the first-time bulk_create variant — see references/multi-table-fk-import.md.

Key invariants (apply even without reading the reference):

  • Parallelize across tables at the same level, sequential between levels, sequential chunks within a table.
  • Alternate key columns must NOT also appear in the record body — UpsertMultiple fails.
  • Catch per-table failures in the executor — one table failing must not kill the others.
  • Start chunk_size=1000; the helper ramps up adaptively.

Error Handling

from PowerPlatform.Dataverse.core.errors import HttpError

try:
    guid = client.records.create("new_ticket", {"new_name": "Test"})
except HttpError as e:
    print(f"Status {e.status_code}: {e.message}")
    if e.details:
        print(f"Details: {e.details}")
    # 400 — bad field name, @odata.bind format, or missing required field
    # 403 — check security roles
    # 404 — table or record not found
    # 429 — rate limited; SDK retries automatically, reduce batch size if persistent

Writing ERP data

On ERP-linked envs, writes to ERP entities do not go through the Python SDK. See references/erp-writes.md.


Windows Scripting Notes

  • ASCII only in .py files — curly quotes and em dashes cause SyntaxError on Windows.
  • No python -c for multiline code — write a .py file instead.
  • Generate GUIDs in scripts: str(uuid.uuid4()), not shell backtick substitution.

Sample Data Generation

Generate realistic sample records inline — schema-driven, table-agnostic, PII-safe defaults (@example.com emails, 555-01xx phones).

Quick reference: confirm environment + count + table → query EntityDefinitions(LogicalName='<table>')/Attributes?$filter=AttributeOf eq null for required columns → dispatch by AttributeType (String / Memo / Integer / DateTime / Picklist / etc.) → client.records.create() (use CreateMultiple for count >= 10).

For the schema-driven fake() template, the EntityDefinitions query, and the safety rules, see references/sample-data-generation.md.

Key invariants:

  • Skip Lookup, Uniqueidentifier, State, Status, Owner, Customer fields unless the user explicitly provides values.
  • UserLocalizedLabel may be null — dereference safely.

Confirmation-flow examples

Generate N sample records (destructive — preview the snippet, ask for env):

  • ❌ "Which environment should I target? Please provide the Dataverse URL."
  • ✅ "I'll run the Sample Data Generation snippets with TABLE=\"contact\", COUNT=20. Uses CreateMultiple, .example.com emails, 555-01xx phones, against the active pac auth list environment. Confirm to proceed, or specify a different environment."

Sample data on a custom entity (schema unknown — prose is enough):

  • ❌ "I need more info about the entity. What are the required fields?"
  • ✅ "Custom entity — I'll query EntityDefinitions for cr123_project to discover required columns, then generate 5 records inline mapping each column to a generator by AttributeType and call client.records.create(\"cr123_project\", records). Confirm to proceed, or tell me a different count."

Skill: Metadata — Making Changes

Before the first metadata change in a session:

  1. Confirm the target environment with the user — see the Multi-Environment Rule in dv-overview.
  2. Confirm the solution — ask "What solution should these components go into?" If SOLUTION_NAME is in .env, confirm it. If no solution exists yet, you MUST ask the user for the solution name and publisher prefix before creating anything. The publisher prefix is permanent — it cannot be changed after components are created with it.

STOP and ask the user:

"What solution name and publisher prefix should I use? The prefix (e.g., contoso, lit, soc) is permanent on every table and column."

Then query existing publishers and show them — the user may want to reuse one:

# Publisher discovery + solution creation — use SDK (never raw Web API).
# See dv-solution for the full publisher discovery flow.
publishers = client.records.list("publisher",
    filter="customizationprefix ne 'none' and uniquename ne 'MicrosoftCorporation'",
    select=["publisherid", "uniquename", "friendlyname", "customizationprefix"], top=10)
# MANDATORY: Show existing publishers to user and ask which to use or create new

After user confirms, create using SDK:

publisher_id = client.records.create("publisher", {
    "uniquename": "<name>", "friendlyname": "<display>",
    "customizationprefix": "<prefix>",  # from user input, NOT hardcoded
    "description": "<desc>",
})
solution_id = client.records.create("solution", {
    "uniquename": "<SolutionName>", "friendlyname": "<Display Name>",
    "version": "1.0.0.0",
    "publisherid@odata.bind": f"/publishers({publisher_id})",
})

Never create tables or columns outside a solution.

  1. Pass solution="<UniqueName>" in every SDK call, or include "MSCRM.SolutionName": "<UniqueName>" on every raw Web API call.

Skill boundaries

NeedUse instead
Create, update, or delete data recordsdv-data
Query or read recordsdv-query
Export or deploy solutionsdv-solution
ERP schemadv-query; ERP routing

How Changes Are Made: Environment-First

Do not write solution XML by hand to create new tables, columns, forms, or views.

The environment validates metadata far more reliably than an agent editing XML. The correct workflow is:

  1. Make the change in the environment via the Dataverse MetadataService API (or pac commands where available)
  2. Pull the change into the repo via pac solution export + pac solution unpack
  3. Commit the result

The exported XML is generated by Dataverse itself and is always valid. Hand-written XML is fragile — a single incorrect attribute or missing element causes an import failure with an opaque error.

The only time you write files directly is when editing something that already exists in the repo (e.g., tweaking an existing view's columns or modifying a form layout you've already pulled).

CLI schema inspection: dataverse data describe --table account --include all --json (uses LogicalName). API discovery: dataverse api list --target dataverse.


Creating a Table

If creating multiple tables for a data import, also see these sections later in this skill:

  • Idempotent Table Creation — check-first pattern for re-runnable scripts
  • Alternate Keys — required for upsert; create immediately after each table
  • Metadata Propagation Delays and Lock Contention — phased creation to avoid lock errors

Prefer the SDK for table creation — use raw Web API only when you need full control over OwnershipType, HasActivities, or other advanced properties the SDK doesn't expose.

SDK approach (use this by default):

import os, sys
sys.path.insert(0, os.path.join(os.getcwd(), "scripts"))
from auth import get_client

# get_client sets a plugin attribution context on the User-Agent header.
# Do not modify the context value — it is a closed schema for server-side
# telemetry (app/skill/agent). Never include secrets or PII.
client = get_client("dv-metadata")

info = client.tables.create(
    "new_ProjectBudget",
    {"new_Amount": "decimal", "new_Description": "string"},
    solution="MySolution",
    primary_column="new_Name",
    display_name="Project Budget",  # human-readable name; plural auto-appends "s"
)
print(f"Created: {info['table_schema_name']}")

Web API fallback (ONLY when you need OwnershipType, HasActivities, or other properties the SDK doesn't expose):

# Helper for Label boilerplate
def label(text):
    return {"@odata.type": "Microsoft.Dynamics.CRM.Label",
            "LocalizedLabels": [{"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
                                  "Label": text, "LanguageCode": 1033}]}

entity = {
    "@odata.type": "Microsoft.Dynamics.CRM.EntityMetadata",
    "SchemaName": "new_ProjectBudget",
    "DisplayName": label("Project Budget"),
    "DisplayCollectionName": label("Project Budgets"),
    "Description": label(""),
    "OwnershipType": "UserOwned",
    "HasActivities": False, "HasNotes": False, "IsActivity": False,
    "PrimaryNameAttribute": "new_name",
    "Attributes": [{
        "@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",
        "SchemaName": "new_name",
        "DisplayName": label("Name"),
        "RequiredLevel": {"Value": "ApplicationRequired"},
        "MaxLength": 100, "IsPrimaryName": True,
    }]
}
# POST to /api/data/v9.2/EntityDefinitions with MSCRM.SolutionUniqueName header

Column Naming: Avoid *Id Suffix Collisions

Never name a regular column with an Id suffix (e.g., prefix_CountryId). Dataverse auto-generates a navigation property with the Id suffix when you create a lookup — if a regular column with that name exists, lookup creation fails with a schema name collision.

  • WRONG: prefix_DepartmentId (int) — collides with auto-generated lookup
  • RIGHT: prefix_SrcDepartmentId or prefix_DepartmentSourceId

Adding Columns

SDK approach (preferred):

created = client.tables.add_columns(
    "new_ProjectBudget",
    {"new_Description": "string", "new_Amount": "decimal", "new_Active": "bool"},
)
print(created)  # ['new_Description', 'new_Amount', 'new_Active']

Supported type strings: "string" / "text", "int" / "integer", "decimal" / "money", "float" / "double", "datetime" / "date", "bool" / "boolean", "file", and Enum subclasses (for local option sets).

Choice (picklist) column via SDK:

from enum import IntEnum

class BudgetStatus(IntEnum):
    DRAFT = 100000000
    APPROVED = 100000001
    REJECTED = 100000002

created = client.tables.add_columns(
    "new_ProjectBudget",
    {"new_Status": BudgetStatus},
)

Set constraints — pass a dict spec instead of a bare type string (keys: max_length, min_value, max_value, precision, format, required, display_name); works on create and add_columns, no raw Web API:

client.tables.add_columns("new_ProjectBudget", {
    "new_Amount":  {"type": "money", "min_value": 0, "max_value": 1000000000, "precision": 2},
    "new_Comment": {"type": "memo", "max_length": 2000, "display_name": "Comment"},
})

Change an existing column in place with update_column(table, col, spec) or update_columns(table, {col: spec}) — same keys; all specs are validated before any write.


Lookup Columns and Relationships

SDK approach — simple lookup (preferred):

result = client.tables.create_lookup_field(
    referencing_table="new_projectbudget",
    lookup_field_name="new_AccountId",
    referenced_table="account",
    display_name="Account",
    solution="MySolution",
)
print(f"Created lookup: {result.lookup_schema_name}")

SDK approach — full control over 1:N relationship:

from PowerPlatform.Dataverse.models.relationship import (
    LookupAttributeMetadata,
    OneToManyRelationshipMetadata,
    CascadeConfiguration,
)
from PowerPlatform.Dataverse.models.labels import Label, LocalizedLabel
from PowerPlatform.Dataverse.common.constants import CASCADE_BEHAVIOR_REMOVE_LINK

lookup = LookupAttributeMetadata(
    schema_name="new_AccountId",
    display_name=Label(localized_labels=[LocalizedLabel(label="Account", language_code=1033)]),
)

relationship = OneToManyRelationshipMetadata(
    schema_name="account_new_projectbudget",
    referenced_entity="account",
    referencing_entity="new_projectbudget",
    referenced_attribute="accountid",
    cascade_configuration=CascadeConfiguration(delete=CASCADE_BEHAVIOR_REMOVE_LINK),
)

result = client.tables.create_one_to_many_relationship(lookup, relationship, solution="MySolution")
print(f"Created: {result.relationship_schema_name}")

SDK approach — many-to-many relationship:

from PowerPlatform.Dataverse.models.relationship import ManyToManyRelationshipMetadata

relationship = ManyToManyRelationshipMetadata(
    schema_name="new_ticket_knowledgebase",
    entity1_logical_name="new_ticket",
    entity2_logical_name="new_knowledgebase",
)

result = client.tables.create_many_to_many_relationship(relationship, solution="MySolution")
print(f"Created: {result.relationship_schema_name}")

Web API approach (fallback when SDK patterns don't suffice):

relationship = {
    "@odata.type": "Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata",
    "SchemaName": "account_new_projectbudget",
    "ReferencedEntity": "account",
    "ReferencingEntity": "new_projectbudget",
    "Lookup": {
        "@odata.type": "Microsoft.Dynamics.CRM.LookupAttributeMetadata",
        "SchemaName": "new_AccountId",
        "DisplayName": {"@odata.type": "Microsoft.Dynamics.CRM.Label",
                        "LocalizedLabels": [{"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
                                              "Label": "Account", "LanguageCode": 1033}]},
        "RequiredLevel": {"Value": "None"}
    }
}
# POST to /api/data/v9.2/RelationshipDefinitions

After creating a lookup — the @odata.bind navigation property:

When you create records that set this lookup, you need the navigation property name for @odata.bind. The navigation property name is case-sensitive and must match the entity's $metadata (usually the SchemaName of the lookup field, e.g., new_AccountId):

Navigation Property Name@odata.bind keyEntity set
new_AccountIdnew_AccountId@odata.bind/accounts(<guid>)
new_ParentTicketIdnew_ParentTicketId@odata.bind/new_tickets(<guid>)

Common mistake: Using the logical name (lowercase) like new_accountid@odata.bind returns a 400 error. Navigation property names are case-sensitive and must match the entity's $metadata.


Adding a Table to a Solution

After creating a table via API, add it to your solution so it gets pulled on export:

pac solution add-solution-component \
  --solutionUniqueName <SOLUTION_NAME> \
  --component <SchemaName> \
  --componentType 1 \
  --environment <url>

Component type 1 = Entity (Table). See dv-solution for the full type code list.

Or via Web API:

# POST to /api/data/v9.2/AddSolutionComponent
body = {
    "ComponentId": "<entity-metadata-id>",
    "ComponentType": 1,       # 1 = Entity
    "SolutionUniqueName": "<SOLUTION_NAME>",
    "AddRequiredComponents": True
}

Forms and Views

systemform (forms) and savedquery (views) are ordinary entities — create/read/modify them with the SDK's record CRUD (no urllib). Only publishing (PublishXml, an unbound action) needs dataverse api request.

Quick reference:

  • Create form: client.records.create("systemform", {...formxml..., "type": 2}) (2=Main, 7=Quick Create, 6=Quick View, 11=Card).
  • Modify form: records.list("systemform", filter=...) for a template → mutate formxml → records.update("systemform", id, {...}) → publish.
  • Publish: dataverse api request POST PublishXml — required for changes to take effect.
  • Create view: client.records.create("savedquery", {...fetchxml..., ...layoutxml...}) (0=standard, 1=advanced find, 2=associated, 4=quick find).

Full code, the template recipe, the classid table, and publish: references/forms-and-views.md.

Key invariants:

  • All id attributes in form XML must be unique GUIDs (str(uuid.uuid4()).upper()).
  • Do not use python -c for GUID generation on Windows — write a .py file.
  • Forms must be published after every create or modify, otherwise changes are invisible to users.

Business Rules

Create business rules in the Power Apps maker portal. They are too complex to write reliably as JSON/XAML. After creation, export+unpack the solution and commit the result.


Publisher Prefix

All custom schema names must use your solution's publisher prefix (e.g., new_, contoso_). Find yours:

pac solution list --environment <url>

Or check solutions/<SOLUTION_NAME>/Other/Solution.xml after the first pull — look for <CustomizationPrefix>.


FormXml Pitfalls

  • All id attributes must be valid GUIDs in {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} format. Do not use strings like "general".
  • labelid is also a GUID — not a human-readable string.
  • Subgrid controls require a valid <ViewId> — must be the GUID of an existing SavedQuery. Create the view first.
  • Cell, section, tab, and control IDs must all be unique across the entire form.
  • Control classid values — see the classid table above.

Tip: Create forms in the maker portal and pull via pac solution export — use the pulled XML as a template for programmatic creation.


After Creating Columns: Report Logical Names

After creating columns (via Web API or MCP), always report the actual logical names to the user. Column names may be normalized or prefixed in ways the user doesn't expect. Summarize in a table:

Display NameLogical NameType
Emailcr9ac_emailString
Tiercr9ac_tierPicklist
Customercr9ac_customeridLookup

This prevents downstream failures when the user tries to insert data using incorrect column names.


Common Web API Error Codes

Error CodeMeaningRecovery
0x80040216Transient metadata cache error. Column or table metadata not yet propagated.Wait 3-5 seconds and retry. Usually succeeds on second attempt.
0x80048d19Invalid property in payload. A field name doesn't match any column on the table.Check logical column names — use EntityDefinitions(LogicalName='...')/Attributes to verify.
0x80040237Schema name already exists.Verify the column/table exists before creating a new one — it may have been created by a previous timed-out call.
0x8004431aPublisher prefix mismatch.Ensure all schema names use the solution's publisher prefix.
0x80060891Metadata cache not ready after table creation.Call GET EntityDefinitions(LogicalName='...') first to force cache refresh, then retry.

Always translate error codes to plain English before presenting them to the user.


Metadata Propagation Delays and Lock Contention

After creating tables / columns / alternate keys, Dataverse runs internal metadata operations (index build, cache propagation) for 3–30 seconds. Submitting another metadata operation while these run causes lock-contention errors.

Mitigation — phased creation, not interleaved. Create ALL tables → wait 15–30s → create ALL alternate keys → wait 15–30s → create ALL lookups. Do NOT interleave operations on the same table.

Symptoms (any of these means propagation isn't done):

  • Picklist column creation fails with 0x80040216
  • Lookup @odata.bind fails with "Invalid property"
  • update_table (MCP) fails with "EntityId not found in MetadataCache"
  • Lookup or alternate-key creation fails with "another customization operation is running"

For the retry_metadata helper that catches transient lock errors and the full phased-creation sequence, see references/metadata-propagation.md.

Inspect Existing Schema

Before changing a model, inspect what exists. These read-only calls return raw metadata dicts (PascalCase names) and are safe to run anytime.

Assumes client from the auth setup shown earlier in this skill (from auth import get_client).

# typed=True returns type-specific fields (MaxLength, MinValue/MaxValue) in one request -- no @odata.type cast, no urllib
for col in client.tables.list_columns("account", typed=True):
    print(col["LogicalName"], col.get("MaxLength"))
# get_column(table, col, typed=True) reads one column's constraints

# All relationships for one table (1:N, N:1, and N:N combined)
rels = client.tables.list_table_relationships("account")
for rel in rels:
    print(f"{rel['SchemaName']} -> {rel.get('@odata.type')}")

# All relationships in the environment (optionally filtered)
all_rels = client.tables.list_relationships(select=["SchemaName", "ReferencedEntity", "ReferencingEntity"])

For SQL-queryable column discovery (virtual/computed columns excluded), dv-query also has client.query.sql_columns(table).

Session Closing: Pull to Repo

After every metadata session, perform the pull-to-repo sequence — see dv-overview "After Any Change: Pull to Repo" for the full export/unpack/commit commands.

If you used the MSCRM.SolutionName header during creation, verify components were added before exporting:

sol = client.records.list("solution",
    filter="uniquename eq '<SOLUTION_NAME>'", select=["solutionid"], top=1).first()
if sol is not None:
    components = client.records.list("solutioncomponent",
        filter=f"_solutionid_value eq {sol['solutionid']}",
        select=["componenttype", "objectid"])
    print(f"{len(components)} components in the solution")

Idempotent Table Creation

When creating tables programmatically (e.g., a schema setup script that may be re-run), use a check-first pattern — query client.tables.get() before creating. This is explicit, avoids masking unrelated errors, and lets you branch logic based on whether the table was created or reused:

def ensure_table(client, schema_name, columns, solution, primary_column="prefix_Name", display_name=None):
    existing = client.tables.get(schema_name)
    if existing:
        print(f"Reusing: {schema_name}")
        return existing
    info = client.tables.create(schema_name, columns, solution=solution,
                                primary_column=primary_column, display_name=display_name)
    print(f"Created: {info['table_schema_name']}")
    return info

Alternate Keys (Required for Upsert)

UpsertMultiple requires an alternate key on the column(s) Dataverse should use to identify existing records. Always create alternate keys on source-system ID columns (prefix_Src*Id) at schema-setup time so every import is idempotent.

Quick reference:

  • SDK call: client.tables.create_alternate_key(table, key_name, [columns], display_name=...). Composite keys: pass multiple columns.
  • Use a check-first pattern with client.tables.get_alternate_keys(table) to skip keys that already exist — see references/alternate-keys.md for the ensure_alternate_key helper.
  • Index creation is async — for large tables, poll client.tables.get_alternate_keys(table) until status == "Active" before using.
  • Constraints: max 16 columns / 900 bytes / 10 keys per table; valid types are Integer / Decimal / String / DateTime / Lookup / OptionSet.

For SDK code samples (single + composite + idempotent + status-check), the agent decision rules for which column to pick (DB source vs Excel/CSV), and the failure-handling notes, see references/alternate-keys.md.

EntityDefinitions Filter Limitation

startswith() is NOT supported as a filter on EntityDefinitions. This query will return a 400 error:

GET /api/data/v9.2/EntityDefinitions?$filter=startswith(LogicalName,'new_')  # BROKEN

To retrieve metadata for multiple custom tables, query each table individually:

GET /api/data/v9.2/EntityDefinitions(LogicalName='new_projectbudget')?$select=LogicalName,EntitySetName

Or query all and filter client-side:

GET /api/data/v9.2/EntityDefinitions?$select=LogicalName,EntitySetName

MCP Table Creation Notes

When using MCP create_table or update_table:

  • Column types. MCP handles most types (text, numeric, boolean, datetime, choice/multiselect, lookup/customer, file/image); global option sets, N:N, alternate keys, forms, views need SDK/Web API.
  • Timeouts / cache delays. Creation may report a timeout or stale cache; always describe('tables/{name}') before retrying or a follow-up update_table (if the table exists, skip creation).
  • Self-referential lookups (Parent → same table) are added via update_table after creation.

Skill: Overview — What to Use and When

Load this skill first for Dataverse work: scope, tool capabilities, hard rules, and the change lifecycle. It does not route; the agent auto-selects and chains specialist skills using their WHEN/DO NOT USE WHEN frontmatter triggers. Users describe tasks in plain English; never ask them to name a skill or command.


What This Plugin Covers

Dataverse / Power Platform work for every persona — builders and agent devs, data scientists, environment admins, and business users — delivered by specialist skills. The agent loads and routes to these automatically via their frontmatter triggers — you never invoke them by name.

AreaSkill
Connect, authenticate, configure MCP, verify the environmentdv-connect
Schema — tables, columns, relationships, forms, views; inspect existing schemadv-metadata
Data writes — record CRUD, bulk create/update/upsert, CSV/FK-ordered import, sample datadv-data
Data reads & analytics — OData queries, QueryBuilder, FetchXML (aggregation + N:N joins), DataFramesdv-query
Solution ALM — create, export, import, pack/unpack, post-import validationdv-solution
Finance and Operations X++ — author, build, deploy, DB sync, verifyerp-xpp
Finance and Operations UDE developer-database access (JIT SQL)erp-sql
Environment administration — bulk delete, retention/archival, org & OrgDB settings, recycle bindv-admin
Security & access — roles, users, application users, business units, self-elevation (PAC CLI)dv-security

Model-driven apps: the building blocks (tables, forms, views) are covered by dv-metadata; composing the app shell itself — site map and navigation — is not yet a first-class skill.

Out of scope:

  • Canvas apps — a different technology; use pac canvas or the maker portal
  • Power Automate flows — use the maker portal or the Power Automate Management API
  • Azure infrastructure beyond what's needed for service-principal setup
  • Business Central or other Dynamics products

Hard Rules

Safety rules (init, auth, env confirmation) are non-negotiable. Tool selection (Rules 1, 2, 4) is capability-based.

0. Check Init State First

Before writing ANY code or creating ANY files, actively search your callable tools for any tool whose name or description contains dataverse (tools may be registered under environment-specific names like mcp__dataverse_<orgid>__read_query, not just generic names). If any Dataverse MCP tool is found, use it directly — skip the init check and all setup. MCP auth is host-managed and does not need .env or scripts/auth.py. Never declare MCP unavailable based solely on the initially displayed tool list.

If no MCP tool is found, check for an existing CLI profile — it's the fastest path for data operations:

dataverse auth who

If that shows an active profile with an environment URL, use CLI directly for data operations (see dv-query/dv-data examples) — no .env, auth.py, or workspace setup needed. For explicit "connect" or "set up" requests, run dv-connect regardless — it configures MCP, SDK, and PAC.

If no CLI profile exists, check workspace init:

ls .env scripts/auth.py 2>/dev/null
  • If BOTH exist: proceed to the task.
  • If EITHER is missing: run python <plugin-scripts>/auth.py --ping. If it prints REACHABLE (exit 0), the workspace is bootable without pip -- confirm the URL and proceed. If --ping fails, run dv-connect.

1. Python for scripting; the CLIs and MCP are first-class

Python is the language for automation logic (transformation, control flow, retry, CSV). The toolchain (scripts/auth.py, the SDK, skill examples) is Python-based. But MCP tools, the Dataverse CLI (dataverse), the Python SDK, and the PAC CLI (pac) are all first-class tool invocations — use whichever fits. The Dataverse CLI has the same standing as pac, which is invoked freely across the solution and metadata skills.

NEVER:

  • Write automation logic in JavaScript/TypeScript/Node.js (npm, yarn, pnpm, package.json, node_modules/)
  • Use @azure/msal-node, @azure/identity, or any Node.js Azure SDK
  • Implement a bespoke MSAL / device-code flow — auth is scripts/auth.py, pac auth, and the Dataverse CLI

ALWAYS:

  • Use pip install and the Python SDK (PowerPlatform-Dataverse-Client) for data and schema logic
  • Use scripts/auth.py for tokens/credentials; azure-identity (Python) for Azure credential flows
  • Treat the Dataverse CLI (dataverse) and pac as allowed first-party CLIs

2. Pick the surface that fits — capability awareness, not a fixed order

No mandated tool order. Each surface has a capability profile; pick what fits the job and the surface you are already in — soft defaults, not a required sequence. The full matrix is in Tool Capabilities below; the principles:

  • Prefer a managed surface (MCP, the Dataverse CLI, or the SDK) over hand-rolled raw OData — they carry auth, paging, retry, and geo routing that raw HTTP re-implements. When MCP can't handle it (bulk >25 records, large reads, advanced schema like forms/views/N:N relationships/global option sets/alternate keys, multi-step workflows, analytics, or MCP isn't available), the Python SDK is the default.
  • Raw Web API is the last-resort escape hatch for surfaces with no managed path (unbound actions like PublishXml, global option sets, anything without a first-class SDK/CLI command) — and even then prefer dataverse api (managed auth, exit codes) over hand-rolled urllib/get_token. Forms/views are not raw-only (SDK records.create/update on systemform/savedquery; only PublishXml needs dataverse api). Aggregation/N:N joins aren't raw-only either: client.query.fetchxml() (aggregates + link-entity), or the CLI's data associate for N:N writes.
  • If an SDK method fails or a PAC command seems missing, check the relevant skill before hand-rolling raw HTTP.

Field casing: $select/$filter use lowercase logical names (new_name). $expand and @odata.bind use Navigation Property Names that are case-sensitive and must match $metadata (e.g., new_AccountId). Getting this wrong causes 400 errors. SDK record payloads: provide the correct SchemaName casing on @odata.bind keys (e.g., new_AccountId@odata.bind); the SDK does not auto-correct wrong casing. Raw Web API calls (forms, views, metadata): casing is entirely manual — a lowercase new_accountid@odata.bind will 400.

Publisher prefix: Never hardcode a prefix (especially new); query existing publishers and ask the user. The prefix is permanent. See the solution skill's publisher discovery flow.

3. Use Documented Auth Patterns

Three entry points, one shared sign-in:

  • dataverse auth create (Dataverse CLI) writes a shared MSAL token cache. That sign-in serves CLI, MCP proxy, and scripts/auth.py via msal-extensions.
  • scripts/auth.py — Python/SDK auth (service principal → shared CLI cache → device-code). Prefer get_client(skill) (SDK); get_plugin_headers(skill, get_token()) is the fallback for SDK gaps — both stamp attribution.
  • pac auth create (PAC CLI) authenticates pac for dv-solution, dv-admin, and erp-xpp.

Telemetry attribution (keep it deterministic): every request carries a closed-schema app=dataverse-skills/<ver>;skill=<skill>;agent=<agent> context so the server sees which skill routed each OData call. It is baked in — get_client(skill) and get_plugin_headers(skill, ...) stamp it on the SDK and raw-HTTP paths; the Dataverse CLI auto-stamps DataverseCli/<ver> + the command, and you add the skill with --context "app=dataverse-skills/<ver>;skill=<skill>;agent=<agent>" (the CLI wraps it in parentheses itself — do not pre-wrap). Never modify, omit, or free-form this context — it is a closed schema (allowlisted skill/agent, no PII).

NEVER:

  • Read or parse raw token cache files (e.g., tokencache_msalv3.dat) — reuse the cache only through scripts/auth.py / msal-extensions
  • Implement your own MSAL device-code flow
  • Hard-code tokens or credentials in scripts
  • Invent a new auth mechanism

If auth is expired or missing, re-run dataverse auth create (or pac auth create), or check .env. See the dv-connect skill.

4. Be honest about gaps — don't hallucinate

Each skill documents a tested sequence — follow it when it fits. The skills are the source of truth for the supported, non-deprecated API. If a call fails with AttributeError, the installed SDK version may not have it — check the skill's version note and use the documented alternative.

The honesty guard: if you hit a gap the skills don't cover, say so and suggest a workaround. Do not hallucinate an unsupported path — do not invent a method, parameter, or endpoint that isn't documented. If unsure, say so.

Connectivity is not auth. A login.microsoftonline.com token can succeed while the org's data-plane domain is unreachable (restricted-egress hosts like ChatGPT Work Mode). Never report a count or result you didn't get from a real call that returned — verify with python scripts/auth.py --check; if it fails, say "unreachable," never a fabricated number. On a constrained host, lead with the SDK, not CLI/MCP. See dv-connect/references/headless-hosts.md.


Tool Capabilities — Which Tool for Which Job

Understanding the real limits of each tool prevents hallucinated paths. This is the one piece of context no individual skill owns.

ToolUse forDoes NOT support
MCP ServerData CRUD (create/read/update/delete records, batch up to 25 per call), table create/update/delete + column add (incl. local choice/multiselect + lookup/customer), schema + record inspection via describe, metadata search (search), data + file-content search (search_data, when Dataverse search is enabled), file upload/downloadForms, Views, global Option Sets, N:N relationships, alternate keys, Solutions (lookup + local choice/multiselect columns are supported via create_table/update_table). Note: table creation may timeout but still succeed — always describe (e.g. describe('tables/{name}')) before retrying. Run queries sequentially (parallel calls timeout). Column names with spaces normalize to underscores (e.g., "Specialty Area" → cr9ac_specialty_area). SQL (read_query): supports JOIN, GROUP BY (COUNT/SUM/AVG/MIN/MAX), TOP, WHERE, ORDER BY; does NOT support DISTINCT, HAVING, subqueries, OFFSET, UNION, CASE/IF, CAST/CONVERT, CTE, or date functions. For those, use client.query.sql() (also allows DISTINCT, <5K rows), $apply, or a builder->DataFrame with pandas — see dv-query. Bulk: MCP create_record/update_record/delete_record batch up to 25 records per call; for larger bulk use the SDK CreateMultiple — see dv-data.
Python SDK (dv-data)Scripted data writes, especially at volume. Record CRUD, upsert (alternate keys), bulk create/update/upsert (CreateMultiple/UpdateMultiple/UpsertMultiple), CSV import with lookup resolution, file column uploads (chunked >128MB)global Option Sets, record association ($ref), $apply aggregation, table/column/relationship creation (use dv-metadata), custom action invocation
Python SDK (dv-query)Bulk reads and analytics. Multi-page record iteration, OData queries (select/filter/expand/orderby), QueryBuilder fluent API, GUID-free display (formatted values), $expand to resolve lookups, aggregation and N:N joins via client.query.fetchxml() (aggregate FetchXML + link-entity), pandas DataFrame handoff (client.query.builder(...).execute().to_dataframe()) for exports, Jupyter notebook snippetsOData $apply and N:N $expand on the QueryBuilder path — use records.list(expand=...) for N:N, or fetchxml() for aggregates (not raw urllib)
Dataverse CLI (dataverse)Headless data plane: data CRUD, associate/disassociate (N:N + $ref), data upload; api request/invoke (Web API escape hatch); api list/describe (Custom API discovery)Metadata/schema (use SDK — dv-metadata), solution ALM (use PAC), forms/views; blocked on ChatGPT web / Codex cloud (no .NET runtime) — use the SDK
PAC CLISolution export/import/pack/unpack, ERP X++ SDK install + package scaffold/compile/deploy/DB sync, environment create/list/delete/reset, auth profile management, plugin updates (pac plugin push — first-time registration requires Web API), user/role assignment (pac admin assign-user), add solution components (pac solution add-solution-component)Data CRUD, Dataverse metadata creation (tables/columns/forms), listing solution components (no list-components — query solutioncomponent via SDK/CLI); X++ SDK install/compile require Windows
Azure CLIApp registrations, service principals, credential managementDataverse-specific operations
GitHub CLIRepo management, GitHub secrets, Actions workflow statusDataverse-specific operations
Raw Web API (last resort)Only when no managed surface exposes the operation — i.e. not doable via MCP, the Python SDK, the Dataverse CLI, or the dataverse api escape hatch. Genuine cases: unbound actions like PublishXml, global option sets, and similar edge cases (not forms/views — those are SDK record CRUD on systemform/savedquery). Even then, prefer dataverse api (managed auth + skill attribution) over hand-rolled urllib.Functionally nothing (full OData/MetadataService) — but raw urllib bypasses managed auth, paging, retry, and skill attribution, so treat it as the path of last resort

Routing: the table shows what each surface does; the how to choose principle (soft defaults, not a fixed order) is Hard Rule 2. MCP tools not in your list? Load dv-connect.

Volume guidance: CLI dataverse data create/query/count for one-off commands; MCP for up to ~25 records per call or simple filters; the SDK's CreateMultiple for larger bulk writes (chunk large sets starting ~1,000 — see dv-data) and dv-query for bulk reads; SDK fetchxml() for aggregation.

SDK method cheat-sheet (anti-hallucination, not a preference signal): SDK method names are the least discoverable surface, so agents invent them. This maps common ops to the exact call. Each op is equally reachable via MCP/CLI per Hard Rule 2; see the noted skill for the full pattern.

OperationSDK callSkill
Create / update / delete recordsclient.records.create() / .update() / .delete() (pass a list for bulk)dv-data
Upsert on an alternate keyclient.records.upsert()dv-data
Query / filter recordsclient.records.list(...) (flat) or .list_pages(...) (streaming)dv-query
One record by GUIDclient.records.retrieve(table, guid) (None if missing)dv-query
Aggregation / server-side joinsclient.query.fetchxml(xml) (aggregates + link-entity)dv-query
Fluent query build (chainable)client.query.builder(Table).where(...).execute()dv-query
Limited SQL readclient.query.sql("SELECT ...")dv-query
Load into pandasclient.query.builder(table).select(...).execute().to_dataframe()dv-query
Upload to a file columnclient.files.upload(...)dv-data
Create tables / columns / lookups / N:Nclient.tables.create() / .add_columns() / .create_lookup_field() / .create_many_to_many_relationship()dv-metadata
Create an alternate key (enables upsert)client.tables.create_alternate_key(...)dv-metadata
Inspect existing schemaclient.tables.list_columns(table) / .list_table_relationships(table)dv-metadata
Create publisher / solutionclient.records.create("publisher" / "solution", {...})dv-solution

MCP Availability Check

If the user's request involves MCP — explicitly or implicitly — search your callable tools for any tool whose name or description contains dataverse (same search as Hard Rule 0).

If MCP NOT available and user explicitly asked for MCP ("use MCP to query"):

  1. Do NOT silently fall back to the Python SDK or Web API
  2. Tell the user: "Dataverse MCP tools aren't configured in this session yet."
  3. Load dv-connect to set up the MCP server
  4. After MCP is configured, stop — the session must restart for MCP tools to appear. Do not proceed with SDK.

If MCP NOT available and user asked a data question ("how many accounts?"):

  1. Use the CLI (if profile exists) or SDK to answer. Do not block the user.
  2. After answering, offer: "MCP would handle this conversationally — want me to set it up?"

The distinction matters: explicit MCP request → block and set up MCP; implicit question → answer with SDK, offer MCP setup.

If MCP tools ARE available, prefer MCP for simple reads/queries/small CRUD. Use the SDK only when a script is needed.


The Change Lifecycle — Operate Safely

For any real change, walk these three steps in order: confirm where, confirm the container, then persist the result.

Step 1 — Confirm the Environment (MANDATORY)

Dataverse work often spans multiple environments (dev, test, staging, prod) and multiple sets of credentials. Never assume the active PAC auth profile, values in .env, or anything from memory or a previous session reflects the correct target for the current task.

Before the FIRST operation that touches a specific environment — creating a table, deploying a plugin, pushing a solution, inserting data — you MUST:

  1. Show the user the environment URL you intend to use
  2. Ask them to confirm it is correct
  3. Run pac org who to verify the active connection matches

"I'm about to make changes to <URL>. Is this the correct target environment?"

Do not proceed until the user explicitly confirms. This is the single most important safety check in the plugin. Skipping it risks making irreversible changes to the wrong environment. Once confirmed for a session, you do not need to re-confirm for every subsequent operation in the same session against the same environment.

Step 2 — Confirm the Solution (before any metadata change)

Before creating tables, columns, or other metadata, ensure a solution exists to contain the work:

  1. Ask the user: "What solution should these components go into?"
  2. If a solution name is in .env (SOLUTION_NAME), confirm it with the user
  3. If no solution exists yet, load the dv-solution skill and follow its publisher discovery + solution creation flow. Use the SDK — never raw Web API — to create publisher and solution records:
# Quick reference — full pattern with publisher discovery is in dv-solution
publisher_id = client.records.create("publisher", {
    "uniquename": "<name>", "friendlyname": "<display>",
    "customizationprefix": "<prefix>", "description": "<desc>",
})
solution_id = client.records.create("solution", {
    "uniquename": "<Name>", "friendlyname": "<Display>",
    "version": "1.0.0.0",
    "publisherid@odata.bind": f"/publishers({publisher_id})",
})
  1. Pass solution="<UniqueName>" on all SDK calls, or include "MSCRM.SolutionName": "<UniqueName>" header on raw Web API metadata calls.

Creating metadata without a solution means it exists only in the default solution and cannot be cleanly exported or deployed. Always solution-first.

Step 3 — Pull to Repo (MANDATORY)

Any time you make a metadata change (via MCP, Web API, or the maker portal), you must end the session by pulling:

pac solution export --name <SOLUTION_NAME> --path ./solutions/<SOLUTION_NAME>.zip --managed false
pac solution unpack --zipfile ./solutions/<SOLUTION_NAME>.zip --folder ./solutions/<SOLUTION_NAME>
rm ./solutions/<SOLUTION_NAME>.zip
git add ./solutions/<SOLUTION_NAME>
git commit -m "feat: <description>"
git push

The repo is always the source of truth.


Scripts

The plugin ships scripts/auth.py (Azure Identity token/credential acquisition — used by all other scripts and the SDK). Any Web API call beyond a one-off query should be a Python script committed to /scripts/, using scripts/auth.py for tokens. For writes see dv-data; queries and analytics see dv-query; post-import validation see dv-solution.


Windows Scripting

Platform-specific shell rules (ASCII in .py, no multiline python -c, PAC PowerShell wrapper, unbuffered background output) live in references/windows-scripting.md. Read it when running on Windows.

Skill: Query — Read and Analyze Dataverse Records

This skill uses Python and the Dataverse CLI. Do not use Node.js, JavaScript, or any other language for Dataverse scripting. See the overview skill's Hard Rules.

Reads: prefer a managed surface, choose by shape

Fast path for simple reads: If dataverse auth who shows an active profile, skip workspace setup and query directly with the CLI examples below. No .env, auth.py, pip install, or PAC needed for data reads.

Pick MCP, the Dataverse CLI, or the SDK by the shape of the read — all three handle auth and retry (see the routing table below and the overview's Tool Capabilities / Hard Rule 2). MCP fits small, interactive reads; the CLI fits headless one-liners (OData, SQL, count); the SDK fits bulk iteration and analytics. For $apply aggregation and N:N $expand, prefer client.query.fetchxml() (aggregates + link-entity) or the managed dataverse api escape hatch; reach for hand-rolled urllib/get_token() only to stay in-process inside a tight Python loop (e.g. paging thousands of rows with client-side processing — see web-api-advanced.md).

Dataverse CLI gotchas (custom tables + Windows)

When you drive the dataverse CLI directly (headless reads/CRUD; note the CLI needs .NET + a keyring, so it is blocked on ChatGPT web / Codex cloud — use the SDK there), two empirical traps:

  • Custom-table SQL pluralization. dataverse data query in SQL mode auto-pluralizes the table name, and irregular plurals resolve wrong: FROM im_category looks up entity set im_categorys and returns a 404 that reads like "table missing." It is not — switch to OData mode with the explicit entity set: dataverse data query --table im_categories --select im_name. Discover the real EntitySetName from EntityDefinitions when unsure; never conclude the table doesn't exist from this 404.
  • Windows shell quoting. Wrap the whole --path value in double quotes so cmd.exe/PowerShell don't treat & as a command separator. Keep & literal — it separates OData query options; encoding it to %26 merges them and breaks the query. Encode only $->%24 (in PowerShell a bare $select is read as a variable). If an unquoted & splits the command, the wrapper can exit nonzero even when the API returned valid JSON — quoting prevents it. (This is why the dataverse api request examples in other skills quote the path, use %24, and leave & literal.)

Dataverse CLI query examples (copy-paste ready)

All dataverse commands take --context for skill attribution (global flag).

# OData filtered read (--table takes the EntitySet name, e.g. accounts not account)
dataverse data query --table accounts --select "name,accountid" --filter "name eq 'john'" --top 10 --json --context "app=dataverse-skills/<ver>;skill=dv-query;agent=<agent>"

# Count records
dataverse data count --table accounts --context "app=dataverse-skills/<ver>;skill=dv-query;agent=<agent>"

# SQL mode (uses the logical name, e.g. account not accounts)
dataverse data query --sql "SELECT name, accountid FROM account WHERE name LIKE '%john%'" --json --context "app=dataverse-skills/<ver>;skill=dv-query;agent=<agent>"

# Get single record by ID
dataverse data get --table accounts --id <guid> --json --context "app=dataverse-skills/<ver>;skill=dv-query;agent=<agent>"

# Raw API escape hatch
dataverse api request --target dataverse --path "/api/data/v9.2/accounts?%24select=name&%24top=5" --context "app=dataverse-skills/<ver>;skill=dv-query;agent=<agent>"

ERP target is a separate path. ERP (Finance and Operations), when linked to a Dataverse env, does not go through the Python SDK. See references/erp-reads.md.

How to Answer Data Questions

When the user asks a question about their data, pick the approach by what they're asking, not by which API you know:

User asks...ApproachWhy
"show me open tickets" / simple filterMCP read_query, CLI dataverse data query --table ... --filter ..., or client.records.list(table, filter=...)Small result, no aggregation
"how many X" / simple countCLI dataverse data count --table ..., MCP read_query, or client.query.sql("SELECT COUNT(*) ...")Server-side count (no row download)
Single-table aggregation (most/sum/avg/top-N)$apply (raw) or client.query.sql() GROUP BYBoth run server-side, return only grouped results
Cross-table aggregationclient.query.sql("...INNER JOIN...GROUP BY...") or client.query.fetchxml(...) (server-side); else builder->DataFrame + pd.merge()sql() supports INNER/LEFT JOIN + GROUP BY; pandas merge for shapes SQL can't express
"show me X with related Y" / resolve lookupsclient.records.list(table, expand=...) or QueryBuilderLookup resolution
"export this data" / bulk extractclient.query.builder(t).select(...).execute().to_dataframe()Direct to DataFrame → CSV
"load into notebook" / interactive analysisclient.query.builder(t).select(...).execute().to_dataframe()pandas native
"find duplicates" / complex filterclient.records.list(table, filter=...) or QueryBuilderSDK handles pagination
Simple filtered read (<5K rows)CLI dataverse data query --sql "SELECT ...", or client.query.sql()Lightweight single call

Key principle: Let the server do the work. For single-table aggregation, use $apply (raw) or client.query.sql() GROUP BY — both run server-side and return only grouped results. For cross-table questions, prefer a server-side sql() JOIN (INNER/LEFT) or fetchxml() link-entity; when SQL can't express it, pull each table via client.query.builder(t).select(...).execute().to_dataframe() and pd.merge() — the merge is sub-second; the bottleneck is network transfer, which select minimizes.

Always query the live Dataverse environment. Do not query local copies, cached files, or source databases when the user expects results from Dataverse. The data in Dataverse is the source of truth.


SQL Queries — client.query.sql()

client.query.sql() uses the Dataverse Web API ?sql= parameter — a T-SQL subset. It supports SELECT / SELECT DISTINCT / SELECT TOP N (0-5000), INNER JOIN / LEFT JOIN, WHERE, GROUP BY, ORDER BY, OFFSET/FETCH, and COUNT/SUM/AVG/MIN/MAX. It does NOT support SELECT *, subqueries, CTEs, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, or string/date/math functions. Results are capped at ~5,000 rows.

When to use: Fast filtered reads on tables with <5K rows. For these, it's significantly faster (~2-6s) than page iteration or DataFrames because it's a single HTTP call.

# Fast filtered read on small tables (<5K rows)
results = client.query.sql(
    "SELECT TOP 100 name, estimatedvalue "
    "FROM opportunity "
    "WHERE statecode = 0 "
    "ORDER BY estimatedvalue DESC"
)
for r in results:
    print(f"{r['name']}: ${r.get('estimatedvalue', 0):,.0f}")

Do NOT use for: Tables >5K rows (results silently truncated), SELECT *, subqueries/CTEs, HAVING, UNION, RIGHT/FULL/CROSS JOIN, or functions. INNER/LEFT JOIN and GROUP BY are supported — use them for server-side joins/aggregation on <5K-row results; for larger or unsupported shapes use fetchxml() or $apply.

FetchXML — server-side joins and aggregates

For SQL-JOIN scenarios or aggregates the OData builder cannot express, use FetchXML. client.query.fetchxml(xml) returns an inert query object — no HTTP is made until you call .execute() (eager, all pages) or .execute_pages() (lazy, one page at a time). Both return QueryResult pages with .to_dataframe().

query = client.query.fetchxml("""
  <fetch top="50">
    <entity name="account">
      <attribute name="name" />
      <link-entity name="contact" from="parentcustomerid" to="accountid" alias="c" link-type="inner">
        <attribute name="fullname" />
      </link-entity>
    </entity>
  </fetch>
""")

result = query.execute()          # collect all pages
df = result.to_dataframe()

# Or stream one page at a time for large results:
for page in query.execute_pages():
    print(page.to_dataframe().shape)

Discover queryable columns — client.query.sql_columns()

Before writing a SQL or $select read, list the columns the SQL endpoint can actually query — virtual and computed lookup-display columns are excluded. Each entry has name, type, is_pk, is_name, and label.

for c in client.query.sql_columns("account"):
    print(f"{c['name']:30s} {c['type']:20s} PK={c['is_pk']}")

For deeper schema inspection — full column metadata and table relationships — use dv-metadata (client.tables.list_columns(), client.tables.list_relationships(), client.tables.list_table_relationships()).

Skill boundaries

NeedUse instead
Explicit physical ERP SQL table read or a table read in an established JIT/sqlcmd workflowerp-sql
Create, update, delete records (Dataverse)dv-data
Query, create, update, delete records (ERP)See references/erp-reads.md and erp-writes
Create tables, columns, relationshipsdv-metadata
Export or deploy solutionsdv-solution

Setup

import os, sys
sys.path.insert(0, os.path.join(os.getcwd(), "scripts"))
from auth import get_client

# get_client sets a plugin attribution context on the User-Agent header.
# Do not modify the context value — it is a closed schema for server-side
# telemetry (app/skill/agent). Never include secrets or PII.
client = get_client("dv-query")

get_client(skill) handles auth, environment URL, and plugin attribution (User-Agent tagging). See scripts/auth.py. For scripts that run to completion, wrap the returned client in a with statement for automatic connection cleanup. For ERP, use ERP MCP or the Dataverse CLI --target erp path — see references/erp-reads.md.


Field Name Casing Rule

Getting this wrong causes 400 errors.

Property typeConventionExampleWhen used
Structural (columns)LogicalName — always lowercasenew_name, new_priority$select, $filter, $orderby
Navigation (lookups)Navigation Property Name — case-sensitive, matches $metadatanew_AccountId$expand
  • System table navigation properties (e.g., parentaccountid, ownerid): lowercase
  • Custom lookup navigation properties: case-sensitive, match $metadata SchemaName (e.g., new_AccountId)

Query Records

client.records.list() is the primary read method on the GA SDK. It collects all pages and returns a flat QueryResult you iterate directly (records, not pages). For very large result sets, client.records.list_pages() streams one QueryResult per HTTP page. Always use select= to limit columns.

# list() -- flat QueryResult, iterate records directly
result = client.records.list(
    "new_ticket",
    select=["new_name", "new_priority", "new_status"],
    filter="new_status eq 100000000",
    orderby=["new_name asc"],
    top=50,
)
for r in result:
    print(r["new_name"], r["new_priority"])

print(f"{len(result)} tickets")   # QueryResult supports len(), indexing, .first(), .to_dataframe()

For large tables where you do not want every row in memory at once, stream pages:

for page in client.records.list_pages("new_ticket", select=["new_name"], page_size=200):
    for r in page:          # each page is a QueryResult
        print(r["new_name"])

Each record is a Record object that supports dict-like access: r["column"], r.get("column"), r.keys(). Do not use r.data.get() -- use r.get() directly.

Migrating from records.get(): records.get() is deprecated on the GA SDK. Replace for page in client.records.get(...): for r in page: with for r in client.records.list(...): (flat), or keep the page loop using list_pages(...). Replace a by-GUID records.get(table, guid) with records.retrieve(table, guid) (returns None if not found).


Fetch a Single Record by ID

client.records.retrieve() returns the record, or None if no row has that GUID (no exception on 404).

record = client.records.retrieve("new_ticket", "<record-guid>",
    select=["new_name", "new_priority", "new_status"])
if record is not None:
    print(record["new_name"])
else:
    print("Ticket not found")

$select with Lookup Columns (GUID-free display)

To show display names instead of GUIDs, request the formatted value annotation via include_annotations:

for r in client.records.list("opportunity",
    select=["name", "estimatedvalue", "_parentaccountid_value"],
    include_annotations="OData.Community.Display.V1.FormattedValue",
):
    account_name = r.get("_parentaccountid_value@OData.Community.Display.V1.FormattedValue")
    print(f"{r['name']} — {account_name}")

You MUST pass include_annotations — without it, the Prefer: odata.include-annotations header is not sent and formatted values are not in the response. Use "*" for all annotations or the specific annotation name above.

Formatted values are available for lookup, choice, status, and owner fields.


$expand — Resolve Lookup to Full Related Record

for r in client.records.list("opportunity",
    select=["name", "estimatedvalue"],
    expand=["parentaccountid($select=name)"],   # nested $select avoids fetching all account columns
):
    account = r.get("parentaccountid") or {}
    print(f"{r['name']} — {account.get('name', 'Unknown')}")

Always use nested $select inside $expand — without it, Dataverse returns every column on the related entity, which wastes bandwidth and memory.

$expand with multiple custom lookups

for r in client.records.list(
    "new_ticket",
    select=["new_name", "new_priority", "new_status"],
    expand=["new_CustomerId($select=new_name)", "new_AgentId($select=new_name)"],  # nested $select + case-sensitive nav props
):
    customer = r.get("new_CustomerId") or {}
    agent    = r.get("new_AgentId") or {}
    print(f"{r['new_name']} | {customer.get('new_name','')} | {agent.get('new_name','')}")

expand uses the Navigation Property Name (new_CustomerId), not the lowercase logical name (new_customerid). Using lowercase causes a 400 error.


Advanced query patterns (raw Web API)

The raw OData $apply transform is the one pattern with no SDK method. The SDK does cover aggregation/joins — client.query.sql() (INNER/LEFT JOIN, GROUP BY, COUNT/SUM/AVG) and client.query.fetchxml() (aggregate + link-entity) — and N:N $expand reads via client.records.list(<table>, expand=["<n:n_nav>"]) or client.query.builder(<table>).expand(...). Reach for raw Web API only for the $apply transform. See references/web-api-advanced.md for full code samples.

Quick reference:

  • $expand on N:N relationships: prefer SDK client.records.list(<table>, expand=["<n:n_nav>"]) / builder().expand(). Raw form: GET /<entitySet>?$expand=<n:n_nav>($select=...) — single page only; follow @odata.nextLink for >5,000 results.
  • $apply for aggregations: runs server-side, returns grouped results in one call. Patterns: groupby((col),aggregate(metric with sum as total)), aggregate($count as count), aggregate(amount with average as avg). 50K source-record limit.
  • Cross-table aggregation: $apply only works within one entity set. Prefer client.query.sql() (INNER/LEFT JOIN + GROUP BY) or fetchxml() link-entity; else pull each table via client.query.builder(t).select(...).execute().to_dataframe() → pd.merge() → groupby(). Always pass select; without it transfers 10-20x more data.

QueryBuilder — Fluent Query API

Chainable builder for complex queries that would be awkward as a single OData URL or FetchXML string. Full reference and examples in references/querybuilder.md.

Jupyter Notebook Setup

For interactive querying in notebooks (auth + DataverseClient + DataFrame display), see references/jupyter-setup.md.

Querying ERP data

On ERP-linked envs, ERP reads do not go through DataverseClient. Use ERP MCP or dataverse data query/get/count --target erp. See references/erp-reads.md.

Common Query Errors

StatusCauseFix
400Wrong field casing in $select/$filter (must be lowercase LogicalName) or $expand (must be case-sensitive Navigation Property Name)Verify names via EntityDefinitions(LogicalName='...')/Attributes
400Unsupported SQL — MCP read_query rejects DISTINCT/HAVING/subqueries/OFFSET/UNION/CAST/CONVERT/CASE/date-functions (but allows JOIN + GROUP BY); client.query.sql() rejects SELECT */subqueries/CTE/HAVING/UNION/RIGHT/FULL/CROSS JOIN/functions (but allows INNER/LEFT JOIN, GROUP BY, DISTINCT)Use fetchxml()/$apply for shapes sql() can't express, or pandas for cross-table
404Table logical name not foundCheck spelling — use client.tables.get("<name>") to verify
429Rate limitedSDK retries automatically; reduce page size or add delays between pages

For HttpError handling in SDK scripts, see the error handling pattern in dv-data.


Windows Scripting Notes

  • ASCII only in .py files — curly quotes and em dashes cause SyntaxError on Windows.
  • No python -c for multiline code — write a .py file instead.
  • Generate GUIDs in scripts: str(uuid.uuid4()), not shell backtick substitution.

Skill: Security — Role Assignment and Self-Elevation

This skill uses first-party CLIs — PAC CLI for role changes, Dataverse CLI to verify. Do NOT write Python scripts for role operations.

Preview Before Running

Role grants and self-elevate are destructive (they change security posture and are logged to Purview). Before running, preview the action in plain prose — target user, role, environment(s) — using placeholders (<ENV_URL>, <USER_EMAIL>) for anything unknown, and ask for confirmation and missing values in the same turn. Skip the raw pac admin block; the user shouldn't have to read CLI syntax to approve a security change.

Key principle: the user should be able to evaluate what's about to happen from your first response. A bare "which environment?" fails that test; a one-line prose preview passes it.

Examples

Assign role (user given, env missing):

  • ❌ "Which environment should I target?"
  • ✅ "I'll assign System Administrator to user@contoso.com on <ENV_URL>. Confirm to proceed and provide the target environment URL (or 'all' to list and batch)."

Admin access across all environments:

  • ❌ "Please provide your email address."
  • ✅ "I'll list your environments, then assign System Administrator in parallel on each one for <YOUR_UPN>. If assign-user fails on any environment, I'll fall back to self-elevate (logged to Purview) for that one. Confirm to proceed and provide your UPN."

Skill boundaries

NeedUse instead
Create or modify tables, columns, relationshipsdv-metadata
Manage org settings, audit, bulk delete, retentiondv-admin
Query or read recordsdv-query
Write, update, or delete recordsdv-data
Tenant-level governance (DLP, env lifecycle)pac admin --help

Prerequisites

  • PAC CLI installed and authenticated (pac auth create)
  • System Administrator role in target environment (or Global/PP/D365 Admin for self-elevate)
  • Active auth profile: pac auth list
  • Headless / restricted-egress hosts: SDK handles role / user / business-unit ops; service principal for PAC-only ops; verify egress with python scripts/auth.py --check. See dv-connect/references/headless-hosts.md.

Assign a Security Role to a User

pac admin assign-user --user <email-or-object-id> --role "System Administrator" --environment <url>

Arguments

ArgumentAliasRequiredDescription
--user-uYesUser email (UPN) or Azure AD object ID
--role-rYesSecurity role name (e.g., System Administrator, Basic User)
--environment-envYesTarget environment URL or ID
--application-user-auNoTreat user as an application user (service principal)
--business-unit-buNoBusiness unit ID. Defaults to the caller's business unit

Verify the assignment — exit code 0 is not proof

pac admin assign-user exits 0 even when it fails (unresolved environment, wrong role name, unknown user). Never treat a clean exit as success.

  1. Read the output, not just the exit code. A failed run still exits 0 but prints an error (environment ... not found, role ... does not exist). Stop if the output contains an error.
  2. Confirm against the exact --environment you used — do not re-resolve or shorten it; a different id silently "succeeds" on the wrong org. Query the user's roles with a Dataverse CLI read:
# Resolve the user's systemuserid, then list their assigned roles.
# --context carries plugin/skill/agent attribution on the managed CLI call.
dataverse api request --target dataverse --method GET \
  --path "/api/data/v9.2/systemusers?%24select=systemuserid&%24filter=internalemailaddress eq 'user@contoso.com'" \
  --environment <same-url-as-assign> \
  --context "app=dataverse-skills/<ver>;skill=dv-security;agent=<agent>"
dataverse api request --target dataverse --method GET \
  --path "/api/data/v9.2/systemusers(<systemuserid>)/systemuserroles_association?%24select=name" \
  --environment <same-url-as-assign> \
  --context "app=dataverse-skills/<ver>;skill=dv-security;agent=<agent>"

If the first query returns no row, the sign-in identity may live on domainname (the AAD UPN) rather than internalemailaddress (Primary Email) — retry with %24filter=domainname eq '<upn>', or azureactivedirectoryobjectid eq '<objectid>' when you assigned by object id. A missing row is not proof the grant failed.

If the target role is absent, the assignment did not take — re-run, read the output, or fall back to self-elevate.


Batch Workflow: Assign Role Across Multiple Environments

Run in parallel — never sequentially:

Step 1: pac admin list                                              -> Get all environments
Step 2: Filter by type if needed (e.g., Developer, Sandbox)        -> Identify targets
Step 3: Confirm with user — show list of target environments
Step 4: Run ALL assignments in a single bash call:
pac admin assign-user --user user@contoso.com --role "System Administrator" --environment https://dev1.crm.dynamics.com &
pac admin assign-user --user user@contoso.com --role "System Administrator" --environment https://dev2.crm.dynamics.com &
pac admin assign-user --user user@contoso.com --role "System Administrator" --environment https://dev3.crm.dynamics.com &
wait
Step 5: Verify each landed (exit 0 is not proof — see above), then report ("Assigned + verified on 3/3 environments")

Important: Always confirm which environments will be affected before assigning roles, and verify each assignment landed — a clean exit code does not prove success.


Tenant Admin Self-Elevation (Fallback)

Self-elevation is materially different from assigning a role to another user. pac admin assign-user <other> grants privilege to someone else; pac admin self-elevate grants privilege to the caller. The risk profile and audit posture are different, so the confirmation protocol is stricter.

If pac admin assign-user fails with "user has not been assigned any roles", use:

pac admin self-elevate --environment https://myorg.crm.dynamics.com
  • Requires Global Admin, Power Platform Admin, or Dynamics 365 Admin
  • All elevations are logged to Microsoft Purview
  • Uses the active auth profile if --environment is omitted

Self-elevation confirmation protocol (stricter than assign-user)

Before running pac admin self-elevate, the agent MUST:

  1. State the risk explicitly. Include this wording (or equivalent) in the pre-run summary:

    "This grants YOU System Administrator on <env>. The action is logged to Microsoft Purview with your identity and timestamp."

  2. Capture a reason. Ask for a one-line reason — ticket ID, incident number, or a free-form note such as "dev sandbox access — no ticket". Echo the reason back in the pre-run summary so the user sees what will be on the record.
  3. Wait for an explicit confirmation AFTER the user has seen both (1) and (2). Do NOT accept a bare "yes" given before the risk statement and reason are on screen.
  4. Do NOT silently fall back. If pac admin assign-user fails, surface the failure first, then offer self-elevate with this protocol — never chain them automatically.

Flow: Always try pac admin assign-user first. admin self-elevate is the documented fallback, gated by the protocol above.

CLI fallback: If pac admin self-elevate errors out, self-elevate manually via Power Platform Admin Center → select the environment → Access → System Administrator role. All elevations are still logged to Purview. (In PAC CLI 2.6.4 the command fails with bolt.authentication.http.AuthenticatedClientException / ApiVersionInvalid because the CLI sends an empty api-version= to the backend.)


Safety Rules

  • Always confirm before assigning System Administrator role
  • Show the list of target environments before batch operations
  • Self-elevation is logged and auditable — warn the user

Skill: Solution

Create, export, unpack, pack, import, and validate Dataverse solutions via PAC CLI. Includes post-import validation using the Python SDK.

Headless / restricted-egress hosts: use the raw Web API (ExportSolution / ImportSolution) for the online steps. pac solution pack/unpack are local file operations (no auth) but need a host that can run PAC -- do them on a capable machine or CI runner. Verify egress with python scripts/auth.py --check. See dv-connect/references/headless-hosts.md.

Skill boundaries

NeedUse instead
Create tables, columns, relationships, forms, viewsdv-metadata
Create, update, or delete data recordsdv-data
Query or read recordsdv-query
Connect to Dataverse / set up MCPdv-connect

Create a New Solution

Use the Python SDK for publisher and solution record creation — not raw HTTP. Publishers and solutions are standard Dataverse tables. client.records.create() and client.records.list() handle auth, pagination, and error handling automatically, avoiding the URL encoding, header boilerplate, and GUID-parsing bugs that raw urllib calls introduce.

Step 1: Find or Create the Publisher

Every solution belongs to a publisher. The publisher's customizationprefix (e.g., contoso, sa, lit) is prepended to every custom table, column, and relationship schema name. This prefix is effectively permanent — existing components keep their prefix forever, even if you change the publisher later.

Never use the default new prefix. It provides no organizational identity, risks naming collisions, and signals the developer did not follow best practices.

Discovery flow — always run this before creating a publisher:

import os, sys
sys.path.insert(0, os.path.join(os.getcwd(), "scripts"))
from auth import get_client

# get_client sets a plugin attribution context on the User-Agent header.
# Do not modify the context value — it is a closed schema for server-side
# telemetry (app/skill/agent). Never include secrets or PII.
client = get_client("dv-solution")

# 1. Query for existing non-Microsoft publishers
publishers = client.records.list(
    "publisher",
    filter="customizationprefix ne 'none' and uniquename ne 'MicrosoftCorporation' and uniquename ne 'Microsoftdynamic'",
    select=["publisherid", "uniquename", "friendlyname", "customizationprefix"],
    top=10,
)

if publishers:
    # Show existing publishers and ask user which to use
    print("Existing publishers in this environment:")
    for p in publishers:
        print(f"  {p['uniquename']} (prefix: {p['customizationprefix']}_)")
    # ASK THE USER: "Which publisher should this solution use?"
    # Or: "Should I reuse '<name>' (prefix: <prefix>_)?"
    publisher_id = publishers[0]["publisherid"]  # after user confirms
else:
    # No custom publisher exists — ASK THE USER for prefix
    # "What publisher prefix should I use? (e.g., 'contoso', 'sa', 'lit' — 2-8 lowercase chars)"
    publisher_id = client.records.create("publisher", {
        "uniquename": "<publisheruniquename>",
        "friendlyname": "<Publisher Display Name>",
        "customizationprefix": "<prefix>",   # from user input, NOT 'new'
        "description": "<description>",
    })

Rules:

  • Always ask the user before creating a new publisher or choosing a prefix. Never hardcode a prefix.
  • The prefix must match any tables already created in the solution — you cannot mix prefixes.
  • One publisher can own many solutions. Reuse an existing publisher when possible.

Step 2: Create the Solution Record

Use the SDK to create the solution record (preferred over raw Web API):

import os, sys
sys.path.insert(0, os.path.join(os.getcwd(), "scripts"))
from auth import get_client

# get_client sets a plugin attribution context on the User-Agent header.
# Do not modify the context value — it is a closed schema for server-side
# telemetry (app/skill/agent). Never include secrets or PII.
client = get_client("dv-solution")

# Create the solution record
solution_id = client.records.create("solution", {
    "uniquename": "<UniqueName>",
    "friendlyname": "<Display Name>",
    "version": "1.0.0.0",
    "publisherid@odata.bind": "/publishers(<publisher_guid>)",
})
print(f"Created solution: {solution_id}")

The required fields:

Table:  solution
Fields: uniquename    = "<UniqueName>"
        friendlyname  = "<Display Name>"
        version       = "1.0.0.0"
        publisherid   = <publisher GUID from step 1>

Note: There is no pac solution create command. PAC CLI handles export/import/pack/unpack, not solution record creation. Use the SDK or Web API to create the record.

Step 3: Add Components

Use pac solution add-solution-component to add tables, forms, views, and other components:

pac solution add-solution-component \
  --solutionUniqueName <UniqueName> \
  --component <ComponentSchemaName> \
  --componentType <TypeCode> \
  --environment <url>

Note: PAC CLI uses camelCase args here (--solutionUniqueName, --componentType), not kebab-case.

Common component type codes:

Type CodeComponent
1Entity (Table)
2Attribute (Column)
26View
60Form
61Web Resource
300Canvas App
371Connector

Repeat the command for each component you need to add.

Alternative: Auto-add via MSCRM.SolutionName Header

When creating metadata via the Web API, include the MSCRM.SolutionName header to auto-add components to the solution:

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "MSCRM.SolutionName": "<UniqueName>"
}

Important: After using this approach, verify components were added by querying the solutioncomponent table with the SDK (pac solution list-components is not available in current PAC):

sol = client.records.list("solution",
    filter="uniquename eq '<UniqueName>'", select=["solutionid"], top=1).first()
if sol is not None:
    components = client.records.list("solutioncomponent",
        filter=f"_solutionid_value eq {sol['solutionid']}",
        select=["componenttype", "objectid"])
    print(f"{len(components)} components in the solution")

If the header was misspelled or the solution doesn't exist, components will be created in the default solution instead — silently. Always verify.

Find the Solution Name

Before exporting, confirm the exact unique name:

pac solution list --environment <url>

The UniqueName column is what you pass to other commands. Display names have spaces; unique names do not.

Pull: Export + Unpack

Confirm the target environment before exporting or importing. Run pac auth list + pac org who, show the output to the user, and confirm it matches the intended environment. Developers work across multiple environments — do not assume.

Export the solution as unmanaged (source of truth):

pac solution export \
  --name <UniqueName> \
  --path ./solutions/<UniqueName>.zip \
  --managed false \
  --environment <url>

Unpack into editable source files:

pac solution unpack \
  --zipfile ./solutions/<UniqueName>.zip \
  --folder ./solutions/<UniqueName> \
  --packagetype Unmanaged

Windows file-lock race. Run export and unpack as separate commands (as above); chaining them immediately can hit a transient ZIP file-lock right after export. If unpack fails with a lock / "in use" error, retry after a moment, and verify the unpacked folder has the expected components before deleting the zip.

Delete the zip — the unpacked folder is the source:

rm ./solutions/<UniqueName>.zip

Commit:

git add ./solutions/<UniqueName>
git commit -m "chore: pull <UniqueName> baseline"
git push

Push: Pack + Import

Pack the source files back into a zip:

pac solution pack \
  --zipfile ./solutions/<UniqueName>.zip \
  --folder ./solutions/<UniqueName> \
  --packagetype Unmanaged

Import (async recommended for large solutions):

pac solution import \
  --path ./solutions/<UniqueName>.zip \
  --environment <url> \
  --async \
  --activate-plugins

Poll Import Status

After async import, check the job:

pac solution list --environment <url>

Post-Import Validation

After importing a solution, verify that components are live. Use the Python SDK to check directly — no external scripts needed.

Check a table exists

info = client.tables.get("<logical_name>")
if info:
    print(f"[PASS] Table '{info.logical_name}' exists")
else:
    print(f"[FAIL] Table '<logical_name>' not found")

Check a form is published

forms = client.records.list(
    "systemform",
    filter="objecttypecode eq '<entity>' and type eq <form_type_code>",
    select=["name", "formid"],
    top=5,
)
# Form type codes: 2 = main, 7 = quick create

Check a view exists

views = client.records.list(
    "savedquery",
    filter="returnedtypecode eq '<entity>'",
    select=["name", "savedqueryid", "statuscode"],
    top=10,
)

Check a user's role assignment (N:N $expand)

records.list passes $expand straight through, so read the N:N navigation property directly with the SDK:

users = list(client.records.list(
    "systemuser",
    filter="internalemailaddress eq '<email>'",   # fallback: domainname eq '<upn>'
    select=["fullname"],
    expand=["systemuserroles_association($select=name)"],
    top=1,
))
roles = [r["name"] for r in users[0].get("systemuserroles_association", [])] if users else []

Alternatively, the managed Dataverse CLI escape hatch (dataverse api request — not urllib), or FetchXML with a link-entity:

dataverse api request --target dataverse --method GET \
  --path "/api/data/v9.2/systemusers?%24filter=internalemailaddress eq '<email>'&%24select=fullname&%24expand=systemuserroles_association(%24select=name)&%24top=1" \
  --environment <DATAVERSE_URL> \
  --context "app=dataverse-skills/<ver>;skill=dv-solution;agent=<agent>"

The response value[0].systemuserroles_association is the list of assigned roles (each with name).

Check import errors

jobs = client.records.list(
    "importjob",
    select=["importjobid", "solutionname", "startedon", "completedon", "progress"],
    orderby=["startedon desc"],
    top=5,
)

For detailed error history, also query msdyn_solutionhistory:

history = client.records.list(
    "msdyn_solutionhistory",
    filter="msdyn_status eq 1",  # 1 = failed
    select=["msdyn_name", "msdyn_starttime", "msdyn_exceptionmessage"],
    orderby=["msdyn_starttime desc"],
    top=5,
)

Validation error reference

ErrorCauseFix
Table not found after importComponent not in solutionAdd via pac solution add-solution-component
Form check fails immediatelyPublishing is asyncWait 30 seconds and retry
Role not assignedUser not provisionedAssign the role via pac admin assign-user or the Power Platform Admin Center
Import job at 0%Import still runningPoll again in 60 seconds

Notes

  • Always use --managed false / --packagetype Unmanaged for the development solution. Managed packages are for deployment to downstream environments (test, prod).
  • --activate-plugins ensures any registered plugins in the solution are activated on import.
  • If you see "solution already exists" errors, use --import-mode ForceUpgrade to overwrite.
  • Large solutions (Sales, Customer Service) can take 10–20 minutes to import. Be patient and poll rather than re-importing.
  • All validation queries above require auth. Use scripts/auth.py for credential/token acquisition. See dv-query for SDK query patterns and dv-data for write patterns.

Skill: Finance and Operations SQL Access

Critical safety rules — read first

  1. Confirm the Dataverse URL, selected access type, exact client IP or range, and access reason before requesting credentials. JIT access changes database access and firewall configuration even though the SQL check only reads. Verify the exact organization and linked ERP environment with the targeted Dataverse CLI check below before the request. This workflow uses Dataverse CLI verification instead of the overview's PAC check; PAC is not required. Every new grant invalidates existing SQL credentials for the same user in the same environment, including credentials used in Visual Studio, SSMS, or another SQL session. Disclose this and obtain explicit approval before each grant. The user must supply the IP address or range. Never discover it, suggest a range, or recommend a lookup source or command. If the user cannot provide it, stop before requesting credentials. The user must supply the JIT reason. Use the host's structured question tool if it has one, otherwise ask in chat. Keep any reason field empty, with no suggested/default answer. Wait for a meaningful, non-empty response; never invent, infer, or auto-fill the reason.
  2. UDE-only (ErpDeploymentType = OnlineDev); the user must already have the environment System administrator (sysAdmin) role. USEs are not implemented or tested by this skill. Confirm eligibility before requesting a grant; never self-elevate. Reader is the only supported SQL access type. Obtain explicit approval for Reader access; never offer or request Writer, accept write-capable credentials, or escalate after a failure. Never broaden the approved IP scope without new explicit approval or execute direct ERP data changes; the helper only probes the connection and performs explicitly approved bounded table reads. Use supported business APIs for writes.
  3. Never expose the password. Do not invoke the credential action through a tool that displays its response. Capture the managed CLI response inside Python, keep credentials in memory, and pass the password only in the sqlcmd child's SQLCMDPASSWORD environment. Never use -P, files, .env, chat, or logs for the password.
  4. Never bypass TLS validation. Require encryption and certificate validation; do not add -C.
  5. A credential response is not a successful connection. Require sqlcmd exit code zero and a matching database/login from the connection check. Do not claim success while a JIT operation or login is pending.
  6. Default to a reusable session for interactive reads, starting with the first table request. Obtain approval to retain credentials in the owner process. Reuse only this conversation's session for the approved workspace/environment/role/IP scope. Do not close it merely because one read or agent turn finishes. Close on an explicit user request or known conversation end; idle timeout and expiry also end it. Never expose credentials, automatically renew access, or attach to another conversation's session.

This skill is an explicit opt-in exception to normal ERP OData/MCP reads, not a replacement for them. It connects to the ERP SQL database, not the Dataverse read-only TDS endpoint. A Dataverse authentication token is used to request temporary SQL credentials, not as the SQL password.

Feature eligibility: this skill supports unified development environments (UDEs) only, requiring the System administrator (sysAdmin) role in the environment. That prerequisite is separate from the SQL Reader role requested by both helpers. Supported business APIs, not direct SQL writes, belong in dv-data.

Current helper limitation: preflight accepts only ErpDeploymentType = OnlineDev. Microsoft's product database access documentation also covers unified sandbox environments (USEs), but that broader platform scope is not implemented or tested by this skill. Stop on any other deployment type; do not bypass the guard or guess a USE mapping.

Skill boundaries

NeedUse instead
Ordinary ERP business-data reads, analytics, or runtime entity/schema/action discoverydv-query
ERP record writes or DMF importsdv-data
Authentication, tools, or linkage diagnosticsdv-connect
X++ development, deployment, or database synchronizationerp-xpp
Dataverse SQL queries or TDS accessdv-query; this JIT action is ERP-only
Unified sandbox environment (USE) SQL accessNot implemented or tested here; use the documented Visual Studio workflow
Production SQL access or executing direct SQL updatesNot covered; use supported administration and business APIs

Preflight and confirmation

Before requesting a grant: if this conversation already has a ready session ID, check session.py status with its approved scope and workspace. If active, use session.py read for the newly approved table/limit: do not request a new reason, role selection, firewall grant, or credentials. The steps below apply to starting a new grant, not every read. If no reusable session exists, default to the session workflow below; disclose a one-shot fallback before using it.

  1. Load dv-overview first. For planning or skill authoring only, do not request credentials.
  2. Confirm the target Dataverse URL with the user. Run the following explicitly targeted CLI check:
dataverse org who --environment <dataverse-url> --json --context "app=dataverse-skills/<ver>;skill=erp-sql;agent=<agent>"
  1. Require OrgUrl to match the confirmed URL, a linked ErpUrl, and ErpDeploymentType equal to OnlineDev. Stop on missing linkage, another deployment type, expired authentication, or a mismatch. Use dv-connect to repair Dataverse CLI authentication if needed; do not require a separate PAC sign-in for this workflow.
  2. Locate Python, the Dataverse CLI, and sqlcmd (ODBC). Run sqlcmd -? to check the installed variant and its flags. Recognize both legacy -N Encrypt Connection and current -N[s|m|o] Encrypt Connection help formats. This helper uses the ODBC -N encryption flag (mandatory encryption); do not silently substitute another variant's syntax, select optional encryption, or bypass certificate validation.
  3. Ask the user to supply the public IPv4 address or IPv4 range/CIDR to authorize for the machine running sqlcmd, using an empty field without defaults or suggestions. Ranges are limited to 256 addresses, all public. Show both endpoints and the total address count for approval; a range allows every address between its endpoints. CIDRs must be network-aligned and include their full address span (not only usable host addresses). Never discover the IP, derive a candidate range, or recommend services, tools, commands, or other sources for finding it. Do not substitute local interface, environment-server, or SQL-reported addresses. If the user cannot supply a valid scope or declines, stop before requesting credentials.
  4. Explicitly ask the user: "What is the reason for this JIT SQL access request?" Use the host's structured question tool if it has one, with an empty free-text reason field; otherwise ask in chat. Provide no default or suggested answer. Explain that their text will be recorded as sqljitreason. Wait for a meaningful, non-empty user response; if they decline or leave it blank, stop before requesting credentials. Do not derive a reason from the task, supply a generic justification, or reuse a previous request's reason without asking. If the user already explicitly supplied a reason for this specific request, repeat their exact text for confirmation instead of asking them to retype it.
  5. Explain that only Reader access is supported and ask for approval, using the host's structured question tool if it has one, otherwise ask in chat. Do not offer a Writer option. If approval is absent or declined, stop; a fixed role does not imply consent to a grant.
  6. Show the target, linked ERP URL, Reader access type, client IP, user-provided reason verbatim, and proposed SQL (SELECT DB_NAME(), SUSER_SNAME()). For a table read, also disclose the table, schema inspection, row count, and preview limit. Warn that a new grant invalidates existing SQL credentials for the same user/environment, including credentials used in Visual Studio or SSMS, and can disrupt those workflows (see the Microsoft product database access documentation above). Obtain explicit approval for this invalidation, the JIT/firewall change, connection probe, and requested reads; stop if approval is absent or declined. Pass that exact reason to --reason (and therefore sqljitreason), without rewriting it. Environment confirmation or acceptance of an agent-generated reason does not satisfy the user-provided reason requirement.

User-supplied scope only: pass the exact approved IP/range to --client-ip. Normalizing a user-supplied CIDR to its endpoints is validation, not permission to generate, expand, or propose a different range. Never prefill from an earlier session or use a firewall error as the source for a new scope.

Discover the contract, not the password

IPv4 only: the approved SQL firewall scope must be a public IPv4 address or bounded IPv4 range/CIDR. Azure SQL firewall endpoints do not accept IPv6. Reject IPv6 before requesting credentials; do not substitute an IPv4 address without a new user-supplied value and explicit approval.

API documentation gap: the product database access page linked above documents the Visual Studio Tools > SQL Credentials for Dynamics 365 FinOps workflow, not this Dataverse action or its request/response schema. Environment metadata does not establish a publicly documented or supported API contract.

Before either helper starts a new grant, discover the action in the confirmed environment. The following metadata reads do not request credentials and are safe to display:

dataverse api list sql --target dataverse --environment <dataverse-url> --json --context "app=dataverse-skills/<ver>;skill=erp-sql;agent=<agent>"
dataverse api describe msprov_getfinopssqljitaccessasync --target dataverse --environment <dataverse-url> --json --context "app=dataverse-skills/<ver>;skill=erp-sql;agent=<agent>"

Treat msprov_getfinopssqljitaccessasync as a discovery candidate, not a fixed public contract. Use api describe to inspect its binding, method, and request/response field names and types. Compare these with the current scripts/connect.py adapter (ACTION, request_credentials, and validate_credentials). Its fixed path and field mappings are implementation assumptions; the helper does not perform metadata discovery itself.

If the action is absent, discovery fails, or the schema cannot be verified as compatible, stop before requesting credentials. Do not guess fields, substitute an endpoint, or bypass validation. Direct the user to the documented Visual Studio workflow instead. Discovery alone does not resolve the public API support gap; API-owner confirmation/public documentation is still needed before claiming a supported integration.

Do not invoke it through MCP invoke_api or a bare terminal command: that would display the password. Use the helper below, which invokes the managed Dataverse CLI and captures its output in process. No raw HTTP or new authentication flow is needed.

Request credentials and connect

One-shot fallback only: for interactive chat, use Reuse access across follow-up reads below from the first request, even if the user names only one table. The connect.py invocation in this section is only for explicitly selected one-shot execution or an explained, approved fallback when a persistent owner cannot be kept running.

Resolve scripts/connect.py relative to this skill's directory (not the workspace). Both helpers load the plugin's bundled scripts/auth.py by explicit path, so an older workspace copy cannot shadow it. Only when the bundled file is absent do they use the workspace's scripts/auth.py. The helper must expose load_env and the public get_cli_context attribution function. Missing or incompatible helpers stop before any credential request: update the plugin, or refresh the workspace copy through dv-connect helper setup for skill-only/npx installs.

After metadata discovery and the approval above, use Python to launch the helper. Replace placeholders with approved non-secret values and the resolved helper path:

import subprocess
import sys

subprocess.run(
    [
        sys.executable, "<resolved-erp-sql-skill-directory>/scripts/connect.py",
        "--environment", "<confirmed-dataverse-url>",
        "--client-ip", "<approved-public-IPv4-or-IPv4-range-or-CIDR>",
        "--reason", "<verbatim-user-provided-access-reason>",
        "--role", "Reader",
        "--confirm-environment", "<confirmed-dataverse-url>",
    ],
    check=True,
)

The one-shot helper rechecks the Dataverse organization and ERP linkage before granting access. It requests the explicitly approved Reader role, rejects any other returned role before connecting or retaining credentials in a session, validates the IP and expiry, waits 60 seconds for credential propagation, and launches sqlcmd with the returned server, database, and username. The password is placed only in a child environment; inherited SQLCMD startup/scripting settings are removed. Without --table it executes only the fixed database/login probe and exits. With --table, it completes the approved read before discarding credentials. It never opens an unattended interactive SQL session or accepts arbitrary SQL.

Reuse access across follow-up reads

Use scripts/session.py by default for interactive reads after explicit approval to retain credentials in a running process; do not require the user to predict all later table requests. It uses the same preflight, grant, SQL functions, and safeguards as the one-shot helper; no passwords are persisted or returned to the agent.

Launch start once through a supported, explicitly approved persistent background task or user-managed dedicated terminal, never a foreground subprocess.run agent call. Follow the host launch table and dedicated-terminal fallback. Inspect successive output lines for the JSON ready: true record; the first line can be a progress message. Verify readiness with status, retain the task handle and non-secret session ID in this conversation, and use read, status, and close with that ID. A readiness timeout is not permission to kill/relaunch the owner or request another grant. After a successful read, leave the owner running for follow-up turns and report the reusable session ID and its idle/expiry limits. Do not put close in a per-read cleanup/finally block or run it before each answer. Every client supplies the same environment, Reader role, and approved IP scope, and runs from the same workspace. Each later table/count/limit still needs user approval; do not infer that a grant authorizes arbitrary reads.

The session is local to the current OS user: Windows named pipe or macOS/Linux Unix-domain socket. It ends on close, JIT expiry, or 15 idle minutes; only successful reads reset the idle clock, not status checks. Requests are serialized; a busy/unavailable session is an explicit error, never a trigger for a new grant. If the harness cannot keep a process running, explain the limitation and use one-shot mode only after repeating the credential-invalidation warning and obtaining fresh grant approval; never write credentials to disk. See reusable SQL sessions for executable invocations, lifecycle, transport security, and validation limits.

Propagation retries reuse the same credentials within bounded limits; they never widen the IP scope or request another grant. See session lifecycle and retry limits for timings and stop conditions shared by both helpers. Report only non-secret server/database, role, expiry, operation ID, and the verified connection outcome. Local exit releases credential references, not the server-side grant; credentials can expire or be invalidated by a later grant.

If credentials are absent, report the operation ID and stop. Do not invent polling endpoints or assume the operation completed. Inspect the environment's actual operation-history schema and obtain approval before any follow-up operation.

Client-IP response format: the live API can return ipaddress as start-end, even for a single approved address (for example, 8.8.8.8-8.8.8.8). The helper normalizes approved CIDRs to explicit inclusive ranges for sqljitclientipaddress. Require both returned endpoints to equal the approved bounds exactly; reject broader, narrower, reversed, non-public, or oversized scopes. A single IP and an identical-endpoint range are equivalent. Never disable IP validation to make a connection succeed. A local validation failure after the API call does not undo a granted credential or its invalidation of prior credentials. Disclose this, repeat the invalidation warning, and obtain fresh approval before another grant.

Common mistakes

WrongCorrect
Requesting this action with --target erpThe action is on the linked Dataverse environment
Inventing a reason or pre-filling the reason formExplicitly ask for the user's reason with an empty free-text field; submit their confirmed text verbatim
Offering Writer or escalating after a failureOnly Reader is supported; obtain explicit approval and stop on permission failures
Guessing a credential endpoint or using an Entra token as the SQL passwordDiscover and verify the action's metadata before granting access; use only the returned SQL credentials
Printing the response or using sqlcmd -P <password>Capture in Python; use child-only SQLCMDPASSWORD
Using -C to make a TLS failure disappearFix certificate trust, hostname, or client configuration
Assuming -K ReadOnly prevents writesRequire Reader credentials; a client intent flag is not an authorization boundary
Requesting another grant after every login failureAllow propagation, retry the same credentials within bounds, then report failure
Checking only that credentials were returnedVerify sqlcmd's exit code and actual database/login
New JIT grant for each metadata/count/data queryKeep one credential response in memory for the entire approved read
Retrying propagation only for the initial probeApply the same bounded retry/expiry checks to every SQL command
Combining -h -1 with -y 0Use the helper's tested text-preview flags; these options conflict
Parsing ordinary sqlcmd output as JSONUse the text preview; only managed CLI API output is parsed as JSON

Read a physical ERP table

For an explicitly requested physical-table read within this SQL workflow, stay in erp-sql instead of assuming the table is an OData entity. Ordinary business-data reads and entity-discovery questions stay in dv-query. A table name alone is not consent to direct SQL access or a JIT grant; never infer a physical table from a business concept or entity-discovery request.

Default: session.py read, including the first table request. Follow the session workflow: reuse this conversation's ready owner, or start one once after the required approvals and wait for verified readiness. Obtain approval for the table, schema inspection, count, and preview limit, then pass --table <approved-schema.table> --top <approved-limit> to session.py read with the recorded session ID and approved scope. The user must supply the table; if absent, ask rather than select or infer one. There are no table-specific modes or business filters. --top supports 1-100 and defaults to 50. Use only --role Reader.

The read uses the owner's existing credentials; it does not request a new grant or close the owner afterward. It discovers the exact table/schema and columns, omits payload/secret-like/unsupported columns, counts rows, and returns a bounded preview. RECID ascending is not the latest rows; without it, ordering is not guaranteed. Report status codes as stored unless their enum mapping is verified.

One-shot fallback: only after explicit one-shot selection or approval of a persistence limitation, add the same read options to connect.py. This requests a new grant and discards local credentials when it exits. Repeat the invalidation warning and obtain grant approval; never switch automatically after a session error.

See table-read guidance for the complete reusable invocation, output limits, and failure recovery. No live grants are needed merely to author or test the skill.

Troubleshooting

Before any replacement grant, repeat the same-user/environment credential-invalidation warning, including the impact on Visual Studio, SSMS, or another SQL session, and obtain fresh explicit approval. This applies to firewall/IP corrections, expiry, failed validation, and owner restarts. Earlier approval is not consent to another invalidation; retries using the same credentials do not request a new grant.

  • Revoked/expired sign-in: repair the affected CLI through dv-connect, then rerun preflight. Do not inspect token cache files.
  • Missing action or unsupported deployment type: stop; do not fall back to LCS or invent another endpoint.
  • Permission failure: report it; do not self-elevate or switch to Writer.
  • Network/firewall failure: SQL-reported IPs are diagnostics used only to check whether bounded retries stay inside the user-approved scope, not a discovery source for a new grant. An out-of-scope, missing, invalid, or ambiguous IP stops the workflow. Do not copy it into --client-ip, generate a range, or recommend an IP lookup. Ask the user to supply any replacement IP/range themselves, repeat the credential-invalidation warning, and obtain fresh explicit approval before a new grant. In-scope failures use bounded retries with the same credentials; never broaden the allowlist or disable TLS.
  • Expired credentials: repeat the invalidation warning and obtain fresh approval before a new request; another tool may have obtained newer credentials for the same user/environment. Never reuse expired credentials.
  • Changing SQL egress: if a user-supplied correction is followed by another out-of-scope SQL-reported IP, stop requesting grants. Do not infer a subnet, accumulate grants, or repeatedly chase addresses. Resume only after the user independently supplies and explicitly approves a replacement scope, with the invalidation warning repeated.
  • Sanitized command failure: the helper reports the command, recognized diagnostic code/class, exit code where available, and validated SQL client IP for firewall errors, but intentionally withholds raw output that could contain credentials. Use metadata/auth checks for diagnosis, not credential-response logging.

The sqlcmd password and TLS behavior follow the Microsoft sqlcmd reference.

Skill: Finance and Operations X++ Development

Critical safety rules — read first

  1. Windows only. pac tool xpp install and pac package compile --package-type erp require Windows. Do not invent a Linux/macOS or SDK-based fallback.
  2. Confirm the target before any deploy or DB sync. Show the Dataverse environment URL, obtain explicit confirmation, then run pac org who --environment <url> and verify both the Dataverse URL and linked ERP URL/version.
  3. Never assume Full DB sync. Although standalone pac package db-sync defaults to Full, require the user to choose Full, Module, or Incremental when the request is ambiguous.
  4. Do not call deployment successful until PAC reaches a successful terminal state. Preserve and report the async operation ID on failure.
  5. Do not overwrite existing models or source files. Inspect .erp/xpp.json, descriptors, and target metadata paths before scaffolding or editing.
  6. Pin every runtime surface before ERP verification. PAC and the Dataverse CLI have separate active profiles. Before any dataverse ... --target erp check, require dataverse auth who and dataverse org who --json to match the confirmed Dataverse and linked ERP URLs. Validate ERP MCP according to its transport: direct HTTP must target <erp-url>/mcp; an stdio proxy must receive the base <erp-url> and route effectively to /mcp. Profile selection does not retarget an existing MCP connection.
  7. Treat runtime verification as possible data mutation. After the separate post-deployment opt-in, inspect the X++ implementation, disclose exact test inputs and expected mutations, and obtain confirmation for those inputs and effects. Do not apply a generic test matrix to non-idempotent operations.
  8. All additional validation after an ERP X++ package deployment is opt-in. After pac package deploy --package-type erp, capture PAC's terminal result, then ask whether the user wants any further validation and which checks to run. Do not query the async operation, execute an X++ artifact, query its ERP entity, or test its security unless selected. For runtime validation, confirm exact inputs, success criteria, and failure criteria; never invent values or execute an unapproved failure path. This rule is scoped to ERP X++ package deployment, not Dataverse solution ALM.

PAC CLI is the managed surface for the X++ lifecycle. Do not replace these commands with raw Dataverse APIs, direct calls to the ERP sidecar, LCS upload automation, or hand-written compiler invocations.

For a planning-only X++ request, loading skills and reading local references is allowed; do not make environment calls or write local files.

Intent routing

User intentAction
Create an ERP package/modelpac package init --package-type erp
Install compiler metadata for an environmentpac tool xpp install
Check/remove local SDKspac tool xpp list / pac tool xpp uninstall
Compile or build X++pac package compile --package-type erp
Deploy one prebuilt ZIPpac package deploy --package-type erp --package <zip>
Deploy all models in a repopac package deploy --package-type erp --solution-root <root>
Run DB sync onlypac package db-sync
Create an ERP custom serviceAuthor its X++ class/contracts plus AxService and AxServiceGroup metadata, then compile and deploy
Create an ERP ICustomAPI actionAuthor an ICustomAPI class, action menu item, and privilege/duty/role security, then compile, deploy, DB-sync when required, and verify through ERP MCP
Author, compile, deploy, and verifyFollow End-to-end workflow

There is no pac package build or top-level pac xpp command. For ERP, pac package compile --package-type erp compiles labels and X++, runs best-practice checks, and builds deployable managed ZIPs.

Skill boundaries

NeedUse instead
Connect/authenticate, install or update PAC CLIdv-connect
Read or analyze ERP business datadv-query
Explicit direct developer-database SQL access or temporary SQL credentialserp-sql
Create/update/delete ERP business records or import DMF datadv-data
List/cancel ERP batch jobsdv-admin
Dataverse solution ALMdv-solution
ERP UI personalization, workflow editing, or environment lifecycleFinance and Operations UI / Power Platform admin tooling; not covered

Preflight

  1. Confirm Windows.
  2. Run pac and inspect its banner; pac --version is invalid. These commands require the PAC CLI .NET tool version 2.11.1 or later.
  3. Run pac package help and pac tool xpp help. If compile, db-sync, or tool xpp is absent, load dv-connect and update to the latest .NET tool installation before continuing.
  4. For environment operations, run:
pac auth list
pac org who --environment <dataverse-url>

The output must identify the confirmed Dataverse environment and include a linked ERP URL/version. Do not substitute the ERP URL for --environment; PAC accepts the Dataverse URL and resolves ERP linkage.

  1. Before runtime verification through the Dataverse CLI or ERP MCP, run:
dataverse auth who
dataverse org who --json \
  --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>"

Require the selected CLI profile's environment URL and returned erpUrl to match the PAC target confirmed above. If they do not, run dataverse auth select --name <profile-name>, then repeat both checks. Pass --environment <dataverse-url> on commands that support it, but never treat that option as a substitute for selecting the correct profile; some ERP data commands have no environment override.

For ERP MCP verification, inspect the active server configuration. Require direct HTTP to use the confirmed <erp-url>/mcp, or require an stdio proxy such as dataverse mcp to receive the confirmed base <erp-url> and use its effective /mcp endpoint. If it differs, stop and reconnect or reinitialize the matching ERP MCP server before discovery or invocation.

Before every MCP runtime invocation, establish a fresh transport-specific session and verify its caller through an MCP-originated identity/current-session check. dataverse auth who proves only the CLI identity. If MCP cannot prove its caller, do not invoke through that session. For security acceptance, the proven caller must be the intended non-administrator test user.

  1. Before a first SDK install, explain that it downloads roughly 4 GB and expands to roughly 16 GB under %LOCALAPPDATA%\Microsoft\Dynamics365\<version>\PackagesLocalDirectory.

Command quick reference

# Scaffold one or more models
pac package init --outputDirectory <root> --package-type erp \
  --model <ModelA,ModelB> --publisher <publisher> --layer ISV

# SDK lifecycle
pac tool xpp install --environment <dataverse-url>
pac tool xpp list
pac tool xpp uninstall --version <four-part-version>

# Compile/build all configured models
pac package compile --solution-root <root> --package-type erp \
  --app-version <four-part-version> --language en-US

# Compile one model during the edit loop
pac package compile --solution-root <root> --package-type erp \
  --model <ModelName> --app-version <four-part-version> \
  --language en-US --incremental

# Deploy one compiled package, without DB sync
pac package deploy --environment <dataverse-url> --package-type erp \
  --package <root>/bin/<Model>_<version>_managed.zip \
  --build-type Full --release-type Dev --db-sync None \
  --logConsole --logFile <deployment-log-path>

# Deploy every model in .erp/xpp.json in dependency order
pac package deploy --environment <dataverse-url> --package-type erp \
  --solution-root <root> --build-type Full --release-type Dev \
  --db-sync None --logConsole --logFile <deployment-log-path>

Use explicit values rather than relying on defaults in automation. Full argument tables and DB-sync rules are in references/commands.md.

Authoring X++ source

The repo root contains .erp/xpp.json; source defaults to src/. Each model has a descriptor and metadata under:

<root>/
  .erp/xpp.json
  src/<Model>/Descriptor/<Model>.xml
  src/<Model>/<Model>/AxClass/<Class>.xml

Run pac package init instead of hand-writing the descriptor/config. Add metadata files surgically after inspecting existing paths. PAC compiles and packages authored metadata; it does not scaffold custom services, ICustomAPI actions, or data entities. For runnable classes, labels, custom services, ICustomAPI actions, public OData data entities, and artifact-specific verification, use references/authoring.md.

Compile/build rules

  • A normal compile runs labels -> X++ -> best-practice checks -> deployable ZIP.
  • Use --incremental only for the edit loop. Run a non-incremental compile before a final deployment.
  • Do not use --skip-bp unless the user explicitly requests it and understands the reduced validation.
  • If multiple SDKs are installed, pass --app-version; otherwise PAC may reject ambiguous selection.
  • Treat Compile summary: ... failed or any nonzero exit as failure even if a ZIP already exists from an earlier run.
  • Verify the output ZIP was produced by the current run under <root>/bin/.
  • If label compilation reports XPPLC2010 and PAC fails despite exit code 0 from LabelC, add a valid label resource; do not delete logs or bypass the stage.

Deploy and DB-sync rules

  • Deploy-only means --db-sync None.
  • --build-type controls how the server applies the package: Full, Incremental, or Delete; it is not a local build command.
  • --release-type Dev is the normal test/development choice. Release forces Full DB sync server-side when a sync is requested.
  • Delete ignores DB-sync settings.
  • Single-package deployment uses --package <zip>. Solution-mode deployment omits --package, reads .erp/xpp.json, topologically orders models, deploys them, then runs one requested DB sync.
  • PAC injects fnomoduledefinition.json into the ZIP at deploy time. Copy the artifact first if an immutable checksum must be retained.
  • Standalone DB sync and deploy-with-sync are separate supported workflows; never redeploy merely to satisfy a DB-sync-only request.

See references/workflows.md for compile-only, deploy-only, DB-sync-only, multi-model, and full lifecycle sequences. Apply the success gates, diagnostics flow, and error mappings in references/validation.md to every compile, deployment, DB sync, and runtime verification.

End-to-end workflow

For “make this X++ change and deploy it”:

  1. Inspect the repo and preserve existing work.
  2. Confirm model/class names, publisher, and layer before scaffolding a new model.
  3. Run pac package init --package-type erp only when the model does not exist.
  4. Add or edit the requested X++ metadata, such as classes, contracts, custom services, service groups, ICustomAPI actions and security, public data entities, and required labels.
  5. Confirm/authenticate the target environment and verify ERP linkage/version.
  6. Install or reuse the matching SDK.
  7. Compile non-incrementally and require zero compile errors. Address best-practice warnings unless the user accepts them.
  8. Deploy with explicit build/release/DB-sync modes.
  9. Capture PAC's exit code, async operation ID, terminal state, and DB-sync result as part of the deployment command. Do not run additional validation automatically.
  10. Ask whether the user wants post-deployment validation and which checks they authorize: async-operation re-query, API/action discovery, runtime behavior, data-entity query, multiple-case testing, and/or security acceptance. Earlier deployment approval and selection of one check do not authorize another.
  11. If all validation is declined, report the PAC deployment result and state that no additional validation was performed. If runtime validation is selected, inspect only the deployed custom artifact and its contract, then ask for each required input plus the expected success and failure criteria. Repeat exact values or criteria already in the prompt for confirmation; never invent or broaden them.
  12. For selected runtime checks, pin the Dataverse CLI profile and transport-specific ERP MCP target to the confirmed environment, then verify only the approved artifact:
  • Runnable class: open https://<erp-host>/?mi=SysClassRunner&cls=<ClassName>.
  • Custom service: inspect the X++ implementation for side effects before invoking erp:<ServiceGroup>/<Service>/<Operation> with dataverse api invoke --target erp --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>"; use list/describe only for discovery.
  • ICustomAPI action: if discovery was selected, use ERP MCP api_find_actions to validate its action menu item and contract. If execution was selected, invoke only approved inputs using the confirmed source contract or approved discovery result, then compare every returned property and expected mutation with the observed result.
  • Public OData data entity: if discovery was selected, inspect it with dataverse data describe --target erp. If query execution was selected, query the confirmed entity set with dataverse data query --target erp. Add --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>" to each command that runs.
  • Security acceptance: only when runtime execution and security acceptance were both selected, invoke the approved case as a non-administrator test user assigned the intended custom role. Administrator execution is diagnostic only and does not validate the privilege/duty/role chain.
  1. Report the package path, environment, async operation ID, terminal status, DB-sync mode, the validation checks accepted or declined, and results only for checks actually performed.

Common mistakes — do not use these

WrongCorrect
pac xpp installpac tool xpp install
pac xpp compilepac package compile --package-type erp
pac package buildpac package compile --package-type erp
pac package deploy --package-type xpp--package-type erp
Passing the ERP URL to --environmentPass the linked Dataverse URL
Omitting --package for one ZIPAdd --package <zip>
Adding --package for repo-wide deploymentOmit it and use --solution-root
pac package db-sync --db-sync NoneNone is deploy-only; standalone modes are Full, Module, Incremental
Module sync without --modulesAdd --modules ModelA,ModelB
Incremental sync without --argument-fileAdd a valid IncrementalSyncParameters JSON file

Sponsors

Details

Marketplace
microsoft/Dataverse-skills
Source
.github/plugins/dataverse
Category
Community