General considerations

• A patient registration Embedded Patient Block is sent together with each request. This block contains both the wmdaId and the patientId of the patient.

• Next to the actual request information, whenever institutions are needed, they are sent explicitly as an Embedded Address Block.

• The requested donor has to be reserved at the remote hub and reported back to the requesting registry by an Embedded Donor Block within a Reservation Response reflecting the changed donor status  (cf. DONOR_CB with D_STATUS = ”RS”).

• All changes in the donors (change of status, updated typing, or IDMs) resulting from the requests are reported back in an Embedded Donor Block within the respective message, e.g. updated HLA information resulting from an Extended Typing Request in an Extended Typing Results. A separate update must be made to the Search & Match system with the updated donor data to ensure an up-to-date master data. More information on how to do so may be found here.
• Reference Code: In EMDIS, there was a REF_CODE field to reference result messages to the same request, e.g. Sample Request and its results. In Match-Connect, all the request-related messages responding to the original request must have a referenceMessageId as part of the message.

  • The message ID (referenceMessageId) of the request message is used as a reference code for the rest of the request-related message flow.

  • Next to the technical referenceMessageId requests, a human-readable reference code (requestId) is used for end-user recognition (communication outside of the automated system).
    • The requestId is optional.
      
    • The requestId is part of the original message block.
      
    • The requestId will be generated by the sending registry.
    • The requestId will only be used for human-to-human communication (e.g. could be used on printed invoices).
• Most fields inherited from EMDIS Semantics contain comments describing their purposes in EMDIS and the original names to assist in the transition from EMDIS to Match-Connect.
• Paragraph Request + Response Flows depicts the new message flows.
• In the Semantics tables describing message structures, `{...}` indicates that an object contains additional nested fields that are not listed. For full field details, see the Swagger specification.
  
• General usage of messages:

  • PR -> DR Message sent by the Patient Registry (PR) to the Donor Registry (DR).

  • DR -> PR Message sent by the Donor Registry (DR) to the Patient Registry (PR).

  • PR <-> DR Message that can be sent by either registry to the other, depending on the situation.

5.1 - Extended Typing Request (TYP_REQ)

Usage: PR -> DR

This message is used to request an extended typing of a donor (adult, adcu, cbu). It primarily contains information about what to type and for which donor.
The expected return messages are Reservation Response, Extended Typing Results (donor or cbu) and/or Request Rejection.

Rules:

• Intermediate resolution (M) translates to non-high resolution.
• Combinations are possible, i.e. several loci may be requested in one message.

The institutionPaying block must provide the necessary details for the donor registry to send an invoice for the service. In EMDIS, this used to be the address of the financial institution.

The appropriate action if the typing request cannot be accepted or has to be changed by the receiving registry, e.g., due to national rules, is to inform the requesting side what was done. If only the resolution was changed (the sending registry will receive something different than ordered - either more or less) or only a part of the requested loci were accepted (the sending registry will only receive parts of what was ordered): send a message response containing the warning.

5.2 - Extended Typing Results (TYP_RES)

Usage: DR -> PR

This message is used to send the results of the Extended Typing Request back to the requesting registry.  Different endpoints have been implemented according to source type (e.g. donor, cbu).

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.

5.2.1 - Extended Typing Results Donor (TYP_RES for donors)

5.2.2 - Extended Typing Results CBU (TYP_RES for CBUs) (new message, to be implemented in v2.2)

5.3 - Sample Request (SMP_REQ)

Usage: PR -> DR

This message is used to request a sample to be used for verification typing in the lab of the sending registry.

The expected return messages are Reservation Response, Sample Arrival Date, Sample Information, IDM Results, and/or Request Rejection.

Rules:

• The fields earliestDateCanReceive and latestDateCanReceive represent the lower and upper limit of the period of time in which the blood sample has to be received. If the second date is missing, the sample may be received any time after the first date.
• The quantity for the first product is optional when requesting DNA from a cord blood unit. In all other requests, the quantity fields for any of the corresponding product fields are required if a product is requested.
• A number of tubes requested in a sample request or marrow request:
  • The maximum amount of material, requested in one sample request or pre-collection sample request is 100 ml, if not stated otherwise in the national rules of the donor registry.
  • If the number of tubes is unassigned, and not given in the request, the default value number of tubes is one.
• A typical response to the Sample Request message is the Sample Arrival Date message. In addition to that, it is mandatory (by the accreditation standards) that the donor registry also sends an IDM Result message to inform the patient registry of the known diseases of the donor.

5.4 - Sample Information (SMP_INFO)

Usage: DR -> PR

This message is used to send relevant secondary information that may arise in the context of the sample request.

Rules:

• The message can only be exchanged in one direction: from the donor side to the patient side.
• Sample information is always referencing a sample request.
• Sample information is only valid as long as the referenced sample request is considered ”open” and the donor is reserved for this patient after the sample request.
• A request is considered ”open” as long as the patient registry has neither reported the sample testing results nor a Request Rejected message nor a request cancellation.
• There might be several sample information messages within the context of one sample request. Subsequent sample information is regarded as new or additional information and not as updates.

5.5 - Sample Arrival (SMP_ARR)

Usage: DR -> PR

This message is used to transmit the proposed date of the sample arrival.

5.6 - Sample Response (SMP_RES)

Usage: PR -> DR

This message is used to transmit the results of the sample testing.

Rules:

• donorStillOfInterest = ”N” means: the donor can be released immediately.
• donorStillOfInterest = ”Y” means:  please prolong donor reservation according to your national rules.
• The fields for the infectious disease markers are included in this message to give the transplant centers the possibility to report the results of IDMs they might have tested.
• If Sample Results cannot be sent, a Request Rejection message should be sent with the reason field populated to explain why.
• 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.

Note: To release a donor after a sample result with donorStillOfInterest = 'Yes' has been issued, the  Reservation Release message should be used.

5.7 - Infectious Disease Marker Request (IDM_REQ)

Usage: PR -> DR

This message is used to request i nfectious disease marker test results of the selected donor.

The expected return messages are  Reservation Response, IDM Results, and/or Request Rejection.

Rules:

• Several distinct requests for the same patient/donor pair at a time are possible, for example, a verification typing and a CMV status. But each request must be answered by an individual IDM Results message, i.e. results must not be ”concatenated” to a single result message. Multiple IDM requests for the same patient/donor pair have to be disjoint (i.e. may not contain identical markers). The occurrence of multiple requests should be an exception. Normally, all markers required should be requested within one message.

5.8 - Infectious Disease Marker Results (IDM_RES)

Usage: DR -> PR

This message is used to send the results of the IDM request back to the requesting registry. 

Rules:

• The common use of the IDM Results message is in response to the Sample Request message, in addition to the shipment of the donor blood sample. Please note there may be a charge involved with this service. If a fee is charged, it may come as a separate item or might be included in the price of the sample shipment. Such IDM Results messages can be sent via a regular EMDIS message - the remote hub must be able to handle it appropriately. The IDM Results must have the same referenceMessageId as the Sample Request message.
• IDM Results message can be generated in response to two different message requests:
  • Sample Request does not specify what set of infectious disease markers to be tested
  • IDM Request does specify what set of infectious disease markers to be tested
• The field marker is a required field.
• For those hubs reporting infectious disease markers during verification typing, the marker field should contain the IDMs actually tested. There is a fixed-length binary field for the IDM Results message. The blood group may also be reported.
• IDM results can also be reported as a part of the Sample Results message by the hub (transplant center) that requested the blood sample. This is to give the transplant centers the possibility to report the results of IDMs they might have tested.

5.8.1 - Infectious Disease Marker Results (IDM_RES for donors)

5.8.2 - Infectious Disease Marker Results CBU (IDM_RES for CBUs) (new message, to be implemented in v2.2)

5.9 - Reservation Request (RSV_REQ)

Usage: PR -> DR

This message is used to request the reservation of a donor for a specific patient for a upcoming transplantation at the receiving registry. The patient registry can ask for a specific reservation period by making use of the optional field expirationDate.

The expected return message is  Reservation Response .

5.10 - Reservation Response (RSV_RES)

Usage: DR -> PR

This message informs the requesting patient registry if the donor registry has confirmed the Reservation Request OR if the donor reservation was performed after another request.

The donor registry reports back the expirationDate. This might differ from the expirationDate of the Reservation Request message due to local rules or regulations at the donor registry side. The expirationDate in the Reservation Response reflects the "true" reservation period.

If the donor is unavailable, the Reservation Request has to be answered with a Request Rejection (NO_RES).

The reservationResponse message contains a field called: "confirmed". This field confirms either the willingness of the requested donor to further proceed with the respective request (refreshed by direct contact) or the ability of the registry to fulfil the request, e.g. extendedTypingRequest, by making use of a stored sample.

• a first reservationResponse has to be sent immediately and automatically after processing the incoming request reflecting the reservation of the requested donor. This message not only reflects the successful reservation but also allows to specify the expirationDate of the reservation, that might differ from registry to registry. In this immediate response the field "confirmed" could be TRUE if the request can be processed by making e.g. use a stored sample, otherwise it must be set to FALSE.
• a follow-up reservationResponse can be sent:
  • after the requested donor confirmed willingness to proceed with the request. In which case "confirmed" has to be set to TRUE.
  • if the expirationDate was changed (e.g. extended)

Rules:

• Reservation soft fail: The API will soft fail with HTTP 200. The message will be sent and is retrievable including a warning.

  • If response.confirmed  is true , then donor.status  must be RS  (reserved). If donor.status  has any other value when confirming the reservation, a soft fail occurs.

5.10.1 - Reservation Response (RSV_RES for donors)

5.10.2 - Reservation Response CBU (RSV_RES for CBUs) (new message, to be implemented in v2.2)

5.11 - Reservation Release Request (new message)

Usage: PR -> DR

The patient registry sends this message to inform the donor registry that a donor can be released from the reservation when it is no longer needed (e.g. patient is deceased or was transplanted with another donor). This should be used if a request has been completed but the associated donors reservation is still running. If a request is still running (no results have been provided by the donor registry yet), then a Request Cancellation message should be used instead to cancel the request and release the donor at the same time. 

Additionally the Reservation Release Request can also be sent following a reservation request if the resulting reservation is no longer required and the donor is to be released.

If an reservation release message is sent while the request is still ongoing it has to be denied.

Use case: a Typing Request was sent → the donor was reserved for the patient → the request was completed, so it cannot be cancelled anymore → the donor remains reserved till the expiration date → the patient registry must send the Reservation Release Request, if the donor is not needed to the patient anymore, even if some registry systems assume that.

This is a change with respect to the current procedure and should be handled as such, as it has implications for local systems.

There is no response to this message except for the automated acknowledgement.

The referenceMessageId must be taken from the request that caused the donor reservation.

Note: The Reservation Release should not be issued if the donor is still needed for the patient (for example, if the donor VT release period has completed, the release message should not be issued if the donor is still reserved in another request or work-up).

5.12 - Workup Request (new message, not implemented yet)

Future Phase

5.13 - Workup Status (new message, not implemented yet)

Future Phase

5.14 - Request Cancellation (REQ_CAN)

Usage: PR -> DR

This message is used to cancel a request that has been sent to the donor registry. The cancellation request must have a preceding request that is being canceled (referenced by the referenceMessageId).

5.15 - Cancellation Confirmation (new message, to be implemented in v2.1)

Usage: DR -> PR

This message is sent by the Donor Registry in response to a Request Cancellation (REQ_CAN) to confirm or decline the cancellation.

5.16 - Request Rejection (NO_RES)

Usage: PR -> DR

Sent by the Patient Registry to notify the Donor Registry that a previously sent request cannot be fulfilled. The request must be referenced by the field referenceMessageId.

5.17 - Request Rejection (NO_RES_DR) (new message, to be implemented in v2.1)

Usage: DR -> PR

Sent by the Donor Registry to notify the Patient Registry that the request cannot be fulfilled (service cannot be provided). The request must be referenced by the field referenceMessageId.

Note: For Reservation Requests, if a donor cannot be reserved, Reservation Response with confirmed = ‘No’ should be issued and not Request Rejection.

5.18 - Result Reminder (RES_REM)

Usage: PR <-> DR 

This message is sent by the requesting registry to remind the receiving registry of an outstanding result from a previous request. The request must be referenced by the field referenceMessageId.

5.19 - Generic Request (new message)

Usage: PR -> DR

This message is used for registering a patient (by the embedded patient block).

This may be required, for example, for direct WU requests until 5.12 is available, or to reactivate a closed patient case on the receiving registry side.

5.20 - Upload and Download attachment

The sending registry uploads a file to the WMDA blob storage using the uploadAttachment endpoint and specifies the receiving registry. Once uploaded, the API returns attachmentGuid, which is then shared with the receiving registry to download the file using the downloadAttachment endpoint.

Rules:

• After a successful upload, an attachmentGuid is returned in the response.

• Uploaded file is stored in the WMDA blob storage for a maximum of 90 days after upload. 
• If it was not downloaded up after 90 days, it will be automatically deleted and must be uploaded again, if still needed to be sent.
• After the first successful download, the document can be downloaded multiple times within the next 72 hours. Once this period expires, the document is deleted from WMDA storage and must be requested again if needed.

• The attachmentGuid  must be shared with the receiving registry through endpoints that include an Embedded Attachment block.

• The receiving registry uses the downloadAttachment endpoint to download the file from blob storage.

• Only one file can be uploaded or downloaded at a time.

• Each file must be uploaded separately using the uploadAttachment endpoint.

• Each uploaded file can be linked to only one receiving registry.

• If a file needs to be shared with another registry, it must be uploaded again specifically for that registry.

• Maximum file size: 10 MB.

• Supported file format: PDF only.

5.21 - Cord Blood Unit Report Request (CBR_REQ) (new message, to be implemented in v2.2)

Usage: PR -> DR

This message is used to request a cord blood unit report.

5.22 - Cord Blood Unit Report Response (CBR_RES) (new message, to be implemented in v2.2)

Usage: DR -> PR

This message is used to respond to a Cord Blood Unit Report Request.

The message may include an Embedded Attachment block containing the attachmentGuid of the Cord Blood Unit Report.

5.23 - Request + Response Flows

Please note that for the above request flows textMessage and documentExchange messages could be send as optional messages in both directions PR→ DR as well as DR→ PR. They are not displayed above for better readability. For more details about how to include a documentExchange messages please see example below.

Technical process flow for sending and receiving requests and -responses to and from Match-Connect

Document exchange

how to include an attachment exchange in a workflow

e.g. generic request:

Technical process for sending and receiving attachments during a request via Match-Connect