1 Purpose
2 Specification
3 Key points
- 3.1 Main differences from V1
4 Authorization
5 Validations
- 5.1 Validate request
- 5.2 Validate backwards compatibility
- 5.3 Validate status transition
- 5.4 Validate client
- 5.5 Validate signed content
- 5.6 Validate patient_signed flag
- 5.7 Validate person authentication methods
6 Service logic
- 6.1 Save signed person request in Media content storage
- 6.2 Update person request
- 6.3 Create or update person
  - 6.3.1 Create person
  - 6.3.2 Update person
- 6.4 Submit person on verification
  - 6.4.1 Manual NHS verification
  - 6.4.2 DRFO registry verification
  - 6.4.3 DRACS death acts registry verification
  - 6.4.4 DRACS birth acts registry verification
  - 6.4.5 DRACS name change acts registry verification
  - 6.4.6 Legal capacity verification
- 6.5 Calculate cumulative verification status
- 6.6 Create/Update relationship between confidant patient and related patient

Purpose

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

Specification

https://uaehealthapi.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/person-requests/sign-person-request-v2

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 RC_(CSI-1323)_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 compatibility

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
- 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: DRFO data synchronization for Persons | Data flow

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: Online verification of Persons with DRACS death acts registry_EN

DRACS birth acts registry verification

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

Person is created and persons age <= no_self_auth_age and person has document with type BIRTH_CERTIFICATE (check in Request, within $.person.documents)
Person is created and persons age > no_self_auth_age and person has only document with type BIRTH_CERTIFICATE (check in Request, within $.person.documents)
Person is updated and persons age <= no_self_auth_age and person has document with type BIRTH_CERTIFICATE (check in Request, within $.person.documents) and following fields are updated:
1. first_name
2. last_name
3. second_name
4. birth_date
5. document.number with type = ‘BIRTH_CERTIFICATE’
Person is updated and persons age > no_self_auth_age and person has only document with type BIRTH_CERTIFICATE (check in Request, within $.person.documents) and following fields are updated:
1. first_name
2. last_name
3. second_name
4. birth_date
5. document.number with type = ‘BIRTH_CERTIFICATE’

then online verification with DRACS birth acts registry needed. Set to person verification record:

dracs_birth_act_id = null
dracs_birth_verification_status = VERIFICATION_NEEDED
dracs_birth_verification_reason = ONLINE_TRIGGERED
dracs_birth_verification_comment = null
dracs_birth_synced_at = null
dracs_birth_unverified_at = null

Check existence of verification candidates for person_id with status = ‘NEW’ and entity_type = ‘dracs_birth_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 birth acts registry via separate process: RC_DRACS birth acts synchronization for Persons (DRACS 2.0)

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

if person is created:
- dracs_birth_act_id = null
- dracs_birth_verification_status = VERIFICATION_NOT_NEEDED
- dracs_birth_verification_reason = INITIAL
- dracs_birth_verification_comment = null
- dracs_birth_synced_at = null
- dracs_birth_unverified_at = null
if person is updated – do not update dracs_birth_verification_status and dracs_birth_verification_reason for person.

DRACS name change acts registry verification

If person is created, set values in person_verifications table:

dracs_name_change_verification_status = VERIFICATION_NOT_NEEDED
dracs_name_change_verification_reason = INITIAL

If person is updated and persons dracs_name_change_verification_status = ‘VERIFICATION_NEEDED’:

Check existence of verification candidates for person_id with status = ‘NEW’ and entity_type in (‘dracs_marriage_act', ‘dracs_divorce_act’, ‘dracs_change_name_act’) in the person_verification_candidates table:
- if found:
  - Compare updated person data with them using following processes for each entity_type:
    - for dracs_marriage_act - use RC_DRACS certificates synchronization for Person (DRACS 2.0) | Step 3. Marriage act comparison process
    - for dracs_divorce_act - use RC_DRACS certificates synchronization for Person (DRACS 2.0) | Step 3. Divorce act comparison process
    - for dracs_change_name_act - use RC_DRACS certificates synchronization for Person (DRACS 2.0) | Step 3. Change name act comparison process
  - If a candidate does not already match the updated person’s data - deactivate them, set:
    - status = ‘DEACTIVATED’
    - status_reason = ‘PERSON_UPDATED’
    - updated_at = now()
  - If no more active candidates for name change left - update person DRACS change name verification status, set values:
    - dracs_name_change_verification_status = VERIFIED
    - dracs_name_change_verification_reason = AUTO_OFFLINE
    - dracs_name_change_verification_comment = null

Legal capacity verification

If person’s data match following rules: person has legal capacity document (from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter) with type ‘MARRIAGE_CERTIFICATE’ or ‘DIVORCE_CERTIFICATE’ (check in Request, within $.person.documents)

then online verification with DRACS certificates registry is needed. Set to person verification record:

legal_capacity_verification_status = VERIFICATION_NEEDED
legal_capacity_verification_reason = ONLINE_TRIGGERED
legal_capacity_entity_id = NULL
legal_capacity_entity_type = NULL
legal_capacity_unverified_at = NULL

Then person will be verified online with DRACS certificates registry via separate process: RC_DRACS certificates synchronization for Person (DRACS 2.0)

If person’s data match following rules: person has legal capacity document (from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter) with type other than ‘MARRIAGE_CERTIFICATE’ or ‘DIVORCE_CERTIFICATE’ (check in Request, within $.person.documents)

then persons legal capacity is verified by default. Set to person verification record:

legal_capacity_verification_status = VERIFICATION_NOT_NEEDED
legal_capacity_verification_reason = AUTO_DATA_ABSENT
legal_capacity_entity_id = NULL
legal_capacity_entity_type = NULL
legal_capacity_unverified_at = NULL

If person does not have legal capacity document (from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter), legal capacity verification is not needed. Set to person verification record:

legal_capacity_verification_status = VERIFICATION_NOT_NEEDED
legal_capacity_verification_reason = AUTO_DATA_ABSENT
legal_capacity_entity_id = NULL
legal_capacity_entity_type = NULL
legal_capacity_unverified_at = NULL

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, DRACS birth acts registry verification, DRACS name change acts registry verification according to logic described at https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18254790685:

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 https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17525605929, set values:
- confidant_person_id = person.confidant_person.person_id
- person_id = id of created person
- verification_status = “VERIFICATION_NEEDED”
- verification_reason based on relationship document:
  - if confidant_person.relationship_documents contains document with type BIRTH_CERTIFICATE, set verification_reason = “ONLINE_TRIGGERED”
  - if confidant_person.relationship_documents does not contain document with type BIRTH_CERTIFICATE, set verification_reason = “MANUAL_CREATED_BY_DOCTOR”
- confidant_person_relationship_documents = person.confidant_person.documents_relationship
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 and legal_capacity_verification_status = VERIFIED or VERIFICATION_NOT_NEEDED according to Legal capacity verification - 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)

In case if person is updated (person.id exists in person_data for person request), and person has active Confidant person relationships with relationship document with type='BIRTH_CERTIFICATE' and following person fields are updated:

first_name
last_name
second_name
birth_date

Update found active Confidant person relationships as those that need online verification with DRACS birth acts registry, set values:

verification_status = “VERIFICATION_NEEDED”
verification_reason = “ONLINE_TRIGGERED”
updated_at = now()
updated_by = user_id

Check existance of verification candidates for updated confidant_person_relationship_id with status = ‘NEW’ and entity_type = ‘dracs_birth_act' in confidant_person_relationship_verification_candidates table, if found - deactivate them, set:

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

In case if person is updated (person.id exists in person_data for person request), and person exists in the system as confidant person in active confidant person relationship with relationship document with type='BIRTH_CERTIFICATE' and following person fields are updated:

first_name
last_name
second_name
birth_date
tax_id