...

Properties of a REST API method document

...

• plan - The request represents an intention to ensure something occurs without providing authorization for others to act. Medication request with type plan can't be dispensed and only provide the instruction to administer the medicine. It also can't be qualified

• order - The request represents a request/demand and authorization for action. Medication request with type order can be dispensed.

Logic

Технічний опис бізнес-процесу виписування рецепту в ЕСОЗ (загальний процес для усіх рецептурних ЛЗ, в т.ч. і тих, які підлягають реімбурсації)

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

ATTRIBUTES - see on Apiary

...

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

...

Preconditions

1. Only authenticated and authorized users with appropriate scope can invoke Prequalify Medication Request Request (MRR)

2. This method simply returns the result of data validation within each submitted medical program, but not creates any entities in the system

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

4. Any Medical program can have separate block of branching logic configured at medical program settings by NHS administrator

5. Сompatibility is checked only for programs which are available in payload (array)

6. Successful invocation of the method returns decision for each program if it is valid or not to create Medication Request with submitted combination of parameters in the payload. If program status is invalid, the reason must be saved and returned in response.

Logic

Технічний опис бізнес-процесу виписування рецепту в ЕСОЗ (загальний процес для усіх рецептурних ЛЗ, в т.ч. і тих, які підлягають реімбурсації)

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

ATTRIBUTES - see on Apiary

Request structure

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

Description of the REST API request structure, example

{
  "medication_request_request": {
    "person_id": "585044f5-1272-4bca-8d41-8440eefe7d26",
    "employee_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "division_id": "881d6dee-dd3d-43f3-8983-922354c0e6ce",
    "created_at": "2017-08-17",
    "started_at": "2017-08-17",
    "ended_at": "2017-09-16",
    "medication_id": "1349a693-4db1-4a3f-9ac6-8c2f9e541982",
    "medication_qty": 10.34,
    "intent": "plan",
    "category": "community",
    "based_on": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "care_plan"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      },
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "activity"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      }
    ],
    "context": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "encounter"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "dosage_instruction": [
      {
        "sequence": 1,
        "text": "0.25mg PO every 6-12 hours as needed for menses from Jan 15-20, 2015.  Do not exceed more than 4mg per day",
        "additional_instruction": [
          {
            "coding": [
              {
                "system": "eHealth/SNOMED/additional_dosage_instructions",
                "code": "311504000"
              }
            ]
          }
        ],
        "patient_instruction": "0.25mg PO every 6-12 hours as needed for menses from Jan 15-20, 2015.  Do not exceed more than 4mg per day",
        "timing": {
          "event": [
            "2017-04-20T19:14:13Z"
          ],
          "repeat": {
            "bounds_duration": {
              "value": 10,
              "unit": "days",
              "system": "eHealth/ucum/units",
              "code": "d"
            },
            "count": 2,
            "count_max": 4,
            "duration": 4,
            "duration_max": 6,
            "duration_unit": "d",
            "frequency": 1,
            "frequency_max": 2,
            "period": 4,
            "period_max": 6,
            "period_unit": "d",
            "day_of_week": [
              "mon"
            ],
            "time_of_day": [
              "2017-04-20T19:14:13Z"
            ],
            "when": [
              "WAKE"
            ],
            "offset": 4
          },
          "code": {
            "coding": [
              {
                "system": "TIMING_ABBREVIATIONS",
                "code": "patient"
              }
            ]
          }
        },
        "as_needed_boolean": true,
        "site": {
          "coding": [
            {
              "system": "eHealth/SNOMED/anatomical_structure_administration_site_codes",
              "code": "344001"
            }
          ]
        },
        "route": {
          "coding": [
            {
              "system": "eHealth/SNOMED/route_codes",
              "code": "46713006"
            }
          ]
        },
        "method": {
          "coding": [
            {
              "system": "eHealth/SNOMED/administration_methods",
              "code": "419747000"
            }
          ]
        },
        "dose_and_rate": {
          "type": {
            "coding": [
              {
                "system": "eHealth/dose_and_rate",
                "code": "'ordered'"
              }
            ]
          },
          "dose_range": {
            "low": {
              "value": 0,
              "unit": "mg",
              "system": "eHealth/ucum/units",
              "code": "mg"
            },
            "high": {
              "value": 0,
              "unit": "mg",
              "system": "eHealth/ucum/units",
              "code": "mg"
            }
          },
          "rate_ratio": {
            "numerator": {
              "value": 0,
              "unit": "mg",
              "system": "eHealth/ucum/units",
              "code": "mg"
            },
            "denominator": {
              "value": 0,
              "unit": "mg",
              "system": "eHealth/ucum/units",
              "code": "mg"
            }
          }
        },
        "max_dose_per_period": {
          "numerator": {
            "value": 0,
            "unit": "mg",
            "system": "eHealth/ucum/units",
            "code": "mg"
          },
          "denominator": {
            "value": 0,
            "unit": "mg",
            "system": "eHealth/ucum/units",
            "code": "mg"
          }
        },
        "max_dose_per_administration": {
          "value": 0,
          "unit": "mg",
          "system": "eHealth/ucum/units",
          "code": "mg"
        },
        "max_dose_per_lifetime": {
          "value": 0,
          "unit": "mg",
          "system": "eHealth/ucum/units",
          "code": "mg"
        }
      }
    ],
    "priority": "routine",
    "prior_prescription": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "medication_request"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "container_dosage": {
      "system": "MEDICATION_UNIT",
      "code": "ML",
      "value": 4
    }
  },
  "programs": [
    {
      "id": "59781de0-2e64-4359-b716-bcc05a32c10f"
    }
  ]
}Headers

...

Request data validation

Validate container_dosage field

$.container_dosage - volume of a medication’s primary container, which is requested by a doctor or issuer of a medication request, to be dispensed to patient.

Validate $.container_dosage field by schemata

...

$.container_dosage.code and $.container_dosage.value should be both filled

1. in case of error return 422 error ("required property %{property} was not present")

...

$.container_dosage.system should be “MEDICATION_UNIT”

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

...

Authorize

1. Verify the validity of access token

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

2. Verify that token is not expired

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

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

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

Request data validation

Validate container_dosage field

$.container_dosage - volume of a medication’s primary container, which is requested by a doctor or issuer of a medication request, to be dispensed to patient.

1. Validate $.container_dosage field by schemata

   1. $.container_dosage.code and $.container_dosage.value should be both filled

      1. in case of error return 422 error ("required property %{property} was not present")

   2. $.container_dosage.system should be “MEDICATION_UNIT”

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

   Check if there is at list one record of Brand with

   1. if $.container_dosage is filled then $.container_dosage.unit should be checked with the MEDICATION_UNIT dictionary by $.container_dosage.code as a key.

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

2. Check if there is at list one record of Brand with requested primary container volume
   a. if not exist - return 404 error (message: "Not found any appropriate medication with such container parameters")

...

1. Check ended_at >= started_at

   1. in case of error - return 422 error “Ended date must be >= Started date!“

2. Validate started_at >= created_at, but not greater than (created_at + MEDICATION_REQUEST_REQUEST_EXTENDED_LIMIT_STARTED_AT_DAYS)

   1. if invalid - return 422 error  (message: "The start date should be equal to or greater than the creation date, but the difference between them should be not exceed {{MEDICATION_REQUEST_REQUEST_EXTENDED_LIMIT_STARTED_AT_DAYS}} day(s).")

3. Validate started_at >= current_date()

   1. if invalid - return 422 error  (message: "Started date must be >= current date!")

4. Check created_at >= (current date - MEDICATION_REQUEST_REQUEST_DELAY_INPUT)

   1. in case of error - return 422 “Create date must be >= Current date - MRR delay input!”

...

There is a list of medications (BRANDs, which links to Innmsmedications.type = BRAND OR medications.type = INNM_DOSAGE)  which can be used for the program. It must be check whether there is at least one available medication (with `medication_request_allowed` == TRUE)  for the Innm for the particular program 

...

2. Check if there is at list one record of Brand with requested primary container volume

a. if not exist - return 404 error (message: "Not found any appropriate medication with such container parameters")

3. Check if there is at list one record medication_qty <= max_request_dosage or (max_request_dosage is null)

a. if not exist - return 404 error (message: "Not found any appropriate medication complying with max_request_dosage limit")

4. Check compliance of medication quantity: remainder of the division (medication_qty/package_min_qty) is equal to 0

a. in case it is not equal to zero - return 422 “The amount of medications in medication request must be divisible to package minimum quantity“

5. Check max allowed quantity for the treatment period:

• Get non-null max_daily_dosage from all filtered above program medications

• Define max value among max_daily_dosage as highest_max_daily_dosage

• Get package_min_qty from all related brands, connected to found program medications

• Define min value among package_min_qty as lowest_package_min_qty

a. Validate that remainder of the division: (highest_max_daily_dosage × (ended_at - started_at+1)) / one of package_min_qty is equal to 0

i. if true - check medication_qty <= (highest_max_daily_dosage × (ended_at - started_at+1))

1.in case of error - return 422 “The amount of medications in medication request is greater than available maximum for the max_daily_dosage and treatment period limit” 

b. Validate: (medication_qty - (highest_max_daily_dosage × (ended_at - started_at+1))) < lowest_package_min_qty

i. in case of error - return 422 “The amount of medications in medication request is not complying with max_daily_dosage and treatment period limit”

2. Check absence the same medications for the programs

It can be only 1 Medication request (ACTIVE, COMPLETED)  per one innm for the one patient at defined period of time.

Example validation: without crossing time

...

EP

...

 Preconditions # 1

...

Result validate #1 

...

 Preconditions #2

...

Result validate #2 

...

 Preconditions #3

...

Result validate #2 

...

PreQualifyMedicationRequestRequest

...

No records in MedicationRequest

...

OK

...

Created record in MedicationRequest

...

Not valid

...

Medications request
dispensed (COMPLETED)

...

Not valid

...

QualifyMedicationRequestByID

...

No records in MedicationRequest

...

Not possible

...

Create record in MedicationRequest

...

OK

...

Medications request
dispensed (COMPLETED) 

...

Not valid

1. For info - status charts: Medication_request

2. Get `check_innm_id`

...

...

1. Get Medication requests with their completed Medication dispense by person_id & check_innm_id

SELECT m0.id, m2.id, m2.package_qty, m2.package_min_qty, m3.id, m3.name
FROM medications AS m0
         INNER JOIN ingredients AS i1 ON i1.medication_child_id = {$.medication_id}
         INNER JOIN medications AS m2 ON i1.parent_id = m2.id
         INNER JOIN medical_programs AS m3 ON m3.id = {$.medical_program_id}
         INNER JOIN program_medications AS p4 ON (m3.id = p4.medical_program_id) AND (p4.medication_id = m2.id)
WHERE (i1.is_primary = TRUE)
  AND (m0.id = {$.medication_id})
  AND (m0.type = 'INNM_DOSAGE')
  AND (m0.is_active = TRUE)
  AND (m2.is_active = TRUE)
  AND (m3.medication_request_allowed = TRUE)
  AND (p4.is_active = TRUE)
  AND (p4.medication_request_allowed = TRUE)

2. Check if there is at list one record of Brand with requested primary container volume in case when found medications is not medications.type = INNM_DOSAGE:

a. if not exist - return 404 error (message: "Not found any appropriate medication with such container parameters")

3. Check if there is at list one record medication_qty <= max_request_dosage or (max_request_dosage is null)

a. if not exist - return 404 error (message: "Not found any appropriate medication complying with max_request_dosage limit")

4. Check max allowed quantity for the treatment period. If there in a list of medications is at list one record with medications.type = INNM_DOSAGE do p.4.2 and skip p.4.1
   4.1. in case when found medications is medications.type = BRAND:

• Get non-null max_daily_dosage from all filtered above program medications

• Define max value among max_daily_dosage as highest_max_daily_dosage

• Get package_min_qty from all related brands, connected to found program medications

• Define min value among package_min_qty as lowest_package_min_qty

a. Validate that remainder of the division: (highest_max_daily_dosage × (ended_at - started_at+1)) / one of package_min_qty is equal to 0

i. if true - check medication_qty <= (highest_max_daily_dosage × (ended_at - started_at+1))

ii. in case of error - return 422 “The amount of medications in medication request is greater than available maximum for the max_daily_dosage and treatment period limit” 

b. Validate: (medication_qty - (highest_max_daily_dosage × (ended_at - started_at+1))) < lowest_package_min_qty

i. in case of error - return 422 “The amount of medications in medication request is not complying with max_daily_dosage and treatment period limit”.

4.2. in case when found medications is medications.type = INNM_DOSAGE:

• Get non-null max_daily_dosage from all filtered above program medications

• Define max value among max_daily_dosage as highest_max_daily_dosage

a. Validate: ((highest_max_daily_dosage × (ended_at - started_at+1)) - medication_qty) >= 0

i. in case of error - return 422 “The amount of medications in medication request is not complying with max_daily_dosage and treatment period limit”

5. Check compliance of medication quantity in case when found medications is not medications.type = INNM_DOSAGE: remainder of the division (medication_qty/package_min_qty) is equal to 0

a. in case it is not equal to zero - return 422 “The amount of medications in medication request must be divisible to package minimum quantity“

2. Check absence the same medications for the programs

It can be only 1 Medication request (ACTIVE, COMPLETED)  per one innm for the one patient at defined period of time.

Example validation: without crossing time

1. For info - status charts: Medication_request

2. Get `check_innm_id`

SELECT m0.id
FROM medications AS m0
         INNER JOIN ingredients AS i1 ON m0.id = i1.parent_id
         INNER JOIN (SELECT si2.id AS id
                     FROM medications AS sm0
                              INNER JOIN ingredients AS si1 ON si1.parent_id = sm0.id
                              INNER JOIN innms AS si2 ON si1.innm_child_id = si2.id
                     WHERE (sm0.is_active = TRUE)
                       AND (sm0.id = {$.medication_id})
                       AND (si1.is_primary = TRUE)
                       AND (si2.is_active = TRUE)) AS s2 ON i1.innm_child_id = s2.id
WHERE (m0.is_active = TRUE)

1. Get Medication requests with their completed Medication dispense by person_id & check_innm_id

SELECT m0.started_at, m0.ended_at
FROM medication_requests AS m0
WHERE (m0.medical_program_id = {$.medical_program_id})
  AND (m0.medication_id = ANY ({$.medication_id}))
  AND (m0.status = ANY (ACTIVE,COMPLETED))
  AND (m0.started_at <= {$.ended_at})
  AND (m0.patient_id = {$.patient_id} OR m0.person_id = {$.person_id})
ORDER BY m0.ended_at DESC
LIMIT 1

1. Validate exist (IF EXIST ()  - that is

...

1. if (ended_at - started_at + 1) >= MEDICATION_REQUEST_REQUEST_STANDARD_DURATION chart param then
   created_at from prequalify request should be greater then (ended at - MEDICATION_REQUEST_MAX_RENEW_DAY) of the found MR

   1. in case of error return 422 error ('It's to early to create new medication request for such innm_dosage and medical_program_id')

2. if (ended_at - started_at + 1) < MEDICATION_REQUEST_REQUEST_STANDARD_DURATION chart param then
   created_at from prequalify request should be greater then (ended at - MEDICATION_REQUEST_MIN_RENEW_DAY) of the found MR

   1. in case of error return 422 error ('It's to early to create new medication request for such innm_dosage and medical_program_id')

...

SELECT medical_program_setting->>'care_plan_required'
FROM medical_programs
WHERE id = 'medical_program_id';

b. if care_plan_required true:

...

Validate employee_id as described on Create Medication request Request. Except on Prequalify method a declaration has not checked for the employee.

6. Check Care plan and Activity

...

1. If medication request has program with MEDICATION_REQUEST_MAX_PERIOD_DAY in medical program setting:

   1. Check that medication request period (ended_at - started_at + 1) less than or equal to medical program setting MEDICATION_REQUEST_MAX_PERIOD_DAY parameter

      1. in case of error - return 200 with status = INVALID and rejection_reason = “Period length exceeds allowed value for the medical program“ 

2. If medication request has program without MEDICATION_REQUEST_MAX_PERIOD_DAY in medical program setting:

   1. Check that medication request period (ended_at - started_at + 1) less than or equal to MEDICATION_REQUEST_MAX_PERIOD_DAY parameter from charts

      1. in case of error - return 200 with status = INVALID and rejection_reason = “Period length exceeds default maximum value“

...

1. Validate "context" is an active (not entered-in-error) entity from corresponding dictionary, that belongs to the current patient

   1. Validate there is an entity in collection $.data.context.identifier.type.coding[0].code with id == $.data.context.identifier.value that belongs to the current patient

      1.  in case of error - return 200 with status = INVALID and rejection_reason = “Entity not found“

   2. encounter diagnosis is not empty in $.encounter.diagnosis

      1. in case of error return 422 ("Encounter without diagnosis can not be referenced")

   3. Validate context.identifier.type.coding[0].code = encounter

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

   4. encounter diagnosis is not empty in $.encounter.diagnosis

      1. in case of error return 422 ("Encounter without diagnosis can not be referenced")

9. Check person

It is needed to check if person has allowed verification status to get medication.

...

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

   1. If medical program has funding_source = LOCAL:

      1. Check there is exists any active medical program provision with msp_legal_entity_id equal to employee's legal entity

         1. in case of error - return 200 with status = INVALID and rejection_reason = "Medical program is not provided for legal entity specified in the medication request"

Processing

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

Response structure examples

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

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' !"
    }
  ]
}

...

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

...