/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)
Properties of a REST API method document
...
Document type
...
Метод REST API
...
Document title
...
[Document status] REST API [Назва методу] [ID методу]
...
Guideline ID
...
GUI-0011
...
Author
...
@
...
Document version
...
1
...
Document status
...
DRAFT
...
Date of creation
...
ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
...
Date of update
...
ХХ.ХХ.ХХХХ (дата зміни версії)
...
Method API ID
...
API-007-011-001-0478
...
Microservices (namespace)
...
MPI
...
Component
...
Auth
...
Component ID
...
COM-007-011
...
Link на API-специфікацію
...
...
Resource
...
{{host}}//api.ehealth.gov.ua/api/patients/id/encounter_package
...
Scope
...
Protocol type
...
REST
...
Request type
...
Sync/Async
...
Public/Private
Purpose
This WS is designed to create approval on
entity, which aggregate other entities (episode_of_care, diagnostic_report, care_plan),
OR forbidden group
OR diagnoses group,
OR on service_request including it’s permitted_resources
OR on cancel for encounter, specimen and procedure.
Approvals are processed in the async way
Only authenticated and authorized employees with appropriate scope can create approval.
Logic
Description of the working algorithm of the API method and the interaction of services with each other add Service logic (if necessary)
Configuration parameters
Description of the configuration parameters that are used when processing a request in the system
Dictionaries
Provides a list of links to dictionaries that are available in Confluence
Input parameters
Description of input parameters
...
Input parameter
...
Mandatory
...
Type
...
Description
...
Example
...
composition_id
...
M
...
String ($uuid) (path)
...
Composition object ID
...
89678f60-4cdc-4fe3-ae83-e8b3ebd35c59
...
...
...
...
...
Request structure
See on API-specification (посилання на сторінку з API-специфікацією)
Description of the REST API request structure, example
...
| title | Example |
|---|
...
Headers
...
Key
...
Value
...
Mandatory
...
Description
...
Example
...
Content-Type
...
application/json
...
M
...
Тип контенту
...
Content-Type:application/json
...
Authorization
...
Bearer c2778f3064753ea70de870a53795f5c9
...
M
...
Перевірка користувача
...
Authorization:Bearer c2778f3064753ea70de870a53795f5c9
...
...
...
...
...
Request data validation
Validation of related entities
Validate user
Granted_to.employee_id should be active
in case of error - return 422 “Should be active“
If resource from granted_to != 'legal_entity':
Check if employee from the same legal entity as user:
client_id from token should be linked with employee_id from granted_to object.
in case of error - return 422 “Employee <employee_id> doesn't belong to your legal entity“
Check employee_type is from list of employee types configuration CREATE_APPROVAL_ALLOWED_EMPLOYEE_TYPES
in case of error - return 422 “Invalid employee type“
Validate person authentication_method
If resource = care_plan & care_plans.terms_of_service = ‘INPATIENT'&granted_to.employees.legal_entity_id = care_plans.managing_organization:
skip validation of person authentication_method
set approvals.urgent = null
In other cases:
Check patient_id:
if belongs to person, then GET auth_method from MPI using {patient_id}
If it's OTP:
send SMS to the auth_phone via otp_verification service POST /verifications
save authentication_method_current.type and number to Mongo DB
return authentication_method_current.type = OTP
If it is offline
save authentication_method_current.type to Mongo DB
return authentication_method_current.type = offline
if it is null:
return error 409 (Person does not have active authentication method)
if belongs to preperson:
set approval urgent = null
Validation of the request
Validate resources or block of resources
Approvals are processed in the async way
Validate resources
Search for the resource in DB is done by the pair patient_id + resources_id due to solution architecture when all resources must be discovered via patient identifier
In case no records found using this combination - system will respond with 404 error
...
if episode_of_care is presented in request as the code of resource
Check episode_of_care in the request exists and is in active or closed status in DB
in case of error return - 422 (Episode is canceled)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
...
if diagnostic_report is presented in request as the code of resource
Check diagnostic_report block in the request exists and is in final status in DB
in case of error return - 422 (Diagnostic report in \"entered_in_error\" status can not be referenced or Diagnostic report with such id is not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
...
if care_plan is presented in request as the code of resource
Check care_plan in the request exists in DB
in case of error return - 422 (Care plan with such id is not found)
Check there no other objects in request
in case of error return - 422 (Approval for care plan can not contain other entities)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
If access_level = 'write':
Check if care_plans.managing_organization = granted_to.employees.legal_entity_id:
in case of error return - 422 ('User is not allowed to write care plan from another legal_entity')
...
if encounter is presented in request as the code of resource
Check encounter in the request exists in DB and is not in “entered_in_error” status in DB
(Encounter in \"entered_in_error\" status can not be referenced or Encounter with such id is not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
...
if procedure is presented in request as the code of resource
Check procedure in the request exists in DB and is not in “entered_in_error” status in DB
in case of error return - 422 (Procedure in \"entered_in_error\" status can not be referenced)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
...
if specimen is presented in request as the code of resource
Check specimen in the request exists in DB and is not in “entered_in_error” status in DB
in case of error return - 422 (Specimen in \"entered_in_error\" status can not be referenced)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
if composition is presented in request as the code of resource
...
in case of error return - 422 (Composition in \"entered_in_error\" status can not be referenced)
...
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate service_request
If service_request block is presented in request
Get Service_request details (only in active status)
use Response.permitted_resources as resources for approval(could be episode or diagnostic_report).
If resource from granted_to = 'legal_entity':
Check if status of legal_entity in (ACTIVE, SUSPENDED, REORGANIZED):
in case of error return - 422 (Legal entity should be active)
Validate forbidden_group
if forbidden_group block is presented in request
Check forbidden group in the request exists and is_active in DB
in case of error return - 404 (not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate diagnoses_group
if diagnoses_group block is presented in request
Check diagnoses_group in the request exists and is_active in DB
in case of error return - 404 (not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate service_group
if service_group block is presented in request
Check services_group in the request exists and is_active in DB
in case of error return - 404 (not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate composition
If composition block is presented in request do the following validations
Validate value in the field $.composition, Reference, optional.
...
in case of error return - 404 (not found)
...
Check the resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate patient
if patient block is presented in request
Get patient_id from URL:
Check person_id from the request equal to the patient_id from URL
in case of error return - 404 (“Approval for one patient can not be created in another patient’s context”)
exists and is_active in DB
in case of error return - 404 (Person is not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate resource_types
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Check that requested
resource_typesare any of the following [device, device_association, detected_issue]in case of error return - 422 ("$.resource_types value is not allowed in enum")
Check that device and device_association requested in
resource_typesas they are both requiredin case of error return - 422 ("$.resource_types device and device_association are required)
Validate created_by
Validate value in the field $.created_by, optional.
Extract user_id from token. Check that author belongs to one of the user’s employee.
in case of error - return 422 ('User is not allowed to create approval for the employee')
Check that author is an active and approved employee and related to the legal entity (client_id from token).
in case of error - return 403 ('Access denied')
Validate block child_resource
if child_resource is not empty:
validate that access_level == read
in case of error return - 422 ("$.access_level. value is not allowed in enum")
check that $.child_resource.identifier.value context is equal to $.resource.identifier.value
in case of error return - 422 (Child resource context id is not equal to granted resource id)
validate that service_requests / forbidden_groups / diagnoses_group / patients are not filled
in case of error return - 422 (schema does not allow additional properties)
validate that resources max items = 1
in case of error return - 422 ($.resources.expected a maximum of 1 items but got 2)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate access_level
Validate that access_level correspond to granted_resources:
In case error return 422 ("Resource types [\"$.granted_resources[].code\"] not allowed to use write access_level")
If employee_type of granted_to.identifier.value employee == ASSISTANT:
Check that access_level == ‘read’:
In case error return 422 ("Role ASSISTANT is not allowed to use write access_level for approval")
...
block
...
granted_resources
...
context
...
access_level
...
access to
...
reason
...
resources
...
episode_of_care
...
...
read
...
Reading all the data of specified in approval episode
...
null or child_resource
...
diagnostic_report
...
read
...
Reading all the data of specified in approval diagnostic report
...
diagnostic_report
...
write
...
Canceling diagnostic report package
...
care_plan
...
read
...
Reading all the data of specified in approval care plan
...
care_plan
...
write
...
Creating activities for care plan, cancelling medication requests or recalling/cancelling service requests based on care plan
...
encounter
...
write
...
Canceling encounter data package
...
procedure
...
write
...
Canceling procedure
...
specimen
...
write
...
Canceling specimen
...
composition
...
write
...
Mark in error composition
...
child_resources
...
diagnostic_report
...
episode_of_care
...
read
...
Reading all the data of specified in context for diagnostic_report
...
null
...
encounter
...
episode_of_care
...
Reading all the data of specified in context for encounter
...
null
...
condition
...
episode_of_care
...
Reading all the data of specified in context for condition
...
null
...
observation
...
episode_of_care
diagnostic_report
...
Reading all the data of specified in context for observation
...
null
...
activity
...
care_plan
...
Reading all the data of specified in context for activity
...
null
...
clinical_impression
...
episode_of_care
...
Reading all the data of specified in context for clinical_impression
...
null
...
allergy_intolerance
...
episode_of_care
...
Reading all the data of specified in context for allergy_intolerance
...
null
...
immunization
...
episode_of_care
...
Reading all the data of specified in context for immunization
...
null
...
device
...
episode_of_care
...
Reading all the data of specified in context for device
...
null
...
risk_assessment
...
episode_of_care
...
Reading all the data of specified in context for risk_assessment
...
null
...
procedure
...
episode_of_care
...
Reading all the data of specified in context for procedure
...
null
...
service_request
...
episode_of_care
...
...
read
...
Reading data from granted_resources in approval service request
...
service_request
...
diagnostic_report
...
...
read
...
forbidden_group
...
forbidden_group
...
...
read
...
Reading all the medical events with items (codes/services/service_groups) of specified in approval forbidden groups
...
null
...
diagnoses_group
...
diagnoses_group
...
...
read
...
Reading short data of episodes with current_diagnoses.codes that specified in approval diagnoses group
...
null
...
services_group
...
services_group
...
...
read
...
Reading short data of diagnostic reports and procedures with code.identifier.value that specified in approval service group
...
null
...
patient_id
...
patient_id
...
...
read
...
Reading all the data of specified patient
...
null
...
resource_types
...
device
...
...
read
...
Read all the data of specified patient and resource type
...
null
...
device_association
...
...
read
...
Read all the data of specified patient and resource type
...
null
...
detected_issue
...
...
read
...
Read all the data of specified patient and resource type
...
null
...
composition
...
composition
...
...
read
...
Read all the data of specified in approval composition including resources in composition sections and forbidden groups associated with such resources
...
null
Validate authorize_with
The patient can pass the id of his auth_method which he wants to confirm the approval. The necessary auth method can be found by making Get person's auth methods
...
сheck that $.authorize_with with 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 Check confidant person relationship 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”
...
validate auth_method.id is UUID
in case error return 422
...
search auth method in MPI.person_authentication_method
in case error return 422, "such authentication method doesn't exist"
...
search auth method of this patient where MPI.person_authentication_method.person_id = $.patient.id
in case error return 422, "such authentication method does not belong to this person"
...
in case of error - return 422 ‘Authentication method doesn't exist, is inactive or does not belong to this person’
...
validate if auth_method.type = NA
error return 422, "Сannot be confirmed by a method with type= NA. Use a different method."
...
validate that this method is active ( authentication_method.ended_at > now() and is_active = true)
This field is optional and set in new field authorize_with and save type and phone_number in approvals.urgent.authentication_method_current.
If approval doesn't have this field, then choose that method which is returned from mpi as person's default method.
Service logic
Set is_verified value to:
false if patient is person.
true if patient is preperson.
All the approvals where is_verified = false should be deleted 12 hours after creation - env. configuration parameter (APPROVAL_TTL_HOURS)
All approvals depends on value of granted_resources has its own expires_at config parameter - env. configuration parameter
Approvals with child_resources will be created ON entity which is context of this child_resources
For approvals on child_resource with resource and on service_request:
set child resource to block reason
set service_request to block reason
If block
resource_typespassed in request - it must be saved todb.approvals.granted_resource_types.db.approvals.granted_resourcesmust be emptyin all other scenarios
db.approvals.granted_resource_typesmust be empty
Specific approvals can request and provide additional permissions from patient to employee to get access to some sensitive information in requested resource
If approval is requested on Composition (block $.composition is presented in request)
Check each resource from
composition.section[].entry[](any level of hierarchy) to see if it matches with any of the rule of forbidden groups according to Medical Events filtration by Forbidden groupsIf if does - put forbidden group identifier to approval
append approval.forbidden_groups with the Reference to forbidden group(s)
If some resources matches with the same forbidden group that was already added - do not duplicate it
Determine SMS template based on the list of matched forbidden groups (see table below)
If approval is requested on child_resource (block $.composition is presented in request)
Check the resource from child_resource to see if it matches with any of the rules of forbidden groups according to Medical Events filtration by Forbidden groups
If if does - put forbidden group identifier to approval
append approval.forbidden_groups with the Reference to forbidden group(s)
Determine SMS template based on the list of matched forbidden groups (see table below)
If block
compositionpassed in request - put $.composition reference todb.approvals.granted_resourcesCheck type of authentication_method for patient:
If type = 'OTP' send SMS type of granted_to & type of entity in granted_resources:
...
granted_to
...
block
...
granted_resources
...
Sms
...
items with FG
...
w\o items with FG
...
employee
...
resources
...
episode_of_care
...
Код <code> для доступу до даних про <forbidden_groups.short_name> <forbidden_groups.sms_url>
If there are codes from more than 1 group:
Код <code> для доступу до даних про ВІЛ,РПП https://bit.ly/nszu1677f
...
Код авторизації дій в системі eHealth: <code>
...
diagnostic_report
...
care_plan
...
encounter
...
procedure
...
specimen
...
child_resources
...
diagnostic_report
...
encounter
...
condition
...
observation
...
activity
...
clinical_impression
...
allergy_intolerance
...
immunization
...
device
...
risk_assessment
...
procedure
...
service_request
...
episode_of_care
...
diagnostic_report
...
forbidden_group
...
forbidden_group
...
-(only with FG)
...
diagnoses_group
...
diagnoses_group
...
ICD10: Код <code>: доступ на групу діагнозів {diagnoses_group_code} http://bit.ly/nszu1677b
ICPC2: Код <code>: доступ на групу діагнозів {diagnoses_group_code} http://bit.ly/nszu1677e
...
services_group
...
services_group
...
Код ****: доступ на групу сервісів {service_group_code} http://bit.ly/nszu1677e
...
patient_id
...
patient_id
...
Код авторизації дій в системі eHealth: <code>
...
resource_types
...
device
...
Код <code>: доступ до інформації про медичні вироби пацієнта
...
...
device_association
...
...
detected_issue
...
composition
...
composition
...
Код авторизації дій в системі eHealth: <code>
...
granted_to
...
block
...
granted_resources
...
Sms
...
items with FG
...
w\o items with FG
...
legal_entity
...
service_request
...
episode_of_care
...
-(only w/o FG)
...
Код <code>: згода на обробку персональних даних https://bit.ly/nszu1677i)
Processing
A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API
Response structure examples
See on API-specification (посилання на сторінку з API-специфікацією)
Description of the REST API response structure, example
...
| title | Example |
|---|
...
/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)
Properties of a REST API method document
Document type | Метод REST API |
|---|---|
Document title | [DRAFT] [UPD] Create approval [API-007-011-001-0478] |
Guideline ID | GUI-0011 |
Author | @ |
Document version | 1 |
Document status | DRAFT |
Date of creation | ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD) |
Date of update | ХХ.ХХ.ХХХХ (дата зміни версії) |
Method API ID | API-007-011-001-0478 |
Microservices (namespace) | ME |
Component | Compositions_ME |
Component ID | COM-007-011 |
Link на API-специфікацію | |
Resource | {{host}}//api.ehealth.gov.ua/api/patients/id/encounter_package |
Scope | |
Protocol type | REST |
Request type | |
Sync/Async | |
Public/Private |
Purpose
This WS is designed to create approval on
entity, which aggregate other entities (episode_of_care, diagnostic_report, care_plan),
OR forbidden group
OR diagnoses group,
OR on service_request including it’s permitted_resources
OR on cancel for encounter, specimen and procedure.
Approvals are processed in the async way
Only authenticated and authorized employees with appropriate scope can create approval.
Logic
Service logic
Set is_verified value to:
false if patient is person.
true if patient is preperson.
All the approvals where is_verified = false should be deleted 12 hours after creation - env. configuration parameter (APPROVAL_TTL_HOURS)
All approvals depends on value of granted_resources has its own expires_at config parameter - env. configuration parameter
Approvals with child_resources will be created ON entity which is context of this child_resources
For approvals on child_resource with resource and on service_request:
set child resource to block reason
set service_request to block reason
If block
resource_typespassed in request - it must be saved todb.approvals.granted_resource_types.db.approvals.granted_resourcesmust be emptyin all other scenarios
db.approvals.granted_resource_typesmust be empty
Specific approvals can request and provide additional permissions from patient to employee to get access to some sensitive information in requested resource
If approval is requested on Composition (block $.composition is presented in request)
Check each resource from
composition.section[].entry[](any level of hierarchy) to see if it matches with any of the rule of forbidden groups according to Medical Events filtration by Forbidden groupsIf if does - put forbidden group identifier to approval
append approval.forbidden_groups with the Reference to forbidden group(s)
If some resources matches with the same forbidden group that was already added - do not duplicate it
Determine SMS template based on the list of matched forbidden groups (see table below)
If approval is requested on child_resource (block $.composition is presented in request)
Check the resource from child_resource to see if it matches with any of the rules of forbidden groups according to Medical Events filtration by Forbidden groups
If if does - put forbidden group identifier to approval
append approval.forbidden_groups with the Reference to forbidden group(s)
Determine SMS template based on the list of matched forbidden groups (see table below)
If block
compositionpassed in request - put $.composition reference todb.approvals.granted_resourcesCheck type of authentication_method for patient:
If type = 'OTP' send SMS type of granted_to & type of entity in granted_resources:
Configuration parameters
N/A
Dictionaries
N/A
Input parameters
Input parameter | Mandatory | Type | Description | Example | |
|---|---|---|---|---|---|
| 1 | patient_id |
| String | mpi_id. Required | aff00bf6-68bf-4b49-b66d-f031d48922b3 |
| 2 |
|
|
|
|
|
Request structure
See on API-specification
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
Headers
Request data validation
Authorize
Verify the validity of access token
in case of error - 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 = 'approval:create ')
return 403 (“Your scope does not allow to access this resource. Missing allowances: approval:create ”) in case of invalid scope(s)
Validation of related entities
Validate user
Granted_to.employee_id should be active
in case of error - return 422 “Should be active“
If resource from granted_to != 'legal_entity':
Check if employee from the same legal entity as user:
client_id from token should be linked with employee_id from granted_to object.
in case of error - return 422 “Employee <employee_id> doesn't belong to your legal entity“
Check employee_type is from list of employee types configuration CREATE_APPROVAL_ALLOWED_EMPLOYEE_TYPES
in case of error - return 422 “Invalid employee type“
Validate person authentication_method
If resource = care_plan & care_plans.terms_of_service = ‘INPATIENT'&granted_to.employees.legal_entity_id = care_plans.managing_organization:
skip validation of person authentication_method
set approvals.urgent = null
In other cases:
Check patient_id:
if belongs to person, then GET auth_method from MPI using {patient_id}
If it's OTP:
send SMS to the auth_phone via otp_verification service POST /verifications
save authentication_method_current.type and number to Mongo DB
return authentication_method_current.type = OTP
If it is offline
save authentication_method_current.type to Mongo DB
return authentication_method_current.type = offline
if it is null:
return error 409 (Person does not have active authentication method)
if belongs to preperson:
set approval urgent = null
Validation of the request
Validate resources or block of resources
Approvals are processed in the async way
Validate resources
Search for the resource in DB is done by the pair patient_id + resources_id due to solution architecture when all resources must be discovered via patient identifier
In case no records found using this combination - system will respond with 404 error
if episode_of_care is presented in request as the code of resource
Check episode_of_care in the request exists and is in active or closed status in DB
in case of error return - 422 (Episode is canceled)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
if diagnostic_report is presented in request as the code of resource
Check diagnostic_report block in the request exists and is in final status in DB
in case of error return - 422 (Diagnostic report in \"entered_in_error\" status can not be referenced or Diagnostic report with such id is not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
if care_plan is presented in request as the code of resource
Check care_plan in the request exists in DB
in case of error return - 422 (Care plan with such id is not found)
Check there no other objects in request
in case of error return - 422 (Approval for care plan can not contain other entities)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
If access_level = 'write':
Check if care_plans.managing_organization = granted_to.employees.legal_entity_id:
in case of error return - 422 ('User is not allowed to write care plan from another legal_entity')
if encounter is presented in request as the code of resource
Check encounter in the request exists in DB and is not in “entered_in_error” status in DB
(Encounter in \"entered_in_error\" status can not be referenced or Encounter with such id is not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
if procedure is presented in request as the code of resource
Check procedure in the request exists in DB and is not in “entered_in_error” status in DB
in case of error return - 422 (Procedure in \"entered_in_error\" status can not be referenced)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
if specimen is presented in request as the code of resource
Check specimen in the request exists in DB and is not in “entered_in_error” status in DB
in case of error return - 422 (Specimen in \"entered_in_error\" status can not be referenced)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
if composition is presented in request as the code of resource
Check composition in the request exists in DB and is notin “entered_in_error” status in DB
in case of error return - 422 (Composition in \"entered_in_error\" status can not be referenced)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate service_request
If service_request block is presented in request
Get Service_request details (only in active status)
use Response.permitted_resources as resources for approval(could be episode or diagnostic_report).
If resource from granted_to = 'legal_entity':
Check if status of legal_entity in (ACTIVE, SUSPENDED, REORGANIZED):
in case of error return - 422 (Legal entity should be active)
Validate forbidden_group
if forbidden_group block is presented in request
Check forbidden group in the request exists and is_active in DB
in case of error return - 404 (not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate diagnoses_group
if diagnoses_group block is presented in request
Check diagnoses_group in the request exists and is_active in DB
in case of error return - 404 (not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate service_group
if service_group block is presented in request
Check services_group in the request exists and is_active in DB
in case of error return - 404 (not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate composition
If composition block is presented in request do the following validations
Validate value in the field $.composition, Reference, optional.
Check composition exists in DB, is notin “entered_in_error” status and belongs to patient
in case of error return - 404 (not found)
Check the resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate patient
if patient block is presented in request
Get patient_id from URL:
Check person_id from the request equal to the patient_id from URL
in case of error return - 404 (“Approval for one patient can not be created in another patient’s context”)
exists and is_active in DB
in case of error return - 404 (Person is not found)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate resource_types
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Check that requested
resource_typesare any of the following [device, device_association, detected_issue]in case of error return - 422 ("$.resource_types value is not allowed in enum")
Check that device and device_association requested in
resource_typesas they are both requiredin case of error return - 422 ("$.resource_types device and device_association are required)
Validate created_by
Validate value in the field $.created_by, optional.
Extract user_id from token. Check that author belongs to one of the user’s employee.
in case of error - return 422 ('User is not allowed to create approval for the employee')
Check that author is an active and approved employee and related to the legal entity (client_id from token).
in case of error - return 403 ('Access denied')
Validate block child_resource
if child_resource is not empty:
validate that access_level == read
in case of error return - 422 ("$.access_level. value is not allowed in enum")
check that $.child_resource.identifier.value context is equal to $.resource.identifier.value
in case of error return - 422 (Child resource context id is not equal to granted resource id)
validate that service_requests / forbidden_groups / diagnoses_group / patients are not filled
in case of error return - 422 (schema does not allow additional properties)
validate that resources max items = 1
in case of error return - 422 ($.resources.expected a maximum of 1 items but got 2)
Check if resource from granted_to = 'employee':
in case of error return - 422 ("$.resource. value is not allowed in enum")
Validate access_level
Validate that access_level correspond to granted_resources:
In case error return 422 ("Resource types [\"$.granted_resources[].code\"] not allowed to use write access_level")
If employee_type of granted_to.identifier.value employee == ASSISTANT:
Check that access_level == ‘read’:
In case error return 422 ("Role ASSISTANT is not allowed to use write access_level for approval")
block | granted_resources | context | access_level | access to | reason |
|---|---|---|---|---|---|
resources | episode_of_care |
| read | Reading all the data of specified in approval episode |
null or child_resource |
diagnostic_report | read | Reading all the data of specified in approval diagnostic report | |||
diagnostic_report | write | Canceling diagnostic report package | |||
care_plan | read | Reading all the data of specified in approval care plan | |||
care_plan | write | Creating activities for care plan, cancelling medication requests or recalling/cancelling service requests based on care plan | |||
encounter | write | Canceling encounter data package | |||
procedure | write | Canceling procedure | |||
specimen | write | Canceling specimen | |||
composition | write | Mark in error composition | |||
child_resources | diagnostic_report | episode_of_care | read | Reading all the data of specified in context for diagnostic_report | null |
encounter | episode_of_care | Reading all the data of specified in context for encounter | null | ||
condition | episode_of_care | Reading all the data of specified in context for condition | null | ||
observation | episode_of_care diagnostic_report | Reading all the data of specified in context for observation | null | ||
activity | care_plan | Reading all the data of specified in context for activity | null | ||
clinical_impression | episode_of_care | Reading all the data of specified in context for clinical_impression | null | ||
allergy_intolerance | episode_of_care | Reading all the data of specified in context for allergy_intolerance | null | ||
immunization | episode_of_care | Reading all the data of specified in context for immunization | null | ||
device | episode_of_care | Reading all the data of specified in context for device | null | ||
risk_assessment | episode_of_care | Reading all the data of specified in context for risk_assessment | null | ||
procedure | episode_of_care | Reading all the data of specified in context for procedure | null | ||
service_request | episode_of_care |
| read | Reading data from granted_resources in approval service request | service_request |
diagnostic_report |
| read | |||
forbidden_group | forbidden_group |
| read | Reading all the medical events with items (codes/services/service_groups) of specified in approval forbidden groups | null |
diagnoses_group | diagnoses_group |
| read | Reading short data of episodes with current_diagnoses.codes that specified in approval diagnoses group | null |
services_group | services_group |
| read | Reading short data of diagnostic reports and procedures with code.identifier.value that specified in approval service group | null |
patient_id | patient_id |
| read | Reading all the data of specified patient | null |
resource_types | device |
| read | Read all the data of specified patient and resource type | null |
device_association |
| read | Read all the data of specified patient and resource type | null | |
detected_issue |
| read | Read all the data of specified patient and resource type | null | |
composition | composition |
| read | Read all the data of specified in approval composition including resources in composition sections and forbidden groups associated with such resources | null |
Validate authorize_with
The patient can pass the id of his auth_method which he wants to confirm the approval. The necessary auth method can be found by making Get person's auth methods
сheck that $.authorize_with with 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 Check confidant person relationship 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”
validate auth_method.id is UUID
in case error return 422
search auth method in MPI.person_authentication_method
in case error return 422, "such authentication method doesn't exist"
search auth method of this patient where MPI.person_authentication_method.person_id = $.patient.id
in case error return 422, "such authentication method does not belong to this person"
Get value of
THIRD_PERSON_CONFIDANT_PERSON_RELATIONSHIP_CHECKconfig parameter, if it is set totrue- for auth method type = ‘THIRD_PERSON’ validate that person from value is an approved confidant for a person from request – exists active and approved confidant person relationship between person from request and person_id from authentication method value (using following logic: Check confidant person relationship withperson_id= person from request andconfidant_person_id= value from auth method) - expected:ok, :approvedresponse)in case of error - return 422 ‘Authentication method doesn't exist, is inactive or does not belong to this person’
validate if auth_method.type = NA
error return 422, "Сannot be confirmed by a method with type= NA. Use a different method."
validate that this method is active ( authentication_method.ended_at > now() and is_active = true)
This field is optional and set in new field authorize_with and save type and phone_number in approvals.urgent.authentication_method_current.
If approval doesn't have this field, then choose that method which is returned from mpi as person's default method.
Processing
granted_to | block | granted_resources | Sms | |
items with FG | w\o items with FG | |||
employee | resources | episode_of_care | Код <code> для доступу до даних про <forbidden_groups.short_name> <forbidden_groups.sms_url>
If there are codes from more than 1 group:
Код <code> для доступу до даних про ВІЛ, | Код авторизації дій в системі eHealth: <code> |
diagnostic_report | ||||
care_plan | ||||
encounter | ||||
procedure | ||||
specimen | ||||
child_resources | diagnostic_report | |||
encounter | ||||
condition | ||||
observation | ||||
activity | ||||
clinical_impression | ||||
allergy_intolerance | ||||
immunization | ||||
device | ||||
risk_assessment | ||||
procedure | ||||
service_request | episode_of_care | |||
diagnostic_report | ||||
forbidden_group | forbidden_group | -(only with FG) | ||
diagnoses_group | diagnoses_group | ICD10: Код <code>: доступ на групу діагнозів {diagnoses_group_code} http://bit.ly/nszu1677b ICPC2: Код <code>: доступ на групу діагнозів {diagnoses_group_code} http://bit.ly/nszu1677e | ||
services_group |
| Код ****: доступ на групу сервісів {service_group_code} http://bit.ly/nszu1677e | ||
patient_id | patient_id | Код авторизації дій в системі eHealth: <code> | ||
resource_types | device | Код <code>: доступ до інформації про медичні вироби пацієнта | ||
device_association | ||||
detected_issue | ||||
granted_to | block | granted_resources | Sms | |
items with FG | w\o items with FG | |||
legal_entity | service_request | episode_of_care | -(only w/o FG) | Код <code>: згода на обробку персональних даних https://bit.ly/nszu1677i) |
Response structure examples
See on API-specification
| Expand | ||
|---|---|---|
| ||
|
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
HTTP status codes
Response code | HTTP Status code | Message | Internal name | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | Базові | ||||||||||
| 2 | 401 | Invalid access token | |||||||||
| 3 | 401 | Unauthorized |
| Помилка підтвердження | 4 | 403 | Access denied | ||||
| 54 | 403 | Your scope does not allow to access this resource. Missing allowances: approval:create | |||||||||
| 65 | 404 | Approval for one patient can not be created in another patient’s context | |||||||||
| 7 | 10006 | 404 | Composition not found | COMPOSITION_NOT_FOUND_404 | Не знайдено медичний висновок | 8 | 404 | not found | |||
| 97 | 409 | Person does not have active authentication method | |||||||||
| 108 | 422 | Authentication method with type THIRD_PERSON must be submitted for this person | |||||||||
| 119 | 422 | Authentication method doesn't exist, is inactive or does not belong to this person | |||||||||
| 1210 | 422 | $.access_level. value is not allowed in enum | |||||||||
| 1311 | 422 | Approval for care plan can not contain other entities | |||||||||
| 1412 | 422 | Сannot be confirmed by a method with type= NA. Use a different method. | |||||||||
| 1513 | 422 | Child resource context id is not equal to granted resource id | |||||||||
| 1614 | 422 | Care plan with such id is not found | |||||||||
| 1715 | 422 | Composition in \"entered_in_error\" status can not be referenced | |||||||||
| 1816 | 422 | Diagnostic report in \"entered_in_error\" status can not be referenced or Diagnostic report with such id is not found | |||||||||
| 1917 | 422 | Episode is canceled | |||||||||
| 2018 | 422 | Employee <employee_id> doesn't belong to your legal entity | |||||||||
| 2119 | 422 | Invalid employee type | |||||||||
| 2220 | 422 | Legal entity should be active | |||||||||
| 2321 | 422 | Procedure in \"entered_in_error\" status can not be referenced | |||||||||
| 2422 | 422 | $.resource. value is not allowed in enum | |||||||||
| 2523 | 422 | $.resource_types device and device_association are required | |||||||||
| 2624 | 422 | $.resources.expected a maximum of 1 items but got 2 | |||||||||
| 2725 | 422 | Resource types [\"$.granted_resources[].code\"] not allowed to use write access_level | |||||||||
| 2826 | 422 | Role ASSISTANT is not allowed to use write access_level for approval | |||||||||
| 2927 | 422 | such authentication method doesn't exist | |||||||||
| 3028 | 422 | such authentication method does not belong to this person | |||||||||
| 3129 |
| 422 | Should be active | ||||||||
| 3230 | 422 | schema does not allow additional properties | |||||||||
| 3331 | 422 | Specimen in \"entered_in_error\" status can not be referenced | |||||||||
| 3432 | 422 | User is not allowed to write care plan from another legal_entity | |||||||||
| 3533 | 422 | User is not allowed to create approval for the employee | |||||||||
| 3634 | Специфічні | ||||||||||
| 37 |
| 422 | Only for active MPI record can be created medication request! | 35 |
| ||||||
Post-processing processes
Description of actions performed on data after processing
Technical modules where the method is used
List of pages describing technical N/A
Technical modules where the method is used
Название | ID ТМ | Статус |
|---|---|---|
TM0112 | ||
...