Purpose

This WS is designed to register patient in the system based on data received from Patient Information System.

Key points

1. This method must be used only by Auth front-end

2. Validates session token (jwt) that was obtained as a result of signed content as well as patient data validation by https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17525605808 and signed content, skips revalidation of patient data.

3. Creates user as well as patient in the system

4. Generates access token for further actions

Specification

Apiary

Validate request

Validate signed content

• Check signed_content and signed_content_encoding are submitted

  • in case of error - return 422 ('required property signed_content was not present' or ‘required property signed_content_encoding was not present')

• Check signed content is a valid base64

  • in case of error - return 422 ('Invalid signed content')

• Check signed content encoding is a 'base64' value

  • in case of error - return 422 ('is invalid')

• Check digital signature is valid

  • in case of error - return 400

Validate applicant

• Get drfo value from digital signature of signed_content

• Check that applicant user exists in mithril database, users table, with tax_id = drfo from digital signature and is_active = true

  • in case of error - return 404 ('Applicant user not found.')

• Check that applicant user is not blocked (is_blocked <> true)

  • in case of error - return 401 ('Applicant user is blocked.')

• Check that applicant user has active person in mpi database, persons table, with id = person_id from found applicant user, status = active and is_active = true

  • in case of error - return 404 ('Applicant person not found.')

• Check that applicant user has active person with appropriate age (greater than no_self_auth_age global parameter)

  • in case of error - return 401 ('Incorrect applicant person age for such an action.')

Validate JWT

Ensure that token provided in payload (obtained from https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17525605808 ) is valid

• validate JWT signature

• validate issuer (iss = Ehealth)

• validate aud (aud = pis-registration)

• validate expiration (exp in the future)

• validate content_hash equals to MD5 hash value of signed_content field

  • in case of any error - return 401 ('Unauthorized')

Validate person registration request

• Validate person data according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17525605954/Rules+to+validate+patient+data#Person-with-confidant

• Check that confidant_person.person_id is the same person who signed request (confidant_person.person_id = x-person-id)

  • in case of error - return 422 ('Confidant person and signer must be the same')

• Check patient_signed field value equals to ‘true’

  • in case of error - return 422 ('expected true but got false for attribute %{attribute}')

• Check process_disclosure_data_consent field value equal to ‘true’

  • in case of error - return 422 ('expected true but got false for attribute %{attribute}')

Service logic

Search person

1. Search for existing active person in mpi database with data from person registration request according to existing process, described here https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986/Create+Update+person+request#Search-person
   Calculate score of comparison between found active persons and person registration request using existing deduplication process, described here https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/583402355
   Compare found score with PIS_ONLINE_DEDUPLICATION_MATCH_SCORE config parameter, set to ‘0.95’:

   1. If one active person with match score > PIS_ONLINE_DEDUPLICATION_MATCH_SCORE was found - save its person_id and proceed to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706777/RC_PIS.+Patient+sign-up+registration+DRACS+2.0#Check-confidant-person-relationship

   2. If more than one active person with match score > PIS_ONLINE_DEDUPLICATION_MATCH_SCORE was found - return 401 ('It is impossible to uniquely identify the person.')

   3. If no active person with match score > PIS_ONLINE_DEDUPLICATION_MATCH_SCORE was found - proceed to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706777/RC_PIS.+Patient+sign-up+registration+DRACS+2.0#Create-person

Create person

1. Create new person in mpi database, set values in following tables based on person registration request:

   1. persons table

   2. person_phones table

   3. person_addresses table

   4. person_documents table

   5. person_authentication_methods table

2. Save signed content to media storage

3. Submit person on verification - create record in person_verifications table for person_id, set values for each verification stream:

   1. Manual NHS verifiation

      1. if $.person.confidant_person exists in person registration request or $.person.documents contains document with type = 'PERMANENT_RESIDENCE_PERMIT' or  $.person.unzr is not empty and first 8 digits of $.person.unzr != $.person.birth_date

         1. set nhs_verification_status = NOT_VERIFIED

         2. set nhs_verification_reason = DOCUMENTS_TRIGGERED

      2. else - scan copies of persons documents are not needed, set verification status according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706567/RC_Sign+person+request+v2+DRACS+2.0#Manual-NHS-verification

   2. DRFO registry verification - according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706567/RC_Sign+person+request+v2+DRACS+2.0#DRFO-registry-verification

   3. DRACS death acts registry verification - according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706567/RC_Sign+person+request+v2+DRACS+2.0#DRACS-death-acts-registry-verification

   4. DRACS birth acts registry verification - according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706567/RC_Sign+person+request+v2+DRACS+2.0#DRACS-birth-acts-registry-verification

   5. DRACS name change acts registry verification - according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706567/RC_Sign+person+request+v2+DRACS+2.0#DRACS-birth-acts-registry-verification

   6. Legal capacity verification - according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706567/RC_Sign+person+request+v2+DRACS+2.0#Legal-capacity-verification

4. Calculate cumulative person verifiation status according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18201706567/RC_Sign+person+request+v2+DRACS+2.0#Calculate-cumulative-verification-status

Create confidant person relationship

Service must create unverified relationship between confidant person and related person for further verification by responsible person on NHS side

• Call https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17525605929 . Set values:

  • confidant_person_id = $request.confidant_person.person_id

  • person_id = person.id

  • verification_status = “VERIFICATION_NEEDED”

  • verification_reason based on relationship document:

    • if documents_relationship contains document with type BIRTH_CERTIFICATE, set verification_reason = “ONLINE_TRIGGERED”

    • if documents_relationship does not contain document with type BIRTH_CERTIFICATE, set verification_reason = “ONLINE_TRIGGERED_BY_PIS_REGISTRATION_VIA_CONFIDANT”

  • confidant_person_relationship_documents = person.confidant_person.documents_relationship

  In case if persons age < person_full_legal_capacity_age years old:

  • calculate relationship_expiration_date - date when person becomes person_full_legal_capacity_age years old

  • check if $.active_to <= relationship_expiration_date

    • if true - set active_to = $.active_to

    • else - set active_to = relationship_expiration_date

• Check existing authentication method for person with type = THIRD_PERSON, ended_at > true or null and value = $request.confidant_person.person_id

  • if not found - create new authentication method for person, set values:

    • type = THIRD_PERSON

    • value = person.confidant_person.person_id

    • started_at = now()

    • ended_at: if person.age < no_self_auth_age

      • ended_at = person.birth_date + no_self_auth_age - 1d

        • else end_date = null

  • if found - update authentication method for person, set values:

    • ended_at: if person.age < no_self_auth_age

      • ended_at = person.birth_date + no_self_auth_age - 1d

        • else end_date = null

Check confidant person relationship

Check relationship using https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17525605916 and having applicant person_id as confidant_person_id and person_id

1. If relationship doesn’t exist - check that relationship can be created for found patient id using logic: if persons age is greater then no_self_registration_age global parameter, but less then person_full_legal_capacity_age global parameter, check that person does not have document with type from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter or person has document with type from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter and legal_capacity_verification_status <> VERIFIED or VERIFICATION_NOT_NEEDED

   1. If relationship can be created for patient – Create relationship https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17525605916/Check+confidant+person+relationship#Create-confidant-person-relationship

   2. If relationship can not be created for patient – return 422 ('Confidant can not be submitted for person who has document that proves legal capacity')

Search user in Mithril

1. Search for existing user in mithril database, users table, with person_id = person_id and is_active = true

   1. If user is found - check it is not blocked (is_blocked <> true)

      1. in case blocked - return 401 ('User is blocked.').

      2. in case not blocked - save its user_id and proceed to p.3.

   2. If user is not found - proceed to p.4.

Create user if not exists

1. Create user for active person in mithril database, users table, set:

   1. id = autogenerate uuid

   2. settings = ‘{“trusted_source”: false}’

   3. priv_settings = ‘{"login_hstr": [], "otp_error_counter": 0}’

   4. inserted_at = now()

   5. updated_at = now()

   6. password_set_at = now()

   7. tax_id = tax_id or document.number from payload (if both where passed - then tax_id must be used)

   8. person_id = person_id of person that was found on Search person step

2. Create global role for created user in mithril database, global_user_roles table, set:

   1. id = autogenerate uuid

   2. user_id = user_id of user created on p.4

   3. role_id = id of role with name ‘PATIENT’

   4. inserted_at = now()

   5. updated_at = now()

Generate authorization token

1. Generate auth_token with scope app:authorize for user_id and client_id of Auth UI (from env)

2. Save token to mithril database, tokens table, set:

   1. id = token uuid

   2. name = token name (‘access_token’)

   3. value = hashed token

   4. expires_at = date and time when token will be expired in unix-time format

   5. details = additional details of token (scopes, client_id, grant_type)

   6. user_id = id of user

   7. inserted_at = now()

   8. updated_at = now()

3. Render a response according to specification.