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

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

4-digit ION of the sending registry

messageType

string

the type of message just sent by calling this endpoint

responseType

string

Enum:
Array [ Warning, Acknowledge]

wmdaRemark

One or more remarks, each in its own object

Field	Details
remarkType	string
description	string

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.

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

Consider to use address block structure according to HL7-FHIR standard with extensions (https://hapifhir.io/hapi-fhir/apidocs/hapi-fhir-structures-r4/org/hl7/fhir/r4/model/Address.html), e.g.

Suggested format	Suggested field	Description	Mapping to NEW_ADD
StringType	City	The name of the city, town, suburb, village or other community or delivery center.	City Req 40
StringType	country	Country - a nation as commonly understood or generally accepted.	Country Req 2
StringType	District	The name of the administrative area (county).	Address Line 2 ADDR_2 Opt 40
List <StringType>	line	This component contains the house number, apartment number, street name, street direction, and P.O.	Address Line 3 ADDR_3 Opt 40
Period	period	The time period when the address was/is in use.	new - Opt
StringType	postalCode	A postal code designating a region defined by the postal service.	ZIP code ZIP Req 10
StringType	state	Sub-unit of a country with limited sovereignty in a federally organized country.	new - Opt
StringType	text	Specifies the entire address as it should be displayed e.g. on a postal label. This may be provided instead of or as well as the specific parts.	Address Line 1 to Address Line 3, City, Country, Zip code - Opt
Enumeration <Address.AddressType>	type	Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses. Most addresses are both.). This is the underlying object with id, value, and extensions. The accessor "getType" gives direct access to the value.	new - Req
Enumeration <Address.AddressUse>	use	The purpose of this address.	Institution Type INST_TYPE Req 3
StringType	contact person	The name of the contact person.	Contact person PERSON Opt 40
StringType	`phone`	The value is a telephone number used for voice calls.	Phone Number PHONE Req 20
StringType	`fax`	The value is a fax machine.	Fax Number FAX Opt 20
StringType	`email`	The value is an email address.	Email address EMAIL Opt 60
StringType	ID	Not needed anymore, as the full address will be sent embedded in every request.	INST_ID Req 10
		Obsolete. S&M provides accreditation on the match list.	Accreditation Opt 5

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 [ Warning, Acknowledge, 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

No parameters specified

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

message*

Field	Details
text	string nullable: true Text. Message for a human at receiving registry.
sentDate	string($date-time) nullable: true Date sent SENT_DATE Opt 8

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

No parameters specified

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

No parameters specified

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

No parameters specified

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