Integration Dashboard — Workflow Guide

This guide walks through the full lifecycle of an integration from a user's perspective: configuring the trigger, watching logs appear on the dashboard, reading outcomes, and retrying failures. For the underlying backend execution sequences, see the Backend Workflow Guide.

Step 1: Adding an Integration Trigger via manageIntegrations

The starting point for all integrations is the Manage Integrations tool inside the CrelioHealth Support Dashboard CRM. This is where the trigger configuration (which lab, which action, which endpoint) is created or updated.

URL: https://livehealth.solutions/supportdashboard/manageIntegrations/

How to configure an integration

1. Search for the Lab

Open the manageIntegrations page. Use the Search by Lab Name, Id dropdown (powered by AsynchronousSelect) to find the lab you want to configure. Once selected, the tool auto-loads all existing DeveloperAuthentication entries for that lab.

2. Select a Developer

From the Select Developer Name dropdown, pick the developer/integration partner whose authentication key (authKey) the integration will use. Selecting a developer loads all existing labIntegration rows associated with that developer context.

3. Select or Create an Integration ID

From Select Integration Id, pick an existing labIntegration row to edit — or leave blank to create a new one.

4. Fill in the Configuration Panels

Two accordion panels appear:

Developer Authentication panel — captures the core integration identity:

Developer Authentication Flags panel — boolean toggles for advanced behaviours:

5. Save

Click Add/Update Integration. The button calls addUpdateIntegration(...) which writes:

• A developerAuthentication row (resolved by authKey)
• One or more labIntegration rows keyed by actionCategoryListId

On success, the response returns the generated authKey and a 200 toast.

Local Development Setup

On local environments you don’t need to use manageIntegrations. Instead:

1. Open the labIntegrations table in your database.
2. Add (or update) a row with the required actionCategoryListId_id that maps to the business event you want to test.
3. Set the url / endpoint field to your test webhook receiver (e.g., a webhook.cool or similar tool).
4. If the integration type is Mirth, also populate integrationExtraDetails with the host and port JSON:

{
  "host": "127.0.0.1",
  "port": 6661
}

5. Ensure isDisable=0 and isIntegrationEnable=1 on the related developerAuthentication row.
6. The next business event matching that actionCategoryListId will automatically trigger the integration.

Step 2: How a Log Gets Created

After an integration is configured and a business event fires, the log lifecycle proceeds automatically:

Key observations:

• The log is pre-created as QUEUED before the HTTP call is made. This ensures the record is never lost even if the worker times out.
• The log_id (DocumentDB _id) travels through the entire chain — from get_integration_payload() → Fusion task payload → handler → decorator → DocumentDB update.
• Logging is always a passive side-effect. It cannot break the business event that triggered it.

Step 3: Reading Integration Logs on the Dashboard

Once events are firing, operators and support staff can observe the outcomes on the Integration Dashboard.

API tab — shows inbound third-party API calls captured by IntegrationDirectoryLogger:

Webhook tab — shows outbound webhook dispatch events, one row per trigger per integration:

Errors tab — filtered view showing only FAIL/QUEUED records across both API and Webhook types:

Log status values

Key fields to inspect

Step 4: Retrying a Failed Integration

Failed integrations can be retried manually from the dashboard or automatically by the scheduler.

Manual retry flow

1. Locate the failed log — find the IntegrationDirectory document with status=FAIL and note the log_id (_id).
2. Trigger the retry — click the Retry action in the dashboard UI. This calls RetryIntegrationView with the log_id, retry_id, and lab_id.
3. System re-fetches live domain context — the system reads retry_context (serialized at first execution) and calls the appropriate _prepare_kwargs_* function to re-fetch live objects from the database, ensuring the retry uses fresh data, not a stale snapshot.
4. Integration re-dispatched — the original trigger function is called with the freshly rebuilt arguments. The outcome is written to an IntegrationRetryLog record.
5. Dashboard updated in real time — a Pusher event (UpdateRetryIntegrationStatus) fires immediately, updating the retry count and status on the dashboard without a page refresh.

Auto-retry

The auto-retry scheduler runs periodically and checks for logs that:

• Are in FAIL or QUEUED status
• Were created within the past 24 hours (or within a configured date range)
• Have an auto_retry_count below the allowed maximum
• Match one of the auto-retry error patterns (e.g., "No response", socket timeout errors, or Mirth QUEUED logs older than 10 minutes)

Step 5: Troubleshooting a Specific Log

Use the following decision flow when a log is in an unexpected state:

Common failure patterns

Configuration Reference

The fields set in manageIntegrations map directly to the database models:

developerAuthentication
├── authKey            → token used by inbound API calls
├── labId              → scopes the auth to a lab
├── orgId              → (if isOrg=1) scopes to an org
├── developerId        → the integration partner
└── isIntegrationEnable

labIntegration (one row per action trigger)
├── actionCategoryListId  → the business event trigger (Action ID)
├── url                   → third-party endpoint
├── requestType           → 0 = GET query-string, 1 = POST JSON body
├── integrationExtraDetails → JSON: Mirth host/port, vendor, x-api-key, etc.
├── authId                → FK to developerAuthentication
└── isDisable             → soft-disable without deleting

Workflow Example: Bill Generation Webhook Trigger

The following is the simplest end-to-end test you can run to verify that integration logging is working correctly.

Pre-requisite: A labIntegration row exists with actionCategoryListId_id set to the Bill Generation action ID, and isDisable=0.

1. Create a bill

Generate a bill for any patient on the lab. This fires the domain event that calls commomFunctionForIntegrationBillCategory, which builds the payload and enqueues a Fusion task.

2. Run the Fusion scheduler

Fusion processes queued tasks asynchronously. On local, tasks won't execute until the scheduler is running. Start it with:

python run_scheduler.py

On UAT/production, the Fusion scheduler runs continuously — no manual step needed.

3. Check the Integration Dashboard

Navigate to the Integration Dashboard for the lab. Switch to the Webhook tab and filter by the Bill Generation action category. You should see a new row with:

• Operation: Bill Generation
• Status: SUCCESS or FAIL (depending on whether the endpoint responded correctly)
• Date & Time: the timestamp of the bill creation event