
The additional meta-information "blocks" are added to ensure the receiving registry is aware of:
- A timestamp
- Which registry sent the information (sending registry)
- What type of response is provided by the WMDA Match Connect system
Field | Details |
---|
referenceMessageId* | string($uuid) |
deliveredAtUtc* | string($date-time) Server-supplied timestamp showing UTC time of Message delivery to receiving registry's inbox queue. |
| integer maximum: 9999 minimum: 0 maxLength: 4 minLength: 4 example: 56784-digit ION of the sending registry |
responseType | string Enum: Array [ Warning] |
wmdaRemarks |
Field | Details |
---|
remarkType | string | 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 the type of message just sent by calling this endpoint |
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.
- The contactPerson is required if the INST_TYPE is ”LAB”.
- The organisationId (formerly known as ) of an institution should remain stable over time and should not be assigned to different institutions.
In the Match-Connect system, the addresses will be embedded in the donor requests. See Chapter Requests for details.
Message structure:
Send | Retrieve |
---|
addressRequest | |
Field | Details |
---|
organisationId* | string nullable: false maxLength: 10 minLength: 3 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 hub code + local address id.
- The hub code usually is the two-character ISO country code of the registry (e.g. NL for Netherlands)
- In the case of multiple registries in one country, a replacement code will be assigned.
- Should be provided as a user-friendly (displayable) id for use on screens and on documentation.
| line1* | string nullable: false maxLength: 60 Address line 1 | line2 | string nullable: true maxLength: 60 Address line 2 | line3 | string nullable: true maxLength: 60 Address line 3 | postalCode* | string nullable: false maxLength: 10 | city* | string nullable: false maxLength: 40 | country* | string nullable: false minLength: 2 maxLength: 2 2 character ISO country code ( ISO 3166-1 alpha-2) | type* | string nullable: false minLength: 3 maxLength: 3 HUB = EMDIS Hub DON = Donor center TRA = Transplant center HAR = Harvesting center LAB = Typing laboratory FIN = Financial institution CBB = Cord Blood Bank | contactPerson | string nullable: true maxLength: 40 Contact person. Required if type = LAB. | phone* | string nullable: false maxLength: 20 | fax | string nullable: true maxLength: 20 | email | string nullable: true maxLength: 60 | receivingRegistry* | string maximum: 9999 minimum: 0 maxLength: 4 minLength: 4 example: 12344 digit ION of the receiving registry |
|
| limit | integer default: 100
| shouldPeek | boolean default: false
Set to true if you want messages to remain available after retrieval |
|
|
Field | Details |
---|
wmdaId* | integer nullable: false example: 1234ID provided by the WMDA |
patientId* | string maxLength: 17 nullable: false example: XY1234P. |
hla* | {...} |
idm | {...} |
dateOfBirth | string($date) nullable: true maxLength: 10 example: 1961-05-27 |
diagnosis | {...} |
diseasePhase | string nullable: true Enum: Array [ 48 ] |
ethnicity | string nullable: true Enum: Array [ 20 ] |
poolCountryCode | string maxLength: 2 pattern: ^[A-Z]{2} nullable: true example: NLISO 3166-1 alpha-2 Country Code (capitalized) |
abo | string nullable: true Enum: Array [ 4 ] |
rhesus | string nullable: true Enum: Array [ 2 ] |
weight | integer nullable: true minimum: 1 maximum: 999 example: 76 |
sex | string nullable: true Enum: Array [ 2 ] |
firstName | string maxLength: 30 nullable: true example: JohnFirst (given name) of the patient |
lastName | string maxLength: 30 nullable: true example: DoeLast (family name) of the patient |
6.1.4 Embedded Donor Block
In EMDIS, the following messages are linked to the donor updates:
- IDM_RES
- TYP_RES
- NO_RES
- RSV_RES
These four will be replaced with the Match-Connect API endpoints that have the donor details embedded in the message. Respective endpoints of IDM_RES and TYP_RES will deliver new IDM and new typing details, and all the mentioned endpoints will also inform the patient registry of the new donor status.
These donor updates are for the receiving registry (patient registry) only and will not be updated in the central HUB. So the sending (donor) registry is responsible for sending a DIFF upload to the S&M system in parallel to keep information in sync.
Donor type | Details |
---|
| grid* | string nullable: true maxLength: 19 minLength: 19 example: 9991012070433202000 |
|
|
CBU | cordId* | string maxLength: 17 example: CB1234567
CBU Identification2 (formerly CB_ID) |
|
|
ADCU | adcuIdid* | string minLength: 13 maxLength: 13 example: A99991412345612N
N/A in EMDIS, available in the future |
|
|
Here is the comparison of the DONOR_CB and the API endpoints: EMDIS vs API.xlsx
6.1.5 Embedded WMDA Response block
The WMDA will provide a standard response to request messages sent to Match-Connect. Its structure is as follows:
Field | Details |
---|
deliveredAtUtc* | string($date-time) Server-supplied timestamp showing time of Message delivery to receiving registry's inbox queue |
referenceMessageId* | string($uuid) |
responseType* | stringEnum: Array [ Success, Warning, Failed]
messages can be failed, if the message has a structure or information that prevent delivery to the receiving registry. This could be incorrect JSON structure and non-existent ION or because the receiving registry does not allow messages from your registry. |
receivingRegistryMessageSequenceNumber | 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. |
wmdaRemarks | [...] |
6.1.6 Embedded 'generalInformation' Response block
The WMDA will provide a standard response to retrieve messages sent to Match-Connect. Its structure is as follows:
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 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) |
---|
| |
Field | Details |
---|
organisationResponse | Field | Details |
---|
retrievedAtUtc* | string($date-time) Server-supplied timestamp showing time of Message retrieval and storage in organisation's own systems | referenceMessageId* | string($uuid) | responseType* | string Enum: Array [ 3 ] | remark | string
|
|
|
|
| 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 []
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 | |
Field | Details |
---|
requestingRegistryReferenceCode | string maxLength: 15 example: XX12345
| text* | string nullable: true Text. Message for a human at receiving registry. | * | string maximum: 9999 minimum: 0 maxLength: 4 minLength: 4 example: 12344 digit ION of the receiving registry | patient* | Patient ID | donor* | Donor ID |
|
| 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
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 | 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. |
|
Field | Details |
---|
generalInformation* | Embedded General Information Block | originalMessage* | Field | Details |
---|
level | string alert level. enums may change Enum: Array [ 3 ] | status | string check later Enum: Array [ 2 ] | messageText | string maxLength: 1024 example: WMDA will do maintenance on SMC system on the weekend of 10 march |
|
| metaInformation* | Embedded Meta Block |
|
|
6.5 Alert Update message
The Alert Update message is used to broadcast an update about some previous alert. Messages are generated centrally by WMDA. Members are expected to display them to the users.
Message structure:
Send | Retrieve (Post) |
---|
| AlertUpdateRetrieve |
Alert updates can only be sent by the WMDA's central system | 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. |
|
Field | Details |
---|
generalInformation* | Embedded General Information Block | originalMessage* | Field | Details |
---|
alertReferenceIdentifier | string($uuid) | level | string alert level. enums may change Enum: Array [ 3 ] | status | string check later Enum: Array [ 2 ] | message | string maxLength: 1024 example: WMDA will do maintenance on SMC system on the weekend of 10 march |
|
| metaInformation | Embedded Meta Block |
|
|
6.6 Available Messages
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 |
Field | Details |
---|
totalMessages* | integer example: 6 Count of messages that are ready for retrieval
| messagesReadyForRetrieval* | 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.
GET |
availableMessagesAll |
Field | Details |
---|
generalInformation* | 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* | 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* | {...} |
|
|
|
|