Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
maxLevel1

3.1 - Patient

...

Identification 

A patientId may be provided when registering a new patient in WMDA Search & Match.   Upon registration, a wmdaId will be assigned and returned.   The wmdaId itself is guaranteed to be globally unique, though it cannot guarantee that the same patient is not identified with another wmdaId.  registered by multiple organisations using the same patientId or with different patientId's within the same organisation. The wmdaId must be used to identify the patient in all calls to the Search, Match & Connect (SMC) service after the initial patient registration.

...

IdentifierDescription
patientId
  • Provided by the local registry system.  
  • Should be worldwide unique.
    • Should follow the construct of hub code ION + local patient id. 
      • The hub code should be the two-character ISO country code of the registry (e.g. DE for Germany)  In the case of multiple registries in one country, a replacement code will be assignedION 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.
wmdaId
  • Generated by the central (SMC) system.
  • Must be globally unique.
  • Must be used for all system-to-system patient identification after the initial patient registration.Should be displayed on screens and on documentation.

3.2 - Create Patient

...

A POST to the patients endpoint The CreatePatientRequest is used to submit a patient to the Search & Match Service.   This call returns a wmdaId for the patient.

Send
Post
patients
Expand
CreatePatient
titleRequest
Patient
...
FieldDetails
patientIdstring
maxLength: 17

nullable: true

example:
 P1234XX
98761234P

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{...}
diseasePhase

string
nullable: true

Enum:
Array [

 48 

 48 ]

ethnicity

string
nullable: true

Enum:
Array [

 21 

 21 ]

poolCountryCodestring
maxLength: 2

pattern: ^[A-Z]{2}

nullable: true

example: NL

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

transplantCentreIdstring
maxLength: 10

nullable: true

example: TC X
abo

string
nullable: true

Enum:
Array [

 4 

 4 ]

rhesus

string
nullable: true

Enum:
Array [

 2 

 2 ]

weightinteger
nullable: true

minimum: 1

maximum: 999

example: 76
sex

string
nullable: true

Enum:
Array [

 2 

 2 ]

legalTermsboolean
nullable: true

default: false

example: true

If not set to true, then patientId will not be stored.

Expand
titleResponse...
FieldDetails
wmdaIdinteger
example: 123456

nullable: false

3.3 - Update Patient

The UpdatePatientRequest A PUT to the patients endpoint is used to update a patient with the Search & Match Service.  An update to search relevant information, such as HLA, ethnicity or pool will result in a refresh of the search.

Send
Put
patients
Expand
UpdatePatient
titleRequest...
Field
Patient
Details
patientIdstring
maxLength: 17

nullable: true

example: 
P1234XX
XY1234P

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

A patient ID can only be updated when it was not set before. 

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 [ 21 ]

poolCountryCodestring
maxLength: 2

pattern: ^[A-Z]{2}

nullable: true

example: NL

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

transplantCentreIdstring
maxLength: 10

nullable: true

example: TC X
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 ]

legalTermsboolean
nullable: true

default: false

example: true

If not set to true, then patientId will not be stored.

wmdaId*integer
example: 123456

nullable: false
Expand
titleResponse...
None specified

3.4 - Update Patient Status

The UpdatePatientStatusRequest A PUT to the patients/status endpoint is used to update a patient's search status with the Search & Match Service.  Allowable statuses status values are SUS, PRE, ACT and STP.  A new patient is defaulted to the new (NEW) state.  Under the NEW state, searches must be requested explicitly.  When doing so, the patient is moved to the PRE state. Under the ACT state, searches will be kept up to date automatically.  SUS will stop automatic updates to searches, but results will remain for 42 days.  STP will terminate the search and delete all search results.

Image Removed

Include Page
BMDWPUB:Patient states and their effect on automatic updating of search results (full logic)
BMDWPUB:Patient states and their effect on automatic updating of search results (full logic)


Put
patients/status
Send
UpdatePatientStatus

Request

Expand
titleRequest...
FieldDetails
wmdaId*integer
example: 123456

nullable: false
newStatus*

string


maxLength: 3


nullable: false

Enum:
Array [ 4 ]

changeReasonstring
maxLength: 3
nullable: true

Reason why the change was made. Mandatory when changing to "STP"

Enum:
Array [ 21 ]
Expand
titleResponse...
FieldDetails
wmdaId*integer
example: 123456

nullable: false
newStatus
status*

string
maxLength: 3

nullable: false

Enum:
Array [

 4 

4 ]

changeReasonstring
maxLength: 3

nullable: true

Reason why the change was made. Mandatory when changing to "STP"

Enum:
Array [ 21 ]

3.5 - Retrieve Patient

The retrievePatientRequest A GET to the patients endpoint is used to retrieve an individual patient's information from the Search & Match Service.

Get
patients 
Expand
titleRequest...
FieldDetails
wmdaId*integer
example: 123456

nullable: false
Expand
titleResponse...
FieldDetails
patientId*string
maxLength: 17

nullable: true

example: XY1234P

Organisation unique identifier for patient. Cannot be set unless "legalTerms" is set to "true".

...

Do not use real names here.

status*

string
nullable: false

Enum:
Array [ 5 ]

hla*{...}
idm*{...}
dateOfBirth*string($date)
nullable: true

maxLength: 10

example: 1961-05-27
diagnosis*{...}
diseasePhase*

string
nullable: true

Enum:
Array [ 48 ]

ethnicity*

string
nullable: true

Enum:
Array [ 21 ]

poolCountryCode*string
maxLength: 2

pattern: ^[A-Z]{2}

nullable: true

example: NL

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

transplantCentreId*string
maxLength: 10

nullable: true

example: TC X
abo*

string
nullable: true

Enum:
Array [ 4 ]

rhesus*

string
nullable: true

Enum:
Array [ 2 ]

weight*integer
nullable: true

minimum: 1

maximum: 999

example: 76
sex*

string
nullable: true

Enum:
Array [ 2 ]

legalTerms*boolean
nullable: true

default: false

example: true

If not set to true, then patientId will not be stored.

wmdaId*integer
example: 123456

nullable: false
lastUpdated*string($date-time)
nullable: false

maxLength: 255

needed to help determine when patient can be automatically moved to STP state

lastViewed*string($date-time)
nullable: false

maxLength: 255

needed for sorting patients in the patient list

assignedUserName*string
minLength: 4

maxLength: 100

nullable: true

example: janethesearchcoordinator@lunarregistry.com

typically the e-mail address of the user

...

  • wmdaId

3.6 - Retrieve Patient

...

(s)

A GET to the patients/list endpoint The listPatientsRequest is used to retrieve multiple patient's information from the Search & Match Service.  You may define a page size, a specific page number, a series of allowable statuses and may limit to only patients assigned to you..

Post
patients/list
Expand
titleRequest...

Field

Details

patientId

string
maxLength: 17

nullable: true
example: NL12345P

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

limit

integer
nullable: true
default: 100
example:250

offset

integer
nullable: true
default: 0

onlyMyPatients

boolean
default: 0
nullable: true
example: true

Only return patients assigned to current user.
Expand
titleResponse...
Field

Details

paging
Expand
title...
FieldDetails
limit*integer
default: 100
offset*integer
default: 0
totalCount*integer
minimum: 0
patients
Expand
title...
FieldDetails
wmdaId*integer
example: 123456

nullable: false
patientId*string
maxLength: 17

nullable: true

example: XY1234P

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

status*

string
nullable: false

Enum:
Array [ 5 ]

dateOfBirth*string($date)
nullable: true

maxLength: 10

example: 1961-05-27
ethnicity*

string
nullable: true

Enum:
Array [ 21 ]

lastUpdated*string($date-time)
nullable: false

maxLength: 255

needed to help determine when patient can be automatically moved to STP state

lastViewed*string($date-time)
nullable: false

maxLength: 255

needed for sorting patients in the patient list

assignedUserName*string
minLength: 4

maxLength: 100

nullable: true

example: janethesearchcoordinator@lunarregistry.com

typically the e-mail address of the user

requests*[...]
Send
ListPatients
  • limit
  • offset
  • status
  • onlyMyPatients

    3.7 - Assign User To Patient

    The AssignUserToPatient A PUT to the patients/user endpoint is used to assign a particular user name to a patient within the Search & Match Service.

    Put
    patients/user
    Send
    AssignUserToPatient

    Request

    Expand
    titleRequest...
    FieldDetails
    wmdaId*integer
    example: 123456

    nullable: false
    userName*string
    minLength: 4

    maxLength: 100

    nullable: true

    example: janethesearchcoordinator@lunarregistry.com

    typically the e-mail address of the user

    Expand
    titleResponse...
    FieldDetails
    succeededboolean
    default: true
    messagestring
    example: Successfully assigned janethesearchcoordinator@lunarregistry.com

    3.8 - Register Patient   

    There is no registerPatientRequest endpoint.  A patient is registered with a partner registry at the time of request in the form of an embedded Patient block - described in the Admin chapter. 

    3.9 - Update Registered

    ...

    Patient (PAT_UPD)

    The updateRegisteredPatientRequest updateRegisteredPatient message is used to update a registered patient with a partner registry.  The central hub will review the contents and update any values that are already stored in the Search & Match system.


    string
    Send (Post)Retrieve
    UpdateRegisteredPatientUpdateRegisteredPatientRetrieve
    (Post)
    updateRegisteredPatientupdateRegisteredPatientRetrieve

    Patient

    wmdaId
    Expand
    titleRequest...
    FieldDetails
    receivingRegistry
    *integer
    nullable
    maximum: 
    false
    9999
    example
    minimum: 
    1234

    ID provided by the WMDA

    patientId*
    0

    maxLength: 
    17
    4
    nullable
    minLength: 
    false
    4
    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

    • MetaInformation
    • Sent payload

    3.10 - Message Flows

    1234

    4 digit ION of receiving registry

    patient*Embedded Patient Block
    Expand
    titleResponse...
    FieldDetails
    wmdaResponse*Embedded WMDA Response Block
    Expand
    titleRequest...
    limitinteger
    default: 100

    shouldPeekboolean
    default: false

    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. If that message (no longer) exists then no message will be returned.

    Expand
    titleResponse...
    FieldDetails
    generalInformationEmbedded General Information Block
    originalMessage*Embedded Patient Block
    metaInformation*Embedded Meta Block

    3.10 - Patient Flows


    PlantUML Render Macro
    titlePatient Flows

    participant "Patient Registry" as PR

    control "Match-Connect" as MC

    control "Search & Match\nService" as SM

    participant "Donor Registry" as DR

    skinparam SequenceMessageAlign center

    skinparam dpi 92

    == Register Patient ==

    PR -> SM : Create Patient

    activate SM #FFBBBB

    SM -> PR : Return WMDA Patient ID

    deactivate SM

    == Modify Patient ==

    PR -> SM : Update Patient

    PR -> SM : Assign User To Patient

    == Retrieve Patient(s) ==

    PR -> SM : Retrieve Patients

    activate SM #FFBBBB

    SM -> PR : Return One or More Patients

    deactivate SM

    == Making Requests ==

    PR -[#dodgerblue]> DR : <color #dodgerblue> Request a Donor (patient embedded) </color>

    PR -[#dodgerblue]> DR : <color #dodgerblue> Update Registered Patient </color>

    3.11 - Patient Life Cycle

    Include Page
    BMDWPUB:Patient life cycle
    BMDWPUB:Patient life cycle
    Image Removed