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 PIS. Confidant patient sign-up validation 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

Authorization

• Verify the validity of access token

  • in case of error - return 401 (“Invalid access token”)

• Verify that token is not expired

  • in case of error - return 401 (“Invalid access token”)

• Check user scopes in order to perform this action (scope = confidant_person:sign_up)

  • return 403 (“Your scope does not allow to access this resource. Missing allowances: confidant_person:sign_up”) in case of invalid scope(s)

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

• Check that signer of the request relates to the authenticated person. Get person from MPI using x-person-id and ensure that person.tax_id or person.documents is equal to signer drfo (from digital signature)

  • if drfo value equals to tax_id regexp (^[0-9]{10}$) - compare with person.tax_id

  • if drfo value equals to national_id number regexp (^[0-9]{9}$) - compare with document with type 'NATIONAL_ID'

  • if drfo value contains at least one letter, perform reverse transliteration of field using existing algorithm (described here), then check that value equals to passport number regexp (^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$) - compare with document with type 'PASSPORT'

    • in case of error - return 401 ('Unable to authenticate signer')

Validate JWT

Ensure that token provided in payload (obtained from PIS. Confidant patient sign-up validation ) 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/PCAB/pages/17415143598/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 /wiki/spaces/PCAB/pages/17427464424
   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/PCAB/pages/17416880243/PIS.+Confidant+patient+sign-up+registration#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/PCAB/pages/17416880243/PIS.+Confidant+patient+sign-up+registration#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/DRACS/pages/17249206422/IL.Sign+person+request+modified+EN#Manual-NHS-verification

   2. DRFO registry verification - according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/DRACS/pages/17249206422/IL.Sign+person+request+modified+EN#DRFO-registry-verification

   3. DRACS death acts registry verification - according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/DRACS/pages/17249206422/IL.Sign+person+request+modified+EN#DRACS-death-acts-registry-verification

4. Calculate cumulative person verifiation status according to logic, described here: https://e-health-ua.atlassian.net/wiki/spaces/DRACS/pages/17249206422/IL.Sign+person+request+modified+EN#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 Create confidant person relationship. Set values:

  • confidant_person_id = $request.confidant_person.person_id

  • person_id = person.id

  • verification_status = “VERIFICATION_NEEDED”

  • 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 confidant person relationship

Get confidant_person_id from token (new header x-person-id)

Check relationship using Check confidant person relationship and having confidant_person_id and person_id

1. If relationship doesn’t exist - Create relationship https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17416880243/PIS.+Confidant+patient+sign-up+registration#Create-confidant-person-relationship

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