⚠Due to planned maintenance you will experience short (<30 min) downtime between 08:00 - 08:30 CET.
Table of Contents | ||
---|---|---|
|
2.1 Rules
- The Match-Connect technical specifications consist of an OpenAPI specification and the documents listed below. When developing a Match-Connect implementation, all content of the following documents is relevant and needs to be considered:
- The Semantics of Match-Connect Messages
- The Match-Connect Data Dictionary
- A Donor block is embedded in every result message, i.e., TYP_RES, IDM_RES, SMP_RES, RSV_RES, or NO_RES message, as the donor record changes in its source.
- More generally: every time data on a match list provided by donor upload changes, a DIFF upload becomes necessary to update the master data.
- The term" donor" in this document usually refers to "adult donor", "cord blood unit", or "adult donor cryopreserved unit."
- The paying institution (INST_PAY) has to be of the institution type (INST_TYPE) FIN.
- Empty/blank/missing fields in the payload mean deletion.
- Consequently, empty/blank integer or float values must be provided as null values.
- The WMDA nomenclature files (http://hla.alleles.org/wmda/index.html) must be used for all HLA fields. The central hub and/or the receiving registry may reject messages with invalid values. The details are described in the WMDA Guidelines for use of HLA Nomenclature (https://www.nature.com/articles/bmt201393; follow the link" Supplementary information").
- The Match-Connect semantics for the WMDA-approved additional codes are defined as follows:
Message\Value | NEW | XXXX | NNNN |
---|---|---|---|
Patient block (see 6 - Administration v1.0) | Y | DRB3/4/5 | DRB3/4/5 |
Donor block (see 6 - Administration v1.0) | Y | DRB3/4/5 | DRB3/4/5 |
Typing response | Y | DRB3/4/5 | DRB3/4/5 |
Sample response | Y | DRB3/4/5 | DRB3/4/5 |
...
- HLA data changes of a patient must not cancel requests for the patient. The requests remain under the full responsibility of the patient registry.
- A donor can have only one open request at a time.
- Multiple requests of the same type for the same patient-donor pair are invalid and must be rejected by the receiving registry.
- Duplicate requests on the same day: This issue becomes complicated if Sample Requests are concerned - sometimes users want to" correct" their previous request (i.e., forgot to request quantity and product).
- The correct way to do this is to cancel the erroneous first request and send the second one later.
- However, this procedure might also confuse if not carried out on the same working day. If in doubt, a phone call helps to sort things out.
- Multiple responses for the same request (i.e., the same message type) are regarded as updates and should therefore differ from the previously sent one.
- Denial, Warning, and Remark content from the message response as well as the Text message content have to be presented to the responsible user (search coordinator) by the local Match-Connect administrator in an appropriate manner, unless already presented by the registry software.
- Don't send information multiple times (via Match-Connect and fax/email) - if it happens Message Responses of type "Warning" are to be used to find errors.
- To establish worldwide uniqueness of the IDs, do not create new IDs for patients or addresses: use the primary keys of your database tables prefixed by your unique registry code (in EMDIS known as hub code) as Match-Connect IDs.
- Donor IDs (GRID and CB_ID) are defined elsewhere and must already be worldwide unique
- Return original data in responses even if you had to change incoming data due to national rules.
- Announce changes in your national system, for example, sending/accepting more Match-Connect messages.
- Provide Sample Response or Request Rejection for all samples received, even if the donor is reported as unavailable in the meantime. Closing a request formally by sending an appropriate response message is essential (for result reminders and invoicing) because the donor often becomes available again.
2.2 How to read the new semantics if you know EMDIS
As previously indicated in Section 2.1, the OpenAPI specification forms an integral component of our updated documentation set. Henceforth, we will refer to this API documentation as "Swagger." You can access it via the following publicly available URL: https://apispecs.wmda.info/
...
A table showing recommended sets of API endpoints to be implemented is provided in appendix A. The set of APIs depends on your use of services.
2.3 API authentication
Include Page | ||||
---|---|---|---|---|
|
2.4 General technical design
2.4.1 Message Ordering/Sequencing
The general reasons behind message ordering are:
...
- avoid peer-to-peer problem
- least effort needed on registry side
- receiver can re-request "missing" message
- can be automated, no help needed by WMDA staff
2.4.2 Message collection - general flow
Messages can be collected via individual API calls against the different "retrieve" API endpoints, which can be described as a "pull model".
The pull model is described in the following steps:
...
Users should be aware that the functionality to restore messages is limited to 72 hours. After this window, the soft-deleted messages are permanently removed from the system. Also see: Chapter 2.4.7 Message storage retention policies.
2.4.3 "shouldPeek" function
The "shouldPeek" function, which is specified as a parameter for every "Retrieve" endpoint, allows users to preview messages without marking them as retrieved or soft-deleted. It serves as a testing utility to inspect messages without altering their status within the system.
...
It is crucial to emphasize that the "shouldPeek" function should only be used for testing purposes to ensure proper functioning of the intended message-flow.
2.4.4 RESTful best practices
In the development of Match Connect, we have adhered to RESTful best practices to ensure optimal performance and maintainability.
...
- Using 'POST' instead of 'GET' for message retrieval
A 'POST' API call for retrieval of messages aligns with HTTP semantics, especially considering the nature of Match Connect. In line with HTTP semantics and RESTful best practices, 'GET' requests should per definition be cacheable. In Match Connect message retrieval triggers a mutation, because messages are no longer available after retrieval. Therefore, the information in Match Connect is non-cacheable.
The 'POST' method better reflects the intention of performing a server-side operation and helps avoid unintended caching of mutable operations, enhancing the overall robustness and correctness of Match Connect.
Additional information about RESTful best practices can be found here.
Additional information about HTTP semantics can be found here.
2.4.5 Generic message flow for Connect messages
For all user generated connect messages from a patient registry to a donor registry or vice versa the generic message flow consists of the message sent (e.g. a Sample Request) and a corresponding Message Response (6.2). The detailed message flow for such a message including the generic response message is shown below. The generic response message will be omitted in request message flows in chapter 5, for better readability.
For further details on the message response itself see chapter 6.2.
The message flow below also shows the direct answer to an API call (for simplicity only 200 and 400 are shown).
...
PlantUML Macro | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
participant "Patient Registry" as PR control "Match-Connect" as MC control "Search & Match\nService" as SM participant "Donor Registry" as DR skinparam SequenceMessageAlign center skinparam dpi 92 == Sending a user generated message == PR -[#dodgerblue]> DR : Send 'Message A' group details note left DR: routine asychronous check for pending messages DR -[#green]> MC : Call /availableMessages to check for not-picked up messages activate MC #FFBBBB MC -> DR : 200 OK - Array of messages not yet delivered (**emtpy**) MC -> DR : 400 Bad Request deactivate MC PR -[#green]> MC : Call respective Request-API to send 'Message A' activate MC #FFBBBB MC -> PR : 200 OK MC -> PR : 400 Bad Request deactivate MC DR -[#green]> MC : Call /availableMessages to check for not-picked up messages activate MC #FFBBBB MC -> DR : 200 OK - Array of messages not yet delivered (**'Message A'**) MC -> DR : 400 Bad Request deactivate MC DR -[#green]> MC : Call respective Response-API to picked up 'Message A' activate MC #FFBBBB MC -> DR : 200 OK MC -> DR : 400 Bad Request deactivate MC end == Providing the generic response == DR -[#dodgerblue]> PR : Message response (ack, reject, warning to 'Message A') \nshould always include messageId of referring message group details PR -[#green]> MC : Call /availableMessages to check for not-picked up messages activate MC #FFBBBB MC -> PR : 200 OK - Array of messages not yet delivered (**emtpy**) MC -> PR : 400 Bad Request deactivate MC DR -[#green]> MC : Call /messageResponse API to send the generic response to 'Message A' activate MC #FFBBBB MC -> DR : 200 OK MC -> DR : 400 Bad Request deactivate MC PR -[#green]> MC : Call /availableMessages to check for not-picked up messages activate MC #FFBBBB MC -> PR : 200 OK - Array of messages not yet delivered (**generic response to 'Message A'**) MC -> PR : 400 Bad Request deactivate MC PR -[#green]> MC : Call /messageResponseRetrieve API to pick up the generic response to 'Message A' activate MC #FFBBBB MC -> PR : 200 OK MC -> PR : 400 Bad Request deactivate MC end |
2.4.6 Automatically generated and manually curated Swagger
The use of both an automatically generated and manually curated Swagger serves a dual purpose.
...
Together, these two approaches provide important information about technical accuracy and communication about the development of Match Connect.
2.4.7 Message storage retention policies
Messages sent using the Connect API have the following retention policies applied:
...