Differences

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

--- openemr_manual [2026/08/25 21:16] – Add module version / OpenEMR compatibility matrix 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]])
 ==== Choose Your Install Method ====
@@ Line 41: / Line 43: @@
 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.X**
+**Current Version: 2.2.0**
 === Method 1: Composer (Recommended) ===
@@ Line 49: / Line 51: @@
 <code bash>
 cd /path/to/openemr
-composer require claimrevolution/oe-module-claimrev-connect:^2.1
+composer require claimrevolution/oe-module-claimrev-connect:^2.2
 sudo systemctl reload php-fpm   # or restart Apache
 </code>
-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.
+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.
 To **update** the module later:
@@ Line 83: / Line 85: @@
   - 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 90: / 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 681: / 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 ====
@@ Line 699: / 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 719: / 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 779: / 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) ==
@@ Line 832: / 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
@@ Line 850: / Line 896: @@
   * Portal notifications
   * Native OpenEMR eligibility sync
----
-===== Module Version Compatibility =====
-Use this table to pick the right module version for your OpenEMR install. **If you are on any OpenEMR 8.x release, use v2.1.7 or later** — earlier versions have known faults on the 8.0.x patch line.
-^ Module version ^ OpenEMR 7.x ^ OpenEMR 8.0.x ^ OpenEMR 8.2 / 8.3 ^ Notes ^
-| **v2.1.7** (current) | Yes | Yes | Yes | Recommended for every supported core. Verified on 8.0.0.3, 8.2.0 and 8.3.0. |
-| v2.1.6 | Yes | **No** | Yes | Verified on 7.0.4. On 8.0.x the module's own pages still fatal — see below. |
-| v2.1.5 | Yes | **No** | Yes | Same 8.0.x limitation as v2.1.6. |
-| v2.1.4 | Yes | Partial | Yes | Fixes the site-wide login failure from v2.1.3, but module pages still fatal on 8.0.x. |
-| v2.1.3 | Yes | **No — do not install** | Yes | Causes an HTTP 500 during login bootstrap on 8.0.x, taking the whole site down. Upgrade to v2.1.7. |
-All versions require **PHP 8.2 or later**.
-==== Why the 8.0.x column matters ====
-OpenEMR's 8.0.x patch releases ship an ''OEGlobalsBag'' without the ''getKernel()'' method that the flex/master line provides. Because the real class //is// present on 8.0.x, the module's compatibility shim never activates there, so any direct call to ''getKernel()'' fails with "Call to undefined method".
-  * **v2.1.3** called it during login bootstrap — the entire site returned HTTP 500.
-  * **v2.1.4** routed the service layer through ''Compat\KernelCompat::resolve()'', which fixed login, but eleven call sites in the module's own pages and templates were missed.
-  * **v2.1.7** completed that migration. One of the missed call sites rendered inside the patient dashboard, so on 8.0.x it aborted the page render and made the adjacent **Patient Portal / API** panel disappear — a symptom that did not obviously point at this module.
-If you are running OpenEMR 8.0.x on v2.1.6 or earlier and see missing dashboard panels or blank module pages, upgrading to v2.1.7 resolves 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.7</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.