---

name: integrate-backend description: >- Analyzes the user's business problem and recommends the right backend integration approach — Web API, AI Web API (generative summaries / grounded search), Server Logic, Cloud Flows, or a combination — for a Power Pages site, then routes to the appropriate specialized skill. Use when the user wants to add backend integration, connect to data, add AI summaries, or needs help deciding which backend approach to use. user-invocable: true argument-hint: describe what your backend needs to do allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill, Task, TaskCreate, TaskUpdate, TaskList model: opus

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:

| Question | When to ask | |----------|-------------| | Does the user need to see the result immediately, or can it happen in the background? | When the request involves processing that could be sync or async | | Are external APIs or services involved (e.g., Stripe, SendGrid, SharePoint)? | When the request mentions "integration" without specifics | | Does this involve sensitive credentials that shouldn't be in the browser? | When external service integration is mentioned | | Is this a one-time action or a multi-step workflow? | When the request could be a simple call or an orchestration |

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

| Pattern | Why it must be server-side | |---------|---------------------------| | Status/state transitions (Draft → Submitted →