3.1 - Patient
...
Identification
Anchor3.1 - Patient Identification3.1 - Patient IdentificationA 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.
TODO: Discuss whether patientId should be made required within createPatientRequest and updatePatientRequest Risk of nullable is that duplicate patients may be created. Some transplant centers or patient registries may have concerns with sharing a patientId before the point of donor request. If we make patientId required then we should also consider enforcing uniqueness. Decision on nullability deferred to the business requirements group. |
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 Anchor3.2 - Create Patient3.2 - Create PatientThe CreatePatientRequest is used to submit a patient to the Search & Match Service. This call returns a wmdaId for the patient.
CreatePatientRequest (/api/v2/patients)
Patient Identification |
---|
patientId | string maxLength: 17 nullable: true |
|
|
Patient HLAhlaHLAPatient DiagnosisdiagnosisDiagnosisRequestPatient Disease PhasediseasePhasestring example: 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) |
|
|
Patient Date of BirthdateOfBirthstring($date-time)Patient IDMsidmIdmRequestmaxLength: 10 example: 1961-05-27 | diagnosis | {...} | diseasePhase | string |
|
|
Patient EthnicityEnum: Array [ 48 ] | ethnicity | string nullable: true |
|
|
Patient's Country CodeEnum: Array [ 21 ] | poolCountryCode | string maxLength: 2 pattern: ^[A-Z]{2} nullable: true |
|
|
Patient Transplant Centre example: NLISO 3166-1 alpha-2 Country Code (capitalized) | transplantCentreId | string maxLength: 10 nullable: true
|
|
|
Patient Blood Groupexample: TC X | abo | string nullable: true |
|
|
Patient RhesusEnum: Array [ 4 ] | rhesus | string nullable: true |
|
|
Patient WeightEnum: Array [ 2 ] | weight | integer |
|
|
($int32)Patient Sex minimum: 1 maximum: 999 example: 76 | sex | string nullable: true |
|
|
ConsentEnum: Array [ 2 ] | legalTerms | boolean |
|
|
(If you keep the legalTerms value at "false" or don't send it when creating a new patient, you have indicated you will not comply with legal terms and therefore are not allowed to store a pId. In that case the pId is set to the same value as the wmdaId. This behaviour mirrors the behaviour in the web GUI of WMDA Search & Match. If you click on the "No, I don't have consent" button you are also not allowed to store a patient ID or comment.) Expected response:
...
3.3 - Update Patient
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
3.3 - Update PatientThe UpdatePatientRequest A PUT to the patients endpoint is used to update a patient with the Search & Match Service.
UpdatePatientRequest
An update to search relevant information, such as HLA, ethnicity or pool will result in a refresh of the search.
Patient Identification
WMDA Patient IdentificationwmdaIdstringPatient HLAhlaHLAPatient DiagnosisdiagnosisDiagnosisRequestPatient Disease PhasediseasePhasestring
nullable: truePatient IDMsidmIdmRequestPatient Date of BirthdateOfBirthstring($date-time)
nullable: true 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 ] |
|
|
Patient Ethnicity truePatient's Country Code true Enum: Array [ 21 ] | poolCountryCode | string maxLength: 2 pattern: ^[A-Z]{2} nullable |
|
|
: truePatient Transplant Centre: true example: NLISO 3166-1 alpha-2 Country Code (capitalized) | transplantCentreId | string maxLength: 10 nullable: |
|
|
truePatient Blood Group true example: TC X | abo | string nullable: true Enum: |
|
|
truePatient Rhesus Array [ 4 ]
| rhesus | string nullable: |
|
|
truePatient Weight true Enum: Array [ 2 ] | weight | integer |
|
|
($int32): truePatient Sex: true minimum: 1 maximum: 999 example: 76 | sex | string nullable: true Enum: |
|
|
trueConsent Array [ 2 ]
| legalTerms | boolean |
|
|
(If you keep the legalTerms value at "false" or don't send it when creating a new patient, you have indicated you will not comply with legal terms and therefore are not allowed to store a pId. In that case the pId is set to the same value as the wmdaId. This behaviour mirrors the behaviour in the web GUI of WMDA Search & Match. If you click on the "No, I don't have consent" button you are also not allowed to store a patient ID or comment.) 3.4 - Register Patient
Image Removed
...
The registerPatientRequest is used to register a patient with a partner registry. This message accompanies all requests.
RegisterPatientRequest
...
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
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.
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 |
Expand |
---|
| Field | Details |
---|
wmdaId* | integer example: 123456 nullable: false | newStatus* | string nullable: false Enum: Array [ 4 ] | changeReason | string nullable: trueReason why the change was made. Mandatory when changing to "STP" Enum: Array [ 21 ] |
|
Expand |
---|
| Field | Details |
---|
wmdaId* | integer example: 123456 nullable: false | status* | 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
A GET to the patients endpoint is used to retrieve an individual patient's information from the Search & Match Service.
Get |
---|
patients |
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 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 |
---|
| 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 |
---|
| 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
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 updateRegisteredPatient message
3.5 - Update Registered Patient
Image Removed
Anchor3.5 - Update Registered Patient3.5 - Update Registered PatientThe updateRegisteredPatientRequest is used to update a registered patient with a partner registry.
TODO: Discuss whether we need this message. Does the requesting registry take responsibility for sending updates to the partners it wants OR does SMC take responsibility for updating patients with all registries with which the patient has been shared?
UpdateRegisteredPatientRequest
...
Send (Post) | Retrieve (Post) |
---|
updateRegisteredPatient | updateRegisteredPatientRetrieve |
Expand |
---|
| Field | Details |
---|
receivingRegistry* | integer maximum: 9999 minimum: 0 maxLength: 4 minLength: 4 example: 12344 digit ION of receiving registry | patient* | Embedded Patient 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. |
|
|
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 |
---|
|
...