| Info |
|---|
|
Match-Connect Semantics v2.0 |
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.
| Field | Details |
|---|
| referenceMessageId* | string ($uuid) |
| deliveredAtUtc* | string ($date-time) Server-supplied timestamp showing UTC time of Message delivery to receiving registry's inbox queue. |
| sendingRegistry* | integer 4-digit ION of the sending registry. |
| responseType | string Enum:
[ success, warning, failed ](Enum) |
| wmdaRemarks | One or more remarks, each in its own object | Expand |
|---|
| | Field | Details |
|---|
| remarkType | string (Enum:
[ invalidInformation, invalidJson, requiredFieldsMissing, invalidReceivingRegistry, notPermittedReceivingRegistry, additionalPropertiesViolated, invalidHla, objectShouldNotBeNull, integerExpected, stringExpected, messageDoesNotExist ]) | | description | string |
|
|
| messageSequenceNumber* | integer
Incrementing integer set by WMDA MatchConnect system that indicates the order in which the messages were received by the WMDA and therefore the order in which messages should be processed. Each receiving registry has its own unique sequence. |
| messageType* | string (Enum) The stringEnum the type of message just sent by calling this endpoint. |
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.
| Field | Details |
|---|
| limit* | integer
Limit as stated in request. Default 100 100. |
| totalCount* | integer
Number of messages retrieved (0 or 1). |
| remainingCount* | integer
Number of messages remaining (not yet retrieved) for this endpoint. |
| isSuccessful* | boolean Was the retrieval of the message successful? |
| summary* | string example: "1 message retrieved successfully. 7 remaining messages." summary Summary of retrieval. |
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.
...
| addressRequest - example of request with the block named institutionPaying |
| Expand |
|---|
| title | institutionPaying block in Request... |
|---|
| | Field | Details |
|---|
| organisationId | string
Organisation unique identifier for the institution. - 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 organisation 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.
| | organisation* | | Expand |
|---|
| | name* | string Name of the destination organisation | | addressLine1* | string first First line of address. Generally the street and house number. | | addressLine2 | string second Second line of address | | addressLine3 | string third Third line of address | | postalCode* | string | | city* | string The name of the city, town, suburb, village or other community or delivery center. | | country* | string Country - a nation as commonly understood or generally accepted. | | phone | string The value is a telephone number used for voice calls. | | fax | string The value is the number for a fax machine. | | email | string ($email) The value is an email address. | | type* | string (Enum)
Type of organisation. node = MatchConnect node. Formerly known as "HUB". collectionCentre is formerly known as HAR. Enum:
[ node, donorCentre, transplantCentre, collectionCentre, lab, financialInstitution, cordBloodBank ] |
|
| | contactPerson* | | Expand |
|---|
| | name* | string The name of the contact person. | | phone* | string The value is a telephone number used for voice calls. | | fax | string The value is the number for a fax machine. | | email | string ($email) The value is an email address. |
|
|
|
|
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.
Rules:
hla 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,
the API will with HTTP 200. The message will be sent and is retrievable including warning.hla soft fail. When providing drb3 , drb4 , or drb5 - 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 soft hard fail with HTTP 200. The message will be sent and is retrievable including warning.
hla hard fail. 400. For required hla loci loci (a, b , drb1), either dna or serology must be provided. If neither is provided, the API will return HTTP 400a hard fail occurs.
| patient | Field | Details |
|---|
| wmdaId* | integer 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
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* | | Expand |
|---|
| title | {...}
|---|
| a*idm | |
| dateOfBirth | | Expand |
|---|
| . | | Field year* | Type |
|---|
| field1 | string
example: 01:128 1st allele | | field2 | string
example: 24:02 2nd allele. If field2 is provided, field1 should also be provided | | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 1 1st allele | | field2 | string
example: 24 2nd allele. If field2 is provided, field1 should also be provided |
|
| Either dna or serology must be provided b* | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 08:15 1st allele | | field2 | string
example: 07:02 2nd allele. If field2 is provided, field1 should also be provided |
|
| serologyinteger Year of birth (4 digits). | month | integer Month of birth (1–12). | day | integer Day of birth (1–31). If day is provided, month must also be present. |
|
|
| diagnosis | {...} |
| diseasePhase | string (Enum)
|
| ethnicity | string (Enum)
|
| poolCountryCode | string example: NL Two-letter ISO 3166-1 alpha-2 code for the country. Uppercase letters. |
| abo | string (Enum) |
| rhesus | string (Enum) |
| weight | integer |
| sex | string (Enum) |
| firstName | string First (given name) of the patient. |
| lastName | string Last (family name) of the patient. |
| mic | |
. |
| Field | Type |
|---|
field1 |
example: 81st allele
| field2 | string
example: 7 2nd allele. If field2 is provided, field1 should also be provided |
Either dna or serology must be provided
c | | Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 07:01 1st allele | | field2 | string
example: 07:02 2nd allele. If field2 is provided, field1 should also be provided |
|
|
| serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 7 1st allele | | field2 | string
example: 7 2nd allele. If field2 is provided, field1 should also be provided |
|
|
dbr1* | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 03:01 1st allele | | field2 | string
example: 15:46 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 3 1st allele | | field2 | string
example: 15 2nd allele. If field2 is provided, field1 should also be provided |
|
|
Either dna or serology must be provided |
|
dqb1 | | Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:01 1st allele | | field2 | string
example: 06:02 2nd allele. If field2 is provided, field1 should also be provided |
|
|
| serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 2 1st allele | | field2 | string
example: 6 2nd allele. If field2 is provided, field1 should also be provided |
|
|
dpb1 | | Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:01 1st allele | | field2 | string
example: 87:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb3 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:01 1st allele | | field2 | string
example: 03:25 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb3 , drb4 , and drb5 together can have a maximum of two typing fields
|
|
drb4 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:01 1st allele | | field2 | string
example: 03:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb3 , drb4 , and drb5 together can have a maximum of two typing fields
|
|
drb5 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:10 1st allele | | field2 | string
example: 01:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb3 , drb4 , and drb5 together can have a maximum of two typing fields
|
|
dpa1 | | Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 03:01 1st allele | | field2 | string
example: 02:20 2nd allele. If field2 is provided, field1 should also be provided |
|
|
dqa1 | | Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:02 1st allele | | field2 | string
example: 05:05 2nd allele. If field2 is provided, field1 should also be provided |
|
|
idm | | Expand |
|---|
|
cmvStatus | string
enum [ P, G, M, B, H, O, N ] |
|
dateOfBirth | | Expand |
|---|
| year* | integer Year of birth (4 digits) | month | integer Month of birth (1–12) | day | integer Day of birth (1–31). If day is provided, month must also be present |
|
| diagnosis | {...} | diseasePhase | string
Array [ 48 ] | ethnicity | string
Array [ 21 ] | poolCountryCode | string Two-letter ISO 3166-1 alpha-2 code for the country. Uppercase letters | abo | string
Array [ 4 ] | rhesus | string
Array [ 2 ] | weight | integer | sex | string
Array [ 2 ] | firstName | string First (given name) of the patient | lastName | string Last (family name) of the patient | mic | | Expand |
|---|
| a | string example: 008:01:01/008:01:02/008:03/008:04+018:01/018:02 gl-string like format containing the MIC-A typing | b | string example: 008:01:01/008:01:02/008:03/008:04+018:01/018:02 gl-string like format containing the 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 minimisation.
| donor* | | description: | Supply one node from the following | | donorType* | string Enum:
[ adult, adcu, cbu ] | | donorId* | string |
|
6.1.6 Embedded Adult Donor Block (donor in response)
In EMDIS, the following messages are linked to the donor updates:
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.
Rules
hla soft fail. When providing hla values (dna or serology), field1 should be provided whenever field2 is present. If only field2 is provided without the corresponding field1, the API will soft fail with HTTP 200. The message will be sent and is retrievable including warning.
hla soft fail. When providing drb3 , drb4 , or drb5 , the combination of these loci can have a maximum of two typing fields. If more values are provided, the API will soft fail with HTTP 200. The message will be sent and is retrievable including warning.hla hard fail. For required hla loci (a, b , drb1), either dna or serology must be provided. If neither is provided, the API will return HTTP 400.
...
...
...
a*
...
| Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:128 1st allele | | field2 | string
example: 24:02 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 1 1st allele | | field2 | string
example: 24 2nd allele. If field2 is provided, field1 should also be provided |
|
|
Either dna or serology must be provided |
...
b*
...
| Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 08:15 1st allele | | field2 | string
example: 07:02 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 8 1st allele | | field2 | string
example: 7 2nd allele. If field2 is provided, field1 should also be provided |
|
|
Either dna or serology must be provided |
...
c
...
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 07:01 1st allele | | field2 | string
example: 07:02 2nd allele. If field2 is provided, field1 should also be provided |
|
|
| serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 7 1st allele | | field2 | string
example: 7 2nd allele. If field2 is provided, field1 should also be provided |
|
|
...
dbr1*
...
| Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 03:01 1st allele | | field2 | string
example: 15:46 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 3 1st allele | | field2 | string
example: 15 2nd allele. If field2 is provided, field1 should also be provided |
|
|
Either dna or serology must be provided |
...
dqb1
...
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:01 1st allele | | field2 | string
example: 06:02 2nd allele. If field2 is provided, field1 should also be provided |
|
|
| serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 2 1st allele | | field2 | string
example: 6 2nd allele. If field2 is provided, field1 should also be provided |
|
|
...
dpb1
...
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:01 1st allele | | field2 | string
example: 87:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
...
drb3
...
| Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:01 1st allele | | field2 | string
example: 03:25 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb3 , drb4 , and drb5 together can have a maximum of two typing fields
|
...
drb4
...
| Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:01 1st allele | | field2 | string
example: 03:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb3 , drb4 , and drb5 together can have a maximum of two typing fields.
|
...
drb5
...
| Expand |
|---|
|
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:10 1st allele | | field2 | string
example: 01:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb3 , drb4 , and drb5 together can have a maximum of two typing fields
|
...
dpa1
...
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 03:01 1st allele | | field2 | string
example: 02:20 2nd allele. If field2 is provided, field1 should also be provided |
|
|
...
dqa1
...
| dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:02 1st allele | | field2 | string
example: 05:05 2nd allele. If field2 is provided, field1 should also be provided |
|
|
...
Unique number provided by ICCBBA for the registry that is responsible for the donor/CBU
...
| Expand |
|---|
|
| Field | Details |
|---|
| antiCmvStatus | string Enum:
[ P, G, M, B, H, O, N, Q ]
Antibody to Cytomegalovirus status. Where P = IgG or IgM positive, test did not differentiate; G = IgG positive, IgM negative; M = IgG negative, IgM positive; B = Both IgG and IgM positive; H = IgG positive, IgM not tested; O = IgG negative, IgM not tested; N = Both IgG and IgM negative; Q = Questionable | | antiCmvDate | string ($date) date of CMV Ab test | | cmvNatStatus | string Enum:
[ P, N, Q ]
Cytomegalovirus Natural Status. P = positive; N = negative; Q = Questionable | | cmvNatDate | string ($date) date of CMV NAT test | | hepatitisBSurfaceAntigenStatus | string Enum:
[ P, N, Q ]
Hepatitis B status (hepatitis B surface antigen). P = Positive; N = Negative; Q = Questionable | | antiHepatitisBCoreStatus | string Enum:
[ P, N, Q ]
Hepatitis B status (antibody to hepatitis B core antigen). P = Positive; N = Negative; Q = Questionable | | antiHepatitisBSurfaceAntigenStatus | string Enum:
[ P, N, Q ]
Hepatitis B status (antibody to hepatitis B surface antigen). P = Positive; N = Negative; Q = Questionable | | hepatitisBNatStatus | string Enum:
[ P, N, Q ]
HBV NAT status. P = Positive; N = Negative; Q = Questionable | | antiHepatitisCStatus | string Enum:
[ P, N, Q ]
Hepatitis C status (antibody to hepatitis C virus). P = Positive; N = Negative; Q = Questionable | | hepatitisCNatStatus | string Enum:
[ P, N, Q ]
Hepatitis C Virus (HCV) Nucleic Acid Test Status. P = Positive; N = Negative; Q = Questionable | | antiHepatitisEStatus | string Enum:
[ P, N, Q ]
Hepatitis E status (antibody to hepatitis E virus). P = Positive; N = Negative; Q = Questionable | | hepatitisENatStatus | string Enum:
[ P, N, Q ]
Hepatitis E Virus (HEV) Natural Status. P = Positive; N = Negative; Q = Questionable | | antiHiv12Status | string Enum:
[ P, N, Q ]
Antibody status for HIV types 1 and 2. P = Positive; N = Negative; Q = Questionable | | hiv1NatStatus | string Enum:
[ P, N, Q ]
Natural antibody status for HIV-1. P = Positive; N = Negative; Q = Questionable | | hivP24Status | string Enum:
[ P, N, Q ]
HIV P24 Antigen Status. P = Positive; N = Negative; Q = Questionable | | antiHtlvStatus | string Enum:
[ P, N, Q ]
Antibody status for Human T-Lymphotropic Virus (HTLV-1/2). P = Positive; N = Negative; Q = Questionable | | syphilisStatus | string Enum:
[ P, N, Q ]
Syphilis status. P = Positive; N = Negative; Q = Questionable | | westNileVirusNatStatus | string Enum:
[ P, N, Q ]
Natural antibody status for West Nile Virus (WNV). P = Positive; N = Negative; Q = Questionable | | chagasNatStatus | string Enum:
[ P, N, Q ]
Natural antibody status for Chagas disease. P = Positive; N = Negative; Q = Questionable | | antiEbvStatus | string Enum:
[ P, G, M, B, H, O, N, Q ]
Antibody status for Epstein-Barr Virus (EBV). P = IgG or IgM positive, test did not differentiate; G = IgG positive, IgM negative; M = IgG negative, IgM positive; B = Both IgG and IgM positive; H = IgG positive, IgM not tested; O = IgG negative, IgM not tested; N = Both IgG and IgM negative; Q = Questionable | | antiToxoplasmosisStatus | string Enum:
[ P, G, M, B, H, O, N, Q ]
Anti-Toxoplasmosis Status. P = IgG or IgM positive, test did not differentiate; G = IgG positive, IgM negative; M = IgG negative, IgM positive; B = Both IgG and IgM positive; H = IgG positive, IgM not tested; O = IgG negative, IgM not tested; N = Both IgG and IgM negative; Q = Questionable | | parvoB19NatStatus | string Enum:
[ P, N, Q ]
Natural antibody status for Parvovirus B19. P = Positive; N = Negative; Q = Questionable | | alanineAminotransferaseStatus | integer minimum: 0 maximum: 999 Alanine aminotransferase status in units per litre | | antiChagasStatus | string Enum:
[ P, N, Q ]
Chagas antibody status. P = Positive; N = Negative; Q = Questionable |
|
...
example: 008:01:01/008:01:02/008:03/008:04+018:01/018:02 gl-string like format containing the MIC-A typing. | b | string example: 008:01:01/008:01:02/008:03/008:04+018:01/018:02 gl-string like format containing the 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 minimisation.
| donor* | | description: | Supply one node from the following | | donorType* | string (Enum) | | donorId* | string (oneOf) - grid (Global Registry Identifier) for
adult donor - adcuId for
adcu (Adult Donor Cryopreserved Unit) - cordId for
cbu (Cord Blood Unit)
|
|
6.1.6 Embedded Adult Donor Block (donor in response)
In EMDIS, the following messages are linked to the donor updates:
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.
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.
| donor | | Expand |
|---|
| | Field | Type |
|---|
| grid* | string | | dateOfBirth* | string ($date) | | sex | string
| | hla* | {...} | | abo | string
| | rhesus | string
| | donorRegistryIon* | integer ($int32) Unique number provided by ICCBBA for the registry that is responsible for the donor/CBU | | status* | string
| | ethnicity | string
| | idm | {...} | | lastContactDate | string ($date) | | marrowDonationsCount | integer ($int32) | | pbscDonationsCount | integer ($int32) | | donorAttribute | string | | weight | integer | | height | integer ($int32) | | kir | {...} | | collectionType | string Collection type, i.e. the willingness of the donor to donate in a specific manner. M = Marrow P = PBSC B = Both PBSC & Marrow Enum:
| | transfusionsCount | integer ($int32) | | pregnanciesCount | integer ($int32) | | reservedPatientId | string this field will be replaced by the reservedPatientWmdaId field | | reservedPatientWmdaId | integer The wmdaId of the patient for whom this donor is reserved | | statusEndDate | string ($date) | | statusReason | string Enum:
| | mic | | Expand |
|---|
| a | string example: 008:01:01/008:01:02/008:03/008:04+018:01/018:02 gl-string like format containing the MIC-A typing | b | string example: 008:01:01/008:01:02/008:03/008:04+018:01/018:02 gl-string like format containing the MIC-B typing |
|
| | ccr5 | string
| | lastMedicalCheckupDate | string ($date) |
|
|
|---|
6.1.7 Embedded CBU Block (in response)
In EMDIS, the following messages are linked to the CBU updates:
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.
| cbu | | Expand |
|---|
| | Field | Type |
|---|
| cordId* | string CBU Identification2 (formerly CB_ID) | | dateCollected* | string ($date) | | hla* | {...} | | cbbIon* | integer ($int32) Unique number provided by ICCBBA for the registry that is responsible for the donor/CBU | | status* | string
| | idm | {...} |
|
|
|---|
...
| Expand |
|---|
|
| Field | Type |
|---|
| kir2Dl1Status | string Enum:
[ P, N ] | | kir2Dl2Status | string Enum:
[ P, N ] | | kir2Dl3Status | string Enum:
[ P, N ] | | kir2Dl4Status | string Enum:
[ P, N ] | | kir2Dl5aStatus | string Enum:
[ P, N ] | | kir2Dl5bStatus | string Enum:
[ P, N ] | | kir2Dp1Status | string Enum:
[ P, N ] | | kir2Ds1Status | string Enum:
[ P, N ] | | kir2Ds2Status | string Enum:
[ P, N ] | | kir2Ds3Status | string Enum:
[ P, N ] | | kir2Ds4Status | string Enum:
[ P, N ] | | kir2Ds5Status | string Enum:
[ P, N ] | | kir3Dl1Status | string Enum:
[ P, N ] | | kir3Dl2Status | string Enum:
[ P, N ] | | kir3Dl3Status | string Enum:
[ P, N ] | | kir3Dp1Status | string Enum:
[ P, N ] | | kir3Ds1Status | string Enum:
[ P, N ] | | kirGlStringUri | string maxLength: 255 URI that refers to a GL String registered with a GL service or direct GL String for absence / presence |
|
...
Collection type, i.e. the willingness of the donor to donate in a specific manner. M = Marrow P = PBSC B = Both PBSC & Marrow
...
string
this field will be replaced by the reservedPatientWmdaId field
...
integer
The wmdaId of the patient for whom this donor is reserved
...
| Expand |
|---|
|
a | string example: 008:01:01/008:01:02/008:03/008:04+018:01/018:02 gl-string like format containing the MIC-A typing | b | string example: 008:01:01/008:01:02/008:03/008:04+018:01/018:02 gl-string like format containing the MIC-B typing |
|
...
6.1.7 Embedded CBU Block (donor in response)
In EMDIS, the following messages are linked to the CBU updates:
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.
| cbu | | Expand |
|---|
| | Field | Type |
|---|
| cbuId* | string CBU Identification2 (formerly CB_ID) | | dateCollected* | string ($date) | hla* | | Expand |
|---|
| a* | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:128 1st allele | | field2 | string
example: 24:02 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 1 1st allele | | field2 | string
example: 24 2nd allele. If field2 is provided, field1 should also be provided |
|
|
Either dna or serology must be provided |
| b* | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 08:15 1st allele | | field2 | string
example: 07:02 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 8 1st allele | | field2 | string
example: 7 2nd allele. If field2 is provided, field1 should also be provided |
|
|
Either dna or serology must be provided |
| c | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 07:01 1st allele | | field2 | string
example: 07:02 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 7 1st allele | | field2 | string
example: 7 2nd allele. If field2 is provided, field1 should also be provided |
|
|
dbr1* | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 03:01 1st allele | | field2 | string
example: 15:46 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 3 1st allele | | field2 | string
example: 15 2nd allele. If field2 is provided, field1 should also be provided |
|
|
Either dna or serology must be provided |
| dqb1 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:01 1st allele | | field2 | string
example: 06:02 2nd allele. If field2 is provided, field1 should also be provided |
|
| | serology | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 2 1st allele | | field2 | string
example: 6 2nd allele. If field2 is provided, field1 should also be provided |
|
|
dpb1 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:01 1st allele | | field2 | string
example: 87:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb3 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:01 1st allele | | field2 | string
example: 03:25 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb4 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:01 1st allele | | field2 | string
example: 03:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
drb5 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 02:10 1st allele | | field2 | string
example: 01:01 2nd allele. If field2 is provided, field1 should also be provided |
|
|
dpa1 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 03:01 1st allele | | field2 | string
example: 02:20 2nd allele. If field2 is provided, field1 should also be provided |
|
|
dqa1 | | Expand |
|---|
| | dna | | Expand |
|---|
| | Field | Type |
|---|
| field1 | string
example: 01:02 1st allele | | field2 | string
example: 05:05 2nd allele. If field2 is provided, field1 should also be provided |
|
|
| cbbIon* | integer ($int32) Unique number provided by ICCBBA for the registry that is responsible for the donor/CBU | | status* | string
| | idm | | Expand |
|---|
| | | Field | Details |
|---|
| antiCmvStatus | string Enum:
[ P, G, M, B, H, O, N, Q ]
Antibody to Cytomegalovirus status. Where P = IgG or IgM positive, test did not differentiate; G = IgG positive, IgM negative; M = IgG negative, IgM positive; B = Both IgG and IgM positive; H = IgG positive, IgM not tested; O = IgG negative, IgM not tested; N = Both IgG and IgM negative; Q = Questionable | | antiCmvDate | string ($date) date of CMV Ab test | | cmvNatStatus | string Enum:
[ P, N, Q ]
Cytomegalovirus Natural Status. P = positive; N = negative; Q = Questionable | | cmvNatDate | string ($date) date of CMV NAT test | | hepatitisBSurfaceAntigenStatus | string Enum:
[ P, N, Q ]
Hepatitis B status (hepatitis B surface antigen). P = Positive; N = Negative; Q = Questionable | | antiHepatitisBCoreStatus | string Enum:
[ P, N, Q ]
Hepatitis B status (antibody to hepatitis B core antigen). P = Positive; N = Negative; Q = Questionable | | antiHepatitisBSurfaceAntigenStatus | string Enum:
[ P, N, Q ]
Hepatitis B status (antibody to hepatitis B surface antigen). P = Positive; N = Negative; Q = Questionable | | hepatitisBNatStatus | string Enum:
[ P, N, Q ]
HBV NAT status. P = Positive; N = Negative; Q = Questionable | | antiHepatitisCStatus | string Enum:
[ P, N, Q ]
Hepatitis C status (antibody to hepatitis C virus). P = Positive; N = Negative; Q = Questionable | | hepatitisCNatStatus | string Enum:
[ P, N, Q ]
Hepatitis C Virus (HCV) Nucleic Acid Test Status. P = Positive; N = Negative; Q = Questionable | | antiHepatitisEStatus | string Enum:
[ P, N, Q ]
Hepatitis E status (antibody to hepatitis E virus). P = Positive; N = Negative; Q = Questionable | | hepatitisENatStatus | string Enum:
[ P, N, Q ]
Hepatitis E Virus (HEV) Natural Status. P = Positive; N = Negative; Q = Questionable | | antiHiv12Status | string Enum:
[ P, N, Q ]
Antibody status for HIV types 1 and 2. P = Positive; N = Negative; Q = Questionable | | hiv1NatStatus | string Enum:
[ P, N, Q ]
Natural antibody status for HIV-1. P = Positive; N = Negative; Q = Questionable | | hivP24Status | string Enum:
[ P, N, Q ]
HIV P24 Antigen Status. P = Positive; N = Negative; Q = Questionable | | antiHtlvStatus | string Enum:
[ P, N, Q ]
Antibody status for Human T-Lymphotropic Virus (HTLV-1/2). P = Positive; N = Negative; Q = Questionable | | syphilisStatus | string Enum:
[ P, N, Q ]
Syphilis status. P = Positive; N = Negative; Q = Questionable | | westNileVirusNatStatus | string Enum:
[ P, N, Q ]
Natural antibody status for West Nile Virus (WNV). P = Positive; N = Negative; Q = Questionable | | chagasNatStatus | string Enum:
[ P, N, Q ]
Natural antibody status for Chagas disease. P = Positive; N = Negative; Q = Questionable | | antiEbvStatus | string Enum:
[ P, G, M, B, H, O, N, Q ]
Antibody status for Epstein-Barr Virus (EBV). P = IgG or IgM positive, test did not differentiate; G = IgG positive, IgM negative; M = IgG negative, IgM positive; B = Both IgG and IgM positive; H = IgG positive, IgM not tested; O = IgG negative, IgM not tested; N = Both IgG and IgM negative; Q = Questionable | | antiToxoplasmosisStatus | string Enum:
[ P, G, M, B, H, O, N, Q ]
Anti-Toxoplasmosis Status. P = IgG or IgM positive, test did not differentiate; G = IgG positive, IgM negative; M = IgG negative, IgM positive; B = Both IgG and IgM positive; H = IgG positive, IgM not tested; O = IgG negative, IgM not tested; N = Both IgG and IgM negative; Q = Questionable | | parvoB19NatStatus | string Enum:
[ P, N, Q ]
Natural antibody status for Parvovirus B19. P = Positive; N = Negative; Q = Questionable | | alanineAminotransferaseStatus | integer minimum: 0 maximum: 999 Alanine aminotransferase status in units per litre | antiChagasStatus | stringEnum:
[ P, N, Q ]
Chagas antibody status. P = Positive; N = Negative; Q = Questionable| reservedPatientId | string this field will be replaced by the reservedPatientWmdaId field | | reservedPatientWmdaId | integer The wmdaId of the patient for whom this donor is reserved | | statusEndDate | string ($date) | | statusReason | string
|
|
|
|---|
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.
...
| Field | Details |
|---|
| attachmentGuid* | string ($uuid) |
| attachmentDescription* | string (Enum: TBD
) Type Describes the purpose of the attachment/file. |
| fileName * | string
maxLength : 255
example: test.txtpdf |
6.2 Message Response
The message response is intended as an automated response to every user-generated message. It serves three purposes:
...
| Send (Post) | Retrieve (Post) |
|---|
| MessageResponseRequest | |
| Expand |
|---|
| | Field | Details |
|---|
| receivingRegistry* | integer ION | | organisationResponse* | | Expand |
|---|
| | Field | Details |
|---|
| retrievedAtUtc* | string ($date-time) Server-supplied timestamp showing time of Message retrieval and storage in organisation's own systems | | referenceMessageId* | string ($uuid) | | responseType* | string Enum:
Array [ 3 ] | | remark | string
|
|
| |
| | Expand |
|---|
| | limit | integer
| | shouldPeek | boolean
Set to true if you want messages to remain available after retrieval | | messageSequenceNumber | integer Optional field to request a message with a specific messageSequenceNumber. |
|
|
6.3 Instruments
6.3.1 Text message [TXT_MSG]
Usage:
| Status |
|---|
| subtle | true |
|---|
| colour | Blue |
|---|
| title | PR <-> DR |
|---|
|
...
| Send (Post) | Retrieve (Post) |
|---|
| textMessageRequest | |
| Expand |
|---|
|
| Details |
|---|
| referenceMessageId | string ($uuid)
can be used to refer to message that has been sent previously
| | text* | string Text. Message for a human at receiving registry. | | receivingRegistry * | string 4 digit ION of the receiving registry | | patient | wmdaId | | donor* | Embedded Donor Block (donor in request) |
|
| | Expand |
|---|
| | limit | integer
| | shouldPeek | boolean
Set to true if you want messages to remain available after retrieval | | messageSequenceNumber | integer Optional field to request a message with a specific messageSequenceNumber. |
|
|
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.
Send (Post)
| Send (Post)
|
| uploadAttachment | downloadAttachment |
| Expand |
|---|
| title | Upload a file (form) |
|---|
| | Field | Details |
|---|
| receivingRegistry* | integer 4-digit ION of receivingRegistry | | fileName* | string | | attachmentDescription* | string, Enum | | file | string($binary) PDF only, max 10 MB |
|
| Expand |
|---|
| | Field | Details |
|---|
| timeUtc* | string ($date-time) | | message* | string
| | attachmentGuid* | string ($uuid)
| | receivingRegistry* | integer 4-digit ION of receivingRegistry | | fileName* | string | | attachmentDescription* | string, Array |
|
| | Expand |
|---|
| | Field | Details |
|---|
| attachmentGuid* | string
($uuid)
|
|
| Expand |
|---|
| | Field | Details |
|---|
| 200 OK | File |
|
|
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.
| Send | Retrieve (Post) |
|---|
| AlertRetrieve |
| Alerts can only be sent by the WMDA's central system | | Expand |
|---|
| | limit | integer
| | shouldPeek | boolean
Set to true if you want messages to remain available after retrieval | | messageSequenceNumber | integer Optional field to request a message with a specific messageSequenceNumber. |
|
| Expand |
|---|
| | Field | Details |
|---|
| generalInformation* | Embedded General Information Block | | messages* | originalMessage | Expand |
|---|
| | Field | Details |
|---|
| level | string alert level. enums may change Enum:
Array [ 3 ] | | status | string check later Enum:
Array [ 2 ] | | messageText | string
maxLength: 1024
example: WMDA will do maintenance on SMC system on the weekend of 10 march |
|
|
| metaInformation* Embedded Meta Block |
|
|
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.
| Send | Retrieve (Post) |
|---|
| AlertUpdateRetrieve |
| Alert updates can only be sent by the WMDA's central system | | Expand |
|---|
| | limit | integer
| | shouldPeek | boolean
Set to true if you want messages to remain available after retrieval | | messageSequenceNumber | integer
example: 12345 Optional field to request a message with a specific messageSequenceNumber. |
|
| Expand |
|---|
| | Field | Details |
|---|
| generalInformation* | Embedded General Information Block | | messages* | originalMessage | Expand |
|---|
| | Field | Details |
|---|
| level | string alert level. enums may change Enum:
Array [ 3 ] | | status | string check later Enum:
Array [ 2 ] | | messageText | string
maxLength: 1024
example: WMDA will do maintenance on SMC system on the weekend of 10 march |
|
|
| metaInformation* Embedded Meta Block |
|
|
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).
| GET |
| availableMessages |
| Expand |
|---|
| | Field | Details |
|---|
| totalMessages* | integer
example: 6
Count of messages that are ready for retrieval
| | messagesReadyForRetrieval * | | Expand |
|---|
| | Field | Details |
|---|
| messageResponse | Count integer, example: 6 sequenceNumbers integer, List 1, 18
| | alert* | Count integer sequenceNumbers integer | | updatedPatient* | Count integer sequenceNumbers integer | | ping* | Count integer sequenceNumbers integer | | textMessage* | Count integer sequenceNumbers integer | | genericRequest* | Count integer sequenceNumbers integer | | extendedTypingRequest* | Count integer sequenceNumbers integer | | typingResponse* | Count integer sequenceNumbers integer | | sampleRequest* | Count integer sequenceNumbers integer | | sampleInfo* | Count integer sequenceNumbers integer | | sampleArrival* | Count integer sequenceNumbers integer | | sampleResponse* | Count integer sequenceNumbers integer | | infectiousDiseaseMarkerRequest* | Count integer sequenceNumbers integer | | infectiousDiseaseMarkerResult* | Count integer sequenceNumbers integer | | reservationRequest* | Count integer sequenceNumbers integer | | reservationResponse* | Count integer sequenceNumbers integer | | reservationRelease* | Count integer sequenceNumbers integer | | requestCancellation* | Count integer sequenceNumbers integer | | requestRejected* | Count integer sequenceNumbers integer | | resultReminder* | Count integer sequenceNumbers integer | | cordBloodUnitReportRequest* | Count integer sequenceNumbers integer | | cordBloodUnitReportResponse* | Count integer sequenceNumbers integer |
|
|
|
|
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.
Retrieve (Post)
|
| availableMessagesAll |
| Expand |
|---|
| | Field | Details |
|---|
| limit | integer
default: 100
| | shouldPeek | boolean
default: false
Set to true if you want messages to remain available after retrieval |
|
| Expand |
|---|
| | Field | Details |
|---|
| generalInformation* | | Expand |
|---|
| | Field | Details |
|---|
| limit* | integer default: 100
| | shouldPeek | boolean default: false
| | totalCount* | integer minimum: 0
example: 1
| | remainingCount* | integer minimum: 0 | | isSuccessful* | boolean default: true
| | summary* | string maxLength: 255
example: 1 message retrieved sucessully. 0 remaining messages
|
|
| | messages * | | Expand |
|---|
| | Field | Details |
|---|
| originalMessage* | oneOf: alert
ping
textMessageRequest
genericRequest
extededTypingRequest
typingResponse
sampleRequest
sampleArrival
sampleInfo
sampleResponse
infectiousDiseaseMarker
infectiousDiseaseMarkerResult
reservationRequest
reservationResponse
reservationRelease
requestCancellation
requestRejected
resultReminder
cordBloodUnitReportRequest
cordBloodUnitReportResponse | | metaInformation* | {...} |
|
|
|
|
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.
...