- Match-Connect technical specifications consist of the API documentation 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
- Match-Connect Data Dictionary
- A Donor_DIFF 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 is changing in its source.
- More generally: every time data on a match list that was provided by donor upload changes, a DIFF upload becomes necessary to update the master data.
- The term ”donor” in this document usually means ”adult donor” or ”cord blood unit” or "adult donor cryopreserved unit".
- The institution paying (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 have to be provided as null values.
- The WMDA nomenclature files (http://hla.alleles.org/wmda/index.html) must be used for all HLA fields. 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 | NEW | XXXX | NNNN |
|---|
| PAT_UPD | | DRB3/4/5 | DRB3/4/5 |
| Donor_DIFF | | DRB3/4/5 | DRB3/4/5 |
| TYP_RES | Y | DRB3/4/5 | DRB3/4/5 |
| SMP_RES | Y | DRB3/4/5 | DRB3/4/5 |
- HLA changes of a patient must not cancel requests for the patient. The requests remain under full responsibility of the patient registry.
- Duplicate requests on the same day: This issue becomes particularly difficult if SMP_REQs are concerned - sometimes users want to ”correct” their previous request (i.e. forgot to request quantity and product). The correct way of doing this is to cancel the erroneous request first and send the second one later. However, this procedure might also confuse if not carried out on the same working day. In doubt a phone call helps sorting things out.
- MSG_DEN, WARNING and REMARK content from the message response messages as well as the TXT_MSG messages have to be presented to the responsible user (search coordinator) by the local Match-Connect administrator in an appropriate manner.
- Don’t send information multiple times - WARNINGs are to be used if it happens in order to find errors.
- Multiple *_REQ messages for the same patient-donor-pair are therefore invalid and have to be rejected by the receiving registry. If a request has to be corrected, it has to be cancelled (REQ_CAN) and subsequently re-requested ( *_REQ)
- Multiple *_RES or *_ARR messages for the same request (i.e. the same message ID) are regarded as updates and therefore should be different from the previously sent one.
- Do not change IDs of patients, donors 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.
- Return the data as you’ve received it, for example, if you had to change incoming data due to national rules, return the original data with the answer.
- Announce changes in your national system, for example, sending/accepting more Match-Connect messages.
- Provide SMP_RES or NO_RES for all samples received even if the donor is reported as unavailable in the meantime. Closing a request formally by sending an appropriate result message is important (for result reminders, invoicing) because often the donor later shows up as AV again.
2.2 How to read the new semantics if you know EMDIS
As one can see from the first sentence above, the API documentation is part of the new documentation set. This API documentation is called "swagger" for shortness. It is located at this publicly available address: https://apispecs.wmda.info/
At this address one can find both Search & Match API specifications and Connect API specifications:
Since the communication is now split to communication with WMDA's Search & Match and messaging with other registries, each API request in the Semantics may be represented in two styles:
- Communication with S&M
- Most of the Patient API endpoints and all Search API endpoints consist of such messages.
- Messaging with other registries
- One Patient API and all Connect APIs are represented in this style.
Wherever suitable, we included EMDIS names of the messages in parentheses:
In many cases, current implementation of EMDIS messages will require a conversion of the flat EMDIS message structure into the nested (multi-level) structure of the API messages. All the fields in API have better names: e.g., REQ_DATE becomes requestDate.
EMDIS rules from the EMDIS Semantics are modified accordingly to the new reality and are added to each message, where applicable.