Cumuluz Translate Implementation Guide
0.1.0 - ci-build

Cumuluz Translate Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Getting Started

Getting Started

This walkthrough discovers and executes one synthetic BgZ 2017 Patient to nl-core Patient route. Start the service using the repository README, then replace http://localhost:8080 with the base URL of your environment.

1. Confirm the exact route

curl -sS \
  -H 'Accept: application/fhir+json' \
  'http://localhost:8080/fhir/stu3-r4/translation-index'

Find an entry whose sourceProfile is http://nictiz.nl/fhir/StructureDefinition/BgZ-Patient and whose targetProfile is http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient. Do not infer support from the presence of another Patient route.

See Discovery for the response structure and all direction-specific endpoints.

2. Send the transform

The complete synthetic request is published as Patient transform request.

curl -sS \
  -H 'Accept: application/fhir+json' \
  -H 'Content-Type: application/fhir+json' \
  --data @ig/input/examples/patient-transform-request.json \
  'http://localhost:8080/fhir/stu3-r4/$transform'

The request makes both profile canonicals explicit and uses validationMode=report. Report mode runs all validation and governance stages but returns materialized output even when a stage reports a problem. Its result is always labelled non-conformant.

Use enforce when the integration must receive output only after all unrelaxed validation errors, fatal issues, and blocking governance decisions have passed.

3. Process the response

HTTP 200 returns a FHIR Parameters resource. The complete synthetic shape is published as Patient transform response.

Parameter Client action
result Parse it with the target FHIR version and verify meta.profile.
targetProfile Verify that it equals the requested target canonical.
outcome Inspect every issue.severity; do not treat HTTP 200 as validation success.
translationReport Record route identity, conformance mode, stages, artifact identities and loss decisions.
logical Read only when the request set returnLogical=true; it is diagnostic intermediate data.

For this fixture the selected route is:

Route property Value
Direction STU3 to R4
Source profile http://nictiz.nl/fhir/StructureDefinition/BgZ-Patient
Logical model https://fhir.cumuluz.org/StructureDefinition/logical/LogicalPatient
Target profile http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient
Source mapping layered zib2017, nlcore2017 and BgZ Patient groups
Target mapping LogicalPatientToNlcorePatient

The layered source groups reuse mapping rules; they are not profile inheritance. The fixture is documentation-only data and the route remains subject to the governance state returned by the running service.

4. Handle failures

Request errors, unknown or ambiguous profile pairs, invalid source resources, and blocked enforce stages return a version-correct OperationOutcome, normally with HTTP 400.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-supported",
      "diagnostics": "Unsupported translation route from '<source>' to '<target>'"
    }
  ]
}

Treat diagnostics as human-readable context. Drive client behavior from the HTTP status, resource type, issue severity, requested profiles, and returned route/conformance evidence.

Continue by use case