6.1 Embedded blocks 

6.1.1 Embedded Meta Information block

The additional meta-information "blocks" are added to the response to a submitted request and to the retrieved message to ensure that both registries are aware of:

• Assigned message identifier.
• A timestamp.
• Which registry sent the information (sending registry).
• What type of response is provided by the WMDA Match Connect system.
• Any failed validations detected by the Match Connect system.
• A sequence number, so that the receiving registry knows if any message is missing. 
• A message type.

6.1.2 Embedded 'generalInformation' Response block

In addition to the meta block, WMDA will provide a standard response to each retrieve-type message sent to Match-Connect.  Its structure is as follows:

6.1.3 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.
• The contactPerson is required if the INST_TYPE is ”LAB”.

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

Message structure:

...

Example of a request with institutionPaying object: see TYP_REQ message.

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

Note: in Connect API the following fields (firstName, lastName, dateOfBirth, diagnosis, sex) are optional compared to EMDIS.

...

ID provided by the WMDA

...

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.

Rules:

• HLA soft fail: The API will soft fail with HTTP 200. The message will be sent and is retrievable including a warning
  • When providing hla values (dna or serology), field1 should be provided whenever field2 is present. If only field2 is provided without the corresponding field1, a soft fail occurs.
  • When providing drb3 , drb4 , or drb5 , the combination of these loci can have a maximum of two typing fields. If more values are provided, a soft fail occurs.
• HLA hard fail: the API will hard fail with HTTP 400. For required hla loci (a, b , drb1), either dna  or serology  must be provided. If neither is provided, a hard fail occurs.

6.1.5 Embedded Donor Block (donor in request)

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

6.1.6 Embedded Adult

...

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.

...

string
Array [ 48 ]

...

string
Array [ 21 ]

...

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

...

string
Array [ 4 ]

...

string
Array [ 2 ]

...

string
Array [ 2 ]

...

First (given name) of the patient

...

Last (family name) of the patient

...

string

gl-string like format containing the MIC-A or MIC-B typing

6.1.5 Embedded Donor Block (donor in request)

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

6.1.6 Embedded Adult Donor Block (donor in response)

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

• TYP_RES
• IDM_RES
• NO_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:

• extendedTypingDonorResponseRequest
• infectiousDiseaseMarkerDonorResponseRequest
• requestRejectedRequest

These donor updates are for the receiving registry (patient registry) only. 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 Block (donor in response)

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

• TYP_RES
• IDM_RES
• NO_RES

These three will be replaced with the Match-Connect API endpoints that have the CBU 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 CBU donor status.

The corresponding endpoints in Match-Connect are:

• extendedTypingCbuResponseRequestextendedTypingDonorResponseRequest
• infectiousDiseaseMarkerCbuResponseRequestinfectiousDiseaseMarkerDonorResponseRequest
• requestRejectedRequest

These CBU donor updates are for the receiving registry (patient registry) only. So the sending (donor) registry is responsible for sending a DIFF upload to the Search S& Match M system in parallel to keep information in sync.

...

6.1.8 Embedded Attachment block

The embedded attachment block provides all the information needed by the receiving registry to download the attachments stored at MC. The block can be part of a request message or the explicit Document Exchange message. 

The embedded attachment block allows for multiple files to be sent simultaneously, with a limit of 10 different documents. Only PDFs are permitted to be sent. The size limit of each message is 10 MB. The respective AttachmentGuids must be retrieved from WMDA by the sending registry

beforehand, during the upload process of the document(s).

Its structure is as follows:

...

string Enum: TBD

Describes the purpose of the attachment/file

...

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 must use the referenceMessageId of the original message as the Reference ID in its structure.

Message structure:

...

...

...

...

...

Server-supplied timestamp showing time of Message retrieval and storage in organisation's own systems

...

string

Enum:
Array [ 3 ]

Rules:

• HLA soft fail: The API will soft fail with HTTP 200. The message will be sent and is retrievable including a warning
  • When providing hla values (dna or serology), field1 should be provided whenever field2 is present. If only field2 is provided without the corresponding field1, a soft fail occurs.
  • When providing drb3 , drb4 , or drb5 , the combination of these loci can have a maximum of two typing fields. If more values are provided, a soft fail occurs.
• HLA hard fail: the API will hard fail with HTTP 400. For required hla loci (a, b , drb1), either dna  or serology  must be provided. If neither is provided, a hard fail occurs.

6.1.7 Embedded CBU Block (in response)

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

• TYP_RES
• IDM_RES
• NO_RES

These three will be replaced with the Match-Connect API endpoints that have the CBU 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 CBU status.

The corresponding endpoints in Match-Connect are:

• extendedTypingCbuResponseRequest
• infectiousDiseaseMarkerCbuResponseRequest
• requestRejectedRequest

These CBU updates are for the receiving registry (patient registry) only. So the sending (donor) registry is responsible for sending a DIFF upload to the Search & Match system in parallel to keep information in sync.

6.1.8 Embedded Attachment block

The Embedded Attachment block is used to exchange references (attachmentGuid) of attachments between registries. It contains all the information required by the receiving registry to download files stored in the WMDA blob storage.

Rules

• Each message can include up to 10 Embedded Attachment Blocks.

• Each block represents a single attachment and contains three mandatory fields:

  • attachmentGuid  - the unique identifier of the uploaded file.

  • attachmentDescription - type of the file.

  • fileName - name of the file.

• The receiving registry downloads each file separately using the Download Attachment endpoint

• The block can be part of a request message or the explicit Document Exchange message. The following endpoints contain Embedded Attachment block:

• • textMessage (TXT_MSG)
  • GenericRequest
  • extendedTypingRequest (TYP_REQ)
  • extendedTypingResponse (TYP_RES)
  • sampleRequest (SMP_REQ)
  • sampleResponse (SMP_RES)
  • sampleInfo (SMP_INFO)
  • sampleArrival (SMP_ARR)
  • infectiousDiseaseMarkerRequest (IDM_REQ)
  • infectiousDiseaseMarkerResult (IDM_RES)
  • reservationRequest (RSV_REQ)
  • reservationResponse (RSV_RES)
  • reservationRelease
  • requestCancellation (REQ_CAN)
  • requestRejection (NO_RES)
  • resultReminder (RES_REM)
  • cordBloodUnitReportResponse (CRB_RES)

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 must use the referenceMessageId of the original message as the Reference ID in its structure.

...

string

...

...

6.3 Instruments

6.3.1 Text message [TXT_MSG]

The TXT_MSG is useful for conveying notes or comments about a particular donor, patient/donor pair, or request. To reflect this, the text message must contain a 'donor in request' block that can be supported by a patient and or referenceMessageId.

Note: Since Warnings are going to be automated, we must keep Text Messages as the only means for user communication.

Message structure:

6.3

...

Instruments

6.3.1 Text message [TXT_MSG]

Usage:

The TXT_MSG is useful for conveying notes or comments about a particular donor, patient/donor pair, or request. To reflect this, the text message must contain a 'donor in request' block that can be supported by a patient and or referenceMessageId.

Note: Since Warnings are going to be automated, we must keep Text Messages as the only means for user communicationThe uploadAttachment endpoint is used to store a document in the WMDA blob storage for later retrieval of that document by the receiving registry via the downloadAttachment endpoint. Both API calls are between a registry and WMDA. For the document exchange between the registries, we use the API endpoints: genericDocumentExchangeRequestRequest and genericDocumentExchangeRequestRetrieve.
A document is stored in the WMDA storage for a maximum of 90 days after upload. If it was not picked up after 90 days, it will be automatically deleted and must be uploaded again, if still needed to be sent. Once picked up, it can be re-retrieved via the recoverMessage capability within a maximum of 72 hours. After that, the document must be resent if needed.

6.3.6 - Document Exchange (new message)

This message is used to send the information that a document is available at the WMDA blob storage for the receiver. The document can be connected to a patient, a donor, or a request.

6.3.2 - Upload and download attachment

The uploadAttachment endpoint is used to store a document in the WMDA blob storage for later retrieval of that document by the receiving registry via the downloadAttachment endpoint. Both API calls are between a registry and WMDA. For the document exchange between the registries, we use the API endpoints: genericDocumentExchangeRequestRequest and genericDocumentExchangeRequestRetrieve.
A document is stored in the WMDA storage for a maximum of 90 days after upload. If it was not picked up after 90 days, it will be automatically deleted and must be uploaded again, if still needed to be sent. Once picked up, it can be re-retrieved via the recoverMessage capability within a maximum of 72 hours. After that, the document must be resent if needed.

...

6.4 Alert message (new message, to be implemented in v2.1)

The Alert message is used to broadcast some important information about the system, like a planned service outage. Messages are generated centrally by WMDA. Members are expected to display them to the users.

Message structure:

6.5 Alert Update message (new message, to be implemented in v2.1)

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:

6.6 Available Messages

6.6.1 Available Messages

This endpoint allows end users to retrieve an overview of all messages 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", which allows for an individual 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). 

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

This endpoint allows end users to retrieve an array of all messages 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. 

6.7 Recover Messages

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

...