⚠Due to planned maintenance you will experience short (<30 min) downtime between 08:00 - 08:30 CET.
Table of Contents |
---|
<title>
<Narrative>
<Swagger - API reference>
<temporary - document any differences needing implementation in swagger>
<Specific rules / expectations>
6.0 Responsibilities of the Match Connect System / Broker
The Match Connect system acts as a central broker of information exchange between registries participating in the Match Connect ecosystem, also called central hub from here on. The central hub bears responsibility to:
- Route information from the sending registry to the receiving registry and maintain information integrity
- Provide meta information to aid in the investigation of message failures or data synchronization problems
- Provide meta information for traceability
- Ensure integrity of the data in the Search & Match Service
- Perform syntactic validation of the information (e.g. appropriate information structure, allowable values, valid dates, etc)
- Validate the data for fields which are contained in the Search & Match Service and update these accordingly. This applies to
- Patient data, in particular HLA
In performing these duties, the Match Connect system will inspect the contents of messages to determine who to route messages to and to perform basic validation. This content is not intended to be reviewed by administrators of the system except in cases of investigating message failures or data synchronization problems. Original message contents will never be modified by the central system but additional meta information "blocks" will be added to ensure the receiving registry is aware of:
- What registry sent the information
- What type of information is contained
- A message identifier
- A timestamp
- Any failed validations detected by the Match Connect system
6.1 Embedded Address block
6.1 Embedded blocks
6.1.1 Embedded Meta block
The additional meta-information "blocks" are added to ensure the receiving registry is aware of:
- A 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.
metaInformation* |
|
6.1.2 Embedded Address block (NEW_ADD)
...
With this message block, the contact information of the hub's institutions, namely Financial institutionsFinancial institutions, Transplant Centers, and Laboratories are shared with the partner hubs. Thus a partner hub partner hub has all the required contact information for the Institute IDs, ”INST_ID”, 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.
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 follow the construct of ION + local address id.
- 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 Chapter Requests for details.
Address block structure:
https://hapifhir.io/hapi-fhir/apidocs/hapi-fhir-structures-r4/org/hl7/fhir/r4/model/Address.html
...
Field | Details | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
organisationId | string Organisation unique identifier for the institution.
| |||||||||||||||||||||||
organisation* |
| |||||||||||||||||||||||
contactPerson* |
|
6.1.3 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:
Field | Details |
---|---|
wmdaId* | integer nullable: false example: 1234 ID provided by the WMDA |
patientId* | string 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. |
emdisPatientId | string maxLength: 17 minLength: 3 nullable:true example: AU9654021 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. |
hla* | {...} |
idm | {...} |
dateOfBirth | string($date) nullable: true maxLength: 10 example: 1961-05-27 |
diagnosis | {...} |
diseasePhase | string Enum: |
ethnicity | string Enum: |
poolCountryCode | string maxLength: 2 pattern: ^[A-Z]{2} nullable: true example: NL ISO 3166-1 alpha-2 Country Code (capitalized) |
abo | string Enum: |
rhesus | string Enum: |
weight | integer nullable: true minimum: 1 maximum: 999 example: 76 |
sex | string Enum: |
firstName | string maxLength:50 nullable: true example: John First (given name) of the patient |
lastName | string maxLength:50 nullable: true example: Doe Last (family name) of the patient |
mic | {...} |
6.1.4 Embedded Donor Block (donor in request)
In case 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.
Donor type | Details | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
donor* |
|
6.1.5 Embedded Donor Block (donor in response)
In EMDIS, the following messages are linked to the donor updates:
- TYP_RES
- IDM_RES
- RSV_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:
- extendedTypingResponse
- infectiousDiseaseMarkerResponse
- reservationResponse
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.
Field | Details | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
grid* | string | |||||||||||||||||||||||||||
dateOfBirth* | string | |||||||||||||||||||||||||||
sex | string | |||||||||||||||||||||||||||
hla* |
| |||||||||||||||||||||||||||
abo | string nullable:true Enum: [A, B, O, AB] | |||||||||||||||||||||||||||
rhesus | string nullable:true Enum: [P, N] | |||||||||||||||||||||||||||
donorRegistryIon* | integer($int32) Unique number provided by ICCBBA for the registry that is responsible for the donor/CBU | |||||||||||||||||||||||||||
status* | string | |||||||||||||||||||||||||||
ethnicity | string Enum: | |||||||||||||||||||||||||||
idm | [ ... ] | |||||||||||||||||||||||||||
lastContactDate | string($date) | |||||||||||||||||||||||||||
marrowDonationsCount | integer($int32) | |||||||||||||||||||||||||||
pbscDonationsCount | integer($int32) | |||||||||||||||||||||||||||
donorAttribute | string | |||||||||||||||||||||||||||
weight | integer | |||||||||||||||||||||||||||
height | integer($int32) | |||||||||||||||||||||||||||
kir | [ ... ] | |||||||||||||||||||||||||||
collectionType | string | |||||||||||||||||||||||||||
transfusionsCount | integer($int32) | |||||||||||||||||||||||||||
pregnanciesCount | integer($int32) | |||||||||||||||||||||||||||
reservedPatientId | string | |||||||||||||||||||||||||||
statusEndDate | string($date) | |||||||||||||||||||||||||||
statusReason | string | |||||||||||||||||||||||||||
mic | {...} | |||||||||||||||||||||||||||
ccr5 | string nullable: true Enum: [ DD, DW, WW ] | |||||||||||||||||||||||||||
lastMedicalCheckupDate | string($date) |
Here is the comparison of the DONOR_CB and the API endpoints: EMDIS vs API.xlsx
6.1.6 Embedded general information block
The WMDA will provide a standard response that contains the parameters used to retrieve messages in Match-Connect. Its structure is as follows:
generalInformation* |
|
...
6.2 Message Response
The message response is intended as an automated response to every user generated message. It serves three purposes:
...
Note: The concept of the REF_CODE field used in EMDIS is replaced by the GUID referenceMessageId assigned by the central system to each message. The Message Response is supposed to be using the GUID referenceMessageId of the original message as the Reference ID in its structure.
Message structure:
Send (Post) | Retrieve |
---|
(Post) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
MessageResponseRequest | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
- Reference ID (GUID)
- Response type
- message acknowledgment
- warning
- message denial
- Remark - a string explaining the reason for a denial or a warning, empty for acknowledgment
MessageResponse payload
Meta block6.3 Text message [TXT_MSG]
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
- Patient
- Donor
- Text
TextMessage payload
Meta block6.4 Alert message
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) | |||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
get_api_v1_AlertRetrieve | ||||||||||||||||||||||||||||||||||||||
Alerts can only be sent by the WMDA's central system |
Alert Payload:
|
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) | |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
get_api_v1_AlertUpdateRetrieve | ||||||||||||||||||||||||||||||||||
Alert updates can only be sent by the WMDA's central system Alert Update Payload:
|
|
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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.
Retrieve (Post) | ||||||||||||||||||||||||||||||||||||||||||||||||||||
availableMessagesAll | ||||||||||||||||||||||||||||||||||||||||||||||||||||
|
6.8 Recover Messages
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 a 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: section 2.4.7 Message storage retention policies in the Technical Guidelines chapter.
POST | ||||||||||||||||||||
recoverMessages | ||||||||||||||||||||
|