ЕСОЗ - публічна документація

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Purpose

To allow NHS Admin/Data Stuart (NHS employee with assigned appropriate scopes) to SAVE updates to personal data of a Person, based on Person’s official request to NHS, which is actually a legal authorisation for changes in his personal data.

Scheme

Design

 Editing

Specification

 index.graphql
"Creates a person_request record with the status SIGNED (in il.person_request) with following update of a person record (in mpi.persons)."
  createPersonRequest(
    input: CreatePersonRequestInput!
  ): CreatePersonRequestPayload

 persons.graphql
"""
Input for `createPersonRequest` mutation.
User must have a scope **person_request:write_nhs**
"""
input CreatePersonRequestInput {
  "Signed data to create Person_Request for update of a person record in mpi.persons"
  signedContent: SignedContent!
  "This parameters is MPI.person.(id of edited person).inserted_at, saved in FE at the beginning of editing process and should be transferred to BE for validation of parallel editing"
  updatedAtForValidation: DateTime!
}

"""
Return type for `createPersonRequest` mutation.
"""
type CreatePersonRequestPayload {
  "Updated data of a Person - from mpi.persons"
  person: Person!
}

Key points

The process is initiated by any NHS employee (only within NHS Admin Panel) with necessary scopes and involves the transfer (by graphQL mutation) of a signed_content. It includes JSON with Person data, where are id of an existing person and no keys and parameters of the authentication methods.

It has similarities to update part of IL.Update-person-request (w/o declaration) process, but there are some main differences:

  1. Person_request record is created in BE directly in status SIGNED based on obtained signed_content(which is signed with digital signrature) from FE. Without interim records to DB with such statuses as NEW, APPROVED.

  2. During update process of Person’s personal data in MPI.person table, there is no need in ONLINE/OFFLINE approve from Person.

  3. There are two new parameters for controlling level of changes and avoid risks of unnecessary automatic deduplication:

    1. PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ADMIN

    2. PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ADMIN
      This parameters might be turned on/off by

      1. PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ACTIVE = true

      2. PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ACTIVE = true

  4. There are additional mandatory fields in the message:

    1.   nhs_request_number
  nhs_request_comment

  5. And there are other differences in fields, values and controls:

    1. $.patient_signed and $.process_disclosure_data_consent should be absent in Message and therefore null value should be set in IL.person_requests. And finally in MPI.persons table those values should not be overwritten.

    2. print-form is not necessary

    3. IL.person_requests.(new record).channel = 'NHS'

  6. One more additional parameter is transferred from FE to BE updatedAtForValidation

  7. second_name and unzr can be set to null. no_tax_id and tax_id can be transferred in the message as null, if they are set both to null.

Process is synchronous. If all validations are successfully completed, the synchronous process of update a person starts by processing the message. 

Scope and roles

Scope name

Roles

Description

New

person_request:write_nhs

  1. ADMIN

  2. NHS ADMIN VERIFIER

Scope for creation ofperson_request record with following update of a person record. Without online/offline approve by Person. As Person’s paper request to NHS - is actually a legal authorisation for changes in Person’s personal data.

#

Path

Link and Article

1

E-Health > Persons > Ідентифіковані персони > Person Requests Technical Requirements

IL.Create/Update person request (w/o declaration)

Create/Update person request

Create/Update person request

2

Public. Medical Service Provider Integration Layer > Person Requests

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

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

Authorize

  1. Verify the validity of access token

    1. Return 401 in case validation fails

  2. Check user scopes person_request:write_nhs

    1. Return 403 in case invalid scope(s)

Digital signature

Decode content that is encrypted in an electronic digital signature.
Use Digital signature WS. Method checks digital signature and returns result.
See service specification

Validate DRFO

  1. Check that DRFO in Certificate details exists and not empty

  2. Check that DRFO in Certificate details is equal to DRFO in Party

    1. Get party.tax_id using employee_id in person payload

    2. Compare DRFO in Certificate with party.tax_id

      1. Convert DRFO and TAX_ID to uppercase

      2. Compare DRFO and TAX_ID as Cyrillic letters

      3. Convert DRFO to Cyrillic and compare as Cyrillic letters

    3. In case validation fails - generate 422 error

Latin to Cyrillic mapping

%{"A" => "А", "B" => "В", "C" => "С", "E" => "Е", "H" => "Н", "I" => "І", "K" => "К", "M" => "М", "O" => "О", "P" => "Р", "T" => "Т", "X" => "Х"}

Validation of Signed Content

Get global parameters

For futher validation, Invoke Global parameters to get following parameter:

  • no_self_auth_age 

cURL example
curl -X GET \
  {:host}/api/global_parameters

Validation

1

Validate parallel editings (new)

Whether Person data were not changed by other users (MSP, NHS) of NHS system. By preliminary keeping value updated_at (saved out of initial query of personal data during start of editing process) and checking at the moment of saving data:

  • If MPI.person.(id = $.id).updated_at = $.updatedAtForValidation then Ok

    • in case of error return 422, 'Person's data were changed while you were editing. Please repeat your steps for update'

2

Validate Person’s status id in DB and deduplication controls

  • If person.id is in request then 

    • if $.person.id is UUID and UUID_version($.person.id is UUID) = 4 then ok

      • in case of error, return 422, “person.id is not UUID type or UUID version is not appropriate“

    • search person by person.id in MPI 

      • in case of error return 404, "not found"

    • If MPI.persons.($.id).status = “active” then ok

      • in case of error return 422 - msg "The Person is not active, therefore any updates of personal data are prohibited”

    • Scoring of level of updates

      Check decoded signed content within system’s deduplication controls within two validations . I.e.

      • Deduplication validation 1 check whether level of changes is “so high” that it is necessary to prohibit (forbid) saving changes.

        • if calculated_score (current data, updates_of_Person) >  PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ADMIN
          then Validation 1 passed, check other validations

          • else return error 409, "Level of conducted changes is higher than permitted. Updates can't be saved. Please check whether you have selected appropriate Person for changes. Calculated score: <calculated_score>. Permitted score: PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ADMIN) "

      • Deduplication validation 2 - whether there are no other Persons, which highly similar to current updates of a Person

        • if calculated_score (updates_of_Person, other_similar_Persons) <  PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ADMIN
          then Validation 2 passed, check other validations

          • else return error 409, "We have found Person(s) with high similarity in DB. Calculated score is equal or greater than permitted PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ADMIN. Please check whether you have selected appropriate Person for changes and investigate possible duplicates of the Person."

    • Deduplication validation 1 and 2 might be turned off by setting independently any of the following parameters

      • PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE_NHS_ACTIVE = true

      • PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE_NHS_ACTIVE = true

3

Check “patient_signed” flag.

This field should not be transferred. And therefore BE should not overwrite this field in DB

4

Check “process_disclosure_data_consent” flag.

This field should not be transferred. And therefore BE should not overwrite this field in DB

5

Validate confidant person

If person age < prm.global_parameters.no_self_auth_age then

check existence of confidant_person

  • in case of error return 422 - msg "Confidant person is mandatory for children"

Validate confidant person age >= prm.global_parameters.no_self_auth_age:

  • in case of error return 422 - msg "Third person must be adult"

validate presence of a secret word:

  • in case of error return 422,

Check that confidant person document type (in documents_person field) exists in IDENTITY_DOCUMENT_TYPES config parameter

  • in case of error return 422 - msg “Submitted document type is not allowed“

6

Validate "tax_id"

  • tax_id has validation pattern - `^[0-9]{10}$`

    • if doesn't match, return error 422 "string does not match pattern ..."

  • NHS employee can update birth_date, but

  • (If VALIDATE_TAX_ID_WITH_BIRTH_DATE_GENDER_AND_CHECK_SUM is false then ok

    • If (GetBirthDateFromTaxId($.tax_id) != $.birth_date) or (GetGenderFromTaxId($.tax_id) != $.gender) then

      • in case of error, return 422 “Person's tax ID is not valid.“)

    • else ok

  • NHS employee can update tax_id:

    • from null to tax_id2, in case that there is no any person with tax_id2
      if tax_check_cnt_1 = 0 then ok
      How to get tax_check_cnt_1: select count(*) tax_check_cnt_1 select * from persons where tax_id = $.person.tax_id and status = 'active' and id <> $.person.id and is_active = true

      • in case of error, return 422 “There is another active person in DB with the same Tax_id. Updates to Personal data were not saved. “

    • And from tax_id1 to tax_id2, in case that there is no any person with tax_id2
      if tax_check_cnt_1 = 0 then ok
      How to get tax_check_cnt_1: select count(*) tax_check_cnt_1 select * from persons where tax_id = $.person.tax_id and is_active = 'active' and id <> $.person.id

      • in case of error, return 422 “There is another active person in DB with the same Tax_id. Updates to Personal data were not saved. “

    • from tax_id1 to null

    • from null to null

7

Check "no_tax_id" flag

  • "no_tax_id" can be null in the message, if tax_id is null also.

  • If "no_tax_id"= true, tax_id field should be empty

    • in case of error return 422

  • If "no_tax_id"=false and age>14, tax_id should be present

    • in case of error return 422

8

Validate person documents

  1. issued_at, issued_by is mandatory for documents

  2. Validate dates

    1. issued_at <= now() and issued_at => birth_date

      1.  in case `issued_at > now()` show error 422, "Document issued date should be in the past"

      2.  in case `issued_at < person.birth_date` show error 422, "Document issued date should greater than person.birth_date "

    2. expiration_date > now()

      1.  in case error show 422, "Document expiration_date should be in the future"

      2. expiration_date is mandatory for document_type

        • NATIONAL_ID

        • COMPLEMENTARY_PROTECTION_CERTIFICATE

        • PERMANENT_RESIDENCE_PERMIT

        • REFUGEE_CERTIFICATE

        • TEMPORARY_CERTIFICATE

        • TEMPORARY_PASSPORT

      3. in case of error return 422, "expiration_date is mandatory for document_type $.documents.type"

  3. Validate documents_type.number according to json schema 

    1. PASSPORT - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`

    2. NATIONAL_ID - `^[0-9]{9}$`

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

    4. COMPLEMENTARY_PROTECTION_CERTIFICATE - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`

    5. REFUGEE_CERTIFICATE - `^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$`

    6. TEMPORARY_CERTIFICATE - `^(((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{4,6}|[0-9]{9}|((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{5}\\/[0-9]{5})$`

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

  4. 'unzr' can be with null value in the message.

  5. if `unzr` exists and is not null and matches "^[0-9]{8}-[0-9]{5}$" check if first 8 symbols = birth_date

    1. in case of error return 422, msg "Birthdate or unzr is not correct"

  6. if documents.type=NATIONAL_ID

    1. check if unzr exists in request, in case of error return 422, msg "unzr is mandatory for document type NATIONAL_ID"

  7. Document numbersmaxLength < 25 

  8. Check that submitted document type exists in IDENTITY_DOCUMENT_TYPES config parameter

    1. in case of error - return 422 ('Submitted document type is not allowed')

  9. Check submitted person document types exist in PERSON_REGISTRATION_DOCUMENT_TYPES config parameter that contains values from DOCUMENT_TYPE dictionary

    • in case of error - return 422 ('Submitted document type is not allowed')

  10. Check document types from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter (that prove persons legal capacity) are not submitted if persons age is less then no_self_registration_age global parameter or greater then person_full_legal_capacity_age global parameter

    • in case of error - return 422 ('<Document type> can not be submitted for this person') with first found document type

  11. If at least one document type from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter is submitted, check that at least one document type from PERSON_REGISTRATION_DOCUMENT_TYPES is submitted

    • in case of error - return 422 ('Document that proves personal data must be submitted.')

  12. If at least one document type from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter is submitted, check that only one legal capacity document type is submitted

    • in case of error - return 422 ('Only one legal capacity document must be submitted')

9

Validate NHS request fields

  • nhs_request_number, nhs_request_comment are mandatory

  • Validate them according to json schema 

    • if doesn't match, return error 422 “ required property %{property} was not present"

JSON validation schema

What should be other for NHS Admin Panel

As a basis this JSON Schema validator (https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/589266986#Update-person-request ) is used. Except:

  1. “patient_signed" and "process_disclosure_data_consent" are not required and should not be present.

  2. allow null value in second_name field of the Person object.

    1. "second_name": { "type": [ "string", "null" ] }

  3. allow null value in unzr field of the Person object

    1. "unzr": { "type": [ "string", "null" ], "pattern": "^[0-9]{8}-[0-9]{5}$" }

  4. allow in message both tax_id, no_tax_id with null values if they are both set to null

  5. updatedAtForValidation key and grouping key nhs_request_number, nhs_request_comment are validated with the following validation Schema:

 validation of nhsComment and updatedAtForValidation
  "nhs_request_number": {
  "type": "string",
  "description": "NHS internal Docflow's number of Person's official request to NHS",
  "maxLength": 50
  },
  "nhs_request_comment":{
  "type": "string",
  "description": "Title of an official Person's request to NHS or a description of that official request to NHS"},
  "maxLength": 3000
  }


    "updatedAtForValidation": {
      "type": "string",
      "format": "date-time"
    }

Execution

Search pending person_requests in IL.person_requests

Search persons request  in IL.person_requests to prevent inconsistent parallel updates:

WHERE IL.person_requests.person_id = :($.person.id)
  AND IL.person_requests.status IN ('NEW', 'APPROVED')

Cancel person_requests records in IL.person_requests

Change status of all found person requests:

SET   IL.person_requests.status = 'CANCELED'
WHERE IL.person_requests.id IN (:LIST of Search results)

Create new record in IL.person_requests

  1. Insert [new record] to IL.person_requests:

    1. Set status = 'SIGNED'. 

    2. Set Person’s id, person_id = $.person.id

    3. Set inserted_at= now() (Get current date-time)

    4. Set inserted_by - user_id (Extract user from token)

    5. Set channel, IL.person_request.(newrecord).channel = 'NHS'

    6. Set printout_form = null

Store signed_content in appropriate Person_request Bucket.

Update Person in MPI.persons

  1. Update Person’s data in MPI.persons.(id = $.person.id) with submitted new data $ (including two $.nhs_request_number and$.nhs_request_comment).

  2. Set updated_at - now() (Get current date-time)

  3. Set updated_by - user_id (Extract user from token)

  4. Create appropriate records based on submitted new data $ (including two $.nhs_request_number and$.nhs_request_comment) in:

    1. MPI.person_documents

    2. MPI.person_phones

    3. MPI.person_addresses

Submit person on verification

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

Set person verification according to logic https://e-health-ua.atlassian.net/wiki/spaces/DRACS2/pages/17858101317/UPD+Sign+person+request+v2#Manual-NHS-verification

DRFO registry verification

Set person verification according to logic https://e-health-ua.atlassian.net/wiki/spaces/DRACS2/pages/17858101317/UPD+Sign+person+request+v2#DRFO-registry-verification

DRACS death acts registry verification

Set person verification according to logic https://e-health-ua.atlassian.net/wiki/spaces/DRACS2/pages/17858101317/UPD+Sign+person+request+v2#DRACS-death-acts-registry-verification

DRACS birth acts registry verification

Set person verification according to logic https://e-health-ua.atlassian.net/wiki/spaces/DRACS2/pages/17858101317/UPD+Sign+person+request+v2#DRACS-birth-acts-registry-verification

DRACS name change acts registry verification

Set person verification according to logic: https://e-health-ua.atlassian.net/wiki/spaces/DRACS2/pages/17858101317/UPD+Sign+person+request+v2#DRACS-name-change-acts-registry-verification

Legal capacity verification

Set person verification according to logic: https://e-health-ua.atlassian.net/wiki/spaces/DRACS2/pages/17858101317/UPD+Sign+person+request+v2_EN#Legal-capacity-verification

Calculate cumulative verification status

Calculate persons cumulative verification status according to logic https://e-health-ua.atlassian.net/wiki/spaces/DRACS2/pages/17858101317/UPD+Sign+person+request+v2#Calculate-cumulative-verification-status

Update confidant person relationships

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 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 existence 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 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

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 existence 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 = ‘CONFIDANT_PERSON_UPDATED’

  • updated_at = now()

Response

Updated personal data of a Person:

  • person: Person! (typename: Person)

  • No labels

ЕСОЗ - публічна документація