setup-offline-profile — скилл для Claude Code: обзор и установка
Скилл setup-offline-profile настраивает профиль Mobile Offline в Dataverse для мобильных приложений Power Apps и генерирует конфигурационный файл offline-profile.json.
MIT ★ 1 167 обновлён 2026-10-29
/plugin marketplace add microsoft/power-platform-skills
/plugin install mobile-app@power-platform-skillsЧто делает setup-offline-profile
Скилл запускает пошаговый мастер для развёртывания автономного режима в мобильных клиентах Power Apps на iOS и Android. Он создаёт записи в системных таблицах Dataverse (mobileofflineprofile, mobileofflineprofileitem и mobileofflineprofileitemassociation), определяя фильтры строк для каждой таблицы, правила связей, состав столбцов и частоту синхронизации.
Процесс разбит на три контрольные точки: проверка готовности таблиц, согласование объёма выгружаемых строк и утверждение связей со столбцами. Конфигурация сохраняется в локальный файл offline-profile.json. При этом файл power.config.json скилл намеренно не трогает.
Для работы требуется инициализированный проект с файлами power.config.json, app.config.js и манифестом модели данных .datamodel-manifest.json. Если приложение собрано только под веб, мастер предупредит об этом, потому что профили Dataverse Mobile Offline поддерживаются только на iOS и Android.
Какие задачи решает
- настроить автономный режим Dataverse для мобильного клиента Power Apps
- создать записи Mobile Offline Profile и привязать таблицы через Web API
- сформировать файл
offline-profile.jsonс фильтрами строк и частотой синхронизации - проверить готовность таблиц Dataverse к офлайн-репликации перед публикацией
Примеры запросов агенту
- Настрой автономный профиль Dataverse для мобильного приложения
- Запусти setup-offline-profile и настрой синхронизацию таблиц для работы без сети
- Сконфигурируй offline-profile.json для текущего проекта Power Apps
Как установить setup-offline-profile
1Через маркетплейс плагинов
/plugin marketplace add microsoft/power-platform-skills/plugin install mobile-app@power-platform-skillsКоманда ставит плагин mobile-app целиком, со всеми его скиллами
2Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill setup-offline-profile -a claude-code3Вручную: положить файлы
~/.claude/skills/setup-offline-profile/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/setup-offline-profile/
1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill setup-offline-profile -a codex2Вручную: положить файлы
.agents/skills/setup-offline-profile/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill setup-offline-profile -a cursor2Вручную: положить файлы
.cursor/skills/setup-offline-profile/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install microsoft/power-platform-skills plugins/mobile-apps/skills/setup-offline-profile2Вручную: положить файлы
.github/skills/setup-offline-profile/SKILL.md1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill setup-offline-profile -a gemini-cli2Командой платформы
gemini skills install https://github.com/microsoft/power-platform-skills --path plugins/mobile-apps/skills/setup-offline-profileВручную: положить файлы
.devin/skills/setup-offline-profile/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о setup-offline-profile
Как установить setup-offline-profile в Claude Code?
Подключите каталог командой /plugin marketplace add microsoft/power-platform-skills, после чего установите плагин командой /plugin install mobile-app@power-platform-skills.
Что делает скилл setup-offline-profile?
Он создаёт профиль Mobile Offline в Dataverse через пошаговый сценарий с тремя согласованиями и записывает правила выгрузки данных в файл offline-profile.json.
Работает ли скилл в чисто веб-проектах?
Профиль создаётся только для нативных платформ iOS и Android. Если в app.config.js указан только веб, мастер остановится и предупредит, что приложение не сможет задействовать офлайн-профиль.
Исходный текст
SKILL.md · MIT
---
name: setup-offline-profile
description: Use when the user wants to enable offline mode for a Power Apps mobile app and create a Mobile Offline Profile in Dataverse — designs per-table row scope, relationships, columns, and sync frequency through a 3-gate approval flow.
user-invocable: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, EnterPlanMode, ExitPlanMode, Task
model: opus
---
> **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](${PLUGIN_ROOT}/shared/shared-instructions.md)** — read first.
**References:**
- [offline-profile-schema.md](${PLUGIN_ROOT}/shared/references/offline-profile-schema.md) — Dataverse entity field map
- [dataverse-offline-api.md](${PLUGIN_ROOT}/shared/references/dataverse-offline-api.md) — Web API recipes for profile / item / association POSTs
- [offline-profile-reconciliation.md](${PLUGIN_ROOT}/shared/references/offline-profile-reconciliation.md) — the `schemaColumns` baseline this skill writes + the lifecycle delta check that consumes it
# Setup Offline Profile
End-to-end wizard for creating a Dataverse Mobile Offline Profile that the app (and any other compatible Power Apps client) can use to download data for offline access.
**Scope of v0**: configuration only. This skill creates records in the existing
Dataverse Mobile Offline Profile tables (`mobileofflineprofile`,
`mobileofflineprofileitem`, `mobileofflineprofileitemassociation`) and writes
the full app-level offline config — profile metadata, per-table scope, and the
temporary SDK-workaround fields — to `offline-profile.json`. **This skill does
NOT modify `power.config.json`** (that file is owned by `pa app init`
and its schema is controlled upstream). The template already bundles
`@microsoft/power-apps-native-offline`; `@microsoft/power-apps-native-host`
consumes the profile and owns local SQLite access, queued synchronization,
reconnect behavior, and status UX. This skill does not scaffold duplicate
app-owned offline runtime code.
**Out of scope for v0**:
- Custom filter mode (`recorddistributioncriteria=3`, savedquery picker) — defer to v0.5
- User/team membership assignment — split into `/assign-offline-profile`
- Row-count download estimation — split into `/preview-offline-scope`
## App-root binding
Before entering the wizard, and before any project read or command, execute
[app-working-directory.md](${PLUGIN_ROOT}/shared/references/app-working-directory.md).
Resolve one absolute `working_dir`: inherit a child invocation's owner root or
use the direct invocation's explicit `--working-dir`/initial cwd per that contract.
Missing or conflicting child context returns `NEEDS_CONTEXT`, never a launch-cwd
fallback. Bind every shell call and file tool, including references and retries,
to this root; file tools use absolute `<working_dir>/...` paths.
Retain the selected environment ID/URL/tenant and supplied answers as invocation
context. Re-supply the absolute `PLUGIN_ROOT` and required values in each fresh
call; prior shell variables do not persist. Forward the same root and identity
to the architect and prerequisite helper. Entry approval is not permission to
skip the wizard's offline gates. A `--plan-only` or planning-phase caller returns
`NEEDS_CONTEXT: offline setup requires an implementation-phase invocation`
before entering this mutating wizard.
## Workflow
1. Verify project & auth → 2. Resolve mode (create vs extend) → 3. Spawn architect agent → **Gate 1** (table prerequisites) → 4. Run the internal `enable-tables-offline` workflow if needed → 5. POST profile shell → **Gate 2** (per-table row scope) → 6. POST profile items → **Gate 3** (relationships + columns + sync) → 7. POST associations → 8. Validate + publish → 9. Persist artifacts → 10. Summary
---
### Step 1 — Verify project & auth
```bash
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
environment_id=$(node -p "require('./power.config.json').environmentId || ''") || {
echo "BLOCKED: unreadable power.config.json" >&2; exit 1;
}
if [ -z "$environment_id" ]; then
echo "NEEDS_CONTEXT: selected app has no environmentId" >&2; exit 1;
fi
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$environment_id" --no-cache --require-tenant
```
Require the resolved environment ID, HTTPS URL, and tenant to match any supplied
owner context. Capture them as `<selected-environment-id>`, `<envUrl>`, and
`<tenantId>`. A mismatch returns `NEEDS_CONTEXT`; do not switch environment or
account to proceed. Pass `--tenant-id "<tenantId>"` to every Dataverse request,
including copied reference commands and retries.
Locate `<working_dir>/.datamodel-manifest.json` or
`<working_dir>/docs/plan-artifacts/.datamodel-manifest.json` with absolute file
tools. Keep the selected absolute manifest path in invocation context for the
architect (Step 3) and artifact updates (Step 9); never search another app.
**Web-only target detection** — Mobile Offline Profiles only apply to native targets (iOS/Android). If the project is web-only, the profile will be created in Dataverse but **the generated app will never use it**:
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
# Inspect platforms declared in app.config.js
node -e "
const c = require('./app.config.js');
const platforms = c?.expo?.platforms ?? [];
const hasNative = platforms.includes('ios') || platforms.includes('android');
console.log(JSON.stringify({ platforms, hasNative }));
"
```
| `hasNative` | Action |
|---|---|
| `true` (has `ios` and/or `android`) | Continue normally |
| `false` (web-only or no platforms) | Print: `⚠ This project only targets web — Mobile Offline Profiles don't apply (they require iOS/Android). Continuing will create the profile in Dataverse but no app will use it.` Ask via `AskUserQuestion`: "Continue anyway?" Default No. |
| Parse error / app.config.js missing key | Warn, but assume native (don't block on a parser quirk) |
STOP conditions:
- No `power.config.json` → "Run `/create-mobile-app` first."
- Neither `.datamodel-manifest.json` nor `docs/plan-artifacts/.datamodel-manifest.json` → "Run `/add-dataverse` first — offline profiles require a data model."
- Environment resolution failure → standard auth recovery (`az login --tenant <env-tenant>` or provide environment URL directly; see [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)).
- Web-only + user declines override → STOP. Print: `Offline profile creation skipped — no native target.`
#### Step 1a — Environment consistency check
Same as `/add-dataverse` Step 3a — verify `power.config.json` resolves and `az` can token for the target tenant. STOP if it cannot; user must re-auth with `az login --tenant <env-tenant>`.
#### Step 1b — Resume check
Read `memory-bank.md` `## Offline profile` block. Decide based on `status`:
| `status` value | Action |
|---|---|
| (section absent) OR `status: none` | First-time run. Continue to Step 2. |
| `status: not-applicable` | User previously opted out during `/create-mobile-app` offline-profile setup ("doesn't need offline support"). Re-confirm: "Memory-bank says this app doesn't need offline. Override and proceed? (y/N)". Default N stops here. |
| `status: done` AND a profile matching `profileId` still exists in env | Already complete. Print summary from the memory-bank block; ask user if they want to `/edit-offline-profile` (v0.2) or just exit. |
| `status: done` BUT `GET /mobileofflineprofiles(<profileId>)` returns 404 | Profile was deleted externally (maker portal or another env). Treat as `none`; clear the section; continue to Step 2. |
| `status: in-progress` AND profile exists in env | **Resume flow** — see below. |
| `status: in-progress` BUT profile doesn't exist in env | Memory-bank stale. Auto-clean: clear the section, log `recovered from stale in-progress state`, continue to Step 2 as a fresh run. |
**Resume flow** — when memory-bank has `status: in-progress` AND the profile still exists:
1. `GET /mobileofflineprofiles(<profileId>)?$expand=MobileOfflineProfile_MobileOfflineProfileItem` to compute what's actually been committed:
- 0 items → profile shell exists, items not yet POSTed. Resume from Step 6.
- 1+ items, missing some from manifest → resume from Step 6, skipping items already present.
- All items present, `selectedcolumns` empty on ≥1 → resume from Step 7 (PATCH).
- All items present, all have `selectedcolumns` → resume from Step 8 (Publish).
- `componentstate=0` (Published) → memory-bank lies; treat as `done`.
2. Ask the user one consolidated AskUserQuestion (NOT a per-step approval):
```
Resume from <computed step> on profile "<name>" (<profileId>)?
Items already committed: <N> of <M>
PATCHes already applied: <K>
Published: <yes|no>
Options:
- Resume from where it left off (recommended)
- Start fresh — delete the half-built profile and re-run from Step 5
- Cancel
```
3. On `Resume` → jump to the computed step. Skip already-committed items by matching `selectedentitytypecode`.
4. On `Start fresh` → `DELETE /mobileofflineprofiles(<profileId>)` (cascade-deletes items + associations), clear memory-bank section, continue to Step 2 as new.
5. On `Cancel` → STOP, leave memory-bank untouched.
**Memory-bank checkpoint contract:** the skill writes `status: in-progress` + `profileId` immediately after Step 5 (profile shell POST). Each subsequent step updates a `lastSuccessfulStep:` field so resume knows where to pick up. On `BLOCKED:` from any step, the skill leaves `status: in-progress`; on `DONE`, it writes `status: done` in Step 9c.
**Idempotency on POST retries:** if Step 6 re-POSTs an item with the same `selectedentitytypecode` against the same parent profile, Dataverse may return `409 Conflict` ("duplicate"). The wrapper `dataverse-request.js` treats this as silent success via its `looksLikeDuplicate` logic — safe to re-attempt.
### Step 2 — Resolve mode (create vs extend vs reconcile)
**Telemetry checkpoint: `resolve_offline_profile_mode`**
**Print before starting:**
> "→ Checking for existing offline profiles in the environment…"
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \
"mobileofflineprofiles?\$select=mobileofflineprofileid,name,description,publishedon" \
--tenant-id "<tenantId>"
```
Decision tree — evaluate in order:
| # | Condition | Action |
|---|---|---|
| 1 | Step 1b already detected `status: in-progress` in memory-bank | Resume flow (handled in Step 1b). Do not re-evaluate here. |
| 2 | `offline-profile.json` has top-level `profileId: <X>` AND profile `<X>` still exists in env | **Collision case — ASK USER.** AskUserQuestion: (a) Extend the pinned profile (re-architect against current data model + add/PATCH items as needed), (b) Delete the pinned profile and create fresh (irreversible — cascade-deletes items + associations + memberships), (c) Cancel. Default = (a) extend. NEVER silently delete. |
| 3 | `offline-profile.json` has top-level `profileId: <X>` AND profile `<X>` does NOT exist (404 from GET) | `offline-profile.json` is stale (env reset, profile manually deleted). Delete the local file, continue to row #4. |
| 4 | Any existing profile in env has `name` matching this app's name (case-insensitive substring match on `power.config.appDisplayName` or directory name) | **ASK USER.** AskUserQuestion: (a) Extend the name-matching profile, (b) Create a new profile (the name-matching one may belong to another app — your call), (c) Cancel. No default — both are legitimate. |
| 5 | Zero profiles in env | Mode = `create-new`. Continue to Step 3. |
| 6 | 1+ profiles in env but no name match + no pin | Mode = `create-new` (the env has unrelated profiles). Continue to Step 3. Print one-line note: `↷ <N> unrelated profiles exist in env; not extending — see /edit-offline-profile to manage them.` |
> **Why row #2 is critical (empirical 2026-05-25)**: the chanel-rm and FCB Tracker test runs hit this case. Without this check, the skill cascade-deleted the pinned profile silently. After this patch, the user gets a clear three-way choice and `delete` is always an explicit action.
> **Extend mode (rows #2a, #4a) implementation**: re-spawn the architect with `Mode: extend, existingProfileId: <X>`. The architect compares its current proposal to the on-server items + associations and outputs three lists: (i) items to ADD, (ii) items to PATCH (scope/columns/sync diffs), (iii) items to DELETE (in-server but not in current data model). Surface to the user at Gate 2. After approval, the skill issues incremental writes — no profile-shell POST.
### Step 3 — Spawn architect agent
**Telemetry checkpoint: `design_offline_profile_scope`**
**Print before starting:**
> "→ Spawning mobile-app:offline-profile-architect agent (read-only) to design the profile…"
Spawn via `Task`:
```text
agent: mobile-app:offline-profile-architect
prompt:
Owner: setup-offline-profile
Phase: planning
Working directory: <working_dir>
Plugin root: ${PLUGIN_ROOT}
Environment ID: <selected-environment-id>
Environment URL: <envUrl>
Tenant ID: <tenantId>
Manifest path: <absolute manifest path within working_dir>
Proposal output: <working_dir>/_offline_section.md
Publisher prefix: <prefix>
Mode: default
```
The agent returns `_offline_section.md` in the working directory. Read it. Parse its first-line status code:
- `DONE` → continue
- `DONE_WITH_CONCERNS: <list>` → surface concerns at Gate 2 / Gate 3 where relevant; continue
- `NEEDS_CONTEXT: <missing>` → resolve the missing context (most often: data model file absent), re-spawn once (cap: 2 retries). If still failing, STOP with the agent's reason.
- `BLOCKED: <reason>` → STOP, surface to user, do not silently retry.
### Step 3.5 — Configuration review (interactive AskUserQuestion flow)
**Telemetry checkpoint: `review_offline_profile_configuration`**
**Print before starting:**
> "→ Presenting the proposed offline profile configuration. You'll tap an option to accept, adjust, or cancel — no need to type."
The skill renders the proposal as a one-screen summary (read-only context) and then drives the decision through structured `AskUserQuestion` prompts — the same click-style pattern `/create-mobile-app` uses for its 4 plan gates. This replaces the older "type `accept` / plain-English edits / `cancel`" reply flow, which was hit-or-miss when users typed something the parser didn't recognize.
#### Step 3.5a — Print the summary (informational only)
Substitute real values from `_offline_section.md` and the architect output:
```text
══════════════════════════════════════════════════════════════════════
Mobile Offline Profile — Proposed Configuration
══════════════════════════════════════════════════════════════════════
PROFILE METADATA
Name : <proposed name>
Description : <proposed description, or "(none)">
Mode : create-new | extend existing (<profileId>)
TABLE PREREQUISITES (IsAvailableOffline + ChangeTrackingEnabled)
cr123_note ❌/❌ → will be enabled
cr123_visit ✅/❌ → ChangeTracking will be enabled
contact ✅/✅ → no change
PER-TABLE CONFIG
▸ cr123_note (Organization rows, User's rows)
Sync : every 10 min
Columns : 12 (cr123_title, cr123_body, cr123_visitid, …, modifiedon, createdon)
▸ cr123_visit (Related rows only)
Sync : every 10 min
Columns : 8 (cr123_name, cr123_date, …, modifiedon)
▸ contact (All records)
Sync : every 60 min
Columns : 5 (fullname, emailaddress1, …, modifiedon)
RELATIONSHIPS (will be POSTed as mobileofflineprofileitemassociation rows)
cr123_note → cr123_note_visit (links to cr123_visit)
cr123_note → cr123_note_image (includes image bytes)
══════════════════════════════════════════════════════════════════════
```
No prompt is shown alongside this text — it's informational context, immediately followed by the interactive prompt below.
#### Step 3.5b — Top-level decision (single `AskUserQuestion`)
```text
header : Offline profile
question : "Accept the proposed offline profile configuration and publish to Dataverse?"
options :
- Accept and publish (Recommended)
- Adjust before publishing
- Cancel — abort, nothing is mutated
```
Outcomes:
| User picks | Action |
|---|---|
| **Accept and publish** | Write memory bank checkpoint (see below), continue to Step 4 (enable prereqs if needed) → Step 5 (POST shell) → Step 6 (POST items) → Step 7 (PATCH selectedcolumns) → Step 8 (publish) → Step 9 (persist) → Step 9.5 (verify) → Step 10 (summary). **No further prompts** unless something fails. |
| **Cancel** | STOP. No Dataverse mutations. No artifacts written. Update `memory-bank.md` with `status: cancelled-at-config-review`. |
| **Adjust before publishing** | Continue to Step 3.5c. |
#### Step 3.5c — Pick the areas to adjust (single `AskUserQuestion`, multiSelect)
```text
header : Adjust which
question : "Which sections of the proposal do you want to change?"
multiSelect: true
options :
- Profile name or description
- Per-table row scope (who's rows get synced)
- Per-table sync interval
- Per-table column selection
```
Whatever the user picks drives Step 3.5d. If they pick nothing (closing the dialog), treat that as a no-op and loop back to Step 3.5b.
#### Step 3.5d — Drill-down per area
For each area the user picked in 3.5c, run the corresponding sub-flow. Apply edits to an in-memory config copy as you go; nothing hits Dataverse until Step 3.5e.
**Profile name or description** — text prompt (free-form input, no enumeration possible):
> "Type the new profile name, or `skip` to keep `<current name>`."
>
> Then: "Type the new description, or `skip` to keep `<current description>`."
Validate name ≤ 100 chars; trim whitespace; reject empty.
**Per-table row scope** — one `AskUserQuestion` per table (batch up to 4 tables per call; 5+ tables → multiple calls):
```text
header : Scope <table>
question : "Row scope for `<table-logical-name>`?"
options :
- Related rows only (child of a parent table; default for pure children)
- All records (default for shared catalogs like product / contact)
- User's own rows (Organization-scoped + recordsownedbyme=true; default for personal transactional data)
- Organization's rows (Organization-scoped, all owners — broadest non-All)
```
Map answers → `recordDistributionCriteria` (0=Related, 1=All, 2=Organization) + the `recordsownedby*` sub-flags. If the user picks "User's own rows" set `recordsownedbyme=true`; if "Organization's rows" leave all three sub-flags false.
**Per-table sync interval** — one `AskUserQuestion` per table:
```text
header : Sync <table>
question : "How often should `<table-logical-name>` sync?"
options :
- Every 5 min — hot transactional data (Recommended for tables users edit live)
- Every 15 min — typical
- Every 30 min — slower-moving
- Every 60 min — static catalogs (lowest battery cost)
```
(Range is 5–1440 min server-side; custom values outside these four come via the `Other` free-text option that `AskUserQuestion` always provides — validate 5 ≤ N ≤ 1440.)
**Per-table column selection** — text fallback (column lists are too varied for multi-choice):
> "For `<table>`, type column changes one per line:
> `exclude <column>` to drop a column from sync
> `include <column>` to add one that's currently excluded
> `all` to reset to every column from the manifest
> `skip` to leave columns unchanged"
Validate every named column exists in `.datamodel-manifest.json`; reject typos with the closest-match column suggestion.
#### Step 3.5e — Re-confirm
After all picked sub-flows complete, **re-render the summary** (Step 3.5a format) with the changed rows marked `→ updated` in a different colour or with a leading `*`. Then re-run Step 3.5b — same three-option `AskUserQuestion`. The user can adjust again, accept, or cancel.
This loop is bounded by user patience, not a hard limit. If they pick "Adjust" repeatedly without ever choosing "Accept" or "Cancel", that's their prerogative — every loop is reversible and nothing has hit Dataverse yet.
#### Step 3.5f — Memory bank checkpoint (after `Accept and publish`)
```yaml
## Offline profile
status: in-progress
profileName: <name>
mode: create-new | extend
configReview: accepted
```
> **Design rationale.** The original Step 3.5 used free-text replies ("type `accept` or describe edits in English") to keep things conversational. In practice users typed responses the regex parsers didn't recognise — `change scope of contact to teamonly`, `set sync to 10`, etc. — and the skill either silently dropped the edit or asked a clarifying question that drove additional confusion. The `AskUserQuestion` flow above eliminates parsing risk for the enumerable fields (scope, sync interval, top-level decision) while preserving the free-text path for the genuinely free-form fields (name, description, column lists). Net result: zero ambiguous interactions for the common adjustments, fewer typing-induced errors, parity with `/create-mobile-app`'s plan-gate UX.
### Step 4 — Run the internal `enable-tables-offline` workflow if needed
**Telemetry checkpoint: `enable_dataverse_tables_offline`**
If Gate 1 identified any table needing change, read and execute
`${PLUGIN_ROOT}/skills/enable-tables-offline/SKILL.md` with the approved table
list and the complete scoped handoff below. Configuration review must already
be accepted; neither a saved manifest nor a bare table list is approval.
```text
$ARGUMENTS: --working-dir '<working_dir>' <comma-separated approved logical names>
Context:
MOBILE_APP_ORCHESTRATING=1
orchestrator: setup-offline-profile
working_dir: <working_dir>
phase: implementation
approved_scope:
environmentId: <selected-environment-id>
environmentUrl: <envUrl>
tenantId: <tenantId>
tables: <exact Gate 1-approved prerequisite table allowlist>
operations: <approved IsAvailableOffline/ChangeTrackingEnabled changes>
publication: <approved targeted publication; broader fallback only if separately approved>
supplied_answers: <current offline gate responses>
```
Wait for it to return and parse its literal first-line status. `DONE` continues;
`DONE_WITH_CONCERNS` must be surfaced before continuing. On `NEEDS_CONTEXT`,
resolve the missing context within this owner's approved root/scope or return
the blocker; never re-dispatch with a different app or infer approval.
If `BLOCKED`, propagate the block up — STOP.
If all tables were already enabled, skip this step.
### Step 5 — POST profile shell
**Telemetry checkpoint: `create_offline_profile_shell`**
**Print before starting:**
> "→ Creating MobileOfflineProfile record (Name + Description only)…"
For `create-new` mode:
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
"mobileofflineprofiles" \
--tenant-id "<tenantId>" \
--body '{
"name": "<app name> Offline Profile",
"description": "<auto-generated description referencing app name + scope summary>"
}' \
--include-headers
```
Capture `mobileofflineprofileid` from the `OData-EntityId` response header (matches the pattern in `/add-dataverse` Step 5b).
For `extend` mode: re-use the existing `mobileofflineprofileid` from Step 2.
Write to `memory-bank.md`:
```yaml
## Offline profile
status: in-progress
profileId: <guid>
profileName: <name>
mode: create-new | extend
gate1: approved
```
### (Gate 2 — REMOVED, consolidated into Step 3.5)
### Step 6 — POST profile items
**Telemetry checkpoint: `add_tables_to_offline_profile`**
**Print before starting:**
> "→ Creating <N> MobileOfflineProfileItem records (one per table, sequential)…"
> **⚠️ Concurrency rule.** Profile items reference each other implicitly via the parent profile. Issue POSTs sequentially, one at a time. The mobileofflineprofileitem entity does NOT hold the metadata lock that EntityMetadata does, but the validation pass on each POST reads neighboring items — parallel POSTs occasionally return 412 PreconditionFailed. Sequential is the safe path.
For each table, in sequence:
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
"mobileofflineprofileitems" \
--tenant-id "<tenantId>" \
--body '{
"name": "<table display name>",
"[email protected]": "/mobileofflineprofiles(<profileId>)",
"selectedentitytypecode": "<table-logicalname>",
"recorddistributioncriteria": <0|1|2>,
"recordsownedbyme": <bool>,
"recordsownedbymyteam": <bool>,
"recordsownedbymybusinessunit": <bool>,
"getrelatedentityrecords": true,
"syncintervalinminutes": 10
}' \
--include-headers
```
Capture each `mobileofflineprofileitemid` from the response header. Store in a local map `tableLogicalName → itemId` — needed for Step 7 (associations) and Step 9 (offline-profile.json).
`selectedcolumns` is NOT set here — added at Gate 3 / Step 7 once the user confirms the column subset.
Print `✓ <table>` after each 2xx.
### (Gate 3 — REMOVED, consolidated into Step 3.5)
### Step 7 — POST associations + PATCH selectedcolumns
**Telemetry checkpoint: `configure_offline_profile_associations`**
**Print before starting:**
> "→ Creating association rows + PATCHing selectedcolumns on each profile item…"
#### Step 7a — POST `mobileofflineprofileitemassociation` rows
Empirical 2026-05-24 + 2026-05-25 capture from maker portal **unblocked** association creation. Recipe (no `selectedrelationshipsschema` field — server fills it):
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
"mobileofflineprofileitemassociations" \
--tenant-id "<tenantId>" \
--body '{
"name": "<relationshipSchemaName>",
"relationshipdisplayname": "<relationshipSchemaName>",
"relationshipid": "<MetadataId-of-1:N-relationship-from-architect>",
"[email protected]": "/mobileofflineprofileitems(<PARENT-item-id>)"
}' \
--include-headers
```
> **⚠️ Critical direction rule.** `regardingobjectid` is the **parent (1-side)** profile item. For an `account → orderline` 1:N relationship, the association lives on the `account` profile item with the relationship `account_orderline` (read from `EntityDefinitions(LogicalName='account')/OneToManyRelationships`). POSTing on the `orderline` (child) side fails `PublishXml` with `0x80071140 — no relationships are specified for this Related-only table`. This is the canonical bug — architect's Step 5 now explicitly walks parents' `OneToManyRelationships` to produce parent-keyed output.
For each (PARENT-item, 1:N-relationship-to-child) pair from the architect's proposal:
1. Resolve `relationshipid` (MetadataId GUID) via `EntityDefinitions(LogicalName='<PARENT-table>')/OneToManyRelationships` filtering by `SchemaName === <relationshipSchemaName>`. Cache the lookup per parent table.
2. POST the association (sequential — parallel POSTs occasionally return 412 PreconditionFailed).
3. Capture the new `mobileofflineprofileitemassociationid` from the `OData-EntityId` response header.
> **Skip-when-redundant rule.** If the parent profile item has `recorddistributioncriteria=1` (All records), the architect should have pruned associations on it (per Step 5 pruning rule). Defensively: if any propagate through, SKIP them at POST time. Print: `↷ Skipping <association> on All-records parent <table> — redundant, all rows download anyway`.
> **Pre-publish cycle detection.** Before Step 8 publish, build the relationship graph from the just-created associations and DFS for cycles. If a cycle exists (e.g. `account → task → account`), prompt the user to remove ONE association and re-do this step for the affected pair — otherwise Step 8 will return `0x80071141`. See [shared/references/dataverse-offline-api.md §6b](${PLUGIN_ROOT}/shared/references/dataverse-offline-api.md).
> **Idempotency.** Re-POSTing an existing (item, relationship) pair returns `409 Conflict`; the `dataverse-request.js` `looksLikeDuplicate` rescue treats this as success. Re-runs after a partial failure are safe.
Skip Step 7a entirely if the architect's proposal includes zero relationships (rare — usually fixture-grade single-table profiles).
#### Step 7b — PATCH `selectedcolumns` on each item
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> PATCH \
"mobileofflineprofileitems(<itemId>)" \
--tenant-id "<tenantId>" \
--body '{
"selectedcolumns": "<JSON string — see below>"
}'
```
`selectedcolumns` shape (verified by inspecting an existing profile created by maker portal — see [§10 known blocker in plan](#) for caveat):
```json
{
"Columns": ["cr123_title","cr123_body","cr123_visitid","modifiedon","createdon","statecode"]
}
```
Wrap as a stringified JSON in the memo field.
If syncintervalinminutes was edited at Gate 3, include it in the same PATCH.
### Step 8 — Publish
**Telemetry checkpoint: `publish_offline_profile`**
**Print before starting:**
> "→ Publishing profile (targeted PublishXml)…"
> **Validate step intentionally skipped.** Empirical 2026-05-17: the `Validate` action's documented body shape is rejected by the server. The maker portal does NOT call Validate either (confirmed via 2026-05-24 capture) — publish-time validation runs server-side as part of PublishX...
© Microsoft · MIT · microsoft/power-platform-skills