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 (sender)
What type of information is contained
/* Pending */ Any failed validations detected by the Match Connect system

metaInformation
messageId	string($uuid)
sentAtUtc	string($date-time) Server-supplied timestamp showing UTC time of Message delivery to recipient's inbox queue.
sender	string maximum: 9999 minimum: 0 maxLength: 4 minLength: 4 example: 5678 4 digit ION of sender
messageType	string Enum: Array [ 1 ]

6.1.2 Embedded Address block

Original message: Address to broadcast [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 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. (HP's suggestion, requires discussion/checking the standard regarding the institution ID field, the accreditation field and the extension of the use field):

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 ADD_NEW
StringType	city	The name of the city, town, suburb, village or other community or delivery center.	City CITY Req 40
StringType	country	Country - a nation as commonly understood or generally accepted.	Country 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, P.O.	Address Line 3 ADDR_3 Opt 40
Period	period	Time period when 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.	new - Opt
Enumeration <Address.AddressType>	type	Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g.	new - Req
Enumeration <Address.AddressUse>	use	The purpose of this address.	Institution Type INST_TYPE Req 3

Missing fields from ADD_NEW with Albert's comments for consideration:

Institution Identification INST_ID Req 10 - not needed anymore, as the full address will be sent embedded in every request
Address Line 1 ADDR_1 Req 40 - needs to be added, as the structure above has it only in field "text" that seems optional
Contact person PERSON Opt 40 - better to have a separate field
Phone Number PHONE Req 20 - better to have a separate field
Fax Number FAX Opt 20 - better to have a separate field
Email address EMAIL Opt 60 - better to have a separate field
Accreditations obtained ACCREDITATION Opt 5 - is it still being used by anyone?
- Position 1: NetCord-FACT
- Position 2: AABB
- Position 3: to be defined
- Position 4: to be defined
- Position 5: to be defined

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:

patient
wmdaId*	integer nullable: false example: 1234 ID provided by the WMDA
patientId*	string maxLength: 17 nullable: false example: P1234XX Organisation unique identifier for 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: trueEnum: Array [ 48 ]
ethnicity	string nullable: trueEnum: 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: trueEnum: Array [ 4 ]
rhesus	string nullable: trueEnum: Array [ 2 ]
weight	integer nullable: true minimum: 1 maximum: 999 example: 76
sex	string nullable: trueEnum: 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:

InfectiousDiseaseMarkerResultRequest (IDM_RES)
TypingResponseRequest (TYP_RES)
NoResultRequest (NO_RES)
ReservationResultRequest (RSV_RES)

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.

In the future a block for ADCUs may come to play.

Donor type

Payload

Adult donor

{

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

{

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

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

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

Request

wmdaResponse
deliveredAtUtc	string($date-time) Server-supplied timestamp showing time of Message delivery to recipient's inbox queue
referenceMessageId	string($uuid)
responseType	string Enum: Array [ 3 ]
wmdaRemark	[...]

Response

wmdaResponse
deliveredAtUtc	string($date-time) Server-supplied timestamp showing time of Message delivery to recipient's inbox queue
referenceMessageId	string($uuid)
responseType	stringEnum: Array [ 3 ]
wmdaRemark	[...]

MessageResponse payload

Meta block (6.1.1)

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

Patient Block (6.1.3)
Donor Block (6.1.4)
Text

TextMessage payload

Meta block (6.1.1)

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

Alert Payload:

Level
Status
Message

Meta block (6.1.1)

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

Alert Update Payload:

Alert reference ID (GUID)
Level
Status
Message

Meta block (6.1.1)