Purpose
This WS is used to create Person Request (as part of Person creation w/o declaration process). Upon successful completion of the whole process, a person is created in MPI. Also this WS allows to update the person’s data according to his id, which was previously found.
Specification
Key points
This WS can be used for both creating new person and updating existing person.
Person authentication method shouldnt be passed in request for update person.
Main differences from V1
Confidant_person is an object, not an array.
It is allowed to submit confidant person when person is created.
It is not allowed to submit confidant person when person is updated.
Validation of confidant person is updated: age, verification status and auth methods are important.
Validation of auth methods is updated: in case if person has confidant, as THIRD_PERSON in auth methods must be submitted confidant.
Validation of person documents is updated: if person`s age is between no_self_registration_age and person_full_legal_capacity_age, documents that prove legal capacity can be sumbitted. In case if legal capacity is provenoven by document, person can not have confidant.
Validate necessity of confidant person is added: in some cases (view on validations below) it is necessary to have confidant if person is created (in the request body) and if person is updated (in db https://e-health-ua.atlassian.net/wiki/spaces/EDDR/pages/18048483381/MPI#confidant_person_relationships).
Links to save documents for confidant persons are updated.
When person, that is updated, must be authorized by confidant person - authentication method with type = THIRD_PERSON must be passed in
authorize_withfield.
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)
If BLOCK_UNVERIFIED_PARTY_USERS is true, then check party's data match following condition: verification_status != NOT_VERIFIED or (verification_status = NOT_VERIFIED and updated_at > current_date - UNVERIFIED_PARTY_PERIOD_DAYS_ALLOWED):
in case not match - return 403 ("Access denied. Party is not verified")
If BLOCK_DECEASED_PARTY_USERS is true, check that party is not deceased (party_verification record does not equal to: dracs_death_verification_status = VERIFIED and dracs_death_verification_reason = MANUAL_CONFIRMED):
in case of error - return 403 ("Access denied. Party is deceased")
Determine person request process
Check existence of $.person.id field in request:
if not exists - proceed to Create person request process
if exists - process to Update person request process
Create person request
Validate request
Validate 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')
Validate client
Check that client_id belongs to legal entity with type from PERSON_REQUEST_LEGAL_ENTITY_TYPES config parameter
in case of error - return 409 ('Invalid legal entity type')
Check that client_id belongs to active legal entity (status = active and is_active = true)
in case of error - return 409 ('Legal entity is not active')
Validate tax id
Check that
tax_idfield matches pattern^[0-9]{10}$in case of error - return 422 ('string does not match pattern’) with the corresponding regexp
If VALIDATE_PERSON_TAX_ID_UNIQUENESS chart param is true, then check there is no another active person with the same
tax_idin the systemin case of error - return 422 ('tax_id is already used by another person')
Validate no_tax_id flag
If
no_tax_id= true, check thattax_idfield is emptyin case of error - return 422 ('Persons who refused the tax_id should be without tax_id')
If
no_tax_id= false and persons age > no_self_auth_age global parameter, check thattax_idis presentin case of error - return 422 ('Only persons who refused the tax_id could be without tax_id')
Validate patient_signed flag
Check
patient_signedfield is present in requestin case of error - return 422 ('required property patient_signed was not present')
Check that
patient_signed= false in requestin case of error - return 422 ('value is not allowed in enum')
Validate process_disclosure_data_consent flag
Check
process_disclosure_data_consentfield is present in requestin case of error - return 422 ('required property process_disclosure_data_consent was not present')
Check that
process_disclosure_data_consent= true in requestin case of error - return 422 ('value is not allowed in enum')
Validate person addresses
Check that at least one address record with
type = 'RESIDENCE'is submittedin case of error - return 422 ('one and only one residence address is required')
Validate necessity of confidant person
A block with information about confidant person must be transferred when the person is created.
New endpoints /wiki/spaces/CSI/pages/17613291561 must be used to manage list of persons confidants.
Source:
In case if persons age < no_self_registration_age global parameter - check that confidant_person is submitted
in case of error - return 422 ('Confidant person is mandatory for children.')
In case if persons age is greater then no_self_registration_age global parameter, but less then person_full_legal_capacity_age global parameter:
if none of persons documents has type from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter - check that confidant_person is submitted
In case of error - return 422 ('Confidant person is mandatory for minor patients.')
Else if at least one of submitted person document types exist in PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter - check that confidant_person is not submitted
in case of error - return 422 ('Confidant can not be submitted for person who has document that proves legal capacity.')
Validate confidant person
Confidant person must be validated only if $.person.confidant_person block is presented in the request:
Check that confidant_person.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 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;
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 /wiki/spaces/CSI/pages/17667883028 with
person_id=$.person.confidant_person.person_idfrom request - expected:ok, :approvedresponse)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 that 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 that confidant person has active authentication method with type = OTP
in case of error - return 422 ('Confidant person must have active authentication method with type "OTP"')
Validate confidant persons
documents_relationshipValidate document
issued_atdateCheck 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_todateCheck that active_to > now()
in case error - return 422 ('Document active_to should be in future')
Validate document
typeaccording to DOCUMENT_RELATIONSHIP_TYPE dictionaryIn case of error - return 422 ('value is not allowed in enum')
Validate document
numberaccording to regexp (as part of JSON Schema validation)BIRTH_CERTIFICATE -
^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$In case of error - return 422 ('string does not match pattern') with the corresponding regexp
other document type numbers should be validated according to format varchar (255)
in case of error - return 422 ('expected value to have a maximum length of 255 but was <<document_number_length>>')
Validate person documents
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')
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
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.')
Validate document
issued_atdateCheck 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
expiration_dateif PERSON_DOCUMENTS_USE_SPECIFIC_EXPIRATION_DATE == true:
check that "expiration_date" > PERSON_DOCUMENTS_SPECIFIC_EXPIRATION_DATE
in case error show 422, "Document expiration_date should be more than <PERSON_DOCUMENTS_SPECIFIC_EXPIRATION_DATE>"
else PERSON_DOCUMENTS_USE_SPECIFIC_EXPIRATION_DATE == false:
check that "expiration_date" > now()
in case error show 422, "Document expiration_date should be in future"
Check that expiration_date exists for following document types:
NATIONAL_ID
COMPLEMENTARY_PROTECTION_CERTIFICATE
PERMANENT_RESIDENCE_PERMIT
REFUGEE_CERTIFICATE
TEMPORARY_CERTIFICATE
TEMPORARY_PASSPORT
in case error - return 422 ('expiration_date is mandatory for document_type $.documents.type')
Validate document
numberaccording to regexp (as part of JSON Schema validation)PASSPORT -
^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$NATIONAL_ID -
^[0-9]{9}$BIRTH_CERTIFICATE -
^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$COMPLEMENTARY_PROTECTION_CERTIFICATE -
^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$REFUGEE_CERTIFICATE -
^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$TEMPORARY_CERTIFICATE -
^(((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{4,6}|[0-9]{9}|((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{5}\\/[0-9]{5})$TEMPORARY_PASSPORT -
^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$CHILD_BIRTH_CERTIFICATE -
^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$MARRIAGE_CERTIFICATE -
^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$DIVORCE_CERTIFICATE -
^((?![ЫЪЭЁыъэё@%&$^#`~:,.*|}{?!])[A-ZА-ЯҐЇІЄ0-9№\\/()-]){2,25}$in case of error - return 422 ('string does not match pattern') with the corresponding regexp
If
unzrexists and is not null, check that it matches pattern -^[0-9]{8}-[0-9]{5}$in case of error - return 422 ('string does not match pattern') with the corresponding regexp
If document with
typeNATIONAL_ID exists in request, check thatunzrexists in requestin case of error - return 422 ('unzr is mandatory for document type NATIONAL_ID')
Check that document types NATIONAL_ID and PASSPORT both do not exist in request
in case of error - return 422 ('Person can have only new passport NATIONAL_ID or old PASSPORT.')
Check that document types BIRTH_CERTIFICATE or BIRTH_CERTIFICATE_FOREIGN are submitted if persons age < no_self_auth_age global parameter
in case of error - return 422 ('Documents should contain one of: BIRTH_CERTIFICATE, BIRTH_CERTIFICATE_FOREIGN.')
Check that document
numberlength < 255in case of error - return 422 ('expected value to have a maximum length of 255 but was <<document_number_length>>')
Search pending declaration requests
Search declarations request in IL.declaration_requests to prevent duplication:
if
$.person.tax_idis not null, search with following parameters:data_person_tax_id =
$.person.tax_idstatus = NEW or APPROVED
if
$.person.tax_idis null, search with following parameters:data_person_documents.[i].number =
$.person.documents.[i].numberstatus = NEW or APPROVED
If found declaration request - return 409 ('This person already has a declaration request')
Search person
We are looking for a person to prevent duplication of a person.
Create pairs of new person with people from clusters (tax_id, phone_number and number of the document) and send to the deduplication model.
Compare score for each pair with PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE config parameter:
in case score < PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE - create new person
in case score > PERSON_ONLINE_DEDUPLICATION_MATCH_SCORE - return 409 ('Such person exists. Update this person')
Validate person authentication methods
A block with information about authentication methods must be transferred when the person is created.
It is prohibited to transfer authentication methods when the person is updated.
Endpoints (described here Authentication Methods Technical Requirements) must be used to update persons authentication methods.
Check that only one authentication method is submitted for person
in case of error - return 422 ('expected a maximum of 1 items but got <<count_authentication_method_objects>>')
In case if
person.confidant_personblock is not empty:Check that submitted
authentication_methodsrecord hastype = 'THIRD_PERSON'in case of error - return 422 ('Only THIRD_PERSON authentication method can be created for person')
Check that THIRD_PERSON is the same person who is submitted as confidant (
authentication_methods[0].value = confidant_person[0].person_id)in case of error - return 422 ('Confidant person must be submitted as THIRD_PERSON for authentication method')
Check that THIRD_PERSON is found less than third_person_limit global parameter value in the system (in table person_authentication_methods with value = authentication_methods[0].value& ended_at іs empty or > now() & type = THIRD_PERSON)
in case of error - return 422 ('This fiduciary person is present more than $.global_parameters.third_person_limit times in the system')
Else if
person.confidant_personblock is empty:Check that submitted
authentication_methodsblock contains record withtype = 'OTP'ortype = 'OFFLINE'in case of error - return 422 ('Only OTP or OFFLINE authentication method can be created for person')
For authentication method with type = ‘OTP’ perform following phone number limit validation only if USE_PHONE_NUMBER_AUTH_LIMIT config parameter is set to
true:check that phone number from persons authentication method is found less than phone_number_auth_limit global parameter in the system (in table person_authentication_methods with phone_number = $.person.authentication_methods.[0].phone_number & ended_at іs empty or > now() & type = OTP)
in case of error - return 409 ('This phone number is present more then $.global_parameters.phone_number_auth_limit times in the system')
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.
Validate block confidant person. If
$.person.confidant_personis not null:Generate URLs with type
confidant_person.{confidant_person.person_id}.documents_relationship.[:].{type}
Validate block of person documents. If one of the documents has document.type = BIRTH_CERTIFICATE_FOREIGN and there is no same document in {$.person_request.person.confidant_person.[:].documents_relationship.[:]}
and persons age < no_self_auth_age global parameter then
Generate URL with type
person.BIRTH_CERTIFICATE_FOREIGN
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
Generate URL with type
person.PERMANENT_RESIDENCE_PERMIT
Validate block of authentication methods. If authentication method type = OFFLINE
Generate URLs with type
person.{$.person.documents.[:].type}for each persons document
Validate persons unzr. If$.person.unzris not emptyandfirst 8 digits of$.person.unzr != $.person.birth_dateGenerate URL with typeperson.unzr
Invoke Media Content Storage to generate upload URL for each document obtained by executing logic above and save documents to DB.
Search pending person requests
Search pending person requests in IL.person_requests to prevent requests duplication based on person request data:
if
$.person.tax_idis not null, search with following parameters:tax_id =
$.person.tax_iddocuments.[i].number =
$.person.documents.[i].numberstatus = NEW or APPROVED
if
$.person.tax_idis null, search with following parameters:documents.[i].number =
$.person.documents.[i].numberfirst_name =
$.person.first_namelast_name =
$.person.last_namestatus = NEW or APPROVED
Cancel person request
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 =
$.personfrom request in json formatstatus = NEW
authentication_method_current = type for auth method that is used to authorize request (set phone_number for type OTP or THIRD_PERSON with type OTP)
channel = MIS
legal_entity_id = client_id from token (id of legal entity where person request is created)
tax_id =
$.person.tax_idfrom request (if not null)last_name =
$.person.last_namefrom requestfirst_name =
$.person.first_namefrom requestbirth_date =
$.person.birth_datefrom requestdocuments = generated links for documents upload (if needed)
person_documents =
$.person.documentsfrom request in json formatinserted_by = user_id from token
updated_by = user_id from token
inserted_at = now()
updated_at = now()
patient_signed =
$.patient_signedfrom requestprocess_disclosure_data_consent =
$.process_disclosure_data_consentfrom requestversion = 2
Generate verification code
In case if person request authentication_method_current.type = OTP, invoke Initialize OTP to generate one time password and send it to persons or confidants 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 a person.
Update person request
It is necessary to transfer the same json as when creating person, only to transfer the id of an existing person and do not transfer the block with the authentication methods and confidant person.
Validate existing person
If $.person.id is submitted in request then:
Check that
$.person.idis a valid uuidin case error - return 422 ('string does not match pattern') with uuid regexp
Check that person exists in persons table (MPI DB) with status = active and is_active = true
in case error - return 404 ('Person does not exist.’)
Check that amount of changes of person data in request is acceptable (person is not updated too much). Compare updated person data with data from person request using existing deduplication model - check that resulted comparison score is greater that PERSON_ONLINE_DEDUPLICATION_UPDATE_SCORE config parameter
in case of error - return 409 ('Such person can't be updated. Deduplication update score is lower than system value (less changes should be made)')
Update person’s data with empty value of the second name is possible by setting second_name = null.
Validate request
Validate request using JSON schema
Validate client
Validate as on Create person request process
Validate tax id
If updated persons tax_id is not null - check that
$.person.tax_idequals to updated persons tax_idin case of error - return 422 ('tax_id can't be updated')
Validate as on Create person request process
Validate no_tax_id flag
Validate as on Create person request process
Validate patient_signed flag
Validate as on Create person request process
Validate process_disclosure_data_consent flag
Validate as on Create person request process
Validate person addresses
Validate as on Create person request process
Validate person documents
Validate as on Create person request process
Validate authorize_with
The person can pass the id of his auth method which he wants to use to confirm the update person request. The necessary auth method can be found by making Get person's auth methods.
Check that
$.authorize_withwith auth_method.type = 'THIRD_PERSON' is submitted for person that must be authorized by confidant person using following logic: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 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 /wiki/spaces/CSI/pages/17667883028 with
person_id= person from request - expected:ok, :approvedresponse)in case of error - return 422 ('Authentication method with type THIRD_PERSON must be submitted for this person')
Check that
$.authorize_withis a valid uuidin case error - return 422 ('string does not match pattern') with uuid regexp
Check that auth method exists in MPI database,
person_authentication_methodstable, belongs to person from request, stored in$.person.id, is active (ended_at > now() or ended_at is null and is_active = true), and type != NA, additionally for auth method with type = ‘THIRD_PERSON’ - check that person from value is an approved confidant for a$.person.idfrom request – exists active and approved confidant person relationship between person from request and person_id from authentication method value (using following logic: /wiki/spaces/CSI/pages/17667883028 withperson_id= person from request andconfidant_person_id= value from auth method - expected:ok, :approvedresponse)in case error - return 409 ('Authentication method doesn't belong to person.')
This field is optional and set in authentication_method_current field of person request.
If person request doesn't have this field, then choose that method which is returned from mpi as using following process.
Determine authentication method current for request
If
$.authorize_withis not null - set its value as authentication method current for requestIf
$.authorize_withis null - set default auth method as authentication method current for request - use function in mpi that return default auth methodCheck that persons default auth method != NA
in case of error - return 409 ('Person does not have active auth methods.')
Search pending declaration requests
Search as on Create person request process
Generate upload URL
Generate upload URL as on Create person request process
Search pending person requests
Search as on Create person request process
Cancel person request
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 =
$.personfrom request in json formatstatus = NEW
authentication_method_current = calculated authentication method current for request (set phone_number for type OTP or THIRD_PERSON with type OTP)
channel = MIS
legal_entity_id = client_id from token (id of legal entity where person request is created)
tax_id =
$.person.tax_idfrom request (if not null)last_name =
$.person.last_namefrom requestfirst_name =
$.person.first_namefrom requestbirth_date =
$.person.birth_datefrom requestdocuments = generated links for documents upload (if needed)
person_documents =
$.person.documentsfrom request in json formatinserted_by = user_id from token
updated_by = user_id from token
inserted_at = now()
updated_at = now()
patient_signed =
$.patient_signedfrom requestprocess_disclosure_data_consent =
$.process_disclosure_data_consentfrom requestperson_data_id =
$.person.idfrom requestauthorize_with =
$.authorize_withfrom request (if not null)version = 2
Generate verification code
In case if person request authentication_method_current.type = OTP, invoke Initialize OTP to generate one time password and send it to persons or confidants 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 a person.