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

Home

Official URL: https://translate-ig.cumuluz.dev/ig/ImplementationGuide/org.cumuluz.translate.ig Version: 0.1.0
Draft as of 2026-09-23 Computable Name: CumuluzTranslateIG

Cumuluz Translate

CumuluZ Translate converts FHIR resources only through registered source-profile and target-profile pairs. This implementation guide has two purposes: it defines the technical translation contract and shows system integrators exactly how to discover, call, and interpret the service.

The service is a prototype. An executable route and a technically conformant result are not clinical certification or clinical acceptance.

Integrate the service

Follow these pages in order:

  1. Getting Started — execute one complete discovery and transform flow.
  2. Discovery — find operations and exact supported profile pairs at runtime.
  3. Transform — integrate single-resource translation in all four FHIR-version directions.
  4. Bundle Translation — translate related STU3 resources together.
  5. EPS Document Output — assemble the specific EPS document target.
  6. QuestionnaireResponse Extraction — extract supported PZP forms.
  7. Validate — validate an R4 resource independently.

Every operation page includes a concrete call, the response shape, failure behavior, and the fields a client must inspect.

Review the technical specification

Subject Page
Exact route contract, assurance and conformance Translation Contract
Logical models, StructureMaps and ConceptMaps Mapping Model
Choosing an output family Target Profiles
Complete human-readable route inventory Translation Matrix
Local draft XIB definitions XIB Reference
Generated FHIR definitions and examples Artifacts

Public operations

Operation Endpoint
STU3 to R4 transform POST /fhir/stu3-r4/$transform
STU3 to STU3 transform POST /fhir/stu3/$transform
R4 to STU3 transform POST /fhir/r4-stu3/$transform
R4 to R4 transform POST /fhir/r4/$transform
QuestionnaireResponse extraction POST /fhir/$extract-questionnaire-response
R4 validation POST /fhir/r4/$validate

The shared translation shape is:

registered source profile -> local logical model -> registered target profile

The endpoint selects the FHIR-version direction. The normalized sourceProfile + targetProfile pair selects one exact route. A shared resource type, an installed package, or a compatible logical model does not create a route.

Input and output at a glance

Public operations exchange one UTF-8 FHIR JSON resource per HTTP request or response. Use Content-Type: application/fhir+json and Accept: application/fhir+json. Sources and results are nested FHIR resources inside Parameters; they are not passed as strings, files, multipart parts or Binary data.

Situation Complete HTTP body
transform request version-appropriate Parameters containing parameter[source].resource
transform success target-version Parameters containing parameter[result].resource and evidence
transform failure target-version OperationOutcome
standalone validation success or validation failure R4 OperationOutcome; inspect issue severities
unprocessable validation request R4 OperationOutcome with HTTP 400

The Transform direction table names the exact FHIR version of every envelope and nested resource. Bundle Translation and EPS Document Output document the mixed-version STU3-to-R4 envelope explicitly.

Client responsibilities

A client must:

  1. discover the exact route before sending data;
  2. send application/fhir+json with the FHIR version required by the endpoint;
  3. preserve Bundle identities and references;
  4. inspect the returned FHIR resource and diagnostic evidence, not only the HTTP status;
  5. treat report and none results as non-conformant;
  6. apply its own clinical acceptance and workflow policy after technical translation.

R4-target transforms return R4 Parameters with result, targetProfile, translationReport, and usually outcome. STU3-target transforms return STU3 Parameters; their OperationOutcome carries equivalent route and stage evidence.

Scope boundary

The service is not a FHIR repository, a generic resource-type converter, a free-form mapping engine, or a generic QuestionnaireResponse processor. Unsupported profiles and pairs return a version-correct FHIR OperationOutcome. Transport, authentication, authorization, filtering, persistence, pseudonymisation and the internal C-CDA adapter are outside this public operation surface.