Page History

...

• • avoid peer-to-peer problem
  • least effort needed on registry side
  • receiver can re-request "missing" message
    • can be automated, no help needed by WMDA staff

2.4.2

...

Message collection - general flow

Messages can be collected via individual API calls against the different "retrieve" APIs." API endpoints, which can be described as a "pull model".

The pull model is described in the following steps:

1. Retrieving an overview of all messages that are ready for retrieval by the receiving registryIt is left for the retrieving registry to choose how to collect the messages, by picking one of the following scenarios:

• Using the endpoint:  availableMessages - Retrieve an array with an overview of all the messages that are ready to be downloadedfor retrieval, including sequence numbers
  
  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 an optional parameter "sequenceNumber", that 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). 
  
  
• Using the endpoint:  availableMessagesAll - Retrieve an array of all the messages that are ready to be downloadedfor retrieval, including message content (OPTIONAL, MAY NOT BE 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 one single 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 implementing best practices (IBP), but also required. In those cases the same static structure for all call responses on a specific endpoint is not only implementing best practices (IBP), but also required.
  
  

2. Pulling available messages from corresponding "retrieve" endpoints

After identifying which specific message(s) should be retrieved by using the availableMessages endpoint, the messages can be retrieved from the "retrieve" endpoints that correspond to their message type. In the request body, users can specify parameters such as the limit (number of messages to retrieve), "shouldPeek" and sequenceNumber.

The API for the specified message type for a "retrieve" endpoint responds to the retrieval request with the requested messages. Users can then process and display these messages in their application based on their type and content.

This pull model allows users to have control over the messages they retrieve, specifying limits and retrieving messages from a particular point in the sequence using "sequenceNumber"

3. Messages are (soft)deleted after retrieval

After retrieval messages are soft-deleted. This means that after retrieval, messages are marked as deleted for the end-user and longer available in the "availableMessages" and their corresponding "Retrieve" endpoint. 

After soft-deletion, the system marks the messages as deleted for the end user, but messages will be stored for an additional temporary period of 72 hours. During this timeframe, the data is still restorable. 

4. Restoring messages using the "recoverMessages" endpoint

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 the 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: Chapter 2.4.7 Message storage retention policies.

2.4.3 "shouldPeek" function

The "shouldPeek" function, which is specified as a parameter for every "Retrieve" endpoint, allows users to preview messages without marking them as retrieved or soft-deleted. It serves as a testing utility to inspect messages without altering their status within the system.

This function is valuable for debugging and ensuring the proper functionality of the message retrieval process.

It is crucial to emphasize that the "shouldPeek" function should only be used for testing purposes to ensure proper functioning of the intended message-flow.

2.4.

...

4 RESTful best practices

In the development of Match Connect, we have adhered to RESTful best practices to ensure optimal performance and maintainability. 

...

• Using 'POST' instead of 'GET' for message retrieval
  
  A 'POST' API call for retrieval of messages aligns with HTTP semantics, especially considering the nature of Match Connect. In line with HTTP semantics and RESTful best practices, 'GET' requests should per definition be cacheable. In Match Connect message retrieval triggers a mutation, because messages are no longer available after retrieval. Therefore, the information in Match Connect is non-cacheable. 
  
  The 'POST' method better reflects the intention of performing a server-side operation and helps avoid unintended caching of mutable operations, enhancing the overall robustness and correctness of Match Connect.
  
  Additional information about RESTful best practices can be found here.
  Additional information about HTTP semantics can be found here. 

2.4.

...

5 Generic message flow for Connect messages

For all user generated connect messages from a patient registry to a donor registry or vice versa the generic message flow consists of the message sent (e.g. a Sample Request) and a corresponding Message Response (6.2). The detailed message flow for such a message including the generic response message is shown below. The generic response message will be ommited in request message flows in chapter 5, for better readability. 

...

participant "Patient Registry" as PR

control "Match-Connect" as MC

control "Search & Match\nService" as SM

participant "Donor Registry" as DR

skinparam SequenceMessageAlign center

skinparam dpi 92

== Sending a user generated message ==
PR -[#dodgerblue]> DR : Send 'Message A'

group details
note left DR: routinely asychron check for pending messages
DR -[#green]> MC : Call /availableMessages to check for not-picked up messages
activate MC #FFBBBB
MC -> DR : 200 OK - Array of messages not yet delivered (**emtpy**)
MC -> DR : 400 Bad Request
deactivate MC

PR -[#green]> MC : Call respective Request-API to send 'Message A'
activate MC #FFBBBB
MC -> PR : 200 OK
MC -> PR : 400 Bad Request
deactivate MC
 
DR -[#green]> MC : Call /availableMessages to check for not-picked up messages
activate MC #FFBBBB
MC -> DR : 200 OK - Array of messages not yet delivered (**'Message A'**)
MC -> DR : 400 Bad Request
deactivate MC
 
DR -[#green]> MC : Call respective Response-API to picked up 'Message A'
activate MC #FFBBBB
MC -> DR : 200 OK
MC -> DR : 400 Bad Request
deactivate MC 
end
== Providing the generic response ==
DR -[#dodgerblue]> PR : Message response (ack, reject, warning to 'Message A') \nshould always include messageId of referring message

group details
PR -[#green]> MC : Call /availableMessages to check for not-picked up messages
activate MC #FFBBBB
MC -> PR : 200 OK - Array of messages not yet delivered (**emtpy**)
MC -> PR : 400 Bad Request
deactivate MC

DR -[#green]> MC : Call /messageResponse API to send the generic response to 'Message A'
activate MC #FFBBBB
MC -> DR : 200 OK
MC -> DR : 400 Bad Request
deactivate MC
 
PR -[#green]> MC : Call /availableMessages to check for not-picked up messages
activate MC #FFBBBB
MC -> PR : 200 OK - Array of messages not yet delivered (**generic response to 'Message A'**)
MC -> PR : 400 Bad Request
deactivate MC
 
PR -[#green]> MC : Call /messageResponseRetrieve API to pick up the generic response to 'Message A'
activate MC #FFBBBB
MC -> PR : 200 OK
MC -> PR : 400 Bad Request
deactivate MC
 
end

2.4.

...

6 Automatically generated and manually curated Swagger

The use of both an automatically generated and manually curated Swagger serves a dual purpose.

...

Together, these two approaches provide important information about technical accuracy and communication about the development of Match Connect.

2.4.

...

7 Message storage retention policies

Messages sent using the Connect API have the following retention policies applied: 

...