| Table of Contents | ||||
|---|---|---|---|---|
|
Purpose*
Pre-qualify service request in order to define whether the medical program could be applied in this particular case or not
Specification*
...
Link
...
...
Resource
...
/api/patients/{{patient_id}}/service_requests/prequalify
...
Scope
...
service_request:write
...
Components
...
Service request
...
Microservices
...
API paragraph not found
...
Protocol type
...
REST
...
Request type
...
POST
...
Sync/Async
...
Async
...
Public/Private/Internal
...
Public
Logic*
This method is used to pre-qualify service request in order to define whether the medical program could be applied in this particular case or not
Input parameters
...
Input parameter
...
Values
...
Type
...
Description
...
Example
...
patient_id
...
String
...
Unique patient identifier
...
7075e0e2-6b57-47fd-aff7-324806efa7e5
Request structure*
See on Apiary
Example:
...
| title | Response example |
|---|
...
| Table of Contents | ||||
|---|---|---|---|---|
|
Purpose
This WS is designed to prequalify Service request: check the ability of create Service request within the Medical program
Specification
| Page Properties | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Preconditions
must be an active encounter
Logic
This method is used to pre-qualify service request in order to define whether the medical program could be applied in this particular case or not
Input parameters
Input parameter | Values | Type | Description | Example |
|---|---|---|---|---|
patient_id | String | Unique patient identifier |
|
Request structure
See on Apiary
Example:
| Expand | ||
|---|---|---|
| ||
|
Authorize*
Verify the validity of access token
Return (401, 'unauthorized') in case of validation fails
Verify that token is not expired
in case of error - return (401, 'unauthorized')
Check user scopes in order to perform this action (scope = 'service_request:write')
Return (403, 'invalid scopes') in case of invalid scope(s)
Request to process the request using a token in the headers
Headers*
Наприклад:
Content-Type:application/json
Authorization:Bearer mF_9.B5f-4.1JqM
Request data validation*
Validate request using JSON Schema
Return 422 with the list of validation errors in case validation fails
Validate legal entity
Check legal entity type: it has to be in me_allowed_transactions_le_types config parameter, has status = active
in case of error return 409 "Action is not allowed for the legal entity"
Validate service request
Validate that service request ID is unique
$.id must be unique
in case of error return 409 - "Service request with such id already exists"
Requisition is a common identifier for the group of service requests and it must matches with one of the patient's episode of care number
$.requisition must match with patient's episode of care number
in case of error return 409 - "Incorrect requisition number"
Service request category must refer to a valid dictionary
$.category.coding[*].system == "eHealth/SNOMED/service_request_categories"
in case of error return 409 "Incorrect service request category"
Procedure code must refer to a valid dictionary
$.code.coding[*].system == "eHealth/SNOMED/procedure_codes"
in case of error return 409 "Incorrect procedure code"
Patient must be active
$.patient.identifier.type.coding[*].system == "eHealth/resources"
$.patient.identifier.type.coding[*].code == "patient"
$.patient.identifier.value refer to active MPI (is_active == true and status == 'active')
in case patients.preperson == true
check PREPERSON_SERVICE_REQUEST_ALLOWED_CATEGORIES (values from dictionary: eHealth/SNOMED/service_request_categories) configuration according allowed categories for prepersons
in case of error return 422 (Category of service request is not allowed for prepersons)
Context must be an active encounter
$.context.identifier.type.coding[*].system == "eHealth/resources"
$.context.identifier.type.coding[*].code == "encounter"
$.context.identifier.value refer to existing encounter (status == 'finished')
Occurence is a valid date-time in the future
$.occurrenceDateTime
$.occurrence_date_time - ISO date must be greater current date-time
$.occurrencePeriod.start
$.occurrence_period.start - ISO date must be greater than current date-time
$.occurrence_period.end - ISO date must be greater than current date-time and greater than $.occurrencePeriod.start
in case based_on passed in request
if care plan activity has detail.scheduled_timing.repeat.bounds_period - validate occurence within bounds_period
if care plan activity has detail.scheduled_period - validate occurence within scheduled_period
else - validate occurence within care_plan.period
Authored On is a valid date-time in the past
$.authored_on - ISO date must be less than current date-time
Requester_employee must be active employee within current legal entity
$.requester_employee.identifier.type.coding[*].system == "eHealth/resources"
$.requester_employee.identifier.type.coding[*].code == "employee"
$.requester_employee.identifier.value refer to active employee within current legal entity (employee.status == approved and employee.is_active == true and employee.legal_entity_id == token.client_id)
Requester_legal_enity must be current legal enity
Performer type must refer to a valid dictionary
$.performer_type.coding[*].system == "eHealth/SNOMED/service_request_performer_roles"
in case of error return 409 "Incorrect service request category"
Supporting info must refer to a valid medical events object (Episode of Care) within specified patient.
$.supporting_info.identifier.type.coding[*].system == "eHealth/resources"
in case of error return 409 "Incorrect supporting info"
Reason reference must refer to a valid medical events object (Observation, Condition) within specified patient.
$.reason_reference.identifier.type.coding[*].system == "eHealth/resources"
$.reason_reference.identifier.type.coding[*].code in ("condition", "observation")
in case of error return 409 "Incorrect reason reference"
Permitted Episode of care must refer to a valid medical events object (Episode of Care) within specified patient.
$.permitted_episodes.identifier.type.coding[*].system == "eHealth/resources"
$.permitted_episodes.identifier.type.coding[*].code == "episode_of_care"
in case of error return 409 "Incorrect reason reference"
Validate code is an existing service or service group that is allowed to be used in service_request
in case not found or is_active == false return 422 "Service(Service group) not found"
if request_allowed==false return 422 "Service request is not allowed for this service(service_group)"
in case based_on passed in request
If service_requests.code.identifier.value is service, validate $based_on[].activity.code.identifier.value = service_requests.code.identifier.value
in case error return 422, "Service in activity differs from service in service request"
If service_requests.code.identifier.value is service_group, validate $based_on[].activity.code.identifier.value = service_requests.code.identifier.value
in case error return 422, "Service group in care plan activity differ from service group in service request"
if service_requests.code.identifier.value is service/service group, validate $based_on[].activity.code.identifier.value is service/service group
in case error return 422, "Activity referes to '#{service/service group}' but service request refers to '#{service group/service}'"
Validate service category is equal to service request category in case service was defined as a code (not a service_group)
Select category from PRM.services where id = $.code.identifier.value
if PRM.services.category!=$.category OR PRM.services.category is not NULL return 422 "Service category does not match with service request category"
For each program validate it is an existing service program (type=service)
in case not found or is_active==false write result in Data collection according to apiary
in case type!= service write result in Data collection according to apiary - "Invalid program type"
check if medical_programs.medical_program_settings.care_plan_required == true then the request should contain a based_on with care plan and activity that contains the same medical program
in case of error return 422 with msg ("Care plan and activity with the same program should be present in request")
check that program equal to $.activity[].program
in case of error return 422 with msg ("Program from activity should be equal to program from request")
For each program validate that service(or service_group) is an active member of the program
Select request_allowed, is_active from PRM.program_services where service_id(or group_id) == $.signed_content.code.identifier.value and program_id=$.program.identifier.value
if not found or is_active==false write result in Data collection according to apiary - "Service is not included in the program"
if request_allowed==false write result in Data collection according to apiary - "Service request is not allowed for this service(service_group) in this programm"
For each program validate that doctor is allowed to create service request with the program for the current patient
$.requester has an active declaration with the patient OR
$.requester works in the same MSP with doctor that has an active declaration with the patient AND doctors employee_type== DOCTOR
in case of error write result in Data collection according to apiary - "User is not allowed to create service request with the program for the patient"
Validate based_on
If submitted, check field has array with two values of Reference type: one is valid Care plan resource, another - Activity resource.
in case of error return 422 with msg ("expected a minimum of %{min} items but got %{actual}")
Verify Care plan:
It should belong to the same person as set in service request
in case of error return 422 with msg ("Care plan with such id is not found")
It should be in active status
in case of error return 422 with msg ("Care plan is not active")
Care plan's period end (if exist) should be greater than current date or equal.
Verify submitted Activity:
It belongs to the Care plan.
in case of error return 422 with msg ("Activity with such id is not found")
It has activity.detail.kind=service_request; activity.detail.product_reference=service_request.code[].value.
in case of error return 422 with msg ("Invalid activity kind")
It has scheduled, in_progress status
in case of error return 422 with msg ("Invalid activity status")
if quantity was set, then validate remaining_quantity greater then zero:
in case of error return 422, "The number of available services according to the care plan activity has been exhausted"
Verify activity period:
If it has scheduled_timing:
if bounds_period.end defined then check it greater than current date or equal.
If it has scheduled_period:
if scheduled_period.end defined then check it greater than current date or equal.
Validate patient's verification status:
If SR has based_on with valid activity, then skip this validation.
Else check patient's verification_status is not equal to NOT_VERIFIED.
in case of error return 409, "Patient is not verified"
ELSE, if program meets the requirements write status "Valid" according to apiary.
Processing*
API paragraph not found
...
|
Authorize
Verify the validity of access token
Return (401, 'unauthorized') in case of validation fails
Verify that token is not expired
in case of error - return (401, 'unauthorized')
Check user scopes in order to perform this action (scope = 'service_request:write')
Return (403, 'invalid scopes') in case of invalid scope(s)
Request to process the request using a token in the headers
Headers
Наприклад:
Content-Type:application/json
Authorization:Bearer mF_9.B5f-4.1JqM
Request data validation
Validate request using JSON Schema
Return 422 with the list of validation errors in case validation fails
Validate legal entity
Check legal entity type: it has to be in me_allowed_transactions_le_types config parameter, has status = active
in case of error return 409 "Action is not allowed for the legal entity"
Validate service request
Validate that service request ID is unique
$.id must be unique
in case of error return 409 - "Service request with such id already exists"
Requisition is a common identifier for the group of service requests and it must matches with one of the patient's episode of care number
$.requisition must match with patient's episode of care number
in case of error return 409 - "Incorrect requisition number"
Service request category must refer to a valid dictionary
$.category.coding[*].system == "eHealth/SNOMED/service_request_categories"
in case of error return 409 "Incorrect service request category"
If $.specimens attribute is set, then check the category is in SPECIMEN_SERVICE_REQUEST_ALLOWED_CATEGORIES chart parameter
in case of error - return 422 ("Service request category is not allowed for specimens")
If $.requester_employee has ASSISTANT type, then check the category in ASSISTANT_SERVICE_REQUEST_ALLOWED_CATEGORIES chart parameter
in case of error - return 422 (“Service request category is not allowed for a requester_employee with type ASSISTANT“)
Service request code must refer to a valid dictionary
$.code.identifier.type.coding[*].system == “eHealth/resources”
in case of error return 422 “value is not allowed in enum”
Patient must be active
$.patient.identifier.type.coding[*].system == "eHealth/resources"
$.patient.identifier.type.coding[*].code == "patient"
$.patient.identifier.value refer to active MPI (is_active == true and status == 'active')
in case patients.preperson == true
check PREPERSON_SERVICE_REQUEST_ALLOWED_CATEGORIES (values from dictionary: eHealth/SNOMED/service_request_categories) configuration according allowed categories for prepersons
in case of error return 422 (Category of service request is not allowed for prepersons)
Context must be an active encounter
If focus on specimens is set, then context is optional
$.context.identifier.type.coding[*].system == "eHealth/resources"
$.context.identifier.type.coding[*].code == "encounter"
$.context.identifier.value refer to existing encounter (status == 'finished')
Occurence is a valid date-time in the future
$.occurrenceDateTime
$.occurrence_date_time - ISO date must be greater current date-time
$.occurrencePeriod.start
$.occurrence_period.start - ISO date must be greater than current date-time
$.occurrence_period.end - ISO date must be greater than current date-time and greater than $.occurrencePeriod.start
in case based_on passed in request
if care plan activity has detail.scheduled_timing.repeat.bounds_period - validate occurence within bounds_period
if care plan activity has detail.scheduled_period - validate occurence within scheduled_period
else - validate occurence within care_plan.period
Authored On is a valid date-time in the past
$.authored_on - ISO date must be less than current date-time
Requester_employee must be active employee within current legal entity
$.requester_employee.identifier.type.coding[*].system == "eHealth/resources"
$.requester_employee.identifier.type.coding[*].code == "employee"
$.requester_employee.identifier.value refer to active employee within current legal entity (employee.status == approved and employee.is_active == true and employee.legal_entity_id == token.client_id .rand employee.type=value from list of employee_types in configuration: ALLOWED_SERVICE_REQUEST_REQUESTER_EMPLOYEE_TYPES )
in case of error - 422 “Invalid employee type”
Requester is one of current user's employee
in case of error return 422 "User is not allowed to create service request for the employee"
Requester_legal_enity must be current legal enity
Supporting info must refer to a valid medical events object (Episode of Care, Condition, Observation, Diagnostic report) within specified patient.
$.supporting_info.identifier.type.coding[*].system == "eHealth/resources"
in case of error return 409 "Incorrect supporting info"
Reason reference must refer to a valid medical events object (Observation, Condition) within specified patient.
$.reason_reference.identifier.type.coding[*].system == "eHealth/resources"
$.reason_reference.identifier.type.coding[*].code in ("condition", "observation")
in case of error return 409 "Incorrect reason reference"
Permitted resources must refer to a valid medical events object (Episode of Care, diagnostic report) within specified patient.
$.permitted_resources.identifier.type.coding[*].system == "eHealth/resources"
$.permitted_resources.identifier.type.coding[*].code == "episode_of_care", “diagnostic_report”
in case of error return 409 "Incorrect permitted resources"
Validate code is an existing service or service group that is allowed to be used in service_request
in case not found or is_active == false return 422 "Service(Service group) not found"
if request_allowed==false return 422 "Service request is not allowed for this service(service_group)"
in case based_on passed in request
If service_requests.code.identifier.value is service, validate $based_on[].activity.code.identifier.value = service_requests.code.identifier.value
in case error return 422, "Service in activity differs from service in service request"
If service_requests.code.identifier.value is service_group, validate $based_on[].activity.code.identifier.value = service_requests.code.identifier.value
in case error return 422, "Service group in care plan activity differ from service group in service request"
if service_requests.code.identifier.value is service/service group, validate $based_on[].activity.code.identifier.value is service/service group
in case error return 422, "Activity referes to '#{service/service group}' but service request refers to '#{service group/service}'"
Validate service category is equal to service request category in case service was defined as a code (not a service_group)
Select category from PRM.services where id = $.code.identifier.value
if PRM.services.category!=$.category OR PRM.services.category is not NULL return 422 "Service category does not match with service request category"
For each program validate it is an existing service program (type=service)
in case not found or is_active==false write result in Data collection according to apiary
in case type!= service write result in Data collection according to apiary - "Invalid program type"
check if medical_programs.medical_program_settings.care_plan_required == true:
the request should contain a based_on with care plan and activity that contains the same medical program
in case of error return 422 with msg ("Care plan and activity with the same program should be present in request")
check that program present in request
in case of error return 422 with msg ("Program from activity should be present in request")
check that program equal to $.activity[].program
in case of error return 422 with msg ("Program from activity should be equal to program from request")
if program in service request is set check if $.activity[].program is not null
in case of error return error msg (“Program should not be present in request for this activity“)
For each program validate that service(or service_group) is an active member of the program
Select request_allowed, is_active from PRM.program_services where service_id(or group_id) == $.signed_content.code.identifier.value and program_id=$.program.identifier.value
if not found or is_active==false write result in Data collection according to apiary - "Service is not included in the program"
if request_allowed==false write result in Data collection according to apiary - "Service request is not allowed for this service(service_group) in this programm"
Validate performer
If focus on specimens is set, then performer is optional
if category = transfer_of_care,
performer is sent, in case error return 422, "performer is mandatory for category `transfer_of_care`"
performer is real LE with status=Active and is_Active=true, in case error, return 422, "performer is not active legal entity"
if category = laboratory_procedure,
performer is optional; if is send - performer is real LE with status=Active and is_Active=true, in case error, return 422, "performer is not active legal entity"
else other category and performer is send return 422 error $.performer.identifier.value “Not allowed for this category“
validate LocationReference
if category = transfer_of_care,
LocationReference is real division with type in (CLINIC, LICENSED_UNIT,AMBULANT_CLINIC,FAP) and status=Active and is_active=true, in case error return 422, "LocationReference is not an active division"
LocationReference division.legal_entity_id=Performer, in case error return 422, "Division does not belong to performer legal entity"
Validate PerformerType
if category = hospitalization
PerformerType is sent, in case error return 422, "PerformerType is mandatory for category hospitalization"
PerformerType is a code from dictionary.SPECIALITY_TYPE and match config file 'SERVICE_REQUEST_HOSPITALIZATION_SPECIALITY_TYPES', in case error return 422, "PerformerType=$PerformerType is forbidden for category hospitalization"
if performer_type value is included in chart variables 'SERVICE_REQUEST_PERFORMER_TYPE_SPECIALITY_TYPES':
define allowed service codes for service_requests.code.identifier.value using a set of chart variables 'SERVICE_REQUEST_<SPECIALITY_TYPE>_PERFORMER_TYPE_CODES', in case of error return 422 “Service does not correspond to performer's speciality for hospitalization“
if category = transfer_of_care
if service codes for service_requests.code.identifier.value using a set of chart variables 'SERVICE_REQUEST_TRANSFER_OF_CARE_<SPECIALITY_TYPE>_PERFORMER_TYPE_CODES', performer_type field is mandatory
in case error return 422, "PerformerType is mandatory"
PerformerType is a code from dictionary.SPECIALITY_TYPE and match config file 'SERVICE_REQUEST_TRANSFER_OF_CARE_SPECIALITY_TYPES', in case error return 422, "PerformerType=$PerformerType is forbidden for category transfer_of_care"
if performer_type value is included in chart variables 'SERVICE_REQUEST_TRANSFER_OF_CARE_PERFORMER_TYPE_SPECIALITY_TYPES':
define allowed service codes for service_requests.code.identifier.value using a set of chart variables 'SERVICE_REQUEST_TRANSFER_OF_CARE_<SPECIALITY_TYPE>_PERFORMER_TYPE_CODES', in case of error return 422 “Service does not correspond to performer's speciality for transfer of care“
else other category and PerformerType is send return 422 error $.performer_type.coding[0].value "Not allowed for category <category>"
Validate based_on
If submitted, check field has array with two values of Reference type: one is valid Care plan resource, another - Activity resource.
in case of error return 422 with msg ("expected a minimum of %{min} items but got %{actual}")
Verify Care plan:
It should belong to the same person as set in service request
in case of error return 422 with msg ("Care plan with such id is not found")
It should be in active status
in case of error return 422 with msg ("Care plan is not active")
Care plan's period end (if exist) should be greater than current date or equal.
Verify submitted Activity:
It belongs to the Care plan.
in case of error return 422 with msg ("Activity with such id is not found")
It has activity.detail.kind=service_request; activity.detail.product_reference=service_request.code[].value.
in case of error return 422 with msg ("Invalid activity kind")
It has scheduled, in_progress status
in case of error return 422 with msg ("Invalid activity status")
if quantity was set, then validate remaining_quantity greater then zero:
if quantity.code = PIECE:
select all active service requests based on current activity and calculate previously reserved quantity as sum of SR.quantity.value.
select all medical events based on not active service requests, that relates to current activity, and count their number as used quantity.
calculate reserved at the moment quantity as sum of previously reserved quantity and used quantity, including quantity from current SR
calculate remaining quantity by subtracting reserved at the moment quantity from activity's quantity
Check remaining quantity is greater then or equal to zero
in case of error return 422 "The number of available services according to the care plan activity has been exhausted"
if quantity.code = MINUTE:
select all active service requests based on current activity and calculate previously reserved quantity as sum of SR.quantity.value
select all procedures based on not active service requests, that based on current activity, and calculate used quantity as sum of procedure durations (calculates from performed_period attribute)
calculate reserved at the moment quantity as sum of previously reserved quantity and used quantity, including quantity from current SR
calculate remaining quantity by subtracting reserved at the moment quantity from activity's quantity
Check remaining quantity is greater then or equal to zero
in case of error return 422 "The number of available services according to the care plan activity has been exhausted"
if quantity.code is null:
select all medical events based on service requests, that are related to current activity, and count their number as used quantity.
calculate remaining quantity by subtracting used quantity from activity's quantity
Check remaining quantity is greater then zero
in case of error return 422 "The number of available services according to the care plan activity has been exhausted"
Verify activity period:
If it has scheduled_timing:
if bounds_period.end defined then check it greater than current date or equal.
If it has scheduled_period:
if scheduled_period.end defined then check it greater than current date or equal.
Validate patient's verification status:
If SR has based_on with valid activity, then skip this validation.
Else check patient's verification_status is not equal to NOT_VERIFIED.
in case of error return 409, "Patient is not verified"
ELSE, if program meets the requirements write status "Valid" according to apiary.
25. Validate quantity
Check it is SimpleQuantity type, $.quantity.value is not empty, fractional and greater than zero
in case of error return 422 schema validation error
Check $.quantity.system is SERVICE_UNIT dictionary and $.quantity.code belongs to it
in case of error return 422 schema validation error
In case based_on passed in request and activity there has a quantity attribute:
Validate that system and code in activity's quantity isn’t null
in case of error return 422 (“A service request is not allowed to have a quantity attribute if the quantity in the related activity has no units”)
Validate that system and code in activity's quantity match to the system and code in the service request's quantity.
in case of error return 422 ("The quantity units must not differ from the quantity units in the activity"
26. Validate focus, if submitted:
Check field is array with elements of Reference type on Specimen resource
in case of error return 422 “not allowed in enum”
Check there is at least one Specimen and it matches those pointed in specimens field:
in case of error return 422 “Specimen does not match what is indicated in the specimens field.“
Processing
API paragraph not found
Response structure
See on Apiary
Example:
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
Post-processing processes
...
API paragraph not found
HTTP status codes
...
| Page Properties | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|