eClinicalWorks Integration Setup

This tutorial guides you through connecting Vantrexia to eClinicalWorks (eCW) via FHIR R4 and SMART Backend Services. You'll generate RSA keys, register your application in the eCW developer portal, configure JWT authentication, import patients, and verify that observations flow bidirectionally between the two systems.

Step 1: Prerequisites

Gather the following before starting:

Step 2: Generate RSA Key Pair

The eCW SMART Backend Services flow uses asymmetric cryptography. You'll sign JWT assertions with your private key, and eCW will verify them using your public key.

1. Open a terminal and navigate to your keys directory:
   Shell Copy

   mkdir -p backend/keys && cd backend/keys

2. Generate a 2048-bit RSA private key:
   Shell — Generate Private Key Copy

   openssl genrsa -out private.pem 2048

3. Extract the public key:
   Shell — Extract Public Key Copy

   openssl rsa -in private.pem -pubout -out public.pem

4. Verify both files were created:
   Shell Copy

   ls -la *.pem
   # -rw-------  1 user  staff  1675 Feb  6 10:00 private.pem
   # -rw-r--r--  1 user  staff   451 Feb  6 10:00 public.pem

Step 3: Register Application in eCW Developer Portal

1. Log in to the eCW Developer Portal.
2. Navigate to My Applications → Create New Application.
3. Fill out the registration form:

   Field	Value
   Application Name	Vantrexia RPM
   Application Type	Backend Service (SMART Backend Services)
   FHIR Version	R4
   Scopes Requested	system/Patient.read, system/Observation.write, system/Observation.read
   JWKS URL	https://your-domain.com/.well-known/jwks.json
   Description	Remote Patient Monitoring platform — reads patient demographics, writes vital sign observations

4. After submission, eCW will review your application (typically 1–3 business days for sandbox, 1–2 weeks for production).
5. Once approved, you'll receive a Client ID — save this value securely.

Step 4: Configure JWKS Endpoint

eCW needs to verify your JWT signatures. Vantrexia exposes a JWKS (JSON Web Key Set) endpoint that serves your public key in JWK format.

1. Vantrexia automatically generates the JWKS from your public key. Verify the endpoint is accessible:
   Shell Copy

   curl https://your-domain.com/.well-known/jwks.json

2. You should see a response like:
   Response — JWKS Copy

   {
     "keys": [
       {
         "kty": "RSA",
         "kid": "vantrexia-ecw-key-1",
         "use": "sig",
         "alg": "RS384",
         "n": "0vx7agoebGcQSuuPiLJXZpt...",
         "e": "AQAB"
       }
     ]
   }

3. Ensure this URL is publicly accessible — eCW's token server will fetch it to validate your JWT assertions.

Step 5: Set Backend Environment Variables

Configure the eCW integration variables in your backend .env file:

# eClinicalWorks Integration
ECW_CLIENT_ID=your-client-id-from-ecw-portal
ECW_CLIENT_SECRET=your-client-secret
ECW_ENVIRONMENT=staging
ECW_PRACTICE_CODE=your-practice-code
ECW_APP_TYPE=backend_service

After updating the .env file, restart the backend service:

docker compose restart backend

Step 6: Test JWT Authentication

Vantrexia provides a built-in test endpoint that generates a JWT assertion, exchanges it for an access token from eCW, and reports the result:

curl -X POST https://app.vantrexia.com/api/v1/ecw/test/jwt/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

A successful response:

{
  "status": "success",
  "message": "JWT authentication successful",
  "token_endpoint": "https://staging-oauthserver.eclinicalworks.com/oauth/oauth2/token",
  "access_token_preview": "eyJhbGciOiJSUzM4NCIs...truncated",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "system/Patient.read system/Observation.write system/Observation.read",
  "issued_at": "2026-02-06T12:00:00Z"
}

Step 7: Test FHIR Connection

After JWT authentication works, test the end-to-end FHIR connection:

curl -X POST https://app.vantrexia.com/api/v1/ecw/test/connection/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "fhir_base_url": "https://fhir4.eclinicalworks.com/fhir/r4/FFHEDD",
  "fhir_version": "4.0.1",
  "capabilities": [
    "Patient.read",
    "Observation.read",
    "Observation.write"
  ],
  "test_patient_count": 142,
  "connection_latency_ms": 245
}

Step 8: Import Patients from eCW

With the FHIR connection established, you can browse and import patients from eCW into Vantrexia:

1. Browse eCW patients — Fetch the patient list from eCW:
   GET /api/v1/ecw/patients/ Copy

   curl -X GET "https://app.vantrexia.com/api/v1/ecw/patients/?page=1&page_size=20" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

   This returns a paginated list of patients from eCW with their FHIR resource IDs, names, DOBs, and MRNs.
2. Select patients for import — Use the dashboard or API to import selected patients:
   POST /api/v1/patients/import_selected_from_ecw/ Copy

   curl -X POST https://app.vantrexia.com/api/v1/patients/import_selected_from_ecw/ \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "ecw_patient_ids": [
         "ecw-patient-fhir-id-001",
         "ecw-patient-fhir-id-002",
         "ecw-patient-fhir-id-003"
       ]
     }'

3. The import process:
   • Reads patient demographics from eCW FHIR (name, DOB, MRN, phone, address)
   • Creates corresponding patient records in Vantrexia
   • Links the Vantrexia patient to their eCW FHIR ID for bidirectional sync
   • Sets patient active=True

{
  "imported": 3,
  "skipped": 0,
  "errors": [],
  "patients": [
    {
      "vantrexia_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ecw_fhir_id": "ecw-patient-fhir-id-001",
      "name": "John Smith",
      "mrn": "ECW-10042"
    },
    {
      "vantrexia_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "ecw_fhir_id": "ecw-patient-fhir-id-002",
      "name": "Sarah Johnson",
      "mrn": "ECW-10087"
    },
    {
      "vantrexia_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "ecw_fhir_id": "ecw-patient-fhir-id-003",
      "name": "Robert Williams",
      "mrn": "ECW-10103"
    }
  ]
}

Step 9: Verify FHIR Data Flow

The final step is confirming that vital sign observations recorded in Vantrexia are pushed back to eCW and appear in the patient's flowsheet.

1. Ensure an imported patient has a device assigned and has taken at least one reading (or use the device simulator).
2. Vantrexia automatically creates FHIR Observation resources and pushes them to eCW when new vitals are recorded. Verify by checking the sync log:
   Shell Copy

   docker compose logs backend | grep "ecw_sync" | tail -5

   You should see entries like:
   Output Copy

   backend | [2026-02-06 12:30:00] INFO ecw_sync: Pushed Observation to eCW for patient ECW-10042 (systolic: 128, diastolic: 82)
   backend | [2026-02-06 12:30:01] INFO ecw_sync: eCW response: 201 Created, FHIR Observation ID: obs-fhir-98765

3. Log in to the eCW web interface and navigate to the patient's flowsheet. Verify the vital sign reading appears with:
   • Correct systolic/diastolic values
   • Timestamp matching the Vantrexia reading
   • Source tagged as "Vantrexia RPM"
4. In Vantrexia, check the patient's Sync Status tab to see a history of all FHIR pushes with their HTTP status codes and eCW response IDs.

Quick Reference