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

Compare with Current View Page History

« Previous Version 24 Next »

6.1 Embedded Meta block

The additional meta-information "blocks" are added to ensure the receiving registry is aware of:

  • What registry sent the information (sender)
  • What type of information is contained
  • A message identifier
  • A timestamp
  • Any failed validations detected by the Match Connect system


metaInformation{

Field nameformatDescription
messageIdstring($uuid)ID of the originally sent message
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 the sender
messageTypestringTo be designed and described. The idea is to help registry's MC admin to analyze possible issues reported in validationDetails field. AM: I think this is an excessive information, as messageId should be sufficient. 
validationDetails
To be designed and described. The idea is to supply the concerns of the central hub validation system that are acceptable but require attention of the receiving registry.

}

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

Address block structure (HP's suggestion, requires discussion regarding the accreditation field and extension of the use field):

https://hapifhir.io/hapi-fhir/apidocs/hapi-fhir-structures-r4/org/hl7/fhir/r4/model/Address.html

e.g.

StringType

city

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

StringType

country

Country - a nation as commonly understood or generally accepted.

StringType

district

The name of the administrative area (county).

List<StringType>

line

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

Period

period

Time period when address was/is in use.

StringType

postalCode

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

StringType

state

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

StringType

text

Specifies the entire address as it should be displayed e.g.

Enumeration
<Address.AddressType>

type

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

Enumeration
<Address.AddressUse>

use

The purpose of this address.


  • Institution Type INST_TYPE Req 3
  • Institution Identification INST_ID Req 10
  • Address Line 1 ADDR_1 Req 40
  • Address Line 2 ADDR_2 Opt 40
  • Address Line 3 ADDR_3 Opt 40
  • Contact person PERSON Opt 40
  • ZIP code ZIP Req 10
  • City CITY Req 40
  • Country COUNTRY Req 2
  • Phone Number PHONE Req 20
  • Fax Number FAX Opt 20
  • Email address EMAIL Opt 60
  • Accreditations obtained ACCREDITATION Opt 5
    • Position 1: NetCord-FACT
    • Position 2: AABB
    • Position 3: to be defined
    • Position 4: to be defined
    • Position 5: to be defined

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

  • Request

  • 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.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 ]
registryAccreditationStatus*string
nullable: trueEnum:
Array [ 2 ]
firstAccreditationYear*number
minimum: 1990
maximum: 2100
nullable: true
example: 2019
matchClass*string
example: 9/10
nullable: false
nmdpGrade*string
maxLength: 5
example: MPPMP
nullable: true

A - high-res match on ARD, P - probable match, M - sure Mismatch

zeroMismatchProbability*integer
minimum: 0
maximum: 100
nullable: true
oneMismatchProbability*integer
nullable: true
minimum: 0
maximum: 100
twoMismatchProbability*integer
nullable: true
minimum: 0
maximum: 100
aLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
bLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
cLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
drLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
dqLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
inexplicable*boolean
matchingInformationDpb1*{...}
mismatches*[...]
searchResultRecordState*string
nullable: false
default: ExistingEnum:
Array [ 4 ]
searchResultRecordStateUpdatedAt*string($date-time)
nullable: true
maxLength: 255

date and time when the last change was registered in the system

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 ]
registryAccreditationStatus*string
nullable: trueEnum:
Array [ 2 ]
firstAccreditationYear*number
minimum: 1990
maximum: 2100
nullable: true
example: 2019
matchClass*string
example: 9/10
nullable: false
nmdpGrade*string
maxLength: 5
example: MPPMP
nullable: true

A - high-res match on ARD, P - probable match, M - sure Mismatch

zeroMismatchProbability*integer
minimum: 0
maximum: 100
nullable: true
oneMismatchProbability*integer
nullable: true
minimum: 0
maximum: 100
twoMismatchProbability*integer
nullable: true
minimum: 0
maximum: 100
aLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
bLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
cLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
drLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
dqLocusMatchProbability*integer
nullable: true
minimum: 0
maximum: 100
inexplicable*boolean
matchingInformationDpb1*{...}
mismatches*[...]
searchResultRecordState*string
nullable: false
default: ExistingEnum:
Array [ 4 ]
searchResultRecordStateUpdatedAt*string($date-time)
nullable: true
maxLength: 255

date and time when the last change was registered in the system

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

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

6.6 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.7 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.8 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

  • No labels