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.

Request Resource

The request body is a FHIR Parameters resource.

Required Parameters

Name Type Meaning
source Resource The STU3 source resource or STU3 bundle to translate
sourceProfile canonical The supported STU3 source profile route
targetProfile canonical The supported R4 target profile route

Optional Parameters

Name Type Meaning
validate boolean Validate the translated R4 result before returning
returnLogical boolean Include the intermediate logical model as a Binary resource

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
logical Binary The intermediate logical model, only when returnLogical=true
outcome OperationOutcome Validation output, only when validation is requested

Example Patient Request

This example uses a richer patient fixture so the translated response shows the current patient mapping more fully, including identifiers, demographics, extensions, 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": "validate",
      "valueBoolean": true
    },
    {
      "name": "returnLogical",
      "valueBoolean": true
    }
  ]
}

Example Patient Response Shape

The full rendered 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.

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

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

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

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