dataverse-web-api

Skill: Dataverse Web API

When to Use

Trigger when performing CRUD operations, managing metadata (tables, columns, relationships, views, forms), creating Custom APIs, managing solutions, or any direct HTTP interaction with the Dataverse Web API (OData v4.0).

---

CRITICAL RULES

1. Always Use MSCRM.SolutionUniqueName Header

Every component-creating request MUST include:

MSCRM.SolutionUniqueName: YourSolutionName

WHY: Omitting this header dumps components into the Default Solution — an ALM anti-pattern that makes the component nearly impossible to manage via solution transport. This is the single most common mistake when building via Web API.

2. @odata.type Is Required on All Column/Attribute Creation

Every column creation payload MUST include the correct @odata.type:

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

WHY: Omitting or using the wrong type returns a 400 error. The API cannot infer the column type.

3. Every Table Needs a Primary Name Column

Every custom table MUST have exactly one StringAttributeMetadata with IsPrimaryName: true included in the table creation payload. WHY: Without it, the table is created but lookups, views, and forms cannot display a name.

4. Publish After Customization Changes

After creating/modifying forms, views, sitemaps, or business rules, you MUST call:

POST /api/data/v9.2/PublishXml

WHY: Customizations are not visible to users until published. Schema changes (tables, columns) are immediately effective, but UI customizations require publishing.

5. FormXml and FetchXml Must Stay in Sync

Every attribute in a view's layoutxml MUST also appear in the fetchxml. WHY: Missing attributes in fetchxml cause blank columns in the view.

6. Authentication: Use Azure CLI

az account get-access-token \
  --resource "https://[org].crm6.dynamics.com/" \
  --tenant "[tenant-id]" \
  --query accessToken -o tsv

Do NOT use pac auth token (does not exist as a command). For CI/CD, use service principal OAuth2 client_credentials flow.