lsc-troubleshoot
Skill10 starsChanged 29 days agoApache-2.0View on GitHub
Diagnoses and resolves Life Sciences Cloud (LSC) issues. Use when user reports errors, unexpected behavior, or needs help debugging LSC configurations, FlexCards, OmniScripts, or Salesforce org issues.
In this repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- roz-uiSkill
- lsc-account-managementSkill
- lsc-activity-planSkill
- lsc-agentforceSkill
- lsc-app-alertsSkill
- lsc-briefingsSkill
- lsc-calendar-tot-routineSkill
- lsc-config-migrationSkill
- lsc-consent-managementSkill
- lsc-custom-scriptsSkill
- lsc-data-migrationSkill
- lsc-data-modelSkill
- lsc-db-schemaSkill
- lsc-demo-data-loadingSkill
- lsc-events-managementSkill
- lsc-field-emailSkill
- lsc-health-checkSkill
- lsc-home-page-configurationSkill
- lsc-implementation-reviewSkill
- lsc-implementationSkill
- lsc-integration-patternsSkill
- lsc-intelligent-contentSkill
- lsc-key-account-managementSkill
- lsc-lists-filtersSkill
- lsc-mobile-app-settingsSkill
- lsc-mobile-validationSkill
- lsc-next-bestSkill
- lsc-performance-validationSkill
- lsc-product-managementSkill
- lsc-provider-engagement-complianceSkill
- lsc-quick-actions-configurationSkill
- lsc-reporting-analyticsSkill
- lsc-sample-managementSkill
- lsc-surveysSkill
- lsc-territory-alignmentSkill
- lsc-user-managementSkill
- lsc-visit-managementSkill
- salesforce-querySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
33 rules. About 0 are common, 15 are distinctive, and 18 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
18
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
When did it start happening?
- Very specific: line 88
If yes: use toggle_trigger_handler, update_admin_setting, or create_admin_setting to make the change
- Distinctive: line 89
Always confirm with the user before applying each change
- Distinctive: line 90
After applying the fix, verify it resolved the issue by re-checking the configuration
- Distinctive: line 102
Check PTDAs exist for the rep's territory:
- Distinctive: line 108
Must include both Brand-level AND sample-level marketable products.
- Very specific: line 110
Check sample-level marketable products have: Type = 'Product', DistributionMethod set (Drop/Ship/DropAndShip), ParentBrandProductId …
- Very specific: line 111
Check rep has ProductItem records in their User Inventory Location.
- Very specific: line 112
Check TerritoryProdtQtyAllocation records exist with current TimePeriod and OwnerId = rep (Private sharing).
- Very specific: line 114
After signature, iPad Add Another or the side menu still adds a sample the Product Item dropdown hides: follow lsc-visit-management Signed …
- Distinctive: line 139
Products not appearing in Product Details: Check the PTDA → Marketable Product chain:
- Distinctive: line 143
If PTAs exist but PTDAs don't, run the alignment batch job from Admin Console > Product (tile) > Product Alignment Jobs
- Very specific: line 171
Check that CalendarEvent_* config records exist and are active:
- Very specific: line 177
Check that PlannerAdministration_* config records exist:
- Very specific: line 183
Verify the DbSchema_CalendarEvent and DbSchema_PlannerAdministration records exist:
- Distinctive: line 189
If records are missing, re-run the Calendar/Planner setup in Admin Console to regenerate them
- Very specific: line 227
Check IsLicenseValidated — is it true?
- Very specific: line 228
If false: check PeriodStart — is it set?
- Very specific: line 229
If false and ComplianceScope is Address: check linked CPA's IsActive
- Very specific: line 230
If State badge is red but IsLicenseValidated = true: check JurisdictionState — must match the CPA's state code
- Very specific: line 238
ProviderAcctTerritoryInfo.Territory2Id: must point to the leaf territory (not a parent) - Very specific: line 239
ProviderAcctTerritoryInfo: must have LSC4CEAutoShare sharing rule for the territory group (manually created records don't get this … - Very specific: line 273
Check ProviderAcctTerritoryInfo.Territory2Id points to the correct leaf territory (the dbschema filter matches Territory2.Name = …
- Very specific: line 274
Check LSC4CEAutoShare exists on the ProviderAcctTerritoryInfo record
- Very specific: line 275
Check PrvdAccountTerritorySummary records exist (one per user in the territory)
- Distinctive: line 357
After deploy, regenerate the mobile metadata cache for the affected profile(s) and re-sync the device.
- Distinctive: line 360
If the record simply has no/wrong record type, set it to the one whose layout already has the related list:
- Distinctive: line 366
No cache regen needed — just re-sync the device so the new record type's layout takes effect.
- Distinctive: line 380
Check relevant Admin Console settings
- Very specific: line 381
Use describe_sobject to verify object structure
- Distinctive: line 382
Verify data integrity with SOQL queries
- Distinctive: line 384
Test in isolation if possible
- Distinctive: line 385
Document the fix for future reference
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
LSC Troubleshooting Expert
You are an expert at diagnosing and resolving LSC issues.
Troubleshooting Approach
- Gather information:
- What module/feature is affected?
- What is the expected vs actual behavior?
- When did it start happening?
- Any recent changes to configuration?
- Start with
diagnose_lsc_issue, passing the exact error text or the user's description of the symptom (paste the whole error, including object and field names). It matches the symptom against known causes found in real cases, mostly misconfigurations, and the validation rules. When an org is connected, it runs their checks and reports which causes are in the org, with the records to fix. Lead with what it found. A cause marked "This is how LSC works" is behaviour to explain, not a bug to fix. Investigate by hand only what it couldn't check. - Use LSC tools to investigate further:
search_lsc_knowledgeto find relevant documentationget_lsc_module_docsfor module-specific guidanceget_lsc_admin_setupfor configuration requirementsget_lsc_troubleshooting({ topic: "implementation-anti-patterns" })for design/config anti-patterns — check this first for post-go-live incidents (Sev-1, API-limit "death loops", duplicate visits, inventory-count failures): these are config/design issues far more often than product bugs. For a broad design review, use thelsc-implementation-reviewskill.
- If connected to an org, look further with:
describe_sobjectto verify object/field setup (always verify API names first)run_soqlto check data and configurationsget_recordto inspect specific recordslist_trigger_handlersto check if required trigger handlers are enabledlist_admin_settingsto check Admin Console configurationtoggle_trigger_handlerto enable/disable trigger handlers as needed
Querying LifeSciConfigRecord (Admin Console Configuration)
LSC Admin Console settings are stored in LifeSciConfigRecord and LifeSciConfigCategory objects. These are Tooling API-only objects and cannot be queried via standard SOQL.
Important:
- Standard SOQL queries against
LifeSciConfigRecordwill fail withINVALID_TYPE describe_sobjectwill fail withNOT_FOUND- You MUST use the Tooling API (API v65 or above) to query these objects
How to query via SF CLI:
sf data query --use-tooling-api --query "SELECT Id, DeveloperName, MasterLabel, IsActive, IsOrgLevel, Type FROM LifeSciConfigRecord" --api-version 65.0Key fields on LifeSciConfigRecord:
DeveloperName— Uses{Category}_{Suffix}naming convention (e.g.,CalendarEvent_PlannedEvent)LifeSciConfigCategoryId— Reference to the parentLifeSciConfigCategoryType— e.g., "CONFIGURATION"IsOrgLevel/IsActive— Status flags- There is NO
ValueorMetadatafield — the record acts as a metadata definition; actual config values are managed internally by the Admin Console
LifeSciConfigCategory defines groupings:
Categorypicklist — e.g., "CalendarEvent", "PlannerAdministration", "DbSchema", "QuickAction"Typepicklist — "List" (flat enumeration) or "Hierarchical" (org-level with profile overrides)
Useful diagnostic queries (Tooling API):
-- List all config categories
SELECT Id, DeveloperName, Category, Type FROM LifeSciConfigCategory
-- List all config records for a specific category
SELECT Id, DeveloperName, MasterLabel, IsActive, IsOrgLevel
FROM LifeSciConfigRecord
WHERE DeveloperName LIKE 'CalendarEvent_%'
-- List Planner Administration settings
SELECT Id, DeveloperName, MasterLabel, IsActive, IsOrgLevel
FROM LifeSciConfigRecord
WHERE DeveloperName LIKE 'PlannerAdministration_%'- When the fix involves configuration changes, offer to apply them:
- "I found the issue: [handler/setting] is disabled/misconfigured. Want me to fix it?"
- If yes: use
toggle_trigger_handler,update_admin_setting, orcreate_admin_settingto make the change - Always confirm with the user before applying each change
- After applying the fix, verify it resolved the issue by re-checking the configuration
Common Issue Categories
OmniStudio Issues (Web Only)
- OmniStudio components (FlexCards, OmniScripts, DataRaptors) are NOT available in the LSC Mobile app (iPad). Only suggest OmniStudio troubleshooting for web-based issues.
- FlexCard not displaying: Check DataRaptor, permissions, cache
- OmniScript errors: Validate step configuration, integration procedures
- Performance issues: Check DataRaptor queries, caching settings
Sample Management
- Samples panel "No items found" (most common): The #1 cause is missing
ProductTerrDtlAvailability(PTDA) records for sample-level marketable products. Diagnosis steps:- Check PTDAs exist for the rep's territory:
Must include both Brand-level AND sample-level marketable products.SELECT ProductId, Product.Name, SortOrder FROM ProductTerrDtlAvailability WHERE TerritoryId = '<territory-id>' - If PTDAs are missing: check that
ProductTerritoryAvailability(PTA) records exist for sample-level marketable products at a parent territory (e.g.,GB-COUNTRY) withAlignmentType = 'Territory and Subordinates Inclusion'. UsingTerritory Inclusionat a leaf territory does NOT create PTDAs. Then run the alignment batch job from Admin Console > Product (tile) > Product Alignment Jobs. - Check sample-level marketable products have:
Type = 'Product',DistributionMethodset (Drop/Ship/DropAndShip),ParentBrandProductIdpointing to the Brand,ProductSpecificationType = 'LSSampleProduct'. - Check rep has
ProductItemrecords in their User InventoryLocation. - Check
TerritoryProdtQtyAllocationrecords exist with currentTimePeriodandOwnerId = rep(Private sharing).
- Check PTDAs exist for the rep's territory:
- SortOrder on PTDA is NOT required — null SortOrder does not block samples. This is a known red herring.
- After signature, iPad Add Another or the side menu still adds a sample the Product Item dropdown hides: follow
lsc-visit-managementSigned Add Another.SamplesPlugin.canInsertForGroupandProductMenuBlocignore the signature rule. This is an iPad defect, not a web defect. Seesupport-engineering-visit-signed-add-another.md. - Visit Engagement shows a lookup label that ends in ID, and the user must pick a parent: follow
lsc-visit-managementLookup ID suffix. AProviderVisitProdDetailingfield on the layout forces a parent pick. Remove the field. Do not call this a label regression. Seesupport-engineering-visit-lookup-id-suffix.md. - iOS throws a data inconsistency error on a Visit when a custom field has the same API name on
VisitandProviderVisit: followlsc-visit-managementDuplicate field API name. The mobile app shows the Visit copy. Remove the duplicate. Do not start with a metadata cache or aLifeSciMetadataRecordoverride. Seesupport-engineering-visit-duplicate-field-api.md. - Visit Engagement allows removing an attendee who has samples, and the visit stays removed until undo: follow
lsc-visit-managementAttendee remove with samples. The client blocks only a signed visit. Sample protection is server-only. Visit Action Validation has no removal event. Working as designed. Do not claim anOnDeletehook. Seesupport-engineering-visit-attendee-remove-samples.md. - Visit expense allocation fails with Script-thrown exception or
REQUIRED_FIELD_MISSING [Name]onExpenseParticipant: followlsc-visit-managementExpense participant name. A missingExpenseParticipantNameHandlerrecord leaves the handler inactive. Setup does not create system-handler records. Open a support case. Do not create the row. Seesupport-engineering-visit-expense-participant-name.md. - Samples (Product Disbursements) are disabled for an HCP attendee on an HCO visit: follow
lsc-visit-managementAttendee sample address. The attendee's primary address does not match the parent visit address. Working as designed. Do not lead withHcoTypesForSamplesAndItemsor a profile override. Seesupport-engineering-visit-attendee-sample-address.md. - Web and iPad show different names for the same product in the Samples, Direct to Practitioner, or Items dropdown: follow
lsc-visit-managementProduct name fields. Web Apex usesProduct2.Name. iOS usesLifeSciMarketableProduct.Name. The saved Product2 id matches. Set both names equal. Do not say the web LWC reads the marketable-product name. Seesupport-engineering-visit-product-name-fields.md. - Web Visit Details shows Account ID, Place ID, or Record Type ID, and iPad does not: follow
lsc-visit-managementDetails ID label.lightning-output-fieldsets no label, so the page shows the API label. The mobile app uses the field label. Do not attribute it to a Setup label override. Seesupport-engineering-visit-details-id-label.md. - Desktop on package 264 shows the raw key
NextVisitObjectiveLabel: followlsc-visit-managementNext visit objective label. en_US dropped that key from the LSC translations document in a dedupe-by-text collision, and 264 no longer falls back to REST. Do not call this a missing package label or an org locale. Seesupport-engineering-visit-next-objective-label.md. - Web Samples and Direct to Practitioner do not render after a product is selected, and iPad does: follow
lsc-visit-managementSample DTP locale. The org locale is the old JDK valueen_IE_EURO. Switch to the ICU locale. Do not add a related list to the Provider Visit layout. Seesupport-engineering-visit-sample-dtp-locale.md. - A Visit quick action is missing on iPad, or the button shows and the layout will not open: follow
lsc-quick-actions-configurationVisit Highlights Panel action. iPad reads the FlexiPage Highlights Panel. TheSalesforceTestingpackaged page lacksCancel_visit. Add the action or assign another page. Do not start with a GoTo target or a metadata cache. Seesupport-engineering-visit-highlights-action.md. - iPad crashes when editing a Presentation Forum on package 262: follow
lsc-visit-managementForum edit crash. The handler passes the forum id, not the parent Visit id, toeditCoordinator, andfatalErrorcrashes the app. Package 264 passesForumReferenceId. Do not stop at a request for a crash log. Seesupport-engineering-visit-forum-edit-crash.md. - Provider Visit Information merged fields are empty: follow
lsc-visit-managementInformation detail field.ProviderVisitProductDtlIdis on the Provider Visit layout. Remove it. Do not stop at a layout or rendering hypothesis. Seesupport-engineering-visit-information-dtl-field.md. - Visit Engagement still shows the old Samples label after Rename Tabs and Labels: follow
lsc-visit-managementRenamed label. Standard Label Translations were last refreshed before the rename. Re-generate the document. Do not say the component bypasses Rename Tabs and Labels. Seesupport-engineering-visit-renamed-label.md. - iPad Provider Visit New or Edit has no section header, and the fields are on screen: follow
lsc-visit-managementiPad section header.BaseLayoutViewModelflattens every section into one with an empty label andeditHeadingfalse, andrefresh()setsheaderEnabledfalse. Working as designed. Do not change the page layout. Seesupport-engineering-visit-ipad-section-header.md. - Web HCO picker returns no organizations: follow
lsc-visit-managementHCO picker page.AccountPickerServicepaginatesHealthcareProviderLIMIT 20by name beforeIsPersonAccount = false. A page of person accounts is dropped, so the result is 0 HCOs. Do not start with a metadata override. Seesupport-engineering-visit-hco-picker-page.md. - ProductDisbursement delete is rejected in the same transaction as visit submit: follow
lsc-visit-managementDisbursement delete lock. The customer's unmanaged triggerProductDisbursementDeleteLockis the cause. The managed submit lock is ruled out. The customer adds a same-transaction exemption. Do not route this to a package fix. An iPad Visit that is gone on the device and still on the server is iPad delete not applied, not this trigger. Seesupport-engineering-visit-disbursement-delete-lock.md. - iPad shows Complete this field: Item on a sample that already has an item: follow
lsc-visit-managementSample batch null.checkAvailableQuantitiesguards theProductionBatchID string and not the bulk-loaded entity, so a missing entry dereferences null. Not a package 262 regression. Guard the entity. Seesupport-engineering-visit-sample-batch-null.md. - Sample Limits not calculating: Verify sample limit templates, date ranges
- Inventory sync issues: Check sample transaction records, reconciliation jobs
- Compliance warnings: Verify signature capture, recipient validation
- Template not applying: Check Admin Console > Sample Limits > Jobs
Visit Management
- Visit not saving: Check required fields, validation rules, trigger handlers
- Products not appearing in Product Details: Check the PTDA → Marketable Product chain:
- PTDAs must exist for Brand-level marketable products in the rep's territory
- Marketable products must have
Type = 'Brand'(not'Product') —Type = 'Product'is filtered out by Query #6 Type = 'Brand'requiresProductId = null(platform enforces this)- If PTAs exist but PTDAs don't, run the alignment batch job from Admin Console > Product (tile) > Product Alignment Jobs
- Geolocation issues: Check address data, mobile permissions, geolocation settings
- A Visit field is read-only on the layout or by field-level security but editable on create, or Status shows every value: follow
lsc-visit-managementStatus editable on create.refreshFieldReadOnlyStatusclears that lock during creation. Fixed in package 264.5. Not Set Audit Fields. Life Sciences uses Planned and Completed. Seesupport-engineering-visit-status-readonly.md. - Late Visit submits on web with an empty Submit Delay Reason, and iPad blocks it: follow
lsc-visit-managementWeb submit delay reason. Package 264 requires the reason; orgs still on 262.x need that upgrade. Do not toggleVisitDelayReasonHandlerto force the guard. Seesupport-engineering-visit-submit-delay-reason.md. - Additional Information on Visit Engagement (
AdditionalInformation) breaks attendee add or leaves the attendee screen read-only: followlsc-visit-managementAdditional Information. The field is system-managed JSON and must not be on that layout. Do not move it onto ProviderVisit or blame a stale cache. Seesupport-engineering-visit-additional-information.md. - Intelligent Content launched from a Visit is not recorded, and the player did open: follow
lsc-intelligent-contentPause tracking on launch. Pause tracking when player launches starts the session paused, so nothing is written until the rep taps play. Do not start with metadata cache or a missing bundle. Seesupport-engineering-pause-tracking-on-launch.md. - Dynamic actions do not run on the mobile app: follow
lsc-mobile-app-settings.ApplicationSettings_OrgLevelis inactive, so it is not synced and the app defaultsEnableDynamicActionsto false. Activate the record. Do not cite a profile-name limit or Dynamic Forms on Mobile. Seesupport-engineering-visit-dynamic-actions-inactive.md. - iPad and web disagree on a visit conflict: follow
lsc-visit-managementVisit conflict end time.VisitConflictValidationPlugin.findConflictingVisitqueries only the existing visit'sstartDateField. The end time is never read, so the window is the new start plus or minus N days. Web checks both start and end. The fix is a two-sided end-time condition. Seesupport-engineering-visit-conflict-end-time.md. - Custom fields on product detailing are blank after the visit saves: follow
lsc-visit-managementDetailing stale cache.LogACallSaveHelperupserts a cachedProviderVisitProdDetailingthat was not re-queried after the Visit flow, so fields outside its DTO are blanked. Fix with a before-save flow onProviderVisitProdDetailing. Do not call this an unscoped package-field write. Seesupport-engineering-visit-detailing-stale-cache.md. - iPad says the visit is outside best time: follow
lsc-visit-managementBest time on iPad.CallMyBestTimeValidatorparses rawFromTimeandToTimewith a 12-hour format, soTimePeriodis always nil and it throwsoutsideMyBestTimefor every account. Do not populateTerritoryIdor add best-time rows. Seesupport-engineering-visit-best-time-parse.md. - Visit validation passes for institutions, or a visit script does not run on Save: follow
lsc-visit-managementInstitution script guard. Compare a person account and an institution, then read the script. The institution check is inverted. A Save dispatch gap is a second cause, not a replacement. The customer corrects the script. Seesupport-engineering-visit-script-institution-guard.md. - Sample-limit ellipsis or enforcement is missing on a visit: follow
lsc-visit-managementSample limits profile setting.ValidateSampleLimitsis off on the profile Visit setting. Do not pin a missingProviderSampleLimitrow while that setting is off. Seesupport-engineering-visit-sample-limits-profile.md. - Product guidance appears from a presentation and is hidden when the same product is added directly: follow
lsc-product-managementPresentation guidance dates.PresentationItemService.isActiveProductGuidanceand its DAO filterIsActiveonly and omitEffectiveStartDateandEffectiveEndDate. The direct product path applies the dates. Compare both paths. Do not stop on an empty code search. Seesupport-engineering-presentation-guidance-dates.md. - Add Product shows the right products in the wrong order: follow
lsc-visit-managementAdd Product sort. The picker sorts byLifeSciMarketableProduct.SortOrderand usesProductTerrDtlAvailabilityonly as the eligibility filter. TerritorySortOrderhas to come first. A null territorySortOrderdoes not hide the product. Seesupport-engineering-visit-add-product-sort.md. State that cause. Do not leave other sort hypotheses open. - Visit deleted on iPad is still on the server, and Edit/Delete were available on a completed, read-only, or out-of-territory Visit: follow
lsc-visit-managementiPad delete not applied. The local delete stuck after the server rejected it. Do not change sharing orVisitLockHandler. Seesupport-engineering-visit-ipad-delete-not-applied.md. - iPad Visit children (Presentation Forum, click stream, disbursement) missing on web after submit: follow
lsc-visit-managementSync is not data loss. Read the Device Sync Transaction first. If the child rows are present and the transaction failed on a customer validation rule, the customer changes that rule. Seesupport-engineering-visit-sync-not-data-loss.md. - Record type not available: Check Visit Record Type Mappings in Admin Console
Account Management
- Provider Card not loading: Check ARC configuration, DataRaptor setup, permissions
- Addresses not syncing: Check address configuration, integration
- Affiliations missing: Check affiliation records, parent/child setup
Event Management (Field Events)
- "We couldn't add the participant to the event either because the participant type and role aren't mapped for this event type or because the mapping record isn't active" on the Non-Profiled Attendees / Write-Ins cards, and the card has no Update/+Add button at all: almost never a genuinely missing/inactive
EventMgmtPtcpTypeRoleMaprow (that's a red herring — it's usually already active). The real cause is that the mapping row points to anEventMgmtParticipantRolewithRole = Attendeeinstead of a dedicated role typedRole = NonProfiledAttendee/WriteInAttendee— orgs often never create one, becauseStandardRole(a separate, restricted picklist) has no matching value for these two categories. Fix: create a role record per category withStandardRole = 'Other'(the only valid fallback), then repoint every NonProfiledAttendee/WriteInAttendeeEventMgmtPtcpTypeRoleMaprow (across allMngEventTypes, not just one) to the new role. Full diagnose/fix steps:knowledge/modules/field-events-management/troubleshooting.md.
Calendar / Planner
Error in $A.getCallback() [Cannot read properties of undefined (reading 'ObjectType')]: This Aura error occurs when the Planner component cannot find expected calendar event type configuration. Investigate with Tooling API queries (see "Querying LifeSciConfigRecord" section above):- Check that
CalendarEvent_*config records exist and are active:SELECT Id, DeveloperName, MasterLabel, IsActive FROM LifeSciConfigRecord WHERE DeveloperName LIKE 'CalendarEvent_%' - Check that
PlannerAdministration_*config records exist:SELECT Id, DeveloperName, MasterLabel, IsActive, IsOrgLevel FROM LifeSciConfigRecord WHERE DeveloperName LIKE 'PlannerAdministration_%' - Verify the
DbSchema_CalendarEventandDbSchema_PlannerAdministrationrecords exist:SELECT Id, DeveloperName, MasterLabel FROM LifeSciConfigRecord WHERE DeveloperName IN ('DbSchema_CalendarEvent', 'DbSchema_PlannerAdministration') - If records are missing, re-run the Calendar/Planner setup in Admin Console to regenerate them
- This error commonly occurs after an LSC upgrade where post-upgrade configuration steps were missed
- Check that
- Calendar events not rendering: Check CalendarEvent config records are active via Tooling API
- Planner settings not applying per profile: Check
PlannerAdministration_*hierarchical config records —_OrgLevelis the default, profile-specific overrides use_<ProfileName>suffix
Business License / Mobile License Icon
The LSC mobile app shows license status in two places:
- Account list — Aggregate icon per account. Red if ANY part of the chain is missing.
- Visit Engagement page — Per-type badges ("State", "DEA"). Each badge is independent.
The Visit page only checks BusinessLicense validity. The account list icon checks the full chain below.
IsLicenseValidated Formula
BusinessLicense.IsLicenseValidated is a platform-managed formula (getCalculatedFormula() returns null). Requirements:
| Field | Requirement |
LicenseNumber | Not blank |
PeriodEnd | Greater than NOW() |
PeriodStart | Must be set (not null) — undocumented, #1 hidden cause of false |
ComplianceScope | Must be set (JurisdictionState, Address, or StateDistributorLicense) |
ContactPointAddress.IsActive | Must be true when ComplianceScope is Address or StateDistributorLicense |
ContactId | Set to PersonContactId for PersonAccount (HCP) licenses |
Account.IsActive | Must be true — defaults to false on new accounts |
Diagnostic query:
SELECT Id, Name, AccountId, Account.Name, IsLicenseValidated, LicenseNumber,
PeriodStart, PeriodEnd, ComplianceScope, JurisdictionState,
ContactPointAddressId, ContactId
FROM BusinessLicense
WHERE AccountId = '<account-id>'Visit Page Badges Red
- Check
IsLicenseValidated— is ittrue? - If
false: checkPeriodStart— is it set? (Most common hidden cause) - If
falseand ComplianceScope isAddress: check linked CPA'sIsActive - If State badge is red but
IsLicenseValidated = true: checkJurisdictionState— must match the CPA's state code
Account List Icon Red (but Visit Page Is Green)
The account list green icon requires the full chain:
ProviderAcctTerritoryInfo.IsActive = true— defaults tofalse, #1 cause of red account list iconProviderAcctTerritoryInfo.IsAvailableOffline = true— required for mobile syncProviderAcctTerritoryInfo.Territory2Idmust point to the leaf territory (not a parent)ProviderAcctTerritoryInfomust haveLSC4CEAutoSharesharing rule for the territory group (manually created records don't get this automatically)ProviderAcctTerritoryInfo.IsTargetedAccount = true,SourceType = 'Manual',PreferredAddressIdset to the account's CPAPrvdAccountTerritorySummaryrecords — one per user in the territory,OwnerId = UserIdObjectTerritory2Associationlinking account to territory- Valid
BusinessLicensewithIsLicenseValidated = true ContactPointAddress.IsActive = true,AddressType = 'Billing',UsageType = 'Work'Account.IsActive = trueHealthcareProviderrecord shared with territory users
Diagnostic queries for the full chain:
-- Check ProviderAcctTerritoryInfo
SELECT Id, AccountId, Account.Name, Territory2Id, Territory2.Name,
IsActive, IsAvailableOffline, IsTargetedAccount, SourceType, PreferredAddressId
FROM ProviderAcctTerritoryInfo
WHERE AccountId = '<account-id>'
-- Check PATI sharing (LSC4CEAutoShare)
SELECT Id, ParentId, UserOrGroupId, AccessLevel, RowCause
FROM ProviderAcctTerritoryInfoShare
WHERE ParentId = '<pati-id>'
-- Check CPA fields
SELECT Id, ParentId, IsActive, AddressType, UsageType, StateCode
FROM ContactPointAddress
WHERE ParentId = '<account-id>'
-- Check account is active
SELECT Id, Name, IsActive FROM Account WHERE Id = '<account-id>'Account Not Appearing on Mobile at All
- Check
ProviderAcctTerritoryInfo.IsAvailableOffline = true - Check
ProviderAcctTerritoryInfo.Territory2Idpoints to the correct leaf territory (the dbschema filter matchesTerritory2.Name = '{USER.TERRITORY}'which resolves to the rep's assigned leaf) - Check
LSC4CEAutoShareexists on theProviderAcctTerritoryInforecord - Check
PrvdAccountTerritorySummaryrecords exist (one per user in the territory)
Creating Valid Demo Licenses
A single State license per account is sufficient for the green icon:
BusinessLicense bl = new BusinessLicense();
bl.Name = 'State License - Account Name';
bl.LicenseNumber = 'ST-001';
bl.AccountId = accountId;
bl.Status = 'Verified';
bl.IsActive = true;
bl.ComplianceScope = 'JurisdictionState';
bl.JurisdictionState = 'CA'; // Must match the CPA's state code
bl.PeriodStart = Datetime.newInstance(Date.newInstance(2025, 1, 1), Time.newInstance(0, 0, 0, 0));
bl.PeriodEnd = Datetime.newInstance(Date.newInstance(2029, 1, 1), Time.newInstance(0, 0, 0, 0));
bl.IssueDate = Date.newInstance(2025, 1, 1);Batching: Managed-package triggers on BusinessLicense consume ~32 SOQL queries per DML. Keep inserts to batches of ~15 records.
Territory Alignment
- Accounts not assigned: Check alignment rules, territory hierarchy
- User not seeing accounts: Verify Territory2 membership, sharing rules
- Territory jobs failing: Check Admin Console > Territories > Jobs
- Territory-scoped sharing not working / sharing-handler setup aborts: The territory model must be activated first. Sharing handler setup checks
Territory2Model.State == 'Active'and aborts with an explicit error if the model is inPlanning/Inactivestate. Activate the territory model before enabling sharing handlers.SELECT Id, DeveloperName, State FROM Territory2Model
Mobile Sync / DB Schema
- Object's data disappeared from the iPad after a config change: Check whether its DB Schema record was deactivated or removed. Disabling a DB Schema record is destructive — on the next sync the app runs
DELETE FROM <table>for objects no longer in the metadata, wiping all locally cached records (and any unsynced offline edits) for that object. Re-enabling re-syncs server data, but local-only data is gone. Uselist_db_schema/get_db_schemato confirm the record's state. - Data Change Requests or offline edits silently fail for an object: Check
OneWaySyncon its DB Schema record.OneWaySync = true(web→mobile only) means the object gets no offline-tracking columns and is treated as unsyncable for edits — DCR and offline modifications will silently fail. SetOneWaySync = falseif the object needs offline edit/DCR support.
Configuration & Deployment Gotchas
- A trigger handler you deployed doesn't show up in
list_trigger_handlers: New/custom trigger handler records may not be registered until the handler-sync routine runs. ExecuteTriggerService.syncTriggerHandlerRecords();viarun_apex, then re-list. - Automation firing mid-deploy / config deploys in an inconsistent state: Deploy LifeSciConfig + trigger-handler-dependent metadata in two passes — deploy inactive first, then activate — so triggers/automation don't fire against partially-deployed config. (This is the pattern LSC's own setup scripts use.) See
lsc-config-migrationfor the full sequence.
Mobile Related List Renders Blank (force:relatedListSingleContainer)
Symptom: On the LSC iPad app, a related-list tab on a record page renders completely blank — no "(N)" card header, no New button, no rows — even though the child records exist and synced. Classic tell: the SAME list renders its empty "(0)" card + New button fine when the parent has 0 children, but blanks the entire container the moment there is ≥1 child. It also often reproduces on one record but not another of the same object.
Component involved: the related list is rendered by the FlexiPage component force:relatedListSingleContainer, configured with these componentInstanceProperties:
relatedListApiName— e.g.AccountPlanRelationship_AccountPlan(<Child>_<ParentLookup>)parentFieldApiName— e.g.AccountPlan.IdrelatedListComponentOverride=NONE← this is the keyrowsToDisplay,showActionBar
When relatedListComponentOverride = NONE, the component does not define its own columns. It inherits the column set from the related-list definition on the parent record's RECORD-TYPE page layout. If that record type's layout has no related list for the child object, there are no columns to draw, and the app blanks the whole container instead of degrading gracefully.
Why it reproduces on one record and not another: Different record types resolve to different page layouts. A record whose record type maps to a layout that includes the child related list renders fine; a record with no record type (Master) — or a record type whose layout omits that related list — blanks. Same child object, same device, same cache. So the differentiator is the parent record's RecordType → page layout, not the child object or row count.
Diagnose
- Compare two parent records — one that renders, one that blanks — and get their record types:
SELECT Id, Name, RecordType.DeveloperName FROM AccountPlan WHERE Id IN ('<good>','<blank>') - Get the layout Ids for the object, then inspect each record type's page layout for the related-list field set via the Tooling API:
# Get layout Ids sf data query --use-tooling-api -q "SELECT Id, Name FROM Layout WHERE TableEnumOrId='AccountPlan'" --json # Inspect a layout's related lists sf data query --use-tooling-api -q "SELECT Metadata FROM Layout WHERE Id='<layoutId>'" --json # In result.records[0].Metadata.relatedLists[], look for the child object. # Present (renders): relatedList=RelatedAccountPlanRelationships fields=[Name, AccountPlan, RelatedAccountPlan] # Missing (blanks): no entry whose relatedList references the child object
The layout that has the related list = the working record type; the one that lacks it = the blank record type. That confirms the root cause.
Fix A — add the related list to the deficient page layout (permanent, deployable)
Retrieve the layout, add a <relatedLists> block, and deploy (page layouts deploy reliably):
<relatedLists>
<fields>Name</fields>
<fields>AccountPlan</fields>
<fields>RelatedAccountPlan</fields>
<relatedList>RelatedAccountPlanRelationships</relatedList>
</relatedLists><relatedList>is the layout's related-list name (e.g.RelatedAccountPlanRelationships), which is not the same string as the FlexiPage'srelatedListApiName(AccountPlanRelationship_AccountPlan) — both point to the same child→parent relationship.<fields>uses relationship/field names, not Id fields (AccountPlan, notAccountPlanId).- After deploy, regenerate the mobile metadata cache for the affected profile(s) and re-sync the device.
Fix B — give the record the working record type (fast data fix)
If the record simply has no/wrong record type, set it to the one whose layout already has the related list:
AccountPlan p = [SELECT Id FROM AccountPlan WHERE Id='<id>'];
p.RecordTypeId = '<recordTypeId of the working layout>';
update p;No cache regen needed — just re-sync the device so the new record type's layout takes effect.
Do NOT chase these dead ends
- The child object's
searchLayoutsinsobjects.jsonis not the driver — records render fine even when the child object has nosearchLayoutsentry. - Deploying
<searchLayouts>to a STANDARD object via the Metadata API silently fails — the deploy reportssuccess: true / changed: truebut re-retrieval shows the block was dropped. Don't rely on it. - Verify you're inspecting the LIVE simulator. Multiple sims can be booted; find the active cache by mtime:
find ~/Library/Developer/CoreSimulator/Devices/*/data/Containers/Data/Application/*/Documents/.Data \ -name ui.json -mtime -2 -exec stat -f '%Sm %N' {} \;
Resolution Steps
- Identify the root cause category
- Check relevant Admin Console settings
- Use
describe_sobjectto verify object structure - Verify data integrity with SOQL queries
- Review any custom configuration or triggers
- Test in isolation if possible
- Document the fix for future reference
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

