@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/life-sciences-fieldsalesrep-coordinate/references/stage-5-visit-creation-overview.md

@@ -0,0 +1,307 @@
+# Stage 5 — Visit Creation
+
+Creates a sample Visit and all supporting records as the Field Sales Rep user (not the admin) in a Life Sciences Cloud org. This is the final stage (Stage 5) of the `life-sciences-fieldsalesrep-coordinate` workflow; the coordinator invokes it after the rep user (Stage 4) is provisioned.
+
+## Stage Scope
+
+- **In scope**: logging in as the sales rep; creating the full visit-chain records (Account → ProviderVisitProdDiscussion); generating the mobile metadata cache (LifeSciMobileMetadataRecord + Connect API); guiding a final manual iPad app validation; displaying a summary
+- **Out of scope**: creating territories (Stage 3), provisioning users (Stage 4), package installation (Stage 1)
+
+---
+
+## Prerequisites
+
+These must exist in the org before this stage runs (the coordinator sequences the earlier stages so they do):
+
+| Prerequisite | Created by |
+|---|---|
+| Field Sales Rep user (with LSC Custom Profile) | Stage 4 (User Provisioning) |
+| Active Territory Model with level-3 territory | Stage 3 (`life-sciences-territory-configure`) |
+| Life Sciences Cloud packages installed | Stage 1 (`life-sciences-prerequisites-validate`) |
+
+---
+
+## Required Inputs
+
+Gather before proceeding:
+
+- **Target org** (admin alias): The org alias or username for the admin connection (from `sf config get target-org` or user-specified)
+- **Sales Rep credentials**: Username and password for the Field Sales Rep user. **Ask the user** if not already known — do NOT assume or reuse admin credentials.
+
+---
+
+## Source Data (CSV-driven — read first, use only these)
+
+**All record field values MUST come from the CSV files in `.lsc-starter-config/LSStarterConfig/Data/`** — read the corresponding CSV at execution time and use **only** the values it contains. Never hardcode values from this overview or carry them over from a prior run; the CSVs are the single source of truth and may change between runs.
+
+> **The `.lsc-starter-config/LSStarterConfig/Data/` CSVs must already be present in the CWD** (from the public repo <https://github.com/SalesforceLabs/LSStarterConfig.git>). This embedded stage is a pure consumer of the folder and does NOT download or delete it — the coordinator (`life-sciences-fieldsalesrep-coordinate`) is the sole owner of the single download (at the start of the run) and the single delete (at the end). If `.lsc-starter-config/LSStarterConfig/` is absent when this stage runs, stop and report that it must be provisioned by the coordinator; do not download it here.
+
+- Read each CSV (e.g. `cat .lsc-starter-config/LSStarterConfig/Data/<object>.csv`, named per the sobject — `account.csv`, `healthcareprovider.csv`, … `providervisitproddiscussion.csv`; the per-object mapping is in `references/stage-5-visit-creation-visit-creation-data.md`), parse header + rows, and create **one record per row** using exactly the columns present.
+- CSV columns that hold **source-org IDs** (e.g. `ProductId`, `TerritoryId`, `ParentProductId`, `ProviderVisitId`, record-type IDs) will NOT exist in the target org — resolve the equivalent record in the target org and remap the ID. Never insert a raw source-org ID.
+- The literal values shown in the workflow steps below and in `references/stage-5-visit-creation-visit-creation-data.md` are **illustrative of one CSV snapshot only** — the live CSV wins if they differ.
+
+---
+
+## State Tracking
+
+Maintain a creation state throughout the workflow (target org, rep username/alias, and a per-step status list for steps 1–16) so a smoke-test failure can be diagnosed and resumed. See the full state model in `references/stage-5-visit-creation-execution-state-and-recovery.md`.
+
+---
+
+## Workflow
+
+### Phase 1 — Login as Sales Rep
+
+1. **Ask the user** for the Sales Rep credentials (username and password) if not already known.
+
+2. **Authenticate as the Sales Rep** using the web login flow — **run the command yourself** (do not hand it to the user); it opens a browser on the user's machine for them to complete the login interactively, then returns:
+   ```bash
+   sf org login web --alias lsc-rep --instance-url <instanceUrl>
+   ```
+   Or use JWT/password flow if available:
+   ```bash
+   sf org login sfdx-url --sfdx-url-stdin <<< "<sfdxAuthUrl>"
+   ```
+
+   > Rep-owned steps (2, 3, 4, 6, 10–13) use `--target-org lsc-rep`; admin-owned steps (5, 7, 8, 9, 14–15) use `--target-org <admin>`. See the Phase 2/3 notes for the ownership split rationale.
+
+3. **Verify the login** succeeded with `sf org display --target-org lsc-rep --json` and confirm the username matches the expected sales rep.
+
+### Phase 2 — Create Account and Provider Records (Steps 2–6)
+
+> **Rep vs. Admin ownership (important):** The LSC Custom Profile can create the Account, HealthcareProvider, ContactPointAddress, ProviderAcctTerritoryInfo, and the whole Visit chain (Steps 10–13) — but NOT territory associations (Step 5) or product master data (Steps 7–9). Create those as the admin (`--target-org <admin>`), then switch back to the rep. This split is expected: territory associations and products are admin-managed data.
+
+**Step 2: Create Account (RecordType = Health_Care_Provider)**
+
+First, query the RecordType ID:
+```bash
+sf data query --query "SELECT Id FROM RecordType WHERE SObjectType='Account' AND DeveloperName='Health_Care_Provider'" --target-org lsc-rep --json
+```
+
+Then create the Account:
+```bash
+sf data create record --sobject Account --values "FirstName='Aaron' LastName='Morita' Salutation='Dr.' RecordTypeId='<recordTypeId>' IsActive=true" --target-org lsc-rep --json
+```
+
+> Reference: `account.csv` — Name=Aaron Morita, Salutation=Dr., RecordType=Health_Care_Provider.
+> The active flag is the standard `IsActive` field (boolean) — NOT `IsActive__c`. If the rep lacks FLS to it, omit it and have an admin set it afterward.
+
+**Step 3: Create HealthcareProvider**
+
+First, query the HealthcareProvider RecordType ID:
+```bash
+sf data query --query "SELECT Id FROM RecordType WHERE SObjectType='HealthcareProvider' AND DeveloperName != null LIMIT 1" --target-org lsc-rep --json
+```
+
+Then create:
+```bash
+sf data create record --sobject HealthcareProvider --values "AccountId='<accountId>' IsActive=true IsPrimaryProvider=true Name='Aaron Morita HP' ProviderType='Medical Doctor' Status='Active' RecordTypeId='<hcpRecordTypeId>'" --target-org lsc-rep --json
+```
+
+> Reference: `healthcareprovider.csv` — ProviderType=Medical Doctor, Status=Active. Do NOT set `NationalProviderIdentifier` or `IsSpeaker` — they (and `IsActive`) are FLS-gated on the LSC Custom Profile, so as the rep the create fails with `INVALID_FIELD`. Omit NPI/IsSpeaker (an admin can set them later).
+
+**Step 4: Create ContactPointAddress**
+
+```bash
+sf data create record --sobject ContactPointAddress --values "ParentId='<accountId>' AddressType='Billing' Name='415 Mission St' Street='415 Mission St' City='San Francisco' State='California' StateCode='CA' PostalCode='94105' Country='United States' CountryCode='US' Latitude=37.789853 Longitude=-122.396806 IsActive=true IsPrimary=true UsageType='Work'" --target-org lsc-rep --json
+```
+
+> Reference: `contactpointaddress.csv` — 415 Mission St, San Francisco, CA 94105
+
+**Step 5: Create ObjectTerritory2Association — as ADMIN**
+
+First, query the level-3 territory ID:
+```bash
+sf data query --query "SELECT Id, Name FROM Territory2 WHERE Territory2Model.State='Active' AND ParentTerritory2.ParentTerritory2Id != null" --target-org <admin> --json
+```
+
+Then create it **as the admin** — the rep profile lacks "Manage Territories", so as the rep this fails with `entity type cannot be inserted: Object Territory Association` (describe reports `createable=false` for the rep). As the admin it is `createable=true`:
+```bash
+sf data create record --sobject ObjectTerritory2Association --values "ObjectId='<accountId>' Territory2Id='<territory2Id>' AssociationCause='Territory2Manual'" --target-org <admin> --json
+```
+
+> Reference: `objectterritory2association.csv` — AssociationCause=Territory2Manual. This is an admin-managed record, not referenced by any later record (the Visit gets its territory from its own `TerritoryId`, Step 10; the account↔territory link is carried by ProviderAcctTerritoryInfo, Step 6). If admin access is unavailable, it may be skipped without breaking the visit.
+
+**Step 6: Create ProviderAcctTerritoryInfo**
+
+```bash
+sf data create record --sobject ProviderAcctTerritoryInfo --values "AccountId='<accountId>' Territory2Id='<territory2Id>' PreferredAddressId='<contactPointAddressId>' IsActive=true IsAvailableOffline=true IsTargetedAccount=true SourceType='Manual'" --target-org lsc-rep --json
+```
+
+> Reference: `provideracctterritoryinfo.csv` — IsTargetedAccount=true, SourceType=Manual
+
+### Phase 3 — Create Product Records (Steps 7–9) — as ADMIN
+
+Products are master data. The rep's LSC Custom Profile has NO create permission on `Product2` / `LifeSciMarketableProduct` (as the rep, even `Name` reports `createable=false` and `Product2.ProductCode` is not visible), and `ProductTerritoryAvailability` also fails as the rep. Create all three **as the admin** (`--target-org <admin>`). If your rep genuinely must own products, grant the profile Create + field access first — but the default and recommended path is admin.
+
+**Step 7: Create Product2 (no RecordType) — as ADMIN**
+
+```bash
+sf data create record --sobject Product2 --values "Name='Immunexis 5mg' ProductCode='IM001-5' IsActive=true" --target-org <admin> --json
+```
+
+> Reference: `product2.csv` — Do NOT set a RecordType.
+
+**Step 8: Create LifeSciMarketableProduct — as ADMIN**
+
+```bash
+sf data create record --sobject LifeSciMarketableProduct --values "Name='Immunexis 5mg' ProductId='<product2Id>' IsActive=true IsAvlForSamplingAllocation=true Manufacturer='Makana Health' DistributionMethod='Drop' SignatureRequirementLevel='Mandatory' SortOrder=100 StartDate=2026-07-01 Type='Product'" --target-org <admin> --json
+```
+
+> Reference: `lifescimarketableproduct.csv` — Manufacturer=Makana Health, DistributionMethod=Drop
+
+**Step 9: Create ProductTerritoryAvailability — as ADMIN**
+
+```bash
+sf data create record --sobject ProductTerritoryAvailability --values "ProductId='<lifeSciMarketableProductId>' TerritoryId='<territory2Id>' AlignmentType='Territory Inclusion' Purpose='Visit' Status='Draft' UsageType='LifeSciences'" --target-org <admin> --json
+```
+
+> Reference: `productterritoryavailability.csv` — AlignmentType=Territory Inclusion, Purpose=Visit. After Step 9, switch back to the rep (`--target-org lsc-rep`) for the Visit chain (Steps 10–13) so the visit records are rep-owned.
+
+### Phase 4 — Create Visit Records (Steps 10–13)
+
+> **STOP-GATE (chain integrity).** Steps 10–13 are a strict dependency chain — each `sf data create record` returns an `id` that is a required input to the next step. After **every** create in this stage (Steps 2–13), confirm the response has `"success": true` and capture the real returned `id`. If any create fails, **STOP immediately** — do NOT continue with a null, empty, or placeholder ID (that produces an orphaned or mis-parented record chain that looks created but is broken). Report which step failed and its error. After Step 13, verify the full chain resolves: the ProviderVisitProdDiscussion → ProviderVisitProdDetailing → ProviderVisit → Visit → Account links must all be non-null.
+
+**Step 10: Create Visit (PlannedVisitStartTime = NOW)**
+
+```bash
+sf data create record --sobject Visit --values "AccountId='<accountId>' PlaceId='<contactPointAddressId>' PlannedVisitStartTime='<NOW_ISO8601>' Status='Planned' TerritoryId='<territory2Id>'" --target-org lsc-rep --json
+```
+
+> `<NOW_ISO8601>` = current datetime in ISO 8601 (e.g. `2026-08-01T10:30:00.000+0000`), generated at execution time with `date -u +"%Y-%m-%dT%H:%M:%S.000+0000"`.
+>
+> Reference: `visit.csv` — Status=Planned, linked to Account, Place, and Territory
+
+**Step 11: Create ProviderVisit**
+
+First, query the territory name:
+```bash
+sf data query --query "SELECT Name FROM Territory2 WHERE Id='<territory2Id>'" --target-org lsc-rep --json
+```
+
+Then create:
+```bash
+sf data create record --sobject ProviderVisit --values "VisitId='<visitId>' TerritoryName='<territoryName>' IsConfirmed=false" --target-org lsc-rep --json
+```
+
+
+**Step 12: Create ProviderVisitProdDetailing**
+
+```bash
+sf data create record --sobject ProviderVisitProdDetailing --values "ProviderVisitId='<providerVisitId>' ProductId='<lifeSciMarketableProductId>' Priority=4 AdditionalInformation='Discussed Oncology products and treatments' IsGeneratedFromPresentation=false" --target-org lsc-rep --json
+```
+
+> Reference: `providervisitproddetailing.csv` — Priority=4, AdditionalInformation about Oncology products
+
+**Step 13: Create ProviderVisitProdDiscussion**
+
+```bash
+sf data create record --sobject ProviderVisitProdDiscussion --values "ProviderVisitProductDtlId='<providerVisitProdDetailingId>' Note='Discussed Oncology treatments and patient care approaches'" --target-org lsc-rep --json
+```
+
+> Reference: `providervisitproddiscussion.csv` — Note about Oncology treatments
+
+### Phase 5 — Generate Metadata Cache (Steps 14–15) — as ADMIN
+
+This phase sets up a prerequisite metadata record and calls the Connect API to generate the metadata cache. No permission set is required — the generate Connect API bypasses the metadata validation itself, so validation-skip and generate permissions are not needed.
+
+**Step 14: Create LifeSciMobileMetadataRecord Prerequisite**
+
+Create a **parent** `LifeSciMobileMetadataRecord` record and a **child** record linked to the LSC Custom Profile (`ParentMobileMetadataRecId` + `ProfileId`). Set **both** to `Status = 'ValidationCompleted'` — the generate API rejects the call unless the **parent** is `ValidationCompleted`, not just the child. Extract the **parent** record ID — needed as `parentMetadataRecordId` in Step 15. Read `references/stage-5-visit-creation-metadata-cache-generation.md` for exact Apex and the schema-check command.
+
+**Step 15: Call the Metadata Generate Connect API**
+
+Use the CLI's own authenticated REST client — a hand-rolled `curl` fails with `INVALID_AUTH_HEADER`. The body accepts `parentMetadataRecordId`, `apiVersion`, and `prefix` (do NOT include `generateStandardTranslations` — it is rejected):
+
+Write the request body to a **project-local** relative file (never `/tmp` or any path outside the project) and remove it right after:
+
+```bash
+cat > .lsc-mdgen-body.json <<'EOF'
+{
+  "parentMetadataRecordId": "<parentRecordId>",
+  "apiVersion": "65.0",
+  "prefix": "lsc4ce"
+}
+EOF
+sf api request rest \
+  "/services/data/v65.0/connect/life-sciences/commercial/metadata/actions/generate" \
+  --method POST \
+  --body @.lsc-mdgen-body.json \
+  --target-org <admin>
+rm -f .lsc-mdgen-body.json
+```
+
+> Expected: HTTP 200 with `{ "message": "Task enqueued for metadata cache generation." }`. This only confirms the task was accepted — it is NOT the final success signal. Generation runs asynchronously; the metadata records' `Status` then transitions to `Active`. **`Active` is the success state** — wait for it before treating generation as complete. A transition to `Inactive` (or records stuck unchanged) means the job failed or never ran — check `IntegrationErrorMessage` and Setup → Apex Jobs. Verify with a query on `Status`. See `references/stage-5-visit-creation-metadata-cache-generation.md` for full details.
+
+---
+
+### Phase 6 — Manual iPad Mobile-App Validation (Step 16) — as REP (manual)
+
+The **final validation step (Step 16)** is **manual** — it can't be done programmatically. A tester installs the Life Sciences Cloud iPad app, logs in as the **rep**, and confirms the Visit is visible. Do this in order:
+
+1. **Display the Sales Rep credentials** — `Username: <repUsername>`, `Password: use the password you created`, and (only if the app prompts for a custom domain) `Login URL: <instanceUrl>`. Use the actual username/URL from this run — never invent them. **Do NOT print the password value**; refer to the password created during user provisioning. If the user lacks it, an admin can reset it; never substitute admin credentials.
+
+2. **Give the install/login/navigation instructions:** on the iPad, install "Life Sciences Cloud Mobile" from the App Store (<https://apps.apple.com/us/app/life-sciences-cloud-mobile/id6499238627>); open it and log in with the rep credentials; wait for the initial sync to finish (org data + metadata cache, 3–5 min on first login); then open the **Visits** tab and tap the Visit to view details.
+
+3. **Ask the confirmation prompt** — substitute the actual Visit Name and Account Name (auto-generated here as Visit `00000001`, Account `Dr. Aaron Morita`): **"Do you see the Visit '00000001' for Account 'Dr. Aaron Morita' in the iPad app?"**
+
+4. **Handle the response:** **YES** → mark Step 16 `confirmed`; this is the **end of the LSC setup in the org** — report success (Phase 7) and stop. **Issue reported** → mark `issue`, walk the troubleshooting steps below, then re-ask.
+
+**Troubleshooting (only if the Visit is not visible):** verify each of these (`--target-org <admin>`), fix any that fail, have the tester force a re-sync (pull-to-refresh on the Visits list, or log out/in), then re-ask the prompt: (1) rep assigned to the level-3 territory (`UserTerritory2Association`) — else assign via Stage 4 (User Provisioning); (2) `ProviderAcctTerritoryInfo` exists for the Account + territory and `IsActive=true` — else (re)create Step 6; (3) `LifeSciMobileMetadataRecord` records are `Status='Active'` — else re-run Steps 14–15. Common root cause: the app synced **before** the territory assignment, ProviderAcctTerritoryInfo, or metadata cache existed. Exact queries/fixes are in `references/stage-5-visit-creation-visit-creation-data.md`.
+
+---
+
+## Phase 7 — Summary
+
+After all records are created, display the completion summary — Account details, Visit details, and a 16-step record-creation summary with each record ID, ending with "Created as user: `<repUsername>`" and the iPad confirmation line. The exact ASCII template is in `references/stage-5-visit-creation-execution-state-and-recovery.md`; substitute the actual IDs and values from the run.
+
+> **Keep the summary to that block.** Do NOT append notes that describe the underlying data, its shape (row/record counts, hierarchy levels), specific product/record names or IDs, or commentary comparing the source data to the skill's examples. End at the summary; no "worth noting for future runs" addendum.
+
+---
+
+## Smoke-Test-Failure Recovery
+
+If any step fails, immediately perform auto-diagnosis: show **What happened** (exact CLI error), **Why**, **Possible causes**, **What I can do** (retry / skip / auto-fix / stop), and a **partial-success status** (completed N-1/16, failed step, records created so far). **Wait for user choice before continuing — do NOT silently skip failed steps.**
+
+The failure-report template and the full auto-diagnosis error table (error pattern → diagnosis → auto-fix, covering `INVALID_TYPE`, `INVALID_FIELD`, `INSUFFICIENT_ACCESS_OR_READONLY`, `DUPLICATE_VALUE`, the Step 15 Connect API errors, etc.) are in `references/stage-5-visit-creation-execution-state-and-recovery.md`.
+
+---
+
+## Rules / Constraints
+
+Load-bearing rules (full table with rationales in `references/stage-5-visit-creation-execution-state-and-recovery.md`):
+
+- **`.lsc-starter-config/LSStarterConfig/` must already be present in the CWD — do NOT download or delete it.** That folder's download/cleanup is owned by `life-sciences-fieldsalesrep-coordinate`.
+- **Read the `.lsc-starter-config/LSStarterConfig/Data/` CSV for each object and use ONLY its values** — at execution time, one record per row; never hardcode field values or reuse a prior run's. The CSVs are the single source of truth.
+- **Ownership split:** create the **visit records** (Account, HealthcareProvider, ContactPointAddress, ProviderAcctTerritoryInfo, Visit, ProviderVisit, detailing, discussion) as the rep (`--target-org lsc-rep`); create **territory associations (Step 5), product master data (Steps 7–9), and metadata cache (Steps 14–15) as the admin** (`--target-org <admin>`) — the LSC Custom Profile can't create those.
+- **Ask for rep credentials — never assume or reuse admin credentials.**
+- Create records in exact order 2→15, then run the manual iPad validation (Step 16) last; earlier IDs feed later records and the metadata cache must exist before the app can sync the Visit.
+- **Step 16 is manual** — show rep credentials (ask for the password if unknown; never use admin creds), give instructions, and never claim it's done without the user's explicit "yes"; on a reported issue, run the troubleshooting checks before re-asking.
+- `PlannedVisitStartTime` must be NOW; Product2 must NOT have a RecordType.
+- Show diagnosis on every failure and wait for the user's decision — no silent skips.
+
+---
+
+## Gotchas
+
+Common failures and fixes — missing RecordTypes/objects, rep-vs-admin FLS on HealthcareProvider (NPI/IsSpeaker) and product master data, ISO 8601 date formats, the Step 14 profile/metadata prerequisites, and the Step 15 Connect API errors — are tabulated in `references/stage-5-visit-creation-execution-state-and-recovery.md`.
+
+---
+
+## Output Expectations
+
+Deliverables:
+- Authenticated as the Sales Rep (not admin); all 13 visit-chain records created in dependency order (Account → ProviderVisitProdDiscussion).
+- LifeSciMobileMetadataRecord parent + child (child linked to the LSC Custom Profile), both `Status='ValidationCompleted'`; cache generation enqueued via Connect API and confirmed complete when the records reach `Status='Active'`.
+- Manual iPad validation guided (rep creds shown, instructions given, confirmation prompt asked); a "yes" closes out setup, an issue triggers troubleshooting.
+- Completion summary displayed (Account + Visit details, all record IDs). On failure: auto-diagnosis (What/Why/Causes/Actions) + partial-success status.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/stage-5-visit-creation-visit-creation-data.md` | Default field values for all records (sourced from CSV files); also the Step 16 manual iPad validation checklist and troubleshooting queries |
+| `references/stage-5-visit-creation-metadata-cache-generation.md` | During Phase 5 (Steps 14–15) — exact Apex and `sf api request rest` commands for metadata cache generation |
+| `references/stage-5-visit-creation-execution-state-and-recovery.md` | The full creation-state model, the smoke-test-failure recovery template + auto-diagnosis error table, and the gotchas table |

package/skills/life-sciences-fieldsalesrep-coordinate/references/stage-5-visit-creation-visit-creation-data.md

@@ -0,0 +1,211 @@
+# Visit Creation Data Reference
+
+> **Read the CSVs — do not treat these tables as authoritative.** The values below are a **snapshot** of one export of the `.lsc-starter-config/LSStarterConfig/Data/` CSV files, kept for orientation only. At execution time you MUST read the actual CSV file for each object and use **only** the values it currently contains (one record per row). If a CSV differs from a table here — added/removed columns, changed values, extra rows — the **live CSV wins**. Never hardcode these values or reuse values from a previous run.
+>
+> **Do NOT narrate the difference to the user.** The example values here (e.g. `Immunexis 5mg`) are illustrative placeholders, not data — silently use whatever the live CSV contains and never tell the user that the live data differs from these examples, name a specific CSV row, or comment that the real product is a hierarchy rather than the sample product. Announcing the mismatch leaks internal data structure into user-facing output (against the "never mention the CSVs or underlying data in user-facing notes" rule) and adds noise. Just read the CSV and create the records.
+
+Field values for all records, sourced from `.lsc-starter-config/LSStarterConfig/Data/` CSV files.
+
+## Source folder & object→CSV mapping
+
+The CSVs come from the public repo <https://github.com/SalesforceLabs/LSStarterConfig.git>. As an embedded Stage 5, this stage is a pure consumer of the `.lsc-starter-config/LSStarterConfig/` folder and MUST NOT download or delete it — the coordinator (`life-sciences-fieldsalesrep-coordinate`) is the sole owner of the single download (at the start of the run) and the single delete (at the end). If the folder is not present when this stage runs, stop and report that it must be provisioned by the coordinator; do not fetch it here.
+
+Each object maps to a CSV named for the sobject (lowercased) under `.lsc-starter-config/LSStarterConfig/Data/`:
+
+| Object | CSV file |
+|---|---|
+| Account | `account.csv` |
+| HealthcareProvider | `healthcareprovider.csv` |
+| ContactPointAddress | `contactpointaddress.csv` |
+| ObjectTerritory2Association | `objectterritory2association.csv` |
+| ProviderAcctTerritoryInfo | `provideracctterritoryinfo.csv` |
+| Product2 | `product2.csv` |
+| LifeSciMarketableProduct | `lifescimarketableproduct.csv` |
+| ProductTerritoryAvailability | `productterritoryavailability.csv` |
+| Visit | `visit.csv` |
+| ProviderVisit | `providervisit.csv` |
+| ProviderVisitProdDetailing | `providervisitproddetailing.csv` |
+| ProviderVisitProdDiscussion | `providervisitproddiscussion.csv` |
+
+## Account (RecordType: Health_Care_Provider)
+
+| Field | Value | Source |
+|-------|-------|--------|
+| FirstName | Aaron | account.csv |
+| LastName | Morita | account.csv |
+| Salutation | Dr. | account.csv |
+| RecordType DeveloperName | Health_Care_Provider | account.csv |
+| IsActive | True | account.csv (standard `IsActive` boolean — NOT `IsActive__c`) |
+
+> Created as the **rep** (`--target-org lsc-rep`). `IsActive` is the standard field; if the rep lacks FLS to it, omit and set as admin.
+
+## HealthcareProvider
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | Aaron Morita HP | healthcareprovider.csv |
+| IsActive | True | healthcareprovider.csv |
+| IsPrimaryProvider | True | healthcareprovider.csv |
+| ProviderType | Medical Doctor | healthcareprovider.csv |
+| Status | Active | healthcareprovider.csv |
+| AccountId | (from Step 2) | FK |
+
+> Do NOT set `NationalProviderIdentifier` or `IsSpeaker` on creation. Both — along with `IsActive` — are gated by field-level security on the LSC Custom Profile; if the rep lacks FLS the create fails. `IsSpeaker` and `NationalProviderIdentifier` are not required for the visit, so omit them (an admin can set them later). The CSV lists them because it was exported from an org where the profile had FLS to those fields.
+
+## ContactPointAddress
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | 415 Mission St | contactpointaddress.csv |
+| AddressType | Billing | contactpointaddress.csv |
+| Street | 415 Mission St | contactpointaddress.csv |
+| City | San Francisco | contactpointaddress.csv |
+| State | California | contactpointaddress.csv |
+| StateCode | CA | contactpointaddress.csv |
+| PostalCode | 94105 | contactpointaddress.csv |
+| Country | United States | contactpointaddress.csv |
+| CountryCode | US | contactpointaddress.csv |
+| Latitude | 37.789853 | contactpointaddress.csv |
+| Longitude | -122.396806 | contactpointaddress.csv |
+| IsActive | True | contactpointaddress.csv |
+| IsPrimary | True | contactpointaddress.csv |
+| UsageType | Work | contactpointaddress.csv |
+| ParentId | (from Step 2 — Account) | FK |
+
+## ObjectTerritory2Association
+
+| Field | Value | Source |
+|-------|-------|--------|
+| ObjectId | (from Step 2 — Account) | FK |
+| Territory2Id | (queried — level-3 territory) | FK |
+| AssociationCause | Territory2Manual | objectterritory2association.csv |
+
+> Create as **admin** (`--target-org <admin>`) — the rep profile lacks "Manage Territories" so OT2A is `createable=false` for the rep. Not referenced by any later record; may be skipped if admin access is unavailable.
+
+## ProviderAcctTerritoryInfo
+
+| Field | Value | Source |
+|-------|-------|--------|
+| AccountId | (from Step 2) | FK |
+| Territory2Id | (queried — level-3 territory) | FK |
+| PreferredAddressId | (from Step 4 — ContactPointAddress) | FK |
+| IsActive | True | provideracctterritoryinfo.csv |
+| IsAvailableOffline | True | provideracctterritoryinfo.csv |
+| IsTargetedAccount | True | provideracctterritoryinfo.csv |
+| SourceType | Manual | provideracctterritoryinfo.csv |
+
+## Product2 (NO RecordType)
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | Immunexis 5mg | product2.csv |
+| ProductCode | IM001-5 | product2.csv |
+| IsActive | True | product2.csv |
+
+> Do NOT set RecordTypeId — this is an explicit requirement.
+> Create as **admin** — the rep profile has no create permission on Product2 (`Name` is `createable=false`, `ProductCode` invisible for the rep). Steps 7–9 (Product2, LifeSciMarketableProduct, ProductTerritoryAvailability) are all admin-owned master data.
+
+## LifeSciMarketableProduct
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | Immunexis 5mg | lifescimarketableproduct.csv |
+| ProductId | (from Step 7 — Product2) | FK |
+| IsActive | True | lifescimarketableproduct.csv |
+| IsAvlForSamplingAllocation | True | lifescimarketableproduct.csv |
+| Manufacturer | Makana Health | lifescimarketableproduct.csv |
+| DistributionMethod | Drop | lifescimarketableproduct.csv |
+| SignatureRequirementLevel | Mandatory | lifescimarketableproduct.csv |
+| SortOrder | 100 | lifescimarketableproduct.csv |
+| StartDate | 2026-07-01 | lifescimarketableproduct.csv |
+| Type | Product | lifescimarketableproduct.csv |
+
+## ProductTerritoryAvailability
+
+| Field | Value | Source |
+|-------|-------|--------|
+| ProductId | (from Step 8 — LifeSciMarketableProduct) | FK |
+| TerritoryId | (queried — level-3 territory) | FK |
+| AlignmentType | Territory Inclusion | productterritoryavailability.csv |
+| Purpose | Visit | productterritoryavailability.csv |
+| Status | Draft | productterritoryavailability.csv |
+| UsageType | LifeSciences | productterritoryavailability.csv |
+
+## Visit
+
+| Field | Value | Source |
+|-------|-------|--------|
+| AccountId | (from Step 2) | FK |
+| PlaceId | (from Step 4 — ContactPointAddress) | FK |
+| PlannedVisitStartTime | NOW (generated at runtime) | requirement |
+| Status | Planned | visit.csv |
+| TerritoryId | (queried — level-3 territory) | FK |
+
+## ProviderVisit
+
+| Field | Value | Source |
+|-------|-------|--------|
+| VisitId | (from Step 10) | FK |
+| TerritoryName | (queried territory Name) | providervisit.csv |
+| IsConfirmed | False | providervisit.csv |
+
+## ProviderVisitProdDetailing
+
+| Field | Value | Source |
+|-------|-------|--------|
+| ProviderVisitId | (from Step 11) | FK |
+| ProductId | (from Step 8 — LifeSciMarketableProduct) | FK |
+| Priority | 4 | providervisitproddetailing.csv |
+| AdditionalInformation | Discussed Oncology products and treatments | providervisitproddetailing.csv |
+| IsGeneratedFromPresentation | False | providervisitproddetailing.csv |
+
+## ProviderVisitProdDiscussion
+
+| Field | Value | Source |
+|-------|-------|--------|
+| ProviderVisitProductDtlId | (from Step 12) | FK |
+| Note | Discussed Oncology treatments and patient care approaches | providervisitproddiscussion.csv |
+
+---
+
+## Manual iPad Mobile-App Validation (Step 16)
+
+Final, **manual** step — a tester logs into the Life Sciences Cloud iPad app as the **rep** and confirms the Visit is visible.
+
+- **App Store**: Life Sciences Cloud Mobile — <https://apps.apple.com/us/app/life-sciences-cloud-mobile/id6499238627>
+- **Login**: open the app, log in with the rep credentials, wait for the initial sync (downloads org data + mobile metadata cache; 3-5 minutes on first login), then land on the Home page.
+- **Navigate**: Home page → **Visits** tab (list of Visits) → tap the Visit name/row → Visit details.
+- **Confirmation prompt**: "Do you see the Visit '00000001' for Account 'Dr. Aaron Morita' in the iPad app?" (substitute the actual Visit Name and Account Name from the run).
+
+### Troubleshooting (Visit not visible)
+
+| Check | How to verify | Fix |
+|---|---|---|
+| Rep is assigned to the level-3 territory | `SELECT Id, Territory2.Name FROM UserTerritory2Association WHERE UserId = '<repUserId>'` | If missing, assign via Stage 4 (User Provisioning) |
+| `ProviderAcctTerritoryInfo` exists for the Account + territory | `SELECT Id, AccountId, Territory2Id, IsActive FROM ProviderAcctTerritoryInfo WHERE AccountId = '<accountId>'` | If missing/inactive, (re)create Step 6 with `IsActive=true`, `IsAvailableOffline=true` |
+| Mobile sync metadata cache available and current | `SELECT Id, Status, LastModifiedDate FROM LifeSciMobileMetadataRecord ORDER BY LastModifiedDate DESC` | Records must be `Status='Active'`; if not, re-run Steps 14–15, then re-sync on the iPad |
+
+> Common root cause: the app synced **before** the territory assignment, `ProviderAcctTerritoryInfo`, or metadata cache existed. After fixing the data, have the tester **force a re-sync** (pull-to-refresh on the Visits list, or log out and back in), then re-ask the confirmation prompt.
+
+---
+
+## Dependency Chain
+
+```text
+Account (Step 2)
+├── HealthcareProvider (Step 3) — AccountId
+├── ContactPointAddress (Step 4) — ParentId
+├── ObjectTerritory2Association (Step 5) — ObjectId
+├── ProviderAcctTerritoryInfo (Step 6) — AccountId, PreferredAddressId (Step 4)
+└── Visit (Step 10) — AccountId, PlaceId (Step 4), TerritoryId
+
+Product2 (Step 7)
+└── LifeSciMarketableProduct (Step 8) — ProductId
+    └── ProductTerritoryAvailability (Step 9) — ProductId (Step 8)
+    └── ProviderVisitProdDetailing (Step 12) — ProductId (Step 8)
+
+Visit (Step 10)
+└── ProviderVisit (Step 11) — VisitId
+    └── ProviderVisitProdDetailing (Step 12) — ProviderVisitId
+        └── ProviderVisitProdDiscussion (Step 13) — ProviderVisitProductDtlId
+```

package/skills/life-sciences-fieldsalesrep-coordinate/references/state-machine-and-changes.md

@@ -0,0 +1,108 @@
+# Orchestration State Machine & Change Handling
+
+Operational reference for `life-sciences-fieldsalesrep-coordinate`: the idempotent stage-transition rules, the mid-flow change-request impact assessment, and the resume/partial-re-run protocol. Read this alongside the workflow in `SKILL.md`.
+
+---
+
+## Idempotent Stage Transitions
+
+Stages are **not re-entrant**. If the user says "Proceed" or names a stage that is already running or completed, do NOT re-execute it.
+
+### Behavior Matrix
+
+| Current stage status | User says "Proceed" / "Run Stage N" | Response |
+|---|---|---|
+| `running` | Duplicate trigger | "Stage N is already in progress — I'll let you know when it completes." |
+| `passed` | Re-run request | "Stage N already completed successfully. Would you like to re-run it anyway? This is safe (all stages are idempotent) but will take extra time." |
+| `failed` | Retry request | Allow — re-run the stage (this is intentional recovery) |
+| `pending` | Advance request | Allow — normal forward progression |
+
+### Implementation Rules
+
+1. **Before executing any stage**, check its current `status` in `OrchestrationState`.
+2. **If `running`**: reply with the in-progress message and take no action. Do not queue a second execution.
+3. **If `passed`**: ask for explicit confirmation before re-running. Only re-run if the user says "yes, re-run it".
+4. **If `failed`**: treat as a retry — re-run without extra confirmation (the user is explicitly recovering).
+5. **Accidental double-confirms** (user says "yes" or "proceed" twice in quick succession) must never cause a stage to execute twice. The `status` field is the single source of truth — transition to `running` at the START of execution, not on user input.
+
+---
+
+## Mid-Flow Change Requests (Impact Assessment)
+
+If the user requests a change to inputs or decisions made in an earlier stage **while a later stage is in progress or pending**, perform an impact assessment before applying the change.
+
+### When This Applies
+
+- User wants to change the target org mid-flow
+- User wants to change territory names after territories were already deployed
+- User wants to change the new user's details after the profile/permsets were chosen
+- User wants to switch which layouts or flexipages were selected after deploy
+
+### Impact Assessment Protocol
+
+1. **Acknowledge the change request** without applying it immediately.
+
+2. **Identify affected stages** — determine which completed or in-progress stages would be impacted:
+
+   ```text
+   Change Request Impact Assessment
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   
+   Requested change: <describe the change>
+   
+   Stages affected:
+     Stage <N>: <StageName> — <what would need to change/redo>
+     Stage <M>: <StageName> — <downstream impact>
+   
+   Stages NOT affected:
+     Stage <X>: <StageName> — no impact
+   
+   Estimated rework: <time/effort to re-do affected stages>
+   ```
+
+3. **Present options** to the user:
+   - **Apply change and re-run affected stages** — will undo/redo the impacted work
+   - **Apply change for remaining stages only** — keep what's done, apply change going forward (if possible without inconsistency)
+   - **Cancel the change** — continue with original inputs
+
+4. **Wait for user decision** before taking any action.
+
+### Impact Mapping
+
+| Change | Affects Stages | Re-run Required | Notes |
+|--------|--------------|-----------------|-------|
+| Target org | All stages | Yes — full restart | Nothing from prior org transfers |
+| Territory names | Stage 3, Stage 4 | Stage 3 re-deploy + Stage 4 re-assign | Existing model may need new territories added |
+| User details (name, email, username) | Stage 4, Stage 5 | Stage 4 + Stage 5 re-login | Stage 5 logs in as this rep; a new user means re-authenticating |
+| Profile choice | Stage 4 only | Stage 4 only | Profile must exist (from Stage 2) |
+| Layout/flexipage selection | Stage 2 only | Re-deploy updated profile + app | Does not affect Stages 3-4 |
+| Permission set list | Stage 4 only | Stage 4 only | Can add/remove assignments |
+
+### Destructive Change Warnings
+
+Some changes cannot be fully undone:
+
+| Change | Warning |
+|--------|---------|
+| Territory model already activated | "The territory model cannot be deleted once activated. A new model with a different name can be created, but the old one will remain." |
+| User already created | "The existing user will remain. A new user with different details will be created as a separate record." |
+| Config records already deployed | "Config records are upsert-safe — re-deploying with changes will update existing records, not create duplicates." |
+
+Always surface these warnings as part of the impact assessment so the user makes an informed decision.
+
+---
+
+## Resume / Partial Re-run
+
+If the user has already completed some stages (e.g., from a prior session):
+
+1. Ask: "Have you already completed any of these stages?"
+2. For each claimed-complete stage, **verify** by querying the org:
+   - Stage 1: Ask user to confirm prerequisites are met
+   - Stage 2: Query for `LSC Custom Profile`
+   - Stage 3: Query for active territory model with level-3 territory
+   - Stage 4: Query for the user with correct profile and permsets
+   - Stage 5: Query for an existing `Visit` record (`SELECT Id FROM Visit LIMIT 1`)
+3. Skip verified stages and resume from the first incomplete one.
+
+(The exact detection queries per stage are in `orchestration-flow.md` → Resume Logic.)