Begin with the clinical purpose and boundary
An integration is a clinical workflow change expressed through software. Write down the decision or task it should support, who initiates it, who must act on the result, and what happens if data is late or unavailable. This prevents a technically successful transfer from becoming an unsafe or unused workflow.
- Trigger: identify the event that creates an assessment assignment and the system that owns it.
- Identity: define how a person, episode, practitioner, and organisation are matched without relying on names alone.
- Completion: define which response state counts as complete and whether amendments are permitted.
- Review: name the role accountable for seeing the result, deciding what it means, and documenting action.
- Destination: specify whether the receiving record needs item responses, a score, a human-readable report, or a combination.
Turn the workflow into an information contract
For each step, list the minimum fields, identifiers, status values, timestamps, provenance, and allowed changes. FHIR separates a form definition in Questionnaire from a captured set of answers in QuestionnaireResponse, while Observation can represent measurements or simple assertions. Those distinctions help expose decisions that a generic field mapping can hide. [1][2][3]
- Record semantic meaning, cardinality, terminology, units, version, and whether a field may be absent.
- Assign one source of truth for every mutable field and state which system may correct it.
- Preserve stable business identifiers so retries and reconciliation do not create duplicate clinical records.
- Document whether raw item responses may cross the boundary or whether only derived results are necessary.
From clinical purpose to a testable integration
A five-step planning flow that narrows a clinical need into an integration decision and an operational readiness test.
- Purpose
Name the clinical task, trigger, owner, and safe fallback.
- Workflow
Map identity, consent, assignment, completion, review, and documentation.
- Contract
Define semantics, identifiers, provenance, status, and source-of-truth ownership.
- Pattern
Select only the API, FHIR, SMART, webhook, or batch patterns the contract requires.
- Proof
Run capability, failure, reconciliation, security, and rollback tests.
Choose an exchange pattern after the contract is clear
Different patterns solve different problems. A SMART launch can provide authorised EHR context to an application. A FHIR REST exchange can read or write structured resources. A webhook can notify a consumer that an event occurred, while a scheduled export may suit lower-urgency reconciliation. A clinic may need more than one pattern, but each should have a named purpose. [5][4]
Design reconciliation and failure ownership
Assume timeouts, duplicates, out-of-order events, expired authorisation, unmatched patients, and partial downstream outages. Decide which failures can retry automatically, which enter a review queue, and which must halt processing. Keep enough correlation data to trace one assessment across systems without placing sensitive content in ordinary logs. [4]
- Use idempotency or stable identifiers where an operation may be repeated.
- Separate delivery acknowledgement from successful clinical processing.
- Provide a dead-letter or exception queue with an owner and response target.
- Reconcile source and destination counts, statuses, and identifiers on a schedule.
- Define a safe manual fallback before go-live and rehearse it during the pilot.
Create the decision pack before vendor selection
The useful output is a short, testable pack: a sequence diagram, data dictionary, responsibility matrix, security and privacy assumptions, failure catalogue, acceptance tests, and rollback plan. Vendors can then respond to concrete requirements instead of broad questions about whether they have an API.
- Confirm the use case with clinicians, operations, information governance, and integration owners.
- Test identity matching and review ownership with synthetic edge cases.
- Record unsupported capabilities as explicit constraints or future work.
- Use the same pack to assess implementation progress and operational readiness.
Sources and further reading
- FHIR R4 Questionnaire (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official R4 resource definition for a structured set of questions and answer constraints.
- FHIR R4 QuestionnaireResponse (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official R4 resource definition for complete or partial questionnaire answers.
- FHIR R4 Observation (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official R4 definition for measurements and simple assertions.
- FHIR R4 RESTful API (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official interaction, conditional operation, transaction, and response semantics.
- SMART App Launch 2.2: Launch and Authorization (opens in a new tab)HL7 International. Updated 2024-04-30. Accessed 2026-07-13. Official SMART authorization and launch-context workflow.
- FHIR R4 CapabilityStatement (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official declaration model for supported server and client behavior.