...
...
...
...
Purpose
This WS is designed to Pre-qualify data of Medication request Request (post) - check whether it's possible to use Medication request within the particular Medical program.
There are two types of medication requests:
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.
Key points
Only authenticated and authorized users with appropriate scope can invoke Prequalify Medication Request Request (MRR)
This method simply returns the result of data validation within each submitted medical program, but not creates any entities in the system
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
Any Medical program can have separate block of branching logic configured at medical program settings by NHS administrator
Сompatibility is checked only for programs which are available in payload (array)
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.
Specification
...
Link
...
...
Посилання на Apiary або Swagger
...
Resource
...
/api/medication_request_requests/prequalify
...
Посилання на ресурс, наприклад: /api/persons/create
...
Scope
...
medication_request_request:write
...
Scope для доступу
...
Components
...
ePrescription
...
Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription
...
Microservices
...
API paragraph not found
...
Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC
...
Protocol type
...
REST
...
Тип протоколу, який використовується запитом, наприклад: SOAP | REST
...
Request type
...
POST
...
Тип запиту API, наприклад: GET, POST, PATCH…
...
Sync/Async
...
Sync
...
Метод є синхронним чи асинхронним?
Logic
API paragraph not found
Preconditions
API paragraph not found
Global and configurable parameters
No
Input parameters
ATTRIBUTES - see on Apiary
Filters
No
Request structure
See on Apiary
Example:
| Expand | ||
|---|---|---|
| ||
|
Authorize
Verify the validity of access token
in case of error - return 401 (“Invalid access token”) in case of validation fails
Verify that token is not expired
in case of error - return 401 (“Invalid access token”)
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)
Headers
Content-Type:application/json
Authorization:Bearer c2778f3064753ea70de870a53795f5c9
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
in case of error return 422 error ("required property %{property} was not present")
$.container_dosage.system should be “MEDICATION_UNIT”
in case of error return 422 error ("value is not allowed in enum")
if $.container_dosage is filled then $.container_dosage.unit should be checked with the MEDICATION_UNIT dictionary by $.container_dosage.code as a key.in case of error return 422 error ("value is not allowed in enum")
Validate priority
Check by schemata if $.priority is filled with the value of MEDICATION_REQUEST_PRIORITY dictionary
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:
is_active = true, and the same person.
in case of error - return 422 (message: "Prior prescription is not found")
Validate medication request type
Only medication request with type (intent) order can be qualified.
Check medication request intent is order
in case intent == plan - return 409, "Plan can't be qualified"
Validate division
Validate it is exists and active, relates to current legal entity (client_id from token)
in case of error - return 422 error “Only employee of active divisions can create medication request!“
Validate dates:
Check ended_at >= started_at
in case of error - return 422 error “Ended date must be >= Started date!“
Check started_at >= created_at
in case of error - return 422 “Started date must be >= Created date!”
Check started_at >= current date
in case of error - return 422 “Started date must be >= Current date!”
Check created_at >= (current date - MEDICATION_REQUEST_REQUEST_DELAY_INPUT)
in case of error - return 422 “Create date must be >= Current date - MRR delay input!”
Validate dosage instructions
Validate each item as described at Create Medication Request Request: Validate dosage instruction
Validate compliance for programs
Some checks (below in the text) must be passed for the programs
if passed - save the response by this program - status = VALID
if not passed - save response by this program - status = INVALID
Check each medical program in the array is:
is exists
in case of error - return status = INVALID and reject reason = “Medical program not found”
is_active = true
in case of error - return status = INVALID and reject reason = “Medical program is not active”
1. Check INNM complience for the programs
There is a list of medications (BRANDs, which links to Innms) 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
Check compatibility of innm with medication list for the program
if data is not found:
add to response: status = INVALID
add to response: rejection_reason = "Not found any medications allowed for create medication request for this medical program!"
...
| title | SQL script example |
|---|
| Code Block |
|---|
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) |
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")
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")
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“
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
For info - status charts: Medication_request
Get `check_innm_id`
...
| title | SQL script example |
|---|
| Code Block |
|---|
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) |
Get Medication requests with their completed Medication dispense by person_id & check_innm_id
...
| title | SQL script example |
|---|
| Code Block |
|---|
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 |
Validate exist (IF EXIST () - that is
any crossing calculating term (started_at + ended_at) for payload with terms selecting Medication requests (started_at + ended_at).
if found and medical program setting skip_mnn_in_treatment_period = false (absent):
add to response: status = INVALID
add to response: rejection_reason = "It can be only 1 active / completed medication request request or medication request per one innm for the same patient at the same period of time!"
Fetch Medication Request by $
innm_dosge, $medical_program_id, $person_id and max(end_date). In case there is found Medication Request with ended_at>=current_date then next one can be done in:
if (ended_at - started_at) >= 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 MRin case of error return 422 error ('It's to early to create new medication request for such innm_dosage and medical_program_id')
if (ended_at - started_at) < 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 MRin case of error return 422 error ('It's to early to create new medication request for such innm_dosage and medical_program_id')
3. Check that care plan is mandatory for programs
It is need to check if the medication request with a program need a care plan (with setting `care_plan_required` == TRUE) for a this program.
Check if there is a based_on in the request
Check care_plan_required in medical program setting
| Expand | ||
|---|---|---|
| ||
|
b. if care_plan_required true:
i. check based_on (reference on care_plan and it activity) in request comply with program
in case based_on not found:
a. add to response: status = INVALID
b. add to response: rejection_reason = "Medical program from activity should be equal to medical program from request"
4. Check diagnosis comply with programs
It is needed to check if medication request with a program needed a context (encounter) with a specified diagnosis.
If program has CONDITIONS_ICD10_AM_ALLOWED parameter in medical_program_settings:
Check if primary diagnosis from the encounter in context has code from eHealth/ICD10_AM/condition_codes dictionary
Check diagnosis code in CONDITIONS_ICD10_AM_ALLOWED
in case of error - return 200 with status = INVALID and rejection_reason = “Encounter in context has no primary diagnosis allowed for the medical program“
If program has CONDITIONS_ICPC2_ALLOWED parameter in medical_program_settings:
Check if primary diagnosis from the encounter in context has code from eHealth/ICPC2/condition_codes dictionary
Check diagnosis code in CONDITIONS_ICPC2_ALLOWED
in case of error - return 200 with status = INVALID and rejection_reason = “Encounter in context has no primary diagnosis allowed for the medical program“
5. Check employee
It is needed to check if medication request with a program allowed to create for specified employee.
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
It is needed to check if medication request with a program allowed to be created for specified care plan and activity.
Validare based_on as described on Create Medication request Request.
7. Check period
It is needed to check if medication request period does not exceed allowed maximum of days.
If medication request has program with MEDICATION_REQUEST_MAX_PERIOD_DAY in medical program setting:
Check that medication request period (ended_at - started_at) less than or equal to medical program setting MEDICATION_REQUEST_MAX_PERIOD_DAY parameter
in case of error - return 200 with status = INVALID and rejection_reason = “Period length exceeds allowed value for the medical program“
If medication request has program without MEDICATION_REQUEST_MAX_PERIOD_DAY in medical program setting:
Check that medication request period (ended_at - started_at) less than or equal to MEDICATION_REQUEST_MAX_PERIOD_DAY parameter from charts
in case of error - return 200 with status = INVALID and rejection_reason = “Period length exceeds default maximum value“
8. Check context
Validate "context" is an active (not entered-in-error) entity from corresponding dictionary, that belongs to the current patient
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
in case of error - return 200 with status = INVALID and rejection_reason = “Entity not found“
encounter diagnosis is not empty in $.encounter.diagnosis
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.
Validate person's verification status as described on Create Medication request Request
10. Check declaration for a program
It is needed to check specified params for each medical program.
Declaration should always be validated for each program. Validate skip_medication_request_employee_declaration_verifyand skip_medication_request_legal_entity_declaration_verify parameters at medical program settings as described at Create Medication request Request if there are some exclusions.
11. Check provision for a programs
It is needed to check if medical program can be provided by pharmacies.
If medical program has funding_source = LOCAL:
Check there is exists any active medical program provision with msp_legal_entity_id equal to employee's legal entity
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"
Parameters that are used when processing the request
Configuration parameters
API paragraph not found
Dictionaries
API paragraph not found
Processing
API paragraph not found
Response structure
Collect array for all programs in payload with status for each (VALID or INVALID) and rejection_reason.
See on Apiary
Example:
| Expand | ||
|---|---|---|
| ||
|
Post-processing processes
API paragraph not found
HTTP status codes
...
HTTP status code
...
Message
...
What caused the error
...
200
...
Response
...
...
401
...
Invalid access token
...
403
...
Your scope does not allow to access this resource. Missing allowances: medication_request_request:write
...
409
...
Plan can't be qualified
...
422
...
required property %{property} was not present
value is not allowed in enum
Prior prescription is not found
Only employee of active divisions can create medication request!
Ended date must be >= Started date!
Started date must be >= Created date!
Create date must be >= Current date - MRR delay input!
The amount of medications in medication request must be divisible to package minimum quantity
It's to early to create new medication request for such innm_dosage and medical_program_id
Encounter without diagnosis can not be referenced
The amount of medications in medication request must be divisible to package minimum quantity
...
Backward compatibility
...