Properties of a REST API method document

Properties of a REST API method document

Purpose

This WS is designed to qualify Medication request (post) - check the ability to use Medication request within the Medication program and receive program participants

Logic

Процеси роботи з погашенням електронних рецептів

Технічний опис бізнес-процесу погашення рецепту в ЦБД ЕСОЗ

Preconditions

MR should be found by number

Configuration parameters

Description of the configuration parameters that are used when processing a request in the system

Dictionaries

• MEDICATION_FORM

• COUNTRY

• MEDICATION_UNIT

Input parameters

Description of input parameters

Request structure

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

Description of the REST API request structure, example

{
  "division_id": "2848a935-5fd7-48ba-b235-a9b5d475c647",
  "programs": [
    {
      "id": "59781de0-2e64-4359-b716-bcc05a32c10f"
    }
  ]
}

Headers

...

Key

...

Value

...

Mandatory

...

Description

...

Example

...

Content-Type

...

application/json

...

M

...

Тип контенту

...

Content-Type:application/json

...

Authorization

...

Bearer 2778f3064753ea70de870a53795f5c9

...

M

...

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

...

Authorization:Bearer 2778f3064753ea70de870a53795f5c9

...

Request data validation

Validate request

Validate request using JSON schema.

Validate FK

1. Validate id - medication_request_id exists

   1. Return  404 in case (not found medication request in DB with this ID).

2. Validate [programs.id] - medical programs id  exists

   • Return 422 in case validation fails (422 EView - not found medical program in DB with this ID)

Get Medication Request 

Invoke Get Medication request by ID 

Validation status

1. For info - status charts: Medication_request.

2. Check Medication Request `status` = ACTIVE

   1. if invalid - return 409 error (message: "Invalid status Medication request for qualify action!")'.

Validate related Care plan

If medication_request.based_on is present and not null:

Verify Care plan:

...

It should be in active status

1. in case of error - return 409 (message: "Invalid care plan status").

...

  ]
}

Request data validation

Authorize

1. Verify the validity of access token.

2. Check user scope (scope = 'medication_request:details') in order to perform this action

   1. In case error - generate 401 response.

Validate request

Validate request using JSON schema.

Validate FK

1. Validate id - medication_request_id exists

   1. Return  404 in case (not found medication request in DB with this ID).

2. Validate [programs.id] - medical programs id  exists

   • Return 422 in case validation fails (422 EView - not found medical program in DB with this ID)

Get Medication Request 

Invoke Get Medication request by ID 

Validation status

1. For info - status charts: Medication_request.

2. Check Medication Request `status` = ACTIVE

   1. if invalid - return 409 error (message: "Invalid status Medication request for qualify action!")'.

Validate related Care plan

If medication_request.based_on is present and not null:

1. Verify Care plan:

   1. It should be in active status

      1. in case of error - return 409 (message: "Invalid care plan status").

   2. Care plan's period end (if exist) should be greater than current date or equal

      1. in case of error - return 409 (message: “Care plan expired“).

2. Verify care plan Activity:

   1. It has scheduled, in_progress status

      1. in case of error - return 409 (message: "Invalid activity status").

   2. Validate quantity is not exceeded

      1. Select all MD (medication dispenses) in status PROCESSED related to the Medication requests which based_on one activity 

         1. Sum medication_qty in the filtered Medication dispenses as dispensed_qty

         2. medication_qty from current MR as current_qty

         3. Calculate remaining_qty = activity.quantity - (dispensed_qty+current_qty)

      2. Check remaining_qty is greater then zero

         1. error return 409 "The total amount of the dispensed medication quantity exceeds quantity in care plan activity"

Validate division

1. Validate division is active

   1. in case of error - return 409 (

      message: “Care plan expired“).

   Verify care plan Activity:

   1. It has scheduled, in_progress status"Division is not active")

2. Validate division belongs to user's legal entity

   Validate division is active

   1. in case of error - return 409 (

      message: "Invalid activity status").

   2. Validate quantity is not exceeded

      1. Select all MD (medication dispenses) in status PROCESSED related to the Medication requests which based_on one activity 

         1. Sum medication_qty in the filtered Medication dispenses as dispensed_qty

         2. medication_qty from current MR as current_qty

         3. Calculate remaining_qty = activity.quantity - (dispensed_qty+current_qty)

      2. Check remaining_qty is greater then zero

         1. error return 409 "The total amount of the dispensed medication quantity exceeds quantity in care plan activity"

Validate division

1. 1. "Division does not belong to user's legal entity")

2. If chart parameter DISPENSE_DIVISION_DLS_VERIFY is on, then validate division is DLS verified (dls_verified=true)

   1. in case of error - return 409 "Division is not verified in DLS"

3. Check division participates in submitted programs. Validate Provision for each Medical Program:

   If chart parameter DISPENSE_DIVISION_DLS_VERIFY is on, then validate division is DLS verified (dls_verified=true)

   1. If the medical program has no setting skip_contract_provision_verify or it is equal to false/null:

      1. if medical program in the request has funding_source one of NHS, LOCAL

         1. In case of error - return status=INVALID for a program, rejection_reason="Program was configured incorrectly. Either incorrect source of funding or option skip_contract_provision_verify"

      2. provision exist and active for the division:

         1. in case of error - return

      409 (

      1. 1. status=INVALID for a program, rejection_reason= "Division

      is not active")

4. Validate division belongs to user's legal entity

   1. in case of error - return 409 ("Division does not belong to user's legal entity")

5. 1. 1. 1. does not provide the medical program"

      2. if medical program in the request has funding_source = NHS:

         1. provision relates to the actual reimbursement contract: contract.start_date <= current_date <= contract.end_date, is_active = true, status = VERIFIED, contracts.type==reimbursement, contracts.contractor_legal_entity_id=token.client_id, contracts.medical_program_id==$.medical_program_id

            1. in case of error - return

      409 "Division is not verified in DLS"

   Check division participates in submitted programs. Validate Provision for each Medical Program:

   1. If the medical program has no setting skip_contract_provision_verify or it is equal to false/null:

      1. if medical program in the request has funding_source one of NHS, LOCAL

         1. In

            1. status=INVALID for a program, rejection_reason="Medical program provision is not related to any actual contract for the current date"

         2. contract is_suspended = false

            1. in case of error - return status=INVALID for a program, rejection_reason="

            Program was configured incorrectly. Either incorrect source of funding or option skip_contract_provision_verify"

         provision exist and active for the division:

         1. 1. Contract with number <contract_number> is suspended"

      2. if medical program in the request has funding_source = LOCAL, then check medical_program_provision.msp_legal_entity_id = medication_request.legal_entity_id

         1. in case of error - return status=INVALID for a program, rejection_reason= "Division does not provide the medical program"

         if medical program in the request has funding_source = NHS:

         1. provision relates to the actual reimbursement contract: contract.start_date <= current_date <= contract.end_date, is_active = true, status = VERIFIED, contracts.type==reimbursement, contracts.contractor_legal_entity_id=token.client_id, contracts.medical_program_id==program, rejection_reson = "Medical program can not be provided for the legal entity specified in the medication request"

   2. else if skip_contract_provision_verify = true, then skip provision verification for the medical program

6. Get license_types_allowed parameter from settings of medical program from request $.medical_program_id

   1. in case of error - return status=INVALID for a program, rejection_reason="Medical program provision is not related to any actual contract for the current date"

7. contract is_suspended = false

   1. in case of error - return status=INVALID for a program, rejection_reason="Contract with number <contract_number> is suspended"

if medical program in the request has funding_source = LOCAL, then check medical_program_provision.msp_legal_entity_id = medication_request.legal_entity_id

:

1. if it is exists and not empty, get list of all license types from parameter.
   Check that division has active healthcare services with following parameters:

8. Get info from Medication request  by id in payload, set temp variable object `_MR`.

9. Validate the compatibility of innm with the medication program list 

   1. if data is not

      1. legal_entity_id = client_id from access token

      2. division_id = division_id from request

      3. status = 'ACTIVE'

      4. licensed_healthcare_service.status = 'ACTIVE'

      5. healthcare_service.license_id is not null and licenses.type = value from license_types_allowed parameter

         1. in case of error - return  return status=INVALID for a program, rejection_reson = "Medical program can not be provided for the legal entity specified in the medication request"

   2. else if skip_contract_provision_verify = true, then skip provision verification for the medical program

10. Get license_types_allowed parameter from settings of medical program from request $.medical_program_id:

    1. if it is exists and not empty, get list of all license types from parameter.
       Check that division has active healthcare services with following parameters:

       1. legal_entity_id = client_id from access token

       2. division_id = division_id from request

       3. status = 'ACTIVE'

       4. licensed_healthcare_service.status = 'ACTIVE'

       5. healthcare_service.license_id is not null and licenses.type = value from license_types_allowed parameter

          1. in case of error - return status=INVALID for a program, rejection_reason = 'Division does not have active licenses to provide the medical program'

Logic for qualify (analyze compliance with programs)

• Each Medical program may have its unique conditions for the medication dispense. It can be based on analysis of personal info, medications list, terms, locations and combinations of them.

  Also, it is possible to have the medication dispense without any Medical program.

  However for any Medical program we need a separate block of branching logic.

  Check compatibility only for programs which are available in payload (array)

  If program status is invalid, the reason must be saved and returned in response.

Check compliance for programs

1. Validate 2 checks (below in the text) for programs

   1. if passed - save status this program for response = VALID.

Check INNM_dosage compliance for the programs

Validation purpose:  There is a list of medications (which links to innm_dosage) which can be used for the program. It must be check whether there is at least one available medication for the innm_dosage for the particular program.

1. 1. 1. 1. reason = 'Division does not have active licenses to provide the medical program'

Logic for qualify (analyze compliance with programs)

• Each Medical program may have its unique conditions for the medication dispense. It can be based on analysis of personal info, medications list, terms, locations and combinations of them.

  Also, it is possible to have the medication dispense without any Medical program.

  However for any Medical program we need a separate block of branching logic.

  Check compatibility only for programs which are available in payload (array)

  If program status is invalid, the reason must be saved and returned in response.

Check compliance for programs

1. Validate 2 checks (below in the text) for programs

   1. if passed - save status this program for response = VALID.

Check INNM_dosage compliance for the programs

Validation purpose:  There is a list of medications (which links to innm_dosage) which can be used for the program. It must be check whether there is at least one available medication for the innm_dosage for the particular program.

Check that there is at least one medication (brand or innm_dosage) associated with medical program that can be dispensed to the patient

1. Get info from Medication request  by id in payload, set temp variable object `_MR`

2. Validate the compatibility of innm with the medication program list 

   1. Search for active innm_dosages that associated with medical program

      1. medications.is_active = true

      2. medications.type = INNM_DOSAGE

      3. program_medications.is_active = true

   2. Search for active brands that have innm_dosage as primary ingredient and are associated with medical program

      1. medications.is_active = true

      2. medications.type = BRAND

      3. ingredients.is_primary = true

      4. program_medications.is_active = true

   3. if nothing found:

      1. add to response: status = INVALID

      2. add to response: rejection_reason = "Innm not on the list of approved innms for program '#{program.name}"

IF EXISTS
    (SELECT * FROM program_medications MP
        INNER JOIN medications M
            ON M.id = MP.medication_id
                AND M.type =  BRANDS
        INNER JOIN ingredients I
            ON I.parend_id = M.id
                AND I.is_primary = TRUE
                AND I.medication_child_id = _MR.medication_id
    WHERE MP.medical_program_id == $.id
        AND MP.is_active == TRUE
        AND M.is_active == TRUE)

Check absence a same medication for the programs

Validation purpose: It could be done several dispenses for one medication request per one innm for one patient until sum(medication_dispenses.medication_qty) < medication_request.medication_qty

Example validation: without crossing time

1. For info - status charts: Medication Request Status Chart & Medication Dispense Status Chart

2. Get `check_innm_id`

   Code Block
   SELECT I.innm_child_id FROM ingredients I WHERE I.parent_id = _MR.medication_id AND I.is_primary = TRUE

    

3. Get Medication requests with their linked completed Medication dispense by person_id & innm_id

    

   Code Block

   SELECT * FROM medication_requests MR INNER JOIN medication_dispense MD ON MD.medication_request_id = MR.id AND MD.status IN (PROCESSED) INNER JOIN ingredients I ON I.parent_id = MR.medication_id -- type = INNM_DOSAGE AND I.innm_child_id = `check_innm_id` AND I.is_primary = TRUE WHERE MR.person_id == _MR.person_id AND MR.status IN (ACTIVE, COMPLETED) AND NOT($.started_at> MR.ended_at OR $.ended_at < MR.started_at)

    

4. Validate medication request_id

   1. for medication_dispense.medication_request_id !== $.id

      1. Validate exist (IF EXIST ()  - that is any crossing  calculating term (started_at + ended_at) for payload with terms selecting Medication requests with linked Medication dispense (started_at + ended_at))

      2. if found 

         1. get $.medical_programs.medical_program_setting by medical_program_id from request

            1. validate skip_mnn_in_treatment_period variable

               1. in case skip_mnn_in_treatment_period == FALSE (or absent) 

                  1. validate request according to logic:

                     1. add to response: status = INVALID

                        add to response: rejection_reason = "For the patient at the same term there can be only 1 dispensed medication request per one and the same innm!"

               2. in case skip_mnn_in_treatment_period == TRUE

                  1. skip validating frequency of receiving drugs

   2. for medication_dispense.medication_request_id = $.id

      1. Validate medication request qty: sum(medication_dispenses.medication_qty) >= medication_request.medication_qty 

      2. if found

         1. add to response: status = INVALID

            add to response: rejection_reason = "Sum of dispense's medication quantity can not be more then medication_request.medication_qty".

Parameters that are used when processing the request

Configuration parameters

Access to the method is defined by the scope medication_request:details. Permission for this scope is determined by the System administrator by configuring scopes in the context of clients and roles.

Processing

A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API

Response structure examples

Generate structure for response

• Collect response array for all programs in payload with status for each (VALID or INVALID) and rejection_reason

• For all VALID programs - Get linked medications (type = BRAND) with reimbursement info 

• Show only active program medications based on start_date and end (start_date must be earlier or equal to current date or empty, end_date must be greater or equal to current date or empty)

  • Filter participants simultaneously by container_dosage and max_request_dosage

SELECT *
FROM program_medications pm
    INNER JOIN ingredients i ON (i.parent_id = pm.medication_id
                                 AND i.medication_child_id = :medication_request_medication_id
                                 AND i.is_primary = TRUE)
    INNER JOIN medications m ON (m.id = pm.medication_id)
WHERE pm.medical_program_id = $.id
      AND pm.is_active = TRUE
      AND m.is_active = TRUE
      AND (pm.start_date <= now() OR pm.start_date IS NULL)
      AND (pm.end_date >= now() OR pm.end_date IS NULL)
 
-- added 2022-05-20:
      AND (
      ((M.container ->> 'numerator_unit' = $mr.container_dosage.code) AND
      (M.container ->> 'numerator_value' <>  $mr.container_dosage.value)) OR
           ( ($mr.dosage_container.code is NULL) AND ($mr.container_dosage.value is NULL) )
        )
      AND (M.max_request_dosage >= $.medication_qty or M.max_request_dosage is null)

Prepare & return response data structure

Fill response WS data structure

...

Also see on Apiary.

Example:

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

Description of the REST API response structure, example

{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": [
    {
      "program_id": "59781de0-2e64-4359-b716-bcc05a32c10f",
      "program_name": "Програма \"Доступні ліки\"",
      "status": "INVALID",
      "rejection_reason": "Innm not on the list of approved innms for program 'DOSTUPNI LIKI' !",
      "participants": [
        {
          "id": "0f2fbf93-3041-4c0d-a3cf-ff558c861df8",
          "medication_id": "59781de0-2e64-4359-b716-bcc05a32c10f",
          "medication_name": "Амлодипін-КВ",
          "form": "PILL",
          "manufacturer": {
            "name": "ПАТ \"Київський вітамінний завод\"",
            "country": "UA"
          },
          "reimbursement_amount": 15,
          "wholesale_price": 25.14,
          "consumer_price": 34.03,
          "reimbursement_daily_dosage": 1.4438,
          "estimated_payment_amount": 5.15,
          "container_dosage": {
            "numerator_unit": "PILL",
            "numerator_value": 1,
            "denumerator_unit": "PILL",
            "denumerator_value": 1
          },
          "package_min_qty": 20,
          "package_qty": 20,
          "start_date": "2019-01-01",
          "end_date": "2019-06-30",
          "registry_number": "REG-1111"
        }
          ]
    }
  ]
}

HTTP status codes

...

Response code

...

HTTP Status code

...

Message

...

Internal name

...

Description

...

Базові

...

200

...

Response

...

...

401

...

Invalid access token

...

...

401

...

Unauthorized

...

Помилка підтвердження

...

1000

...

404

...

Composition not found

...

COMPOSITION_NOT_FOUND_404

...

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

...

404

...

Not found medication request in DB with this ID

...

...

409

...

Care plan expired

...

409

...

Division is not active

...

409

...

Division does not belong to user's legal entity

...

409

...

Division is not verified in DLS

...

409

...

Invalid status Medication request for qualify action!

...

...

409

...

Invalid care plan status

...

409

...

Invalid activity status

...

409

...

The total amount of the dispensed medication quantity exceeds quantity in care plan activity

...

422

...

Error

...

422

...

]
    }
  ]
}

HTTP status codes

Post-processing processes

Description of actions performed on data after processingNo

Technical modules where the method is used

List of pages describing technical modules where the method is used

...