Delivery step 03
Establish stable integration contracts
Partner formats stay at the edge of the platform. Inside it, each case event has one versioned schema, and every adapter maps to that schema.
What happens
- Define the canonical case events, such as document received, appointment confirmed, and report delivered.
- Map each partner format to the canonical event through an adapter.
- Version each schema, and test every adapter against the same conformance checks.
How the platform carries it out
- Partner formats (HL7 v2, X12, CSV, webhooks) are converted in the adapter. The case record never holds a partner format.
- A schema change creates a new version. Adapters on the earlier version keep working until they are moved.
- Conformance tests replay recorded messages through each adapter and compare the output with the expected event.
AI role
Drafts the mapping for a new partner format. The draft is checked against the schema and the conformance tests before it is accepted.
Approval
An integration analyst approves each mapping and each schema version.
Systems involved
- Integration engines
- Azure Service Bus topics
- Schema versions
- FHIR R4 profiles
Reference components
- FHIR and HL7 v2 mapping
- channel and acknowledgment patterns
- event envelope and document record contracts
Pre-sizing
Business case, effort, time, and cost for this step.
These are planning estimates for scoping. They are based on the work listed here and must be checked with the client before a commitment is made.
Business justification
Without stable contracts every new partner format changes the case record. Versioned case events keep partner changes at the edge and let each partner be added or changed without a rebuild of the workflow.
Business value
- A new partner or format is added as one adapter and one test set.
- Partner changes do not reach the case record, scheduling, or billing.
- Each interface can be tested and replayed before it goes live.
Documentation to produce
- Canonical case event catalog
- Schema versions and change log
- Adapter specification per partner
- Conformance test set
Work breakdown and effort
| Work item | Person-days |
|---|---|
| Define the canonical case events and their fields | 5 |
| Write schemas and the versioning rules | 6 |
| Build the first adapter (HL7 v2 results to the case event) | 8 |
| Build the conformance test harness with recorded messages | 6 |
| Set up the Azure Service Bus topics and subscriptions | 3 |
| Total effort | 28 |
Delivery time
4 weeks for the full step.
Resources required
- Integration engineer: 2 FTE
- Solution architect: 0.5 FTE
- QA engineer: 0.5 FTE
POC: 2 weeks
Scope
- One HL7 v2 result feed converted to one case event, with recorded messages replayed
Exit criteria
- Replay of the recorded messages produces the expected event for every case in the set
MVP: 3 weeks
Scope
- Canonical events for the first four case stages
- Adapters for one EHR feed, one laboratory feed, and the portal intake
Exit criteria
- All adapters pass conformance
- A schema change is shown to create a new version without breaking the older adapter
Assumptions
- A test environment with the partner sandbox is available
- Recorded messages can be shared under the consent rules
Risks
- Partner sandboxes are not available when needed
- Message variants are larger than the recorded set covers
Cost calculation
Enter your own day rate and weekly platform cost. Until they are entered, the calculator shows effort and delivery time only.
- Effort
- 28 person-days
- Delivery time
- 4 weeks
- Labor cost
- 0
- Platform cost
- 0
- Total estimate
- 0