Backend Workflow Guide

This page maps standard integration executions as step-by-step sequences — from configuration through delivery, retry states, and Mirth handoff. For the UI-level walkthrough of how these workflows appear in the Support Dashboard, see the Workflow Guide at the feature root.

---

Workflow 1: Integration Configuration

Goal: Create or update an integration rule for a lab or organization.

1. Support dashboard queries get_developer_authentication and get_actioncategory_list to populate the configuration UI.
2. UI fetches available labIntegration instances for the resolved auth context.
3. User confirms endpoint, headers, and action mapping, then submits via add_update_webhook_integration.
4. Backend writes developerAuthentication keys and labIntegration rows keyed by actionCategoryListId.

---

Workflow 2: Outbound Event Trigger

Goal: Dispatch a payload to a third-party system when a LiveHealth business event fires.

1. A business action completes normally (e.g., bill generated, sample received).
2. The domain controller calls the corresponding trigger function (e.g., commomFunctionForIntegrationBillCategory, common_integration_sample_receive).
3. The trigger function fetches active labIntegration rows matching the actionCategoryListId.
4. For each matching integration, it calls get_integration_payload() to build the structured payload.
5. save_log_instance() pre-creates a log document in DocumentDB, returning a log_id.
6. The trigger enqueues a Fusion task via commonFunctionForIntegrationWebhookCall, injecting the log_id into the payload.
7. The Fusion worker calls the internal webhook handler, which dispatches to the third-party endpoint.
8. WebhookIntegrationDirectoryLogger updates the DocumentDB log with the final SUCCESS or FAIL status.

---

Workflow 3: Bulk Outbound Dispatch

Goal: Enqueue many integration tasks efficiently (e.g., consolidated report submissions).

1. The trigger calls commonIntegrationWebhookFunctionForBulk(...) with a list of records.
2. For each record, a payload is built and a Fusion task is constructed.
3. All tasks are submitted in a single batch via Fusion().bulk(...).
4. The /integrationWebhookBulkAPI/ endpoint processes each task asynchronously and independently.

---

Workflow 4: Inbound API Capture

Goal: Record that a third-party system called a LiveHealth API endpoint.

1. The third party makes an authenticated request to a LiveHealth API (e.g., appointmentConfirmAPI).
2. IntegrationDirectoryLogger captures the pre-call context: token, headers, body, IP, and origin.
3. The API view function executes normally — business logic runs without any modification.
4. After the function returns, the decorator assembles and persists the full request/response payload to IntegrationDirectory.

---

Workflow 5: Fusion Worker Status Callback (integration_callback_url)

Goal: Report the final SUCCESS or FAIL outcome of a Fusion-dispatched HTTP call back to the Integration Dashboard.

This is the standard status-reporting mechanism for all outbound integrations dispatched via Fusion. It is baked into fusion_worker/tasks/webhooks.py and fires automatically after every third-party HTTP call.

1. When get_integration_payload() builds the dispatch payload, it includes an integration_callback_url — pointing to the internal LiveHealth webhook handler decorated with @WebhookIntegrationDirectoryLogger.
2. The Fusion worker (webhooks.py) picks up the queued task and makes the actual HTTP call to the third-party endpoint (via GET(...), POST(...), PUT(...), or DELETE(...)).
3. After the response is received, the worker calls send_integration_payload(), which:
   • Extracts integration_payload from the task args (checking both args.integration_payload and args.payload.integration_payload).
   • Checks the response for suppression signals — if the response code is 209 or the response body contains "message": "#NOTFORDASHBOARD", the callback is skipped entirely and no status is written to the dashboard.
   • If not suppressed, enriches the payload with end_point, request_headers, request_body, response_body, response_status_code, response_time, activity_date, and derived status (SUCCESS for HTTP 2xx, FAIL otherwise).
   • POSTs the enriched payload to integration_callback_url with an internal auth header (x-internal-token).
4. The internal handler at integration_callback_url is wrapped by @WebhookIntegrationDirectoryLogger, which updates the IntegrationDirectory document with the final status.

---

Workflow 6: Retry

Goal: Re-execute a failed or stalled integration with fresh domain context.

1. A retry is triggered manually via the dashboard UI (routed through RetryIntegrationView) or automatically by the auto-retry scheduler.
2. The system reads action_category_list_id from the original IntegrationDirectory log to identify the correct trigger function.
3. retry_context (serialized at first-time execution) is used by the appropriate _prepare_kwargs_* function to re-fetch live domain objects from the database.
4. The original trigger function is called with the freshly rebuilt arguments.
5. WebhookIntegrationDirectoryLogger (with is_retry_enabled=True) captures the outcome and calls IntegrationRetryLog.update_existing_record_and_push_update().
6. The parent IntegrationDirectory document's retry_count is incremented and status updated.
7. A Pusher notification via UpdateRetryIntegrationStatus refreshes the dashboard in real time.

---

Workflow 7: Mirth / HL7 Handoff

Goal: Send an HL7 message to Mirth via TCP socket.

1. The trigger calls send_hl7_manual_sample_update() or an equivalent HL7 handler.
2. The handler reads host, port, and transport settings from labIntegration.integrationExtraDetails.
3. update_message_with_ids() injects LABID and LOGID into the HL7 message body for downstream traceability and stamps the log with stage="LIVEHEALTHAPI".
4. The handler opens a TCP socket and sends the HL7 message to Mirth.
5. WebhookIntegrationDirectoryLogger wraps the handler and records the outcome as SUCCESS, FAIL, or QUEUED.

---

Troubleshooting Checklist

When investigating an integration failure, work through these steps in order:

1. Verify config — confirm the labIntegration row is active and not soft-disabled for the lab and action ID.
2. Check the trigger — confirm the business event actually fired and the trigger function was called.
3. Read the log — find the IntegrationDirectory document. Check status, error_message, response_body, and retry_count.
4. Trace the log_id — the DocumentDB _id is the thread connecting the pre-created log, the Fusion payload, the handler, and any retry records. Start here if anything is missing.
5. Evaluate the response — was the payload valid? Was the auth token correct? Did the third-party return an error body?