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

Compare with Current View Page History

« Previous Version 34 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. (HP's suggestion, requires discussion/checking the standard regarding the institution ID field, the accreditation field and the extension of the use field):

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 ADD_NEW

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.

new - Opt

Enumeration
<Address.AddressType>

type

Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g.

new - Req

Enumeration
<Address.AddressUse>

use

The purpose of this address.

Institution Type INST_TYPE Req 3


Missing fields from ADD_NEW with Albert's comments for consideration:

  • Institution Identification INST_ID Req 10 - not needed anymore, as the full address will be sent embedded in every request
  • Address Line 1 ADDR_1 Req 40 - needs to be added, as the structure above has it only in field "text" that seems optional
  • Contact person PERSON Opt 40 - better to have a separate field
  • Phone Number PHONE Req 20 - better to have a separate field
  • Fax Number FAX Opt 20 - better to have a separate field
  • Email address EMAIL Opt 60 - better to have a separate field
  • Accreditations obtained ACCREDITATION Opt 5 - is it still being used by anyone?
    • Position 1: NetCord-FACT
    • Position 2: AABB
    • Position 3: to be defined
    • Position 4: to be defined
    • Position 5: to be defined

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: trueEnum:
Array [ 48 ]
ethnicitystring
nullable: trueEnum:
Array [ 20 ]
poolCountryCodestring
maxLength: 2
pattern: ^[A-Z]{2}
nullable: true
example: NL

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

abostring
nullable: trueEnum:
Array [ 4 ]
rhesusstring
nullable: trueEnum:
Array [ 2 ]
weightinteger
nullable: true
minimum: 1
maximum: 999
example: 76
sexstring
nullable: trueEnum:
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: falseEnum:
Array [ 3 ]
sex*string
nullable: trueEnum:
Array [ 2 ]
ethnicity*string
nullable: trueEnum:
Array [ 21 ]
idm*{...}
abo*string
nullable: trueEnum:
Array [ 4 ]
rhesus*string
nullable: trueEnum:
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: falseEnum:
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: trueEnum:
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: falseEnum:
Array [ 3 ]
sex*string
nullable: trueEnum:
Array [ 2 ]
ethnicity*string
nullable: trueEnum:
Array [ 21 ]
idm*{...}
abo*string
nullable: trueEnum:
Array [ 4 ]
rhesus*string
nullable: trueEnum:
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: falseEnum:
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: trueEnum:
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: trueEnum:
Array [ 5 ]
freezeDatestring($date)
nullable: true
freezeMethodstring
nullable: trueEnum:
Array [ 2 ]
reservedPatientIdstring
nullable: true
example: 1234222ss
productModificationsstring
nullable: trueEnum:
Array [ 7 ]
bagTypestring
nullable: trueEnum:
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: trueEnum:
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
post_api_v1_MessageResponse

get_api_v1_MessageResponseRetrieve

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
post_api_v1_TextMessageRequest

get_api_v1_TextMessageRetrieve

  • Patient
  • Donor
  • Text

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

get_api_v1_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

get_api_v1_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