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

 

Patient Identifiers

IdentifierDescription
patientId
  • Provided by the local registry system.  
  • Should be worldwide unique.
    • Should follow the construct of ION + local patient id. 
      • The ION 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.
connectPatientId
  • Provided by the local registry system
  • Must be worldwide unique
    • Must follow the construct of ION + local patient id.
      • The ION to be used is the IONn of the patient registering registry (PR).
  • Should be provided as a user-friendly (displayable) id for use on screens and on documentation
  • Should be the same as patientId whenever possible, assuming the patientId followed the construct of ION + local patient id
    • If the original patientId did not  follow the construct of ION + local patient id, then this the connectPatientId must  follow that construct, and will therefore be different than the patient id.
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.

3.2 - Create Patient

A POST to the patients endpoint is used to submit a patient to the Search & Match Service. This call returns a wmdaId for the patient, please be aware that in the current implementation a new wmdaId is assigned to a patient. When a patient was created before and stopped/anonymized (see Patient status), when this patient is created again, a new wmdaId will be assigned. Implementation tip: it might be valuable to save the wmdaId (old and new) in this specific use case.

Post
patients
FieldDetails
patientId

string

example: 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)
example: 1961-05-27
diagnosis{...}
diseasePhase

string

ethnicity

string

poolCountryCodestring
example: NL

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

transplantCentreIdstring
example: TC X
abo

string

rhesus

string

weightinteger
example: 76
sex

string

legalTermsboolean
example: true

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

FieldDetails
wmdaIdinteger
example: 123456

3.3 - Update Patient

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.

Put
patients
FieldDetails
patientIdstring
example: 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)
example: 1961-05-27
diagnosis{...}
diseasePhase

string

ethnicity

string

poolCountryCodestring
example: NL

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

transplantCentreIdstring
example: TC X
abo

string

rhesus

string

weightinteger
example: 76
sex

string

legalTermsboolean
example: true

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

wmdaId*integer
example: 123456
None specified

3.4 - Update Patient Status

A PUT to the patients/status endpoint is used to update a patient's search status with the Search & Match Service.  Allowable 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 (with the search ids). 


Put
patients/status
FieldDetails
wmdaId*integer
example: 123456
newStatus*

string

changeReasonstring
FieldDetails
wmdaId*integer
example: 123456
status*

string

changeReasonstring

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

3.5 - Retrieve Patient

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

Get
patients 
FieldDetails
wmdaId*integer
example: 123456
FieldDetails
patientId*string
example: XY1234P

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

status*

string

hla*{...}
idm*{...}
dateOfBirth*string($date)
example: 1961-05-27
diagnosis*{...}
diseasePhase*

string

ethnicity*

string

poolCountryCode*string
example: NL

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

transplantCentreId*string
example: TC X
abo*

string

rhesus*

string

weight*integer
example: 76
sex*

string

legalTerms*boolean
example: true

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

wmdaId*integer
example: 123456
lastUpdated*string($date-time)

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

lastViewed*string($date-time)

needed for sorting patients in the patient list

assignedUserName*string
example: janethesearchcoordinator@lunarregistry.com

typically the e-mail address of the user

3.6 - Retrieve Patient(s)

A GET to the patients/list endpoint 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

Field

Details

patientId

string
example: NL12345P

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

statuses

Array

string

example: List [ "NEW", "ACT", "SUS" ]

limit

integer
example: 250

offset

integer

onlyMyPatients

boolean
example: true

Only return patients assigned to current user.
Field

Details

paging
FieldDetails
limit*integer
offset*integer
totalCount*integer
patients
FieldDetails
wmdaId*integer
example: 123456
patientId*string
example: XY1234P

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

status*

string

dateOfBirth*string($date)
example: 1961-05-27
ethnicity*

string

lastUpdated*string($date-time)

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

lastViewed*string($date-time)

needed for sorting patients in the patient list

assignedUserName*string
example: janethesearchcoordinator@lunarregistry.com

typically the e-mail address of the user

requests*[...]

3.7 - Assign User To Patient

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
FieldDetails
wmdaId*integer
example: 123456
userName*string
example: janethesearchcoordinator@lunarregistry.com

typically the e-mail address of the user

FieldDetails
succeededboolean
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 updateRegisteredPatient message is used to update a registered patient with a partner registry.


Send (Post)Retrieve (Post)
updateRegisteredPatientRequestupdateRegisteredPatientRetrieve
FieldDetails
receivingRegistry*integer
example: 1234

4 digit ION of receiving registry

patient*Embedded Patient Block
FieldDetails
wmdaResponse*Embedded Meta Information Block
limitintege
shouldPeekboolean

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.

FieldDetails
generalInformationEmbedded General Information Block
originalMessage*Embedded Patient Block
metaInformation*Embedded Meta Block

3.10 - Patient 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

== Perform Donor Search ==

PR -[#green]> SM : <color #green> Start donor search </color>

activate SM #FFBBBB

SM -[#green]> PR : <color #green> Retrieve search results</color>

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