
dataverse
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-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add microsoft/Dataverse-skills.
Contents
Discovered from sourceSkills 10
Skill: Environment Admin — Bulk Delete, Retention, Org Settings, OrgDB, Recycle Bin
⚠️ Critical safety rules — read first
- Bulk delete is irreversible and bypasses the recycle bin.
pac data bulk-delete schedulewithout--fetchxmldeletes 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.- 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."
- Recycle bin disable is PATCH, never DELETE.
PATCH statecode=1, statuscode=2, isreadyforrecyclebin=false. DELETE enqueues async opt-out and orphans per-entity configs — seereferences/recycle-bin.md.- System tables warning. Unfiltered bulk delete on
systemuser,businessunit,organization, orrolebreaks the environment. Warn additionally before running.
Four mechanisms — pick based on where the setting lives:
| Mechanism | Use for | How |
|---|---|---|
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 XML | Keys 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 — recyclebinconfigs | Recycle bin on/off + retention days | CREATE/PATCH recyclebinconfigs entity record |
| Python SDK — settingdefinition + organizationsettings | App-level / plan-level security role toggles | Look 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 label | Column | Type |
|---|---|---|---|
| 1 | Start Auditing | isauditenabled | bool |
| 2 | Audit user access (Log access) | isuseraccessauditenabled | bool |
| 3 | Start Read Auditing (Read logs to Purview) | isreadauditenabled | bool |
| 4 | Plugin trace log setting | plugintracelogsetting | int: 0 Off, 1 Exception, 2 All |
| 5 | Single table search option | tablescopeddvsearchinapps | bool |
| 6 | Prevent slow keyword filter for quick find terms | allowleadingwildcardsinquickfind | int: 0 prevent, 1 allow (UI "prevent=On" flips to 0) |
| 7 | Quick Find record limits | quickfindrecordlimitenabled | bool |
| 8 | Use quick find view for searching on grids/subgrids | usequickfindviewforgridsearch | bool |
| 9 | Canvas apps in Dataverse solutions by default | enablecanvasappsinsolutionsbydefault | bool |
| 10 | Cloud flows in Dataverse solutions by default | enableflowsinsolutionbydefault | bool (note: solution singular) |
| 11 | Enable email address validation (preview) | isemailaddressvalidationenabled | bool |
| 12 | Minimum number of characters to trigger typeahead | lookupcharactercountbeforeresolve | int (0–MAX_INT, null = feature off) |
| 13 | Delay between character inputs that trigger a search | lookupresolvedelayms | int ms (default 250) |
| 14 | Audit log retention policy / Custom retention period (days) | auditretentionperiodv2 | int 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:
| Value | Dataverse search | M365 Copilot search |
|---|---|---|
0 | Off | On |
1 | On | On |
2 | Off | Off |
3 | On | Off |
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 fetchper env, or starting with Python/SDK because it "feels like a query." - ✅ "I'll run
pac org list-settings --filter auditin parallel across all N environments (one&-batch, singlewait)."
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 retentionare only in the .NET Framework build (not thedotnet toolversion). Checkpac help; if it shows.NET 10/.NET 8, runpac 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
organizationrecords); service principal for PAC-only ones. Seedv-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
| Wrong | Correct |
|---|---|
--filter | use --fetchxml with a FetchXML string |
--query / --where / --condition | use --fetchxml |
--date / --before / --older-than | encode date in FetchXML <condition> |
--job-id | use --id |
--all / --purge / --truncate | omit --fetchxml to target all records (warn user first) |
Retention
| Wrong | Correct |
|---|---|
--fetchxml | use --criteria (same FetchXML format, different flag name) |
--filter / --query / --policy | use --criteria |
--enable / --activate | use pac data retention enable-entity |
--table | use --entity |
--operation-id / --job-id / --guid | use --id |
Org Settings
| Wrong | Correct |
|---|---|
--enable-audit / --audit | use --name isauditenabled --value true |
--trace / --plugin-trace / --logging | use --name plugintracelogsetting --value 2 |
--setting / --key / --flag | use --name |
String values like "all" or "enabled" for option sets | use 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"
| Argument | Alias | Required | Description |
|---|---|---|---|
--entity | -e | Yes | Logical name of the table |
--fetchxml | -fx | No | FetchXML filter. See the hard-stop rule below — if omitted, ALL records in the table are deleted. |
--job-name | -jn | No | Descriptive name for the job |
--start-time | -st | No | ISO 8601 start time. Defaults to now |
--recurrence | -r | No | RFC 5545 pattern (e.g., FREQ=DAILY;INTERVAL=1) |
--environment | -env | No | Target 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:
- 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. - Disambiguate vague asks ("clean up old emails") — propose a FetchXML filter with date / statecode / owner conditions before showing any command.
- Empty-filter FetchXML doesn't bypass the gate —
<filter/>or<filter><condition><value/></condition></filter>still targets every record. - Scope: applies to
bulk-delete scheduleonly.cancel,pause,resume,show,listdon'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>
| Argument | Alias | Required | Description |
|---|---|---|---|
--entity | -e | Yes | Logical name of the table |
--criteria | -c | Yes | FetchXML defining which records to archive |
--start-time | -st | No | ISO 8601 start time. Defaults to now |
--recurrence | -r | No | RFC 5545 recurrence pattern |
--environment | -env | No | Target environment URL |
Retention vs Bulk Delete
| Scenario | Use |
|---|---|
| Data no longer needed, permanently delete | Bulk Delete |
| Data must be preserved for compliance | Retention (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: trueis 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
ProcessRecycleBinasync 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
isreadyforrecyclebinexplicitly (true on enable, false on disable), and drain any in-flightProcessRecycleBinasync jobs before any second toggle. Omitting these can produceEntityBinUpdateAction called for entity <x> which is not enabled for RecycleBinon 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, verifypython 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.
.envis present and complete — file exists at the workspace root and contains non-empty values forDATAVERSE_URL,TENANT_ID, andMCP_CLIENT_ID- MCP is registered — the host MCP list has a
dataverse-*entry, or Gemini has its bundleddataverseentry, pointing atDATAVERSE_URL - Both auth surfaces match
.env—dataverse auth whoshows a profile whoseEnvironment UrlmatchesDATAVERSE_URL, ANDpac org whoagainst a PAC profile for the same URL succeeds. (DV CLI auth covers Connect / Data / Query / Metadata / MCP / Python; PAC auth coversdv-solutionanddv-admin. Both are front-loaded at connect time so neither prompts later.) - 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.
| Tool | Check |
|---|---|
| Python 3 | python --version |
| Git | git --version |
| Node.js | node --version |
| PAC CLI | pac (prints version banner; pac --version is not valid) (see tools-setup.md if not in PATH) |
| Dataverse CLI | npm list -g @microsoft/dataverse |
| .NET SDK | dotnet --version |
| Azure CLI | az --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:
dataverse auth create(app0c412cc3-…) covers DV CLI + MCP + Python.pac auth create(PAC's own app) coversdv-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_URLandTENANT_IDfrom 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?
- Interactive login (recommended) — Sign in via browser. No app registration needed. Token stays cached across sessions.
- CI/CD service principal — Use
CLIENT_SECRETorCLIENT_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 whofails → re-run Step 2.pac org whofails → re-run Step 2b.python scripts/auth.py --checkprints a device-code URL → browser/WAM cache has no Python-reusable token. Auto-fix: re-rundataverse auth create --environment <url> --deviceCode, then retry. If it still prompts, checkpip show msal msal-extensions. Headless hosts (ChatGPT / Codex cloud / CI):dataverse auth createcan't persist here — don't loop (see headless-hosts.md).python scripts/auth.py --checkprintsNOT REACHABLEwith 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 listresolves bundled serverdataverseto the selected URL - Antigravity:
agy mcp listcontains 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:
- Detect which tool the user is running (Copilot, Claude, Cursor, Codex, Gemini, or Antigravity) from context
- Set
MCP_CLIENT_IDbased on tool choice - Get environment URL from
.env - Default to GA endpoint (
/api/mcp) - Register the MCP server per host (see the per-host blocks below)
- Handle Dataverse admin consent and allowlist — prefer
dataverse mcp allow <MCP_CLIENT_ID>over the portal (one-time per tenant/environment) - If
ERP_URLexists, 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 --continueto 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/dataverseproxy 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, thengemini mcp list - Antigravity:
agy mcp list; after restart,/mcpThis 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/searcherrors): the server can speak MCP but cannot reach or read Dataverse. Run--validatebelow 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 Forbiddenon 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 successwarning in this case. The validator returns exit code1(failure) unless BOTH/api/mcpand/api/mcp_previewpass. Because most environments don't enable the Preview endpoint,--validatewill exit1even 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-solutionskill. 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 installor write a.jsfile, 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
| Need | Use instead |
|---|---|
| Query or read records | dv-query |
| Create tables, columns, relationships, forms, views | dv-metadata |
| Export or deploy solutions | dv-solution |
| ERP writes | See 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, orPOST /api/data/v9.2/<entity>(<id>)/<nav-property>/$ref $applyaggregation — useclient.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 type | Convention | Example | When used |
|---|---|---|---|
| Structural (columns) | LogicalName — always lowercase | new_name, new_priority | Record payload keys |
| Navigation (lookups) | Navigation Property Name — case-sensitive, matches $metadata | new_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
| Lookup | Correct key | Wrong |
|---|---|---|
Custom: new_AccountId | new_AccountId@odata.bind | new_accountid@odata.bind |
System polymorphic: customerid | customerid_account@odata.bind | customerid@odata.bind |
System: parentcustomerid | parentcustomerid_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
UpsertItemwith alternate keys instead ofcreate()— seereferences/multi-table-fk-import.md. Thecreate()pattern here is for one-shot loads only.
| Volume | Tool | Why |
|---|---|---|
| 1 record | CLI dataverse data create or MCP create_record | No script needed |
| 2–25 records | MCP create_record | Batches up to 25 per call |
| 25+ records | SDK 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):
- Create a single test record with your intended minimal payload
- If
HttpError400 is raised, the error message names the missing required field - Some required fields are plugin-enforced and not visible in
describe - 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:
- Create tables with source ID columns + alternate keys + lookup relationships (see dv-metadata).
- Import Level 0 (no FK deps) tables in parallel via
ThreadPoolExecutor. Sequential chunks within each table (concurrent writes deadlock). - Build source-ID → GUID maps by querying back (upsert doesn't return GUIDs).
- 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 —
UpsertMultiplefails. - 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
.pyfiles — curly quotes and em dashes causeSyntaxErroron Windows. - No
python -cfor multiline code — write a.pyfile 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.
UserLocalizedLabelmay 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. UsesCreateMultiple,.example.comemails,555-01xxphones, against the activepac auth listenvironment. 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
EntityDefinitionsforcr123_projectto discover required columns, then generate 5 records inline mapping each column to a generator byAttributeTypeand callclient.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:
- Confirm the target environment with the user — see the Multi-Environment Rule in dv-overview.
- Confirm the solution — ask "What solution should these components go into?" If
SOLUTION_NAMEis 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.
- Pass
solution="<UniqueName>"in every SDK call, or include"MSCRM.SolutionName": "<UniqueName>"on every raw Web API call.
Skill boundaries
| Need | Use instead |
|---|---|
| Create, update, or delete data records | dv-data |
| Query or read records | dv-query |
| Export or deploy solutions | dv-solution |
| ERP schema | dv-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:
- Make the change in the environment via the Dataverse MetadataService API (or
paccommands where available) - Pull the change into the repo via
pac solution export+pac solution unpack - 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_SrcDepartmentIdorprefix_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 key | Entity set |
|---|---|---|
new_AccountId | new_AccountId@odata.bind | /accounts(<guid>) |
new_ParentTicketId | new_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 → mutateformxml→records.update("systemform", id, {...})→ publish. - Publish:
dataverse api requestPOSTPublishXml— 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
idattributes in form XML must be unique GUIDs (str(uuid.uuid4()).upper()). - Do not use
python -cfor GUID generation on Windows — write a.pyfile. - 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
idattributes must be valid GUIDs in{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}format. Do not use strings like"general". labelidis 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
classidvalues — 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 Name | Logical Name | Type |
|---|---|---|
| cr9ac_email | String | |
| Tier | cr9ac_tier | Picklist |
| Customer | cr9ac_customerid | Lookup |
This prevents downstream failures when the user tries to insert data using incorrect column names.
Common Web API Error Codes
| Error Code | Meaning | Recovery |
|---|---|---|
0x80040216 | Transient metadata cache error. Column or table metadata not yet propagated. | Wait 3-5 seconds and retry. Usually succeeds on second attempt. |
0x80048d19 | Invalid property in payload. A field name doesn't match any column on the table. | Check logical column names — use EntityDefinitions(LogicalName='...')/Attributes to verify. |
0x80040237 | Schema name already exists. | Verify the column/table exists before creating a new one — it may have been created by a previous timed-out call. |
0x8004431a | Publisher prefix mismatch. | Ensure all schema names use the solution's publisher prefix. |
0x80060891 | Metadata 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.bindfails 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
clientfrom 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 — seereferences/alternate-keys.mdfor theensure_alternate_keyhelper. - Index creation is async — for large tables, poll
client.tables.get_alternate_keys(table)untilstatus == "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-upupdate_table(if the table exists, skip creation). - Self-referential lookups (Parent → same table) are added via
update_tableafter 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.
| Area | Skill |
|---|---|
| Connect, authenticate, configure MCP, verify the environment | dv-connect |
| Schema — tables, columns, relationships, forms, views; inspect existing schema | dv-metadata |
| Data writes — record CRUD, bulk create/update/upsert, CSV/FK-ordered import, sample data | dv-data |
| Data reads & analytics — OData queries, QueryBuilder, FetchXML (aggregation + N:N joins), DataFrames | dv-query |
| Solution ALM — create, export, import, pack/unpack, post-import validation | dv-solution |
| Finance and Operations X++ — author, build, deploy, DB sync, verify | erp-xpp |
| Finance and Operations UDE developer-database access (JIT SQL) | erp-sql |
| Environment administration — bulk delete, retention/archival, org & OrgDB settings, recycle bin | dv-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 canvasor 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 printsREACHABLE(exit 0), the workspace is bootable without pip -- confirm the URL and proceed. If--pingfails, rundv-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 installand the Python SDK (PowerPlatform-Dataverse-Client) for data and schema logic - Use
scripts/auth.pyfor tokens/credentials;azure-identity(Python) for Azure credential flows - Treat the Dataverse CLI (
dataverse) andpacas 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 preferdataverse api(managed auth, exit codes) over hand-rolledurllib/get_token. Forms/views are not raw-only (SDKrecords.create/updateonsystemform/savedquery; onlyPublishXmlneedsdataverse api). Aggregation/N:N joins aren't raw-only either:client.query.fetchxml()(aggregates + link-entity), or the CLI'sdata associatefor 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, andscripts/auth.pyviamsal-extensions.scripts/auth.py— Python/SDK auth (service principal → shared CLI cache → device-code). Preferget_client(skill)(SDK);get_plugin_headers(skill, get_token())is the fallback for SDK gaps — both stamp attribution.pac auth create(PAC CLI) authenticatespacfordv-solution,dv-admin, anderp-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 throughscripts/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.
| Tool | Use for | Does NOT support |
|---|---|---|
| MCP Server | Data 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/download | Forms, 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 snippets | OData $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 CLI | Solution 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 CLI | App registrations, service principals, credential management | Dataverse-specific operations |
| GitHub CLI | Repo management, GitHub secrets, Actions workflow status | Dataverse-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.
| Operation | SDK call | Skill |
|---|---|---|
| Create / update / delete records | client.records.create() / .update() / .delete() (pass a list for bulk) | dv-data |
| Upsert on an alternate key | client.records.upsert() | dv-data |
| Query / filter records | client.records.list(...) (flat) or .list_pages(...) (streaming) | dv-query |
| One record by GUID | client.records.retrieve(table, guid) (None if missing) | dv-query |
| Aggregation / server-side joins | client.query.fetchxml(xml) (aggregates + link-entity) | dv-query |
| Fluent query build (chainable) | client.query.builder(Table).where(...).execute() | dv-query |
| Limited SQL read | client.query.sql("SELECT ...") | dv-query |
| Load into pandas | client.query.builder(table).select(...).execute().to_dataframe() | dv-query |
| Upload to a file column | client.files.upload(...) | dv-data |
| Create tables / columns / lookups / N:N | client.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 schema | client.tables.list_columns(table) / .list_table_relationships(table) | dv-metadata |
| Create publisher / solution | client.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"):
- Do NOT silently fall back to the Python SDK or Web API
- Tell the user: "Dataverse MCP tools aren't configured in this session yet."
- Load
dv-connectto set up the MCP server - 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?"):
- Use the CLI (if profile exists) or SDK to answer. Do not block the user.
- 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:
- Show the user the environment URL you intend to use
- Ask them to confirm it is correct
- Run
pac org whoto 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:
- Ask the user: "What solution should these components go into?"
- If a solution name is in
.env(SOLUTION_NAME), confirm it with the user - If no solution exists yet, load the
dv-solutionskill 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})",
})
- 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 queryin SQL mode auto-pluralizes the table name, and irregular plurals resolve wrong:FROM im_categorylooks up entity setim_categorysand 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 realEntitySetNamefromEntityDefinitionswhen unsure; never conclude the table doesn't exist from this 404. - Windows shell quoting. Wrap the whole
--pathvalue in double quotes socmd.exe/PowerShell don't treat&as a command separator. Keep&literal — it separates OData query options; encoding it to%26merges them and breaks the query. Encode only$->%24(in PowerShell a bare$selectis 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 thedataverse api requestexamples 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... | Approach | Why |
|---|---|---|
| "show me open tickets" / simple filter | MCP read_query, CLI dataverse data query --table ... --filter ..., or client.records.list(table, filter=...) | Small result, no aggregation |
| "how many X" / simple count | CLI 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 BY | Both run server-side, return only grouped results |
| Cross-table aggregation | client.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 lookups | client.records.list(table, expand=...) or QueryBuilder | Lookup resolution |
| "export this data" / bulk extract | client.query.builder(t).select(...).execute().to_dataframe() | Direct to DataFrame → CSV |
| "load into notebook" / interactive analysis | client.query.builder(t).select(...).execute().to_dataframe() | pandas native |
| "find duplicates" / complex filter | client.records.list(table, filter=...) or QueryBuilder | SDK 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
| Need | Use instead |
|---|---|
| Explicit physical ERP SQL table read or a table read in an established JIT/sqlcmd workflow | erp-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, relationships | dv-metadata |
| Export or deploy solutions | dv-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 type | Convention | Example | When used |
|---|---|---|---|
| Structural (columns) | LogicalName — always lowercase | new_name, new_priority | $select, $filter, $orderby |
| Navigation (lookups) | Navigation Property Name — case-sensitive, matches $metadata | new_AccountId | $expand |
- System table navigation properties (e.g.,
parentaccountid,ownerid): lowercase - Custom lookup navigation properties: case-sensitive, match
$metadataSchemaName (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. Replacefor page in client.records.get(...): for r in page:withfor r in client.records.list(...):(flat), or keep the page loop usinglist_pages(...). Replace a by-GUIDrecords.get(table, guid)withrecords.retrieve(table, guid)(returnsNoneif 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','')}")
expanduses 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:
$expandon N:N relationships: prefer SDKclient.records.list(<table>, expand=["<n:n_nav>"])/builder().expand(). Raw form:GET /<entitySet>?$expand=<n:n_nav>($select=...)— single page only; follow@odata.nextLinkfor >5,000 results.$applyfor 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:
$applyonly works within one entity set. Preferclient.query.sql()(INNER/LEFT JOIN + GROUP BY) orfetchxml()link-entity; else pull each table viaclient.query.builder(t).select(...).execute().to_dataframe()→pd.merge()→groupby(). Always passselect; 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
| Status | Cause | Fix |
|---|---|---|
| 400 | Wrong field casing in $select/$filter (must be lowercase LogicalName) or $expand (must be case-sensitive Navigation Property Name) | Verify names via EntityDefinitions(LogicalName='...')/Attributes |
| 400 | Unsupported 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 |
| 404 | Table logical name not found | Check spelling — use client.tables.get("<name>") to verify |
| 429 | Rate limited | SDK 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
.pyfiles — curly quotes and em dashes causeSyntaxErroron Windows. - No
python -cfor multiline code — write a.pyfile 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.comon<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>. Ifassign-userfails 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
| Need | Use instead |
|---|---|
| Create or modify tables, columns, relationships | dv-metadata |
| Manage org settings, audit, bulk delete, retention | dv-admin |
| Query or read records | dv-query |
| Write, update, or delete records | dv-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. Seedv-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
| Argument | Alias | Required | Description |
|---|---|---|---|
--user | -u | Yes | User email (UPN) or Azure AD object ID |
--role | -r | Yes | Security role name (e.g., System Administrator, Basic User) |
--environment | -env | Yes | Target environment URL or ID |
--application-user | -au | No | Treat user as an application user (service principal) |
--business-unit | -bu | No | Business 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.
- 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. - Confirm against the exact
--environmentyou 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
--environmentis omitted
Self-elevation confirmation protocol (stricter than assign-user)
Before running pac admin self-elevate, the agent MUST:
- 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." - 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. - 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.
- Do NOT silently fall back. If
pac admin assign-userfails, surface the failure first, then offerself-elevatewith 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/unpackare local file operations (no auth) but need a host that can run PAC -- do them on a capable machine or CI runner. Verify egress withpython scripts/auth.py --check. Seedv-connect/references/headless-hosts.md.
Skill boundaries
| Need | Use instead |
|---|---|
| Create tables, columns, relationships, forms, views | dv-metadata |
| Create, update, or delete data records | dv-data |
| Query or read records | dv-query |
| Connect to Dataverse / set up MCP | dv-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 createcommand. 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 Code | Component |
|---|---|
| 1 | Entity (Table) |
| 2 | Attribute (Column) |
| 26 | View |
| 60 | Form |
| 61 | Web Resource |
| 300 | Canvas App |
| 371 | Connector |
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
unpackfails 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
| Error | Cause | Fix |
|---|---|---|
| Table not found after import | Component not in solution | Add via pac solution add-solution-component |
| Form check fails immediately | Publishing is async | Wait 30 seconds and retry |
| Role not assigned | User not provisioned | Assign the role via pac admin assign-user or the Power Platform Admin Center |
| Import job at 0% | Import still running | Poll again in 60 seconds |
Notes
- Always use
--managed false/--packagetype Unmanagedfor the development solution. Managed packages are for deployment to downstream environments (test, prod). --activate-pluginsensures any registered plugins in the solution are activated on import.- If you see "solution already exists" errors, use
--import-mode ForceUpgradeto 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.pyfor credential/token acquisition. Seedv-queryfor SDK query patterns anddv-datafor write patterns.
Skill: Finance and Operations SQL Access
Critical safety rules — read first
- 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.
- 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.- 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
SQLCMDPASSWORDenvironment. Never use-P, files,.env, chat, or logs for the password.- Never bypass TLS validation. Require encryption and certificate validation; do not add
-C.- 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.
- 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
| Need | Use instead |
|---|---|
| Ordinary ERP business-data reads, analytics, or runtime entity/schema/action discovery | dv-query |
| ERP record writes or DMF imports | dv-data |
| Authentication, tools, or linkage diagnostics | dv-connect |
| X++ development, deployment, or database synchronization | erp-xpp |
| Dataverse SQL queries or TDS access | dv-query; this JIT action is ERP-only |
| Unified sandbox environment (USE) SQL access | Not implemented or tested here; use the documented Visual Studio workflow |
| Production SQL access or executing direct SQL updates | Not 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.
- Load dv-overview first. For planning or skill authoring only, do not request credentials.
- 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>"
- Require
OrgUrlto match the confirmed URL, a linkedErpUrl, andErpDeploymentTypeequal toOnlineDev. 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. - Locate Python, the Dataverse CLI, and sqlcmd (ODBC). Run
sqlcmd -?to check the installed variant and its flags. Recognize both legacy-N Encrypt Connectionand current-N[s|m|o] Encrypt Connectionhelp formats. This helper uses the ODBC-Nencryption flag (mandatory encryption); do not silently substitute another variant's syntax, select optional encryption, or bypass certificate validation. - 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.
- 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. - 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.
- 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 thereforesqljitreason), 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
| Wrong | Correct |
|---|---|
Requesting this action with --target erp | The action is on the linked Dataverse environment |
| Inventing a reason or pre-filling the reason form | Explicitly ask for the user's reason with an empty free-text field; submit their confirmed text verbatim |
| Offering Writer or escalating after a failure | Only Reader is supported; obtain explicit approval and stop on permission failures |
| Guessing a credential endpoint or using an Entra token as the SQL password | Discover 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 disappear | Fix certificate trust, hostname, or client configuration |
Assuming -K ReadOnly prevents writes | Require Reader credentials; a client intent flag is not an authorization boundary |
| Requesting another grant after every login failure | Allow propagation, retry the same credentials within bounds, then report failure |
| Checking only that credentials were returned | Verify sqlcmd's exit code and actual database/login |
| New JIT grant for each metadata/count/data query | Keep one credential response in memory for the entire approved read |
| Retrying propagation only for the initial probe | Apply the same bounded retry/expiry checks to every SQL command |
Combining -h -1 with -y 0 | Use the helper's tested text-preview flags; these options conflict |
| Parsing ordinary sqlcmd output as JSON | Use 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
- Windows only.
pac tool xpp installandpac package compile --package-type erprequire Windows. Do not invent a Linux/macOS or SDK-based fallback.- 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.- Never assume Full DB sync. Although standalone
pac package db-syncdefaults toFull, require the user to chooseFull,Module, orIncrementalwhen the request is ambiguous.- Do not call deployment successful until PAC reaches a successful terminal state. Preserve and report the async operation ID on failure.
- Do not overwrite existing models or source files. Inspect
.erp/xpp.json, descriptors, and target metadata paths before scaffolding or editing.- Pin every runtime surface before ERP verification. PAC and the Dataverse CLI have separate active profiles. Before any
dataverse ... --target erpcheck, requiredataverse auth whoanddataverse org who --jsonto 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.- 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.
- 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 intent | Action |
|---|---|
| Create an ERP package/model | pac package init --package-type erp |
| Install compiler metadata for an environment | pac tool xpp install |
| Check/remove local SDKs | pac tool xpp list / pac tool xpp uninstall |
| Compile or build X++ | pac package compile --package-type erp |
| Deploy one prebuilt ZIP | pac package deploy --package-type erp --package <zip> |
| Deploy all models in a repo | pac package deploy --package-type erp --solution-root <root> |
| Run DB sync only | pac package db-sync |
| Create an ERP custom service | Author its X++ class/contracts plus AxService and AxServiceGroup metadata, then compile and deploy |
Create an ERP ICustomAPI action | Author 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 verify | Follow 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
| Need | Use instead |
|---|---|
| Connect/authenticate, install or update PAC CLI | dv-connect |
| Read or analyze ERP business data | dv-query |
| Explicit direct developer-database SQL access or temporary SQL credentials | erp-sql |
| Create/update/delete ERP business records or import DMF data | dv-data |
| List/cancel ERP batch jobs | dv-admin |
| Dataverse solution ALM | dv-solution |
| ERP UI personalization, workflow editing, or environment lifecycle | Finance and Operations UI / Power Platform admin tooling; not covered |
Preflight
- Confirm Windows.
- Run
pacand inspect its banner;pac --versionis invalid. These commands require the PAC CLI .NET tool version 2.11.1 or later. - Run
pac package helpandpac tool xpp help. Ifcompile,db-sync, ortool xppis absent, load dv-connect and update to the latest .NET tool installation before continuing. - 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.
- 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.
- 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
--incrementalonly for the edit loop. Run a non-incremental compile before a final deployment. - Do not use
--skip-bpunless 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: ... failedor 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
XPPLC2010and 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-typecontrols how the server applies the package:Full,Incremental, orDelete; it is not a local build command.--release-type Devis the normal test/development choice.Releaseforces Full DB sync server-side when a sync is requested.Deleteignores 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.jsoninto 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”:
- Inspect the repo and preserve existing work.
- Confirm model/class names, publisher, and layer before scaffolding a new model.
- Run
pac package init --package-type erponly when the model does not exist. - Add or edit the requested X++ metadata, such as classes, contracts, custom services, service groups,
ICustomAPIactions and security, public data entities, and required labels. - Confirm/authenticate the target environment and verify ERP linkage/version.
- Install or reuse the matching SDK.
- Compile non-incrementally and require zero compile errors. Address best-practice warnings unless the user accepts them.
- Deploy with explicit build/release/DB-sync modes.
- 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.
- 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.
- 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.
- 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>withdataverse api invoke --target erp --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>"; uselist/describeonly for discovery. ICustomAPIaction: if discovery was selected, use ERP MCPapi_find_actionsto 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 withdataverse 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.
- 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
| Wrong | Correct |
|---|---|
pac xpp install | pac tool xpp install |
pac xpp compile | pac package compile --package-type erp |
pac package build | pac package compile --package-type erp |
pac package deploy --package-type xpp | --package-type erp |
Passing the ERP URL to --environment | Pass the linked Dataverse URL |
Omitting --package for one ZIP | Add --package <zip> |
Adding --package for repo-wide deployment | Omit it and use --solution-root |
pac package db-sync --db-sync None | None is deploy-only; standalone modes are Full, Module, Incremental |
Module sync without --modules | Add --modules ModelA,ModelB |
Incremental sync without --argument-file | Add a valid IncrementalSyncParameters JSON file |
Sponsors
Details
- Marketplace
- microsoft/Dataverse-skills
- Source
- .github/plugins/dataverse
- Category
- Community