sharp_revenue_mock_scenario_intake
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| sharp_revenue_mock_scenario_intake [2026/05/05 16:11] – Add Mock Library management UI section 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 13: | Line 13: | ||
| - You browse your own production Sharp Revenue transactions and pick the ones you'd like turned into demo scenarios. | - You browse your own production Sharp Revenue transactions and pick the ones you'd like turned into demo scenarios. | ||
| - You send ClaimRev a CSV listing each scenario by name, the transaction URL, and the match keys you want (subscriber id, payer number, optional suffix). | - You send ClaimRev a CSV listing each scenario by name, the transaction URL, and the match keys you want (subscriber id, payer number, optional suffix). | ||
| - | - ClaimRev anonymizes each transaction (cartoon names, scrubbed addresses, scrubbed embedded EDI) and saves it as a mock scenario. | + | - ClaimRev anonymizes each transaction (cartoon names, scrubbed addresses, scrubbed embedded EDI) and saves it as a mock scenario |
| - | - The scenarios are copied into your test account. | + | - At runtime, |
| ===== Step 1 — Find Your Transactions ===== | ===== Step 1 — Find Your Transactions ===== | ||
| Line 29: | Line 29: | ||
| ==== Required Columns ==== | ==== Required Columns ==== | ||
| + | |||
| + | Every row must have **at least one match dimension** so it doesn' | ||
| + | |||
| + | - **MatchSubscriberId / MatchPayerNumber / MatchSubscriberSuffix** — explicit match keys, set in the CSV. Used by Eligibility, | ||
| + | - **Patient identity** (cartoon first name + last name + DOB) — // | ||
| + | |||
| + | 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' | ||
| + | |||
| + | **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/ | ||
| + | |||
| + | A column left blank acts as a // | ||
| ^ Column ^ Required ^ Description ^ | ^ Column ^ Required ^ Description ^ | ||
| | ScenarioName | yes | Short label the scenario will be filed under (e.g. '' | | ScenarioName | yes | Short label the scenario will be filed under (e.g. '' | ||
| | TransactionUrl | yes | The full // | | TransactionUrl | yes | The full // | ||
| - | | MatchSubscriberId | optional | If set, the scenario | + | | MatchSubscriberId | optional | If set, the scenario only replays |
| - | | MatchPayerNumber | optional | If set, only replays when the request' | + | | MatchPayerNumber | optional | If set, the scenario |
| - | | MatchSubscriberSuffix | optional | Magic-suffix override. Example: setting this to '' | + | | MatchSubscriberSuffix | optional | Magic-suffix override. Example: setting this to '' |
| | 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, | Aetna-Inactive, | ||
| Aetna-NotFound, | Aetna-NotFound, | ||
| + | GenericMedicare, | ||
| + | InsuranceDiscovery-Found, | ||
| </ | </ | ||
| Line 55: | Line 68: | ||
| Email the CSV to your ClaimRev contact. Include: | Email the CSV to your ClaimRev contact. Include: | ||
| - | * Which **test account** the scenarios should land in (account number, e.g. '' | + | * Which **test account** the scenarios should land in (account number, e.g. '' |
| * Approximate timing — when do you need the demo ready by? | * Approximate timing — when do you need the demo ready by? | ||
| Line 71: | Line 84: | ||
| * **Scenario name** + a **Source** chip (your account number, or " | * **Scenario name** + a **Source** chip (your account number, or " | ||
| * **Endpoint** the scenario answers (currently '' | * **Endpoint** the scenario answers (currently '' | ||
| - | * **Match key summary** — Subscriber Id / Payer / Suffix. | + | * **Match key summary** — Subscriber Id / Payer / Suffix |
| - | * **Products** — auto-stamped at capture (e.g. '' | + | * **Products** — auto-stamped at capture (e.g. '' |
| * **Description** — your own free-text label. | * **Description** — your own free-text label. | ||
| * **Created** — capture timestamp. | * **Created** — capture timestamp. | ||
| Line 80: | Line 93: | ||
| * **Run As Is** (▶) — synthesizes a SharpRevenueRequest using the scenario' | * **Run As Is** (▶) — synthesizes a SharpRevenueRequest using the scenario' | ||
| * **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, | + | * **Edit** (✎) — rename the scenario, update the description, |
| * **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' | - **Suffix override.** If the request' | ||
| - | - **Exact match** | + | - **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 // |
| - **Default library fallback.** If no match was found under your test account, the lookup retries against ClaimRev' | - **Default library fallback.** If no match was found under your test account, the lookup retries against ClaimRev' | ||
| - **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' | ||
| + | |||
| + | * **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/ | ||
| + | |||
| + | 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 " | ||
| + | * **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 " | ||
| + | |||
| + | 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" | ||
| + | |||
| + | ==== A Note On Payer Ids ==== | ||
| + | |||
| + | The Sharp Revenue API supports **two flavors** of payer id (see the [[sharp_revenue_testing_guide# | ||
| + | |||
| + | * **Revenue Tools payer id** — ClaimRev' | ||
| + | * **Claim payer id** — the payer id your EMR uses on outbound 837 claims (e.g. '' | ||
| + | |||
| + | **The mock pipeline matches on the Revenue Tools payer id only.** When ClaimRev captures a scenario, the '' | ||
| + | |||
| + | * If your EMR sends '' | ||
| + | * If your EMR sends '' | ||
| + | |||
| + | **For mock-mode demos, configure your EMR client to send Revenue Tools payer ids** (set '' | ||
| ==== Product-Aware Matching ==== | ==== Product-Aware Matching ==== | ||
| - | Each captured scenario is auto-tagged with the **products** that ran in the original transaction | + | Each captured scenario is auto-tagged with the **products** that ran in the original transaction. Today the recognized product ids are: |
| + | |||
| + | ^ Id ^ Product ^ | ||
| + | | 1 | Eligibility | ||
| + | | 2 | Demographics | ||
| + | | 3 | Insurance Discovery | ||
| + | | 4 | Advanced Medicaid | | ||
| + | | 5 | MBI Finder | ||
| + | | 6 | Advanced Verifier | | ||
| + | | 7 | Prior Auth Verification | | ||
| + | |||
| + | At lookup time the scenario only fires if the request asks for a // | ||
| * A captured **Eligibility-only** scenario fires for an Eligibility request, and also for an Eligibility + Demographics combo request. | * A captured **Eligibility-only** scenario fires for an Eligibility request, and also for an Eligibility + Demographics combo request. | ||
| Line 113: | Line 173: | ||
| * Walks the embedded '' | * Walks the embedded '' | ||
| * Replaces the response' | * Replaces the response' | ||
| + | * 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 119: | 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 | + | * **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 |
| + | * **Don' | ||
| + | * **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 | ||
| + | * **Use Revenue Tools payer ids in match keys** — claim payer ids aren't translated by the mock pipeline, so an EMR request | ||
| * **Use clear scenario names.** '' | * **Use clear scenario names.** '' | ||
| * **Suffix variants let one subscriber demo multiple states.** Capturing the same subscriber id under suffixes '' | * **Suffix variants let one subscriber demo multiple states.** Capturing the same subscriber id under suffixes '' | ||
| * **Capture from the right product run.** If you're demoing eligibility, | * **Capture from the right product run.** If you're demoing eligibility, | ||
| + | * **Avoid capturing error-status transactions** as scenarios — when an eligibility request errored upstream there' | ||
| ===== Frequently Asked Questions ===== | ===== Frequently Asked Questions ===== | ||
| **Q: Will my real patients' | **Q: Will my real patients' | ||
| - | 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?** \\ | ||
| + | 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' | ||
| + | |||
| + | **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 '' | ||
| + | |||
| + | **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, | + | Yes. Open **Revenue Tools → Admin → Mock Library** and use the Edit / Delete actions. You can edit the name, description, |
| **Q: Do I need a special permission to send this CSV?** \\ | **Q: Do I need a special permission to send this CSV?** \\ | ||
| Line 143: | 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. //" | The letter-based rules (e.g. //" | ||
| - | |||
sharp_revenue_mock_scenario_intake.1777997468.txt.gz · Last modified: by brad.sharp
