Purpose

This WS is used to sign previously approved Person request (as part of Person creation w/o declaration process).

Specification

Apiary

Key points

Signed content must consists of JSON object with person request data and printout template.
Person must re-read and sign person request print form and after that patient_signed should be changed to true.
This WS will store signed copy of person request in Media Content Storage, create or update MPI records if all checks are passed.
Process is synchronous. If all validations are successfully completed, the synchronous process of creating or updating person starts by processing the message.

Main differences from V1

Confidant_person is an object, not an array, so user must use responses from IL.Get Person request by ID v2 or RC_(CSI-1323)_Approve person request v2
In case if document that prove legal capacity is set: deactivates all person records in IL | confidant_person_relationship_requests and MPI | confidant_person_relationships tables.
In case if person is created and confidant is submitted: creates relationship in MPI | confidant_person_relationships and saves documents that prove relationship to MPI | confidant_person_relationship_documents .

Authorization

Verify the validity of access token
- Return (401, 'Invalid access token') in case of validation fails
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 = 'person_request:write')
- Return (403, 'Your scope does not allow to access this resource. Missing allowances: person_request:write') in case of invalid scope(s)

Validations

Validate request

Validate encoded and decoded request according to JSON Schema

Check absence of extra parameters
- In case of error - return 422 ('schema does not allow additional properties')
Check presence of required parameters
- In case of error - return 422 ('required property %{property} was not present')

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "signed_content": {
      "type": "string"
    }
  },
  "required": [
    "signed_content"
  ],
  "additionalProperties": false
}

Check that person request from URL exists in IL database, person_requests table
- in case of error - return 404 ('Person request not found.')

Validate backwards compatability

This WS can sign only person requests that were approved by RC_(CSI-1323)_Approve person request v2

Check that person_request.version field is equal to 2
- in case of error - return 422 ('Person request cannot be processed by the version 2 of the service, use version 1 instead')
Check that channel equals to MIS
- in case of error - return 422 ('Only person request with MIS channel can be signed.')

Validate status transition

Only person request in APPROVED status can be approved.

Check that person request for URL has status = APPROVED
- in case of error - return 409 ('Invalid transition.')

Validate client

The request can be approved only by the employee who works in the same legal entity in which the request was made.

Check that client_id from token equals to legal_entity_id of person request from URL
- in case of error - return 403 ('Client is not allowed to sign person_request.')

Validate signed content

Check that $.signed_content field contains digital signature
- in case of error - return 400 ('Invalid signature')
Check digital signature of $.signed_content is valid
- in case of error - return 400 with digital signature validation error message
Check that decoded signed content equals with previously saved in person_requests table for person request
- in case of error - return 422 ('Signed content does not match the previously created content.')
Check that drfo field exists in digital signature and is not empty
- in case of error - return 410 ('Invalid drfo')
Check that drfo field in digital signature equals to tax_id of party that is related to employee that performs request
- in case of error - return 422 ('Does not match the signer drfo')

Validate patient_signed flag

Person request must be signed only after person has read and signed print form.

After person signed print form, patient_signed field must be set to true and passed in $.signed_content.

Check that patient_signed field exists in decoded person request
- in case of error - return 422 ('required property patient_signed was not present')
Check that patient_signed = true in decoded person request
- in case of error - return 422 ('value is not allowed in enum')

Validate person authentication methods

If Person request for create person is signed, check authentication methods:

If $.person.authentication_methods[0].type = OTP - check that phone number is found less than phone_number_auth_limit global parameter in the system according to RC_(CSI-1323)_Create/Update person request v2 | Validate person authentication methods
- in case of error - return 409 ('This phone number is present more then $.global_parameters.phone_number_auth_limit times in the system')
If $.person.authentication_methods[0].type = THIRD_PERSON - check that third person is found less than third_person_limit global parameter in the system according to RC_(CSI-1323)_Create/Update person request v2 | Validate person authentication methods
- in case of error - return 422 ('This fiduciary person is present more than $.global_parameters.third_person_limit times in the system')

Service logic

Save signed person request in Media content storage

After person request is successfully signed, save signed person request to Media content storage.

Get name for bucket from MEDIA_STORAGE_PERSON_REQUEST_BUCKET config parameter, save person request to /person_requests/person_request_id folder with signed_content filename.

Update person request

Update person request, set values:

status = SIGNED
updated_by = user_id from token
updated_at = now()
patient_signed = true
person_id = id of created or updated person

Create or update person

Create person

If create person request is signed, create new person in MPI database.

Set values in following tables based on person request:

persons table
person_phones table
person_addresses table
person_documents table
person_authentication_methods table
1. if persons auth method type = THIRD_PERSON - calculate end date for method using following logic:
  1. if persons age < no_self_auth_age global parameter - set end_date = birth_date + no_self_auth_age - 1d
  2. else set end_date = start_date + third_person_term global parameter

Update person

If updated person request is signed, update existing person (stored in $.person.id) in MPI database.

Set values in following tables based on person request:

persons table
person_phones table
person_addresses table
person_documents table

Submit person on verification

Please note, (GraphQL) Update person refers to this section.

Create or update existing record in person_verifications table for a person according to logic in sections below. Also, set:

updated_at = now()
updated_by = user uuid
inserted_at = now() (for new records)
inserted_by = user uuid (for new records)

Manual NHS verification

If person’s data match any of the following rules:

Person has OFFLINE auth method
if create Person process, check Request
if update Person process, check within MPI.person_athentication_methods table
Person’s age < no_self_auth_age and has document with type BIRTH_CERTIFICATE_FOREIGN (check in Request, within $.person.documents and $.person.confidant_person[:].documents_relationship[:])
Person’s age >= no_self_auth_age and has document with type PERMANENT_RESIDENCE_PERMIT (check in Request)

then manual verification is needed. Set to person verification record:

nhs_verification_status = VERIFICATION_NEEDED
nhs_verification_reason = RULES_TRIGGERED

else manual verification is not needed. Set to person verification record:

nhs_verification_status = VERIFIED
nhs_verification_reason = RULES_PASSED
nhs_verification_comment = NULL

DRFO registry verification

Set to person verification record:

drfo_data_id = NULL
drfo_data_result = NULL
drfo_synced_at = NULL
drfo_verification_status = VERIFICATION_NEEDED
drfo_verification_reason = ONLINE_TRIGGERED

Then person will be verified online with DRFO registry via separate process: ARCHIVE_DRFO data synchronization for Persons (CSI-2823)

DRACS death acts registry verification

Set to person verification record as ready for online verification with DRACS death acts registry:

dracs_death_verification_status = VERIFICATION_NEEDED
dracs_death_verification_reason = ONLINE_TRIGGERED
dracs_death_online_status = READY

If person is updated, check existance of verification candidates for person_id with status = ‘NEW’ and entity_type = ‘dracs_death_act' in person_verification_candidates table, if found - deactivate them, set:

status = ‘DEACTIVATED’
status_reason = ‘PERSON_UPDATED’
updated_at = now()

Then person will be verified online with DRACS death acts registry via separate process: https://e-health-ua.atlassian.net/wiki/spaces/DRACS/pages/17249763472

MVS passport registry verification

If person’s data match following rules: person has document with type ‘PASSPORT’ or ‘NATIONAL_ID’ (check in Request, within $.person.documents)

then online verification with MVS passports registry needed. Set to person verification record:

mvs_passport_data_id = NULL
mvs_passport_data_status = NULL
mvs_passport_synced_at = NULL
mvs_passport_verification_status = VERIFICATION_NEEDED
mvs_passport_verification_reason = ONLINE_TRIGGERED

Then person will be verified online with MVS passports registry via separate process: RC_ MVS passport data synchronization for Persons (DMS)

If person’s data does not match rules from above – online verification with MVS passports registry is not needed. Set to person verification record:

mvs_passport_data_id = NULL
mvs_passport_data_status = NULL
mvs_passport_synced_at = NULL
mvs_passport_verification_status = VERIFICATION_NOT_NEEDED
mvs_passport_verification_reason = AUTO_DATA_ABSENT

DMS passport registry verification

If person’s data match following rules: person has document with type ‘PASSPORT’ or ‘NATIONAL_ID’ (check in Request, within $.person.documents)

then online verification with DMS passports registry needed. Set to person verification record:

dms_passport_data_id = NULL
dms_passport_data_status = NULL
dms_passport_synced_at = NULL
dms_passport_verification_status = VERIFICATION_NEEDED
dms_passport_verification_reason = ONLINE_TRIGGERED

Then person will be verified online with DMS passports registry via separate process: RC_DMS passport data synchronization for Persons (DMS)

If person’s data does not match rules from above – online verification with DMS passports registry is not needed. Set to person verification record:

dms_passport_data_id = NULL
dms_passport_data_status = NULL
dms_passport_synced_at = NULL
dms_passport_verification_status = VERIFICATION_NOT_NEEDED
dms_passport_verification_reason = AUTO_DATA_ABSENT

UNZR registry verification

If person’s data match following rules: ‘unzr’ is submitted and is not null (check in Request, within $.person.unzr)

then online verification with UNZR registry needed. Set to person verification record:

unzr_data_id = NULL
unzr_data_status = NULL
unzr_synced_at = NULL
unzr_verification_status = VERIFICATION_NEEDED
unzr_verification_reason = ONLINE_TRIGGERED

Then person will be verified online with UNZR registry via separate process: RC_UNZR data synchronization for Person (DMS)

If person’s data does not match rules from above – online verification with UNZR registry is not needed. Set to person verification record:

unzr_data_id = NULL
unzr_data_status = NULL
unzr_synced_at = NULL
unzr_verification_status = VERIFICATION_NOT_NEEDED
unzr_verification_reason = AUTO

Calculate cumulative verification status

Calculate persons cumulative verification status based on persons verification status in each stream: Manual NHS verification, DRFO registry verification, DRACS death acts registry verification, MVS passport registry verification, DMS passport registry verification, UNZR registry verification according to logic described at Person verification status model_EN | Cumulative verification status :

Set calculated status to persons.verification_status field
Create StatusChangeEvent in event manager with new verification status if it was changed

Create/Update relationship between confidant patient and related patient

In case if person is created and person.confidant_person.person_id exists in person_data for person request - create confidant person relationship between person and confidant person:

Call Create confidant person relationship, set values:
- confidant_person_id = person.confidant_person.person_id
- person_id = id of created person
- verification_status = “VERIFICATION_NEEDED”
- verification_reason = “MANUAL_CREATED_BY_DOCTOR”
- confidant_person_relationship_documents = person.confidant_person.documents_relationship with record_type: relationship_confirmation
In case if persons age < person_full_legal_capacity_age global parameter:
- 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
  - if false or $.active_to = null – set active_to = relationship_expiration_date

In case if person is updated (person.id exists in person_data for person request) and at least one of submitted person document types exist in PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter - deactivate all existing confidant person relationships for person:

Deactivate all records in IL | confidant_person_relationship_requests table where person_id = person.id and status = NEW, set values:
- status = CANCELLED
- updated_at = now()
- updated_by = user_id (from token)
Deactivate all records in MPI | confidant_person_relationships table where person_id = person.id and is_active = true. Set:
- active_to = now()
- updated_at = now()
- updated_by = user_id (from token)
For each relationship from previous step - deactivate person authentication methods with type = THIRD_PERSON and value = confidant_person_relationships.confidant_person_id, set values:
- ended_at = now()
- updated_at = now()
- updated_by = user_id (from token)

E-Health

RC_Sign person request v2 (DMS)