Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

/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-001007-001011-001-00010478

Microservices (namespace)

MPI

Component

Auth

Component ID

COM-001007-001011

Link на API-специфікацію

https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/manage-client-configuration/get-client-details

Resource

{{host}}//api.ehealth.gov.ua/api/patients/id/encounter_package

Scope

Protocol type

REST

Request type

Sync/Async

Public/Private

Purpose

  1. This WS is designed to create approval on

    1. entity, which aggregate other entities (episode_of_care, diagnostic_report, care_plan),

    2. OR forbidden group

    3. OR diagnoses group,

    4. OR on service_request including it’s permitted_resources

    5. OR on cancel for encounter, specimen and procedure.

  2. Approvals are processed in the async way

  3. 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

1

composition_id

 M

String ($uuid) (path)

Composition object ID

 89678f60-4cdc-4fe3-ae83-e8b3ebd35c59

2

 

 

 

 

 

Request structure

See on API-specification (посилання на сторінку з API-специфікацією)

Description of the REST API request structure, example

Expand
titleExample
Code Block

Headers

Key

Value

Mandatory

Description

Example

1

Content-Type

application/json

M

Тип контенту

Content-Type:application/json

2

Authorization

Bearer c2778f3064753ea70de870a53795f5c9

M

Перевірка користувача

Authorization:Bearer c2778f3064753ea70de870a53795f5c9

3

 

 

 

 

 

Request data validation

Validation of related entities

Validate user

  1. Granted_to.employee_id should be active

    1. in case of error - return 422 “Should be active“

  2. If resource from granted_to != 'legal_entity':

    1. Check if employee from the same legal entity as user:

      1. client_id from token should be linked with employee_id from granted_to object.

        1. in case of error - return 422 “Employee <employee_id> doesn't belong to your legal entity“

  3. Check employee_type is from list of employee types configuration CREATE_APPROVAL_ALLOWED_EMPLOYEE_TYPES

    1. in case of error - return 422 “Invalid employee type“

Validate person authentication_method

  1. If resource = care_plan & care_plans.terms_of_service = ‘INPATIENT'&granted_to.employees.legal_entity_id = care_plans.managing_organization:

    1. skip validation of person authentication_method

    2. set approvals.urgent = null

  2. In other cases:

    1. Check patient_id:

      1. if belongs to person, then GET auth_method from MPI using {patient_id}

        1. If it's OTP:

          1. send SMS to the auth_phone via otp_verification service POST /verifications

          2. save authentication_method_current.type and number to Mongo DB

          3. return authentication_method_current.type = OTP

        2. If it is offline

          1. save authentication_method_current.type to Mongo DB

          2. return  authentication_method_current.type = offline

        3.  if it is null:

          1. return error 409 (Person does not have active authentication method)

      2. if belongs to preperson:

        1. set approval urgent = null 

Validation of the request

Validate resources or block of resources

  1. 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

...

  1. if episode_of_care is presented in request as the code of resource

    1. Check episode_of_care in the request exists and is in active or closed status in DB

      1. in case of error return - 422 (Episode is canceled)

    2. Check if resource from granted_to = 'employee':

      1. in case of error return - 422 ("$.resource. value is not allowed in enum")

  2. if diagnostic_report is presented in request as the code of resource

    1. Check diagnostic_report block in the request exists and is in final status in DB

      1. 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)

    2. Check if resource from granted_to = 'employee':

      1. in case of error return - 422 ("$.resource. value is not allowed in enum")

  3. if care_plan is presented in request as the code of resource

    1. Check care_plan in the request exists in DB

      1. in case of error return - 422 (Care plan with such id is not found)

    2. Check there no other objects in request

      1. in case of error return - 422 (Approval for care plan can not contain other entities)

    3. Check if resource from granted_to = 'employee':

      1. in case of error return - 422 ("$.resource. value is not allowed in enum")

    4. If access_level = 'write':

      1. Check if care_plans.managing_organization = granted_to.employees.legal_entity_id:

        1. in case of error return - 422 ('User is not allowed to write care plan from another legal_entity')

  4. if encounter  is presented in request as the code of resource

    1. Check encounter in the request exists in DB and is not in “entered_in_error” status in DB

      1. (Encounter in \"entered_in_error\" status can not be referenced or Encounter with such id is not found)

    2. Check if resource from granted_to = 'employee':

      1. in case of error return - 422 ("$.resource. value is not allowed in enum")

  5. if procedure is presented in request as the code of resource

    1. Check procedure in the request exists in DB and is not in “entered_in_error” status in DB

      1. in case of error return - 422 (Procedure in \"entered_in_error\" status can not be referenced)

    2. Check if resource from granted_to = 'employee':

      1. in case of error return - 422 ("$.resource. value is not allowed in enum")

  6. if specimen is presented in request as the code of resource

    1. Check specimen in the request exists in DB and is not in “entered_in_error” status in DB

      1. in case of error return - 422 (Specimen  in \"entered_in_error\" status can not be referenced)

    2. Check if resource from granted_to = 'employee':

      1. in case of error return - 422 ("$.resource. value is not allowed in enum")

  7. if composition is presented in request as the code of resource

    1. Check composition in the request exists in DB and is notin “entered_in_error” status in DB

      1. in case of error return - 422 (Composition  in \"entered_in_error\" status can not be referenced)

    2. Check if resource from granted_to = 'employee':

      1. in case of error return - 422 ("$.resource. value is not allowed in enum")

Validate service_request

  1. If service_request block is presented in request

    1. Get Service_request details (only in active status)

    2. use Response.permitted_resources as resources for approval(could be episode or diagnostic_report).

  2. If resource from granted_to = 'legal_entity':

    1. Check if status of legal_entity in (ACTIVE, SUSPENDED, REORGANIZED):

      1. in case of error return - 422 (Legal entity should be active)

Validate forbidden_group

  1. if forbidden_group block is presented in request

    1. Check forbidden group in the request exists and is_active in DB

      1. in case of error return - 404 (not found)

  2. Check if resource from granted_to = 'employee':

    1. in case of error return - 422 ("$.resource. value is not allowed in enum")

Validate diagnoses_group

  1. if diagnoses_group block is presented in request

    1. Check diagnoses_group in the request exists and is_active in DB

      1. in case of error return - 404 (not found)

  2. Check if resource from granted_to = 'employee':

    1. in case of error return - 422 ("$.resource. value is not allowed in enum")

Validate service_group

  1. if service_group block is presented in request

    1. Check services_group in the request exists and is_active in DB

      1. in case of error return - 404 (not found)

  2. Check if resource from granted_to = 'employee':

    1. 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.

  1. Check composition exists in DB, is notin “entered_in_error” status and belongs to patient

    1. in case of error return - 404 (not found)

  2. Check the resource from granted_to = 'employee':

    1. in case of error return - 422 ("$.resource. value is not allowed in enum")

Validate patient

  1. if patient block is presented in request

    1. Get patient_id from URL:

      1. Check person_id from the request equal to the patient_id from URL

        1. in case of error return - 404 (“Approval for one patient can not be created in another patient’s context”)

      2. exists and is_active in DB

        1. in case of error return - 404 (Person is not found)

  2. Check if resource from granted_to = 'employee':

    1. in case of error return - 422 ("$.resource. value is not allowed in enum")

Validate resource_types

  1. Check if resource from granted_to = 'employee':

    1. in case of error return - 422 ("$.resource. value is not allowed in enum")

  2. Check that requested resource_types are any of the following [device, device_association, detected_issue]

    1. in case of error return - 422 ("$.resource_types value is not allowed in enum")

  3. Check that device and device_association requested in resource_types as they are both required

    1. in 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

  1. if child_resource is not empty:

    1. validate that access_level == read

      1. in case of error return - 422 ("$.access_level. value is not allowed in enum")

    2. check that $.child_resource.identifier.value context is equal to $.resource.identifier.value

      1. in case of error return - 422 (Child resource context id is not equal to granted resource id)

    3. validate that service_requests / forbidden_groups / diagnoses_group / patients are not filled

      1. in case of error return - 422 (schema does not allow additional properties)

    4. validate that resources max items = 1

      1. in case of error return - 422 ($.resources.expected a maximum of 1 items but got 2)

  2. Check if resource from granted_to = 'employee':

    1. in case of error return - 422 ("$.resource. value is not allowed in enum")

Validate access_level

  1. Validate that access_level correspond to granted_resources:

    1. In case error return 422 ("Resource types [\"$.granted_resources[].code\"] not allowed to use write access_level")

  2. If employee_type of granted_to.identifier.value employee == ASSISTANT:

    1. Check that access_level == ‘read’:

      1. 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

...

If approval doesn't have this field, then choose that method which is returned from mpi as person's default method.

Service logic

  1. Set is_verified value to:

    1. false if patient is person.

    2. true if patient is preperson.

  2. All the approvals where is_verified = false should be deleted 12 hours after creation - env. configuration parameter (APPROVAL_TTL_HOURS)

  3. All approvals depends on value of granted_resources has its own expires_at config parameter - env. configuration parameter

  4. Approvals with child_resources will be created ON entity which is context of this child_resources

  5. For approvals on child_resource with resource and on service_request:

    1. set child resource to block reason

    2. set service_request to block reason

  6. If block resource_types passed in request - it must be saved to db.approvals.granted_resource_types. db.approvals.granted_resources must be empty

    1. in all other scenarios db.approvals.granted_resource_types must be empty

  7. Specific approvals can request and provide additional permissions from patient to employee to get access to some sensitive information in requested resource

    1. If approval is requested on Composition (block $.composition is presented in request)

      1. 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 groups

      2. If if does - put forbidden group identifier to approval

        1. append approval.forbidden_groups with the Reference to forbidden group(s)

      3. If some resources matches with the same forbidden group that was already added - do not duplicate it

      4. Determine SMS template based on the list of matched forbidden groups (see table below)

    2. If approval is requested on child_resource (block $.composition is presented in request)

      1. 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

      2. If if does - put forbidden group identifier to approval

        1. append approval.forbidden_groups with the Reference to forbidden group(s)

      3. Determine SMS template based on the list of matched forbidden groups (see table below)

  8. If block composition passed in request - put $.composition reference to db.approvals.granted_resources

  9. Check type of authentication_method for patient:

    1. 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

Expand
titleExample
Code Block

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

5

403

Your scope does not allow to access this resource. Missing allowances: approval:create

6

404

Approval for one patient can not be created in another patient’s context

7

1000

404

Composition not found

COMPOSITION_NOT_FOUND_404

Не знайдено медичний висновок

8

404

not found

9

409

Person does not have active authentication method

10

422

Authentication method with type THIRD_PERSON must be submitted for this person

11

422

Authentication method doesn't exist, is inactive or does not belong to this person

12

422

$.access_level. value is not allowed in enum

13

422

Approval for care plan can not contain other entities

14

422

Сannot be confirmed by a method with type= NA. Use a different method.

15

422

Child resource context id is not equal to granted resource id

16

422

Care plan with such id is not found

17

422

Composition  in \"entered_in_error\" status can not be referenced

18

422

Diagnostic report in \"entered_in_error\" status can not be referenced or Diagnostic report with such id is not found

19

422

Episode is canceled

20

422

Employee <employee_id> doesn't belong to your legal entity

21

422

Invalid employee type

22

422

Legal entity should be active

23

422

Procedure in \"entered_in_error\" status can not be referenced

24

422

$.resource. value is not allowed in enum

25

422

$.resource_types device and device_association are required

26

422

$.resources.expected a maximum of 1 items but got 2

27

422

Resource types [\"$.granted_resources[].code\"] not allowed to use write access_level

28

422

Role ASSISTANT is not allowed to use write access_level for approval

29

422

such authentication method doesn't exist

30

422

such authentication method does not belong to this person

31

 

422

Should be active

32

422

schema does not allow additional properties

33

422

Specimen  in \"entered_in_error\" status can not be referenced

34

422

User is not allowed to write care plan from another legal_entity

35

422

User is not allowed to create approval for the employee

36

Специфічні

37

 

422

Only for active MPI record can be created medication request!

 

 

Post-processing processes

Description of actions performed on data after processing

Technical modules where the method is used

List of pages describing technical modules where the method is used