add-sharepoint

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

📋 Shared instructions: shared-instructions.md — read first.

References:

• sharepoint-reference.md — Column encoding, choice fields, lookups, API patterns (CRITICAL)
• api-authentication-reference.md — Graph API auth, token, site ID
• list-management-reference.md — Query, create, extend lists and columns

Add SharePoint

App root: before any project read or command, execute app-working-directory.md. Use its resolved absolute working_dir for every shell call and file tool, including referenced commands and delegated skills; never inherit a prior cd.

Entry routing: use the shared App feature entry points preflight before the workflow below.

Invocation scope: follow Data-source invocation scope before the workflow below. Standalone calls approve only their SharePoint schema/binding delta and verify it here; they do not start a full-app workflow.

Keep SharePoint list/library schemas in Connectors, not the Dataverse Data Model. Forward supplied site/list/connection choices and ask only for missing values; return scope changes to the current owner, or ask the standalone user, before mutation. Reuse supplied approval only for the exact current data delta.

Removal branch: after resolving invocation scope, --remove or an approved list/library binding removal executes data-source-removal.md and returns. Do not create a connection/list or run Steps 1-12 for removal; the SharePoint list/library and its contents remain on the server.

Refresh branch: after resolving invocation scope, --refresh or an approved retained-list service refresh executes Refresh a retained source and returns before Steps 1-12. Preserve the exact --data-source-name and approved binding identity; do not create a list/connection or run add-data-source.

Two paths: existing lists (skip to Step 6) or new lists (full workflow).

Workflow

1. Check Memory Bank → 2. Plan → 3. Setup Graph API Auth → 4. Review Existing Lists → 5. Create Lists → 6. Get Connection ID → 7. Discover Sites → 8. Discover Tables → 9. Add Connector → 10. Configure → 11. Type-check → 12. Update Memory Bank

---

Step 1: Check Memory Bank

Check for memory-bank.md per shared-instructions.md.

Also confirm this is a mobile app:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
if [ ! -f power.config.json ] || [ ! -f app.config.js ]; then
  echo "BLOCKED: working_dir is not an initialized app" >&2
  exit 1
fi

Step 2: Plan

Telemetry checkpoint: plan_sharepoint_data_source

Reuse the supplied site/list and existing-vs-new decisions. Ask only for missing values:

1. Which SharePoint list(s) do they need?
2. Do the lists already exist on their site, or do they need to create new ones?

For --plan-only or a planning-phase handoff, present the proposed site/list bindings, any schema changes, and unresolved choices, then STOP before implementation. Do not create connections/lists, generate services, or update the app plan or memory-bank. Missing discovery access is not permission to create a connection.

If lists already exist: Skip to Step 6.

If creating new lists:

• Ask about the data they need and design an appropriate schema
• Reuse existing lists when possible (don't duplicate)
• Enter plan mode with EnterPlanMode, present the list designs with columns and types
• Get approval with ExitPlanMode, unless the exact list/schema delta already has current owner approval. Read-only discovery that changes that delta must return for approval before Step 5.

Step 3: Setup Graph API Auth (if creating lists)

See api-authentication-reference.md for full details.

Set-Location -LiteralPath '<working_dir>' -ErrorAction Stop
az account show   # Verify Azure CLI logged in

$api = Initialize-SharePointGraphApi -SiteUrl "https://<tenant>.sharepoint.com/sites/<site-name>"
$headers = $api.Headers
$siteId = $api.SiteId

Requires Sites.Manage.All permission.

Step 4: Review Existing Lists (if creating lists)

Always query existing lists first before creating:

Set-Location -LiteralPath '<working_dir>' -ErrorAction Stop
$existingLists = Invoke-RestMethod -Uri "https://graph.microsoft.com/v1.0/sites/$siteId/lists?`$select=id,displayName,description,list&`$filter=list/hidden eq false" -Headers $headers

See list-management-reference.md for Find-SimilarLists, Compare-ListSchemas, and Get-ListSchema functions.

Present findings to user with AskUserQuestion:

• Lists that can be reused (already exist with matching columns)
• Lists that need extension (exist but missing columns)
• Lists that must be created (no match found)

Step 5: Create Lists (if creating lists)

Telemetry checkpoint: create_sharepoint_lists

Print before starting:

"→ Creating SharePoint lists via Graph API (sequential per list, columns added after list exists)…"

Require explicit current approval for the exact create/extend operations before writing; reuse matching owner approval rather than prompting twice. Use safe functions from list-management-reference.md:

• New-SharePointListIfNotExists
• Add-SharePointColumnIfNotExists
• Add-SharePointLookupColumn (for cross-list references)

Step 6: Get Connection ID

Apply connector-reference.md before any lookup or creation. Use shared_sharepointonline as apiId.

• Supplied --connection-id or approved connectionId: reuse the exact ID; skip create-connection and /list-connections.
• Supplied --connection-ref or approved connectionRef: retain the exact reference for Step 9; skip create-connection and /list-connections.
• Missing binding only: use the approved solution-reference lookup when solution-aware, or obtain explicit approval to create a connection with the command below. Conflicting, blank, or wrong-environment supplied bindings must be clarified, not replaced.

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
$PA connection create --connector shared_sharepointonline --json

Only on the creation path, capture the returned connectionId. The following picker examples use the ID path. With a reference, skip pickers when site/list values are supplied; otherwise obtain the backing ID for that same reference or ask for the missing choices. Do not create another connection for discovery.

If pa connection create cannot complete because browser-based connection creation is disabled or the connector needs interactive auth, direct the user to create one:

Open https://make.powerapps.com/environments/<environment-id>/connections → + New connection → search "SharePoint" → Create. Then provide the connection ID or rerun /list-connections shared_sharepointonline.

Step 7: Discover Sites

Skip this picker when the approved site URL is already supplied.

Print before starting:

"→ Discovering SharePoint sites accessible to this connection…"

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
$PA connection list-datasets --connector shared_sharepointonline --connection-id '<connectionId>' --json

Present the discovered sites only when a site choice is missing.

If pa connection list-datasets fails or returns no results:

• Auth, wrong user, or multiple accounts: follow shared-instructions command-failure handling and retry once.
• Empty list: Confirm the connection ID is for a SharePoint Online connection and the user has access to at least one site. STOP if the list is empty after confirming.

Step 8: Discover Tables

Skip this picker for supplied list/library identities; reuse the approved values.

Print before starting:

"→ Discovering lists/document libraries on each selected site…"

For each selected site:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
$PA connection list-tables --connector shared_sharepointonline --connection-id '<connectionId>' --dataset '<site-url>' --json

Present the tables to the user and ask which ones they want to add. Suggest tables that look relevant to their use case. If lists were created in Step 5, they should appear here.

Step 9: Add Connector

Telemetry checkpoint: generate_sharepoint_data_source

Print before starting:

"→ Running pa app add data-source per list (sequential, ~10–20 seconds each)."

SharePoint is tabular: use --dataset and --table with the exact binding selected in Step 6. Confirm approval covers this environment, connection ID/reference, site, and list/library before registration. Ask the standalone user to approve any newly resolved binding; return a changed child scope to its owner. A picker selection alone is not execution approval. Run only the applicable command:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
# Supplied/resolved connection ID
$PA app add data-source --connector shared_sharepointonline --connection-id '<connectionId>' --dataset '<site-url>' --table '<table-name>'

# Supplied/resolved connection reference
$PA app add data-source --connector shared_sharepointonline --connection-ref '<connectionRef>' --dataset '<site-url>' --table '<table-name>'

Run once per list or document library.

Step 10: Configure

Inspect and return service signatures and usage guidance to the user or current owner. Do not independently edit screens or launch another app workflow; explicitly report that this data-source operation did not wire screens.

Read sharepoint-reference.md before writing any SharePoint code — column encoding, choice fields, and lookups have critical gotchas.

Use Grep to find methods in <working_dir>/src/generated/services/SharePointOnlineService.ts (generated files can be very large — see connector-reference.md).

Sample usage:

import { SharePointOnlineService } from '../../src/generated/services/SharePointOnlineService';

// Read items
const result = await SharePointOnlineService.GetItems({
  dataset: 'https://contoso.sharepoint.com/sites/projects',
  table: 'Project Milestones',
});
const items = result.value ?? [];

// Create item
await SharePointOnlineService.PostItem({
  dataset: 'https://contoso.sharepoint.com/sites/projects',
  table: 'Project Milestones',
  item: { Title: 'Launch review', Status: 'Not Started' },
});

// Update item (SharePoint IDs are integers, not GUIDs)
await SharePointOnlineService.PatchItem({
  dataset: 'https://contoso.sharepoint.com/sites/projects',
  table: 'Project Milestones',
  id: 42,
  item: { Status: 'Done' },
});

Step 11: Type-check

Telemetry checkpoint: validate_sharepoint_integration

Print before starting:

"→ Regenerating connector schemas + running tsc to verify SharePoint services compile (~15–30 seconds)."

Native diff: npx --no-install tsc --noEmit instead of npm run build. Do NOT run platform-specific native build commands here.

pa app add data-source wrote new files into .power/schemas/sharepointonline/. Regenerate connectorSchemas.ts before type-checking so the new list is wired into the runtime schema map:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
npm run generate-schemas
npx --no-install tsc --noEmit

Fix TypeScript errors before proceeding.

Step 12: Update Memory Bank

Update memory-bank.md with: connector added, site URL, lists/libraries connected (or created), type-check status.

Note: No manual executor wiring needed. PowerAppsProvider in app/_layout.tsx handles SharePoint connector routing, connection resolution, and OAuth consent automatically at runtime.