Page History

...

2.4.2 Messages collection

How to collect all messages and keep the sequence:

The actual messages have to Messages can be collected via individual API calls against the different "retriveretrieve" APIs. In order to streamline that process a "master"-retrieve API (/api/v2/availableMessages) is provided that returns a list of individual "retrieve" APIs that contain waiting messages for the retrieving registry. The availableMessages API will list per "retrive" API the sequence number(s) of the waiting message(s) in an array. Each "retrive" API will have the optional parameter "sequenceNumber", that allows for an indivual collection of that specific message. If that parameter is left empty all available messages are retrieved (according to the limit set in the parameters). 

It is left for the retrieving registry to choose how to collect the messages:

A) collect an overview via the availableMessages and then collect the messages one by one in the order given by the sequence number or

B) collect an overview via the availableMessages and then collect all waiting messages and ensure the correct order of processing of the messages in the local system

C) pull all "retrieve" APIs without checking first the availableMessages APIs and ensure the correct order of processing of the messages in the local system

An additional "All-in-One Queue" is under discussion:

Such a queue would provide all waiting messages in the order of the sequence number directly as return value of the call not only the information which (sequence number) and what (retrive API) kind of messages are waiting for retrieval.

Technicaly this could be realized by:

• provide a new endpoint that makes use of the "oneOf" tag and provides all messages for external registries
• Note: here the sequence number is not needed for ordering anymore but still needed to realize missing messages

This would allow a registry to call just one endpoint to collect all messages.

Limitations:

This option doesn't 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.

As on WMDA side (propably) all messages are stored in one queue/store anyhow (check with Mark) both options will only effect the exposure of the messages to the registries and not the internal workings on WMDA side.

...

It is left for the retrieving registry to choose how to collect the messages, by picking one of the following scenarios:

• Retrieving array with overview of all messages that are ready to be downloaded
  
  This endpoint allows end users to retrieve an overview of all messages that are ready to be downloaded. This information can be used to retrieve the messages from their respective *retrieve endpoints.
  The chronological order of processing the messages should be arranged in the local system. This can be done by using the timestamps that are provided with the messages, as part of their meta information.

• Retrieving array with overview of all messages that are ready to be downloaded, including sequence numbers (OPTIONAL, MAY NOT BE IMPLEMENTED)
  
  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). 

• Retrieving array of all messages that are ready to be downloaded, including message content (OPTIONAL, MAY NOT BE 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.