Differences

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

--- openemr_manual [2026/05/13 22:03] – Refresh OE 8.x download notes for the release/v8-0 rebuild verified against 8.0.0.3-2026-03-25 brad.sharp
+++ openemr_manual [2026/10/17 14:41] (current) – brad.sharp
@@ Line 6: / Line 6: @@
   - [[#Download and Installation|Download and Installation]]
   - [[#Configuration|Configuration]]
+    - [[#Option A: ZITADEL key file|Option A: ZITADEL key file]]
+    - [[#Option B: Client ID and Client Secret|Option B: Client ID and Client Secret]]
   - [[#Features|Features]]
     - [[#Dashboard|Dashboard (Home)]]
@@ Line 35: / Line 37: @@
   * OpenEMR **7.0.0** or later (8.x recommended)
   * PHP **8.2** or later
-  * An active ClaimRev account with API credentials
+  * An active ClaimRev account with API credentials (a ZITADEL key file, or a client ID and secret; see [[#Configuration|Configuration]])
-==== Download ====
+==== Choose Your Install Method ====
-Two builds are available — pick the one that matches your OpenEMR major version. Both builds ship the ''src/Compat/'' shim layer that lets a single module codebase run cleanly across the supported OpenEMR versions.
+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.3**
+**Current Version: 2.2.0**
-~~NOTOC~~
+=== Method 1: Composer (Recommended) ===
-=== For OpenEMR 8.x ===
+If you have CLI access to your OpenEMR install:
-| **Module File** | {{ :oe-module-claimrev-connect-v2.1.3-openemr-8.zip | OpenEMR 8.x Module}} |
+<code bash>
-| **Compatible with** | OpenEMR **8.0.x patch line** (verified against the official ''openemr/openemr:8.0.0.3-2026-03-25'' Docker image) and later 8.x / master |
+cd /path/to/openemr
-| **Released** | May 13, 2026 (rebuild from ''release/v8-0'' branch) |
+composer require claimrevolution/oe-module-claimrev-connect:^2.2
-| **Notes** | Includes the ''src/Compat/'' shim layer covering ''CryptoInterface'' and ''ServiceContainer'' for cores that lack them. ''CsrfHelper'' runtime-detects ''SessionWrapperFactory::getActiveSession'' and the two ''CsrfUtils::collectCsrfToken'' signatures so the same build works on the OE 8.0.x line and on newer 8.x cores. ''GlobalConfig::getClientSecret'' prefers ''CryptoGen::decryptFromDatabase'' where available and falls back to ''decryptStandard''. |
+sudo systemctl reload php-fpm   # or restart Apache
+</code>
-=== For OpenEMR 7.x ===
+Composer downloads the latest v2.x release, drops it into ''interface/modules/custom_modules/oe-module-claimrev-connect/'', and updates the autoloader. Continue with [[#Activation|Activation]] below.
-| **Module File** | {{ :oe-module-claimrev-connect-v2.1.3-openemr-7.zip | OpenEMR 7.x Module}} |
+To **update** the module later:
-| **Compatible with** | OpenEMR 7.0.0 through 7.x |
-| **Released** | May 12, 2026 |
-| **Notes** | Same ''src/Compat/'' shim layer plus the ''OEGlobalsBag'' class_alias path needed when the host has no ''OpenEMR\Core\OEGlobalsBag'' class at all. |
-**Changelog**: See [[#Changelog|Changelog]] below.
+<code bash>
+composer update claimrevolution/oe-module-claimrev-connect
+sudo systemctl reload php-fpm
+</code>
-**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.
+=== Method 2: Manual File Drop (Shared Hosting / No CLI) ===
-==== Installation Steps ====
+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 appropriate zip for your OpenEMR version from the section above.
+  - Download the current release zip from [[https://github.com/claimrevolution/oe-module-claimrev-connect/releases|the GitHub releases page]].
-  - Log into OpenEMR as an administrator.
+  - Unzip it locally. You should see a folder named ''oe-module-claimrev-connect/'' containing ''composer.json'', ''info.txt'', ''src/'', ''public/'', ''templates/'', etc.
-  - Navigate to **Modules > Manage Modules**.
+  - Connect to your OpenEMR server with SFTP, FTP, or your hosting control panel's file manager.
-  - Click the **Install** tab, then click **Upload Module** and select the downloaded zip file.
+  - 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).
-  - After upload completes, find **ClaimRev Connect** in the module list and click **Install**.
+  - Continue with [[#Activation|Activation]] below — OpenEMR will see the new directory on the next page load.
-  - Once installed, click **Enable** to activate the module.
+**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.
+**Upgrading from 2.1.x?** After updating the files, click **Run Upgrade** on the Setup tab once. It adds the table 2.2.0 uses for ZITADEL sign-in and is safe to run more than once. Sites that keep using a client ID and secret need nothing else.
+**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 77: / Line 94: @@
 ===== Configuration =====
-After enabling the module, you need to configure your ClaimRev API credentials.
+After enabling the module, connect it to your ClaimRev account. ClaimRev is moving to a new sign-in system (ZITADEL), so there are two ways to do this. **New sites should use a ZITADEL key file (Option A).** Existing sites using a client ID and secret keep working unchanged, and can switch to a key whenever they are ready.
+First, set the environment in **Admin > Config > Connectors > ClaimRev Connect**:
+  * **ClaimRev Environment**: ''P'' for production (the default). Use ''S'' only for a ClaimRev test account, and ''D'' only if ClaimRev support asks you to.
+The API server, sign-in server and scope are set automatically from the environment. You do not need to enter them.
+==== Option A: ZITADEL key file ====
+  - Get your key file from ClaimRev. It is named like ''cr-xxxxxxxxxxxx-key.json'' and can be downloaded only once, so keep it somewhere safe. A key from the ClaimRev **test** portal only works with environment ''S''; a key from the production portal only works with ''P''.
+  - In OpenEMR, go to **ClaimRev Connect > Setup**.
+  - In the **ClaimRev Sign-In Key (ZITADEL)** card, click **Choose File** and pick the key file, or paste its contents into the box.
+  - Click **Save Key and Test Connection**. The module stores the key encrypted, signs in to ClaimRev and checks your account straight away. You should see //ZITADEL key saved and the connection to ClaimRev was verified.//
+  - Open the **Connectivity** tab to confirm: **Identity Provider** shows ZITADEL, **Token** shows Yes, and your default account is listed.
+When a key is saved, the module uses it and ignores the Client ID and Client Secret settings. To go back to Option B, click **Remove Key** on the Setup tab. To replace a key (for example after ClaimRev rotates it), load the new file the same way.
+==== Option B: Client ID and Client Secret ====
-  - Navigate to **Admin > Config > Connectors**.
+  - In **Admin > Config > Connectors > ClaimRev Connect**, enter:
-  - Scroll to the **ClaimRev Settings** section.
+    * **Client ID**: your ClaimRev API client ID
-  - Enter the following values provided by ClaimRev:
+    * **ClaimRev Client Secret**: your ClaimRev API client secret
-    * **Client ID** - Your ClaimRev API client ID
+  - Click **Save**.
-    * **Client Secret** - Your ClaimRev API client secret
+  - Open the **Connectivity** tab in the module to confirm the connection.
-    * **API Server** - The ClaimRev API endpoint URL
-    * **Client Authority** - The OAuth token endpoint
-    * **Client Scope** - The API scope (typically provided by ClaimRev)
-  - Click **Save** to store your settings.
-**Tip:** To verify your connection, navigate to the ClaimRev module and click the **Connectivity** tab for a connection status check. Contact ClaimRev support if you need your API credentials.
+**Tip:** If the connection fails, the **Connectivity** tab shows the reason in a red box. See [[#Troubleshooting|Troubleshooting]]. Contact ClaimRev support if you need your key file or API credentials.
 ---
@@ Line 668: / Line 698: @@
 ===== Compatibility =====
+==== Module Version Compatibility ====
+**Always run the current release.** A single build covers every supported OpenEMR version — the ''src/Compat/'' shim layer adapts to the host core at runtime, so there is no version-specific build to choose.
+^ Module version ^ OpenEMR 7.0.2 ^ OpenEMR 7.0.4 ^ OpenEMR 8.0.x ^ OpenEMR 8.2 ^ OpenEMR 8.3 ^ OpenEMR 8.4 ^
+| **v2.2.0** (current) | Yes | Yes | Yes | Yes | Yes | Yes |
+| v2.1.9 | Yes | Yes | Yes | Yes | Yes | Not tested |
+Requires **PHP 8.2 or later** on any core. v2.2.0 verified live against the ClaimRev API (staging and production, ZITADEL sign-in) on OpenEMR 8.4.1, 8.3.0 and 7.0.2. v2.1.8 verified on 8.3.0, 7.0.4 and 7.0.2, including 837P claim submission.
+=== Running an older module version? ===
+**v2.1.6 and earlier fail on OpenEMR 7.0.4 and on the 8.0.x patch line.** Module pages die with:
+<code>Call to undefined method OpenEMR\Core\OEGlobalsBag::getKernel()</code>
+Those cores ship an ''OEGlobalsBag'' //without// ''getKernel()''. Because the class itself is present, the module's shim does not engage, and the direct call fails. Symptoms are blank module pages, or the **Patient Portal / API** panel vanishing from the patient dashboard. v2.1.3 is worse still — it fails during login bootstrap and returns HTTP 500 for the entire site.
+Upgrading to v2.1.7 or later resolves all of it.
+=== Pinning a specific version ===
+Every release stays available on Packagist. To hold a particular version:
+<code>composer require claimrevolution/oe-module-claimrev-connect:2.1.8</code>
+There is no separate branch per OpenEMR version. A single build covers both 7.x and 8.x, and older cores are supported by pinning the last release that supported them.
 ==== Supported OpenEMR Versions ====
-The ClaimRev Connect module supports:
+The ClaimRev Connect module ships as a **single binary** covering:
-  * **OpenEMR 8.0.x patch line** — use the //OpenEMR 8.x// build above. Verified against ''openemr/openemr:8.0.0.3-2026-03-25''.
+  * **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 8.x newer / master** — same //OpenEMR 8.x// build; the shim layer's runtime detection no-ops on hosts that already expose the newer APIs.
+  * **OpenEMR 7.x** (7.0.0 and later) — verified against ''openemr/openemr:7.0.2''.
-  * **OpenEMR 7.x** — use the //OpenEMR 7.x// build above.
-Both builds ship a ''src/Compat/'' directory that adapts the module to whatever OpenEMR core is hosting it. Some shims use ''class_alias'' to provide classes the host doesn't have at all (e.g., ''CryptoInterface'', ''ServiceContainer''). Others (''CsrfHelper'', ''GlobalConfig'') detect at runtime which API is available and route accordingly — for example, ''CsrfHelper'' falls back to ''$_SESSION'' on cores whose ''SessionWrapperFactory'' lacks ''getActiveSession()''.
+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 ===
@@ Line 687: / Line 745: @@
 | ''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 ====
-To verify the module works correctly on your OpenEMR version:
-  - Navigate to **ClaimRev Connect > Connectivity**.
-  - Click the **Run Compatibility Check** button.
-  - A diagnostic page shows the status of each critical component:
-    * ''OEGlobalsBag'' — Whether the native class or shim is in use
-    * ''ServiceContainer'' — Whether the native class or shim is in use
-    * ''LoggerInterface'' / ''ClockInterface'' / ''CryptoInterface'' — Whether native or shimmed
-    * ''GlobalConfig'' and ''Bootstrap'' — Whether they instantiate successfully
-    * OpenEMR version and PHP version
-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 707: / Line 751: @@
 ==== Connection Issues ====
-  * Verify your API credentials in **Admin > Config > Connectors**
+  * Open the **Connectivity** tab. When sign-in fails it shows the reason in a red box.
+  * Verify your API credentials in **Admin > Config > Connectors**, or your key on the **Setup** tab if you use a ZITADEL key file
   * Ensure your server can reach the ClaimRev API endpoint (check firewall rules)
   * Check the OpenEMR error log for detailed error messages
   * Use the **Connectivity** tab in the module to test your connection
+==== ZITADEL Key Problems ====
+  * **"This key belongs to the ClaimRev Staging/Production environment..."**: the key came from a different ClaimRev portal than your **ClaimRev Environment** setting. Change the environment to the one named in the message (''S'' for a test-portal key, ''P'' for production), or load a key from the matching portal.
+  * **"The key file is not valid JSON" / "not a ZITADEL service-account key file"**: the wrong file or text was loaded. Use the ''cr-...-key.json'' file exactly as downloaded; a client secret will not work here.
+  * **403 "Service Account not properly setup"**: the key works, but ClaimRev has not finished setting up the client application (it needs roles assigned). Contact ClaimRev support.
 ==== Eligibility Check Returns No Results ====
@@ Line 767: / Line 817: @@
 ===== Changelog =====
+The full, detailed changelog is in [[https://github.com/claimrevolution/oe-module-claimrev-connect/blob/main/CHANGELOG.md|CHANGELOG.md on GitHub]].
+== Version 2.2.0 — October 12, 2026 ==
+  * **ZITADEL sign-in.** The module can sign in to ClaimRev with a ZITADEL key file, loaded on the Setup tab and stored encrypted. Sites using a client ID and secret keep working unchanged, and switch over by loading a key. See [[#Configuration|Configuration]].
+  * **Clearer connection errors.** The Connectivity tab shows why sign-in failed. A key from the wrong ClaimRev environment (test vs production) is detected and named.
+  * **Token caching.** ZITADEL access tokens are cached and renewed shortly before they expire, instead of being requested on every page load.
+  * **Upgrade note:** click **Run Upgrade** on the Setup tab once after updating.
+  * Verified on OpenEMR 8.4.1, 8.3.0 and 7.0.2.
+== 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 ==
@@ Line 814: / Line 879: @@
   * **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
-  * **Compatibility Check** — New diagnostic page (Connectivity > Run Compatibility Check) verifies all module dependencies resolve correctly
   * **Statement Tracking Table** — New ''mod_claimrev_patient_statements'' database table for tracking statement history per encounter