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

Transform

Transform

Endpoint

POST /fhir/stu3-r4/$transform

This is the main cross-version operation exposed by the service.

It accepts a STU3 source resource or bundle and returns a translated R4 result.

Use this operation when the input is already a supported STU3 source resource profile. Do not use it for completed forms. QuestionnaireResponses use the separate QuestionnaireResponse extraction operation because one form can produce multiple target resources.

Request Resource

The request body is a FHIR Parameters resource.

For a single source resource, sourceProfile and targetProfile should be provided explicitly. For bundle requests, each entry carries its own source profile in meta.profile, and each entry can override the target family as needed.

Routing Parameters

Name Type Meaning
source Resource The STU3 source resource or STU3 bundle to translate
sourceProfile canonical The supported STU3 source profile route for a single-resource request. Bundle entries can carry source profiles in entry.resource.meta.profile
targetProfile canonical The supported R4 target profile route for a single-resource request or Bundle fallback. Bundle entries can override this per entry
validationMode code Target validation behavior: enforce, report, or none. Defaults to enforce

Optional Parameters

Name Type Meaning
returnLogical boolean Include the intermediate logical model as a Binary resource

validationMode=enforce validates the produced R4 output and fails the transform with an OperationOutcome when validation contains error or fatal issues. validationMode=report validates and returns the translated output plus diagnostics even when validation contains errors. validationMode=none skips transform-time validation; clients can still validate later with POST /fhir/r4/$validate.

$transform does not accept a validate parameter. Use validationMode here, or use the separate R4 $validate endpoint.

Response Resource

On success, the response body is also a FHIR Parameters resource.

Main Response Parameters

Name Type Meaning
result Resource The translated R4 resource or translated R4 bundle
targetProfile canonical The target profile route that was applied for a single-resource request
logical Binary The intermediate logical model, only when returnLogical=true
outcome OperationOutcome Validation output, present for enforce and report modes

Example Patient Request

This example uses a richer patient fixture so the translated response shows the current patient mapping more clearly, including identifiers, demographics, contact data, and communication data.

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source",
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "profile": [
            "http://nictiz.nl/fhir/StructureDefinition/BgZ-Patient"
          ]
        },
        "identifier": [
          {
            "system": "http://fhir.nl/fhir/NamingSystem/bsn",
            "value": "999900134"
          },
          {
            "system": "http://example.org/mrn",
            "value": "MRN-12345"
          }
        ],
        "active": true,
        "name": [
          {
            "use": "official",
            "text": "Jan Jansen",
            "family": "Jansen",
            "given": [
              "Jan"
            ]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "+31-20-5551234"
          }
        ],
        "gender": "male",
        "birthDate": "1975-04-12",
        "address": [
          {
            "line": [
              "Laan van Europa 10"
            ],
            "city": "Amsterdam",
            "country": "NL"
          }
        ]
      }
    },
    {
      "name": "sourceProfile",
      "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/BgZ-Patient"
    },
    {
      "name": "targetProfile",
      "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
    },
    {
      "name": "validationMode",
      "valueCode": "enforce"
    },
    {
      "name": "returnLogical",
      "valueBoolean": true
    }
  ]
}

Example Patient Response Shape

The full example resource is attached as ig/input/examples/patient-transform-response.json.

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "profile": [
            "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
          ]
        },
        "active": true,
        "identifier": [
          {
            "system": "http://fhir.nl/fhir/NamingSystem/bsn",
            "value": "999900134"
          },
          {
            "system": "http://example.org/mrn",
            "value": "MRN-12345"
          }
        ],
        "name": [
          {
            "use": "usual",
            "text": "Jan Jansen",
            "family": "Jansen",
            "given": [
              "Jan"
            ],
            "_given": [
              {
                "extension": [
                  {
                    "url": "http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier",
                    "valueCode": "CL"
                  }
                ]
              }
            ]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "+31-20-5551234"
          }
        ],
        "gender": "male",
        "birthDate": "1975-04-12",
        "address": [
          {
            "line": [
              "Laan van Europa 10"
            ],
            "city": "Amsterdam",
            "country": "NL"
          }
        ]
      }
    },
    {
      "name": "targetProfile",
      "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
    },
    {
      "name": "logical",
      "resource": {
        "resourceType": "Binary",
        "contentType": "application/fhir+json"
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome"
      }
    }
  ]
}

Bundle Input

The transform endpoint also accepts a STU3 Bundle as the source parameter.

When a bundle route is valid, the result parameter contains an R4 Bundle.

For EPS Patient Summary output, set the top-level targetProfile to:

  • http://hl7.eu/fhir/eps/StructureDefinition/bundle-eu-eps

The service translates supported entries through their source-to-logical and logical-to-EPS StructureMaps, then assembles the document Bundle, Composition section references, reachable support resources, and stable fullUrls. PZP Practitioner and PractitionerRole EPS routes remain available as single-resource transforms, but are not standalone document Bundle entries in the current Composition section set.

For bundle requests, each source entry keeps its source profile in meta.profile. If the bundle mixes target families, each Bundle.entry.request can carry a target override using this extension:

  • http://cumuluz/fhir/StructureDefinition/translation-target-profile

The extension value should be the target profile canonical URL in valueUri. If an entry does not specify an override, the top-level targetProfile parameter is used as the fallback default. For PZP bundle entries, the registered PZP 2020 target profile can also be inferred from the entry source profile when no entry-specific or top-level target profile is supplied. Because the extension sits on Bundle.entry.request, examples use a batch Bundle with ordinary FHIR request.method and request.url values so the Bundle remains valid FHIR JSON.

Example bundle request:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source",
      "resource": {
        "resourceType": "Bundle",
        "type": "batch",
        "entry": [
          {
            "fullUrl": "urn:uuid:11111111-1111-4111-8111-111111111111",
            "resource": {
              "resourceType": "Patient",
              "id": "patient-1",
              "meta": {
                "profile": [
                  "http://nictiz.nl/fhir/StructureDefinition/BgZ-Patient"
                ]
              }
            },
            "request": {
              "method": "POST",
              "url": "Patient",
              "extension": [
                {
                  "url": "http://cumuluz/fhir/StructureDefinition/translation-target-profile",
                  "valueUri": "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
                }
              ]
            }
          },
          {
            "fullUrl": "urn:uuid:22222222-2222-4222-8222-222222222222",
            "resource": {
              "resourceType": "Procedure",
              "id": "procedure-1",
              "meta": {
                "profile": [
                  "http://nictiz.nl/fhir/StructureDefinition/BgZ-Procedure"
                ]
              }
            },
            "request": {
              "method": "POST",
              "url": "Procedure",
              "extension": [
                {
                  "url": "http://cumuluz/fhir/StructureDefinition/translation-target-profile",
                  "valueUri": "http://hl7.eu/fhir/base/StructureDefinition/procedure-eu-core"
                }
              ]
            }
          }
        ]
      }
    },
    {
      "name": "validationMode",
      "valueCode": "enforce"
    }
  ]
}

The same shape is also available as ig/input/examples/bundle-transform-request.json.

Failure Behavior

If the request is malformed, the source cannot be parsed, or the profile pair is not supported, the service returns a FHIR OperationOutcome with HTTP 400.

Typical failure causes are:

  • missing source
  • unsupported sourceProfile
  • unsupported targetProfile
  • a source payload that is not valid STU3 content for the expected route

Example Files

  • ig/input/examples/patient-transform-request.json
  • ig/input/examples/patient-transform-response.json
  • ig/input/examples/bundle-transform-request.json

Target Profile Context

The transform request must name the exact R4 target family the client wants.

  • nl-core 2020 routes produce nl-core-shaped Dutch output
  • eu-base routes produce European output
  • EPS routes produce European Patient Summary profile output, and bundle-eu-eps produces an EPS document Bundle for supported source entries
  • PZP 2020 ACP routes produce the matching registered PZP target profile for supported PZP 2017 ACP source profiles

PZP ACP sources also have explicit generic parent targets where the shared logical model validates against the installed parent profile. ACP-Patient targets nl-core-Patient, patient-eu-core, and patient-eu-eps; other PZP sources target their registered nl-core parent or, where no nl-core parent exists, the base R4 parent.

Unsupported route pairs fail with OperationOutcome instead of falling back to a different target. In particular, generic BgZ resources are not accepted as PZP ACP targets, and PZP ACP-Procedure is not exposed as an EU Base or EPS Procedure source route.

QuestionnaireResponses are intentionally outside this profile-pair matrix. They are handled by POST /fhir/$extract-questionnaire-response.

For the general profile story, see Target Profiles.

Discovery Endpoints For Transform

Use these endpoints to discover the operation without reading repository code:

  • GET /fhir/stu3-r4/metadata
  • GET /fhir/stu3-r4/OperationDefinition/bgz-transform
  • GET /fhir/stu3-r4/translation-index
  • GET /fhir/OperationDefinition/extract-questionnaire-response for the form-extraction contract

The translation index is especially useful for clients that want a machine-readable list of supported source and target combinations.