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

Transform

Transform

Use $transform to translate one registered source resource to one registered target profile. A source Bundle uses the same STU3-to-R4 endpoint but follows Bundle Translation. The EPS Bundle target adds the EPS Document Output contract. A completed form uses QuestionnaireResponse Extraction.

Choose the endpoint

The endpoint fixes both FHIR versions. sourceProfile + targetProfile must identify one route in that endpoint's translation index.

Wire format

All transform endpoints accept one UTF-8 JSON resource in the HTTP request body and return one UTF-8 JSON resource. Use:

Content-Type: application/fhir+json
Accept: application/fhir+json

FHIR XML, multipart input, form fields and a JSON-encoded string are not operation input formats. Place the source resource directly in Parameters.parameter.resource:

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "source", "resource": { "resourceType": "Patient" } },
    { "name": "sourceProfile", "valueCanonical": "<source canonical>" },
    { "name": "targetProfile", "valueCanonical": "<target canonical>" },
    { "name": "validationMode", "valueCode": "enforce" }
  ]
}

The example above uses the R4-style parameter datatypes used by STU3-to-R4, R4-to-STU3 and R4-to-R4 requests. A STU3-to-STU3 request is a STU3 Parameters resource and uses valueUri for sourceProfile and targetProfile.

For STU3-to-R4, the server reads the outer parameter structure using R4-style fields but parses only the nested source object as STU3. This is why the request uses valueCanonical while the source resource itself follows STU3.

On success, parameter[result].resource contains the target resource directly. Only parameter[logical].resource, when requested, is a FHIR Binary whose data follows normal base64 Binary encoding.

Request parameters

Bundle sources cannot be combined with returnLogical. | documentContext | 0..1 | R4 Composition used only for EPS document assembly on STU3-to-R4. |

canonical|version is accepted only when the installed top-level StructureDefinition has that version. Unsupported and ambiguous pairs fail; the service never falls back to another route with the same resource type. The obsolete validate transform parameter is rejected; use validationMode.

Complete synthetic request: 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'

Execution and validation modes

source validation -> source-to-logical map -> logical validation
-> governance/loss policy -> logical-to-target map -> target validation

Terminology translation occurs only when the selected StructureMap invokes a ConceptMap.

Success response

All success envelopes are FHIR Parameters resources in the target FHIR version.

See the complete Patient transform response. A client should accept a result only after checking the expected target profile, conformance mode, blocking issue severities and applicable loss decision.

The report's mapped, changed, added, and deleted groups compare source and target payload values. They are not semantic-loss classifications.

Failure response

Malformed Parameters, unknown parameters, invalid source JSON, missing profiles, unsupported or ambiguous pairs, and blocked enforce stages return HTTP 400 with a version-correct OperationOutcome.

Profile-specific mapping preconditions also fail explicitly. For PZP 2017 TreatmentDirective to PZP 1.0 or nl-core-TreatmentDirective2, supply the verified source version with its latest positive verification, linked parties, and health-professional author. Negative verification history is ignored; missing or ambiguous positive evidence fails. Known coded contact parties become role-only contained RelatedPersons without invented identity. Native R4 directives are not required to repeat legacy verification evidence. The transform never substitutes BeginDatum for the review date.

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

Do not retry the same request against another direction or target automatically. Refresh Discovery, correct the profile pair or route the failure to an operator.

Integration checklist

• Send and accept application/fhir+json.
• Use the parser for the endpoint's target FHIR version.
• Set timeouts and payload limits suitable for profile validation.
• Log profile canonicals and returned route identity without logging clinical payloads.
• Preserve the complete FHIR response for auditable stage and loss evidence.
• Do not persist or forward a report or none result as technically conformant.