Integrate Backend

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

Backend Integration

Analyze the user's business problem and recommend the right backend integration approach — Web API, AI Web API, Server Logic, Cloud Flows, or a combination — then route to the appropriate skill(s) to implement the solution.

Core Principles

• Understand the problem first: Never jump to a technology choice. Analyze the user's intent, data flow, security needs, and performance requirements before recommending.
• Recommend the simplest approach that works: Web API for straightforward Dataverse CRUD, AI Web API for generative summaries or grounded search over existing data, Server Logic when server-side processing is needed, Cloud Flows for async background work. Don't over-engineer.
• Secure actions belong on the server: When a write depends on a business rule that must be tamper-proof (state transitions, approval workflows, computed values), the server logic must validate AND execute the write — not just validate and leave the write to a client-side Web API call. See the Secure Action Principle in the decision framework.
• AI Web API sits on top of Web API: The Data Summarization and Case-preset endpoints read through the same _api layer as regular Web API, so they inherit the same table permissions, column permissions, and Webapi/<table>/* site settings. When a plan has both a Web API item and an AI Web API item for the same table, the AI item depends on (and goes in a later phase than) the Web API item. Search Summary has no per-table prereqs and can stand alone.
• Combinations are normal: Many real scenarios need more than one approach. Recommend combinations when justified, but explain why each piece is needed.
• Route, don't implement: This skill recommends and invokes the right skill(s). It does not create backend files itself.

Initial request: $ARGUMENTS

---

Workflow

1. Verify Site Exists — Locate the Power Pages project and check prerequisites 2. Understand the Business Problem — Analyze what the user needs and why 3. Recommend Integration Approach — Present the recommendation with reasoning 4. Route to Skill(s) — Invoke the appropriate backend skill(s) to implement

---

Phase 1: Verify Site Exists

Goal: Locate the Power Pages project root and confirm prerequisites

Actions:

1. Create todo list with all 4 phases (see 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 Explore Current State

Use the Explore agent to quickly scan the site for existing backend integrations:

"Analyze this Power Pages code site for existing backend integrations:

1. Check .powerpages-site/server-logic/ — list any existing server logic endpoints

2. Check .powerpages-site/cloud-flow-consumer/ — list any registered cloud flows

3. Search frontend code (src/**/*.{ts,tsx,js,jsx,vue,astro}) for calls to /_api/ (Web API) and /_api/serverlogics/ (Server Logic) and /_api/cloudflow/ (Cloud Flows)

4. Check for existing service layers or API utilities in src/services/, src/shared/, or similar

5. List available web roles from .powerpages-site/web-roles/*.webrole.yml

Report what backend integrations already exist so we can build on them."

1.3 Discover Dataverse Custom Actions

Check whether the user's Dataverse environment has existing custom actions that could be leveraged in the integration:

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

The script returns Custom APIs (modern) and Custom Process Actions (legacy) with their names, descriptions, binding types, and parameters. If custom actions are found, note them — they will be factored into the recommendation in Phase 3.

Output: Project root confirmed, existing backend integrations identified, Dataverse custom actions discovered

---

Phase 2: Understand the Business Problem

Goal: Analyze the user's request to understand the underlying business problem, not just the technical ask

Actions:

2.1 Analyze the Request

From the user's request and the existing site state, determine:

• What is the user trying to accomplish? (business outcome, not technology)
• What data is involved? (Dataverse tables, external systems, user input)
• Who triggers the operation? (user action, form submit, page load, scheduled)
• Does the user need an immediate response? (real-time UI update vs. background processing)
• Are external services involved? (payment gateways, email, Graph, SharePoint, third-party APIs)
• Are credentials or secrets involved? (API keys, client secrets, tokens)
• Must logic be hidden from the browser? (pricing rules, validation algorithms, business rules)
• Is this a simple data operation or complex business logic? (CRUD vs. multi-step processing)
• Does any write depend on a business rule that must be tamper-proof? (state transitions, approval conditions, computed values) — if yes, the server logic must validate AND execute the write, not just validate
• Does the UI want an AI-generated summary, grounded AI search, or related-record discovery? (e.g., "summarize this case", "summarize open orders", "suggest KB articles on the case page", "AI-powered search") — if yes, AI Web API is the right fit. Watch for the phrasing signals: summarize, summary of, Copilot, related / similar / suggested <entity>, AI search, semantic search.
• Can existing Dataverse custom actions handle part of the requirement? If custom actions were discovered in Phase 1.3, check whether any align with the user's needs — server logic can wrap existing custom actions via InvokeCustomApi instead of building equivalent logic from scratch

2.2 Clarify if Ambiguous

<!-- not-a-gate: ambiguous-intent clarification — sub-prompts under the upcoming Phase 3.4 plan gate; multi-question data-gathering that shapes the recommendation -->

If the request could map to multiple approaches and the right choice isn't clear, use AskUserQuestion to clarify:

Output: Clear understanding of the business problem and technical requirements

---

Phase 3: Recommend Integration Approach

Goal: Present a recommendation with clear reasoning

Actions:

3.1 Apply the Decision Framework

Reference: ${PLUGIN_ROOT}/skills/integrate-backend/references/decision-framework.md

Use the decision matrix, intent mapping, and Secure Action Principle from the reference to determine the right approach. Consider:

1. Can Web API alone handle this? If it's straightforward Dataverse CRUD with no external calls, no secrets, no server-side logic, and no business rules governing the write — recommend Web API. It's the simplest option.

2. Does it need AI Web API? If any of these apply, AI Web API is the right fit:

• The UI wants an AI-generated summary of a record on its detail page (e.g., "summarize this case", "Copilot summary")
• The UI wants an AI summary of a list or collection (e.g., "summarize open orders", "highlight trends in this week's cases")
• A detail page wants related-record discovery (e.g., "suggest KB articles for this case", "similar products", "similar cases") — Search Summary's grounded retrieval is a better fit than a hand-rolled OData keyword match
• The site wants AI-grounded search with citations, replacing or augmenting keyword-only search

AI Web API is read-only — the Secure Action Principle does not apply. If an AI item covers a Dataverse table that is also covered by a Web API item, put the AI item in a later phase (it depends on the Web API Layer 1/2 prereqs being in place). Search Summary items have no per-table prereqs and can stand alone.

3. Does it need Server Logic? If any of these apply, Server Logic is needed:

• External API calls (HttpClient)
• Credentials/secrets must stay on the server
• Business logic must be hidden from the browser
• Multiple Dataverse queries should be batched into one endpoint
• Server-side validation that can't be bypassed
• Wrapping a Dataverse Custom API/Action for portal consumption — if custom actions were found in Phase 1.3, check whether any match the requirement before recommending building from scratch
• The write depends on a business rule that must be tamper-proof (state transitions, approval conditions, computed values) — server logic must validate AND execute the write

4. Does it need Cloud Flows? If any of these apply, Cloud Flows are the right fit:

• The operation is async — the user doesn't need an immediate result
• Background processing: sending emails, notifications, processing orders
• Multi-step workflows across systems with Power Automate connectors
• Long-running processes that exceed the 120-second server logic timeout
• Non-developers should be able to modify the workflow

5. Does it need a combination? Common combinations:

• Web API + AI Web API: UI displays raw Dataverse records and an AI summary of the same data (most common AI pattern — dashboards, case/order detail pages)
• Web API + Cloud Flow: UI reads/writes non-sensitive Dataverse fields, some actions trigger background flows
• Server Logic + Cloud Flow: Real-time endpoint validates and executes the action, async flow does follow-up (e.g., server logic transitions status, Cloud Flow sends notification)
• Web API + Server Logic: Web API for safe direct reads/writes, server logic for operations that need business rule enforcement (server logic validates AND writes for those operations)
• Web API + AI Web API + Cloud Flow: support portal with browsable cases, Copilot summary + KB discovery, and async notifications

3.1.1 Security Review — Apply the Secure Action Principle

Before finalizing the plan, review every item assigned to Web API and ask: "If a user skipped any preceding server logic validation and called this Web API endpoint directly, could they violate a business rule?"

If the answer is yes, that write does not belong in a Web API item. Move the write into the server logic item that validates it. The server logic should validate AND execute the write using Server.Connector.Dataverse.

Common patterns that must use validate-and-execute server logic (not Web API):

Correct plan structure for state transitions:

Phase 1: Server Logic — "transition-order" endpoint
  - POST: accepts { entityId, targetStatus }
  - Reads current record, validates transition is allowed, writes new status
  - Returns { success, previousStatus, newStatus }

Phase 2: Web API — Order table CRUD
  - Read: list/filter orders (safe for Web API)
  - Create: new orders in Draft status (safe — initial state, no rule to enforce)
  - Update: description, notes, dates (safe — no business rules on these fields)
  - NOTE: Status changes are NOT here — they go through the server logic endpoint

Incorrect plan structure (anti-pattern):

❌ Phase 1: Server Logic — "validate-transition" endpoint
  - POST: accepts { entityId, targetStatus }
  - Reads current record, validates transition
  - Returns { valid: true/false }   ← only validates, doesn't write

❌ Phase 2: Web API — Order table CRUD
  - Update: includes status field  ← client writes status after "validation"
  - PROBLEM: client can skip Phase 1 and write any status directly

3.2 Render the HTML Plan

Build the plan data and render an HTML plan before asking for approval. The plan visualizes:

• Key Concepts — Educational overview of Web API, Server Logic, and Cloud Flows (hardcoded in template)
• Overview — Stats per approach, approach chips, design rationale
• Data Flow — Visual flow diagrams showing how data moves for each user action, with steps color-coded by approach
• Implementation Order — Phase-grouped items with dependencies, complexity badges, and implementation commands
• Integration Items — Each item with its approach, reasoning, and implementation details

Prepare a JSON object with these keys:

ITEMS_DATA format:

{
  "name": "Create PayPal Order",
  "approach": "webapi|aiwebapi|serverlogic|cloudflow",
  "description": "What this item does",
  "reasoning": "Why this approach was chosen",
  "phase": 1,
  "status": "new|existing|extends",
  "complexity": "low|medium|high",
  "depends": "Name of item this depends on (if any)",
  "details": [
    { "label": "Endpoint", "value": "/_api/serverlogics/create-paypal-order" },
    { "label": "Secrets", "value": "PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET" }
  ],
  "docs": [
    { "label": "Server Logic Overview", "url": "https://learn.microsoft.com/..." }
  ]
}

Phase assignment rules — assign a phase number to each item based on dependencies:

1. Items with no dependencies go in the earliest phase appropriate for their approach 2. Items that depend on other items go in a later phase than their dependency 3. Items in the same phase have no dependencies on each other and can be built in parallel 4. Recommended default ordering: Server Logic foundations first (validate-and-execute endpoints for state transitions, batch queries), then Web API CRUD for non-sensitive fields (reads, creates with safe defaults, updates to fields with no business rules), then advanced Server Logic (multi-table transactions), then AI Web API for summaries/grounded search over the tables set up by Web API, then Cloud Flows (async follow-ups) 5. Security constraint: A Web API item must never write a field whose value is governed by a business rule enforced in a server logic item. If a field needs validation, the server logic item should write it directly — the Web API item should exclude that field from its scope 6. AI layering constraint: An AI Web API item for a Dataverse table that is also covered by a Web API item must be in a later phase than the Web API item — AI Web API's Data Summarization endpoint reuses the Web API's Layer 1/2 prereqs (table permissions, Webapi/<table>/* site settings). Search Summary items have no per-table prereqs and can go in any phase.

DATA_FLOWS_DATA format (each step's approach is one of webapi, aiwebapi, serverlogic, cloudflow):

{
  "trigger": "User registers and pays",
  "description": "User fills the form, pays via PayPal, receives confirmation",
  "steps": [
    { "approach": "serverlogic", "name": "Validate Seats", "detail": "Check availability" },
    { "approach": "serverlogic", "name": "Create Order", "detail": "Server calls PayPal" },
    { "approach": "cloudflow", "name": "Send Email", "detail": "Async confirmation" }
  ]
}

Important: In data flow diagrams, when a server logic step validates a business rule, the next step should NOT be a Web API write for the same field. The server logic step should validate AND execute. For example:

// ✅ Correct — server logic validates and writes status
{ "approach": "serverlogic", "name": "Submit Order", "detail": "Validates Draft→Submitted, writes new status" }

// ❌ Incorrect — split across server logic validation and Web API write
{ "approach": "serverlogic", "name": "Validate Transition", "detail": "Checks Draft→Submitted" },
{ "approach": "webapi", "name": "Update Status", "detail": "PATCH status to Submitted" }

Write the plan to <PROJECT_ROOT>/docs/backend-plan.html (create docs/ if needed). Use the render script:

node "${PLUGIN_ROOT}/scripts/render-backend-plan.js" --output "<OUTPUT_PATH>" --data "<DATA_JSON_PATH>"

The render script refuses to overwrite existing files. If the default path exists, choose a new descriptive filename (e.g., backend-plan-payments.html).

After rendering, open the HTML plan in the user's default browser:

open "<OUTPUT_PATH>"  # macOS
# start "<OUTPUT_PATH>"  # Windows
# xdg-open "<OUTPUT_PATH>"  # Linux

3.3 Present Plan Summary

Do not restate the full plan in the CLI. The HTML file is the single detailed plan artifact.

In the CLI, give only a brief summary:

• Total items and how many per approach
• Whether the plan uses one approach or a combination
• The actual output path
• A note that the browser-opened HTML contains the full details including data flow diagrams

3.4 Confirm with User

<!-- gate: integrate-backend:3.4.plan-approval | category=plan | cancel-leaves=nothing -->

🚦 Gate (plan · integrate-backend:3.4.plan-approval): Approve the integration plan before invoking the appropriate child skill (integrate-webapi / add-server-logic / add-cloud-flow). The plan HTML stays on disk regardless of choice — Cancel just stops the dispatch.

>

Trigger: Phase 3.3 has rendered the HTML plan and surfaced a brief CLI summary.

Why we ask: Wrong child skill gets dispatched — add-server-logic for a Web API task wastes minutes; add-cloud-flow for a Web API task creates orphaned flow YAML.

Cancel leaves: Nothing — no child skill invoked, HTML plan stays at its saved path.

Use AskUserQuestion:

If "Change approach": Ask what they'd prefer and why, update the plan, and present again.

If "Cancel": Stop the workflow.

Output: User-approved integration approach

---

Phase 4: Route to Skill(s)

Goal: Invoke the appropriate skill(s) to implement the approved approach, respecting phase ordering and building in parallel within each phase

Actions:

4.1 Build the Phase Execution Plan

Group the approved items by their phase number from the plan. Each phase is a batch of independent items — items within a phase have no dependencies on each other and can be built in parallel.

4.2 Execute Phase by Phase

Process phases in order (Phase 1, then Phase 2, etc.). Complete all items in a phase before moving to the next — later phases depend on earlier phases.

Within each phase, maximize parallelism:

• Single approach in the phase: Invoke the skill once with all items for that phase. Tell the skill: "These N items are independent — implement them in parallel where possible."
• Multiple approaches in the same phase: Invoke each skill for its items. Since items in the same phase have no cross-dependencies, the order of skill invocation within a phase does not matter. When invoking the second skill, pass context from the first so it can follow the same frontend patterns (e.g., naming conventions, file organization).

Example — a plan with 4 phases:

When invoking each skill, include: 1. Which items to implement — list the specific item names from the plan for this phase 2. Parallelism guidance — "These items are in the same phase and have no dependencies on each other. Implement them in parallel where possible." 3. Context from previous phases — what was created so far (files, patterns, services) so the skill can build on it

4.3 Summary

After all phases complete, present a brief summary of everything that was created:

Remind the user to deploy with /deploy-site if they haven't already.

4.4 Record Skill Usage

Reference: ${PLUGIN_ROOT}/references/skill-tracking-reference.md

Follow the skill tracking instructions in the reference to record this skill's usage. Use --skillName "IntegrateBackend".

Output: All recommended backend integrations implemented

---

Important Notes

When NOT to Use This Skill

If the user's request clearly and unambiguously maps to a single approach, skip this skill and go directly to the implementation skill:

• "Create a server logic endpoint for..." → /add-server-logic
• "Integrate Web API for the contacts table" → /integrate-webapi
• "Add a cloud flow for sending emails" → /add-cloud-flow
• "Add an AI summary to the case detail page" / "summarize open cases" / "suggest KB articles on this page" → /add-ai-webapi

This skill is for ambiguous requests where the user describes a business problem and needs help choosing the right approach.

Examples: What Routing Looks Like

Example 1: Simple Dataverse CRUD → Web API

User: I need to show a list of products on the homepage and let users
      filter by category.

Recommendation: Web API
Reason: This is straightforward Dataverse read operations with filtering.
        No external APIs, no secrets, no server-side logic needed.
Skill: /integrate-webapi

Example 2: External API with credentials → Server Logic

User: Add payment processing through Stripe. The API key must stay
      on the server.

Recommendation: Server Logic
Reason: Calls an external API (Stripe) with credentials that must be
        protected. Server logic hides the code and credentials from
        the browser.
Skill: /add-server-logic

Example 3: Background email → Cloud Flow

User: When a user submits the contact form, send them a confirmation
      email and notify the support team on Teams.

Recommendation: Cloud Flow
Reason: Email and Teams notifications are async — the user doesn't
        need to wait for them. Cloud Flows have built-in connectors
        for Outlook and Teams.
Skill: /add-cloud-flow

Example 4: Server-side validation → Server Logic (validate-and-execute)

User: Add validation that rejects orders when quantity exceeds
      inventory. Check the actual Dataverse data, not just the form.

Recommendation: Server Logic (validate-and-execute)
Reason: Server-side validation that can't be bypassed from the browser.
        The server logic checks inventory AND creates/updates the order
        in a single call — the client doesn't write the order via Web API
        because quantity validation would be bypassable.
Skill: /add-server-logic

Example 5: Dashboard performance → Server Logic

User: The dashboard makes 3 separate API calls to load contacts,
      orders, and products. It's slow.

Recommendation: Server Logic
Reason: Batching multiple Dataverse queries into a single server
        endpoint reduces round-trips and improves load time.
Skill: /add-server-logic

Example 6: CRUD + background processing → Web API + Cloud Flow

User: Let users submit support tickets from the portal. After
      submission, assign it to the right team and send an email.

Recommendation: Web API + Cloud Flow
Reason: The ticket creation is a Dataverse write (Web API). The
        assignment and email happen in the background after the
        user submits (Cloud Flow).
Phases: Phase 1 → /integrate-webapi (ticket CRUD)
        Phase 2 → /add-cloud-flow (assignment + email, depends on ticket creation)

Example 7: Validate + process + notify → Server Logic + Cloud Flow

User: When a user places an order, validate inventory, process the
      payment through Stripe, and send a confirmation email.

Recommendation: Server Logic + Cloud Flow
Reason: Inventory validation and Stripe payment need real-time
        server-side processing with credentials (Server Logic).
        The confirmation email is async (Cloud Flow).
Phases: Phase 1 → /add-server-logic (validate inventory + process payment — parallel)
        Phase 2 → /add-cloud-flow (confirmation email, depends on payment)

Example 8: State transitions + CRUD → Server Logic (validate-and-execute) + Web API

User: Build a procurement workflow with status transitions
      (Draft → Submitted → Approved) and let users edit request details.

Recommendation: Server Logic + Web API
Reason: Status transitions must be tamper-proof — server logic validates
        the transition AND writes the new status to Dataverse in one call
        (the Secure Action Principle). Editing non-sensitive fields like
        description or notes is safe via Web API since no business rule
        governs those writes.
Phases: Phase 1 → /add-server-logic (transition-request endpoint that
          validates AND writes status changes)
        Phase 2 → /integrate-webapi (read/list requests, edit description
          and notes — but NOT status, which goes through server logic)

NOTE: The Web API item must NOT include the status field in its Update
      operations. Status writes go exclusively through the server logic
      endpoint.

Example 9: AI summary on detail page → AI Web API (Data Summarization, support-case recipe)

User: Add an AI-generated summary card to the case detail page that
      includes the comments customers have posted.

Recommendation: AI Web API — Data Summarization
Reason: Microsoft Learn documents a ready-made Data Summarization
        configuration for this scenario on the standard incident table —
        POST to /_api/summarization/data/v1.0/incidents(<id>) with
        InstructionIdentifier "Summarization/prompt/case_summary" and
        $expand=incident_adx_portalcomments($select=description). The
        user can adopt this verbatim or tweak the columns / prompt for
        their own case-handling UX.
Skill: /add-ai-webapi

Example 10: Related KB articles on detail page → AI Web API (search summary)

User: On the case detail page, show relevant KB articles to help
      agents find answers faster.

Recommendation: AI Web API (Search Summary for related-record discovery)
Reason: Search Summary's grounded retrieval returns AI-ranked citations
        from the site's knowledge index — a much better fit than a
        hand-rolled OData keyword match on the knowledge article table.
        The citations rewrite into SPA routes for clean deep-linking.
Skill: /add-ai-webapi

Example 11: List summary + browsable records → Web API + AI Web API

User: On the dashboard, show the list of open cases from Dataverse
      and an AI summary highlighting the most common issue themes.

Recommendation: Web API + AI Web API
Reason: The list is direct Dataverse reads — Web API handles pagination,
        filtering, and status badges. The summary is a list-form Data
        Summarization call with $filter=statecode eq 0 using the tabular-
        insight prompt pattern. Web API item goes in Phase 1 because AI
        Web API reuses its Layer 1/2 prereqs (table permissions, Webapi
        site settings for the incident table).
Phases: Phase 1 → /integrate-webapi (incident list CRUD for the dashboard)
        Phase 2 → /add-ai-webapi (list summary for open cases, reuses
          Phase 1's Layer 1/2 — the AI skill detects this and skips its
          Web API delegation)

Progress Tracking

Before starting Phase 1, create a task list with all phases using TaskCreate:

Mark each task in_progress when starting and completed when done via TaskUpdate.

---

Begin with Phase 1: Verify Site Exists

Backend Integration Decision Framework

Use this framework to recommend the right backend integration approach for a Power Pages code site. A single user request may map to one approach or a combination.

The Four Approaches

Web API (/integrate-webapi)

What it is: A client-side, browser-based OData API that lets frontend code perform CRUD operations directly against Dataverse tables via /_api/<entity-set> endpoints.

How it works: JavaScript/TypeScript in the browser makes HTTP calls to Dataverse. Authentication is cookie-based (user session). Table permissions and web roles control access. No code runs on the server — the browser does all the work.

Best for:

• Displaying Dataverse records in the UI (lists, tables, dashboards, detail views)
• Form submissions that create or update Dataverse records
• Filtering, sorting, searching records with OData queries
• Inline editing of records
• File/image upload to Dataverse File columns
• Real-time data binding where the user sees results immediately
• Aggregation queries ($apply) for charts and summaries

Not suitable when:

• The logic requires calling external APIs (Stripe, SendGrid, Graph, etc.)
• API keys, client secrets, or other credentials are involved
• Business logic must be hidden from the browser (pricing rules, validation algorithms)
• The operation needs to batch multiple table queries into one call for performance
• The write depends on a business rule that must be tamper-proof (e.g., status transitions, approval workflows) — use Server Logic to validate AND execute the write in a single call instead (see Secure Action Principle)
• The operation should happen in the background after the user moves on

Key characteristics:

• Code runs in the browser (visible in DevTools)
• No external API access
• No credential/secret handling
• Real-time, synchronous responses
• Requires table permissions for every Dataverse table accessed
• CSRF token required for mutations (POST, PATCH, DELETE)

---

AI Web API (/add-ai-webapi)

What it is: A specialization of Web API for AI-augmented reads. Two endpoints: Search Summary (/_api/search/v1.0/summary) produces a grounded AI answer over the site's search index, and Data Summarization (/_api/summarization/data/v1.0/<entitySet>(<id>)?$select=...) produces an AI summary of one record or a collection. Microsoft also documents a ready-made Data Summarization configuration for the standard incident table (the support-case Copilot summary recipe) — that's an example of Data Summarization, not a separate API.

How it works: Same browser-to-portal auth model as Web API — cookie session + CSRF token from /_layout/tokenhtml. Data Summarization reads via the portal's _api layer, so it respects the same table permissions, column permissions, and Web API field settings as regular Web API. The server adds a generative-AI pass that returns a text summary instead of raw records. Read-only by definition — neither endpoint mutates Dataverse.

Best for:

• AI summary of a record on its detail page (e.g., "summarize this case including its portal comments")
• AI summary of a list of records (e.g., "summarize open cases on the dashboard", "trends in this week's orders")
• Related-record discovery on a detail page (e.g., "suggest KB articles relevant to this case", "similar products")
• AI-grounded site search with citations (replaces or augments keyword-only search UIs)

Not suitable when:

• The output needs to be deterministic or exact (AI output is probabilistic; use Web API for exact data)
• The operation writes data (these endpoints are read-only — use Web API or Server Logic)
• The data isn't in Dataverse (Search Summary indexes site content; Data Summarization requires a Dataverse entity set)
• The tenant doesn't have generative AI features enabled (these APIs are preview; until an admin enables them, Data Summarization returns HTTP 400 with error.code = 90041001, while Search Summary returns HTTP 200 with an embedded { Code, Message } envelope instead)
• The site uses the Microsoft-shipped search control and just wants AI-summarised search results on it — that's a workspace toggle (Search/Summary/Title content snippet), not a code integration

Key characteristics:

• Layered on Web API — Data Summarization requires the same Webapi/<table>/enabled, Webapi/<table>/fields, and table permissions as regular Web API reads. Search Summary has no per-table prereqs.
• Code runs in the browser; the AI pass happens server-side
• Read-only — no validate-and-execute concerns (Secure Action Principle does not apply)
• Preview feature — requires tenant admin to enable generative AI, and (for Search Summary) a site-level Copilot workspace toggle. APIs and admin toggles may change before GA.
• /add-ai-webapi delegates Layer 1/2 to /integrate-webapi in AI-only read mode — if a Web API item already covers the same table, the AI item detects the existing prereqs and skips the delegation

Relationship to Web API: AI Web API items for a given Dataverse table should be ordered after any regular Web API item for the same table (Web API sets up Layer 1/2; AI adds Layer 3 on top). Search Summary items can stand alone since they have no per-table prereqs.

Field-list drift caveat (when both items exist for the same table): if /integrate-webapi has already configured Webapi/<table>/fields for full CRUD (including primary key and lookup write forms), the follow-up /add-ai-webapi run detects Layer 1/2 as ready and skips its delegation — leaving the broader CRUD allowlist in place. The AI surface still works, but the fields list is broader than AI-only mode would produce. The ai-webapi-settings-architect agent flags this as an advisory in its plan; the user can narrow the allowlist after the AI surface lands by editing the YAML directly. If a strict read-only posture matters from day one, run /add-ai-webapi before /integrate-webapi on the same table — the AI skill will then write the minimal fields list and the later Web API run will widen it.

---

Server Logic (/add-server-logic)

What it is: Server-side JavaScript that runs in a sandboxed V8 engine on the Power Pages server. Exposed as REST endpoints at /_api/serverlogics/<name>. Code is hidden from the browser.

How it works: The frontend calls a server logic endpoint. The server executes the JavaScript function matching the HTTP method (get, post, put, patch, del). The function can access Dataverse, call external APIs, read site settings/environment variables, and return a computed response.

Best for (by category):

Not suitable when:

• The operation is purely async/background (no immediate response needed) — use Cloud Flows instead
• The scenario only needs simple Dataverse CRUD with no extra logic — Web API is simpler
• The workflow spans multiple systems with built-in connectors (e.g., send email + create record + notify Teams) — Cloud Flows have 400+ connectors
• The operation takes longer than 120 seconds (platform maximum timeout)

Key characteristics:

• Code runs on the server (hidden from browser)
• Can call external APIs via Server.Connector.HttpClient
• Can access Dataverse via Server.Connector.Dataverse (respects table permissions)
• Can read site settings and environment variables for credential management
• 5 functions only: get, post, put, patch, del — each must return a string
• ECMAScript 2023 sandbox, no npm packages, no browser APIs
• 120-second maximum timeout, 10 MB default memory
• CSRF token required for non-GET requests

---

Cloud Flows (/add-cloud-flow)

What it is: Power Automate cloud flows triggered from the Power Pages frontend. The flow runs asynchronously in the Power Automate service and has access to 400+ connectors.

How it works: The frontend calls a registered cloud flow endpoint. The flow runs in the background on Power Automate infrastructure. The user does not wait for the flow to complete — the trigger returns immediately with a confirmation.

Best for:

• Background/async processing where the user doesn't need an immediate result
• Sending emails or notifications after a form submission
• Processing orders, approvals, or multi-step business workflows
• Integrating with systems that have Power Automate connectors (Teams, Outlook, SharePoint, Dynamics 365, SAP, ServiceNow, etc.)
• Long-running processes that exceed the 120-second server logic timeout
• Orchestrating multi-step workflows across multiple systems
• Scenarios where no-code/low-code maintainability is important (business users can modify flows)

Not suitable when:

• The frontend needs an immediate, computed response (use Server Logic)
• The operation is simple Dataverse CRUD (use Web API)
• The logic needs to return data that the UI renders immediately (use Server Logic or Web API)
• Low latency is critical — flow trigger has overhead compared to direct API calls

Key characteristics:

• Runs asynchronously in Power Automate (fire-and-forget from the frontend)
• 400+ pre-built connectors
• No-code/low-code — modifiable by business users in the Power Automate designer
• Output is not immediately consumed by the user
• Registered via .cloudflowconsumer.yml metadata files
• Requires web role assignments for authorization

---

Decision Matrix

Use these questions to narrow down the recommendation:

The Secure Action Principle

When server logic validates a business rule, it must also execute the resulting action.

This is the most important architectural principle for secure backend integration. Splitting validation from execution — where server logic validates a rule and then a separate client-side Web API call performs the write — creates a security gap because the client can skip the validation call and write directly via Web API.

Anti-Pattern: Validate-Only Server Logic + Client-Side Write

❌ INSECURE — Do NOT use this pattern for security-sensitive operations:

1. Browser calls /_api/serverlogics/validate-transition (Server Logic checks Draft → Submitted is valid)
2. Server Logic returns { valid: true }
3. Browser calls /_api/cr65f_orders(id) with PATCH { status: "Submitted" } (Web API writes the change)

Problem: A user can skip step 1 and go directly to step 3 via browser dev tools,
bypassing all server-side validation.

Correct Pattern: Validate-and-Execute Server Logic

✅ SECURE — Server logic validates AND executes:

1. Browser calls /_api/serverlogics/transition-order with POST { orderId: "...", newStatus: "Submitted" }
2. Server Logic reads current record from Dataverse, validates Draft → Submitted is allowed
3. Server Logic writes the status change to Dataverse via Server.Connector.Dataverse.UpdateRecord
4. Server Logic returns { status: "success", previousStatus: "Draft", newStatus: "Submitted" }

The browser never makes a direct Web API write for this operation.

When Does This Apply?

Use validate-and-execute (server logic performs the write) whenever any of these are true:

Use Web API for the write (validation-only server logic is fine) when all of these are true:

Impact on Plan Design

When building integration plans, this principle affects how items are assigned to approaches:

1. State transitions — The server logic endpoint should accept the entity ID and target status, validate the transition, and write the new status to Dataverse. The frontend calls only the server logic endpoint — there is no separate Web API PATCH for the status field.

2. Multi-step operations — When an action involves validation + write + side effects (e.g., award a bid, reject losers, update event status), the entire sequence belongs in one server logic endpoint. The frontend makes a single call.

3. Mixed operations on the same table — A table may use Web API for some fields (e.g., editing a description) and server logic for others (e.g., changing status). This is expected and correct. Table permissions should grant read access broadly but restrict write access to fields that are safe for direct client writes.

4. Phase ordering — Server logic endpoints that validate-and-execute should be built before any dependent frontend work. The frontend for these operations calls server logic, not Web API.

---

Common Combinations

Many real-world scenarios use multiple approaches together:

Mapping User Intent to Approach