Differences

This shows you the differences between two versions of the page.

--- sharp_revenue_mock_scenario_intake [2026/05/06 14:36] – Document wildcard match-key semantics and the at-least-one rule brad.sharp
+++ sharp_revenue_mock_scenario_intake [2026/05/06 19:42] (current) – Document no-key product strip behavior at CSV import brad.sharp
@@ Line 30: / Line 30: @@
 ==== Required Columns ====
-The three Match* columns are individually optional, but **at least one of MatchSubscriberId, MatchPayerNumber, or MatchSubscriberSuffix must be set on every row.** A row with all three blank would catch every request to the endpoint and is rejected at import. A column left blank acts as a //wildcard// for that field — the scenario fires regardless of what the EMR sends for it.
+Every row must have **at least one match dimension** so it doesn't catch every request to its endpoint. The available dimensions are:
+  - **MatchSubscriberId / MatchPayerNumber / MatchSubscriberSuffix** — explicit match keys, set in the CSV. Used by Eligibility, Claim Status, and Prior Auth Verification scenarios where the request carries subscriber + payer.
+  - **Patient identity** (cartoon first name + last name + DOB) — //auto-stamped// at capture time for products that don't carry a subscriber/payer (Insurance Discovery, MBI Finder, Demographics, Advanced Medicaid). You don't fill this in via the CSV — see [[#Patient Identity Match Keys]] below.
+If you leave all three Match* columns blank for an Eligibility / Claim Status / Prior Auth row (which DO carry subscriber+payer in the request), the import is rejected because patient auto-stamp doesn't apply to those products. For no-key products (Insurance Discovery / MBI Finder / Demographics / Advanced Medicaid), leaving the Match* columns blank is normal — the patient auto-stamp gives the row its match dimension.
+**Important — what happens if you put Match* values on a no-key-product row anyway:** the import //silently strips them// before persisting. Insurance Discovery / MBI Finder / Demographics / Advanced Medicaid requests carry no subscriber id or payer number at runtime, so any Match* values you supply for those rows would never match real traffic. Stripping them lets the patient auto-stamp fire instead and gives the row a usable match key. If you actually want subscriber/payer-keyed matching, capture from a transaction that includes Eligibility (alone or alongside the no-key product) — mixed-product captures preserve your Match* values because the Eligibility component still carries subscriber/payer.
+A column left blank acts as a //wildcard// for that field — the scenario fires regardless of what the EMR sends for it.
 ^ Column ^ Required ^ Description ^
 | ScenarioName | yes | Short label the scenario will be filed under (e.g. ''Medicare-Active'', ''BCBS-Inactive'', ''Aetna-Pending''). Used as the human-readable name; not shown to the EMR. |
 | TransactionUrl | yes | The full //view-visit// URL copied in Step 1. ClaimRev parses the transaction id out of this server-side. |
-| MatchSubscriberId | optional | If set, the scenario only replays when the EMR's Subscriber Id matches this value exactly. **Leave blank to match any subscriber id** (useful for "any patient on this payer" scenarios — pair with MatchPayerNumber). |
+| MatchSubscriberId | optional | If set, the scenario only replays when the EMR's Subscriber Id matches this value exactly. **Leave blank to match any subscriber id** (useful for "any patient on this payer" scenarios — pair with MatchPayerNumber). //Stripped at import for no-key product rows.// |
-| MatchPayerNumber | optional | If set, the scenario only replays when the request's Payer Number matches. **Use the Revenue Tools payer id**, not the claim payer id — see [[#A Note On Payer Ids]] below. **Leave blank to match any payer** (useful for "this specific patient regardless of which insurer the EMR sends" scenarios — pair with MatchSubscriberId). |
+| MatchPayerNumber | optional | If set, the scenario only replays when the request's Payer Number matches. **Use the Revenue Tools payer id**, not the claim payer id — see [[#A Note On Payer Ids]] below. **Leave blank to match any payer** (useful for "this specific patient regardless of which insurer the EMR sends" scenarios — pair with MatchSubscriberId). //Stripped at import for no-key product rows.// |
-| MatchSubscriberSuffix | optional | Magic-suffix override. Example: setting this to ''-PENDING'' attaches a "pending" variant to the same subscriber id. Leave blank for the normal scenario. |
+| MatchSubscriberSuffix | optional | Magic-suffix override. Example: setting this to ''-PENDING'' attaches a "pending" variant to the same subscriber id. Leave blank for the normal scenario. //Stripped at import for no-key product rows.// |
 | TargetAccountNumber | optional | **Leave blank.** ClaimRev fills this in when copying to your test account. |
 | Description | optional | One-liner describing what the scenario is for. Shows up in the Mock Library management page; helpful for your future self. |
@@ Line 52: / Line 61: @@
 Aetna-NotFound,https://portal.claimrev.com/sharprevenue/(revenueToolsOut:view-visit/65f2a1b3c4d5e6f7a8b9c0d5/eligibility),NOTREAL999,60054,,,Wrong member id,Shows the no-match flow.
 GenericMedicare,https://portal.claimrev.com/sharprevenue/(revenueToolsOut:view-visit/65f2a1b3c4d5e6f7a8b9c0d6/eligibility),,00060,,,Any-subscriber Medicare scenario,Wildcard subscriber - fires for any member id sent against Medicare.
+InsuranceDiscovery-Found,https://portal.claimrev.com/sharprevenue/(revenueToolsOut:view-visit/65f2a1b3c4d5e6f7a8b9c0d7/eligibility),,,,,Insurance discovery returns coverage,Patient identity auto-stamps from the cartoon scrub - no Match* columns needed.
 </code>
@@ Line 74: / Line 84: @@
   * **Scenario name** + a **Source** chip (your account number, or "Default" for ClaimRev-seeded entries).
   * **Endpoint** the scenario answers (currently ''RunTestsJSON'' for eligibility/coverage discovery, with claim-status to follow).
-  * **Match key summary** — Subscriber Id / Payer / Suffix.
+  * **Match key summary** — Subscriber Id / Payer / Suffix / Patient name / DOB (whichever are set on the row).
   * **Products** — auto-stamped at capture (e.g. ''Eligibility'' or ''Eligibility, Demographics''). See [[#Product-Aware Matching]] below for what subset semantics buy you.
   * **Description** — your own free-text label.
@@ Line 83: / Line 93: @@
   * **Run As Is** (▶) — synthesizes a SharpRevenueRequest using the scenario's match keys and posts it through ''RunSharpRevenue''. The response lands in the regular **Transaction Search** list — useful for confirming the round-trip works end-to-end.
   * **View Original** (⤴) — only shown for scenarios captured from a real transaction in your own account. Default-library entries don't have a source link.
-  * **Edit** (✎) — rename the scenario, update the description, adjust match keys (Subscriber Id / Payer / Suffix). Account number, products, and the canned response payload are immutable post-capture.
+  * **Edit** (✎) — rename the scenario, update the description, adjust match keys (Subscriber Id / Payer / Suffix / Patient name / DOB). Account number, products, and the canned response payload are immutable post-capture.
   * **Delete** (🗑) — only for scenarios you own. ClaimRev admins can also delete default-library entries.
@@ Line 93: / Line 103: @@
   - **Suffix override.** If the request's Subscriber Id ends with a known magic suffix (e.g. ''-PENDING''), the scenario tagged with that suffix wins — regardless of subscriber/payer.
-  - **Match on Account + Endpoint + Subscriber Id + Payer Number**, with the products filter (see below) applied on top. The lookup is **scoped to your test account** — your captured scenarios don't bleed into anyone else's library and vice versa. Match-key fields use //wildcard// semantics: a scenario whose ''MatchSubscriberId'' or ''MatchPayerNumber'' is blank matches **any** request value for that field. When more than one scenario could fire, **more-specific wins** — a scenario with both Subscriber Id and Payer Number set beats a scenario with only one set, which beats a scenario with neither (which can't be persisted anyway, see Step 2).
+  - **Match on Account + Endpoint + the five match-key dimensions** (Subscriber Id, Payer Number, Patient First Name, Patient Last Name, Patient DOB), with the products filter (see below) applied on top. The lookup is **scoped to your test account** — your captured scenarios don't bleed into anyone else's library and vice versa. Match-key fields use //wildcard// semantics: a stored field that is blank matches **any** request value for that field. When more than one scenario could fire, **more-specific wins** — fewer blank fields = more specific.
   - **Default library fallback.** If no match was found under your test account, the lookup retries against ClaimRev's curated default library — these are stock scenarios (e.g. a generic Medicare-Active) that work for any account in mock mode. //You don't manage these; they're pre-loaded by ClaimRev and live alongside your account-specific captures.//
   - **No match → loud error.** If neither account-specific nor default library scenarios match, the response is a Zoll-shaped error so the EMR sees something obviously wrong rather than stale data.
+==== Patient Identity Match Keys ====
+Some Sharp Revenue products don't carry a subscriber id or a payer number in the request — they discover something about a patient from the patient's demographics (name + DOB + SSN). These are:
+  * **Insurance Discovery** (product 3) — finds insurance for a patient.
+  * **MBI Finder** (product 5) — finds a Medicare MBI for a patient.
+  * **Demographics** (product 2) — verifies / supplements demographic data.
+  * **Advanced Medicaid** (product 4) — Medicaid-specific eligibility.
+For these products, the mock library can't match on subscriber/payer (the request doesn't have them). Instead, **patient identity is auto-stamped** at capture from the //anonymized// (cartoon) source patient: First Name, Last Name, and DOB. So a captured Insurance Discovery scenario fires for requests whose patient identity matches the captured cartoon name + DOB.
+The capture flow //also// silently strips any MatchSubscriberId / MatchPayerNumber / MatchSubscriberSuffix the CSV supplied for these rows — those values would never match a real no-key request, so removing them lets the patient auto-stamp give the scenario a usable match key.
+Two consequences worth knowing:
+  * **The captured response and the match key stay internally consistent.** Mock returns "Mickey Mouse / 1928-11-18" data for a request that asked about "Mickey Mouse / 1928-11-18" — coherent demo, no name mismatch in the EMR's UI.
+  * **Configure your test-EMR demo patients to match the cartoon names** stamped on your captured library. The Mock Library page surfaces the cartoon name + DOB you need to set up. Effectively a one-time "create these demo patients in your test EMR" handoff per captured library.
+The patient match key is **always** the anonymized cartoon name + cartoon-shifted DOB. Real patient PHI never lands on the persisted match key.
+If you want to capture **multiple** Insurance Discovery scenarios (e.g. "found insurance" vs "no insurance"), capture from different source transactions — each gets its own cartoon identity, so they discriminate naturally. If you want to override the auto-stamped name (e.g. so it matches a specific test patient your EMR already has set up), edit the scenario in the Mock Library page after capture.
 ==== A Note On Payer Ids ====
@@ Line 141: / Line 173: @@
   * Walks the embedded ''Raw271'' / ''Raw277'' EDI strings and rewrites the same fields //in place//, so the EDI you see in the captured response is structurally valid but PHI-free.
   * Replaces the response's ''ClientId'' with the test account it's filed under.
+  * Auto-stamps the cartoon patient name + DOB onto the persisted MatchKey for no-key products. Real patient PHI never reaches the match-key surface.
 The original production record is **not** modified — anonymization runs on a deep copy.
@@ Line 147: / Line 180: @@
   * **Pick scenarios that exercise different code paths** — at least one Active, one Inactive, one Not-Found, and one error or pending. That gives a meaningful demo without needing dozens of rows.
-  * **At least one match-key field must be set per row.** Subscriber Id alone is usually enough for a per-patient scenario; Payer Number alone is enough for a per-payer catch-all. An all-blank row is rejected at import — the system won't let you persist a scenario that would catch every request to its endpoint.
+  * **At least one match-key dimension must end up set on every row.** For Eligibility / Claim Status / Prior Auth: at least one of Subscriber Id / Payer Number / Suffix in the CSV. For Insurance Discovery / MBI Finder / Demographics / Advanced Medicaid: leave the Match* columns blank — patient identity auto-stamps from the cartoon scrub. An all-blank row that //also// can't auto-stamp (malformed source with no patient identity) is rejected.
+  * **Don't bother filling Match* columns on no-key product rows.** They're stripped at import. The patient auto-stamp is the sole match dimension for those scenarios.
   * **Blank match-key fields wildcard.** A row with Subscriber Id but no Payer Number fires for that subscriber on any payer; a row with Payer Number but no Subscriber Id fires for any subscriber on that payer. When two scenarios could both match, the more-specific one wins.
+  * **For no-key products, configure your EMR's demo patients to match the cartoon identities** stamped on your captured library. The cartoon names + DOBs are visible in **Revenue Tools → Admin → Mock Library**.
   * **Use Revenue Tools payer ids in match keys** — claim payer ids aren't translated by the mock pipeline, so an EMR request that sets ''isRevenueToolsPayerId: false'' won't fire a scenario tagged with the Revenue Tools id. See [[#A Note On Payer Ids]].
   * **Use clear scenario names.** ''Medicare-Active'', ''BCBS-Inactive-Termed'', and ''Aetna-Pending-Auth'' are far easier to discuss than ''Test1'' / ''Test2''.
@@ Line 158: / Line 193: @@
 **Q: Will my real patients' information ever appear in the test account?** \\
-No. Every captured scenario is anonymized before it's saved, and your real production data is not modified.
+No. Every captured scenario is anonymized before it's saved, and your real production data is not modified. The patient match keys auto-stamped onto the persisted MatchKey are the cartoon name + cartoon-shifted DOB only — never real PHI.
 **Q: Are my scenarios visible to other customers in their test accounts?** \\
@@ Line 164: / Line 199: @@
 **Q: My scenario isn't firing — what should I check?** \\
-Most common cause: payer-id mismatch. The mock matches on the Revenue Tools payer id only, so if your EMR is sending ''isRevenueToolsPayerId: false'' with a claim payer id (e.g. ''87726''), the mock looks up that exact value and won't find your scenario tagged with the Revenue Tools id (e.g. ''00060''). Switch the EMR client to send Revenue Tools ids for mock-mode demos. See [[#A Note On Payer Ids]] for the full picture. Other things worth checking: the practice's ZollHost is set to the mock sentinel, the request's Subscriber Id matches your scenario's match key (or your scenario's Subscriber Id is intentionally blank to wildcard), and the request's products are a superset of the scenario's tagged products.
+Most common cause: payer-id mismatch. The mock matches on the Revenue Tools payer id only, so if your EMR is sending ''isRevenueToolsPayerId: false'' with a claim payer id (e.g. ''87726''), the mock looks up that exact value and won't find your scenario tagged with the Revenue Tools id (e.g. ''00060''). Switch the EMR client to send Revenue Tools ids for mock-mode demos. See [[#A Note On Payer Ids]] for the full picture. For no-key products (Insurance Discovery / MBI Finder / Demographics / Advanced Medicaid), check that your EMR's demo patient name + DOB matches the cartoon identity stamped on the scenario — the Mock Library page shows what to use. Other things worth checking: the practice's ZollHost is set to the mock sentinel, the request's Subscriber Id matches your scenario's match key (or your scenario's Subscriber Id is intentionally blank to wildcard), and the request's products are a superset of the scenario's tagged products.
+**Q: I put a SubscriberId on my Insurance Discovery / MBI Finder row but my scenario isn't firing — why?** \\
+Insurance Discovery / MBI Finder / Demographics / Advanced Medicaid requests carry no subscriber id at runtime, so any value you supply for those rows can't ever match a real request. The import flow strips the Match* columns for no-key product rows and stamps patient identity instead. Open **Revenue Tools → Admin → Mock Library** to see the cartoon name + DOB the row is keyed on, and configure your test-EMR demo patient to match those.
 **Q: Can I have a scenario that fires for any patient on a particular payer?** \\
 Yes. Leave MatchSubscriberId blank and set only MatchPayerNumber. The blank field acts as a wildcard so any subscriber id on that payer matches the scenario. If a more specific scenario (both Subscriber Id and Payer Number set) also matches the same request, the specific one wins.
+**Q: How do I demo multiple Insurance Discovery / MBI Finder scenarios for different patients?** \\
+Capture from different source transactions — each one gets its own cartoon patient identity, which becomes the match key. Then configure that many demo patients in your test EMR with names + DOBs that match the cartoons. The Mock Library page shows you exactly which cartoon identity each scenario is keyed on.
 **Q: Can I update or remove a scenario later?** \\
-Yes. Open **Revenue Tools → Admin → Mock Library** and use the Edit / Delete actions. You can edit the name, description, and match keys; the response payload itself is immutable post-capture.
+Yes. Open **Revenue Tools → Admin → Mock Library** and use the Edit / Delete actions. You can edit the name, description, and match keys (Subscriber Id / Payer / Suffix / Patient name / DOB); the response payload itself is immutable post-capture.
 **Q: Do I need a special permission to send this CSV?** \\