Matchbox Server

Matchbox is a FHIR server that can be deployed as a microservice in your IT infrastructure. It includes all features from Matchbox-engine, plus additional features that are API-specific.

Configuration

The following configuration parameters are available for the Matchbox server. They can be set in the Spring configuration (e.g. application.properties/application.yml), or as system properties.

Parameter	Default value	Description
`matchbox.fhir.context.fhirVersion`	`4.0.1`	The FHIR version of the server.
`matchbox.fhir.context.txServer`	`n/a`	The URL of the terminology server to use, or `n/a` not to use a terminology server.
`matchbox.fhir.context.igsPreloaded`	`[]`	The list of IGs to always pre-load when initializing a Matchbox engine.
`matchbox.fhir.context.onlyOneEngine`	`false`	Forces the server to initialize only one engine. See the section Only one engine below.
`matchbox.fhir.context.suppressWarnInfo`	`{}`	The list of warnings/infos to suppress in validation reports. See Suppress warning/information-level issues in validation.
`matchbox.fhir.context.suppressError`	`{}`	The list of errors to suppress in validation reports. See Suppress error-level issues in validation.
`matchbox.fhir.context.httpReadOnly`	`false`	Whether the server is in read-only mode or not. See the section Read-only mode below.
`matchbox.fhir.context.extensions`	`any`	The list of domains allowed in extensions while validating resources; `any` will allow all extensions.
`matchbox.validation.save-statistics`	`false`	Whether the Operation Outcome containing the validation results should be stored or not.
`matchbox.fhir.context.llm.provider`		The LLM provider used for the AI analysis of validation.
`matchbox.fhir.context.llm.modelName`		The LLM model used for the AI analysis of validation.
`matchbox.fhir.context.llm.apiKey`		Your API key for the desired LLM provider.
`matchbox.fhir.context.ssrfProtectionEnabled`	`true`	Whether the SSRF protection is enabled or not.
`matchbox.fhir.validation.analyzeErrorsWithLlm`	`false`	Whether the validation outcome should be analyzed by a LLM, when it includes `error` or `fatal` issues, or not. Requires the LLM parameters to be correctly set
`matchbox.fhir.mcp.requestAnalysisFromClient`	`false`	Whether to request an analysis of the validation outcome by the MCP client or not.
`spring.ai.mcp.server.enabled`		Whether matchbox should be provided as MCP-Server or not.

In addition for validation the different java validator parameters can also be configured for default values: e.g: matchbox.fhir.context.displayIssuesAreWarnings is set default to true, but you can overwrite that by providing another value. To see the current supported list of parameters, you can check the OperationDefinition of $validate on matchbox test instance.

See an example of configuration, to show the expected format:

matchbox:
  fhir:
    context:
      displayIssuesAreWarnings: false
      igsPreloaded: ch.fhir.ig.ch-elm#1.4.0
      suppressWarnInfo:
        hl7.fhir.r4.core#4.0.1:
          - "Constraint failed: dom-6:"
          - "regex:Entry '(.+)' isn't reachable by traversing forwards from the Composition"
        ch.fhir.ig.ch-elm:
          - "regex:Binding for path (.+) has no source, so can't be checked"
          - "regex:None of the codings provided are in the value set 'Observation Interpretation Codes'(.*)"
      llm:
        provider: anthropic
        modelName: claude-3-5-sonnet-20241022
        apiKey: sk-xxx
    validation:
      analyzeErrorsWithLlm: true

The HAPI configuration parameters are also available. The following example shows the use of the most commonly used parameters:

hapi:
  fhir:
    implementationguides:
      fhir_r4_core:
        name: hl7.fhir.r4.core
        version: 4.0.1
        url: classpath:/hl7.fhir.r4.core.tgz
      ch-core:
        name: ch.fhir.ig.ch-core
        version: 4.0.1
      ch-elm:
        name: ch.fhir.ig.ch-elm
        version: 1.7.0
        url: https://build.fhir.org/ig/ahdis/ch-elm/package.tgz

Some more configuration parameters used by validation are described in the Validation page.

Maximum request size

Matchbox runs on Undertow, which rejects request bodies larger than 2 MiB by default with RequestTooBigException: UT000020: Connection terminated as request was larger than 2097152. Matchbox raises that limit to 100 MB; if you have to send larger resources, increase server.undertow.max-http-post-size (e.g. with the environment variable SERVER_UNDERTOW_MAX_HTTP_POST_SIZE). The value must be positive, Undertow cannot be configured for unlimited request bodies through Spring Boot. Note that a reverse proxy in front of Matchbox may enforce its own, smaller limit.

Read-only mode

When enabling httpReadOnly, the server will reject any operation that would modify its state. In particular:

The following FHIR operations are disabled: CREATE, DELETE, UPDATE, PATCH, UPDATE_REWRITE_HISTORY, TRANSACTION, BATCH, ADD_TAGS, DELETE_TAGS, META_ADD, META_DELETE.
The feature Installing an NPM package through the operation $install-npm-package is disabled.
The feature Auto-installation of FHIR packages in the $validate operation is disabled.

It is helpful to enable this mode when the server is used in a production environment (e.g. as a validation server), to make sure its state can't be changed through the API.

Only one engine

When enabling onlyOneEngine, the server will initialize a single Matchbox engine, use it for all requests, and keep it running for the whole serve life duration. It provides the following advantages:

It lowers the memory and CPU consumption, as a single engine is shared among all requests.
It speeds up the response time, as the engine is already initialized and ready to use.
You can overwrite conformance resources (e.g. update StructureMaps, ConceptMaps)

It is helpful to enable this mode when the server is used in a development environment (e.g. as a validation server or for FML map development).

Disabling this mode is recommended when more context separation is required, in particular when dealing with the following situations:

when installing ImplementationGuides that use different FHIR versions, the server will need to initialize multiple engines, to only load the FHIR Core needed for each IG;
when installing multiple versions of the same ImplementationGuide, the server will also initialize separate engines, with only the dependencies required.

Installing an NPM package through the operation $install-npm-package

The operation $install-npm-package allows you to install an NPM package through the API. It is available if and only if httpReadOnly is disabled.

Parameter IN	Card	Description
name	1..1	The name of the package.
version	1..1	The version of the package.
body	1..1	The content of the NPM package as HTTP body

POST /matchboxv3/fhir/$install-npm-package?name=ch.fhir.ig.ch-core&version=4.0.1 HTTP/1.1
Content-Type: application/gzip

<gzip content of the NPM package>

Auto-installation of FHIR packages in the $validate operation

The operation $validate will try to install the FHIR package if it is not already installed, if and only if httpReadOnly is disabled.

The FHIR package to install will be determined by (in the implemented order):

The ig parameter, if present;
The profile parameter. Matchbox will search for IGs that contain that canonical with the Simplifier API and install the first result.

LLM support

Adding llm configurations will allow the server to make API calls to the specified LLM and add an analysis of the validation results to the operation outcome. This provides the user with AI generated instructions on how to fix errors in the validated FHIR resource.

This feature requires a provider, model and API key to be defined in the application configuration.

Supported LLMs:

Provider	Recommended Model	Supported Models
OpenAI (`openai`)	`gpt-4o-mini`	`gpt-3.5-turbo`, `gpt-4`, `gpt-4o`, `gpt-4o-mini`
Anthropic (`anthropic`)	`claude-3-5-sonnet-20241022`	`claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`, `claude-3-sonnet-20240229`, `claude-3-opus-20240229`