Versions Compared

Old Version 3

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.

 

Patient Identifiers

IdentifierDescription
patientId
  • Provided by the local registry system.  
  • Should be worldwide unique.
    • Should
be provided as a user-friendly (displayable) id for use on screens and on documentation.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. DE12345)  
  • In the case of multiple registries in one country a replacement code will be assigned.
TODO:  Discuss whether patientId should be made required
      • 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.
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 register a patient.

    CreatePatientRequest (/api/v2/patients)

    ...

    submit a patient to the Search & Match Service. This call returns a wmdaId for the patient.

    Post
    patients
    Expand
    titleRequest...
    FieldDetails
    patientIdstring
    maxLength: 17
    nullable: 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

    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
    Expand
    titleRequest...
    FieldDetails
    patientIdstring
    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

    ...