dataverse-prerequisites

name	dataverse-prerequisites
description	Shared prerequisite steps for any skill that interacts with the Dataverse OData Web API. Covers PAC CLI authentication, Azure CLI token acquisition, WhoAmI validation, environment URL extraction, and token refresh patterns. Triggers on "pac auth", "dataverse auth", "dataverse prerequisites", "connect to dataverse", "environment setup", "pac env who", "dataverse token", "azure cli token dataverse".
user-invocable	false

Dataverse Prerequisites

Shared prerequisite steps for all skills that interact with the Dataverse OData Web API (v9.2). Complete these steps before creating tables, inserting records, or making any Dataverse API call.

Used by: dataverse-solution-web-api, power-apps-code-apps, power-pages, and any future skill that needs Dataverse API access.

---

CRITICAL RULES

1. Always verify auth before making API calls. A failed token wastes time debugging 401 errors.
2. Use device code auth for PAC CLI. Run pac auth create --deviceCode to avoid browser profile conflicts.
3. Azure CLI tokens expire after ~60 minutes. Refresh before each major step or every 20 records.
4. Never hardcode tokens or environment URLs. Always extract dynamically from pac env who and az account get-access-token.
5. Confirm the target environment before any destructive operation. Show the environment URL to the user and get explicit confirmation before creating tables, columns, or importing solutions. See the Environment Confirmation step below.
6. Read the safety guardrails before any destructive or bulk operation. See ../dataverse-solution-web-api/resources/safety-guardrails.md for the full irreversible operations table, confirmation protocol, bulk operation safety, and prompt injection protection.

---

Step 0 — Ensure Required Tools Are Installed

Check each tool independently. If any are missing, install them before proceeding.

Tool	Check Command	Install (winget)	Fallback Install
PAC CLI	pac (prints version banner; pac --version is NOT valid)	winget install Microsoft.PowerAppsCLI	dotnet tool install --global Microsoft.PowerApps.CLI.Tool
.NET SDK	dotnet --version	winget install Microsoft.DotNet.SDK.9	https://dotnet.microsoft.com/download
Azure CLI	az --version	winget install Microsoft.AzureCLI	https://aka.ms/installazurecliwindows
Git	git --version	winget install Git.Git	https://git-scm.com/downloads

After any winget install, the tool may not be in PATH until the terminal is restarted.

PAC CLI PATH Discovery (Windows)

If pac is not found after install, check these locations:

# winget install location (most common)
Test-Path "$env:LOCALAPPDATA\Microsoft\PowerAppsCLI\pac.exe"

# dotnet tool install location
Test-Path "$env:USERPROFILE\.dotnet\tools\pac.exe"

Add the found directory to PATH or use the full path in scripts.

---

Step 1 — Check PAC CLI Authentication

Run pac env who to verify the user is authenticated and get the current environment URL:

pac env who

Extract the Environment URL (e.g., https://org12345.crm.dynamics.com). Store as $envUrl.

If pac env who fails: The user needs to authenticate first:

pac auth create --deviceCode

Then select the target environment:

pac env select --environment <environment-id-or-url>

Multi-Environment Safety

Developers often work across multiple environments (dev, test, staging, prod). Never assume the active PAC auth profile is correct for the current task.

• Run pac auth list to show all profiles
• Use pac auth select --name <profile-name> to switch
• Name profiles to reflect the environment (e.g., dev, staging, prod)

---

Step 1b — Confirm Target Environment (MANDATORY)

Before the first operation that touches a specific environment (creating tables, importing solutions, inserting data), you MUST:

1. Show the user the environment URL you intend to use
2. Ask them to confirm: "I'm about to make changes to <URL>. Is this the correct target environment?"
3. Run pac org who to verify the active connection matches

Do not proceed until the user explicitly confirms. This is the single most important safety check — 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 against the same environment.

---

Step 2 — Get Azure CLI Token

Get an access token for the Dataverse environment:

$token = az account get-access-token --resource "$envUrl" --query accessToken -o tsv

If az fails: Tell the user to run az login first.

Build the standard headers for all subsequent API calls:

$headers = @{
  Authorization  = "Bearer $token"
  "Content-Type" = "application/json"
  Accept         = "application/json"
  "OData-MaxVersion" = "4.0"
  "OData-Version" = "4.0"
}

---

Step 3 — Verify API Access

Make a lightweight test request to confirm the token works:

Invoke-RestMethod -Uri "$envUrl/api/data/v9.2/WhoAmI" -Headers $headers

If this returns a valid response with UserId, OrganizationId, and BusinessUnitId, proceed.

If it returns:

• 401 Unauthorized — Token expired or invalid. Re-run Step 2.
• 403 Forbidden — User lacks permissions. Check the user's security roles in the environment.

---

Token Refresh Pattern

Azure CLI tokens expire after ~60 minutes. Refresh before each major operation step or every 20 records:

$token = az account get-access-token --resource "$envUrl" --query accessToken -o tsv
$headers["Authorization"] = "Bearer $token"

---

Extract Publisher Prefix

Before creating any schema, discover the publisher prefix for the target solution:

$solution = Invoke-RestMethod -Uri "$envUrl/api/data/v9.2/solutions?`$filter=uniquename eq '<solution-name>'&`$select=_publisherid_value" -Headers $headers
$publisherId = $solution.value[0]._publisherid_value
$publisher = Invoke-RestMethod -Uri "$envUrl/api/data/v9.2/publishers($publisherId)?`$select=customizationprefix" -Headers $headers
$prefix = $publisher.customizationprefix  # e.g., "cr123"

This prefix is required for all table and column SchemaName values.