/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)

• Properties of a REST API method document

• Purpose

• Logic

• Configuration parameters

• Dictionaries

• Input parameters

• Request structure

• Headers

• Request data validation

• Processing

• Response structure examples

• HTTP status codes

• Post-processing processes

• Technical modules where the method is used

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

...

/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)

• Properties of a REST API method document

• Purpose

• Logic

• Configuration parameters

• Dictionaries

• Input parameters

• Request structure

• Headers

• Request data validation

• Processing

• Response structure examples

• HTTP status codes

• Post-processing processes

• Technical modules where the method is used

Properties of a REST API method document

...

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:

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

...

Input parameter

...

Mandatory

...

Type

...

Description

...

Example

...

patient_id

...

...

String

...

mpi_id. Required

...

aff00bf6-68bf-4b49-b66d-f031d48922b3

...

...

...

...

...

Request structure

See on API-specification

...

...

...

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

Request structure

See on API-specification

Headers

Headers

Request data validation

...

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)

...

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

...

• 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")

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

...

Response structure examples

See on API-specification

{
  "data": {
    "id": "d5a5d991-0bf7-476f-b3cf-bec73f044b2e",
    "granted_resources": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "episode_of_care"
              }
            ]
          },
          "value": "d5a5d991-0bf7-476f-b3cf-bec73f044b2e"
        },
        "display_value": "null"
      }
    ],
    "granted_to": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "employee"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "expires_at": 1498749591,
    "reason": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "service_request"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "status": "new",
    "access_level": "read",
    "authentication_method_current": {
      "type": "OTP",
      "number": "+38093*****85"
    }
  },
  "meta": {
    "code": 201,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  }
}

...

...

...

Response structure examples

See on API-specification

HTTP status codes

...