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. Single-resource transforms include the resolved targetProfile; EPS document Bundle transforms return bundle-eu-eps as the resolved target profile.

QuestionnaireResponses use a separate operation. You still send a FHIR Parameters resource, but the input parameter is questionnaireResponse and the output result is a Bundle of extracted R4 resources. The currently registered extraction definition supports PZP ACP forms.

Local Runtime

Run the JVM app:

./gradlew run

Or 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-alpha.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
4. GET /fhir/OperationDefinition/extract-questionnaire-response when you need form extraction

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
• which input and output parameters the QuestionnaireResponse extraction operation uses

Example JSON Resources

The IG source includes concrete request and response JSON examples that match the live service. The patient example is intentionally richer 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'

Minimal QuestionnaireResponse Extraction Request

Use this operation when the input is a completed supported form, not a single source resource profile.

{
  "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
    }
  ]
}

Submit it:

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

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

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.