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:
...
| metaInformation* | | Expand |
|---|
| | referenceMessageId* | string($uuid) | | deliveredAtUtc* | string($date-time) Server-supplied timestamp showing UTC time of Message delivery to receiving registry's inbox queue. | | sendingRegistry* | integer
maximum: 9999
minimum: 1000
maxLength: 4
minLength: 4
example: 56784-digit ION of the sending registry | | responseType | string Enum:
Array [ Warning] | | wmdaRemarks | One or more remarks, each in its own object
| Expand |
|---|
| | 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.
...
| 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 |
|---|
| | 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 |
|---|
| | 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: 1234ID 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: NLISO 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 | integer
nullable: true
minimum: 1
maximum: 999
example: 76 |
| sex | string
nullable: true Enum:
Array [ M, F ] |
| firstName | string
maxLength:50
nullable: true
example: JohnFirst (given name) of the patient |
| lastName | string
maxLength:50
nullable: true
example: DoeLast (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.
...
| Donor type | Details |
|---|
| donor* | | Expand |
|---|
| 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:
...
Here is the comparison of the DONOR_CB and the API endpoints: EMDIS vs API.xlsx
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 |
|---|
| | 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:
...
| Send (Post) | Retrieve (Post) |
|---|
| MessageResponseRequest | |
| Expand |
|---|
| | Field | Details |
|---|
| organisationResponse | | Expand |
|---|
| | 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 |
|---|
| | 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. |
|
|
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.
...
| Send (Post) | Retrieve (Post) |
|---|
| textMessageRequest | |
| Expand |
|---|
| | 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: 12344 digit ION of the receiving registry | | patient* | | Expand |
|---|
| | Field | Details |
|---|
| wmdaId* | integer
nullable: false
example: 1234 ID provided by the WMDA |
|
| | donor* | Embedded Donor Block (donor in request) |
|
| | Expand |
|---|
| | 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. |
|
|
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.
...
| Send | Retrieve (Post) |
|---|
| AlertRetrieve |
| Alerts can only be sent by the WMDA's central system | | Expand |
|---|
| | 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. |
|
|
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.
...
| Send | Retrieve (Post) |
|---|
| AlertUpdateRetrieve |
| Alert updates can only be sent by the WMDA's central system | | Expand |
|---|
| | 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. |
|
|
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 |
|---|
| | Field | Details |
|---|
| totalMessages* | integer
example: 6
Count of messages that are ready for retrieval
| | messagesReadyForRetrieval* | | Expand |
|---|
| | 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 |
|---|
| | Field | Details |
|---|
| limit | integer
default: 100
| | shouldPeek | boolean
default: false
Set to true if you want messages to remain available after retrieval |
|
| Expand |
|---|
| | Field | Details |
|---|
| generalInformation* | | Expand |
|---|
| | 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 |
|---|
| | 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.
...