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

Run The Service

Local JVM:

./gradlew run

Docker image:

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

Local compose:

docker compose up --build

Health check:

curl http://localhost:8080/health

Expected response:

ok

The public prototype deployment uses the same paths at:

• https://translate-alpha.cumuluz.dev

Pick The Right Operation

The service uses FHIR JSON. application/fhir+json is the preferred content type. Resource translations always use a registered sourceProfile -> logical model -> targetProfile route. Choose the endpoint by source and target FHIR version, then use the translation indexes to confirm the exact profile pair.

First Transform

Submit the included BgZ Patient request:

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

The response is a FHIR Parameters resource with:

Minimal Transform Envelope

This shows the envelope only. Real payloads must carry enough data to satisfy the requested source and target profiles.

{
  "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"
    },
    {
      "name": "validationMode",
      "valueCode": "none"
    }
  ]
}

First QuestionnaireResponse Extraction

Use extraction when the input is a completed form and one form can produce multiple target resources.

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

Minimal request shape:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "questionnaireResponse",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "questionnaire": "https://api.iknl.nl/docs/pzp/r4/Questionnaire/ACP-zib2020",
        "status": "completed"
      }
    },
    {
      "name": "validate",
      "valueBoolean": true
    }
  ]
}

The response is a FHIR Parameters resource with an R4 Bundle result and an OperationOutcome.

First Validation

Use standalone validation when you already have an R4 resource.

curl -sS \
  -H 'Content-Type: application/fhir+json' \
  --data @ig/input/examples/patient-validate-request.json \
  'http://localhost:8080/fhir/r4/$validate'

Validation returns an OperationOutcome. HTTP 200 means the validation operation ran; clients still need to inspect error and fatal issues.

Discovery Checklist

Example Files