Purpose

1. 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 and procedure OR patient.

2. Approvals are processed in the async way

3. Only authenticated and authorized employees with appropriate scope can create approval.

Specification

...

Link

...

https://medicaleventsmisapi.docs.apiary.io/#reference/approvals/create-approval/create-approval

...

Resource

...

/api/patients/{{patient_id}}/approvals

...

Scope

...

approval:create

...

Components

...

Approvals

...

Microservices

...

API paragraph not found

...

Protocol type

...

REST

...

Request type

...

POST

...

Sync/Async

...

Async

...

Public/Private/Internal

...

Public

Input parameters

...

Input parameter

...

Values

...

Type

...

Description

...

Example

...

patient_id

...

String

...

mpi_id. Required

...

aff00bf6-68bf-4b49-b66d-f031d48922b3

Request structure

See on Apiary

Example:

...

...

Purpose

1. 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 and procedure OR patient.

2. Approvals are processed in the async way

3. Only authenticated and authorized employees with appropriate scope can create approval.

4. Approvals with “write” access give “read” access by default. Employee with verified not expired approval with “write” access will be able to read data of specified in approval medical_event (if is possible according to ABAC-rules)

Specification

Input parameters

Request structure

See on Apiary

Example:

{
  "resources": [
    {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "episode_of_care"
            }
          ],
          "text": ""
        },
        "value": "97d57238-ffbe-4335-92ea-28d4de117ea2"
      }
    }
  ],
  "granted_to": {
    "identifier": {
      "type": {
 
        "coding": [
            {
 
            "system": "eHealth/resources",

             "code": "episode_of_care"
 employee"
          }

         ],
  
       "text": ""         },
        "value": "97d572389183a36b-ffbe4d45-43354244-92ea9339-28d4de117ea263d81cd08d9c"
    }
  },
  "access_level": "read",
 } "authorize_with":  ],
  "granted_to": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "employee"
          }
        ]
      },
      "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
    }
  },
  "access_level": "read",
  "authorize_with": "cc949559-5dfe-420f-ac05-065e443b2cc6"
}

Authorize

1. Verify the validity of access token

   1. in case of error - return 401 (“Invalid access token”) in case of validation fails

2. Verify that token is not expired

   1. in case of error - return 401 (“Invalid access token”)

3. Check user scopes in order to perform this action (scope = 'approval:create ')

   1. return 403 (“Your scope does not allow to access this resource. Missing allowances: approval:create ”) in case of invalid scope(s)

Headers

Наприклад:

Content-Type:application/json

Authorization:Bearer d368a4b0-4a0e-457a-b267-32359fa6288f

Request data validation

Validate user

1. Granted_to.employee_id should be active

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

2. 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“

Validate resources or block of resources

1. Approvals are processed in the async way

Validate resources

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

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

...

"cc949559-5dfe-420f-ac05-065e443b2cc6"
}

Authorize

1. Verify the validity of access token

   1. in case of error - return 401 (“Invalid access token”) in case of validation fails

2. Verify that token is not expired

   1. in case of error - return 401 (“Invalid access token”)

3. Check user scopes in order to perform this action (scope = 'approval:create ')

   1. return 403 (“Your scope does not allow to access this resource. Missing allowances: approval:create ”) in case of invalid scope(s)

Headers

Наприклад:

Content-Type:application/json

Authorization:Bearer d368a4b0-4a0e-457a-b267-32359fa6288f

Request data validation

Validate user

1. Granted_to.employee_id should be active

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

2. 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 resources or block of resources

1. Approvals are processed in the async way

Validate resources

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 (

         "$.resource. value

         1. 'User is not allowed

         in enum"

         1. to write care plan from another legal_entity')

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

   1. Check diagnostic_report block Check encounter in the request exists and is in final status in exists 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 error return - 422 (not found)

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

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

   1. Check care_plan in the request exists in DB

      Check is status of episode from encounter = 'active'

      1. in case of error return - 422 (Care plan with such id "Encounter refers to episode that is not found)

      Check there no other objects in request

      1. active")

   2. Validate episode related to the encounter:

      1. exists

         1. in case of error - return

         -

         1. 422 (

         Approval for care plan can not contain other entities)
      Check if resource from granted_to = 'employee':

      1. 1. 'Encounter refers to episode that does not exist')

      2. is “active” or “closed”

         1. in case of error - return

         -

         1. 422 (

         "$.resource. value is not allowed in enum")

      if access_level = 'write':

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

         1. 'Encounter refers to episode that is not active or closed')

      2. it’s managing organization matches with author’s legal entity (client_id)

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

Add label

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

   1. Check encounter in Check procedure in the request exists in DB

      1. in case of error return - 422 (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. Check is status of episode from encounter = 'active'

      1. in case of error return - 422 ("Encounter refers to episode that is not active")

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

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

      1. in case of error return - 422 (not foundInvalid specimen status)

   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):

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

...

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 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 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: 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 approval to DB

         3. save authentication_method_current.type and number to DB

         4. return authentication_method_current.type = OTP

      2. If it is offline

         1. save approval to DB

         2. save authentication_method_current.type and number to DB

         3. 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. save approval to DB

      2. set approval status = active

      3. set approval urgent = null 

Validate access_level

1. Validate that access

...

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

   correspond to granted_resources

   1. == ‘read’:

      1. In case error return 422 ("

      Resource types [\"$.granted_resources[].code\"]

      1. Role ASSISTANT is not allowed to use write access_level for approval")

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.

Processing

Cancel existing approvals

Search if there exists active and not expired approvals with current patient_id, for the same granted_resources, granted_to and access_level as in request.

• If found - set their status to terminated. Also, set updated_at and updated_by to current user.

Additional logic

...

All the approvals in status "new" should be deleted 12 hours after creation - env. configuration parameter

...

All approvals with service_group has its own expires_at config parameter - env. configuration parameter

...

All approvals with diagnoses_group has its own expires_at config parameter - env. configuration parameter

...

All approvals with forbidden_group has its own expires_at config parameter - env. configuration parameter

...

All approvals with care_plan has its own expires_at config parameter - env. configuration parameter

...

All approvals with patient 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:

1. set child resource to block reason

2. set service_request to block reason

If resource from granted_to = employee:
Check if for granted_resource and\or for reason there are forbidden groups:

...

if there are items from forbidden group

1. check type of authentication_method for patient

   1. If type = 'OTP' send SMS (Код <code> для доступу до даних про ВІЛ/РПП https://bit.ly/nszu1677f )

if there NO forbidden group items and diagnoses_group block is presented in request

if diagnoses_group type is ICD10:

check type of authentication_method for patient

...

is returned from mpi as person's default method.

Processing

Service logic

1. Set is_verified = false

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

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. Check type of authentication_method for patient:

   1. If type = 'OTP' send SMS type of granted_to & type of entity in granted_resources:

...

if diagnoses_group type is ICPC2:

check type of authentication_method for patient

...

...

check type of authentication_method for patient

...

if there NO forbidden group items and service_group block is presented in request

...

else if there NO forbidden group items

check type of authentication_method for patient

...

...

...

...

...

check type of authentication_method for patient

...

...

Response structure

See on Apiary

...