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

What You Need To Know First

The service does not accept a custom JSON schema.

You send standard FHIR JSON. For translation that means a FHIR Parameters resource containing:

• the STU3 source resource or bundle
• the sourceProfile canonical
• the targetProfile canonical

The service returns a FHIR Parameters resource containing the translated R4 result and, when requested, a validation outcome and the intermediate logical model.

Local Runtime

Run the published image:

docker run --rm -p 8080:8080 dev.cumuluz.org:5000/cumuluz-public/cumuluz-translate:latest

Or run the local compose setup:

docker compose up --build

Check the server:

curl http://localhost:8080/health

Expected response:

ok

Hosted Runtime

The public deployment is currently available at:

• https://translate.cumuluz.dev

The same paths are used on the hosted deployment and the local deployment.

Quick Discovery Steps

If you are integrating against the service for the first time, start with:

1. GET /fhir/stu3-r4/metadata
2. GET /fhir/stu3-r4/OperationDefinition/bgz-transform
3. GET /fhir/stu3-r4/translation-index

These endpoints tell you:

• which operation is exposed
• which input parameters and outputs the transform operation uses
• which exact source profile and target profile combinations are currently supported

Example JSON Resources

The IG source includes concrete request and response JSON examples that match the live service. The patient example is intentionally rich so it shows the current mapped fields more clearly:

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

Minimal Transform Request

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source",
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "profile": [
            "http://nictiz.nl/fhir/StructureDefinition/BgZ-Patient"
          ]
        }
      }
    },
    {
      "name": "sourceProfile",
      "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/BgZ-Patient"
    },
    {
      "name": "targetProfile",
      "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
    }
  ]
}

Submit it:

curl -sS \
  -H 'Content-Type: application/fhir+json' \
  -d @request.json \
  'http://localhost:8080/fhir/stu3-r4/$transform'

Minimal Validate Request

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "profile": [
            "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
          ]
        }
      }
    },
    {
      "name": "profile",
      "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
    }
  ]
}

Submit it:

curl -sS \
  -H 'Content-Type: application/fhir+json' \
  -d @validate.json \
  'http://localhost:8080/fhir/r4/$validate'

Content Type

Use FHIR JSON.

In practice the runtime accepts standard JSON requests used in the tests and examples, but application/fhir+json is the clearest content type to send for interoperable clients.