This repository provides a demonstration of a VSDM 2.0 server.
The server is embedded in a test suite that demonstrates its operations. After running the tests, you can find a detailed description of the specific queries in the target/site/serenity/downloadable folder (you can view the test suite results in target/site/serenity/index.html).
See ReleaseNotes for all information regarding the (newest) releases.
The tiger.yaml file describes the test environment’s structure, as well as the configuration of the VSDM server itself. If you want to dive deeper into the project, it’s worth taking a look there. For a better understanding of Tiger and its capabilities, you can refer to the User Manual: [Tiger User Manual](https://gematik.github.io/app-Tiger/Tiger-User-Manual.html).
In brief, a test suite is executed. Tiger first starts a test environment. The necessary servers for this are listed in tiger.yaml under servers, and in this case, it’s the vsdmServer. Its type is defined as zion.
Zion stands for "Zero-Line mock server." Zion can do more than a regular mock server (it allows a certain degree of interactivity), but it’s far less capable than a real POC (there are limits to interactivity, and migration to a "real" implementation is not possible). It’s designed for quick, codeless sketching of interfaces and interactions.
A Zion server, as described in this example, is defined by a list of responses. When a new request is received, all stored responses are checked to find one for which all requestCriterions are true. Then, the assignments are carried out (these can be used to store values from the request, persist them, or reference them in the response). Finally, the stored response is returned. There’s also the possibility to send requests to backend services and refine the response based on the replies, but that’s not used in this example.
For more details about Zion and the possibilities it offers, you can refer to the User Manual: [Tiger Zion](https://gematik.github.io/app-Tiger/Tiger-User-Manual.html#_tiger_zion).
A journey through the message flow begins in the test suite itself. After starting the test environment, the test from login.feature is executed. The steps that begin with TGR in that file come directly from the Tiger Test framework. Here’s an overview of the actions:
-
First, we set the value of
insurant.telematikIdto the given value. This value will be used to query the user generated invsdmUsers.yaml. This is the Telematik-ID (equivalent to the KVNR) of the insurant (Versicherter). The value here is not a valid KVNR but merely a placeholder. -
We set a new default header for subsequent HTTP requests. Here, a Bearer Token is set, which is read from the
poppTokenTemplate.jsonfile. -
Then, we send a
GETrequest to the configured URL (in this case, it’s the URL of the Zion server, and the port used is specified intiger.yamlfor the Zion server). -
Finally, we check if the expected values are present in the response.
In the poppTokenTemplate.json file, the Bearer Token used for the request is described. It roughly follows the format of a Popp Token (https://fachportal.gematik.de/fileadmin/Fachportal/Downloadcenter/Vorabveroeffentlichungen/Edge/gemF_PoPP_V0.7.0_CC.pdf). Three points are of interest in this file:
-
First, the value
body.tidshould be mentioned. Here, it references the value set forinsurant.telematikIdin the feature file and inserts it into the token. -
The token is a JSON, but the
tgrEncodeAsfield ensures a format transformation. At the moment of serialization (which happens whenTGR set the default headeris executed), the JSON is converted into a JWT. The three parts,body,header, andsignature, are taken and processed accordingly. -
Under
signature.verifiedUsing, the value of the key used to verify the token is mentioned. The key is loaded from thesrc/test/resources/poppServer.p12file when the test suite starts. As this file provides a key pair, the test suite can sign the token during serialization with the matching private key.
After both request criteria are checked and approved, the server performs the assignment. The variable insurantId is set to the referenced value. The string $.header.authorization..body.tid represents an RbelPath, a Tiger-specific construct that allows you to navigate in structures similarly to JsonPath or XPath. Here, we extract the Bearer Token from an HTTP header, look into the contained JWT, and read the nested JSON. As a result, the tid claim is extracted. (After this assignment, insurant.telematikId is equal to insurantId).
After the assignment, the response is prepared. It’s loaded from the vsdmAnswer.xml file, which essentially matches the response to the client. However, this file contains some placeholders that need to be resolved beforehand.
For example, under Bundle.entry.resource.Patient.name.family, you’ll find the expression ${vsdm.insurant.${insurantId}.familyName}. We’ve just assigned insurantId. But where does the value for vsdm.insurant… come from? In the tiger.yaml file, there’s a block called additionalYamls. It reads the vsdmUsers.yaml file and mounts it at the specific location vsdm. This is how we get to the final key vsdm.insurant.my-super-telematik-id.familyName. The value must be Meier, which is then written into the XML accordingly.
If you set the value activateWorkflowUi to true in the second line of the tiger.yaml file, a web page will open when you run the test suite again. It will display extensive information about the test environment and the executed test steps.
If you want to contribute, please check our CONTRIBUTING.md.