ClaimRev Support Documentation

User Tools

Site Tools

Trace:
sharp_revenue_mock_scenario_intake

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
sharp_revenue_mock_scenario_intake [2026/05/05 19:50] – Per-practice scoping: each EMR gets its own scenarios at runtime brad.sharpsharp_revenue_mock_scenario_intake [2026/05/06 19:42] (current) – Document no-key product strip behavior at CSV import brad.sharp
Line 29: Line 29:
  
 ==== Required Columns ==== ==== Required Columns ====
 +
 +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 ^ ^ 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. | | 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. | | 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 will only replay when the EMR submits an eligibility request whose Subscriber Id matches this value exactly. | +| 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, only replays when the request's Payer Number matches. Combine with MatchSubscriberId for tighter matching. | +| 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. | | 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. | | Description | optional | One-liner describing what the scenario is for. Shows up in the Mock Library management page; helpful for your future self. |
Line 49: Line 60:
 Aetna-Inactive,https://portal.claimrev.com/sharprevenue/(revenueToolsOut:view-visit/65f2a1b3c4d5e6f7a8b9c0d4/eligibility),W987654321,60054,,,Termed coverage,Coverage termed last month. Aetna-Inactive,https://portal.claimrev.com/sharprevenue/(revenueToolsOut:view-visit/65f2a1b3c4d5e6f7a8b9c0d4/eligibility),W987654321,60054,,,Termed coverage,Coverage termed last month.
 Aetna-NotFound,https://portal.claimrev.com/sharprevenue/(revenueToolsOut:view-visit/65f2a1b3c4d5e6f7a8b9c0d5/eligibility),NOTREAL999,60054,,,Wrong member id,Shows the no-match flow. 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> </code>
  
Line 71: Line 84:
   * **Scenario name** + a **Source** chip (your account number, or "Default" for ClaimRev-seeded entries).   * **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).   * **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.   * **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.   * **Description** — your own free-text label.
Line 80: 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.   * **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.   * **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.   * **Delete** (🗑) — only for scenarios you own. ClaimRev admins can also delete default-library entries.
  
Line 90: 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.   - **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.
-  - **Exact 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 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.//   - **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.   - **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 ====
 +
 +The Sharp Revenue API supports **two flavors** of payer id (see the [[sharp_revenue_testing_guide#run_sharp_revenue|API Guide]] for the underlying flag):
 +
 +  * **Revenue Tools payer id** — ClaimRev's internal payer catalog id (e.g. ''00060'' for Medicare). Sent with ''isRevenueToolsPayerId: true''.
 +  * **Claim payer id** — the payer id your EMR uses on outbound 837 claims (e.g. ''87726'' for UnitedHealthcare). Sent with ''isRevenueToolsPayerId: false''. In production, the API translates this to the corresponding Revenue Tools id internally before contacting the vendor.
 +
 +**The mock pipeline matches on the Revenue Tools payer id only.** When ClaimRev captures a scenario, the ''MatchPayerNumber'' that gets stamped is the Revenue Tools id, and at runtime ''MockZollSend'' looks up scenarios using whatever payer id is on the wire. So:
 +
 +  * If your EMR sends ''isRevenueToolsPayerId: true'' with a Revenue Tools id (e.g. ''00060''), the mock will find a matching scenario tagged with ''00060''.
 +  * If your EMR sends ''isRevenueToolsPayerId: false'' with a claim payer id (e.g. ''87726''), the mock will look up ''87726'' as-is — and **won't find your ''00060'' scenario**, even though they're the same payer in production.
 +
 +**For mock-mode demos, configure your EMR client to send Revenue Tools payer ids** (set ''isRevenueToolsPayerId: true''). Once you switch back to real-mode for production traffic, claim payer ids work normally — the mismatch is mock-pipeline-specific.
  
 ==== Product-Aware Matching ==== ==== Product-Aware Matching ====
Line 124: 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.   * 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.   * 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. The original production record is **not** modified — anonymization runs on a deep copy.
Line 130: 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.   * **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.
-  * **Match keys are optional but recommended.** Without them, the only thing distinguishing one captured scenario from another is the order they were inserted; with them, your EMR's request data drives which scenario comes back. Subscriber Id alone is usually enough.+  * **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''.   * **Use clear scenario names.** ''Medicare-Active'', ''BCBS-Inactive-Termed'', and ''Aetna-Pending-Auth'' are far easier to discuss than ''Test1'' / ''Test2''.
   * **Suffix variants let one subscriber demo multiple states.** Capturing the same subscriber id under suffixes ''-PENDING'' and ''-ERROR'' lets your EMR demo "this patient came back pending yesterday but errored today."   * **Suffix variants let one subscriber demo multiple states.** Capturing the same subscriber id under suffixes ''-PENDING'' and ''-ERROR'' lets your EMR demo "this patient came back pending yesterday but errored today."
Line 139: Line 193:
  
 **Q: Will my real patients' information ever appear in the test account?** \\ **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?** \\ **Q: Are my scenarios visible to other customers in their test accounts?** \\
 No. Each EMR's test account has its own private mock library. The runtime lookup is scoped to your account — other customers can't see your captures, and you can't see theirs. The only shared bucket is ClaimRev's curated default library, which is read-only for customers. No. Each EMR's test account has its own private mock library. The runtime lookup is scoped to your account — other customers can't see your captures, and you can't see theirs. The only shared bucket is ClaimRev's curated default library, which is read-only for customers.
 +
 +**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. 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?** \\ **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?** \\ **Q: Do I need a special permission to send this CSV?** \\
Line 158: Line 224:
 **Q: How is this different from the letter-based mock rules in the [[sharp_revenue_testing_guide|API Guide]]?** \\ **Q: How is this different from the letter-based mock rules in the [[sharp_revenue_testing_guide|API Guide]]?** \\
 The letter-based rules (e.g. //"first name starts with H returns Active"//) are a generic vendor mock useful for synthetic test data. **Captured scenarios** let you demo with payloads that look like //your// production data — same payers, same member-id formats, same benefit details — without any real PHI. Use the letter-based rules when you don't have real data yet; use captured scenarios when you want a polished demo for a stakeholder. The letter-based rules (e.g. //"first name starts with H returns Active"//) are a generic vendor mock useful for synthetic test data. **Captured scenarios** let you demo with payloads that look like //your// production data — same payers, same member-id formats, same benefit details — without any real PHI. Use the letter-based rules when you don't have real data yet; use captured scenarios when you want a polished demo for a stakeholder.
- 
sharp_revenue_mock_scenario_intake.1778010656.txt.gz · Last modified: by brad.sharp
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki