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

Compare with Current View Page History

« Previous Version 37 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 (sender)
  • What type of information is contained
  • /* Pending */ Any failed validations detected by the Match Connect system


metaInformation
messageIdstring($uuid)
sentAtUtcstring($date-time)

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

senderstring
maximum: 9999

minimum: 0

maxLength: 4

minLength: 4

example: 5678

4 digit ION of sender

messageType

string

Enum:
Array [ 1 ]

6.1.2 Embedded Address block

Original message: Address to broadcast [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 delivery of samples. For the same reason ZIP code, City and Country are required in the address block.

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

Consider to use address block structure according to HL7-FHIR standard with extensions (https://hapifhir.io/hapi-fhir/apidocs/hapi-fhir-structures-r4/org/hl7/fhir/r4/model/Address.html), e.g.

Suggested format

Suggested field

Description

Mapping to NEW_ADD

StringType

city

The name of the city, town, suburb, village or other community or delivery center.

City CITY Req 40

StringType

country

Country - a nation as commonly understood or generally accepted.

Country COUNTRY Req 2

StringType

district

The name of the administrative area (county).

Address Line 2 ADDR_2 Opt 40

List <StringType>

line

This component contains the house number, apartment number, street name, street direction, P.O.

Address Line 3 ADDR_3 Opt 40

Period

period

Time period when address was/is in use.

new - Opt

StringType

postalCode

A postal code designating a region defined by the postal service.

ZIP code ZIP Req 10

StringType

state

Sub-unit of a country with limited sovereignty in a federally organized country.

new - Opt

StringType

text

Specifies the entire address as it should be displayed e.g. on a postal label. This may be provided instead of or as well as the specific parts.

Address Line 1 to Address Line 3, City, Country, Zip code - Opt

Enumeration <Address.AddressType>

type

Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses. Most addresses are both.). This is the underlying object with id, value and extensions. The accessor "getType" gives direct access to the value.

new - Req

Enumeration <Address.AddressUse>

use

The purpose of this address.

Institution Type INST_TYPE Req 3

StringType

contactPerson

The name of the contact person.

Contact person PERSON Opt 40

StringType

phone

The value is a telephone number used for voice calls.

Phone Number PHONE Req 20

StringType

fax

The value is a fax machine.

Fax Number FAX Opt 20

StringType

email

The value is an email address.

Email address EMAIL Opt 60



Not needed anymore, as the full address will be sent embedded in every request.

INST_ID Req 10



Obsolete. Accreditation is provided by S&M on the match list.

Accreditation Opt 5

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:


patient
wmdaId*integer
nullable: false

example: 1234

ID provided by the WMDA

patientId*string
maxLength: 17

nullable: false

example: P1234XX

Organisation unique identifier for 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{...}
diseasePhasestring
nullable: true
Enum:
Array [ 48 ]
ethnicitystring
nullable: true
Enum:
Array [ 20 ]
poolCountryCodestring
maxLength: 2

pattern: ^[A-Z]{2}

nullable: true

example: NL

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

abostring
nullable: true
Enum:
Array [ 4 ]
rhesusstring
nullable: true
Enum:
Array [ 2 ]
weightinteger
nullable: true

minimum: 1

maximum: 999

example: 76
sexstring
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:

  1. InfectiousDiseaseMarkerResultRequest (IDM_RES)
  2. TypingResponseRequest (TYP_RES)
  3. NoResultRequest (NO_RES)
  4. ReservationResultRequest (RSV_RES)

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.

In the future a block for ADCUs may come to play.

Donor typePayload
Adult donor

{

id*integer
nullable: false

example: 5176
donorRegistryIon*integer
nullable: false

minimum: 1000

maximum: 9999

example: 1234
abbreviationstring
example: NL-WMDA

maxLength: 24
haplotypeFrequencySetId*integer
nullable: true

minimum: 0

example: 15
status*string
nullable: false
Enum:
Array [ 3 ]
sex*string
nullable: true
Enum:
Array [ 2 ]
ethnicity*string
nullable: true
Enum:
Array [ 21 ]
idm*{...}
abo*string
nullable: true
Enum:
Array [ 4 ]
rhesus*string
nullable: true
Enum:
Array [ 2 ]
isSelected*boolean
nullable: true

true when this record has been marked as selected

resolutionScore*number
minimum: 0

maximum: 100

nullable: true

example: 54
resolutionString*string
minLength: 5

maxLength: 5

example: AP-A-

nullable: true

A - high-res P - low or intermediate, - no typing

grid*string
nullable: true

maxLength: 19

minLength: 19

example: 9991012070433202000
donorId*string
nullable: true

example: ABC1234

maxLength: 25
donorType*string
nullable: false
Enum:
Array [ 2 ]
lastContactDate*string($date)
nullable: true

minLength: 10

maxLength: 10
marrowDonationsCount*integer
nullable: true

example: 0
pbscDonationsCount*integer
nullable: true

example: 1
dateOfBirth*string($date)
nullable: true

maxLength: 10

example: 1961-05-27
donorAttributestring
maxLength: 3

nullable: true
kir{...}
weightinteger
nullable: true

minimum: 1

maximum: 999

example: 76
heightinteger
nullable: true

minimum: 1

maximum: 999

example: 161
collectionTypestring
nullable: true

Collection type, i.e. the willingness of the donor to donate in a specific manner. M = Marrow P = PBSC B = Both PBSC & Marrow

Enum:
Array [ 3 ]
transfusionsCountinteger
nullable: true

example: 1
pregnanciesCountinteger
nullable: true

example: 2
reservedPatientIdstring
nullable: true

example: 1234222ss
statusEndDatestring($date)
maxLength: 10

nullable: true
statusReasonstring
nullable: true

DO = Donor is too old,
DD = Donor died,
MR = Medical reasons,
PR = Personal reasons,
TX = After transplantation,
MO = Donor has moved,
UC = Unable to contact donor,
OT = Other reasons,
TQ = Typing questionable,
UK = Unknown

Enum: Array [ 10 ]
hla*{...}
mic*{...}
ccr5*string
nullable: true
Enum:
Array [ 3 ]
lastMedicalCheckupDatestring($date)
nullable: true

minLength: 10

maxLength: 10
registry*{...}

}

CBU

{

id*integer
nullable: false

example: 5176
donorRegistryIon*integer
nullable: false

minimum: 1000

maximum: 9999

example: 1234
abbreviationstring
example: NL-WMDA

maxLength: 24
haplotypeFrequencySetId*integer
nullable: true

minimum: 0

example: 15
status*string
nullable: false
Enum:
Array [ 3 ]
sex*string
nullable: true
Enum:
Array [ 2 ]
ethnicity*string
nullable: true
Enum:
Array [ 21 ]
idm*{...}
abo*string
nullable: true
Enum:
Array [ 4 ]
rhesus*string
nullable: true
Enum:
Array [ 2 ]
isSelected*boolean
nullable: true

true when this record has been marked as a selected

resolutionScore*number
minimum: 0

maximum: 100

nullable: true

example: 54
resolutionString*string
minLength: 5

maxLength: 5

example: AP-A-

nullable: true

A - high-res P - low or intermediate, - no typing

cordIdstring
nullable: true

maxLength: 25

example: 9991012070433202000
donorType*string
nullable: false
Enum:
Array [ 2 ]
collectionDatestring($date)
minLength: 10

maxLength: 10

nullable: true

example: 2021-05-27
volume*integer
example: 25

nullable: true
tncCount*number
example: 1140000000

nullable: true
cd34Count*number
example: 3900000

nullable: true
viability*integer
minimum: 0

maximum: 100

example: 97

nullable: true
attachedSegmentsCountinteger
nullable: true

minimum: 0

maximum: 99

example: 2
bankManufacturerIdWmda*integer
example: 5432

nullable: true
cbbAccreditationStatus*string
nullable: true
Enum:
Array [ 3 ]
localIdstring
example: 12345ABC

nullable: true
bagIdstring
example: ABCDE1234

nullable: true
dateOfBirth*string($date)
nullable: true

maxLength: 10

example: 1961-05-27
processingDatestring($date)
nullable: true

minLength: 10

maxLength: 10
processingMethodstring
nullable: true

HES = Hydroxy-Ethyl-Starch, DGS = Density Gradient Separation, CEN = Centrifuge, FIL = Filtration, FIC = FICOL, PER = PERCOL, OTH = Other

Enum:
Array [ 7 ]
processingMethodTypestring
nullable: true
Enum:
Array [ 5 ]
freezeDatestring($date)
nullable: true
freezeMethodstring
nullable: true
Enum:
Array [ 2 ]
reservedPatientIdstring
nullable: true

example: 1234222ss
productModificationsstring
nullable: true
Enum:
Array [ 7 ]
bagTypestring
nullable: true
Enum:
Array [ 4 ]
bagsCountinteger
minimum: 1

maximum: 99

example: 2

nullable: true
bankDistributionIdWmdainteger
nullable: true

example: 1234
bacterialCultureResultsstring
nullable: true

P = Positive N = Negative D = Not done

Enum:
Array [ 3 ]
fungalCultureResultsstring
nullable: true

P = Positive N = Negative D = Not done

Enum:
Array [ 3 ]
hemoglobinopathyScreeningStatusstring
nullable: true

DN = "Screening done, normal results" DU = "Screening done, unusual findings" NS = "No screening done" CD = "Can be done at time of release" NC = "Cannot be done" DT = "Thalassemia" DD = "Drepanocytosis"

Enum:
Array [ 7 ]
viabilityCellTypestring
nullable: true

type of cell tested for viability

Enum:
Array [ 3 ]
viabilityMethodstring
nullable: true

7A = 7AAD PI = Propidium Iodide TB = Trypan Blue OT = Other

Enum:
Array [ 4 ]
viabilityDatestring($date)
nullable: true
volumeFrozen*integer
example: 25

nullable: true
tncFrozenCount*number
example: 1020000000

nullable: true
cd34FrozenCount*number
example: 3700000

nullable: true
cfuFrozenCountinteger
nullable: true

minimum: 10000

maximum: 99990000

Total count of colony forming units (post processing, prior to cryopreservation)

mncFrozenCount*number
example: 430000000

nullable: true
ccr5string
nullable: true
Enum:
Array [ 3 ]
kir{...}
plasmaAliquotsCountinteger
minimum: 0

maximum: 99

nullable: true

Number of plasma aliquots available

redCellAliquotsCountinteger
minimum: 0

maximum: 99

nullable: true

Number of red cell fraction aliquots

nucleatedRbcFrozenCountinteger
minimum: 0

maximum: 9999000000

nullable: true

Total number of nucleated red blood cells (post processing, prior to cryopreservation)

serumAliquotsCountinteger
minimum: 0

maximum: 99

nullable: true
serumQuantitynumber
minimum: 0

maximum: 99.9

nullable: true
plasmaQuantitynumber
minimum: 0

maximum: 99.9

nullable: true
ctCompletionDatestring($date)
maxLength: 10
ctSampleTypestring
nullable: true

maxLength: 2

AS = CBU Contiguous Attached Segment, WB = Whole Blood Sample, RC = Red Cell Fraction (pellet), FP = Blood Spotted Filter Paper, ED = Extracted DNA

Enum:
Array [ 5 ]
dnaSamplesAvailableboolean
nullable: true
otherSamplesAvailableboolean
nullable: true
donorAttributestring
maxLength: 3

nullable: true
statusEndDatestring($date)
maxLength: 10

nullable: true
statusReasonstring
nullable: true

DO = Donor is too old, DD = Donor died, MR = Medical reasons, PR = Personal reasons, TX = After transplantation, MO = Donor has moved, UC = Unable to contact donor, OT = Other reasons, TQ = Typing questionable, UK = Unknown

Enum:
Array [ 10 ]
hla*{...}
mic{...}
registry{...}
cbb{...}
maternalInfo{...}

}

ADCU


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

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:

SendRetrieve
MessageResponse

Request

wmdaResponse
deliveredAtUtcstring($date-time)

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

referenceMessageIdstring($uuid)
responseType

string

Enum:
Array [ 3 ]

wmdaRemark[...]


Response

wmdaResponse
deliveredAtUtcstring($date-time)

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

referenceMessageIdstring($uuid)
responseTypestringEnum:
Array [ 3 ]
wmdaRemark[...]

MessageResponse payload

Meta block (6.1.1)

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

TextMessage payload

Meta block (6.1.1)

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

Alert Payload:

  • Level
  • Status
  • Message

Meta block (6.1.1)

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

Alert Update Payload:

  • Alert reference ID (GUID)
  • Level
  • Status
  • Message

Meta block (6.1.1)

  • No labels