Add Server Logic

> Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

Add Server Logic

Create and manage one or more Power Pages Server Logic files — server-side JavaScript that runs securely on the Power Pages runtime, hidden from the browser and protected by web roles and table permissions. Server Logic enables secure external API integrations, Dataverse operations, and custom business logic without exposing sensitive code or credentials to the client.

Core Principles

• 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

Initial request: $ARGUMENTS

---

Workflow

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//
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

---

Phase 1: Verify Site Exists

Goal: Locate the Power Pages project root and confirm prerequisites

Actions:

1. Create todo list with all 11 phases (see [Progress Tracking](#progress-tracking) table)

1.1 Locate Project

Look for powerpages.config.json in the current directory or immediate subdirectories

If not found: Tell the user to create a site first with /create-site.

1.2 Read Existing Config

Read powerpages.config.json to get the site name and configuration:

1.3 Detect Framework

Read package.json to determine the frontend framework (React, Vue, Angular, or Astro). This is needed for Phase 8 (client-side integration guidance). See ${PLUGIN_ROOT}/references/framework-conventions.md for the full framework detection mapping.

1.4 Explore Existing Server Logic and Frontend Code

Use the Explore agent (via Task tool with agent_type: "explore") to analyze the site for existing server logic patterns and frontend code that may call or need to call server logic endpoints.

Prompt for the Explore agent:

> "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."

From the Explore agent's findings, note:

• 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

1.5 Check Deployment Status (Mandatory)

Look for the .powerpages-site folder:

If not found: The site must be deployed before server logic can be created — server logic files live inside .powerpages-site/server-logic/. Tell the user:

> "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?"

> 🚦 Gate (plan · add-server-logic:1.5.deploy-first): .powerpages-site missing — server logic files live inside it. Deploy first or stop. > > Trigger: Phase 1.5 found no .powerpages-site directory. > Why we ask: Server logic .js/.yml files written to a non-existent path won't deploy. > Cancel leaves: Nothing — no server logic files written yet.

Use AskUserQuestion:

| Question | Options | |----------|---------| | The .powerpages-site folder is required for server logic. Would you like to deploy the site now? | Yes, deploy now (Required), Cancel |

If "Yes, deploy now": Invoke /deploy-site first, then continue to Phase 2.

If "Cancel": Stop the workflow — server logic cannot be created without .powerpages-site.

Output: Confirmed project root, .powerpages-site exists, existing server logic (if any), available web roles

---

Phase 2: Understand Requirements

Goal: Determine the user intent, identify whether one or more server logic files are needed, and capture the required HTTP methods for each item

Actions:

2.1 Analyze User Request

From the user's request, determine:

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

Prefer reuse or safe extension of an existing server logic when it already matches the domain, security model, and lifecycle of the requested capability. Only create a new server logic when reuse would make the existing file confusing, over-broad, or unsafe.

Prefer multiple server logic files when the use case naturally separates into different responsibilities, security boundaries, or lifecycle concerns. Examples:

• 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

2.1.1 Identify Validate-and-Execute Patterns

For each planned server logic item, determine whether it should validate-and-execute — meaning the server logic both validates a business rule AND performs the resulting Dataverse write, rather than just returning a validation result for the client to act on.

A server logic item should validate-and-execute when any of these are true:

| Condition | Example | |-----------|---------| | It enforces a state machine or lifecycle | Order status: Draft → Submitted → Approved | | The write is conditional on a business rule that must be tamper-proof | "Only allow bid submission before the deadline" | | The operation spans multiple tables atomically | Award a bid + reject all others + update event status | | The write involves a computed or derived value | Server calculates a score and writes it | | The client should not have direct write access to the field | Status fields with strict transition rules |

For each validate-and-execute item, note:

• 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

Anti-pattern to avoid: A server logic item that only validates and returns { valid: true/false }, expecting the client to make a separate Web API call to perform the write. This allows the client to skip validation and write directly.

2.1.2 Discover Dataverse Custom Actions

If any planned server logic item involves Dataverse operations, check whether the user's Dataverse environment has existing custom actions (Custom APIs or Custom Process Actions) that could be leveraged instead of building logic from scratch.

Step 1 — Fetch custom actions:

node "${PLUGIN_ROOT}/scripts/list-custom-actions.js" ""

The script outputs a JSON object with:

• 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

Each entry includes: name, displayName, description, type (action or function), binding (unbound, entity, or entityCollection), boundEntity, and source (customApi or customProcessAction). Custom APIs also include requestParameters and responseProperties arrays.

Step 2 — Present and ask the user:

If custom actions are found (total > 0), present a summary to the user grouped by binding type (unbound vs. entity-bound) and ask whether any should be used:

> 🚦 Gate (plan · add-server-logic:2.1.2.use-custom-actions): Custom actions discovered — decide whether to wrap existing Dataverse Custom APIs/Process Actions or build server logic from scratch. Choice changes the Phase 5 implementation shape. > > Trigger: list-custom-actions.js returned at least one entry. > Why we ask: Auto-wrapping could attach the wrong action; auto-skipping duplicates logic that already exists in Dataverse. > Cancel leaves: Nothing — no server logic files written yet.

Use AskUserQuestion:

| Question | Options | |----------|---------| | Your Dataverse environment has `` custom action(s). Would you like to use any of these in your server logic instead of writing the logic from scratch? | Yes, let me choose which ones to use; No, build everything from scratch |

Present the list clearly — for each action show: name, description, type (action/function), binding, and bound entity (if applicable). Group them as Unbound and Entity-bound for readability.

If the user says No, skip to Phase 2.2.

Step 3 — Map custom actions to server logic items:

If the user says Yes, for each server logic item being created, ask which custom action (if any) it should wrap:

Use AskUserQuestion for each server logic item:

| Question | Context | |----------|---------| | For the `` endpoint, which custom action should it use? | Present the list of custom actions with their names, descriptions, and binding types. Include "None — build from scratch" as an option. |

Record the mapping for each server logic item. For items that wrap a custom action, note:

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

This mapping will be used in Phase 5.3 when generating the server logic code, and will appear in the HTML plan (Phase 4) to indicate which items wrap existing custom actions.

2.2 Identify SDK Features Needed

Based on each planned server logic item's purpose, identify which Server SDK features are required:

| Feature | When to use | |---------|-------------| | Server.Connector.HttpClient | Calling external REST APIs (NOT Dataverse) | | Server.Connector.Dataverse | Reading/writing Dataverse records (CRUD + InvokeCustomApi for Dataverse Custom APIs) | | Server.Context | Accessing request parameters, headers, body | | Server.User | User-scoped operations, role checks | | Server.Logger | Always — every function should log entry/exit and errors | | Server.Sitesetting | Reading site setting configuration values | | Server.EnvironmentVariable | Reading Dataverse environment variable values directly via Server.EnvironmentVariable.get(name) — an alternative to Server.Sitesetting for non-secret config | | Server.Website | Accessing site metadata |

2.3 Identify Secret Values

Determine whether any server logic item requires secret or sensitive configuration values that should not be hardcoded. Common examples:

| Scenario | Secret needed | |----------|---------------| | Calling an authenticated external API | API key, client secret, bearer token | | Connecting to a third-party service | Connection string, access token | | OAuth2 client credentials flow | Client ID + client secret | | Webhook verification | Signing secret, shared key |

For each identified secret, capture:

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

These values will be used in Phase 7 to create the environment variables and site settings.

2.3.1 Key Vault Decision

If secrets were identified in Phase 2.3, ask the user now whether they want to use Azure Key Vault. This decision must happen before Phase 4 so the implementation plan can show the chosen secret management approach.

> 🚦 Gate (plan · add-server-logic:2.3.1.keyvault): Pick secret-storage mechanism (Key Vault

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/power-platform-skills
• License: MIT
• Homepage: https://aka.ms/ppskills

Install and usage instructions live in the source repository linked above.