ЕСОЗ - публічна документація

RC_Create Medication request Request (modified - EN)

Owned by Iryna Lishtaba (SoE eHealth)
Oct 05, 2022
8 min read

Specification

Apiary

Purpose

This WS is designed to create Request fo Medication request

There are two types of medication request:

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

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

Authorize

  1. Verify the validity of access token

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

    1. In case error - generate 401 response

Validate request (JSON schema)

Validate request using JSON schema. 

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

Validate employee

Purpose validation: Validation of an employee for the possibility of creating a medication request.

  1. Invoke employee_id from request

  2. Validate employee

    1. Validate that exists

      1. in case invalid return 422 error with msg ("Employee not found")

    2. Validate that $.employees.status == APPROVED

      1. in case invalid return 409 error with msg ("Employee is not active")

    3. Validate that $.employees.legal_entity_id == client_id from token

      1. in case invalid return 422 error with msg ("Employee does not belong to legal entity from token")

    4. Validate that $.employees.employee_type == <employee_type>

      1. in case medical_program_id present in request validate medical_program_settings.skip_employee_validation == false (or absent)

        1. validate <employee_type>

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

            1. validate that employee_type present in employee_types_for_create_medication_request variable

              1. in case invalid return 422 error with msg ("Employee type can't create medication request with medical program from request") 

              2. in case employee_type = DOCTOR

                1. if variable skip_medication_request_employee_declaration_verify = false or null/absent

                  1. then: get $.declarations by employee_id, person_id, status=ACTIVE

                    1. if not found - return 422 error  "Only doctors with an active declaration with the patient can create medication request!"

                  2. else skip declaration verification on employee level (if true)

                2. if variable skip_medication_request_legal_entity_declaration_verify = false or null/absent

                  1. then: get $.declarations by employee's legal_entity_id, person_id, status=ACTIVE

                    1. if not found - return 422 error "Only legal entity with an active declaration with the patient can create medication request!"

                  2. else skip declaration verification on legal entity level (if true)

                3. else if both are true - skip declaration verification at all

              3. in case employee_type = SPECIALIST

                1. get $.employees.speciality.speciality(speciality_officio == true)

                2. validate that speciality present in $.medical_programs.medical_program_setting.speciality_types_allowed variable

                  1. in case invalid return 422 error with msg ("Employee's specialty doesn't allow create medication request with medical program from request") 

      2. in case medical_program_settings.skip_employee_validation == true or there is no medical_program_id in the request, any user who has a scope can create medication request

  3.  Validate employee has declaration with patient (for intent=order only):

    1. get $.declarations by employee_id, person_id, status=ACTIVE

      1. if not found - return 422 error  (message: "Employee must have an active declaration with the patient to create medication request!")

  4. in case employee_type = <XXX>

а. in case invalid return 422 error with msg ("Employee type can't create medication request with medical program from request")

Validate division

Purpose validation: Validation of division for the possibility of creating a medication request.

  1. Invoke Get division details

  2. Validate division_id - division_id exists

    • in case invalid return 422 error with msg ("Division not found")

  3. Validate Response $.data.status==ACTIVE

    1. if not found - return 422 error (message: "Only employee of active divisions can create medication request!")

  4. Division should be active and refers to current legal_entity

    • is_active = true

      status = 'ACTIVE'

      division.legal_entity_id = client_id (context)

Validate legal entity

Purpose validation: Validation of legal entity for the possibility of creating a medication request.

  1. Get client_id from token

  2. Validate client_id=legal_entity_id

    1. check that legal_entity exist

      1. in case invalid return 422 error with msg (422 Legal entity not found)

    2. check that legal_entities.status == ACTIVE

      1. in case invalid return 422 error with msg ("Only active legal entity can provide medication request")

Validate person

Purpose validation: Validation of person for the possibility of creating a medication request.

  1. Invoke Get patient by ID

  2. Validate person_id - mpi_id exists

    • in case invalid return 422 (422 Person not found)

  3. Save temporary variables from: $.data.authentication_methods

  4. Validate Response $.data.is_active==TRUE

    1. if not found - return 422 error (message: "Only for active MPI record can be created medication request!")

  5. Validate person's verification status:

    1. If MRR has based_on with valid activity, then skip this validation.

    2. Else check patient's verification_status is not equal to NOT_VERIFIED.

      1. in case NOT_VERIFIED - return error 409, "Patient is not verified"

Validate dates

  1. created_at - similar to assertion date in FHIR -> Actual date medication request being created

  2. inserted_at - date when Medication request was registered in E-Health

  3. started_at/ended_at - Treatment period. Cannot be less than MR expiration period. Defined by doctor.

  4. dispence_valid_from - Used for dispense validation. As for now equals Created at.

  5. dispense_valid_to -  Implements dispense expiration period. If MR has medical program setting with not empty parameter medication_dispense_period_day, then dispence_valid_from + medication_dispense_period_day, else Dispense valid from + medication_dispense_period global parameter value.

Purpose validation:  Must be: ended_at >= started_at >= created_at

  1. Validate that created_at, started_at, ended_at in date format

    1. in case invalid return 422 with msg ("expected \"%{actual}\" to be a valid ISO 8601 date")

  2. Validate ended_at >= started_at

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

  3. Validate started_at` >= created_at

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

  4. Validate started_at >= current_date()

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

  5. Validate created_at >= current_date() - mrr_delay_input

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

  6. Validate started_at regarding frequency of receiving drugs

    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: PreQualify Medication request#2.Checkabsencethesamemedicationsfortheprograms

        2. in case skip_mnn_in_treatment_period == TRUE

          1. skip validating frequency of receiving drugs

  7. Validate created_at regarding frequency of receiving drugs

    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: PreQualify Medication request#2.Checkabsencethesamemedicationsfortheprograms

        2. in case skip_mnn_in_treatment_period == TRUE

          1. skip validating frequency of receiving drugs

  8. Validate period length (ended_at - started_at):

    1. If medical program has been submitted:

      1. validate request according to logic: PreQualify Medication request: 7. Validate period

    2. else:

      1. Check that medication request period less than or equal to MEDICATION_REQUEST_MAX_PERIOD_DAY parameter from charts

        1. in case of error - return 409 “Period length exceeds default maximum value“ 

Validate medication

Purpose validation: Check FK, status `is_active`=TRUE, type = INNM_DOSAGE

  1. Invoke Get INNM Dosage by ID

  2. Validate medication_id - medication_id exists

    1. in case of error return 422 ("Medication not found")

  3. Validate Response code == 200

    1. if invalid - return 422 error (message: "Only medication with type `INNM_DOSAGE` can be use for created medication request!")\

  4. Validate Response $.is_active==TRUE

    1. if not found - return 422 error (message: "Only active innm_dosage can be use for created medication request!")

Validate context

  1. Validate "context" is present in the request

    1. in case of error return 422 ("required property context was not present")”

  2. 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 409 "{$.data.context.identifier.type.coding[*].code} not found"

    2. Validate that entity is not in status "entered-in-error"

      1. in case of error 409 "Entity in status "entered-in-error" can not be referenced"

  3. Validate context

    1. encounter is present in the request

      1. in case of error return 422 ("Context with encounter is required as medical program is present in the request")

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

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

Validate dosage instruction

Each non-empty attribute must be valid and reference to appropriate dictionary or object

  1. Sequence must be unique within dosage instruction array

    1. in case of error  return (422, "Sequence must be unique")

  2. Additional instruction must refer to a valid dictionary

    1. $.dosage_instruction[*].additional_instruction.coding[*].system == "eHealth/SNOMED/additional_dosage_instructions"

    2. $.dosage_instruction[*].additional_instruction.coding[*].code is a valid entry in dictionary "eHealth/SNOMED/additional_dosage_instructions"

      1. in case of error return 409 "Incorrect additional instruction"

  3. Site must refer to a valid dictionary

    1. $.dosage_instruction[*].site.coding[*].system == "eHealth/SNOMED/anatomical_structure_administration_site_codes"

    2. $.dosage_instruction[*].site.coding[*].code is a valid entry in dictionary "eHealth/SNOMED/anatomical_structure_administration_site_codes"

      1. in case of error return 409 "Incorrect site"

  4. Route must refer to a valid dictionary

    1. $.dosage_instruction[*].route.coding[*].system == "eHealth/SNOMED/route_codes"

    2. $.dosage_instruction[*].route.coding[*].code is a valid entry in dictionary "eHealth/SNOMED/route_codes"

      1. in case of error return 409 "Incorrect route"

  5. Method must refer to a valid dictionary

    1. $.dosage_instruction[*].method.coding[*].system == "eHealth/SNOMED/administration_methods"

    2. $.dosage_instruction[*].method.coding[*].code is a valid entry in dictionary "eHealth/SNOMED/administration_methods"

      1. in case of error return 409 "Incorrect method"

  6. Dose and rate type must refer to a valid dictionary

    1. $.dosage_instruction[*].dose_and_rate.type.coding[*].system == "eHealth/SNOMED/dose_and_rate"

    2. $.dosage_instruction[*].dose_and_rate.type.coding[*].code is a valid entry in dictionary "eHealth/SNOMED/dose_and_rate"

      1. in case of error return 409 "Incorrect dose and rate type"

Validate based_on

If submitted, check field has array with two values of Reference type: one is valid Care plan resource, another - Activity resource.

  1. Verify Care plan:

    1. It should belong to the same person as set in MRR

      1. in case of error return 422 with msg ("Care plan not found")

    2. It should be in active status

  2. Verify submitted Activity:

    1. It belongs to the Care plan.

      1. in case of error return 422 with msg ("Activity not found")

    2. It has activity.detail.kind=medication_request; activity.detail.product_reference=medication_id.

      1. in case of error return 422 with msg ("Invalid activity kind")

    3. It has scheduled, in_progress status

    4. If it has quantity then calculate remaining quantity:

      1. select all MRR in status NEW which based on current activity

        select all MR in statuses ACTIVE, COMPLETED based on current activity

        calculate reserved at the moment medication quantity as sum of medication_qty in the filtered MRR  and MR list, including medication_qty from current MRR

        calculate remaining quantity by subtracting reserved quantity from activity quantity

      2. Check remaining quantity is greater then or equal to zero

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

    5. check that medical_program_id equal to $.activity[].program

      1. in case of error return 422 with msg ("Medical program from activity should be equal to medical program from request")

  3. Validate started_at/ended_at of Medication request Request: 

    1. if care plan activity has detail.scheduled_timing.repeat.bounds_period - validate started_at/ended_at within bounds_period

      if care plan activity has detail.scheduled_period - validate started_at/ended_at within scheduled_period

    2. else - validate started_at/ended_at crossing within care_plan.period

      1. in the case of started_at/ended_at is not within care_plan.period return 422 with msg  ("Invalid care plan period")

       

Validate medical program

  1. Validate medical_program_id is present in the request

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

  2. Validate medical_program_id - medical_program_id exists

    1. in case of error return 422 ("Medical program not found")

  3. Validate medical_programs.medical_program_setting parameters

    1. check if care_plan_required == true then the request should contain a based_on with care plan and activity that contains the same medical program

      1. in case of error return 422 with msg ("Care plan and activity with the same medical program should be present in request")

    2. If there is conditions_icd10_am_allowed parameter, then:

      1. Check if primary diagnosis from the encounter in context has code from eHealth/ICD10_AM/condition_codes dictionary

        1. Check diagnosis code in conditions_icd10_am_allowed

          1. in case of error - return 422 “Encounter in context has no primary diagnosis allowed for the medical program“

    3. If there is conditions_icpc2_allowed parameter, then:

      1. Check if primary diagnosis from the encounter in context has code from eHealth/ICPC2/condition_codes dictionary

        1. Check diagnosis code in conditions_icpc2_allowed

          1. in case of error - return 422 “Encounter in context has no primary diagnosis allowed for the medical program“

    4. if skip_medication_request_employee_declaration_verify = false or null/absent

      1. then: get $.declarations by employee_id, person_id, status=ACTIVE

        1. if not found - return 422 error  "Only doctors with an active declaration with the patient can create medication request!"

      2. else skip declaration verification on employee level (if true)

    5. if skip_medication_request_legal_entity_declaration_verify = false or null/absent

      1. then: get $.declarations by employee's legal_entity_id, person_id, status=ACTIVE

        1. if not found - return 422 error "Only legal entity with an active declaration with the patient can create medication request!"

      2. else skip declaration verification on legal entity level (if true)

Validate multiplicity & medication request allowed for participants

Purpose validation:  Request quantity must have multiplicity package_min_qty for linked medications.  Result (Mod or % operator) must = 0 .
Also if present Medical_program - must exists medications with `medication_request_allowed`== TRUE for participants.

  1. If `$.medical_program_id` present in payload (non null) - Check exist (IF EXIST()) medication & participant 

    1. if not exist - return 404 error (message: "Not found any medications allowed for create medication request for this medical program!")

      SELECT * FROM medications MI                                         -- 2nd level: Medication - type = INNM_DOSAGE     INNER JOIN ingredients I         ON I.medication_child_id = MI.id             AND I.is_primary =TRUE     INNER JOIN medications MED                              -- 3rd level: Medication - type = BRAND         ON MED.type == BRAND             AND I.parent_id = MED.id             AND MED.is_active == TRUE     INNER JOIN program_medications MP         ON MP.medical_program_id == `DOSTUPNI LIKI`             MED.id = MP.medication_id             AND MP.is_active == TRUE             AND MP.medication_request_allowed == TRUE WHERE MI.id == $.medication_id     AND MI.type == INNM_DOSAGE     AND MI.is_active == TRUE

    2. Check exist (IF EXIST()) medication & get combinations of manufacture

      1. if not exist - return 404 error (message: "Not found any active linked medication for this innm dosage!")

        SELECT DISTINCT MED.package_min_qty FROM medications MI                                         -- 2nd level: Medication - type = INNM_DOSAGE     INNER JOIN ingredients I         ON I.medication_child_id = MI.id             AND I.is_primary =TRUE     INNER JOIN medications MED                              -- 3rd level: Medication - type = BRAND         ON MED.type == BRAND             AND I.parent_id = MED.id             AND MED.is_active == TRUE WHERE MI.id == $.medication_id     AND MI.type == INNM_DOSAGE     AND MI.is_active == TRUE

  1. Vaildate multiplicity (Mod == 0) for all elements in result (`$.medication_qty` Mod `MED.package_min_qty` == 0)

    1. if all result of Mod operator  - NOT 0 - return 409 eror (message: "The amount of medications in medication request must be divisible to package minimum quantity") 

Generate number & verification_code for Medication request

  • Generate human readable number for receipt (See specs)

    Structure number XXXX-1234-5678-9012-345-C , where: - XXXX - series: numbers + only some letters (A, E, H, K, M, P, T, X) - 1234-5678-9012-345 - randomly generated numbers - C - checksum: Should be calculated using the Damn algorithm or Verhoeff algorithm After new Request number was generated we should check that it is unique in the DB (entity: medication_request + medication_request_request

    • Generate verification_code for MPI.person_authentication_methods == OTP or OFFLINE

Create Medication request Request

  1. set:

    1. dispense_valid_from = created_at

      dispensed_valid_to = dispensed_valid_from + dispense_period

  2. Fill 'data' structure for Response & save in IL.medication_request_requests

Generate content for response

  • Generate data structure with Responce WS structure

    • Set IL.medication_request_requests this structure

  • in case if response is VALID enrich response with urgent_data:

    • get authetification_method by person_id and return masked number (in case if any)

 

ЕСОЗ - публічна документація