Purpose

This WS is designed to create Request for 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

Specification

Apiary

Key points

Only authenticated and authorized users with appropriate scope can Create Medication Request Request (MRR)
Patient should be stored in hashed form according to security requirements.

Authorize

Verify the validity of access token
1. in case of error - return 401 (“Invalid access token”) in case of validation fails
Verify that token is not expired
1. in case of error - return 401 (“Invalid access token”)
Check user scopes in order to perform this action (scope = 'medication_request_request:write')
1. return 403 (“Your scope does not allow to access this resource. Missing allowances: medication_request_request:write”) in case of invalid scope(s)
If BLOCK_UNVERIFIED_PARTY_USERS is true, then check party's data match following condition: verification_status != NOT_VERIFIED or (verification_status = NOT_VERIFIED and updated_at > current_date - UNVERIFIED_PARTY_PERIOD_DAYS_ALLOWED):
1. in case not match - return 403 ("Access denied. Party is not verified")
If BLOCK_DECEASED_PARTY_USERS is true, check that party is not deceased (party_verification record does not equal to: dracs_death_verification_status = VERIFIED and dracs_death_verification_reason = MANUAL_CONFIRMED):
1. in case of error - return 403 ("Access denied. Party is deceased")

Validations

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
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 requested primary container volume
a. if not exist - return 404 error (message: "Not found any appropriate medication with such container parameters")

Validate priority

Check by schemata if $.priority is filled with the value of MEDICATION_REQUEST_PRIORITY dictionary
1. in case of error return 422 error ("value is not allowed in enum")

Validate prior_prescription

Check that $.prior_prescription is UUID, exists and belongs to this person:
1. is_active = true, and the same person.
  1. in case of error - return 422 (message: "Prior prescription is not found")

Validate employee

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

Invoke employee_id from request
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. If medical program is present and has medical_program_settings with skip_employee_validation == false (or absent), then validate <employee_type>:
  1. validate if employee_type is present in medical_program_settings employee_types_to_create_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_request_employee_declaration_verify = false or null/absent
        then: get $.declarations by employee_id, person_id, status=ACTIVE
        if not found - return 422 error "Only doctors with an active declaration with the patient can create medication request with medical program from request!"
        else skip declaration verification on employee level (if true)
      2. if variable skip_request_legal_entity_declaration_verify = false or null/absent
        then: get $.declarations by employee's legal_entity_id, person_id, status=ACTIVE
        if not found - return 422 error "Only legal entity with an active declaration with the patient can create medication request with medical program from request!"
        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
        in case invalid return 422 error with msg ("Employee's specialty doesn't allow create medication request with medical program from request")
    4. in case employee_type = MED_COORDINATOR
      1. skip validation that speciality present in $.medical_programs.medical_program_setting.speciality_types_allowed variable
5. If medical program has medical_program_settings with 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

Validate division

Validation of the division for the possibility of creating a medication request.

Invoke Get division details
Validate division_id - division_id exists
1. in case invalid return 422 error with msg ("Division not found")
Validate Response $.data.status==ACTIVE
1. if not found - return 422 error (message: "Only employee of active divisions can create medication request!")
Division should be active and refers to current legal_entity
1. is_active = true
2. status = 'ACTIVE'
3. division.legal_entity_id = client_id (context)

Validate legal entity

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

Get client_id from token
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 ("Legal entity is not active")
3. check legal entity type in chart parameter MEDICATION_REQUEST_REQUEST_LEGAL_ENTITY_TYPES
  1. in case invalid return 409 error with msg (“Invalid legal entity type“)

Validate person

Validation of person for the possibility of creating a medication request.

Invoke validation described at PreQualify Medication Request: Check person

Validate dates

created_at - similar to assertion date in FHIR -> Actual date medication request being created
inserted_at - date when Medication request was registered in E-Health
started_at/ended_at - Treatment period. Cannot be less than MR expiration period. Defined by doctor.
dispense_valid_from - Used for dispense validation. As for now equals Created at.
dispense_valid_to - Implements dispense expiration period. If MR has medical program setting with not empty parameter dispense_period_day, then dispense_valid_from + dispense_period_day, else Dispense valid from + medication_dispense_period global parameter value.

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

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")
Validate ended_at >= started_at
1. if invalid - return 422 error (message: "The end date should be equal to or greater than the start date.")
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).")
Validate started_at >= current_date()
1. if invalid - return 422 error (message: "Started date must be >= current date!")
Validate created_at >= current_date() - MEDICATION_REQUEST_REQUEST_DELAY_INPUT chart param
1. if invalid - return 422 error (message: "Create date must be >= Current date - MRR delay input!")
Validate started_at regarding frequency of receiving drugs
1. get $.medical_programs.medical_program_setting by medical_program_id from request
  1. validate skip_treatment_period variable
    1. in case skip_treatment_period == FALSE (or absent)
      1. validate request according to logic: PreQualify Medication request: 2. Check absence the same medications for the programs
    2. in case skip_treatment_period == TRUE
      1. skip validating frequency of receiving drugs
Validate created_at regarding frequency of receiving drugs
1. get $.medical_programs.medical_program_setting by medical_program_id from request
  1. validate skip_treatment_period variable
    1. in case skip_treatment_period == FALSE (or absent)
      1. validate request according to logic: PreQualify Medication request: 2. Check absence the same medications for the programs
    2. in case skip_treatment_period == TRUE
      1. skip validating frequency of receiving drugs
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 request_max_period_day parameter from charts
    1. in case of error - return 409 “Period length exceeds default maximum value“

Validate medication

Check FK, status `is_active`=TRUE, type = INNM_DOSAGE

Invoke Get INNM Dosage by ID
Validate medication_id - medication_id exists
1. in case of error return 422 ("Medication not found")
Validate Response code == 200
1. if invalid - return 422 error (message: "Only medication with type `INNM_DOSAGE` can be use for created medication request!")\
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

Validate "context" is present in the request
1. in case of error return 422 ("required property context was not present")
Validate "context" is an active (not entered-in-error) encounter, that belongs to the current patient
1. Validate context.identifier.type.coding[0].code = encounter
  1. in case of error return 422 ("value is not allowed in enum")
2. 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 422 "Entity not found"
3. Validate that entity is not in status "entered-in-error"
  1. in case of error 422 "Entity in status "entered-in-error" can not be referenced"
4. encounter diagnosis is not empty in $.encounter.diagnosis
  1. in case of error return 422 ("Encounter without diagnosis can not be referenced")
5. Validate employee_id in $.encounter.performer.identifier.value == $. data.employee_id
  1. in case of error return 422 ("Employee is not performer of encounter")
6. Validate $.data.created_at is within $.encounter.period including borders
  1. in case of error return 422 ("Invalid encounter period")

Validate dosage instruction

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

Invoke validation described at Preqalify Medication Request: Validate dosage instructions

Validate based_on

If submitted, invoke validation described at PreQalify Medication Request: Check Care Plan and Activity

Validate medical program

Validate medical_program_id is present in the request
1. in case of error return 422 ("required property medical_program_id was not present")
Validate medical_program_id - medical_program_id exists
1. in case of error return 422 ("Medical program not found")
Validate medical_programs.medication_request_allowed parameter
1. check if medication_request_allowed == true
  1. in case of error return 422 with msg ("Forbidden to create medication request for this medical program!")
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“
If medical program has funding_source = LOCAL , then invoke validation described at https://e-health-ua.atlassian.net/wiki/spaces/RMDN/pages/17693868130/UPD+PreQualify+Medication+request+request#11.-Check-provision-for-a-programs

Validate multiplicity & medication request allowed for participants

Perform validation as described at PreQalify Medication Request: Check INNM complience for the programs. If MRR has no program, then following script used in this validation to define list of medications (BRANDs):

SELECT m0.id, m2.id, m2.package_qty, m2.package_min_qty
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
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)

Perform validation as described at

PreQalify Medication Request: Check absence the same medications for the programs.

Validate authorize_with

If submitted, invoke validation described at PreQalify Medication Request: Check authorize with

Service Logic

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
Structure code 1234, where: - 1234 - randomly generated numbers

Create Medication request Request

set:
1. dispense_valid_from = created_at
2. dispensed_valid_to = dispensed_valid_from + dispense_period
Fill 'data' structure for Response & save in IL.medication_request_requests
1. If encounter is present in the request context then based on it - fill the IL.medication_request_requests.context_episode_id
Fill separately
1. data_employee_id,
  data_intent,
  data_based_on_care_plan_id,
  data_based_on_activity_id,
  data_context_id,
  data_patient_id,
  data_legal_entity_id,
  data_authorize_with
If the medication request request is based on activity with quantity - set remaining_quantity for the activity which was calculated at validation Create Medication Request: Validate based_on (6. Check Care plan and Activity, p. 2.d.1 )

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:
- if authorize_with is submitted - get authentication_method details and return masked number (in case if any)
- else if authorize_with is not submitted - get default authentication_method by person_id and return masked number (in case if any)

RC_CSI-2483_Create Medication request Request