Table of Contents

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
Which What registry sent the information (sendersending registry)
What type of information is contained
A message identifier
A timestamp
response is provided by the WMDA Match Connect system
Any failed validations detected by the Match Connect system

metaInformation{

A sequence number, so that the receiving registry knows if any message is missing.

metaInformation*

Expand

title	...

referenceMessageId*

Field nameformatDescriptionmessageId

string($uuid)

ID of the originally sent messagesentAtUtc

deliveredAtUtc*

string($date-time)

Server-supplied timestamp showing UTC time of Message delivery to

recipient

receiving registry'

s inbox

s inbox queue.

sender

sendingRegistry*

string

integer
maximum: 9999
minimum:

1000
maxLength: 4
minLength: 4
example: 5678

4-digit ION of the

sender

sending registry

messageType

responseType

string

To be designed and described. The idea is to help registry's MC admin to analyze possible issues reported in validationDetails field. AM: I think this is an excessive information, as messageId should be sufficient. validationDetailsTo be designed and described. The idea is to supply the concerns of the central hub validation system that are acceptable but require attention of the receiving registry.

}

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.

StringType	city	The name of the city, town, suburb, village or other community or delivery center.
StringType	country	Country - a nation as commonly understood or generally accepted.
StringType	district	The name of the administrative area (county).
List<StringType>	line	This component contains the house number, apartment number, street name, street direction, P.O.
Period	period	Time period when address was/is in use.
StringType	postalCode	A postal code designating a region defined by the postal service.
StringType	state	Sub-unit of a country with limited sovereignty in a federally organized country.
StringType	text	Specifies the entire address as it should be displayed e.g.
Enumeration <Address.AddressType>	type	Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g.
Enumeration <Address.AddressUse>	use	The purpose of this address.

~~Institution Type INST_TYPE Req 3~~
~~Institution Identification INST_ID Req 10~~
~~Address Line 1 ADDR_1 Req 40~~
~~Address Line 2 ADDR_2 Opt 40~~
~~Address Line 3 ADDR_3 Opt 40~~
~~Contact person PERSON Opt 40~~
~~ZIP code ZIP Req 10~~
~~City CITY Req 40~~
~~Country COUNTRY Req 2~~
~~Phone Number PHONE Req 20~~
~~Fax Number FAX Opt 20~~
~~Email address EMAIL Opt 60~~
~~Accreditations obtained ACCREDITATION Opt 5~~
- ~~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:

Request

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.

Enum:
Array [ Warning]

wmdaRemarks

One or more remarks, each in its own object

Expand

title	...

remarkType	string Array [ InvalidHLA ]
description	string

messageSequenceNumber*

integer
example:12345

Incrementing integer set by WMDA MatchConnect system 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

Array [ attachment, alert, updatedPatient, ping, textMessage, genericRequest, extendedTypingRequest, extendedTypingResponse, sampleRequest, sampleInfo, sampleArrival, sampleResponse, infectiousDiseaseMarkerRequest, infectiousDiseaseMarkerResult, reservationRequest, reservationResponse, reservationRelease, requestCancellation, requestRejected, resultReminder, messageResponse, cordBloodUnitReportRequest, cordBloodUnitReportResponse ]

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.
Organisation unique identifier for the institution (formerly known as INST_ID):
- Should remain stable over time and must not be assigned to different institutions
- Is a 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 ION + local address id.
    - The ION to be used is the ION of the patient registering registry (PR).
- Should be provided as a user-friendly (displayable) id for use on screens and on documentation.

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

Field

Details

organisationId

string
nullable: true
minLength: 5
maxLength: 19
example: 9999123456

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 ION + local address id.
  - The ION to be used is the ION of the patient registering registry (PR).
Should be provided as a user-friendly (displayable) id for use on screens and on documentation.

organisation*

Expand

title	...

Field	Details
name*	string maxLength: 50 example: Institute A Name of the destination organisation
addressLine1*	string maxLength: 50 nullable: false example: Schipholweg 57 First line of address. Generally the street and house number.
addressLine2	string maxLength: 50 nullable: true example: Second floor Second line of address
addressLine3	string maxLength: 50 nullable: true example: Unit 15 Third line of address
postalCode*	string maxLength: 10 nullable: false example: 2316 ZL
city*	string maxLength: 50 nullable: false example: Leiden The name of the city, town, suburb, village or other community or delivery center.
country*	string minLength: 2 maxLength: 2 nullable: false example: NL 2 character ISO country code ( ISO 3166-1 alpha-2)
type*	string nullable: false Array [ node, donorCentre, transplantCentre, collectionCentre, lab, financialInstitution, cordBloodBank ]

contactPerson*

Expand

title	...

Field	Details
name*	string maxLength: 50 example: Jane Doe The name of the contact person.
phone*	string maxLength: 50 nullable: false example: +31 123456789 The value is a telephone number used for voice calls.
fax	string maxLength: 50 nullable: true example: +31 123456790 The value is a fax machine.
email	string maxLength: 320 nullable: true The value is an email address.

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 minLength:5 nullable: false example: 99991234P MUST Start with ION of patient registry. Organisation unique identifier for patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here.
emdisPatientId	string maxLength: 17 minLength: 3 nullable:true example: AU9654021 MUST start with two letter EMDIS hub code. The value comprises the EMDIS patient identification, where the patient search centre is an EMDIS member, otherwise the value is empty.
hla*	{...}
idm	{...}
dateOfBirth	string($date) nullable: true maxLength: 10 example: 1961-05-27
diagnosis	{...}
diseasePhase	string nullable: true Enum: Array [ PF, PI, AP, BC, AD, SD, RD, NA, C0, C1, C2, C3, C4, C5, C6, C7, C8, C9, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, R0, R1, R2, R3, R4, R5, R6, R7, R8, R9, N0, N1, N2, N3, N4, N5, N6, N7, N8, N9 ]
ethnicity	string nullable: true Enum: Array [ UK, AF, AS, CA, HI, AFNA, AFSS, ASSW, ASSO, ASCE, ASSE, ASNE, ASOC, CAEU, CAER, CANA, CAAU, HICA, HISA, MX, OT ]
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 [ A, B, O, AB ]
rhesus	string nullable: true Enum: Array [ P, N ]
weight

Donor typePayloadAdult donor Expand

title	Donor...

{

id*integer
nullable: false
example: 5176donorRegistryIon*integer
nullable: false
minimum: 1000
maximum: 9999
example: 1234abbreviationstring
example: NL-WMDA
maxLength: 24haplotypeFrequencySetId*integer
nullable: true
minimum: 0
example: 15status*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 ]registryAccreditationStatus*string
nullable: trueEnum:
Array [ 2 ]firstAccreditationYear*number
minimum: 1990
maximum: 2100
nullable: true
example: 2019matchClass*string
example: 9/10
nullable: falsenmdpGrade*string
maxLength: 5
example: MPPMP
nullable: true

~~A - high-res match on ARD, P - probable match, M - sure Mismatch~~

zeroMismatchProbability*integer
minimum: 0
maximum: 100
nullable: trueoneMismatchProbability*integer
nullable: true
minimum: 0
maximum: 100twoMismatchProbability*integer
nullable: true
minimum: 0
maximum: 100aLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100bLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100cLocusMatchProbability*

integer
nullable: true
minimum:

0integer

1
maximum:

100drLocusMatchProbability*

999 example: 76
sex	string

integer

nullable: true

minimum: 0
maximum: 100dqLocusMatchProbability*

Enum: Array [ M, F ]
firstName	string maxLength:50

nullable: true

minimum

example:

0
maximum: 100inexplicable*~~boolean~~matchingInformationDpb1*~~{...}~~mismatches*~~[...]~~searchResultRecordState*string
nullable: false
default: ExistingEnum:
Array [ 4 ]searchResultRecordStateUpdatedAt*string($date-time)
nullable: true
maxLength: 255

~~date and time when the last change was registered in the system~~

isSelected*boolean
nullable: true

true when this record has been marked as selected

resolutionScore*number
minimum: 0
maximum: 100
nullable: true
example: 54resolutionString*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: 9991012070433202000donorId*string
nullable: true
example: ABC1234
maxLength: 25donorType*string
nullable: falseEnum:
Array [ 2 ]lastContactDate*string($date)
nullable: true
minLength: 10
maxLength: 10marrowDonationsCount*integer
nullable: true
example: 0pbscDonationsCount*integer
nullable: true
example: 1dateOfBirth*string($date)
nullable: true
maxLength: 10
example: 1961-05-27donorAttributestring
maxLength: 3
nullable: truekir{...}weightinteger
nullable: true
minimum: 1
maximum: 999
example: 76heightinteger
nullable: true
minimum: 1
maximum: 999
example: 161collectionTypestring
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 ]transfusionsCountinteger
nullable: true
example: 1pregnanciesCountinteger
nullable: true
example: 2reservedPatientIdstring
nullable: true
example: 1234222ssstatusEndDatestring($date)
maxLength: 10
nullable: truestatusReasonstring
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 ]lastMedicalCheckupDatestring($date)
nullable: true
minLength: 10
maxLength: 10registry*{...}

}

CBU

Expand

title	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 ]
registryAccreditationStatus*	string nullable: trueEnum: Array [ 2 ]
firstAccreditationYear*	number minimum: 1990 maximum: 2100 nullable: true example: 2019
matchClass*	string example: 9/10 nullable: false
nmdpGrade*	string maxLength: 5 example: MPPMP nullable: true ~~A - high-res match on ARD, P - probable match, M - sure Mismatch~~
zeroMismatchProbability*	integer minimum: 0 maximum: 100 nullable: true
oneMismatchProbability*	integer nullable: true minimum: 0 maximum: 100
twoMismatchProbability*	integer nullable: true minimum: 0 maximum: 100
aLocusMatchProbability*	integer nullable: true minimum: 0 maximum: 100
bLocusMatchProbability*	integer nullable: true minimum: 0 maximum: 100
cLocusMatchProbability*	integer nullable: true minimum: 0 maximum: 100
drLocusMatchProbability*	integer nullable: true minimum: 0 maximum: 100
dqLocusMatchProbability*	integer nullable: true minimum: 0 maximum: 100
inexplicable*	~~boolean~~
matchingInformationDpb1*	~~{...}~~
mismatches*	~~[...]~~
searchResultRecordState*	string nullable: false default: ExistingEnum: Array [ 4 ]
searchResultRecordStateUpdatedAt*	string($date-time) nullable: true maxLength: 255 ~~date and time when the last change was registered in the system~~
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:

...

get_api_v1_MessageResponseRetrieve

...

Reference ID (GUID)
Response type
- message acknowledgment
- warning
- message denial
Remark - a string explaining the reason for a denial or a warning, empty for acknowledgment

...

MessageResponse payload

Meta block

John First (given name) of the patient
lastName	string maxLength:50 nullable: true example: Doe Last (family name) of the patient
mic	{...}

6.1.4 Embedded Donor Block (donor in request)

In case the embedded donor block is part of a message type that may not result in updates of donor-related data, the "embedded donor block (donor in request" block is used.

Only sending a grid, cordId or adcuId for message types with static donor information enhances privacy and security through data minimization.

Donor type

Details

donor*

Expand

title	...

donorType*

string
enum:
Array [ adult, adcu, cbu ]

donorId*

string
oneOf:

grid { "maxLength": 19, "minLength": 19, "example": 9991012070433202000 }

adcuId { "maxLength": 13, "minLength": 13, "example": "A999916123456" }

cordId { "maxLength": 17, "example": "CB1234567" }

6.1.5 Embedded Donor Block (donor in response)

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

TYP_RES
IDM_RES
RSV_RES

These three 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.

The corresponding endpoints in Match-Connect are:

extendedTypingResponse
infectiousDiseaseMarkerResponse
reservationResponse

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 for sending a DIFF upload to the S&M system in parallel to keep information in sync.

Field

Details

grid*

string
nullable:true
maxLength: 19
minLength: 19
example: 9991012070433202000

dateOfBirth*

string
nullable: false
minLength: 10
maxLength: 10
example: 1961-05-27

sex

string
nullable:true
Enum: [M, F]

hla*

Expand

title	...

a*	dna* {...} description: HLA node with DNA
b*	dna* {...} description: HLA node with DNA
c	dna {...} description: HLA node with DNA
drb1*	dna* {...} description: HLA node with DNA
drb3	dna {...} description: HLA node with DNA
drb4	dna {...} description: HLA node with DNA
drb5	dna {...} description: HLA node with DNA
dqa1	dna {...} description: HLA node with DNA
dqb1	dna {...} description: HLA node with DNA
dpa1	dna {...} description: HLA node with DNA
dpb1	dna {...} description: HLA node with DNA

abo

string
nullable:true
Enum: [A, B, O, AB]

rhesus

string
nullable:true
Enum: [P, N]

donorRegistryIon*

integer($int32)
nullable: false
minimum: 1000
maximum: 9999
example: 1234

Unique number provided by ICCBBA for the registry that is responsible for the donor/CBU

status*

string
nullable: false
Enum: [ AV, TU ]

ethnicity

string
nullable: true

Enum:
Array [ UK, AF, AS, CA, HI, AFNA, AFSS, ASSW, ASSO, ASCE, ASSE, ASNE, ASOC, CAEU, CAER, CANA, CAAU, HICA, HISA, MX, OT ]

idm

[ ... ]

lastContactDate

string($date)
nullable: true
minimum: 10
maximum: 10

marrowDonationsCount

integer($int32)
nullable: true
example: 0

pbscDonationsCount

integer($int32)
nullable: true
example: 1

donorAttribute

string
nullable: true
maximum: 3

weight

integer
nullable: true
minimum: 1
maximum: 999
example: 76

height

integer($int32)
nullable: true
minimum: 1
maximum: 999
example: 161

kir

[ ... ]

collectionType

string
nullable: true
Enum: [ M, P, B ]

Collection type, i.e. the willingness of the donor to donate in a specific manner. M = Marrow P = PBSC B = Both PBSC & Marrow

transfusionsCount

integer($int32)
nullable: true
example: 1

pregnanciesCount

integer($int32)
nullable: true
example: 2

reservedPatientId

string
nullable: true
example: 1234222ss

statusEndDate

string($date)
nullable: true
maximum: 10

statusReason

string
nullable: true
Enum: [ DO, DD, MR, PR, TX, MO, UC, OT, TQ, UK ]

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

mic

{...}

ccr5

string
nullable: true
Enum: [ DD, DW, WW ]

lastMedicalCheckupDate

string($date)
nullable: true
minimum: 10
maximum: 10

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

6.1.6 Embedded general information block

The WMDA will provide a standard response that contains the parameters used to retrieve messages in Match-Connect. Its structure is as follows:

generalInformation*

Expand

title	...

Field	Details
limit*	integer($int32) default: 100
totalCount*	integer($int32) minimum: 0 example: 1
remainingCount*	integer($int32) minimum: 0
isSuccessful*	boolean example: true
summary*	String maxLength: 255 example: 1 message retrieved successfully. 0 remaining messages.

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 referenceMessageId assigned by the central system to each message. The Message Response is supposed to be using the referenceMessageId of the original message as the Reference ID in its structure.

Message structure:

Send (Post)

Retrieve (Post)

MessageResponseRequest

MessageResponseRetrieve

Expand

title	Request...

Field

Details

organisationResponse

Expand

title	...

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 [ warning, acknowledge, deny ]
remark	string maxLength: 1000 nullable: true

Expand

title	Response...

Field	Details
metaInformation*	Embedded Meta Block

Expand

title	Request...

limit

integer
default: 100

shouldPeek

boolean
default: false

Set to true if you want messages to remain available after retrieval

messageSequenceNumber

integer
examplet: 12345

Optional field to request a message with a specific messageSequenceNumber. If that message (no longer) exists then no message will be returned.

Expand

title	Response...

Field

Details

generalInformation*

Embedded General Information Block

messages*

Expand

title	...

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 (Post)

Retrieve (Post)

textMessageRequest

textMessageRetrieve

Expand

title	Request...

Field

Details

requestId

string
maxLength: 19
example:XX12345
nullable: true

text*

string
nullable: true
example: Would it be possible to also perform IDM test for SARS-CoV-23?

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*

Expand

title	...

Field

Details

wmdaId*

integer
nullable: false
example: 1234

ID provided by the WMDA

donor*

Embedded Donor Block (donor in request)

Expand

title	Response...

Field	Details
metaInformation*	Embedded Meta Block

Expand

title	Request...

limit

integer
default: 100

shouldPeek

boolean
default: false

Set to true if you want messages to remain available after retrieval

messageSequenceNumber

integer
examplet: 12345

Optional field to request a message with a specific messageSequenceNumber. If that message (no longer) exists then no message will be returned.

Expand

title	Response...

Field

Details

generalInformation*

Embedded General Information Block

messages*

Expand

title	...

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 (Post)

AlertRetrieve

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

Expand

title	Request...

limit

integer
default: 100

shouldPeek

boolean
default: false

Set to true if you want messages to remain available after retrieval

messageSequenceNumber

integer
examplet: 12345

Optional field to request a message with a specific messageSequenceNumber. If that message (no longer) exists then no message will be returned.

Expand

title	Response...

Field

Details

generalInformation*

Embedded General Information Block

messages*

Expand

title	...

Field	Details
originalMessage*	...
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 (Post)

AlertUpdateRetrieve

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

Expand

title	Request...

limit

integer
default: 100

shouldPeek

boolean
default: false

Set to true if you want messages to remain available after retrieval

messageSequenceNumber

integer
examplet: 12345

Optional field to request a message with a specific messageSequenceNumber. If that message (no longer) exists then no message will be returned.

Expand

title	Response...

Field

Details

generalInformation*

Embedded General Information Block

messages*

Expand

title	...

Field	Details
originalMessage*	...
metaInformation*	Embedded Meta Block

6.6 Available Messages

This endpoint allows end users to retrieve an overview of all messages that are ready to be downloaded, including their corresponding sequence numbers. This information can be used to retrieve the messages from their respective *retrieve endpoints. If desired, the messages can be pulled in chronological order, given by the sequence numbers. Each "retrieve" endpoint will have the optional parameter "sequenceNumber", that allows for an indivual collection of the corresponding message(s). If that parameter is left empty all available messages are retrieved (according to the limit set in the parameters).

GET

availableMessages

Expand

title	Response...

Field

Details

totalMessages*

integer
example: 6
Count of messages that are ready for retrieval

messagesReadyForRetrieval*

Expand

title	...

Field	Details
messageResponse	Count integer, example: 6 sequenceNumbers integer, List 1, 18
alert*	Count integer sequenceNumbers integer
updatedPatient*	Count integer sequenceNumbers integer
ping*	Count integer sequenceNumbers integer
textMessage*	Count integer sequenceNumbers integer
genericRequest*	Count integer sequenceNumbers integer
extendedTypingRequest*	Count integer sequenceNumbers integer
typingResponse*	Count integer sequenceNumbers integer
sampleRequest*	Count integer sequenceNumbers integer
sampleInfo*	Count integer sequenceNumbers integer
sampleArrival*	Count integer sequenceNumbers integer
sampleResponse*	Count integer sequenceNumbers integer
infectiousDiseaseMarkerRequest*	Count integer sequenceNumbers integer
infectiousDiseaseMarkerResult*	Count integer sequenceNumbers integer
reservationRequest*	Count integer sequenceNumbers integer
reservationResponse*	Count integer sequenceNumbers integer
reservationRelease*	Count integer sequenceNumbers integer
requestCancellation*	Count integer sequenceNumbers integer
requestRejected*	Count integer sequenceNumbers integer
resultReminder*	Count integer sequenceNumbers integer
cordBloodUnitReportRequest*	Count integer sequenceNumbers integer
cordBloodUnitReportResponse*	Count integer sequenceNumbers integer

6.7 All Available Messages /* Proposed - not yet implemented */

This endpoint allows end users to retrieve an array of all messages that are ready to be downloaded, including their content. This would allow a registry to call just one endpoint to collect all messages.

Limitations:
This option does not work for all applications/tooling, like defining custom API connectors in the 365 PowerPlatform. In those cases the same static structure for all call responses on a specific endpoint is not only IBP, but also required.

Retrieve (Post)

availableMessagesAll

Expand

title	Request...

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

Expand

title	Response...

Field

Details

generalInformation*

Expand

title	...

Field	Details
limit*	integer default: 100
shouldPeek	boolean default: false
totalCount*	integer minimum: 0 example: 1
remainingCount*	integer minimum: 0
isSuccessful*	boolean default: true
summary*	string maxLength: 255 example: 1 message retrieved sucessully. 0 remaining messages

messages*

Expand

title	...

Field

Details

originalMessage*

oneOf:

alert
ping
textMessageRequest
genericRequest
extededTypingRequest
typingResponse
sampleRequest
sampleArrival
sampleInfo
sampleResponse
infectiousDiseaseMarker
infectiousDiseaseMarkerResult
reservationRequest
reservationResponse
reservationRelease
requestCancellation
requestRejected
resultReminder
cordBloodUnitReportRequest
cordBloodUnitReportResponse

metaInformation*

{...}

6.8 Recover Messages

To recover or "restore" a soft-deleted message, users can call to the "recoverMessages" endpoint. This endpoint allows users to bring back messages that were soft-deleted within a 72 hour timeframe.

This approach provides an additional safety measure for end users. In case a message was mistakenly deleted during the retrieval process, or if there is a need to recover soft-deleted data, this mechanism allows for data recovery without permanent loss.

Users should be aware that the functionality to restore messages is limited to 72 hours. After this window, the soft-deleted messages are permanently removed from the system. Also see: section 2.4.7 Message storage retention policies in the Technical Guidelines chapter.

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:

...

get_api_v1_TextMessageRetrieve

...

Patient
Donor
Text

...

TextMessage payload

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:

...

Alert Payload:

Level
Status
Message

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:

SendRetrieveget_api_v1_AlertUpdateRetrieveAlert 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)

POST

recoverMessages

Expand

title	Request...

Field

Details

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.

Expand

title	Response...

Field

Details

isSuccessful (200 OK)

boolean

error (400 Bad Requst)

string

example: Bad request.

Page tree

Versions Compared

Old Version 28

New Version Current

Key

6.1 Embedded

blocks

6.1.1 Embedded Meta block

6.1.2 Embedded Address block

6.1.3 Embedded Patient Block

6.1.4 Embedded Donor Block

6.1.2 Embedded Address block (NEW_ADD)

6.1.3 Embedded Patient Block

6.2 Message Response

6.1.4 Embedded Donor Block (donor in request)

6.1.5 Embedded Donor Block (donor in response)

6.1.6 Embedded general information block

6.2 Message Response

6.3 Text message [TXT_MSG]

6.4 Alert message

6.5 Alert Update message

6.6 Available Messages

6.7 All Available Messages /* Proposed - not yet implemented */

6.8 Recover Messages

6.3 Text message [TXT_MSG]

6.4 Alert message

6.5 Alert Update message

Page tree

Page History

Versions Compared

Old Version 28

New Version Current

Key

6.1 Embedded

blocks

6.1.1 Embedded Meta block

6.1.2 Embedded Address block

6.1.3 Embedded Patient Block

6.1.4 Embedded Donor Block

6.1.2 Embedded Address block (NEW_ADD)

6.1.3 Embedded Patient Block

6.2 Message Response

6.1.4 Embedded Donor Block (donor in request)

6.1.5 Embedded Donor Block (donor in response)

6.1.6 Embedded general information block

6.2 Message Response

6.3 Text message [TXT_MSG]

6.4 Alert message

6.5 Alert Update message

6.6 Available Messages

6.7 All Available Messages /* Proposed - not yet implemented */

6.8 Recover Messages

6.3 Text message [TXT_MSG]

6.4 Alert message

6.5 Alert Update message