6.1 Embedded blocks

6.1.1 Embedded Meta block

The additional meta-information "blocks" are added to ensure the receiving registry is aware of:

A message identifier
A timestamp
What registry sent the information (sending registry)
What type of response is provided by the WMDA Match Connect system
Any failed validations detected by the Match Connect system

Field

Details

referenceMessageId*

string($uuid)

deliveredAtUtc*

string($date-time)

Server-supplied timestamp showing UTC time of Message delivery to receiving registry's inbox queue.

sendingRegistry*

integer
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 5678

4-digit ION of the sending registry

responseType

string

Enum:
Array [ Warning]

wmdaRemarks

One or more remarks, each in its own object

Field	Details
remarkType	string
description	string

messageSequenceNumber*

integer
example: 12345

Incrementing integer set by WMDA MatchConnect systems that indicates the order in which the messages were received by the WMDA and therefore the order in which messages should be processed. Each receiving registry has its own unique sequence.

messageType*

string

the type of message just sent by calling this endpoint

6.1.2 Embedded Address block (NEW_ADD)

With this message block, the contact information of the hub's institutions, namely Financial institutions, Transplant Centers and Laboratories are shared with the partner hubs. Thus a partner hub has all the required contact information for the Institution contained in Donor Requests.

Hubs are required to keep this contact information up to date.
It’s not only useless but forbidden to give a postbox (POB) in a LAB address since this address is used for the delivery of samples. For the same reason ZIP code, City, and Country are required in the address block.
The contactPerson is required if the INST_TYPE is ”LAB”.
The EMDIS ID (INST_ID) of an institution should remain stable over time and should not be assigned to different institutions.

In the Match-Connect system, the addresses will be embedded in the donor requests. See Chapter Requests for details.

Message structure:

Send

Retrieve

addressRequest

addressRetrieve

Field	Details
organisationId*	string nullable: false maxLength: 10 minLength: 3 Organisation unique identifier for the institution. Unique reference to an institution Allows local address management if needed (e.g. for other use cases) by receiving registry and backward compatibility to existing EMDIS implementations. Provided by the local registry system. Should be worldwide unique. Should follow the construct of hub code + local address id. The hub code usually are the two-character ISO country code of the registry (e.g. NL for Netherlands) In the case of multiple registries in one country, a replacement code will be assigned. Should be provided as a user-friendly (displayable) id for use on screens and on documentation.
line1*	string nullable: false maxLength: 60 Address line 1
line2	string nullable: true maxLength: 60 Address line 2
line3	string nullable: true maxLength: 60 Address line 3
postalCode*	string nullable: false maxLength: 10
city*	string nullable: false maxLength: 40
country*	string nullable: false minLength: 2 maxLength: 2 2 character ISO country code ( ISO 3166-1 alpha-2)
type*	string nullable: false minLength: 3 maxLength: 3 HUB = EMDIS Hub DON = Donor centre TRA = Transplant centre HAR = Harvesting centre LAB = Typing laboratory FIN = Financial institution CBB = Cord Blood Bank
contactPerson	string nullable: true maxLength: 40 Contact person. Required if type = LAB.
phone*	string nullable: false maxLength: 20
fax	string nullable: true maxLength: 20
email	string nullable: true maxLength: 60
receivingRegistry*	string maximum: 9999 minimum: 0 maxLength: 4 minLength: 4 example: 1234 4 digit ION of the receiving registry

Field	Details
wmdaResponse	Embedded WMDA Response Block

limit	integer default: 100
shouldPeek	boolean default: false Set to true if you want messages to remain available after retrieval

Field	Details
originalMessage	{...}
metaInformation	Embedded Meta Block

6.1.3 Embedded Patient Block

There is no "register patient" endpoint. Instead, an embedded patient block will accompany all requests. The embedded patient block looks as follows:

Field	Details
wmdaId*	integer nullable: false example: 1234 ID provided by the WMDA
patientId*	string maxLength: 17 nullable: false example: XY1234P Organisation unique identifier for the patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here.
hla*	{...}
idm	{...}
dateOfBirth	string($date) nullable: true maxLength: 10 example: 1961-05-27
diagnosis	{...}
diseasePhase	string nullable: true Enum: Array [ 48 ]
ethnicity	string nullable: true Enum: Array [ 20 ]
poolCountryCode	string maxLength: 2 pattern: ^[A-Z]{2} nullable: true example: NL ISO 3166-1 alpha-2 Country Code (capitalized)
abo	string nullable: true Enum: Array [ 4 ]
rhesus	string nullable: true Enum: Array [ 2 ]
weight	integer nullable: true minimum: 1 maximum: 999 example: 76
sex	string nullable: true Enum: Array [ 2 ]
firstName	string maxLength: 30 nullable: true example: John First (given name) of the patient
lastName	string maxLength: 30 nullable: true example: Doe Last (family name) of the patient

6.1.4 Embedded Donor Block

In EMDIS, the following messages are linked to the donor updates:

IDM_RES
TYP_RES
NO_RES
RSV_RES

These four and newly two more (SMP_ARR and SMP_INFO) will be replaced with the Match-Connect API endpoints that have the donor details embedded in the message. Respective endpoints of IDM_RES and TYP_RES will deliver new IDM and new typing details, and all the mentioned endpoints will also inform the patient registry of the new donor status.

These donor updates are for the receiving registry (patient registry) only and will not be updated in the central HUB. So the sending (donor) registry is responsible to send a DIFF upload to the S&M system in parallel to keep information in sync.

Donor type

Payload

Adult donor

Field	Details
id*	integer nullable: false example: 5176
donorRegistryIon*	integer nullable: false minimum: 1000 maximum: 9999 example: 1234
abbreviation	string example: NL-WMDA maxLength: 24
haplotypeFrequencySetId*	integer nullable: true minimum: 0 example: 15
status*	string nullable: falseEnum: Array [ 3 ]
sex*	string nullable: trueEnum: Array [ 2 ]
ethnicity*	string nullable: trueEnum: Array [ 21 ]
idm*	{...}
abo*	string nullable: trueEnum: Array [ 4 ]
rhesus*	string nullable: trueEnum: Array [ 2 ]
isSelected*	boolean nullable: true true when this record has been marked as selected
resolutionScore*	number minimum: 0 maximum: 100 nullable: true example: 54
resolutionString*	string minLength: 5 maxLength: 5 example: AP-A- nullable: true A - high-res P - low or intermediate, - no typing
grid*	string nullable: true maxLength: 19 minLength: 19 example: 9991012070433202000
donorId*	string nullable: true example: ABC1234 maxLength: 25
donorType*	string nullable: falseEnum: Array [ 2 ]
lastContactDate*	string($date) nullable: true minLength: 10 maxLength: 10
marrowDonationsCount*	integer nullable: true example: 0
pbscDonationsCount*	integer nullable: true example: 1
dateOfBirth*	string($date) nullable: true maxLength: 10 example: 1961-05-27
donorAttribute	string maxLength: 3 nullable: true
kir	{...}
weight	integer nullable: true minimum: 1 maximum: 999 example: 76
height	integer nullable: true minimum: 1 maximum: 999 example: 161
collectionType	string nullable: true Collection type, i.e. the willingness of the donor to donate in a specific manner. M = Marrow P = PBSC B = Both PBSC & Marrow Enum: Array [ 3 ]
transfusionsCount	integer nullable: true example: 1
pregnanciesCount	integer nullable: true example: 2
reservedPatientId	string nullable: true example: 1234222ss
statusEndDate	string($date) maxLength: 10 nullable: true
statusReason	string nullable: true DO = Donor is too old, DD = Donor died, MR = Medical reasons, PR = Personal reasons, TX = After transplantation, MO = Donor has moved, UC = Unable to contact donor, OT = Other reasons, TQ = Typing questionable, UK = Unknown Enum: Array [ 10 ]
hla*	{...}
mic*	{...}
ccr5*	string nullable: trueEnum: Array [ 3 ]
lastMedicalCheckupDate	string($date) nullable: true minLength: 10 maxLength: 10
registry*	{...}

CBU

Field	Details
id*	integer nullable: false example: 5176
donorRegistryIon*	integer nullable: false minimum: 1000 maximum: 9999 example: 1234
abbreviation	string example: NL-WMDA maxLength: 24
haplotypeFrequencySetId*	integer nullable: true minimum: 0 example: 15
status*	string nullable: falseEnum: Array [ 3 ]
sex*	string nullable: trueEnum: Array [ 2 ]
ethnicity*	string nullable: trueEnum: Array [ 21 ]
idm*	{...}
abo*	string nullable: trueEnum: Array [ 4 ]
rhesus*	string nullable: trueEnum: Array [ 2 ]
isSelected*	boolean nullable: true true when this record has been marked as a selected
resolutionScore*	number minimum: 0 maximum: 100 nullable: true example: 54
resolutionString*	string minLength: 5 maxLength: 5 example: AP-A- nullable: true A - high-res P - low or intermediate, - no typing
cordId	string nullable: true maxLength: 25 example: 9991012070433202000
donorType*	string nullable: falseEnum: Array [ 2 ]
collectionDate	string($date) minLength: 10 maxLength: 10 nullable: true example: 2021-05-27
volume*	integer example: 25 nullable: true
tncCount*	number example: 1140000000 nullable: true
cd34Count*	number example: 3900000 nullable: true
viability*	integer minimum: 0 maximum: 100 example: 97 nullable: true
attachedSegmentsCount	integer nullable: true minimum: 0 maximum: 99 example: 2
bankManufacturerIdWmda*	integer example: 5432 nullable: true
cbbAccreditationStatus*	string nullable: trueEnum: Array [ 3 ]
localId	string example: 12345ABC nullable: true
bagId	string example: ABCDE1234 nullable: true
dateOfBirth*	string($date) nullable: true maxLength: 10 example: 1961-05-27
processingDate	string($date) nullable: true minLength: 10 maxLength: 10
processingMethod	string nullable: true HES = Hydroxy-Ethyl-Starch, DGS = Density Gradient Separation, CEN = Centrifuge, FIL = Filtration, FIC = FICOL, PER = PERCOL, OTH = Other Enum: Array [ 7 ]
processingMethodType	string nullable: trueEnum: Array [ 5 ]
freezeDate	string($date) nullable: true
freezeMethod	string nullable: trueEnum: Array [ 2 ]
reservedPatientId	string nullable: true example: 1234222ss
productModifications	string nullable: trueEnum: Array [ 7 ]
bagType	string nullable: trueEnum: Array [ 4 ]
bagsCount	integer minimum: 1 maximum: 99 example: 2 nullable: true
bankDistributionIdWmda	integer nullable: true example: 1234
bacterialCultureResults	string nullable: true P = Positive N = Negative D = Not done Enum: Array [ 3 ]
fungalCultureResults	string nullable: true P = Positive N = Negative D = Not done Enum: Array [ 3 ]
hemoglobinopathyScreeningStatus	string nullable: true DN = "Screening done, normal results" DU = "Screening done, unusual findings" NS = "No screening done" CD = "Can be done at time of release" NC = "Cannot be done" DT = "Thalassemia" DD = "Drepanocytosis" Enum: Array [ 7 ]
viabilityCellType	string nullable: true type of cell tested for viability Enum: Array [ 3 ]
viabilityMethod	string nullable: true 7A = 7AAD PI = Propidium Iodide TB = Trypan Blue OT = Other Enum: Array [ 4 ]
viabilityDate	string($date) nullable: true
volumeFrozen*	integer example: 25 nullable: true
tncFrozenCount*	number example: 1020000000 nullable: true
cd34FrozenCount*	number example: 3700000 nullable: true
cfuFrozenCount	integer nullable: true minimum: 10000 maximum: 99990000 Total count of colony forming units (post processing, prior to cryopreservation)
mncFrozenCount*	number example: 430000000 nullable: true
ccr5	string nullable: trueEnum: Array [ 3 ]
kir	{...}
plasmaAliquotsCount	integer minimum: 0 maximum: 99 nullable: true Number of plasma aliquots available
redCellAliquotsCount	integer minimum: 0 maximum: 99 nullable: true Number of red cell fraction aliquots
nucleatedRbcFrozenCount	integer minimum: 0 maximum: 9999000000 nullable: true Total number of nucleated red blood cells (post processing, prior to cryopreservation)
serumAliquotsCount	integer minimum: 0 maximum: 99 nullable: true
serumQuantity	number minimum: 0 maximum: 99.9 nullable: true
plasmaQuantity	number minimum: 0 maximum: 99.9 nullable: true
ctCompletionDate	string($date) maxLength: 10
ctSampleType	string nullable: true maxLength: 2 AS = CBU Contiguous Attached Segment, WB = Whole Blood Sample, RC = Red Cell Fraction (pellet), FP = Blood Spotted Filter Paper, ED = Extracted DNA Enum: Array [ 5 ]
dnaSamplesAvailable	boolean nullable: true
otherSamplesAvailable	boolean nullable: true
donorAttribute	string maxLength: 3 nullable: true
statusEndDate	string($date) maxLength: 10 nullable: true
statusReason	string nullable: true DO = Donor is too old, DD = Donor died, MR = Medical reasons, PR = Personal reasons, TX = After transplantation, MO = Donor has moved, UC = Unable to contact donor, OT = Other reasons, TQ = Typing questionable, UK = Unknown Enum: Array [ 10 ]
hla*	{...}
mic	{...}
registry	{...}
cbb	{...}
maternalInfo	{...}

ADCU

In the future

Here is the comparison of the DONOR_CB and the API endpoints: EMDIS vs API.xlsx

6.1.5 Embedded WMDA Response block

The WMDA will provide a standard response to request messages sent to Match-Connect. Its structure is as follows:

Field	Details
deliveredAtUtc*	string($date-time) Server-supplied timestamp showing time of Message delivery to receiving registry's inbox queue
referenceMessageId*	string($uuid)
responseType*	stringEnum: Array [ Success, Warning, Failed] messages can be failed, if the message has a structure or information that prevent delivery to the receiving registry. This could be incorrect JSON structure and non-existent ION or because the receiving registry does not allow messages from your registry.
wmdaRemark	[...]

6.2 Message Response

The message response is intended as an automated response to every user generated message. It serves three purposes:

message acknowledgment
warning
message denial

This is a purely machine-to-machine type of message, as compared to EMDIS where such responses can be user generated.

Note: The concept of the REF_CODE field used in EMDIS is replaced by the GUID assigned by the central system to each message. The Message Response is supposed to be using the GUID of the original message as the Reference ID in its structure.

Message structure:

Send

Retrieve

MessageResponse

MessageResponseRetrieve

Field

Details

organisationResponse

Field	Details
retrievedAtUtc*	string($date-time) Server-supplied timestamp showing time of Message retrieval and storage in organisation's own systems
referenceMessageId*	string($uuid)
responseType*	string Enum: Array [ 3 ]
remark	string

Field	Details
wmdaResponse	Embedded WMDA Response Block

limit	integer default: 100
shouldPeek	boolean default: false Set to true if you want messages to remain available after retrieval

Field	Details
originalMessage	{...}
metaInformation	Embedded Meta Block

6.3 Text message [TXT_MSG]

The TXT_MSG is useful to convey notes or comments pertaining to a particular patient, donor, or patient/donor pair.

Note: Since Warnings are going to be automated, we must keep Text Messages as the only means for user communication left.

Message structure:

Send

Retrieve

textMessageRequest

textMessageRetrieve

Field	Details
text*	string nullable: true Text. Message for a human at receiving registry.
receivingRegistry*	string maximum: 9999 minimum: 0 maxLength: 4 minLength: 4 example: 1234 4 digit ION of the receiving registry
patient*	Patient ID
donor*	Donor ID

Field	Details
wmdaResponse	Embedded WMDA Response Block

limit	integer default: 100
shouldPeek	boolean default: false Set to true if you want messages to remain available after retrieval

Field	Details
originalMessage	{...}
metaInformation	Embedded Meta Block

6.4 Alert message

The Alert message is used to broadcast an important information about the system, like planned service outage. Messages are generated centrally by WMDA. Members are expected to display them to the users.

Message structure:

Send

Retrieve

AlertRetrieve

Alerts can only be sent by the WMDA's central system

limit	integer default: 100
shouldPeek	boolean default: false Set to true if you want messages to remain available after retrieval

Field

Details

originalMessage

Field	Details
level	string alert level. enums may change Enum: Array [ 3 ]
status	string check later Enum: Array [ 2 ]
message	string maxLength: 1024 example: WMDA will do maintenance on SMC system on the weekend of 10 march

metaInformation

Embedded Meta Block

6.5 Alert Update message

The Alert Update message is used to broadcast an update about some previous alert. Messages are generated centrally by WMDA. Members are expected to display them to the users.

Message structure:

Send

Retrieve

AlertUpdateRetrieve

Alert updates can only be sent by the WMDA's central system

limit	integer default: 100
shouldPeek	boolean default: false Set to true if you want messages to remain available after retrieval

Field

Details

originalMessage

Field	Details
alertReferenceIdentifier	string($uuid)
level	string alert level. enums may change Enum: Array [ 3 ]
status	string check later Enum: Array [ 2 ]
message	string maxLength: 1024 example: WMDA will do maintenance on SMC system on the weekend of 10 march

metaInformation

Embedded Meta Block

6.6 Available Messages

The available messages endpoint is used for retrieving an array of messages that are ready to be downloaded. This information can then be used to retrieve the messages from their respective *retrieve endpoints.

Message structure:

Send

Retrieve

availableMessages

N/A

No parameters specified

Field	Details
totalMessages	integer total sum of messages that are ready for retrieval
messageType	string the message type Enum: Array [ 23 ]
numberOfMessages	integer number of messages that are ready for retrieval