...
2.0 Guaranteeing Message Order
To guarantee the message order a specific mechanism must be in place. There are several possibilities to realise this.
The added benefit are of multiple ways:
- controlling the correct order is important to stay in sync between sender and reciever
- some message only make sens eif processed in the correct order
- easier error handling and issue tracing
Option A):
intrinsic ordering only:
Sender Responsibility: The sender is responsible for ensuring the desired order of calls to the Connect APIs. If api calls are to be scheduled / batched, it is suggested that the sender maintain a queue of outgoing calls / messages so that message sequence is persistent in the event of system failure.
Receiver Responsibility: The receiver is responsible for monitoring the availableMessages queue and process retrieval calls to the Connect APIs in the order specified.
Pro:
- no additional information or overhead neede
Con:
- only implicite ordering
- no explicit control on missing messages on reciever side
Option B):
ordering via local sequence number:
Sender Responsibility: The sender has to add a reciever specific sequence to each and every message.
Receiver Responsibility: The sequence number would be part of each message itself . The reciever has to check that the sequence number is correct (no number missing) and only process the messages if that is ok. Otherwise go back to the central system and claim the missing message.
Pro:
- most detailed information as the number is part of the whole communication proess
Con:
- a lot of overhead in the commnication
- extra work at each registry
- each registry has to maintain a sequence number for each new registry (peer to peer behaviour)
- exra work for each registry when a new registry is added to the system
Option C):
central sequence number provided by SMC:
option C1: on number per recieving registry
option C2: on number per sending / recieving registry combination
Sender Responsibility:
The sender is responsible for ensuring the desired order of calls to the Connect APIs. If api calls are to be scheduled / batched, it is suggested that the sender maintain a queue of outgoing calls / messages so that message sequence is persistent in the event of system failure.
Central system:
Central system provides the sequence number as part of the meta block as anwser in each connect message (messages to another Registry).
Option: not add it to the message_response (and others)?
Receiver Responsibility:
The sequence number would be part of the meta block. The reciever has to check that the sequence number is correct (no number missing) and only process the messages if that is ok. Otherwise go back to the central system and claim the missing message.
Pro:
- avoid peer-to peer problem
- least effort needed on registry side
- reciever can re-request "missing" message
- can be automated, no help needed by WMDA staff
- allows for different levels of details (C1 vs. C2)
Con:
- additional effort on WMDA side
- new endpoint for re-request specific message
- handling of the sequences
2.1 Rules
- The 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 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 means "adult donor", "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 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:
...