Dv Metadata

Skill: Metadata — Making Changes

Before the first metadata change in a session:

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

STOP and ask the user:

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

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

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

After user confirms, create using SDK:

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

Never create tables or columns outside a solution.

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

Skill boundaries

How Changes Are Made: Environment-First

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

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

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

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

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

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

Creating a Table

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

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

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

SDK approach (use this by default):

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

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

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

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

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

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

Column Naming: Avoid *Id Suffix Collisions

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

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

Adding Columns

SDK approach (preferred):

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

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

Choice (picklist) column via SDK:

from enum import IntEnum

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

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

Web API approach (needed for column types the SDK doesn't support — e.g., currency with precision, memo with custom max length):

# Currency column
attribute = {
    "@odata.type": "Microsoft.Dynamics.CRM.MoneyAttributeMetadata",
    "SchemaName": "new_amount",
    "DisplayName": {"@odata.type": "Microsoft.Dynamics.CRM.Label",
                    "LocalizedLabels": [{"@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
                                          "Label": "Amount", "LanguageCode": 1033}]},
    "RequiredLevel": {"Value": "None"},
    "MinValue": 0,
    "MaxValue": 1000000000,
    "Precision": 2,
    "PrecisionSource": 2
}
# POST to /api/data/v9.2/EntityDefinitions(LogicalName='new_projectbudget')/Attributes

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

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

Adding a Table to a Solution

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

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

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

Or via Web API:

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

Forms and Views

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

Quick reference:

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

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

Key invariants:

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

Business Rules

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

Publisher Prefix

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

pac solution list --environment <url>

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

FormXml Pitfalls

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

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