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

[AH] Create Service Request v.2 [04.09.24]

Owned by Serhii Boldin (SoE eHealth)
Last updated: Sep 04, 2024 by Anastasiia Prokhorova (SoE eHealth)
6 min read

Purpose

This WS is designed to create Service request for receiving services.

Specification

Apiary

Authorization

  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 = 'service_request:write')

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

  4. 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")

  5. 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 request using JSON Schema

Return 422 with the list of validation errors in case validation fails

Validate legal entity

  1. Check legal entity type: it has to be in me_allowed_transactions_le_types config parameter, has status = active and nhs_verified = true

    1. in case of error return 409 "Action is not allowed for the legal entity"

Validate digital signature

  1. Validate request is signed

    1. in case of error - return 400 (“document must be signed by 1 signer but contains 0 signatures”)

  2. Check DS is valid and not expired

  3. Validate that DS belongs to the user

    1. Check that DRFO from DS and party.tax_id matches

      1. in case of error - return 422 (“Does not match the signer drfo“)

Validate service request

  1. Validate that service request ID is unique

    1. $.id must be unique

      1. in case of error return 409 - "Service request with such id already exists"

  2. Requisition is a common identifier for the group of service requests and it must matches with one of the patient's encounter number

    1. $.requisition must match with patient's encounter number

      1. in case of error return 409 - "Incorrect requisition number"

  3. Service request category must refer to a valid dictionary

    1. $.category.coding[*].system  == "ehealth/SNOMED/service_request_categories" 

      1. in case of error return 409 "Incorrect service request category"

    2. in case service was defined as a code (not a service_group) validate service_request.category=service.category from $code.identifier.value

      1. in case error return 422, "Category mismatch"

    3. if category in (hospitalization, transfer_of_care), do not validate service_request.category=service.category from $code.identifier.value

    4. 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")

    5. If $.requester_employee has ASSISTANT type, then check the category in ASSISTANT_SERVICE_REQUEST_ALLOWED_CATEGORIES chart parameter

      1. in case of error - return 422 (“Service request category is not allowed for a requester_employee with type ASSISTANT“)

  4. Service request code must refer to a valid dictionary

    1. $.code.identifier.type.coding[*].system  == “eHealth/resources”

      1. in case of error return 422 “value is not allowed in enum”

  5. Patient must be active

    1. check that patients.status == active

      1. in case of error return 409 (Person is not active)

    2. check if patients.preperson == true

      1. check PREPERSON_SERVICE_REQUEST_ALLOWED_CATEGORIES (values from dictionary: eHealth/SNOMED/service_request_categories) configuration according allowed categories for prepersons

        1. in case of error return 422 (Not allowed for prepersons)

  6. Context must be an active encounter

    1. If focus on specimens is set, then context is optional

    2. $.context.identifier.type.coding[*].system == "eHealth/resources"

    3. $.context.identifier.type.coding[*].code == "encounter"

    4. $.context.identifier.value refer to existing encounter (status == 'finished')

    5. if category = transfer_of_care,

      1. validate encounter.hospitalization.Discharge_Disposition='transfer_general', in case error return 422, "Context is not valid for service request with type $type"

  7. Occurence is a valid date-time in the future

    1. $.occurrenceDateTime

      1. $.occurrence_date_time - ISO date must be greater current date-time

    2. $.occurrencePeriod.start

      1. $.occurrence_period.start - ISO date must be greater than current date-time

      2. $.occurrence_period.end - ISO date must be greater than current date-time and greater than $.occurrencePeriod.start

    3. in case based_on passed in request

      1. if care plan activity has detail.scheduled_timing.repeat.bounds_period - validate occurence within bounds_period

      2. if care plan activity has detail.scheduled_period - validate occurence within scheduled_period

      3. else - validate occurence within care_plan.period

  8. Authored On is a valid date-time in the past

    1. $.authored_on - ISO date must be less than current date-time

  9. Requester_employee must be active employee within current legal entity

    1. $.requester_employee.identifier.type.coding[*].system == "eHealth/resources"

    2. $.requester_employee.identifier.type.coding[*].code == "employee"

    3. $.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 and employee.type=value from list of employee_types in configuration: Medical Events Dictionaries and configurations | ALLOWED_SERVICE_REQUEST_REQUESTER_EMPLOYEE_TYPES

  10. Requester is one of current user's employee

    1. in case of error return 422 "User is not allowed to create service request for the employee"

  11. Requester_legal_enity must be current legal enity

  12. Supporting info must refer to a valid medical events object (Episode of Care, Condition, Observation, Diagnostic Report, Device Request) within specified patient. 

    1. $.supporting_info.identifier.type.coding[*].system == "eHealth/resources"

      1. in case of error return 409 "Incorrect supporting info"

  13. Reason reference must refer to a valid medical events object (Observation, Condition) within specified patient. 

    1. $.reason_reference.identifier.type.coding[*].system == "eHealth/resources"

    2. $.reason_reference.identifier.type.coding[*].code in ("condition", "observation")

      1. in case of error return 409 "Incorrect reason reference"

  14. Permitted resources must refer to a valid medical events object (Episode of Care, diagnostic report) within specified patient. 

    1. $.permitted_resources.identifier.type.coding[*].system == "eHealth/resources"

    2. $.permitted_resources.identifier.type.coding[*].code == "episode_of_care"

      1. in case of error return 409 "Incorrect permitted resources"

  15. Validate expiration_date is in future

    1. in case of error return 422 "Expiration date can not be in past"

  16. Validate code is an existing service or service group that is allowed to be used in service_request
     Note. For service_request.code pass "service", "service_group"

    1. in case not found or is_active == false return 422 "Service(Service group) not found"

    2. if request_allowed==false return error 422 "Request is not allowed for this service"

    3. in case based_on passed in request

      1. If service_requests.code.identifier.value is service, validate $based_on[].activity.code.identifier.value = service_requests.code.identifier.value

        1. in case error return 409, "Service in care plan activity differ from service in service request"

      2. If service_requests.code.identifier.value is service_group, validate $based_on[].activity.code.identifier.value = service_requests.code.identifier.value

        1. in case error return 409, "Service group in care plan activity differ from service group in service request"

  17. If program was specified, validate it is an existing service program (type=service)

    1. in case not found or is_active==false return 422  "Program not found"

    2. in case type!= service return 422 "Invalid program type"

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

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

      2. check that program equal to $.activity[].program

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

  18. If program was specified, validate that service(or service_group) is an active member of the program

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

      1. if not found or is_active==false return 422 "Service is not included in the program"

      2. if request_allowed==false return 422 "Service request is not allowed for this service(service_group) in this programm"

  19. Validate performer

    1. Check whether the field should be filled in:

      1. If focus on specimens is set, then performer is optional

      2. Else, check categories:

        1. if category = transfer_of_care, then performer is required

          1. in case of error return 422 "performer is mandatory for category `transfer_of_care`"

        2. if category = laboratory_procedure, then performer is optional

        3. if any other category, then performer is forbidden

          1. in case of error return 422 “Not allowed for this category“

    2. Check performer is a Reference on legal_entity resource with status=ACTIVE and is_active=true,

      1. in case error, return 422, "performer is not active legal entity"

  20. validate LocationReference

    1. if category = transfer_of_care,

      1. 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"

      2. LocationReference division.legal_entity_id=Performer, in case error return 422, "Division does not belong to performer legal entity"

  21. Validate PerformerType

    1. if category = hospitalization

      1. PerformerType is sent, in case error return 422, "PerformerType is mandatory for category hospitalization"

      2. 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"

      3. if performer_type value is included in chart variables 'SERVICE_REQUEST_PERFORMER_TYPE_SPECIALITY_TYPES':

        1.  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“

    2. if category = transfer_of_care

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

        1. in case error return 422, "PerformerType is mandatory"

      2. 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"

      3. if performer_type value is included in chart variables 'SERVICE_REQUEST_TRANSFER_OF_CARE_PERFORMER_TYPE_SPECIALITY_TYPES':

        1.  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“

  22. Validate quantity as described at RC._PreQualify Service Request_EN

  23. Validate based_on as described at RC._PreQualify Service Request_EN

  24. If patient is person - validate verification status:

    1. If SR 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"

  25. Validate specimens as described at RC._PreQualify Service Request_EN

  26. Validate focus as described at RC._PreQualify Service Request_EN

Service logic

  1. Generate requisition number (see Human readable Service request requisition number) based on encounter id if context was set, else - based on id

  2. Save signed content to media storage

  3. Save data to corresponding collection in DB

  4. Save link to the signed content in service request storage

  5. If program was specified, change program_processing_status to New

  6. If quantity was set:

    1. Fill $.quantity.unit as description of corresponding $.quantity.code from $.quantity.system dictionary

    2. Fill $.remaining_quantity = $.quantity.

  7. If the service request is based on activity with quantity:

    1. recalculate and set remaining_quantity for the activity as described at RC._PreQualify Service Request_EN

Send SMS notification

If patient's default authentication method determined by Determination of a default authentication method and return person's active auth_methods is OTP or third_person.OTP, send SMS to that patient with requisition number

In order to optimize the costs, only one sms should be sent within one encounter. So that send sms only for the first service request for specific encounter

  1. Do NOT send sms in case performer is present

  2. Search for service requests with the same requisition number

    1. if there is at least one service request with such number - do not send sms

    2. if no service requests found - send sms to the patient 

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