Plugin check: Run

node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js"

— if it outputs a message, show it to the user before proceeding.

• Microsoft Learn is the source of truth: Always fetch the latest documentation before writing code. The Server Logic feature is in preview and the SDK may change — never rely on cached knowledge alone.
• No browser APIs, no dependencies: Server Logic runs in a sandboxed server environment with ECMAScript 2023 support. There is no

  fetch

  ,

  XMLHttpRequest

  ,

  setTimeout

  , or any DOM API. No npm packages are available.
• Five functions only: A server logic file can only export these top-level functions:

  get

  ,

  post

  ,

  put

  ,

  patch

  ,

  del

  . The name

  delete

  is a reserved word in JavaScript and cannot be used.
• Always return a string: Every function must return a string. Use

  JSON.stringify()

  when returning objects or arrays.
• Use TaskCreate/TaskUpdate: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.

Prerequisites:

• An existing Power Pages code site created
• The site must be deployed at least once (

  .powerpages-site

  folder must exist) — server logic files live inside

  .powerpages-site/server-logic/

  , so deployment is required before any server logic can be created

1. Verify Site Exists — Locate the Power Pages project, explore existing patterns, and verify prerequisites
2. Understand Requirements — Determine the user intent and whether the solution needs one or more server logic files
3. Fetch Latest Documentation — Query Microsoft Learn for the most current Server Logic SDK reference
4. Review Implementation Plan — Present the plan to the user and confirm before writing code
5. Implement Server Logic — Create the approved

   .js

   and

   .serverlogic.yml

   files in

   .powerpages-site/server-logic/<name>/

6. Configure Table Permissions — (Conditional: only if Server.Connector.Dataverse is used) Set up table permissions for Dataverse tables accessed by the server logic
7. Manage Secrets & Environment Variables — (Conditional: only if the server logic requires secrets) Store sensitive values securely using Azure Key Vault (recommended) or direct environment variables in Dataverse
8. Configure Site Settings — Set up ServerLogic site settings if needed
9. Client-Side Integration — Help wire the server logic into the site's frontend code
10. Verify & Test Guidance — Validate the code and provide testing instructions
11. Review & Deploy — Present summary and offer deployment

1. Create todo list with all 11 phases (see Progress Tracking table)

Task

agent_type: "explore"

"Analyze this Power Pages code site for server logic context. Check:

1. Does

   .powerpages-site/server-logic/

   exist? If yes, list all subdirectories and their .js files. Summarize what each server logic does (which functions it implements, what SDK features it uses). Also read the corresponding .serverlogic.yml files to check web role assignments.
2. Search the frontend source code (

   src/**/*.{ts,tsx,js,jsx,vue,astro}

   ) for any existing calls to

   /_api/serverlogics/

   — these indicate server logic endpoints already being consumed.
3. Look for CSRF token handling patterns (

   __RequestVerificationToken

   ,

   _layout/tokenhtml

   ) — these show how the site currently makes authenticated API calls.
4. Check for any TODO/FIXME comments mentioning server logic, backend, or server-side processing.
5. Look for hardcoded API URLs, mock data, or placeholder fetch calls that might need to be replaced with server logic calls.
6. Check for any existing service layer or API utility files in

   src/shared/

   ,

   src/services/

   , or similar directories that could be reused for server logic integration.
7. Read

   .powerpages-site/web-roles/*.webrole.yml

   files to list available web roles and their GUIDs — these are needed when creating the server logic metadata YAML.
8. For each existing server logic, assess whether it can be reused or safely extended for the requested capability instead of creating a brand-new server logic file. Call out any strong reuse candidates and explain why. Report all findings so we can avoid duplicating work and match existing patterns."

• Existing server logic files — what's already implemented, and which ones are candidates for reuse or extension
• Frontend calling patterns — how the site makes API calls (match this pattern in Phase 9)
• Existing service/utility files — reuse these when adding client-side integration
• Gaps — frontend code that references server logic endpoints that don't exist yet

.powerpages-site

.powerpages-site/server-logic/

"The

.powerpages-site

folder was not found. Server logic files are stored inside this folder, so the site must be deployed at least once before creating server logic. Would you like to deploy now?"

AskUserQuestion

.powerpages-site

/deploy-site

.powerpages-site

.powerpages-site

• Intent shape: Does the request map to a single server logic or multiple server logic?
• Reuse opportunities: Can an existing server logic satisfy or be safely extended for part of the request?
• Server logic inventory: For each required server logic, capture the purpose, suggested endpoint name, and whether it should be reused, extended, or created new
• HTTP methods needed: Which of the 5 functions should be implemented for each server logic (

  get

  ,

  post

  ,

  put

  ,

  patch

  ,

  del

  )

• Separate read vs. write workflows with different web role requirements
• Distinct integrations with different external systems or site settings
• Independent business capabilities that would be harder to test or reason about if merged into one endpoint

• Which Dataverse writes the server logic will perform (UpdateRecord, CreateRecord, etc.)
• Which fields are being written — these fields should NOT be writable via Web API from the client
• What the server logic returns to the client — typically a success/failure result with the before/after state, NOT a validation flag that the client acts on

{ valid: true/false }

node "${CLAUDE_PLUGIN_ROOT}/scripts/list-custom-actions.js" "<ENV_URL>"

• customApis

  — Modern Custom APIs with full request parameters and response properties

• customProcessActions

  — Legacy Custom Process Actions (activated only)

• total

  — Total count of both types combined

name

displayName

description

type

action

function

binding

unbound

entity

entityCollection

boundEntity

source

customApi

customProcessAction

requestParameters

responseProperties

total > 0

AskUserQuestion

<total>

AskUserQuestion

<server-logic-name>

• The custom action name (used in the

  InvokeCustomApi

  call)
• Whether it's a function (

  GET

  ) or action (

  POST

  )
• The binding type and bound entity (if applicable)
• The request parameters and response properties (if available from Custom APIs)

• Secret name: A descriptive name (e.g.,

  ExchangeRateApiKey

  ,

  PaymentGatewaySecret

  )
• Purpose: Why the secret is needed
• Site setting name: The name the server logic will use with

  Server.Sitesetting.Get()

  (e.g.,

  ExternalApi/ExchangeRateApiKey

  )
• Environment variable schema name: The Dataverse environment variable schema name (e.g.,

  cr5b4_ExchangeRateApiKey

  )

Reference:

${CLAUDE_PLUGIN_ROOT}/skills/add-server-logic/references/server-logic-docs.md

• Search Microsoft Learn dynamically for all current Server Logic docs
• Fetch the core reference pages and any relevant scenario-specific pages
• Search for current code samples
• Reconcile the discovered documentation with the known SDK baseline in the reference

• All SDK method signatures, parameter types, and return types
• Current supported HTTP methods and function signatures
• Site settings and their defaults
• Security model (web roles, table permissions, CSRF)
• Client-side calling patterns and response format
• Any new methods or breaking changes discovered in Microsoft Learn

Reference:

${CLAUDE_PLUGIN_ROOT}/skills/add-server-logic/references/server-logic-plan-data-format.md

• The number of server logic items being created or reused
• Each endpoint name, API URL, and files to be created
• The functions that will be implemented and what each one does
• The SDK features, external services, and Dataverse tables involved for each item
• The web roles, security constraints, and site settings that apply to each item
• Any secrets or sensitive values that will be stored as environment variables (with or without Azure Key Vault). If the user chose Azure Key Vault in Phase 2.3.1, populate

  SECRETS_DATA

  with

  useKeyVault: true

  and the list of secrets — the HTML plan will render a Key Vault banner explaining the security benefits and show which secrets each server logic depends on. If no secrets are needed, set

  SECRETS_DATA

  to

  null

  .
• The expected next steps after approval

• Total server logic count
• Whether the plan is creating, updating, or reusing items
• Whether web roles, table permissions, or site settings are involved
• The actual output path returned by the render script
• A note that the browser-opened HTML contains the full details

• If the approved plan says

  reuse

  : Do not create a new folder. Reuse the existing server logic as-is and only update the surrounding integration work if needed.
• If the approved plan says

  update

  / extend: Reuse the existing folder and update the existing

  .js

  /

  .serverlogic.yml

  files rather than creating duplicates.
• If the approved plan says

  create

  : Create the folder inside

  .powerpages-site/server-logic/

  (note: singular

  server-logic

  , no trailing 's'). Ensure the folder name matches that endpoint name exactly.

adx_anonymoususersrole: false
adx_authenticatedusersrole: true
description: Role for authenticated users
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: Authenticated Users

• The site has no suitable existing web roles
• The approved plan includes proposed roles that do not exist yet
• The role assignments need to be refined before metadata can be created

id

name

1. Only top-level functions: The file can only contain these 5 functions at the top level:

   get

   ,

   post

   ,

   put

   ,

   patch

   ,

   del

   . Only include the functions the user needs.
2. Each function returns a string: Use

   JSON.stringify()

   for objects/arrays.
3. Each function has try/catch: Every function must wrap its logic in a try/catch block.
4. Each function logs: Use

   Server.Logger.Log()

   at entry and

   Server.Logger.Error()

   in catch blocks.
5. No imports or requires: No

   import

   ,

   require

   , or external dependencies.
6. No browser APIs: No

   fetch

   ,

   XMLHttpRequest

   ,

   setTimeout

   ,

   setInterval

   ,

   console.log

   , or DOM APIs.
7. Async when needed: Mark functions as

   async

   only when they use

   await

   (HttpClient calls). Dataverse connector methods (

   Server.Connector.Dataverse.*

   ) are synchronous — do NOT use

   async

   /

   await

   with them.

// Server Logic: <name>
// Purpose: Validate and execute <describe the operation>
// Pattern: Validate-and-execute — this endpoint both validates the business rule
//          and performs the Dataverse write. The client should NOT write <protected fields>
//          via Web API — all writes to those fields go through this endpoint.
// API URL: https://<site-url>/_api/serverlogics/<name>

function post() {
    try {
        Server.Logger.Log("<name> POST called");

        const body = JSON.parse(Server.Context.Body);
        const entityId = body.entityId;
        const targetStatus = body.targetStatus;

        // 1. Read the current record from Dataverse
        const current = Server.Connector.Dataverse.RetrieveRecord("<table-name>", entityId, "?$select=<status-field>");
        const currentStatus = current["<status-field>"];

        // 2. Validate the transition
        const allowedTransitions = {
            "Draft": ["Submitted"],
            "Submitted": ["Approved", "Rejected"],
            "Approved": ["Fulfilled"]
        };

        const allowed = allowedTransitions[currentStatus] || [];
        if (!allowed.includes(targetStatus)) {
            return JSON.stringify({
                status: "error",
                message: "Invalid transition: " + currentStatus + " → " + targetStatus + " is not allowed",
                currentStatus: currentStatus,
                targetStatus: targetStatus,
                allowedTargets: allowed
            });
        }

        // 3. Execute the write — server performs the Dataverse update
        const updateData = {};
        updateData["<status-field>"] = targetStatus;
        Server.Connector.Dataverse.UpdateRecord("<table-name>", entityId, JSON.stringify(updateData));

        Server.Logger.Log("<name> transition executed: " + currentStatus + " → " + targetStatus);

        // 4. Return the result — client receives confirmation, not a validation flag
        return JSON.stringify({
            status: "success",
            previousStatus: currentStatus,
            newStatus: targetStatus,
            entityId: entityId
        });
    } catch (err) {
        Server.Logger.Error("<name> POST failed: " + err.message);
        return JSON.stringify({
            status: "error",
            message: err.message
        });
    }
}

1. The server logic reads the current state from Dataverse (not trusting the client's view)
2. It validates the business rule server-side
3. It writes the result to Dataverse via

   Server.Connector.Dataverse.UpdateRecord

4. It returns a success/failure result — NOT a

   { valid: true/false }

   flag for the client to act on
5. The client calls this one endpoint — it does NOT make a separate Web API PATCH call

Server.Connector.Dataverse.InvokeCustomApi

/_api/serverlogics/<name>

// Server Logic: <name>
// Purpose: Wraps Dataverse custom action "<custom-action-name>" for portal consumption
// Custom Action: <custom-action-name> (unbound, action)
// API URL: https://<site-url>/_api/serverlogics/<name>

function post() {
    try {
        Server.Logger.Log("<name> POST called — invoking custom action <custom-action-name>");

        const body = JSON.parse(Server.Context.Body);

        // Build the request payload matching the custom action's input parameters
        const payload = JSON.stringify({
            // "<ParameterName>": body.<clientFieldName>
        });

        const result = Server.Connector.Dataverse.InvokeCustomApi(
            "POST",
            "<custom-action-name>",
            payload
        );

        Server.Logger.Log("<name> custom action completed successfully");

        return JSON.stringify({
            status: "success",
            data: result
        });
    } catch (err) {
        Server.Logger.Error("<name> POST failed: " + err.message);
        return JSON.stringify({
            status: "error",
            message: err.message
        });
    }
}

function post() {
    try {
        Server.Logger.Log("<name> POST called — invoking bound action <custom-action-name>");

        const body = JSON.parse(Server.Context.Body);
        const entityId = body.entityId;

        const payload = JSON.stringify({
            // "<ParameterName>": body.<clientFieldName>
        });

        // Include the entity set and record ID, followed by the fully qualified action name
        const result = Server.Connector.Dataverse.InvokeCustomApi(
            "POST",
            "<entity-set-name>(" + entityId + ")/Microsoft.Dynamics.CRM.<custom-action-name>",
            payload
        );

        Server.Logger.Log("<name> bound action completed for entity " + entityId);

        return JSON.stringify({
            status: "success",
            data: result,
            entityId: entityId
        });
    } catch (err) {
        Server.Logger.Error("<name> POST failed: " + err.message);
        return JSON.stringify({
            status: "error",
            message: err.message
        });
    }
}

function get() {
    try {
        Server.Logger.Log("<name> GET called — invoking custom function <custom-function-name>");

        // Pass parameters as query string for functions
        const param1 = Server.Context.QueryParameters["param1"];
        const queryString = "<custom-function-name>(Param1='" + param1 + "')";

        const result = Server.Connector.Dataverse.InvokeCustomApi(
            "GET",
            queryString,
            null
        );

        Server.Logger.Log("<name> custom function completed successfully");

        return JSON.stringify({
            status: "success",
            data: result
        });
    } catch (err) {
        Server.Logger.Error("<name> GET failed: " + err.message);
        return JSON.stringify({
            status: "error",
            message: err.message
        });
    }
}

• Unbound actions: Use the action name as the URL, pass parameters as JSON body
• Entity-bound actions: Include the entity set and record ID in the URL path, followed by

  Microsoft.Dynamics.CRM.<action-name>

• Functions (GET): Use

  "GET"

  as the HTTP method and pass parameters inline in the URL using OData function call syntax
• Actions (POST): Use

  "POST"

  as the HTTP method and pass parameters as JSON body payload

• InvokeCustomApi

  is synchronous — do NOT use

  async

  /

  await

• The server logic can add additional validation, transformation, or logging around the custom action call — it doesn't have to be a pass-through
• When Custom API response properties are known (from Phase 2.1.2), map them to the response object for clarity

create

update

reuse

node "${CLAUDE_PLUGIN_ROOT}/skills/add-server-logic/scripts/create-serverlogic-metadata.js" --projectRoot "<PROJECT_ROOT>" --name "<name>" --displayName "<human-readable display name>" --description "<description of what this server logic does>" --webRoleIds "<uuid1,uuid2,uuid3>"

<PROJECT_ROOT>/.powerpages-site/server-logic/<name>/<name>.serverlogic.yml

adx_serverlogic_adx_webrole:
  - <web-role-guid-1>
  - <web-role-guid-2>
  - <web-role-guid-3>
description: <description of what this server logic does>
display_name: <human-readable display name>
id: <generated-uuid>
name: <name>

• id

  field is mandatory — The script generates a new UUID (v4). PAC CLI crashes with

  Expected Guid for primary key 'id'

  if this is missing.

• adx_serverlogic_adx_webrole

  — Array of web role GUIDs from step 5.2. Include only the roles required for that server logic item.

• name

  — Must match the folder name and

  .js

  file name (the URL-friendly name used in

  /_api/serverlogics/<name>

  ).

• display_name

  — Human-readable name (e.g., "Exchange Rate API", "Order Processor").
• Alphabetical field ordering — Fields must be sorted alphabetically:

  adx_serverlogic_adx_webrole

  ,

  description

  ,

  display_name

  ,

  id

  ,

  name

  .

Server.Connector.Dataverse

table-permissions-architect

${CLAUDE_PLUGIN_ROOT}/agents/table-permissions-architect.md

"Analyze this Power Pages code site and propose table permissions for Dataverse tables accessed by the approved server logic plan. The following tables need permissions:

[list each table with required CRUD privileges from step 6.1, grouped by server logic item]

Context:

• These permissions are needed because the server logic uses

  Server.Connector.Dataverse

  , which respects table permissions — without them, the connector silently returns 0 records.
• The scope should typically be Global for server logic that fetches all records, unless the server logic filters by the current user (in which case use Contact scope).
• The web roles assigned to these server logic items are: [list web role names and GUIDs from Phase 5.2]
• Project root: [path]

Check for existing table permissions and web roles. If new web roles are needed, create them using the create-web-role.js script. Propose a plan, then after approval create the table permission YAML files using the deterministic scripts."

1. Discover existing table permissions and web roles
2. Create any missing web roles via

   create-web-role.js

   if needed
3. Propose a table permissions plan (with HTML visualization)
4. Present the plan via plan mode for user approval
5. After approval, create table permission YAML files in

   .powerpages-site/table-permissions/

   using

   create-table-permission.js

node "${CLAUDE_PLUGIN_ROOT}/scripts/create-environment-variable.js" "<ENV_URL>" \
  --schemaName "<prefix_SecretName>" \
  --displayName "<Secret Display Name>" \
  --value "PLACEHOLDER_SET_ACTUAL_VALUE"

node "${CLAUDE_PLUGIN_ROOT}/scripts/create-site-setting.js" \
  --projectRoot "<PROJECT_ROOT>" \
  --name "<SiteSetting/Name>" \
  --envVarSchema "<schemaName-from-step-1>"

1. Power Apps maker portal (make.powerapps.com) — Go to Solutions → Default Solution → Environment variables → find the variable by display name → update the value

• Confirm each site setting YAML was created in

  .powerpages-site/site-settings/

• Verify each YAML contains

  envvar_schema

  and

  source: 1

• Confirm the server logic code references the correct site setting names via

  Server.Sitesetting.Get("<SiteSetting/Name>")

Reference:

${CLAUDE_PLUGIN_ROOT}/skills/add-server-logic/references/frontend-integration-reference.md

• Reuse the existing service layer or API utility when the site already has one
• Create a lightweight CSRF-aware helper only when the site has no established API client pattern
• Group multiple server logic endpoints into a coherent service module when that improves maintainability
• Add framework-specific hooks/composables/services only when the codebase already follows that pattern
• Fully integrate the server logic into the actual UI flow — do not stop at creating service/helper code
• Update the relevant pages, components, forms, buttons, or user journeys so the new backend behavior is reachable from the interface
• Replace placeholder data, mock handlers, or temporary actions when they are meant to be backed by the new server logic endpoints
• Add or preserve loading, success, empty, and error states so the UI behaves like a finished feature
• For validate-and-execute endpoints: The frontend must call the server logic endpoint for the protected operation (e.g., status transition) — it must NOT make a separate Web API PATCH for the same field. Ensure the UI for that operation (e.g., a "Submit" or "Approve" button) calls the server logic service function, not the Web API service

.js

• Only allowed top-level functions (get, post, put, patch, del)
• Every function returns a string
• try/catch in every function
• Server.Logger calls in every function
• No

  import

  ,

  require

  , or external dependencies
• No browser APIs (

  fetch

  ,

  XMLHttpRequest

  ,

  setTimeout

  ,

  console.log

  ,

  document

  ,

  window

  )
• Async only on functions that use await
• Correct SDK method usage (verified against Phase 3 documentation)
• HttpClient used only for external APIs (not Dataverse)
• Dataverse connector used for Dataverse operations

.serverlogic.yml

• id

  field exists and is a valid UUID

• adx_serverlogic_adx_webrole

  array is non-empty (at least one web role)

• name

  matches the folder name and

  .js

  file name

• display_name

  and

  description

  are populated
• Fields are alphabetically sorted
• File names match: folder name,

  .js

  name,

  .serverlogic.yml

  name, and

  name

  field all use the same value