HIS integration
Offline HIS → Latrexa Cloud

HIS Integration

Run the Latrexa Sync Agent on your clinic server to sync appointments between your local Hospital Information System and Latrexa — with real-time SignalR updates and automatic retry.

How it works

The Latrexa Sync Agent is a Windows background service installed at your clinic. It loads a small HIS plugin DLL (one per vendor) that talks to your local database or API. The agent handles all communication with Latrexa Cloud — you only implement five methods in your plugin.

Latrexa → HIS

Online bookings download and are created in your HIS when slots are free.

HIS → Latrexa

Walk-in and desk appointments in HIS upload to Latrexa on a schedule.

Real-time

SignalR pushes new bookings instantly; polling is used as fallback.

Step 1 — Get your API key

Each clinic needs an integration API key and organization code. Create these in your Latrexa clinic admin panel.

  1. Sign in to Clinic Admin for your organization.
  2. Open Settings → Integration tab.
  3. Click Create API Key and give it a name (e.g. Reception Server).
  4. Copy the API key immediately — it is shown only once.
  5. Copy your Organization code (your Latrexa subdomain / clinic identifier).
Store the API key securely in appsettings.json on the clinic server. Never commit it to source control or share it publicly.

Step 2 — Install the Sync Agent

Download the self-contained Windows x64 package (includes .NET runtime — no separate install needed).

  1. Download Latrexa.SyncAgent-win-x64.zip.
  2. Extract to e.g. C:\LatrexaSyncAgent.
  3. Edit appsettings.json (see configuration below).
  4. Register and start the Windows Service (see below).

Configuration — appsettings.json

{ "Latrexa": { "BaseUrl": "http://orthoaghil.com", "ApiKey": "YOUR_API_KEY_FROM_CLINIC_ADMIN", "OrganizationCode": "your-clinic-subdomain", "SignalRHubUrl": "http://orthoaghil.com/hubs/integration" }, "Sync": { "PollingIntervalSeconds": 60, "RetryIntervalSeconds": 120, "HisPluginAssembly": "Plugins/Latrexa.SyncAgent.SampleHisPlugin.dll", "HisPluginType": "Latrexa.SyncAgent.SampleHisPlugin.SampleHisConnector", "SqliteDatabasePath": "Data/sync-agent.db" }, "HisPlugin": { "ConnectionString": "Data Source=Data/sample-his.db", "AppointmentTable": "Appointments" } }
SettingDescription
Latrexa:ApiKeyBearer token from Clinic Admin → Integration
Latrexa:OrganizationCodeYour clinic subdomain / organization identifier
Sync:HisPluginAssemblyRelative path to your vendor HIS plugin DLL
Sync:HisPluginTypeFully qualified connector class name
HisPlugin:*Custom settings passed to your plugin's InitializeAsync

Step 3 — Register as Windows Service

Open Command Prompt as Administrator on the clinic server:

REM Install
sc create "Latrexa Sync Agent" binPath= "C:\LatrexaSyncAgent\Latrexa.SyncAgent.exe"
sc description "Latrexa Sync Agent" "Syncs offline HIS appointments with Latrexa Cloud"
sc start "Latrexa Sync Agent"
REM Uninstall
sc stop "Latrexa Sync Agent"
sc delete "Latrexa Sync Agent"

Logs are written to logs\service-log-YYYYMMDD.txt under the install folder. SQLite state (mappings, retry queue) is stored in Data\sync-agent.db.

Build a custom HIS plugin

Each HIS vendor ships one DLL. The main Sync Agent executable never changes.

  1. Download Latrexa.SyncAgent.Abstractions.dll (SDK contract).
  2. Download the sample plugin project as a starting point.
  3. Create a .NET 8 class library and reference the Abstractions DLL.
  4. Implement IHisAppointmentConnector:
InitializeAsync — connect to HIS DB/API using config
GetModifiedAppointmentsAsync — return HIS changes since last sync
CreateOrUpdateAppointmentAsync — write Latrexa booking into HIS
CancelAppointmentAsync — cancel in HIS
IsSlotAvailableAsync — check doctor slot before accepting online booking

Build your DLL, copy it (and Latrexa.SyncAgent.Abstractions.dll if not merged) into the agent's Plugins\ folder, update HisPluginAssembly and HisPluginType in appsettings.json, then restart the service.

Latrexa integration API

All requests from the agent include:

Authorization: Bearer {ApiKey}
X-Organization-Code: {OrganizationCode}
MethodPathPurpose
GET/api/integration/appointments/pendingDownload bookings awaiting HIS sync
POST/api/integration/appointments/uploadUpload HIS appointments to Latrexa
POST/api/integration/appointments/confirmConfirm successful HIS write
POST/api/integration/appointments/rejectReject when slot unavailable
POST/api/integration/heartbeatAgent health check (visible in Clinic Admin)

SignalR hub: http://orthoaghil.com/hubs/integration — events: AppointmentCreated, AppointmentUpdated, AppointmentCancelled.

Troubleshooting

  • 401 Unauthorized — check API key and organization code in appsettings.json.
  • Plugin load error — verify DLL path and fully qualified type name; ensure Abstractions DLL is in Plugins\.
  • No heartbeat in admin — confirm service is running and outbound HTTPS to Latrexa is allowed on the firewall.
  • Duplicate appointments — agent uses SQLite mapping table; do not delete Data\sync-agent.db without support guidance.
Downloads
Sync Agent (win-x64) Abstractions SDK (.dll) Sample Plugin (source + DLL)
Package contents
  • Sync Agent ZIP — self-contained exe, appsettings.json, sample plugin, INSTALL.txt
  • Abstractions DLL — reference in your plugin project
  • Sample ZIP — SampleHisConnector.cs + project file + built DLLs
Quick links
Integration support