You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 112 Next »

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
  • What 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


FieldDetails
referenceMessageId*string($uuid)
deliveredAtUtc*string($date-time)

Server-supplied timestamp showing UTC time of Message delivery to receiving registry's inbox queue.

sendingRegistry*integer
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 5678

4-digit ION of the sending registry

responseType

string

Enum:
Array [ Warning]

wmdaRemarks

One or more remarks, each in its own object


FieldDetails
remarkTypestring
descriptionstring
messageSequenceNumber*

integer
example: 12345

Incrementing integer set by WMDA MatchConnect systems 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

the type of message just sent by calling this endpoint

6.1.2 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. 

  • 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.
  • The contactPerson is required if the INST_TYPE is ”LAB”.
  • The EMDIS ID (INST_ID) of an institution should remain stable over time and should not be assigned to different institutions.

In the Match-Connect system, the addresses will be embedded in the donor requests. See Chapter Requests for details.

Message structure:

SendRetrieve
addressRequest

addressRetrieve

Field

Details

organisationId*

string
nullable: false

maxLength: 10
minLength: 3

Organisation unique identifier for the institution.

  1. Unique reference to an institution
  2. 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 hub code + local address id. 
      • The hub code usually are the two-character ISO country code of the registry (e.g. NL for Netherlands)  
      • In the case of multiple registries in one country, a replacement code will be assigned.
  • Should be provided as a user-friendly (displayable) id for use on screens and on documentation.
line1*

string
nullable: false

maxLength: 60

Address line 1

line2

string
nullable: true

maxLength: 60

Address line 2

line3

string
nullable: true

maxLength: 60

Address line 3

postalCode*

string
nullable: false

maxLength: 10

city*

string
nullable: false

maxLength: 40

country*

string
nullable: false

minLength: 2

maxLength: 2

2 character ISO country code ( ISO 3166-1 alpha-2)
type*

string
nullable: false

minLength: 3

maxLength: 3

HUB = EMDIS Hub
DON = Donor centre
TRA = Transplant centre
HAR = Harvesting centre
LAB = Typing laboratory
FIN = Financial institution
CBB = Cord Blood Bank

contactPerson

string
nullable: true

maxLength: 40

Contact person. Required if type = LAB.

phone*

string
nullable: false

maxLength: 20

fax

string
nullable: true

maxLength: 20

email

string
nullable: true

maxLength: 60

receivingRegistry*string
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 1234

4 digit ION of the receiving registry

FieldDetails
wmdaResponseEmbedded WMDA Response Block
limitinteger
default: 100
shouldPeekboolean
default: false

Set to true if you want messages to remain available after retrieval

FieldDetails
originalMessage{...}
metaInformationEmbedded Meta Block


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:

FieldDetails
wmdaId*integer
nullable: false
example: 1234

ID provided by the WMDA

patientId*string
maxLength: 17
nullable: false
example: XY1234P

Organisation unique identifier for the patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here.

hla*{...}
idm{...}
dateOfBirthstring($date)
nullable: true
maxLength: 10
example: 1961-05-27
diagnosis{...}
diseasePhase

string
nullable: true

Enum:
Array [ 48 ]

ethnicity

string
nullable: true

Enum:
Array [ 20 ]

poolCountryCodestring
maxLength: 2
pattern: ^[A-Z]{2}
nullable: true
example: NL

ISO 3166-1 alpha-2 Country Code (capitalized)

abo

string
nullable: true

Enum:
Array [ 4 ]

rhesus

string
nullable: true

Enum:
Array [ 2 ]

weightinteger
nullable: true
minimum: 1
maximum: 999
example: 76
sex

string
nullable: true

Enum:
Array [ 2 ]

firstNamestring
maxLength: 30
nullable: true
example: John

First (given name) of the patient

lastNamestring
maxLength: 30
nullable: true
example: Doe

Last (family name) of the patient

6.1.4 Embedded Donor Block

In EMDIS, the following messages are linked to the donor updates:

  • IDM_RES
  • TYP_RES
  • NO_RES
  • RSV_RES

These four and newly two more (SMP_ARR and SMP_INFO) 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.

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 to send a DIFF upload to the S&M system in parallel to keep information in sync.

Donor typeDetails
Adult donor

grid*

string
nullable: true
maxLength: 19
minLength: 19
example: 9991012070433202000
CBU

id*

string
maxLength: 17
example: CB1234567

CBU Identification2 (formerly CB_ID)

ADCU

id*

string
maxLength: 16
example: A99991412345612N

N/A in EMDIS, available in the future

Here is the comparison of the DONOR_CB and the API endpoints: EMDIS vs API.xlsx

6.1.5 Embedded WMDA Response block

The WMDA will provide a standard response to request messages sent to Match-Connect.  Its structure is as follows:

FieldDetails
deliveredAtUtc*string($date-time)

Server-supplied timestamp showing time of Message delivery to receiving registry's inbox queue

referenceMessageId*string($uuid)
responseType*

stringEnum:
Array [ Success, Warning, Failed]

messages can be failed, if the message has a structure or information that prevent delivery to the receiving registry. This could be incorrect JSON structure and non-existent ION or because the receiving registry does not allow messages from your registry. 

receivingRegistryMessageSequenceNumber

integer
example: 12345

Incrementing integer set by WMDA MatchConnect systems 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.

wmdaRemarks[...]

6.1.6 Embedded 'generalInformation' Response block

The WMDA will provide a standard response to retrieve messages sent to Match-Connect.  Its structure is as follows:

FieldDetails
limit*integer
default: 100
shouldPeekboolean
default: false
totalCount*integer
minimum: 0
example: 1
remainingCount*integer
minimum: 0
isSuccessful*boolean
default: true
summary*

string
maxLength: 255
example: 1 message retrieved successfully. 0 remaining messages.

6.2 Message Response

The message response is intended as an automated response to every user generated message. It serves three purposes:

  • message acknowledgment
  • warning
  • message denial

This is a purely machine-to-machine type of message, as compared to EMDIS where such responses can be user generated. 

Note: The concept of the REF_CODE field used in EMDIS is replaced by the GUID assigned by the central system to each message. The Message Response is supposed to be using the GUID of the original message as the Reference ID in its structure.

Message structure:

Send (Post)Retrieve (Post)
MessageResponse

MessageResponseRetrieve

FieldDetails
organisationResponse
FieldDetails
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


FieldDetails
wmdaResponseEmbedded WMDA Response Block
limitinteger
default: 100
shouldPeekboolean
default: false

Set to true if you want messages to remain available after retrieval

FieldDetails
originalMessage{...}
metaInformationEmbedded Meta Block

6.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:

SendRetrieve
textMessageRequest

textMessageRetrieve

Field

Details

text*

string
nullable: true

Text. Message for a human at receiving registry.

receivingRegistry*string
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 1234

4 digit ION of the receiving registry

patient*Patient ID
donor*Donor ID
FieldDetails
wmdaResponseEmbedded WMDA Response Block
limitinteger
default: 100
shouldPeekboolean
default: false

Set to true if you want messages to remain available after retrieval

FieldDetails
originalMessage{...}
metaInformationEmbedded Meta Block

6.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:

SendRetrieve

AlertRetrieve
Alerts can only be sent by the WMDA's central system
limitinteger
default: 100
shouldPeekboolean
default: false

Set to true if you want messages to remain available after retrieval

FieldDetails
originalMessage
FieldDetails
levelstring

alert level. enums may change

Enum:
Array [ 3 ]
statusstring

check later

Enum:
Array [ 2 ]
messagestring
maxLength: 1024
example: WMDA will do maintenance on SMC system on the weekend of 10 march
metaInformationEmbedded Meta Block

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:

SendRetrieve

AlertUpdateRetrieve
Alert updates can only be sent by the WMDA's central system
limitinteger
default: 100
shouldPeekboolean
default: false

Set to true if you want messages to remain available after retrieval

FieldDetails
originalMessage
FieldDetails
alertReferenceIdentifierstring($uuid)
levelstring

alert level. enums may change

Enum:
Array [ 3 ]
statusstring

check later

Enum:
Array [ 2 ]
messagestring
maxLength: 1024
example: WMDA will do maintenance on SMC system on the weekend of 10 march
metaInformationEmbedded Meta Block

6.6 Available Messages

The available messages endpoint is used for retrieving an array of messages that are ready to be downloaded. This information can then be used to retrieve the messages from their respective *retrieve endpoints.

Message structure:

SendRetrieve

availableMessages
N/A
No parameters specified
FieldDetails
totalMessagesinteger
total sum of messages that are ready for retrieval
messageTypestring

the message type

Enum:
Array [ 23 ]
numberOfMessagesinteger
number of messages that are ready for retrieval
  • No labels