Skip to main content

​
Overview

The iTransplant integration forwards serology reports from bLIS to iTransplant, a software platform widely used by organ procurement organizations (OPOs) and tissue/eye banks. Once enabled, every finalized serology report for a participating organization is delivered to iTransplant without any manual action by lab staff. A single send carries:
  • The rendered report PDF (base64-encoded)
  • Per-test result codes and result values
  • Subject (donor) and accession identifiers
  • Sample collection time and transfusion status (Pre / Post)
  • Case-type flags that tell iTransplant whether the case is organ, tissue, eye, or birth tissue
Sends happen in the background, so report generation is never blocked by the vendor’s API.
This integration only sends reports for accessions whose test type is Serology. Reports for other test types do not trigger a send.

​
How it works

​
When a send fires

bLIS attempts a send when all of the following are true:
  1. A report has just been finalized (preliminary reports are skipped)
  2. The accession’s test type is SEROLOGY
  3. The integration is globally enabled
  4. The integration is enabled for the accession’s primary organization
If any of these is false, no send is attempted and no message is recorded.

​
What gets sent

Each request includes a JSON payload with the following fields: The destination URL is built from the global base URL plus per-organization parts:
The token configured globally is sent as the ITX-AUTHORIZATION request header. Failed and stalled sends can be retried — see Retries and resends.

​
Realtime status updates

When a send completes (success or failure), bLIS publishes a realtime event on the accession’s channel. Anyone viewing the accession sees the iTransplant status badge in the side panel update without needing to refresh.

​
Configure the integration

Configuration lives under Admin → Integrations → iTransplant. The page has three tabs: Configuration, Organizations, and Messages.
Access requires the Lab Manager role or higher (admin:all permission).

​
Step 1: Enter API credentials

On the Configuration tab, fill in the global settings that apply to every send. Click Save changes to persist. Saving does not enable the integration; you still need to flip the global switch (next step).

​
Step 2: Enable the integration globally

The Enabled / Disabled switch in the page header is the global kill-switch. Until it is on, no sends will fire — even for organizations that are individually enabled.
Toggling the global switch off mid-flight short-circuits any pending worker jobs. They will not retry once the switch is back on; failed sends from while the switch was off must be retried manually from the Messages tab.

​
Step 3: Configure each organization

On the Organizations tab, every organization in bLIS appears in a grid with its current iTransplant status. Open an organization to set its values. A live URL preview shows exactly what bLIS will POST to, with {donorId} left as a placeholder until send time.

​
Case type tagging

bLIS resolves the case type for a send by inspecting every organization linked to the accession — the primary client and any shared (additional) clients — and looking up each one’s case type tag.
  • Exactly one distinct case type across the linked orgs → that case type is used.
  • No case type on any linked org → falls back to the default case type if one is configured, otherwise the send fails with a configuration error.
  • Multiple disagreeing case types → falls back to the default case type if configured, otherwise the send fails.
This means you can tag a shared “Birth Tissue” client just to mark the case type, without enabling that organization to send on its own. Save the case type, leave the Enable sends switch off, and leave the Org-specific ID blank — the organization participates in case-type resolution but never triggers its own sends.
Tag every organization that participates in iTransplant casework — including shared clients that never send themselves — to keep case-type resolution predictable. The default case type is a safety net, not a replacement for correct tagging.

​
Monitor sends

​
From the accession page

When iTransplant is enabled for the accession’s organization, the right-side detail panel shows an iTransplant row with a status badge:
  • Ready — integration is enabled, no messages yet
  • Pending — a send is in flight
  • Sent — last send succeeded
  • Failed — last send failed
Clicking the badge opens a popover with the most recent send attempts. Lab managers can click any attempt to open the full message detail in a side sheet.

​
From the admin Messages tab

The Messages tab on the iTransplant admin page lists every send attempt across the whole system. Filter by status, attempt number, HTTP response code, accession, report, or date range. Sort by most recent attempt to triage failures quickly. Click the panel icon at the start of any row to open the message detail sheet, which shows:
  • The exact request URL and payload (the report PDF is replaced with its filename and length so the row stays compact)
  • The full response body and HTTP status code
  • The retry chain — links to previous and next attempts
  • Timing — when the attempt was queued and when it completed

​
Audit log

Every iTransplant action writes to the bLIS audit log under the integration.* namespace: See Audit logs for how to search and export.

​
Troubleshooting

​
Sends are not firing

Check, in order:
  1. Global switch on — Header switch on the iTransplant admin page must be Enabled.
  2. Organization enabled — On the Organizations tab, the accession’s primary client must show Enabled.
  3. Test type — Only SEROLOGY accessions trigger sends.
  4. Report finalized — Preliminary reports are skipped. Only the final report fires a send.

​
Common configuration errors

When a send fails for configuration reasons, bLIS records a FAILED message with a human-readable error and surfaces it to Sentry. The most common messages:

​
Retries and resends

bLIS distinguishes between automatic retries (the system reattempting transient failures on its own) and manual replays (a person hitting Retry or Resend in the admin UI). Each send — whether a first try, an automatic retry, or a manual replay — is recorded as a single integration message row.

​
Automatic retries

bLIS retries transient failures (HTTP 5xx, 408, 429, and network errors) up to 3 attempts with exponential backoff (500 ms base, 5 s cap). Other 4xx responses (auth, validation, missing donor) are not retried — they will not change on retry and are surfaced to admins for action. The table below summarizes how each kind of response is treated. “Auto-retry” means bLIS reattempts in the background up to 3 attempts before giving up; “no auto-retry” means the message goes straight to FAILED and a person needs to act.
For any auto-retried response, bLIS honors a Retry-After header from iTransplant when present (parsed as either delta-seconds or an HTTP-date), clamped to a maximum of 5 seconds between attempts.

​
Retry a failed send

Lab managers can manually retry a FAILED message from the message detail sheet. bLIS enqueues a fresh send that chains to the original message, so the attempt history stays linear and traceable. Use Retry when:
  • An automatic retry chain exhausted itself (rare; usually means iTransplant was down longer than 30 seconds)
  • A configuration error has been fixed (org-specific ID added, case type tagged) and you want to re-send without generating a new report

​
Resend a successful send

In most cases where a previously-sent report needs to be updated (results changed, demographics corrected, wrong tests reported), the right tool is the standard corrected report flow on the accession. Generating a corrected report finalizes a new report and automatically triggers a fresh send to iTransplant — exactly as if it were a new accession. Resend is an escape hatch for the cases the corrected report flow does not cover, where the vendor needs an updated copy of the same report without generating a new one. For example:
  • An organization’s case-type tag was wrong at send time and you want iTransplant to receive the corrected case flags
  • The original send technically succeeded but iTransplant has confirmed they did not record it correctly
Resending a successful message requires a free-text reason, captured in the integration.resend audit entry so the trail is clear about why support hit the button. If you find yourself reaching for Resend regularly, generate a corrected report instead.

Reports

Understand what triggers a finalized report and what it contains.

Audit logs

Search and export integration.* audit events.