# Integrate Backend

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-microsoft-power-platform-skills-integrate-backend`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [microsoft](https://agentstack.voostack.com/s/microsoft)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [microsoft](https://github.com/microsoft)
- **Source:** https://github.com/microsoft/power-platform-skills/tree/main/plugins/power-pages/skills/integrate-backend
- **Website:** https://aka.ms/ppskills

## Install

```sh
agentstack add skill-microsoft-power-platform-skills-integrate-backend
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **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//*` 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](#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:

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

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 *, *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

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 → Approved) | Client could jump to any status by sending a direct PATCH |
| Conditional writes (only allowed before a deadline, only for certain roles) | Client could write after deadline or from wrong role context |
| Computed field writes (server calculates a score, price, or derived value) | Client could submit any value if it writes the field directly |
| Multi-table atomic operations (award bid + reject others + update event) | Partial execution from client could leave data inconsistent |
| Writes that depend on the current state of other records | Client's stale view of data could lead to invalid writes |

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

| Key | Description |
|-----|-------------|
| `SITE_NAME` | Site name from `powerpages.config.json` |
| `PLAN_TITLE` | Short title (e.g., "Backend Integration Plan") |
| `SUMMARY` | 1-3 sentence summary of the integration strategy |
| `ITEMS_DATA` | Array of integration items (see format below) |
| `DATA_FLOWS_DATA` | Array of data flow diagrams (see format below) |
| `RATIONALE_DATA` | Array of design rationale entries (`icon`, `title`, `desc`) |

**ITEMS_DATA format:**
```json
{
  "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//*` site settings). Search Summary items have no per-table prereqs and can go in any phase.

**DATA_F

…

## Source & license

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

- **Author:** [microsoft](https://github.com/microsoft)
- **Source:** [microsoft/power-platform-skills](https://github.com/microsoft/power-platform-skills)
- **License:** MIT
- **Homepage:** https://aka.ms/ppskills

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-microsoft-power-platform-skills-integrate-backend
- Seller: https://agentstack.voostack.com/s/microsoft
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.