dv-solution

# Skill: Solution Create, export, unpack, pack, import, and validate Dataverse solutions via PAC CLI. Includes post-import validation using the Python SDK. > **Headless / restricted-egress hosts**: use the raw Web API (`ExportSolution` / `ImportSolution`) for the online steps. `pac solution pack`/`unpack` are local file operations (no auth) but need a host that can run PAC -- do them on a capable machine or CI runner. Verify egress with `python scripts/auth.py --check`. See `dv-connect/references/headless-hosts.md`. ## Skill boundaries | 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:** ```python 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): ```python import os, sys sys.path.insert(0, os.path.join(os.getcwd(), "scripts")) from auth import get_client # get_client sets a plugin attribution context on the User-Agent header. # Do not modify the context value — it is a closed schema for server-side # telemetry (app/skill/agent). Never include secrets or PII. client = get_client("dv-solution") # Create the solution record solution_id = client.records.create("solution", { "uniquename": "<UniqueName>", "friendlyname": "<Display Name>", "version": "1.0.0.0", "publisherid@odata.bind": "/publishers(<publisher_guid>)", }) print(f"Created solution: {solution_id}") ``` The required fields: ``` Table: solution Fields: uniquename = "<UniqueName>" friendlyname = "<Display Name>" version = "1.0.0.0" publisherid = <publisher GUID from step 1> ``` > **Note:** There is no `pac solution create` command. PAC CLI handles export/import/pack/unpack, not solution record creation. Use the SDK or Web API to create the record. ### Step 3: Add Components Use `pac solution add-solution-component` to add tables, forms, views, and other components: ``` pac solution add-solution-component \ --solutionUniqueName <UniqueName> \ --component <ComponentSchemaName> \ --componentType <TypeCode> \ --environment <url> ``` > **Note:** PAC CLI uses camelCase args here (`--solutionUniqueName`, `--componentType`), not kebab-case. Common component type codes: | Type 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: ```python 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): ```python sol = client.records.list("solution", filter="uniquename eq '<UniqueName>'", select=["solutionid"], top=1).first() if sol is not None: components = client.records.list("solutioncomponent", filter=f"_solutionid_value eq {sol['solutionid']}", select=["componenttype", "objectid"]) print(f"{len(components)} components in the solution") ``` If the header was misspelled or the solution doesn't exist, components will be created in the default solution instead — silently. Always verify. ## Find the Solution Name Before exporting, confirm the exact unique name: ``` pac solution list --environment <url> ``` The `UniqueName` column is what you pass to other commands. Display names have spaces; unique names do not. ## Pull: Export + Unpack > **Confirm the target environment before exporting or importing.** Run `pac auth list` + `pac org who`, show the output to the user, and confirm it matches the intended environment. Developers work across multiple environments — do not assume. Export the solution as unmanaged (source of truth): ``` pac solution export \ --name <UniqueName> \ --path ./solutions/<UniqueName>.zip \ --managed false \ --environment <url> ``` Unpack into editable source files: ``` pac solution unpack \ --zipfile ./solutions/<UniqueName>.zip \ --folder ./solutions/<UniqueName> \ --packagetype Unmanaged ``` > **Windows file-lock race.** Run export and unpack as **separate** commands (as above); chaining them immediately can hit a transient ZIP file-lock right after export. If `unpack` fails with a lock / "in use" error, retry after a moment, and verify the unpacked folder has the expected components before deleting the zip. Delete the zip — the unpacked folder is the source: ``` rm ./solutions/<UniqueName>.zip ``` Commit: ``` git add ./solutions/<UniqueName> git commit -m "chore: pull <UniqueName> baseline" git push ``` ## Push: Pack + Import Pack the source files back into a zip: ``` pac solution pack \ --zipfile ./solutions/<UniqueName>.zip \ --folder ./solutions/<UniqueName> \ --packagetype Unmanaged ``` Import (async recommended for large solutions): ``` pac solution import \ --path ./solutions/<UniqueName>.zip \ --environment <url> \ --async \ --activate-plugins ``` ## Poll Import Status After async import, check the job: ``` pac solution list --environment <url> ``` ## Post-Import Validation After importing a solution, verify that components are live. Use the Python SDK to check directly — no external scripts needed. ### Check a table exists ```python 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 ```python 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 ```python 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: ```python 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: ```bash 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 ```python jobs = client.records.list( "importjob", select=["importjobid", "solutionname", "startedon", "completedon", "progress"], orderby=["startedon desc"], top=5, ) ``` For detailed error history, also query `msdyn_solutionhistory`: ```python 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 Unmanaged` for the development solution. Managed packages are for deployment to downstream environments (test, prod). - `--activate-plugins` ensures any registered plugins in the solution are activated on import. - If you see "solution already exists" errors, use `--import-mode ForceUpgrade` to overwrite. - Large solutions (Sales, Customer Service) can take 10–20 minutes to import. Be patient and poll rather than re-importing. - All validation queries above require auth. Use `scripts/auth.py` for credential/token acquisition. See `dv-query` for SDK query patterns and `dv-data` for write patterns.