Support for FHIR validation (and use of FHIR-related utilities) in GITB TDL test cases

[costas80]

This issue is about providing the possibility to trigger validation of FHIR resources and use other FHIR-related utilities from GITB TDL test cases.

Effective FHIR validation means starting and pre-populating a FHIR validator which can be time-consuming. As having this overhead per test session is impractical, a better approach is to do this once and reuse the same instance across all tests. As such, rather than use a built-in FHIR validator component the best approach is to have this set up as a separate service that is accessible via the standard GITB validation (for the validator) and processing (for utilities) APIs. The service would likely be deployed alongside the ITB core components (e.g. in the same Dockerised service or Kubernetes cluster), but this could also be full remote.

Note that currently the extension services are managed via SOAP service APIs and XML messages. To simplify implementation in the FHIR validator, a prerequisite for this will be to provide an official REST/HTTP/JSON equivalent.

Once the APIs are supported in the validator, the official TDL documentation will also be extended to define precisely what is supported, and how to use the validator in test cases.

[costas80]

Mentioning here @costateixeira, with whom the implementation approach was discussed, and to follow up on the side of the validator.

Adding also, @olw-medcom, @mlarcelet-cmd and @chouaiech, with whom we've been discussing FHIR support recently (via various channels), to be in the loop.

[costas80]

The support for REST API test services is now available to use on the latest nightly build. The REST API definitions for the different service types are defined in the gitb-types repo's development branch (click for validation, messaging and processing services):

In addition, this specification defines the callback operations exposed from the test engine. These would be used typically by messaging services (i.e., not applicable in the case of the FHIR validator) and also to post log messages on the test session log (I would imagine also not needed here).

Note that using the raw content of these references, you can already inspect them in a Swagger UI. Go for example to https://petstore.swagger.io/ and use the raw validation service API docs in the input field.

For the case of the FHIR validator we are discussing the APIs that apply are the validation service (for the validator) and the processing service (to support the additional utilities).

Extending the HL7 FHIR validator

For this purpose I would suggest referring to the validation and processing service OpenAPI specs and simply creating the API from scratch. The gitb-types repo defines a gitb-types-model module that includes POJO classes for all API types (much better than the existing SOAP classes, defining for example a nice fluent API for easy use). However, I would suggest not using these to extend a third party validator as this would mean adding a dependency to it to purely facilitate development. If this is needed in advance of the next release we can always publish a pre-release version on Maven Central but still I would advise against it.

Using REST-API test services in test cases

To have the ITB make REST calls to an extension service (as opposed to SOAP), you have two approaches:

• Define the test service through the UI specifying that it implements the REST API.
• Explicitly state in test cases that a handler is RESTful.

For the first approach, connect as Test Bed or Community admin, go to the domain's management screen and select the Test services tab. Here define a test service and specify that it's API type is REST. For the address provide the API root path without the specific operations. For example if your /validate operation listens at http://my-address:8181/app/api/validation/validate you should provide http://my-address:8181/app/api/validation.

Note that you can also define the API if creating/managing test services via the ITB's REST API.

The second way of specifying use of REST for test services is directly in test cases. Basically, wherever you have a test step that supports a handler you can define a handlerApiType attribute as follows:

<process hidden="false" desc="Processing step" handler="$DOMAIN{processingService}" handlerApiType="REST"/>

This handlerApiType takes values REST and SOAP and is optional. If not specified, and a matching test service is defined (in the example with identifier processingService), the API type from the service's definition is used. If however the handlerApiType is specified it will take precedence. If neither a test service is defined, not the handlerApiType is used, the API type is considered to be SOAP (we need to do this to maintain backwards compatibility).

Next steps

From this point the next steps would be to:

1. Pull the latest nightly build to have an ITB to test with.
2. Adapt the HL7 FHIR validator fork to define the new validation and processing APIs.
3. Integrate and test with the ITB to make sure that RESTful service calls are working fine.
4. Make the pull request to merge the new API to the core HL7 FHIR validator repo.

Finally, when the 1.30.0 release is published, the documentation will of course be updated in full, and the new gitb-types modules will be published to Maven Central. In addition, the test service template (i.e., the Maven Archetype) will be extended to allow you to create all the scaffolding for a working Spring Boot app using the REST APIs.