Versions Compared

Old Version 77

changes.mady.by.user Matt Prestegaard

Saved on

compared with

New Version Current

changes.mady.by.user Alicia Venter

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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
  • What Which registry sent the information (sendersending registry)
  • What type of information is containedresponse is provided by the WMDA Match Connect system
  • /* Pending */ Any failed validations detected by the Match Connect system
  • A sequence number, so that the receiving registry knows if any message is missing. 
metaInformation*
Expand
title...
referenceMessageId*
FieldDetails
messageId
string($uuid)
sentAtUtc
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

sender

the sending registry

messageType
responseType

string

Enum:
Array [

 1 

Warning]

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

...

contactPerson

...

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

wmdaRemarks

One or more remarks, each in its own object


Expand
title...
remarkType

string 
Array [ InvalidHLA ]

descriptionstring
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.

  1. Unique reference to an institution
  2. 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...
FieldDetails
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...
FieldDetails
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:

FieldDetails
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.

emdisPatientIdstring
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{...}
dateOfBirthstring($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 ]

poolCountryCodestring
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 ]

weightinteger
nullable: true
minimum: 1
maximum: 999
example: 76
sex

string
nullable: true

Enum:
Array [ M, F ]

firstNamestring
maxLength:50
nullable: true
example: John

First (given name) of the patient

lastNamestring
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 typeDetails
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.

FieldDetails
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

abostring
nullable:true
Enum: [A, B, O, AB]
rhesusstring
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{...}
ccr5string
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...
FieldDetails
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
titleRequest...
FieldDetails
organisationResponse
Expand
title...
FieldDetails
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
titleResponse...
FieldDetails
metaInformation*Embedded Meta Block
Expand
titleRequest...
limitinteger
default: 100
shouldPeekboolean
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
titleResponse...
FieldDetails
generalInformation*Embedded General Information Block
messages*
Expand
title...
FieldDetails
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
titleRequest...
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...
FieldDetails
wmdaId*

integer
nullable: false
example: 1234

ID provided by the WMDA

donor*Embedded Donor Block (donor in request)
Expand
titleResponse...
FieldDetails
metaInformation*Embedded Meta Block
Expand
titleRequest...
limitinteger
default: 100
shouldPeekboolean
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
titleResponse...
FieldDetails
generalInformation*Embedded General Information Block
messages*
Expand
title...
FieldDetails
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:

SendRetrieve (Post)

AlertRetrieve
Alerts can only be sent by the WMDA's central system
Expand
titleRequest...
limitinteger
default: 100
shouldPeekboolean
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.

...

Not needed anymore, as the full address will be sent embedded in every request.

...

INST_ID Req 10

...

Obsolete. Accreditation is provided by S&M 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:

FieldDetails
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{...}
dateOfBirthstring($date)
nullable: true
maxLength: 10
example: 1961-05-27
diagnosis{...}
diseasePhasestring
nullable: trueEnum:
Array [ 48 ]
ethnicitystring
nullable: trueEnum:
Array [ 20 ]
poolCountryCodestring
maxLength: 2
pattern: ^[A-Z]{2}
nullable: true
example: NL

ISO 3166-1 alpha-2 Country Code (capitalized)

abostring
nullable: trueEnum:
Array [ 4 ]
rhesusstring
nullable: trueEnum:
Array [ 2 ]
weightinteger
nullable: true
minimum: 1
maximum: 999
example: 76
sexstring
nullable: trueEnum:
Array [ 2 ]
firstNamestring
maxLength: 30
nullable: true
example: John

First (given name) of the patient

lastNamestring
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:

  1. InfectiousDiseaseMarkerResultRequest (IDM_RES)
  2. TypingResponseRequest (TYP_RES)
  3. NoResultRequest (NO_RES)
  4. 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.

...

Expand
titleDonor payload...
FieldDetails
id*integer
nullable: false
example: 5176
donorRegistryIon*integer
nullable: false
minimum: 1000
maximum: 9999
example: 1234
abbreviationstring
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
donorAttributestring
maxLength: 3
nullable: true
kir{...}
weightinteger
nullable: true
minimum: 1
maximum: 999
example: 76
heightinteger
nullable: true
minimum: 1
maximum: 999
example: 161
collectionTypestring
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: 1
pregnanciesCountinteger
nullable: true
example: 2
reservedPatientIdstring
nullable: true
example: 1234222ss
statusEndDatestring($date)
maxLength: 10
nullable: true
statusReasonstring
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: 10
registry*{...}

...

Expand
titleCBU payload...
FieldDetails
id*integer
nullable: false
example: 5176
donorRegistryIon*integer
nullable: false
minimum: 1000
maximum: 9999
example: 1234
abbreviationstring
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

cordIdstring
nullable: true
maxLength: 25
example: 9991012070433202000
donorType*string
nullable: falseEnum:
Array [ 2 ]
collectionDatestring($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
attachedSegmentsCountinteger
nullable: true
minimum: 0
maximum: 99
example: 2
bankManufacturerIdWmda*integer
example: 5432
nullable: true
cbbAccreditationStatus*string
nullable: trueEnum:
Array [ 3 ]
localIdstring
example: 12345ABC
nullable: true
bagIdstring
example: ABCDE1234
nullable: true
dateOfBirth*string($date)
nullable: true
maxLength: 10
example: 1961-05-27
processingDatestring($date)
nullable: true
minLength: 10
maxLength: 10
processingMethodstring
nullable: true

HES = Hydroxy-Ethyl-Starch, DGS = Density Gradient Separation, CEN = Centrifuge, FIL = Filtration, FIC = FICOL, PER = PERCOL, OTH = Other

Enum:
Array [ 7 ]
processingMethodTypestring
nullable: trueEnum:
Array [ 5 ]
freezeDatestring($date)
nullable: true
freezeMethodstring
nullable: trueEnum:
Array [ 2 ]
reservedPatientIdstring
nullable: true
example: 1234222ss
productModificationsstring
nullable: trueEnum:
Array [ 7 ]
bagTypestring
nullable: trueEnum:
Array [ 4 ]
bagsCountinteger
minimum: 1
maximum: 99
example: 2
nullable: true
bankDistributionIdWmdainteger
nullable: true
example: 1234
bacterialCultureResultsstring
nullable: true

P = Positive N = Negative D = Not done

Enum:
Array [ 3 ]
fungalCultureResultsstring
nullable: true

P = Positive N = Negative D = Not done

Enum:
Array [ 3 ]
hemoglobinopathyScreeningStatusstring
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 ]
viabilityCellTypestring
nullable: true

type of cell tested for viability

Enum:
Array [ 3 ]
viabilityMethodstring
nullable: true

7A = 7AAD PI = Propidium Iodide TB = Trypan Blue OT = Other

Enum:
Array [ 4 ]
viabilityDatestring($date)
nullable: true
volumeFrozen*integer
example: 25
nullable: true
tncFrozenCount*number
example: 1020000000
nullable: true
cd34FrozenCount*number
example: 3700000
nullable: true
cfuFrozenCountinteger
nullable: true
minimum: 10000
maximum: 99990000

Total count of colony forming units (post processing, prior to cryopreservation)

mncFrozenCount*number
example: 430000000
nullable: true
ccr5string
nullable: trueEnum:
Array [ 3 ]
kir{...}
plasmaAliquotsCountinteger
minimum: 0
maximum: 99
nullable: true

Number of plasma aliquots available

redCellAliquotsCountinteger
minimum: 0
maximum: 99
nullable: true

Number of red cell fraction aliquots

nucleatedRbcFrozenCountinteger
minimum: 0
maximum: 9999000000
nullable: true

Total number of nucleated red blood cells (post processing, prior to cryopreservation)

serumAliquotsCountinteger
minimum: 0
maximum: 99
nullable: true
serumQuantitynumber
minimum: 0
maximum: 99.9
nullable: true
plasmaQuantitynumber
minimum: 0
maximum: 99.9
nullable: true
ctCompletionDatestring($date)
maxLength: 10
ctSampleTypestring
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 ]
dnaSamplesAvailableboolean
nullable: true
otherSamplesAvailableboolean
nullable: true
donorAttributestring
maxLength: 3
nullable: true
statusEndDatestring($date)
maxLength: 10
nullable: true
statusReasonstring
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{...}

...

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 MatchConnect.  It's structure is as follows:

FieldDetails
senderstring
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 5678

4 digit ION of sender

deliveredAtUtcstring($date-time)

Server-supplied timestamp showing time of Message delivery to recipient's inbox queue

referenceMessageIdstring($uuid)
responseTypestringEnum:
Array [ 3 ]
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:

SendRetrieveMessageResponse

MessageResponseRetrieve

Expand
titleRequest...
FieldDetailswmdaResponse Expand
title...
FieldDetailsdeliveredAtUtcstring($date-time)

Server-supplied timestamp showing time of Message delivery to recipient's inbox queue

referenceMessageIdstring($uuid)responseType

string

Enum:
Array [ 3 ]

wmdaRemark[...]

Expand
titleResponse...
FieldDetails
generalInformation*Embedded General Information Block
messages*
wmdaResponse
Expand
title...
FieldDetails
senderstring
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 5678

4 digit ION of sender

deliveredAtUtcstring($date-time)

Server-supplied timestamp showing time of Message delivery to recipient's inbox queue

referenceMessageIdstring($uuid)responseType

string

Enum:
Array [ 3 ]

wmdaRemark[...]
Expand
titleRequest...
No parameters specified
Expand
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:

titleResponse
SendRetrieve (Post)

AlertUpdateRetrieve
Alert updates can only be sent by the WMDA's central system
Expand
titleRequest...
limitinteger
default: 100
shouldPeekboolean
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
titleResponse...
FieldDetails
generalInformation*Embedded General Information Block
messages*
Expand
title
Expandtitle
...
FieldDetails
originalMessage
*

...

FieldDetailswmdaResponse...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:


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
titleResponse
SendRetrieveTextMessageRequest

TextMessageRetrieve

ExpandtitleRequest
...
FieldDetails
payload
totalMessages*integer
example: 6
Count of messages that are ready for retrieval
messagesReadyForRetrieval*
Expand
title..
.
FieldDetails
patientEmbedded Patient Block
donorEmbedded Donor Block
textstring
nullable: true

Text. Note that text over 1200 characters will be truncated if recipient is EMDIS

sentDatestring($date-time)
nullable: true

Date sent SENT_DATE Opt 8

recipient*string
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 1234

4 digit ION of recipient

correlationGuid*string($uuid)

Sender generated GUID used to correlate response acknowledgement

Expand
titleResponse...
FieldDetailswmdaResponse Expand
title...
FieldDetailssenderstring
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 5678

4 digit ION of sender

deliveredAtUtcstring($date-time)

Server-supplied timestamp showing time of Message delivery to recipient's inbox queue

referenceMessageIdstring($uuid)responseTypestringEnum:
Array [ 3 ]wmdaRemark[...]
Expand
titleRequest...
No parameters specified
Expand
titleResponse...
FieldDetails
sender*string
maxLength: 4
minLength: 4
example: 5678

4 digit ION of sender

sentAtUtc*string($date-time)

Server-supplied timestamp showing UTC time sender posted (i.e. sent) MessageRequest.

deliveredAtUtc*string($date-time)

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

payload*{...}
recipient*string
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 1234

4 digit ION of recipient

correlationGuid*string($uuid)

Sender generated GUID used to correlate response acknowledgement

messageTypestring

Message types supported by WmdaConnect

Enum:
Array [ 21 ]

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:

.
FieldDetails
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.

SendRetrieveAlertRetrieveAlerts can only be sent by the WMDA's central system
Expand
titleRequest...
No parameters specified
ExpandtitleResponse
Retrieve (Post)
availableMessagesAll
Expand
titleRequest...
FieldDetails
limitinteger
default: 100
shouldPeekboolean
default: false

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

Expand
titleResponse...
FieldDetails
generalInformation*
Expand
title...
FieldDetails
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
...
FieldDetails
level
originalMessage*
string

alert level. enums may change

Enum:
Array [ 3 ]statusstring

check later

Enum:
Array [ 2 ]messagestring
maxLength: 1024
example: WMDA will do maintenance on SMC system on the weekend of 10 marchmetaInformationEmbedded 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:

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.

POST
recoverMessages
Expand
titleRequest
SendRetrieveAlertUpdateRetrieveAlert updates can only be sent by the WMDA's central system
Expand
titleRequest...
No parameters specified
ExpandtitleResponse
...
FieldDetails
alertReferenceIdentifierstring($uuid)levelstring

alert level. enums may change

Enum:
Array [ 3 ]statusstring

check later

Enum:
Array [ 2 ]messagestring
maxLength: 1024
example: WMDA will do maintenance on SMC system on the weekend of 10 marchmetaInformationEmbedded Meta Block
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
titleResponse...
FieldDetails
isSuccessful (200 OK)boolean
error (400 Bad Requst)

string

example: Bad request.