Versions Compared

Old Version 31

changes.mady.by.user Matt Prestegaard

Saved on

compared with

New Version Current

changes.mady.by.user Alicia Venter

Saved on

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.

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.

Proposal:  Make patientId required where possible.  WMDA office to investigate making mandatory in existing Search & Match Service.  If there are legitimate reasons not to (amongst TCs or other), we can add a requirement that the patientId become required at the point of request
  • .
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

3.2 - Create PatientThe 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.

CreatePatientRequest (/api/v2/patients)

Changes to be considered:

Post
patients
Expand
titleRequest...
FieldDetails
Patient Identification
patientIdstring
maxLength: 17
nullable: 
true → change to false

3.3 - Update Patient

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

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.

UpdatePatientRequest (/api/v2/patients)

Changes to be considered:

Put
patients
Expand
titleRequest...
FieldDetails
Patient Identification
patientIdstring
nullable: true → change to false

3.4 - Register Patient   Image Removed

...

The registerPatientRequest is used to register a patient with a partner registry.  This message accompanies all requests.

Proposal:  Entire payload may be sent by the sending registry.  The central hub can review the contents and update any relevant values that are (already) stored in the Search & Match system.  The response of the api will provide results (fields / values) of the updates made.

RegisterPatientRequest

Same payload as UpdatePatientRequest (/api/v2/patients).  Additional fields to be considered:

...

string

nullable: false

...

string

nullable: false

3.5 - Update Registered Patient    Image Removed

...

The 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

Same payload as RegisterPatientRequest.

3.5/6 - Update Patient Status Image Removed

...

UpdatePatientStatusRequest

The updatePatientStatusRequest is used to communicate changes in patient status.

Statuses permitted in EMDIS are PRE, ACT, SUS, STP.  PRE / ACT may have some relevance to Search & Match Service.  SUS / STP may have relevance to Search, Match & Connect.

From EMDIS semantics:

"After the status has been set to suspended (SUS), the transplant centre is fully responsible for pending requests. If a transplant centre is no longer interested in a certain pending request, the request has to be cancelled by the transplant centre by means of a REQ_CAN message. If the transplant centre does not explicitly cancel a pending request, the request will be processed normally by the requested hub.

After the status has been set to stopped (STP), all pending requests but WOR_REQ are cancelled automatically at the remote hub. In this case, no REQ_CAN messages have to be sent by the transplant centre. The only way to reactivate the patient is a PAT_UPD / PAT_STAT message pair. The PAT_UPD is necessary since it cannot be guaranteed that the patient information is still stored at the remote hub. It is up to each hub how long patient information is retained after the search was stopped.

However, it makes no sense to delete a patient who is in workup. Patient searches are sometimes not stopped at remote hubs although the search is not really active any more. This wastes time for matching and gives bad statistics about search length and search counts.

All hubs are strongly encouraged to monitor their international searches closely and stop or suspend them if not longer needed. The searched hub is allowed to send reminder faxes with patients without activities to the patient’s hub."

Fields for consideration:

...

string

nullable: false

...

string

nullable: false

...

integer

nullable: false

...

string

nullable: true

...

string

nullable: false

...

string

nullable: true

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.

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

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
titleRequest...
FieldDetails
wmdaId*integer
example: 123456
nullable: false
newStatus*

string
nullable: false

Enum:
Array [ 4 ]

changeReasonstring
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
status*

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 ]

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

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
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*[...]

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


Send (Post)Retrieve (Post)
updateRegisteredPatientupdateRegisteredPatientRetrieve
Expand
titleRequest...
FieldDetails
receivingRegistry*integer
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 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

3.7 - Register Patient with local partners 

3.8 - Replace EMDIS PAT_UPD msg

...