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.
...
| Identifier | Description |
|---|
| 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
The CreatePatientRequest 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.
| SendPost |
|---|
| CreatePatientpatients |
| Expand |
|---|
| | Field | Details |
|---|
| patientId | string
maxLength: 17
nullable: true
example: XY1234P 98761234POrganisation unique identifier for patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here. | | 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: NLISO 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: trueIf not set to true, then patientId will not be stored. |
|
| Expand |
|---|
| | Field | Details |
|---|
| wmdaId | integer
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.
| SendPut |
|---|
| UpdatePatientpatients |
| Expand |
|---|
| | Field | Details |
|---|
| patientId | string
maxLength: 17
nullable: true
example: XY1234POrganisation 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 | {...} | | 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: NLISO 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: trueIf not set to true, then patientId will not be stored. | | wmdaId* | integer
example: 123456
nullable: false |
|
|
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 |
| Expand |
|---|
| | Field | Details |
|---|
| wmdaId* | integer
example: 123456
nullable: false | | newStatus* | string
maxLength: 3
nullable: false Enum:
Array [ 4 ] | | changeReason | string
maxLength: 3
nullable: trueReason why the change was made. Mandatory when changing to "STP" Enum:
Array [ 21 ] |
|
| Expand |
|---|
| | Field | Details |
|---|
| wmdaId* | integer
example: 123456
nullable: false | | newStatusstatus* | string
maxLength: 3
nullable: false Enum:
Array [ 4 ] | | changeReason | string
maxLength: 3
nullable: trueReason 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.
| SendGet |
|---|
| RetrievePatientpatients |
| Expand |
|---|
| | Field | Details |
|---|
| wmdaId* | integer
example: 123456
nullable: false |
|
| Expand |
|---|
| | Field | Details |
|---|
| patientId* | string
maxLength: 17
nullable: true
example: XY1234POrganisation 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: NLISO 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: trueIf not set to true, then patientId will not be stored. | | wmdaId* | integer
example: 123456
nullable: false | | lastUpdated* | string($date-time)
nullable: false
maxLength: 255needed to help determine when patient can be automatically moved to STP state | | lastViewed* | string($date-time)
nullable: false
maxLength: 255needed for sorting patients in the patient list | | assignedUserName* | string
minLength: 4
maxLength: 100
nullable: true
example: janethesearchcoordinator@lunarregistry.comtypically the e-mail address of the user |
|
|
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.
| SendPost |
|---|
| ListPatientspatients/list |
| Expand |
|---|
| 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
Maximum number of patients per page. nullable: true
default: 100
Default value : 100example:250
| offset | integer
Starting position of the requested page. Default value nullable: true
default: 0 | status | array[string] the statuses that the patients are allowed to have Available values : NEW, PRE, ACT, SUS, STP Default value : null Example : ACT|NEW | onlyMyPatients | onlyMyPatients | booleanboolean
default: 0
nullable: true
example: true
Only return patients assigned to current user. Based on username property in JWT token. Does not work with machine credentials (direct API connection without WMDA frontend).Default value : false
|
|
| Expand |
|---|
| | Field | |
|---|
| paging | | Expand |
|---|
| | Field | Details |
|---|
| limit* | integer
default: 100 | | offset* | integer
default: 0 | | totalCount* | integer
minimum: 0 |
|
| | patients | | Expand |
|---|
| | Field | Details |
|---|
| wmdaId* | integer
example: 123456
nullable: false | | patientId* | string
maxLength: 17
nullable: true
example: XY1234POrganisation 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: 255needed to help determine when patient can be automatically moved to STP state | | lastViewed* | string($date-time)
nullable: false
maxLength: 255needed for sorting patients in the patient list | | assignedUserName* | string
minLength: 4
maxLength: 100
nullable: true
example: janethesearchcoordinator@lunarregistry.comtypically the e-mail address of the user | | requests* | [...] |
|
|
|
|
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.
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.
| Send (Post) | Retrieve (Post) |
|---|
| UpdateRegisteredPatientupdateRegisteredPatient | UpdateRegisteredPatientRetrieveupdateRegisteredPatientRetrieve |
| Expand |
|---|
| | Field | Details |
|---|
| recipientreceivingRegistry* | integer
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 12344 digit ION of recipientreceiving registry | | patient* | Embedded Patient Block |
|
| Expand |
|---|
| | Field | Details |
|---|
| deliveredAtUtc | string($date-time) Server-supplied timestamp showing time of Message delivery to recipient's inbox queue | | referenceMessageId | string($uuid) | | responseType | string Enum:
Array [ 3 ] | | remark | [...] | | wmdaResponse* | Embedded WMDA Response Block |
|
| | Expand |
|---|
| | limit | integer
default: 100
| | shouldPeek | boolean
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 |
|---|
| | No parameters specified |
|
3.10 -
...
Patient Flows
| PlantUML Render Macro |
|---|
|
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