ClaimRev Support Documentation

User Tools

Site Tools

Trace:
openemr_manual

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
openemr_manual [2026/03/20 15:11] – Add Recoupment Report docs, update version to 2.1.0, expand compat shim list brad.sharpopenemr_manual [2026/05/22 22:34] (current) – Fix Method 2: OE Manage Modules has no zip-upload UI for custom modules — extract zip and drop files into custom_modules/ via SFTP instead brad.sharp
Line 21: Line 21:
     - [[#X12 Tracker|X12 Tracker]]     - [[#X12 Tracker|X12 Tracker]]
     - [[#Appointments|Appointments]]     - [[#Appointments|Appointments]]
 +    - [[#Calendar Eligibility Indicators|Calendar Eligibility Indicators]]
 +    - [[#Eligibility Sweep|Eligibility Sweep]]
     - [[#Notifications|Notifications]]     - [[#Notifications|Notifications]]
   - [[#Compatibility|Compatibility]]   - [[#Compatibility|Compatibility]]
Line 35: Line 37:
   * An active ClaimRev account with API credentials   * An active ClaimRev account with API credentials
  
-==== Download ====+==== Choose Your Install Method ====
  
-Download the latest version of the ClaimRev Connect module:+The ClaimRev Connect module is published on Packagist as ''claimrevolution/oe-module-claimrev-connect''. Starting with v2.1.3 a **single build** runs on both OpenEMR 7.x and OpenEMR 8.x — runtime compatibility shims in ''src/Compat/'' activate only when the host core lacks the newer APIs. Pick the install method that matches your environment.
  
-**Current Version: 2.1.0**+**Current Version: 2.1.3**
  
-~~NOTOC~~+=== Method 1: Composer (Recommended) ===
  
-| **Module File** | {{ :oe-module-claimrev-connect.zip | OpenEMR Module}} | +If you have CLI access to your OpenEMR install:
-| **Released** | March 20, 2026 | +
-| **Changelog** | See [[#Changelog|Changelog]] below |+
  
-**Note:** If you do not yet have a ClaimRev account, visit [[https://www.claimrev.com|claimrev.com]] or contact us at [[mailto:sales@claimrev.com|sales@claimrev.com]] to get started.+<code bash> 
 +cd /path/to/openemr 
 +composer require claimrevolution/oe-module-claimrev-connect:^2.1 
 +sudo systemctl reload php-fpm   # or restart Apache 
 +</code>
  
-==== Installation Steps ====+Composer downloads the latest v2.1.x release, drops it into ''interface/modules/custom_modules/oe-module-claimrev-connect/'', and updates the autoloader. Continue with [[#Activation|Activation]] below.
  
-  - Download the **oe-module-claimrev-connect.zip** file above. +To **update** the module later: 
-  - Log into OpenEMR as an administrator. + 
-  - Navigate to **Modules > Manage Modules**. +<code bash> 
-  - Click the **Install** tab, then click **Upload Module** and select the downloaded zip file. +composer update claimrevolution/oe-module-claimrev-connect 
-  - After upload completes, find **ClaimRev Connect** in the module list and click **Install**. +sudo systemctl reload php-fpm 
-  - Once installed, click **Enable** to activate the module.+</code> 
 + 
 +=== Method 2: Manual File Drop (Shared Hosting / No CLI) === 
 + 
 +OpenEMR's //Manage Modules// page does not have a zip-upload feature for custom modules — it scans ''interface/modules/custom_modules/'' on every page load and lists whatever directories it finds. For installs without CLI access (shared hosting, restricted environments), drop the files into place via SFTP/FTP: 
 + 
 +  - Download the current release zip from [[https://github.com/claimrevolution/oe-module-claimrev-connect/releases|the GitHub releases page]]. 
 +  - Unzip it locally. You should see a folder named ''oe-module-claimrev-connect/'' containing ''composer.json'', ''info.txt'', ''src/'', ''public/'', ''templates/'', etc. 
 +  - Connect to your OpenEMR server with SFTP, FTP, or your hosting control panel's file manager. 
 +  - Upload the entire ''oe-module-claimrev-connect/'' folder into ''interface/modules/custom_modules/'' so the resulting path is ''interface/modules/custom_modules/oe-module-claimrev-connect/composer.json'' (and so on for the other files). 
 +  - Continue with [[#Activation|Activation]] below — OpenEMR will see the new directory on the next page load. 
 + 
 +**Note:** Updates with this method are the same flow — replace the contents of the ''oe-module-claimrev-connect/'' folder with the contents of the new zip. Method 1 (Composer) is much easier if you have any way to run shell commands on the server. 
 + 
 +=== Method 3: Release Tarball === 
 + 
 +If you installed OpenEMR via an official release tarball that already bundles ''claimrevolution/oe-module-claimrev-connect'' in its ''composer.json'', the module arrives pre-extracted at ''interface/modules/custom_modules/oe-module-claimrev-connect/''. No additional download step. 
 + 
 +==== Activation (all methods) ==== 
 + 
 +  - In OpenEMR, navigate to **Modules > Manage Modules**. 
 +  - Find **ClaimRev Connect** in the module list. Click **Install**, then **Enable**.
   - Navigate to **ClaimRev Connect > Setup** and click **Run Upgrade** to create the required database tables.   - Navigate to **ClaimRev Connect > Setup** and click **Run Upgrade** to create the required database tables.
 +
 +**Note:** If you do not yet have a ClaimRev account, visit [[https://www.claimrev.com|claimrev.com]] or contact us at [[mailto:sales@claimrev.com|sales@claimrev.com]] to get started.
  
 --- ---
Line 110: Line 137:
 ==== Claims Submission ==== ==== Claims Submission ====
  
-The module enables electronic claim submission (837P/837I/837D) to payers through ClaimRev.+The module enables electronic claim submission (837P/837I) to payers through ClaimRev.
  
   * Claims are submitted from the OpenEMR billing manager   * Claims are submitted from the OpenEMR billing manager
Line 206: Line 233:
  
 === Test Mode === === Test Mode ===
-A **Test Mode** toggle is available below the search button. When enabled: +When the **Enable Test Mode** global is on (Admin > Globals > ClaimRev Connect), the Payment Advice, ERA, and Reconciliation pages return **mock data** generated from local OpenEMR billing rows. Useful for demos, training, and posting-workflow rehearsal without hitting the live ClaimRev API.
-  * The search returns **mock data** instead of calling the ClaimRev API, allowing you to practice the posting workflow without real data. +
-  * Posting still writes to OpenEMR (useful for testing with a development database). +
-  * Claims are **not** marked as worked in ClaimRev when test mode is active. +
-  * A yellow warning banner is displayed to remind you that test mode is active.+
  
-**Important:** Only use test mode in development or training environments. Do not enable test mode in production with real patient data unless you understand that mock ERA data will be posted to OpenEMR.+  * Posting still writes to OpenEMR — useful when running against a development database. 
 +  * Claims are **not** marked as worked in ClaimRev while the global is on. 
 +  * Reconciliation row actions (Sync rejected status, Requeue) short-circuit to a fake-success response. 
 +  * ERA Download returns a 0-byte placeholder file. 
 + 
 +**Important:** Only enable the global in development or training environments. The global is the only switch — there is no longer a per-search checkbox.
  
 ==== Reconciliation ==== ==== Reconciliation ====
Line 511: Line 539:
   * **Demographics** - Verify patient demographic information with the payer   * **Demographics** - Verify patient demographic information with the payer
   * **MBI Finder** - Look up a patient's Medicare Beneficiary Identifier   * **MBI Finder** - Look up a patient's Medicare Beneficiary Identifier
 +
 +**Note:** Eligibility, Coverage Discovery, and MBI Finder are mutually exclusive; only one of them can be selected at a time. Demographics can be combined with any of those three.
  
 === How to Run an Eligibility Check === === How to Run an Eligibility Check ===
Line 517: Line 547:
   - Select one or more products to check using the checkboxes.   - Select one or more products to check using the checkboxes.
   - Click **Check Now** for immediate results, or **Queue Check** to process in the background.   - Click **Check Now** for immediate results, or **Queue Check** to process in the background.
-  - Results appear in tabbed sections: Quick Info, Deductibles, Benefits, Medicare, and Validations.+  - Results appear in tabbed sections: Quick Info, Deductibles, Benefits, Medicare, and Validations. The same layout is used for both Eligibility and Coverage Discovery results, since the payer returns the same response shape for both. 
 + 
 +=== Patients With No Insurance === 
 +Coverage Discovery, Demographics, and MBI Finder query the payer using patient demographic data and don't need an insurance row, so the eligibility tab is still available for patients who have no insurance entered. In that case the tab is labelled **No Insurance**, the **Eligibility** option is hidden, and **Coverage Discovery** is pre-selected. Add the matched coverage afterwards through the normal Insurance card workflow if you want to keep it. 
 + 
 +=== Reset Cached Results === 
 +A red **Reset** button next to **Check Now** clears every cached eligibility row for the current patient (across all payer responsibilities). Useful when re-testing a fresh check or after fixing patient demographics that produced a bad result. The button asks for confirmation before deleting.
  
 === Eligibility AI Assistant === === Eligibility AI Assistant ===
Line 535: Line 571:
   * Search for available ERA files by date range   * Search for available ERA files by date range
   * Download individual files for import into the OpenEMR billing system   * Download individual files for import into the OpenEMR billing system
 +  * When **Enable Test Mode** is on, the ERA tab returns mock search results from local billing data and the Download button returns a 0-byte placeholder file.
  
 ==== X12 Tracker ==== ==== X12 Tracker ====
Line 546: Line 583:
 ==== Appointments ==== ==== Appointments ====
  
-The **Appointments** tab provides visibility into appointment-related data synced with ClaimRev, supporting eligibility verification workflows tied to scheduled visits.+The **Appointments** tab provides a comprehensive view of upcoming appointments with integrated eligibility verification, allowing front-desk staff and billers to ensure patients have active coverage before their visit. 
 + 
 +=== Search and Filtering === 
 +Filter appointments using any combination of: 
 +  * **Date Range** — Start and end date (defaults to today through 7 days out) 
 +  * **Facility** — Filter by service location 
 +  * **Provider** — Filter by rendering provider 
 +  * **Eligibility Status** — Filter by: 
 +    * **All** — Show all appointments 
 +    * **Needs Attention** — Appointments with no eligibility check, errors, or stale results 
 +    * **Active Coverage** — Appointments where eligibility returned successfully 
 +    * **Not Checked** — Appointments with no eligibility record at all 
 +    * **Stale** — Appointments where the eligibility check is older than the configured stale threshold 
 + 
 +=== Results Table === 
 +Each appointment row displays: 
 + 
 +| **Column** | **Description** | 
 +| Checkbox | Select for bulk actions | 
 +| Date | Appointment date | 
 +| Time | Appointment start time | 
 +| Patient | Patient last name, first name | 
 +| DOB | Patient date of birth | 
 +| Provider | Rendering provider | 
 +| Facility | Service location | 
 +| Eligibility Status | Color-coded status: Active Coverage (green), Pending (orange), Error (red), Not Checked (gray). Payer name and response messages are shown below the status. | 
 +| Last Checked | Date/time of the most recent eligibility check, or "Never" | 
 +| Actions | Per-row action buttons | 
 + 
 +=== Actions === 
 +  * **Check Now** — Immediately runs an eligibility check for the appointment via AJAX and updates the status in-place without a page reload. Shows a spinner while processing. 
 +  * **Queue** — Queues the eligibility check for background processing by the send/receive service. 
 +  * **Queue Selected** — Queues all checked appointments (or all if none are checked) for background eligibility processing. 
 +  * **Check Now Selected** — Runs immediate eligibility checks for all checked appointments in parallel via AJAX, updating each row's status as results come back. 
 + 
 +=== Detail View === 
 +For appointments with completed eligibility results, an expandable detail row shows the full eligibility response including the quick info summary with benefit details parsed from the 271 response. 
 + 
 +==== Calendar Eligibility Indicators ==== 
 + 
 +When enabled, color-coded indicators appear on appointment blocks in the main OpenEMR calendar, giving providers and staff an at-a-glance view of each patient's eligibility status. 
 + 
 +=== How It Works === 
 +The module hooks into the calendar's event rendering system and adds a colored left border to each appointment block based on the patient's primary insurance eligibility status: 
 + 
 +| **Color** | **CSS Class** | **Meaning** | 
 +| Green | ''event_elig_active'' | Active coverage confirmed | 
 +| Red | ''event_elig_inactive'' / ''event_elig_error'' | Inactive coverage or eligibility check error | 
 +| Yellow | ''event_elig_unchecked'' / ''event_elig_stale'' | Never checked or results older than the stale threshold | 
 +| Blue | ''event_elig_pending'' | Eligibility check queued and waiting for response | 
 + 
 +=== Performance === 
 +Eligibility data for all patients visible on the calendar is loaded in a single batch query, minimizing database overhead. However, on very busy calendars with many appointments, enabling this feature may have a minor impact on calendar load time. 
 + 
 +=== Configuration === 
 +  * Navigate to **Admin > Config > Connectors > ClaimRev Connect** 
 +  * Set **Enable Calendar Eligibility Indicators** to //Yes// 
 +  * The stale threshold is controlled by the **Eligibility Age To Stale** setting (in days) 
 + 
 +==== Eligibility Sweep ==== 
 + 
 +The Eligibility Sweep is an automated background service that proactively queues eligibility checks for upcoming appointments on a scheduled basis, ensuring patients have current coverage verification before they arrive. 
 + 
 +=== How It Works === 
 +  - The sweep runs as a background service once per day (every 1440 minutes). 
 +  - On each run, it checks whether today is one of the configured sweep days. 
 +  - If it is a sweep day, it looks ahead N days for appointments where eligibility is: 
 +    * **Missing** — No eligibility record exists (never checked) 
 +    * **In Error** — Previous check returned an error 
 +    * **Stale** — Results are older than the configured stale threshold 
 +  - Appointments already queued (''waiting'' or ''creating'' status) are skipped to avoid duplicates. 
 +  - Matching appointments are queued for the existing eligibility send/receive background service to process. 
 + 
 +=== Configuration === 
 +Navigate to **Admin > Config > Connectors > ClaimRev Connect** and configure: 
 + 
 +| **Setting** | **Description** | **Default** | 
 +| Enable Eligibility Sweep | Turn the sweep service on or off | Off | 
 +| Sweep Days | Comma-separated day numbers: 0=Sun, 1=Mon, 2=Tue, 3=Wed, 4=Thu, 5=Fri, 6=Sat | 1,4 (Mon, Thu) | 
 +| Sweep Lookahead Days | Number of days ahead to check for appointments | 7 | 
 + 
 +The stale threshold is shared with other eligibility features and is controlled by the **Eligibility Age To Stale** setting. 
 + 
 +=== Example === 
 +With the default settings (sweep on Monday and Thursday, 7-day lookahead): 
 +  * On Monday morning, the sweep queues eligibility checks for all appointments through the following Monday. 
 +  * On Thursday, it queues checks for appointments through the following Thursday. 
 +  * Appointments that already have fresh eligibility results are skipped. 
 + 
 +This ensures that by the time a patient arrives, their eligibility has been verified within the last few days.
  
 ==== Notifications ==== ==== Notifications ====
Line 557: Line 683:
  
 ==== Supported OpenEMR Versions ==== ==== Supported OpenEMR Versions ====
-The ClaimRev Connect module supports: +The ClaimRev Connect module ships as a **single binary** covering: 
-  * **OpenEMR 8.x** — Full native support +  * **OpenEMR 8.x** (master and the 8.0.x patch line) — verified against ''openemr/openemr:flex'' and ''openemr/openemr:8.0.0.3-2026-03-25''. 
-  * **OpenEMR 7.x** — Supported via built-in compatibility shims+  * **OpenEMR 7.x** (7.0.0 and later) — verified against ''openemr/openemr:7.0.2''.
  
-The module includes automatic compatibility shims for classes and interfaces introduced in OpenEMR 8.x. On OpenEMR 7.x, these shims provide equivalent functionality by wrapping legacy APIs directly. On 8.x, the shims are never loaded — the native classes are used.+The ''src/Compat/'' shim layer activates per-host. On OE 8.x cores that already expose the modern APIs the shims are no-ops; on OE 7.x or older 8.0.x cores the shims provide ''OEGlobalsBag'', ''CryptoInterface'', and ''ServiceContainer'' via ''class_alias'', and ''CsrfHelper'' detects the active ''CsrfUtils'' signature at runtime.
  
 === Shimmed Components === === Shimmed Components ===
  
-| **Component** | **What the shim does on 7.x** | +| **Component** | **What the shim does on older cores** | 
-| ''OEGlobalsBag'' | Wraps ''$GLOBALS'' with typed getters |+| ''OEGlobalsBag'' | Wraps ''$GLOBALS'' with typed getters (used directly on 7.x; on 8.0.x patch line the module imports the shim explicitly because the core's ''OEGlobalsBag'' is thinner than expected) |
 | ''ServiceContainer'' | Wraps ''CryptoGen'' and other services directly | | ''ServiceContainer'' | Wraps ''CryptoGen'' and other services directly |
 | ''LoggerInterface'' (''getLogger'') | Provides a PSR-3 logger via OpenEMR's ''SystemLogger'' | | ''LoggerInterface'' (''getLogger'') | Provides a PSR-3 logger via OpenEMR's ''SystemLogger'' |
 | ''ClockInterface'' (''getClock'') | Provides a PSR-20 clock returning the current time | | ''ClockInterface'' (''getClock'') | Provides a PSR-20 clock returning the current time |
 | ''CryptoInterface'' | Wraps ''CryptoGen'' behind the 8.x crypto interface | | ''CryptoInterface'' | Wraps ''CryptoGen'' behind the 8.x crypto interface |
 +| ''CsrfHelper'' | Detects whether ''SessionWrapperFactory::getActiveSession'' exists; routes to ''CsrfUtils'' with the correct argument order and ''$_SESSION'' fallback when needed |
 +| ''GlobalConfig::getClientSecret'' | Prefers ''CryptoGen::decryptFromDatabase'' (upstream PR #11956, May 2026) when available; falls back to ''decryptStandard'' on older cores |
  
 ==== Compatibility Check ==== ==== Compatibility Check ====
Line 584: Line 712:
     * OpenEMR version and PHP version     * OpenEMR version and PHP version
  
-If all checks show green, the module is fully operational. If any check shows "Using ClaimRev shim (7.x mode)", the module is running with compatibility shims — all features work normally.+If all checks show green, the module is fully operational. If any check shows "Using ClaimRev shim", the module is running with compatibility shims — all features work normally.
  
 --- ---
Line 600: Line 728:
   * Ensure the payer is enrolled for eligibility transactions — see [[payer_enrollment|Payer Enrollments]]   * Ensure the payer is enrolled for eligibility transactions — see [[payer_enrollment|Payer Enrollments]]
   * Check that the subscriber ID and patient demographics are accurate   * Check that the subscriber ID and patient demographics are accurate
 +
 +==== "Error communicating with server" When Running Check Now ====
 +  * Most common cause is the upstream ClaimRev API taking longer than the script's allowed run time. The 2.1.2 build raises the script time limit and adds OAuth retries — make sure you're on 2.1.2 or later.
 +  * Click **Reset** next to **Check Now** to clear cached results and try again. A retry usually succeeds because the previous request finished server-side after the browser gave up.
 +  * If the error reproduces every time on a specific patient, capture the OpenEMR error log entry around the failed check (see **Connectivity** for log location) and contact ClaimRev support.
  
 ==== Claims Not Appearing in ClaimRev ==== ==== Claims Not Appearing in ClaimRev ====
Line 616: Line 749:
   * Navigate to **Setup** and click **Run Upgrade** to ensure the ''mod_claimrev_patient_statements'' table exists   * Navigate to **Setup** and click **Run Upgrade** to ensure the ''mod_claimrev_patient_statements'' table exists
   * Try lowering the **Min Amount** filter or clearing all filters   * Try lowering the **Min Amount** filter or clearing all filters
 +
 +==== Calendar Indicators Not Showing ====
 +  * Verify the **Enable Calendar Eligibility Indicators** setting is turned on in **Admin > Config > Connectors > ClaimRev Connect**
 +  * Make sure the module is fully configured (API credentials set) — calendar indicators only register when the module is configured
 +  * Check that patients have eligibility records in the system — appointments for patients with no eligibility data will show a yellow (unchecked) indicator
 +  * Clear your browser cache and reload the calendar
 +
 +==== Eligibility Sweep Not Running ====
 +  * Verify the **Enable Eligibility Sweep** setting is turned on
 +  * Check that today is one of the configured **Sweep Days** (0=Sun through 6=Sat)
 +  * Confirm the ''ClaimRev_Elig_Sweep'' background service is active in **Admin > System > Background Services**
 +  * Check the OpenEMR error log for sweep-related messages (search for "ClaimRev Eligibility Sweep")
 +  * The sweep runs once per day (every 1440 minutes) — it will not re-run on the same day
  
 ==== Database Upgrade Errors ==== ==== Database Upgrade Errors ====
Line 624: Line 770:
   * Confirm the module is both **installed** and **enabled** in Modules > Manage Modules   * Confirm the module is both **installed** and **enabled** in Modules > Manage Modules
   * Clear your browser cache and reload the page   * Clear your browser cache and reload the page
 +
 +==== "Wrong build" Symptoms ====
 +If you installed the //OpenEMR 8.x// build on a 7.x install (or vice versa), you may see:
 +  * **Fatal error: Class "OpenEMR\Core\OEGlobalsBag" not found** when loading any module page on 7.x — uninstall and use the //OpenEMR 7.x// build.
 +  * **Call to undefined method ... CsrfUtils::collectCsrfToken()** with a different signature error — same fix; download the build that matches your OpenEMR major version.
  
 --- ---
  
 ===== Changelog ===== ===== Changelog =====
 +
 +== Version 2.1.3 — May 22, 2026 (Packagist edition) ==
 +  * **Now published on Packagist** as ''claimrevolution/oe-module-claimrev-connect''. Install via ''composer require claimrevolution/oe-module-claimrev-connect:^2.1''. Replaces the previous May 12 (OE 7.x) and May 13 (OE 8.0.x rebuild) separate-zip builds with a single binary.
 +  * **Single-binary cross-version compatibility** — the ''src/Compat/'' shim layer lives in the module's own repo on GitHub, not duplicated across two build branches. Same code path runs on OE 8.x master, the OE 8.0.x patch line, and OE 7.x.
 +  * **Crypto helper hardened for cross-version** — ''GlobalConfig::getClientSecret'' uses ''CryptoGen::decryptStandard'' (works on both OE 7.x and 8.x) instead of the OE 8.x-only ''decryptFromDatabase''.
 +  * **X12_SFTP install fix** — module enable no longer references the non-existent ''background_services.last_run'' column that had been breaking installs on OE 8.x master.
 +
 +== Version 2.1.3 — May 13, 2026 rebuild for OE 8.0.x ==
 +  * **OpenEMR 8.x build rebuilt from the ''release/v8-0'' branch.** The previous 8.x build assumed every 8.x core exposed ''OEGlobalsBag::getKernel'', ''SessionWrapperFactory::getActiveSession'', and ''CsrfUtils::collectCsrfToken(session, subject)''. The OE 8.0.x patch line has none of those — its ''OEGlobalsBag'' is thin, ''SessionWrapperFactory'' uses a different acquisition pattern, and ''CsrfUtils::collectCsrfToken'' takes ''(subject, ?session)'' with a ''$_SESSION'' fallback. The new build ships the ''src/Compat/'' shim layer with runtime-detection for the divergent APIs so the same zip works on 8.0.0.3 and on newer 8.x / master.
 +  * **Verified against ''openemr/openemr:8.0.0.3-2026-03-25''** with full patient + encounter + billing data copied from a flex install. Login, navigation, Claims tab, Reconciliation, Payment Advice, ERA, and Setup all load cleanly.
 +  * **Cross-core crypto handling** — ''GlobalConfig::getClientSecret'' now prefers the newer ''CryptoGen::decryptFromDatabase'' (upstream PR #11956, May 2026) when present and falls back to ''decryptStandard'' transparently. The 2.1.3 hotfix-only revert in the original 8.x build (which always called ''decryptStandard'') is no longer needed.
 +  * Module version constant stays at **2.1.3**; this is a rebuild of the same release for the actual 8.0.x patch line.
 +
 +== Version 2.1.3 (May 2026) ==
 +  * **Security release** — Closes the ten findings raised by the Aisle security review on the upstream PR. The fixes are layered:
 +    * **IDOR guards on eligibility endpoints** — A new ''PatientContext'' helper resolves the session-active patient and the //Check Now// (''eligibility_check_now''), //Reset// (''eligibility_clear''), and //AI chat// (''eligibility_chat'') endpoints now refuse a ''pid'' that does not match. The chat endpoint additionally re-verifies the supplied ''sharpRevenueObjectId'' belongs to that patient via the stored response payload.
 +    * **CSRF on appointment queue actions** — ''appointments.php'' now verifies the existing eligibility CSRF token before either bulk or single ''Queue'' POST handler runs and emits the hidden token in ''#bulkForm''.
 +    * **Authoritative re-fetch for posting + status sync** — ''payment_advice_post.php'' accepts only ''paymentAdviceId'' (single) or ''paymentAdviceIds'' (batch JSON) and re-fetches the authoritative ''ClaimPaymentAggregation'' from ClaimRev before posting. ''claim_sync_status.php'' accepts only ''claimrevObjectId'' and derives the status fields from a re-fetched claim. Browser-supplied amounts, encounter PCNs, or status codes can no longer drive an OE write.
 +    * **Test-mode gating** — The ''skipMarkWorked'' POST flag on payment posting is only honored when ''isTestModeEnabled()'' is true, so a regular user can't suppress the upstream mark-as-worked side effect.
 +    * **Path traversal hardening** — ''EligibilityTransfer'' allowlists ''claimRevResultId'' to ''[A-Za-z0-9_-]'' (with a server-generated fallback) before composing the raw 271 save path.
 +    * **CSV export header sanitization** — ''claim_export_csv'' basename-strips control characters and restricts the API-supplied filename to a conservative charset before emitting it in ''Content-Disposition''. The header is no longer susceptible to CR/LF injection.
 +    * **Module-enable consent** — ''ClaimRevModuleSetup::ensureCoreSftpEnabled'' only flips the X12_SFTP background service to ''active = 1'' on a truly fresh install (''last_run IS NULL''). An admin who deliberately disabled the service keeps that setting across module re-enables.
 +    * **Payment posting race window** — ''PaymentAdvicePostingService::post'' wraps the duplicate check and ''arPostSession'' insert in a MySQL named lock keyed by ''paymentAdviceId''. Concurrent submits of the same advice can no longer post twice; the second call returns a clear //concurrent post in progress// message.
 +  * **Cross-core crypto compatibility** — ''GlobalConfig::getClientSecret'' originally kept calling ''CryptoGen::decryptStandard'' (the legacy API) instead of the newer ''decryptFromDatabase'' that upstream PR #11956 introduced in May 2026. The new method does not exist on older OpenEMR cores most installs still run, and using it would break the Connectivity tab on those installs. //(The May 13 rebuild above changes this to a runtime-detected fallback so the same module works on both.)//
 +
 +== Version 2.1.2 (May 2026) ==
 +  * **Eligibility request body** — Send ''serviceTypeCodes'' as a JSON array (''List<string>'') instead of a comma-separated string, and always emit ''isRevenueToolsPayerId: false'' on each payer entry. The ClaimRev API tightened request validation and started rejecting the older shape with HTTP 400, breaking **Check Now**. Empty service-type-code configuration still asks for all benefits.
 +  * **MBI Finder mutex + request shape** — MBI Finder is now mutually exclusive with Eligibility (matching the existing Coverage Discovery / Eligibility mutex). The ''payers'' array is omitted when only non-eligibility products are selected, since the API ignores it for those products and its presence corrupts MBI Finder results. When MBI Finder is requested, the subscriber number is copied to the top-level ''subscriberId'' field where MBI Finder reads it.
 +  * **Coverage Discovery results render correctly** — Coverage Discovery now renders with the full Quick Info / Deductibles / Benefits / Medicare / Validations layout. The API returns the same response shape as Eligibility, but the old Coverage Discovery view only showed the flat top-level coverage fields and dropped the nested benefit and deductible data.
 +  * **Run without insurance** — Coverage Discovery, Demographics, and MBI Finder can now be run on patients who have no insurance entered. The eligibility tab shows a **No Insurance** view that hides the Eligibility option, pre-selects Coverage Discovery, and submits a request built from patient demographics alone.
 +  * **Stop "Error communicating with server" on slow checks** — The eligibility AJAX endpoint can sit through a Cloud Run cold start (~60s) plus a ''retryLater'' poll loop (~60s) on Coverage Discovery, which exceeded PHP's default 30-second ''max_execution_time''. The Check Now and Appointment Check Now endpoints now allow up to 180 seconds, the Guzzle clients have explicit ''connect_timeout'' / ''timeout'' set so a stuck call can't burn the whole budget, and the OAuth token POST is retried up to two extra times on transient B2C hiccups.
 +  * **Reset button** — A red **Reset** button next to **Check Now** clears every cached eligibility row for the current patient (across all payer responsibilities) after a confirmation prompt. Useful when re-testing a check from a clean slate.
 +
 +== Version 2.1.1 (May 2026) ==
 +  * **Two-build distribution** — The module now ships as separate downloads for OpenEMR 8.x and 7.x. The 8.x build targets the native 8.x classes directly; the 7.x build adds the compatibility shim layer. Pick the build that matches your OpenEMR major version.
 +  * **Hardening pass** — CSRF verification added to all state-changing AJAX endpoints (eligibility check/sync/chat, appointment check, claim mark-worked, CSV export). Bootstrap stops issuing per-request UPDATE writes and respects an admin-disabled core SFTP setting. Watchdog excludes itself from the stuck-service reset query so a long-running watchdog can't clear its own running flag.
 +  * **Bug fixes** — Eligibility Sweep now correctly includes Sunday (''0'') in the configured sweep days. ''claim_export_csv'' parses request input through the typed boundary helper rather than passing raw ''$_POST'' to the service. Menu entry hidden from users without ''acct/bill'' access. Migration runner uses ''QueryUtils::escapeTableName/escapeColumnName'' for schema-validated identifier escaping.
 +  * **Standards** — All module PHP files declare ''strict_types=1'' to catch type coercion bugs at the boundary.
 +  * **Internal** — ''PaymentAdvicePostingService'' and ''ReconciliationService'' refactored to expose pure helpers (idempotency-reference building, PCN parsing, claim status labels, service-line aggregation, discrepancy classification) with PHPUnit isolated test coverage.
  
 == Version 2.1.0 (March 2026) == == Version 2.1.0 (March 2026) ==
Line 633: Line 823:
   * **Patient Balance Queue** — New tab showing encounters with outstanding patient responsibility after insurance has responded. Includes PR breakdown (deductible/coinsurance/copay parsed from ERA memos), per-code detail, statement tracking, and actions to generate statements or mark as sent   * **Patient Balance Queue** — New tab showing encounters with outstanding patient responsibility after insurance has responded. Includes PR breakdown (deductible/coinsurance/copay parsed from ERA memos), per-code detail, statement tracking, and actions to generate statements or mark as sent
   * **Claim Status Dashboard** — New work-queue tab with claim lifecycle timeline, real-time 276/277 status checks, batch sync, and manual notes   * **Claim Status Dashboard** — New work-queue tab with claim lifecycle timeline, real-time 276/277 status checks, batch sync, and manual notes
 +  * **Claim Lifecycle Tracking Tables** — New ''mod_claimrev_claims'' and ''mod_claimrev_claim_events'' database tables for tracking claim status, payer acceptance, ERA classification, paid amounts, and a full event audit trail (submitted, rejected, accepted, denied, ERA received, payment posted, etc.)
   * **AR Aging Report** — New analytics page with 30/60/90/120 day aging buckets grouped by payer, distribution visualization, and CSV export   * **AR Aging Report** — New analytics page with 30/60/90/120 day aging buckets grouped by payer, distribution visualization, and CSV export
   * **Denial Analytics** — New analytics page analyzing adjustment patterns by reason code, payer, and monthly trend with CARC code descriptions and CSV export   * **Denial Analytics** — New analytics page analyzing adjustment patterns by reason code, payer, and monthly trend with CARC code descriptions and CSV export
   * **Recoupment Report** — New analytics page identifying claims with reversed/recouped payments (e.g., Medicare reprocessing). Shows original payment, recoupment, reprocessed payment, net impact, and pending status with CSV export   * **Recoupment Report** — New analytics page identifying claims with reversed/recouped payments (e.g., Medicare reprocessing). Shows original payment, recoupment, reprocessed payment, net impact, and pending status with CSV export
   * **Analytics Dropdown** — AR Aging Report, Denial Analytics, and Recoupment Report grouped under an "Analytics" dropdown in the navigation bar   * **Analytics Dropdown** — AR Aging Report, Denial Analytics, and Recoupment Report grouped under an "Analytics" dropdown in the navigation bar
 +  * **Appointments Page Enhancements** — Added facility, provider, and eligibility status filters. Eligibility status filter supports All, Needs Attention, Active Coverage, Not Checked, and Stale views. Added "Check Now" and "Check Now Selected" buttons for real-time AJAX eligibility checks without page reload. Expandable detail rows show full eligibility response for completed checks.
 +  * **Calendar Eligibility Indicators** — Color-coded left borders on appointment blocks in the main OpenEMR calendar showing eligibility status at a glance (green=active, red=inactive/error, yellow=unchecked/stale, blue=pending). Uses batch query for performance. Enable via the new "Enable Calendar Eligibility Indicators" global setting.
 +  * **Eligibility Sweep Background Service** — New ''ClaimRev_Elig_Sweep'' background service that proactively queues eligibility checks for upcoming appointments on configured days of the week. Configurable sweep days (default Monday and Thursday) and lookahead window (default 7 days). Skips appointments with fresh results or already-queued checks.
   * **OpenEMR 7.x Compatibility** — Built-in compatibility shims (''OEGlobalsBag'', ''ServiceContainer'', ''LoggerInterface'', ''ClockInterface'', ''CryptoInterface'') allow the module to run on OpenEMR 7.x without modification   * **OpenEMR 7.x Compatibility** — Built-in compatibility shims (''OEGlobalsBag'', ''ServiceContainer'', ''LoggerInterface'', ''ClockInterface'', ''CryptoInterface'') allow the module to run on OpenEMR 7.x without modification
   * **Compatibility Check** — New diagnostic page (Connectivity > Run Compatibility Check) verifies all module dependencies resolve correctly   * **Compatibility Check** — New diagnostic page (Connectivity > Run Compatibility Check) verifies all module dependencies resolve correctly
Line 650: Line 844:
 == Version 1.0.0 == == Version 1.0.0 ==
   * Initial release   * Initial release
-  * Claims submission (837P/I/D)+  * Claims submission (837P/837I)
   * Real-time eligibility verification (Eligibility, Coverage Discovery, Demographics, MBI Finder)   * Real-time eligibility verification (Eligibility, Coverage Discovery, Demographics, MBI Finder)
   * AI-powered eligibility assistant   * AI-powered eligibility assistant
Line 656: Line 850:
   * Portal notifications   * Portal notifications
   * Native OpenEMR eligibility sync   * Native OpenEMR eligibility sync
- 
---- 
- 
-===== Support ===== 
- 
-If you need help with the ClaimRev Connect module: 
- 
-  * **Email**: [[mailto:support@claimrev.com|support@claimrev.com]] 
-  * **Phone**: 918-942-9564 
-  * **Hours**: Monday - Friday, 9 AM to 5 PM (CST) 
openemr_manual.1774019475.txt.gz · Last modified: by brad.sharp
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki