assign-offline-profile

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

References:

• offline-profile-schema.md — usermobileofflineprofilemembership / teammobileofflineprofilemembership entity field map
• dataverse-offline-api.md — Web API recipe (§12 — membership POSTs)

Assign Offline Profile

Bind one or more users and/or teams to an existing Mobile Offline Profile. Without this step, the profile exists in Dataverse but is unbound — no one's app actually uses it for offline sync.

Per the maker portal's UX (the "Assign profile to user" dialog under env settings), this is a separate operation from profile creation. Many users hit "I created the profile but offline still doesn't work" — the missing piece is membership.

Workflow

1. Verify project + locate profile → 2. Pick users/teams → 3. Discover existing memberships → 4. Confirm diff (single gate) → 5. POST memberships → 6. Verify → 7. Summary

---

Step 1 — Verify project + locate profile

test -f power.config.json
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$(node -e \"console.log(require('./power.config.json').environmentId)\")"

Profile ID resolution (in order):

STOP if no profile can be resolved. Print: Run /setup-offline-profile first, or pass --profile-id.

power.config.json is intentionally NOT consulted here. That file is owned by npx power-apps init. The profile ID lives in offline-profile.json only.

Step 2 — Pick users/teams

$ARGUMENTS parsing:

If no flags passed, present AskUserQuestion:

Question: "Who should receive this offline profile?"

Options (max 4):

• Just me (the current user) — equivalent to --me
• Pick specific users by UPN — you reply with comma-separated emails in the next message
• Pick a team — list env's teams and pick one
• All users with System User role — equivalent to --all-app-users; broad scope, confirm at gate

For pick-users flow: after the choice, print:

"Reply with comma-separated UPNs (e.g. rm1@contoso.com, rm2@contoso.com)"

Then read the next user message and parse.

Step 3 — Discover existing memberships

Telemetry checkpoint: discover_offline_profile_memberships

For idempotency:

# Existing user memberships for this profile
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \
  "usermobileofflineprofilememberships?\$filter=_mobileofflineprofileid_value eq <profileId>&\$select=usermobileofflineprofilemembershipid,_systemuserid_value&\$expand=systemuserid_systemuser(\$select=domainname)"

# Existing team memberships for this profile
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \
  "teammobileofflineprofilememberships?\$filter=_mobileofflineprofileid_value eq <profileId>&\$select=teammobileofflineprofilemembershipid,_teamid_value&\$expand=teamid_team(\$select=name)"

Build the set of already-bound UPNs and team names.

For each candidate user/team from Step 2, look up their systemuserid / teamid (skip if already in already-bound):

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \
  "systemusers?\$filter=domainname eq '<upn>'&\$select=systemuserid,fullname,domainname&\$top=1"

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \
  "teams?\$filter=name eq '<team-name>' and teamtype eq 0&\$select=teamid,name&\$top=1"

(teamtype eq 0 excludes Access Teams and Owner Teams — only Manage Teams get profile assignments.)

Construct three lists:

• to_add — resolved IDs to POST
• to_remove — resolved IDs to DELETE (from --unassign-* flags)
• not_found — UPNs/team-names that didn't resolve (warn)
• already_bound — skipped no-ops

Step 4 — Confirm diff (single gate)

Telemetry checkpoint: confirm_offline_profile_assignment_diff

AskUserQuestion:

Question header: Confirm membership changes

Question body:

Profile: <name> (<profileId>)

Will ADD:
  - User: rahul@contoso.com (Rahul Bansal)
  - User: charanma@... (Charan Mahankali)
  - Team: Field Service RMs (12 members)

Will REMOVE:
  (none)

Already bound (skipping):
  - User: admin@... (no-op)

Could not resolve:
  - someone@external.com — not in this env's system users

Proceed?

Options:

• Proceed
• Cancel

Step 5 — POST memberships

Telemetry checkpoint: assign_offline_profile_memberships

For each in to_add, POST sequentially (parallel POSTs occasionally return 429):

User membership:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
  "usermobileofflineprofilememberships" \
  --body '{
    "MobileOfflineProfileId@odata.bind": "/mobileofflineprofiles(<profileId>)",
    "SystemUserId@odata.bind": "/systemusers(<systemuserid>)"
  }' \
  --include-headers

Expected 204 with OData-EntityId → capture membership GUID.

Team membership:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
  "teammobileofflineprofilememberships" \
  --body '{
    "MobileOfflineProfileId@odata.bind": "/mobileofflineprofiles(<profileId>)",
    "TeamId@odata.bind": "/teams(<teamid>)"
  }' \
  --include-headers

For each in to_remove, DELETE:

node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> DELETE \
  "usermobileofflineprofilememberships(<membershipid>)"

⚠️ Duplicate handling: POSTing a membership that already exists returns 409 Conflict. The dataverse-request.js wrapper's looksLikeDuplicate rescue treats this as silent success (the Step 3 dedup should catch most cases first). Re-runs are safe.

Step 6 — Verify

Telemetry checkpoint: verify_offline_profile_memberships

Re-query memberships from Step 3 and assert the diff applied:

• Every to_add now appears in the GET response
• Every to_remove no longer appears

If the verification disagrees, return BLOCKED: membership writes did not commit and print the discrepancy.

Step 7 — Summary

Print:

✓ Membership updates applied.

  Profile      : <name>
  Total members: <N users + M teams>
  Added        : <list>
  Removed      : <list>
  Skipped      : <list> (already bound)

Users will receive the profile on their next mobile app sign-in. Existing
sessions need to sign out + sign in to trigger the profile pull.

Update memory-bank.md ## Offline profile block:

membership:
  users: [rahul@..., charanma@...]
  teams: [Field Service RMs]
  lastAssignedAt: 2026-05-19T...

Status code (final line)

• DONE — every requested add/remove applied; verify confirmed
• DONE_WITH_CONCERNS: <list> — some UPNs/teams could not be resolved, or --all-app-users matched 0 users (env may not have the role granted yet)
• NEEDS_CONTEXT: <missing> — couldn't determine profileId (no offline-profile.json, no --profile flags, no profiles in env)
• BLOCKED: <reason> — auth failure, profile not found in env, or verification disagreement

Failure recovery

Memberships are individually committed (no transaction). If Step 5 fails mid-loop:

• Partially-added memberships remain (visible in env)
• Re-running with the same arguments is idempotent (Step 3 dedup catches what's already bound)
• Use --unassign-* to undo specific bindings if needed