Differences

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

--- openemr_manual [2026/08/25 21:49] – 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 684: / Line 701: @@
 ==== 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.
+**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.4 ^ OpenEMR 8.0.x ^ OpenEMR 8.2 / 8.3 ^ Notes ^
+^ Module version ^ OpenEMR 7.0.2 ^ OpenEMR 7.0.4 ^ OpenEMR 8.0.x ^ OpenEMR 8.2 ^ OpenEMR 8.3 ^ OpenEMR 8.4 ^
-| **v2.1.7** (current) | Yes | Yes | Yes | Recommended for every supported core. Verified on 7.0.4, 8.0.0.3, 8.2.0 and 8.3.0. |
+| **v2.2.0** (current) | Yes | Yes | Yes | Yes | Yes | Yes |
-| v2.1.6 and earlier | **No** | **No** | Yes | Module pages fail with //Call to undefined method OEGlobalsBag::getKernel()//. Confirmed on 7.0.4 and on the 8.0.x line. |
+| v2.1.9 | Yes | Yes | Yes | Yes | Yes | Not tested |
-| v2.1.3 only | **No — do not install** | **No — do not install** | Yes | In addition to the above, causes an HTTP 500 during login bootstrap, taking the whole site down. |
-Earlier OpenEMR 7.0.x releases (7.0.2 and below) may work on older module versions, because those cores ship no ''OEGlobalsBag'' at all and the module's shim engages. This has not been re-verified — if you are on 7.0.x, v2.1.7 is the safe choice.
-All versions require **PHP 8.2 or later**.
+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.
-=== Why older module versions fail ===
+=== Running an older module version? ===
-OpenEMR 7.0.4 and the 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.6 and earlier fail on OpenEMR 7.0.4 and on the 8.0.x patch line.** Module pages die with:
-  * **v2.1.3** called it during login bootstrap — the entire site returned HTTP 500.
+<code>Call to undefined method OpenEMR\Core\OEGlobalsBag::getKernel()</code>
-  * **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 7.0.4 or 8.0.x on v2.1.6 or earlier and see blank module pages or a missing Patient Portal / API panel, upgrading to v2.1.7 resolves it.
+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 ===
@@ Line 709: / Line 724: @@
 Every release stays available on Packagist. To hold a particular version:
-<code>composer require claimrevolution/oe-module-claimrev-connect:2.1.7</code>
+<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.
@@ Line 736: / 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 796: / 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) ==