lsc-sample-management
Skill10 starsChanged 29 days agoApache-2.0View on GitHub
Guides Life Sciences Cloud (LSC) Sample Management configuration for inventory, sample limits, and sample limit validation. Use when user asks about sample inventory, sample drops, sample limits, sample limit validation on mobile, the sample-limit ellipsis on a visit, PDMA compliance, inventory operations, production batches, product items, inventory counts, signature requirements, Product2/LifeSciMarketableProduct/ProviderSampleLimit/ProviderSmplLmtTmplAssignment objects, **Complete this field: Item** on a sample that already has an item, a ProductDisbursement delete rejected in the same transaction as visit submit, web Samples and Direct to Practitioner that do not render after a product is selected, a sample dropdown that shows a different name on web than on iPad, Samples disabled for an HCP attendee on an HCO visit, or iPad Add Another and the side menu staying available after signature.
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-surveysSkill
- lsc-territory-alignmentSkill
- lsc-troubleshootSkill
- 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
16 rules. About 0 are common, 7 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 36
When a rep opens the Samples panel during Visit Engagement, the platform runs ~12 SOQL queries.
- Distinctive: line 72
ALL conditions must pass:
- Very specific: line 103
How to verify: Check productType in the ProviderSampleLimit.Rule JSON:
- Very specific: line 113
Fix: Create ProviderSmplLmtTmplAssignmentShare records for each assignment × rep user, or change OWD to Public Read Only.
- Very specific: line 117
Create a custom ProviderSampleLimitTemplate with valid date ranges (do NOT use the default lsc4ce_GenericTemplate — its dates are empty and …
- Very specific: line 118
Create ProviderSmplLmtTmplAssignment at Brand level with RuleCondition in map format
- Very specific: line 120
Run "Assign Sample Limit Templates to Accounts" batch job from Admin Console > Sample Limits (tile) > Sample Limit Jobs — generates …
- Very specific: line 121
Verify generated PSL records have productType: "Brand" in Rule JSON
- Very specific: line 123
Ensure all 3 DbSchema OMCC (LifeSciConfigRecord) entries exist and are active:
- Distinctive: line 243
When limits don't fire on mobile:
- Distinctive: line 248
All 3 DbSchema OMCC entries exist and active?
- Distinctive: line 271
Always call MCP tools to get sourced documentation: Do not answer from general knowledge alone.
- Distinctive: line 292
When the user asks about configuring or enabling Sample Management features, ask them which mode they prefer:
- Distinctive: line 297
Default to guided setup when connected to an org, or documentation mode if no org is connected.
- Very specific: line 352
DO NOT: use run_soql for Admin Console settings — use list_admin_settings / check_sample_config
- Very specific: line 353
DO NOT: use run_soql for mobile cache — use check_mobile_cache_status()
≈ “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
Samples disabled for an HCP attendee on an HCO visit
When Samples are disabled for an HCP attendee on an HCO visit, load knowledge/modules/visit-management/support-engineering-visit-attendee-sample-address.md. Finish only when the reply states every fact under Required answer. Compare the attendee's primary address to the parent visit address first. A mismatch is working as designed. Do not lead with HcoTypesForSamplesAndItems or a profile override.
Product name differs between web and iPad
When the Samples, Direct to Practitioner, or Items dropdown shows one name on web and another on iPad for the same product, load knowledge/modules/visit-management/support-engineering-visit-product-name-fields.md. Finish only when the reply states every fact under Required answer. Web Apex uses Product2.Name. iOS uses LifeSciMarketableProduct.Name. The saved Product2 id is the same. Set both names equal. Do not say the web LWC reads the marketable-product name.
Add Another after signature on iPad
When iPad still offers Add Another or a side-menu sample after the visit is signed, and the Product Item dropdown hides that product, load knowledge/modules/visit-management/support-engineering-visit-signed-add-another.md. Finish only when the reply states every fact under Required answer. SamplesPlugin.canInsertForGroup and ProductMenuBloc ignore the signature rule. This is not a web defect.
Web Samples and DTP after a product is selected
When web Visit Engagement does not render Samples or Direct to Practitioner after a product is selected, and iPad does, load knowledge/modules/visit-management/support-engineering-visit-sample-dtp-locale.md. Finish only when the reply states every fact under Required answer. Organization.DefaultLocaleSidKey is en_IE_EURO, the old JDK form of English (Ireland, Euro). Switch the org to the ICU locale. Do not add a Product Disbursements related list.
Disbursement delete in the same transaction as visit submit
When a ProductDisbursement delete is rejected while the visit is submitting, load knowledge/modules/visit-management/support-engineering-visit-disbursement-delete-lock.md. Finish only when the reply states every fact under Required answer. Query ApexTrigger on ProductDisbursement. The customer's unmanaged trigger ProductDisbursementDeleteLock is the cause. The managed submit lock is ruled out. The customer adds a same-transaction exemption. Do not ask for a package change. Do not use this section when the symptom is an iPad Visit missing on the device and still on the server.
Sample batch null on save
When iPad shows Complete this field: Item and the sample already has a product item, load knowledge/modules/visit-management/support-engineering-visit-sample-batch-null.md. Finish only when the reply states every fact under Required answer. checkAvailableQuantities guards the ProductionBatch ID string, not the entity from the bulk load. A missing entry dereferences null. This is not a package 262 access-rights regression. Guard the resolved entity.
Sample-limit menu missing
When the ellipsis next to a sample product is missing, or sample-limit enforcement does not run, load knowledge/modules/visit-management/support-engineering-visit-sample-limits-profile.md. Call list_admin_settings({ category: "Visit" }) and read ValidateSampleLimits on the user's profile record. User overrides profile, and profile overrides org. Finish only when the reply states every fact under Required answer. A missing ProviderSampleLimit row is the cause only after that profile setting is on and the ellipsis is visible.
Critical Knowledge: How Samples Are Resolved During a Visit
When a rep opens the Samples panel during Visit Engagement, the platform runs ~12 SOQL queries. The critical ones are:
The PTDA Requirement (Most Common Root Cause)
ProductTerrDtlAvailability (PTDA) records are the master product pool for samples. Without them, samples will never appear. PTDAs are:
- Read-only — cannot be inserted via Apex, API, or Data Loader
- Created only by the alignment batch job from
ProductTerritoryAvailability(PTA) records - The batch job must be triggered from Admin Console > Product (tile) > Product Alignment Jobs
PTA → Batch Job → PTDA Pipeline
ProductTerritoryAvailability (PTA) ← Apex-scriptable
↓ alignment batch job ← Admin Console UI only
ProductTerrDtlAvailability (PTDA) ← read-only, cannot insertBrand-level AND sample-level marketable products each need their own PTAs. Step 4 in the data loading flow only creates PTAs for Brand-level products. Sample-level products need separate PTAs + a batch job run.
Critical: AlignmentType Must Be "Territory and Subordinates Inclusion"
PTAs must use Territory and Subordinates Inclusion at a parent territory (e.g., GB-COUNTRY). The batch job generates PTDAs by expanding parent alignments down to child territories. Using Territory Inclusion directly at a leaf territory (e.g., GB-FSR-001-London) does NOT create PTDA records — this is the most common cause of "samples not appearing after running the batch job."
Query #9 — The Critical Sample Filter
This is where most "No items found" issues originate:
SELECT Id FROM LifeSciMarketableProduct
WHERE IsCompetitorProduct != true
AND Type IN ('Product')
AND ParentBrandProductId IN (:brandIdsFromQuery6)
AND DistributionMethod IN ('Drop','DropAndShip')
AND ProductId IN (:product2IdsFromQuery8)
AND ProductSpecificationType IN ('LSSampleProduct')ALL conditions must pass:
Type = 'Product'(not Brand) — sample-level marketable products requiredParentBrandProductIdmust point to a Brand marketable product aligned to the territoryDistributionMethodmust beDrop,Ship, orDropAndShipProductIdmust be in the rep's inventory (ProductItemrecords)ProductSpecificationType = 'LSSampleProduct'(auto-populated from Product2)
Critical Knowledge: Sample Limit Setup
Sample limits control how many sample units a rep can drop per visit or per period for a given HCP account. Getting them to work on mobile requires several data records, correct JSON formats, sharing, and Admin Console settings — all aligned.
Sample Limit Data Model
ProviderSampleLimitTemplate ← Defines rules (PerVisitLimit, PerPeriodLimit)
↓
ProviderSmplLmtTmplAssignment ← Links template → Brand marketable product (Private OWD!)
↓
ProviderSampleLimit ← Links template → Account × Brand product (contains Rule JSON)
↓
Mobile validation on submit ← Checks qty against Rule JSONThe #1 Rule: Limits Must Be at Brand Level
ProviderSampleLimit.ProductId and ProviderSmplLmtTmplAssignment.ProductId must point to Brand-level marketable products (Type = 'Brand'), NOT SKU-level (Type = 'Product').
The mobile app resolves limits by walking up the product hierarchy from the dropped SKU to find its parent Brand, then queries ProviderSampleLimit for that Brand × Account. If the PSL record points to a SKU, the hierarchy walk never finds it, and validation silently skips.
How to verify: Check productType in the ProviderSampleLimit.Rule JSON:
"Brand"= correct"LSSampleProduct"= wrong (SKU-level), validation will not fire
ProviderSmplLmtTmplAssignment Has Private OWD
This is the most common cause of "validation works on web but not mobile":
- Web runs server-side in system context — reads all records regardless of sharing
- Mobile syncs to local SQLite in user context — if the assignment isn't shared with the rep, it won't sync, and validation silently skips
Fix: Create ProviderSmplLmtTmplAssignmentShare records for each assignment × rep user, or change OWD to Public Read Only.
Sample Limit Setup Steps
- Create a custom
ProviderSampleLimitTemplatewith valid date ranges (do NOT use the defaultlsc4ce_GenericTemplate— its dates are empty and cause null dereference) - Create
ProviderSmplLmtTmplAssignmentat Brand level with RuleCondition in map format - Share assignments with rep users (
ProviderSmplLmtTmplAssignmentShare) - Run "Assign Sample Limit Templates to Accounts" batch job from Admin Console > Sample Limits (tile) > Sample Limit Jobs — generates
ProviderSampleLimitrecords with correct Rule JSON - Verify generated PSL records have
productType: "Brand"in Rule JSON - Enable "Validate sample limits" in Admin Console > Visit Settings
Ensure all 3 DbSchema OMCC (
LifeSciConfigRecord) entries exist and are active:DbSchema_ProviderSampleLimitDbSchema_ProviderSampleLimitTemplateDbSchema_ProviderSmplLmtTmplAssignment
How to check: Query via Tooling API (NOT SOQL —
LifeSciConfigRecordis not queryable via standard SOQL):SELECT Id, DeveloperName, IsActive FROM LifeSciConfigRecord WHERE DeveloperName IN ( 'DbSchema_ProviderSampleLimit', 'DbSchema_ProviderSampleLimitTemplate', 'DbSchema_ProviderSmplLmtTmplAssignment' )How to create missing entries: Deploy as
LifeSciConfigRecordmetadata XML. Each file must include the full structure:<fieldValues>entries (especially<fieldName>SObject</fieldName>with<objectValue>set to the target object API name), profile<assignments>, and<lifeSciConfigCategory>DbSchema</lifeSciConfigCategory>.Two-phase deployment required: Deploy with
<isActive>false</isActive>first, then redeploy with<isActive>true</isActive>. Deploying active in a single step fails withEnter: [Type, SObject].
Rule JSON Format
The Rule field on ProviderSampleLimit uses this structure (batch job generates it automatically):
{
"template": {
"operations": [
{ "operation": "RULE", "rule": "PerVisitLimit" },
{ "operation": "RULE", "rule": "PerPeriodLimit" },
{ "operation": "AND" }
],
"name": "lsc4ce_GenericTemplate",
"blockType": "Error",
"label": "Generic Template"
},
"products": {
"<Brand MktProd Id>": {
"rules": {
"PerVisitLimit": {
"quota": 2,
"remaining": 2,
"strategy": "SKU",
"calculation": "SamplesPerVisit",
"label": "Maximum Quantity per Visit",
"starts": "2026-01-01",
"ends": "2026-12-31",
"period": { "type": "SampleLimitDateRangePeriod", "params": {} }
},
"PerPeriodLimit": {
"quota": 10,
"remaining": 10,
"strategy": "SKU",
"calculation": "SamplesInPeriod",
"label": "Maximum Quantity per Period",
"starts": "2026-01-01",
"ends": "2026-12-31",
"period": { "type": "SampleLimitDateRangePeriod", "params": {} }
}
},
"info": {
"productType": "Brand",
"excludedChildProducts": [],
"annualAllocations": {}
}
}
}
}Key fields:
template.blockType:"Error"blocks submission;"Warning"allows ittemplate.operations: Boolean logic —ANDmeans both rules must passproducts.<id>: Key is the Brand-level marketable product IDinfo.productType: Must be"Brand"—"LSSampleProduct"means wrong levelinfo.excludedChildProducts: Must be present (array of SKU IDs to exclude)strategy: "SKU": Quotas tracked per SKU independently, but quota values are the same for all SKUs under the Brandremaining: Runtime counter decremented as drops are recordedstarts/ends: Must cover the current date or validation won't apply
The RuleCondition on ProviderSmplLmtTmplAssignment uses a different map format keyed by rule name:
{
"PerPeriodLimit": {
"name": "PerPeriodLimit",
"label": "Maximum Quantity per Period",
"strategy": "SKU",
"quota": 10,
"calculation": "SamplesInPeriod",
"period": {
"type": "SampleLimitDateRangePeriod",
"params": { "starts": "2026-01-01", "ends": "2026-12-31" }
}
},
"PerVisitLimit": {
"name": "PerVisitLimit",
"label": "Maximum Quantity per Visit",
"strategy": "SKU",
"quota": 2,
"calculation": "SamplesPerVisit",
"period": {
"type": "SampleLimitDateRangePeriod",
"params": { "starts": "2026-01-01", "ends": "2026-12-31" }
}
}
}Do NOT use array format ([{...}]) for assignment RuleCondition — it must be the map/object format above.
Template Name Must Be DeveloperName
ProviderSampleLimit.PrvdSampleLmtTemplateName must use the template's DeveloperName (e.g., GB_Sample_Limit_Template), not the MasterLabel. Wrong name = batch job returns 0 rows and hits null reference.
SignatureRequirementLevel
Set LifeSciMarketableProduct.SignatureRequirementLevel to Mandatory on sample SKUs to require signature capture during sample drops. Values: Mandatory, Optional, NotRequired.
Sample Limit Diagnostic Checklist
When limits don't fire on mobile:
ProviderSampleLimit.ProductId→ Brand-level marketable product?- Rule JSON
productType="Brand"(not"LSSampleProduct")? ProviderSmplLmtTmplAssignmentshared with rep user?- "Validate sample limits" enabled in Visit Settings?
- All 3 DbSchema OMCC entries exist and active? (Query via Tooling API, not SOQL:
SELECT Id, DeveloperName, IsActive FROM LifeSciConfigRecord WHERE DeveloperName IN ('DbSchema_ProviderSampleLimit', 'DbSchema_ProviderSampleLimitTemplate', 'DbSchema_ProviderSmplLmtTmplAssignment')) — if any are missing, the mobile app won't sync the corresponding objects and validation silently skips - Product hierarchy fully linked (
ParentTherapeuticAreaIdat all levels)? - Rule JSON date ranges cover today?
PrvdSampleLmtTemplateNameuses DeveloperName?- iPad synced after changes?
SortOrder on PTDA Is NOT Required
SortOrder on ProductTerrDtlAvailability defaults to null. Query #2 filters by SortOrder != null, which often returns 0 rows. This does NOT block samples — the platform uses all PTDAs for the territory (queried by TerritoryId) regardless of SortOrder.
Admin Console Navigation
- Product Alignment: Admin Console > Product (tile) > Product Alignment
- Alignment Jobs: Admin Console > Product (tile) > Product Alignment Jobs
- Sample Limit Jobs: Admin Console > Sample Limits (tile) > Sample Limit Jobs
- These are NOT under Salesforce Setup — they are tiles in the Admin Console app.
How to Answer Sample Management Questions
Always call MCP tools to get sourced documentation. Do not answer from general knowledge alone.
| User asks about... | Call this tool |
| Sample concepts, data setup chain, best practices | get_lsc_module_docs({ module: "sample-management" }) |
| Specific topic (sample limits, PDMA, inventory counts, etc.) | search_lsc_knowledge({ query: "<topic>" }) |
| Current org sample configuration | check_sample_config() |
| Admin Console sample settings | list_admin_settings({ category: "SampleManagement" }) |
| Trigger handler status | list_trigger_handlers() |
| Object fields and relationships | describe_sobject({ sobject: "ProductItem" }) or describe_sobject({ sobject: "ProductDisbursement" }) |
| Mobile cache status | check_mobile_cache_status() |
| Inventory data in the org | run_soql({ query: "SELECT ... FROM ProductItem ..." }) |
| Validation / audit | audit_mobile_config({ group: "sample-config-check" }) |
| Sample drops during visits (test cases) | search_lsc_knowledge({ query: "sample inventory validation visit" }) |
| Sample limit setup or troubleshooting | search_lsc_knowledge({ query: "sample limit validation" }) |
| Sample limit not firing on mobile | Check: PSL at Brand level? Assignment shared? Visit Settings enabled? DbSchema active? |
Configuration Mode
When the user asks about configuring or enabling Sample Management features, ask them which mode they prefer:
- Show me the documentation — call
get_lsc_module_docs({ module: "sample-management" })and present the relevant sections - Walk me through it — configure it directly in their org step-by-step (guided setup below)
Default to guided setup when connected to an org, or documentation mode if no org is connected.
Guided Setup Workflow
Step 1: Check Current State
check_sample_config()
list_trigger_handlers()
list_admin_settings({ category: "SampleManagement" })Step 2: Report Findings
Present a summary table of what's configured vs what's missing/disabled.
Step 3: Propose Changes
For each issue found, propose the fix and wait for user confirmation.
Step 4: Apply Changes (with user confirmation)
toggle_trigger_handler({ handlerName: "SampleManagementTriggerHandler", active: true })
update_admin_setting({ recordId: "...", fields: { ... } })
create_admin_setting({ category: "SampleManagement", developerName: "...", label: "..." })Step 5: Verify
Re-run check_sample_config() to confirm everything is configured correctly.
Tool Usage Rules
Correct Object Names
| Correct | Wrong (NEVER use) |
Product2 | SampleProduct__c |
LifeSciMarketableProduct | — |
Location | SampleInventory__c |
ProductionBatch | SampleLot__c, ProductBatch__c |
ProductItem | InventoryItem__c |
ProductBatchItem | — |
InventoryOperation | SampleTransaction__c |
ProductRequest | SampleRequest__c |
InventoryCountAssessment | SampleCount__c, InventoryCount__c |
ProductDisbursement | SampleDrop__c |
ProviderSampleLimit | SampleLimit__c |
ProviderSampleLimitTemplate | — |
ProviderSmplLmtTmplAssignment | — (Private OWD — must share with rep users) |
ProviderSmplLmtTmplAssignmentShare | — (sharing object for template assignments) |
PrvdVstSmplLmtTransaction | — |
PrvdVstSmplLmtDiscrepancy | — |
TerritoryProdtQtyAllocation | TerritoryProductQtyAllocation, SampleAllocation__c, ProductAllocation__c |
ProductTerritoryAvailability | ProductAlignment__c |
ProductTerrDtlAvailability | — (read-only, created by alignment batch job only) |
Tool Restrictions
- DO NOT use
run_soqlfor Admin Console settings — uselist_admin_settings/check_sample_config - DO NOT use
run_soqlfor mobile cache — usecheck_mobile_cache_status() - DO NOT try to query
LifeSciConfigRecordwithrun_soql— it requires the Tooling API - DO NOT suggest OmniStudio/FlexCard/OmniScript for mobile — NOT available on LSC Mobile iPad app
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.

