Purpose

This process describes adding Confidant Person relationship for an existing person.

Key points

1. The method allows to create a confidant person relationship request that must be approved and allows to create a confidant person relationship.

2. Creating a new request cancels all existing requests on creation or deactivation for current person and other confidant persons

3. Count of confidant person relationships and confidant person relationship requests that can exist in the system for one person is limited by person_with_third_person_limit config parameter

Specification

Apiary

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 = confidant_person_relationship_request:write)

  • Return (403, 'Your scope does not allow to access this resource. Missing allowances: confidant_person_relationship_request:write') in case of invalid scope(s)

Validation

Validate Person

• Get person_id from URL

• Validate person status is active (status = ‘active' & is_active = 'true’)

  • in case of error - return 404 ('Person is not found')

• 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

  • in case of error - return 422 ('Confidant can not be submitted for person who has document that proves legal capacity')

Validate request

Validate JSON Schema

• Check presence 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')

Validate person confidants limit

• Count relationships from MPI | confidant_person_relationships table where person_id is equal to $.person_id AND is_active=true AND active_to > now() or null

• Check if count from previous step is less than person_with_third_person_limit config parameter

  • in case of error - return 422 ('Limit of confidant persons with this person is exhausted')

Validate confidant person

• Check if $.confidant_person_relationship.confidant_person_id is not equal to person_id from URL

  • in case of error - return 422 ('Persons can not be submited as confidants for themselves')

• Check if $.confidant_person_relationship.confidant_person_id exists in persons table (MPI DB) with status = active and is_active = true

  • in case of error - return 422 ('Confidant person is not found')

• Check if confidant person does not already exist as confidant for person using following process https://e-health-ua.atlassian.net/wiki/spaces/CSI/pages/17667883028 with person_id = person from URL and confidant_person_id = $.confidant_person_id from request - expected :error, :not_found response

  • in case of error - return 422 ('Relationship between confidant person and person already exists')

• Check if confidant person itself shouldn’t be authorized by confidant - so it doesn’t correspond to following rules:

  • confidant persons age < no_self_registration_age global parameter;

  • confidant persons age between no_self_registration_age and person_full_legal_capacity_age global parameters and 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;

  • confidant persons age > person_full_legal_capacity_age global parameter and exists at least one active and approved confidant person relationship for person (using following process https://e-health-ua.atlassian.net/wiki/spaces/CSI/pages/17667883028 with person_id = $.confidant_person_id from request - expected :ok, :approved response)

  • confidant person has at least one confidant person in persons.confidant_person array

    • in case of error - return 422 ('Person with incorrect age or with active confidant person relationship can not be submitted as confidant')

• Check if confidant person cumulative verification status is not in NOT_ALLOWED_CONFIDANT_PERSON_VERIFICATION_STATUSES config parameter

  • in case of error - return 422 ('Person with cumulative verification status <person.verification_status> can not be submitted as confidant')

• Check if confidant person has active authentication method with type = OTP where ended_at is equal to or greater than today`s date

  • in case of error - return 422 ('Confidant person must have active authentication method with type 'OTP' where ended_at is equal to or greater than current date.')

Validate documents relationship

• Validate documents issued_at date

  • Check that issued_at <= now()

    • in case of error - return 422 ('Document issued date should be in the past')

  • Check that issued_at => person.birth_date

    • in case of error - return 422 ('Document issued date should greater than person.birth_date')

• Validate document active_to date

  • Check that active_to > now()

    • in case error - return 422 ('Document active_to date should be in future')

• Validate document type according to DOCUMENT_RELATIONSHIP_TYPE dictionary

  • In case of error - return 422 ('value is not allowed in enum')

• Check that there are no duplicated document type values in request

  • in case of error - return 422 ('Values are not unique by 'type'.')

• Validate document number according to regexp (as part of JSON Schema validation)

  • BIRTH_CERTIFICATE - ^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$

    • In case of error - return 422 error ('string does not match pattern') with the corresponding regexp

• Check that document number length < 255

  • in case of error - return 422 ('expected value to have a maximum length of 255 but was <<document_number_length>>')

• If document type contains BIRTH_CERTIFICATE or BIRTH_CERTIFICATE_FOREIGN values, check that persons age < person_full_legal_capacity_age global parameter

  • in case of error - return 422 ('Invalid relationship document type for person in such age')

Service logic

Search active confidant person relationship requests

To prevent overlimit and duplication of requests, search for active requests in IL | confidant_person_relationship_requests table with person_id = person_id from URL and status = NEW.

If found - cancel them, set values:

• status = CANCELLED

• updated_at = now()

• updated_by = user_id (from token)

Generate upload URL

Depending on the payload system generates list of signed urls for document scan-copies upload.

Signed URLs to be expired after some period of time (according to SECRETS_TTL config parameter). If it has been expired - new confidant person relationship request should be created.

Each link is generated for one one-page document in jpeg format. Document should be no more than 10MB.

• Generate URLs for each document from $.documents_relationship with following parameters:

  • action: PUT

  • bucket: MEDIA_STORAGE_CONFIDANT_PERSON_RELATIONSHIP_REQUEST_BUCKET

  • resource_id: confidant_person_relationship_request_id

  • resource_name: confidant_person_relationship_request_#{type}.jpeg

Create new relationship request

Create new record to IL | confidant_person_relationship_requests table, set values:

• id = autogenerate uuid

• person_id = person_id from URL

• confidant_person_id = $.confidant_person_id

• confidant_person_relationship = methods request

• status = NEW

• action = INSERT

• channel = MIS

• authentication_method_current

  • type = OTP

  • phone_number = phone_number from confidant persons active auth method with type = OTP

• inserted_by = user_id (from token)

• inserted_at = now()

• updated_by = user_id (from token)

• updated_at = now()

• documents_relationship = generated links for documents upload (if needed)

Generate verification code

Get template for OTP SMS from CONFIDANT_PERSON_RELATIONSHIP_SMS_TEMPLATE config parameter.

Invoke Initialize OTP to generate one time password and send it to confidant persons number that is stored in authentication_method_current.phone_number. At this stage, the person receives an SMS message to confirm this phone and the consent to create confidant person relationship.

Render a response

Render a response according to specification