Purpose

This WS is used to initialize creation of Person request to update the person details according to his id, which was previously found using person_id from access token.

Specification

Apiary

Key points

1. This WS should be used only for updating existing person in the system.

2. Person authentication method and confidant person details shouldn't be passed in request for update person.

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_pis')

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

• Check that token contains person_id

  • in case of error - return (401, 'Invalid access token')

Validate person

• Get person_id from token (x-person-id header)

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

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

• Check that amount of changes of person data in request is acceptable (person is not updated too much), according to existing validation, described here https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986/Create+Update+person+request#Update-person-request. Compare resulting score with PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_PIS config parameter.

Validate confidant person and relationship

If person is not legally capable - system must ensure that its details are updated by confidant person and there is registered and verified their relationship

Get applicant_person_id from token, compare it to person_id from token:

• If equals - check that person must not be authorized by confidant person, so it doesn’t correspond to following rules:

  • persons age < no_self_registration_age global parameter;

  • persons age between no_self_registration_age and person_full_legal_capacity_age global parameters and person does not have document with type from PIS_PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter;

  • 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 Check confidant person relationship with person_id = person from request - expected :ok, :approved response)

    • In case of error - return 409 (‘Request must be authorized by confidant person’)

• If not equal - validate relationship with following steps:

  • Check that there is registered relationship between person_id and applicant_person_id(MPI.confidant_person_relationships)

  • Check that relationship is VERIFIED

    • In case of error - return 409 (‘Can’t confirm relationship’)

  • Check that applicant_person_id exists (status = 'active' & is_active = 'true') and has verification_status any but NOT_VERIFIED

    • In case of error - return 409 (‘Confidant person not found or is not verified’)

Validate request

Validate request using JSON schema (according to Вимоги до набору даних персони )

{
  "$schema": "http://json-schema.org/person_request/schema#",
  "definitions": {
    "phone": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Dictionary: PHONE_TYPE"
        },
        "number": {
          "type": "string",
          "pattern": "^\\+38[0-9]{10}$"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    },
    "name": {
      "type": "string",
      "pattern": "^(?!.*[ЫЪЭЁыъэё@%&$^#])[a-zA-ZА-ЯҐЇІЄа-яґїіє0-9№\\\"!\\^\\*)\\]\\[(._-].*$"
    },
    "person_name": {
      "type": "string",
      "pattern": "^(?!.*[ЫЪЭЁыъэё@%&$^#])[А-ЯҐЇІЄа-яґїіє\\'\\-]+(\\s(?!.*[ЫЪЭЁыъэё@%&$^#])[А-ЯҐЇІЄа-яґїіє\\'\\-]+)*$",
      "minLength": 1,
      "maxLength": 255
    },
    "unzr": {
      "type": "string",
      "pattern": "^[0-9]{8}-[0-9]{5}$"
    },
    "tax_id": {
      "type": "string",
      "pattern": "^[0-9]{10}$",
      "minLength": 10,
      "maxLength": 255
    },
    "no_tax_id": {
      "type": "boolean",
      "description": "Status person refused tax_id"
    },
    "gender": {
      "type": "string",
      "description": "Dictionary: GENDER",
      "maxLength": 255
    },
    "address": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Dictionary: ADDRESS_TYPE"
        },
        "country": {
          "type": "string"
        },
        "area": {
          "$ref": "#/definitions/name"
        },
        "region": {
          "$ref": "#/definitions/name"
        },
        "settlement": {
          "$ref": "#/definitions/name"
        },
        "settlement_type": {
          "type": "string",
          "description": "settlement type Dictionary: SETTLEMENT_TYPE"
        },
        "settlement_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
        },
        "street_type": {
          "type": "string",
          "description": "street type Dictionary: STREET_TYPE"
        },
        "street": {
          "$ref": "#/definitions/name"
        },
        "building": {
          "type": "string",
          "pattern": "^[1-9]((?![ЫЪЭЁыъэё])()([А-ЯҐЇІЄа-яґїіє \\/\\'\\-0-9])){0,20}$"
        },
        "apartment": {
          "type": "string"
        },
        "zip": {
          "type": "string",
          "pattern": "^[0-9]{5}$"
        },
        "inserted_by": {
          "type": "string"
        },
        "updated_by": {
          "type": "string"
        },
        "inserted_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "country",
        "area",
        "settlement",
        "settlement_type",
        "settlement_id",
        "inserted_by",
        "updated_by"
      ],
      "additionalProperties": false
    },
    "series_number_document": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "PASSPORT",
            "COMPLEMENTARY_PROTECTION_CERTIFICATE",
            "REFUGEE_CERTIFICATE",
            "TEMPORARY_CERTIFICATE"
          ],
          "description": "Dictionary: DOCUMENT_TYPE"
        },
        "number": {
          "type": "string",
          "pattern": "^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$"
        },
        "issued_by": {
          "type": "string",
          "minLength": 1
        },
        "issued_at": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    },
    "number_document": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "BIRTH_CERTIFICATE",
            "TEMPORARY_PASSPORT"
          ],
          "description": "Dictionary: DOCUMENT_TYPE"
        },
        "number": {
          "type": "string",
          "pattern": "^(?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]+$",
          "minLength": 1,
          "maxLength": 255
        },
        "issued_by": {
          "type": "string",
          "minLength": 1
        },
        "issued_at": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    },
    "id_card": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "NATIONAL_ID"
          ],
          "description": "Dictionary: DOCUMENT_TYPE"
        },
        "number": {
          "type": "string",
          "pattern": "^[0-9]{9}$"
        },
        "issued_by": {
          "type": "string",
          "minLength": 1
        },
        "issued_at": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "type",
        "number"
      ],
      "additionalProperties": false
    }
  },
  "type": "object",
  "properties": {
    "person": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        },
        "second_name": {
          "type": "string"
        },
        "birth_date": {
          "type": "string"
        },
        "birth_country": {
          "type": "string"
        },
        "birth_settlement": {
          "type": "string"
        },
        "gender": {
          "enum": [
            "MALE",
            "FEMALE"
          ]
        },
        "email": {
          "type": "string"
        },
        "no_tax_id": {
          "type": "boolean"
        },
        "tax_id": {
          "type": "string"
        },
        "secret": {
          "type": "string"
        },
        "documents": {
          "type": "array"
        },
        "addresses": {
          "type": "array"
        },
        "phones": {
          "type": "array"
        },
        "unzr": {
          "type": "string"
        },
        "emergency_contact": {
          "type": "object",
          "properties": {
            "first_name": {
              "type": "string"
            },
            "last_name": {
              "type": "string"
            },
            "second_name": {
              "type": "string"
            },
            "phones": {
              "type": "array"
            }
          },
          "required": [
            "first_name",
            "last_name",
            "phones"
          ]
        },
        "preferred_way_communication": {
          "enum": [
            "email",
            "phone"
          ]
        }
      },
      "required": [
        "first_name",
        "last_name",
        "birth_date",
        "birth_country",
        "birth_settlement",
        "gender",
        "secret",
        "documents",
        "addresses",
        "emergency_contact"
      ]
    },
    "patient_signed": {
      "type": "boolean"
    },
    "process_disclosure_data_consent": {
      "type": "boolean"
    }
  },
  "required": [
    "person",
    "patient_signed",
    "process_disclosure_data_consent"
  ]
}

• in case field value does not match the schema - return 422 with field-specific message

• in case additional fields exist in request - return 422 ('schema does not allow additional properties')

• in case required parameter does not exist in request - return 422 ('required property %{property} was not present')

• in case required amount of parameters does not exist in request - return 422 ('expected a minimum of %{min} items but got %{actual}')

Validate tax_id

• Check that $.person.tax_id equals to updated persons tax_id

  • in case of error - return 422 ('tax_id can't be updated')

• Additionally, validate tax_id according to existing validations, described here https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986/Create+Update+person+request#Validate-%22tax_id%22

Validate no_tax_id flag

• Validate no_tax_id flag according to existing validations, described here https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986/Create+Update+person+request#Check-%22no_tax_id%22-flag

Validate patient_signed flag

• Validate patient_signed flag according to existing validations, described here https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986/Create+Update+person+request#Check-%22patient_signed%22-flag

Validate process_disclosure_data_consent flag

• Validate process_disclosure_data_consent flag according to existing validations, described herehttps://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986/Create+Update+person+request#Validate-person-documents

Validate person addresses

• Validate person addresses according to existing validations, described here https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986/Create+Update+person+request#Validate-person-documents

Validate person documents

• If updated persons unzr is not null - сheck that $.person.unzr equals to updated persons unzr

  • in case of error - return 422 ('unzr can't be updated')

• Additionally, validate person documents according to existing validations, described herehttps://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986/Create+Update+person+request#Validate-person-documents

Service logic

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 person request should be created.

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

For each type of documents, if couple of rules worked - only one single link is generated.

1. Validate block of person documents. If one of the documents has document.type = BIRTH_CERTIFICATE_FOREIGN and persons age < no_self_auth_age global parameter then

   1. Generate URL with type person.BIRTH_CERTIFICATE_FOREIGN

2. Validate block of person documents. If one of the documents has document.type = PERMANENT_RESIDENCE_PERMIT and persons age >= no_self_auth_age global parameter then

   1. Generate URL with type person.PERMANENT_RESIDENCE_PERMIT

3. Validate block of person documents. If one of the documents has document.type from PIS_PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES then

   1. Generate URL with type person.<<document_type>> where document_type - type of document from config parameter, for each found document type

4. Validate persons unzr. If $.person.unzr is not empty and first 8 digits of $.person.unzr != $.person.birth_date

   1. Generate URL with type person.unzr

Invoke Media Content Storage to generate upload URL for each document obtained by executing logic above and save documents to DB.

Generate printout form

Prepare data for person request printout form

1. Define printout form template based on applicant_person_id field in token and confidant person relationship validation:

   1. If applicant_person_id does not equal to person_id from token - select printout form with confidant person (stored in PIS_PERSON_REQUEST_PRINTOUT_FORM_INCAPACITY_TEMPLATE_ID config param)

   2. If applicant_person_id equals to person_id from token - select printout form w/o confidant person (stored in PIS_PERSON_REQUEST_PRINTOUT_FORM_TEMPLATE_ID config param)

2. Call MAN service to render printout form

3. Prepare printout content based on person request data

   1. for printout form with confidant person - additionally preload confidant person data based on applicant_person_id from token

      1. get confidant person details from persons table (with persons.id = applicant_person_id)

      2. get confidant person documents from person_documents table (with person_documents.person_id = applicant_person_id)

      3. get relation documents from confidant_person_relationship_documents table (with confidant_person_relationship_id = id of relationship between person and confidant person)

4. Render printout form and save to person request

Search pending person requests

Search pending person requests in IL.person_requests to prevent requests duplication:

• person_data_id = person_id from token

• status = NEW or APPROVED

Cancel person requests

Change status of all found person requests:

• set status = CANCELLED

• set updated_at = now()

• set updated_by = user_id from token

Save person request

Insert record to IL.person_requests, set values:

• id = autogenerate uuid

• person_data = $.person from request in json format

  • person_data.person.id = person_id from token

• status = NEW

• authentication_method_current = null

• channel = PIS

• legal_entity_id = null

• tax_id = $.person.tax_id from request (if not null)

• last_name = $.person.last_name from request

• first_name = $.person.first_name from request

• birth_date = $.person.birth_date from request

• printout_form = rendered printout form

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

• person_documents = $.person.documents from request in json format

• inserted_by = user_id from token

• updated_by = user_id from token

• inserted_at = now()

• updated_at = now()

• patient_signed = $.patient_signed from request

• process_disclosure_data_consent = $.process_disclosure_data_consent from request

• person_data_id = $.person.id from request

• authorize_with = null

Render a response

Render a response according to specification.