Purpose

This WS is designed to Pre-qualify data of Device Request (post) - check whether it's possible to create Device request with specified parameters and within the particular Medical program.

Key points

1. Only authenticated and authorized users with appropriate scope can invoke Prequalify Device Request

2. This method simply returns the result of data validation within each submitted medical program, but not creates any entities in the system.

3. Each Medical program may have its unique conditions for the Device Request. It can be based on analysis of personal info, device definition list, terms, locations and combinations of them.

4. Any Medical program can have separate block of branching logic configured at /wiki/spaces/CSI/pages/17467605147 by NHS administrator.

5. Сompatibility is checked only for programs which are available in payload (array).

6. Successful invocation of the method returns decision for each program if it is valid or not to create Device request with submitted combination of parameters in the payload. If program is invalid, the reason must be returned in the response.

7. It is not allowed for prepersons, because dispense with program is forbidden for them

Specification

Logic

Generate structure for response

1. If general error found at Validate device request section, that doesn’t depend on medical program, then return corresponding error code with error message

2. If general validation passed, then collect array for all programs in payload with status for each (VALID or INVALID) and rejection_reason

3. Generate response according to specification

Input parameters

Request structure

See on Apiary

Example:

{
  "device_request": {
    "intent": "order",
    "code": {
      "coding": [
        {
          "system": "device_definition_classification_type",
          "code": "30221"
        }
      ]
    },
    "quantity": {
      "value": 10,
      "system": "device_unit",
      "code": "piece"
    },
    "encounter": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "encounter"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      },
      "display_value": "null"
    },
    "reason": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "condition"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        },
        "display_value": "null"
      }
    ],
    "requester": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "employee"
            }
          ]
        },
        "value": "b4a6d991-0bf7-476f-b3cf-bec83f044b1b"
      },
      "display_value": "null"
    },
    "authored_on": "2000-01-01T00:00:00.000Z",
    "occurrence_period": {
      "start": "2000-01-01T00:00:00.000Z",
      "end": "2018-08-02T11:00:00.000Z"
    }
  },
  "programs": [
    {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "medical_program"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    }
  ]
}

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 and client scopes in order to perform this action (scope = 'device_request:write')

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

Headers

• Content-Type:application/json

• Authorization:Bearer mF_9.B5f-4.1JqM

• api-key:aFBLVTZ6Z2dON1V

Request data validation

Validate legal entity

• Extract client_id from token

• Check legal entity status (status = ACTIVE)

  • In case of error - return 409 ('client_id refers to legal entity that is not active')

• Check legal entity type in ME_ALLOWED_TRANSACTIONS_LE_TYPES config parameter

  • in case of error - return 409 ('client_id refers to legal entity with type that is not allowed to create medical events transactions')

Validate Patient

• Get Patient identifier from the URL

• Check it exists in persons table (MPI)

  • Return 404 ('not found') in case of error

• Validate person status is active

  • in case of error - return 409 ('Patient is not active')

• Validate person's verification_status is not equal to NOT_VERIFIED.

  • in case NOT_VERIFIED - return error 409 ("Patient is not verified")

• Validate person is not a preperson

  • in case of error return 409 ('Forbidden to create device request for a preperson')

Validate request

Validate request using schema. Return 422 with the list of validation errors in case validation fails. In addition, check following:

Validate Device request

Invoke common validations of root attributes first that are independent of medical programs.

1. Validate requester

Validate value in the field $.requester, Reference on employee resource, required.

• Extract user_id from token. Check that requester belongs to one of the user’s employee.

  • in case of error - return 422 ('User is not allowed to create device request for the requester')

• Check requester is an active and approved employee.

  • in case of error - return 422 ('Invalid employee status')

• Check requester relates to the legal entity (client_id from token).

  • in case of error - return 422 ('Employee <id> doesn't belong to your legal entity')

• Check that requester is the same employee as encounter performer ($.requester == encounter.performer)

  • in case of error - return 422 ('Requester doesn’t match with encounter performer')

2. Validate based on

Validate values in the field $.based_on (Reference), array, optional.

• Check that $.based_on contains only one reference two values of Reference type: one is valid Care Plan resource, another - Activity resource.

  • in case of error - return 422 ('expected a minimum of %{min} items but got %{actual}')

• Validate that referenced resource is one of the following (device_request, activity, care_plan):

  • in case of error - return 422 ("value is not allowed in enum")

• Check that resource exists and belongs to the Patient ($.subject)

  • in case referenced resource is Activity - check that this Activity belongs to the Care Plan that belongs to the same patient

    • in case of error - return 422 ('Care Plan not found')

Verify Care Plan:

• It belongs to the same Patient ($.subject) as set in the Device Request

  • in case of error return 422 ('Care Plan not found')

• It is in active status

  • in case of error return 422 ('Care Plan is not active')

Verify Activity:

• Validate it exists and belongs to the Care Plan.

  • in case of error return 422 ('Activity not found')Check that activity.kind == 'device_request'

  • in case of error - return 422 ("Invalid Activity kind")

• Validate that referenced activity has the same product_codeable_concept or product_reference as current device request

  • Check that $.code == (referenced) activity.detail.codeable_concept OR

  • Check that $.code_reference == (referenced) activity.detail.product_reference

    • in case of error - return 422 ("Type in based_on activity doesn’t match with type in prescribed device request")

• Validate that referenced activity has the same program as current device request

  • Check that $.program == (referenced) activity.detail.program OR is missing on both sides

    • in case of error - return 422 ("Program in based_on activity doesn’t match with program in prescribed device request")

• Check that units of measure is the same

  • Check that $.quantity.code == activity.detail.quantity.code:

    • in case of error return 422 ("The quantity units must not differ from the quantity units in the activity")

• Check that prescribed quantity does not exceed remaining quantity

  • select all device requests based on current activity and calculate previously reserved quantity as sum of DR.quantity.value.

  • calculate reserved at the moment quantity as sum of previously reserved quantity and quantity from current DR

  • calculate remaining quantity by subtracting reserved at the moment quantity from activity's quantity

  • Check that remaining quantity is greater then or equal to zero

    1. in case of error return 422 "The number of available devices according to the care plan activity has been exhausted"

3. Validate intent

Validate value in the field $.intent, string, required.

• Check that value is in allowed active values from device_request_intent dictionary.

  • in case of error - return 422 ('value is not allowed in enum')

4. Validate code or code_reference

One and only one of $.code (CodeableConcept) and $.code_reference (Reference) must be provided

• Check that $.code or $.code_reference provided in request

  • in case of error - return 422 ('At least one of the parameters must be present')

• Check that both $.code or $.code_reference not provided at the same time

  • in case of error - return 422 ('Only one of the parameters must be present')

If $.code provided:

• Check that value is in allowed active values from device_definition_classification_type dictionary.

  • in case of error - return 422 ('value is not allowed in enum')

• Check that there is at least one active device_definition with the same type (device_definitions.classification_type)

  • device_definitions.is_active = true

    • in case of error - return 422 ('Not found any active Device Definition with classification_type '<code>')

If $.code_reference provided:

Validate value in the field $.code_reference, Reference on device_definitions resource

• Check that device definition exists and is_active

  • in case of error - return 422 ('Device definition not found')

5. Validate quantity

Validate value in the field $.quantity, SimpleQuantity type, required.

• Check that $.quantity.system is device_unit dictionary, required

  • in case of error - return 422 ('value is not allowed in enum')

• Check that $.quantity.code comply with $.quantity.system, required

  • in case of error - return 422 ('value is not allowed in enum')

• Check that $.quantity.value is integer, required

  • in case of error - return 422 ('Value should be an integer')

If $.code provided - check that there is at least one Device Definition:

• Find all active Device Definitions with the same classification_type (device_definition.classification_type = device_request.code), that has packaging_unit equal to $.quantity.code of the Device Request

  • in case of error - return 422 “Not found any active Device Definition with classification_type <$.code> and packaging_unit <$.quantity.code>”

• Check that there is at least one Device Definition where remainder of division device_request.quantity / device_definition.packaging_count is equal to zero

  • i. in case there is no such definitions - return 422 "The amount of devices in device request must be divisible to device package quantity"

If $.code_reference provided - check the referenced Device Definition:

• has packaging_unit that matches to $.quantity.code of the Device Request

  • in case of error - return 422 “Not found any active Device Definition with the same units of measure as pointed in the quantity of the Device Request”

• Check that Device Definition has a remainder of division device_request.quantity / device_definition.packaging_count that is equal to zero

  • i. in case there is no such definitions - return 422 "The amount of devices in device request must be divisible to device package quantity"

6. Validate encounter

Validate value in the field $.encounter, Reference on encounter resource, required

• Validate that entity is not in status "entered_in_error"

  • in case of error - return 422 ("Entity in status "entered_in_error" can not be referenced")

• Validate diagnosis in the encounter is not empty

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

• Check that encounter belongs to the patient ($.subject)

  • in case of error - return 422 ('Encounter with such id is not found')

• Check that encounter created in the same legal entity as the requester

  • in case of error - return 422 ('Encounter was not created at the requester’s legal entity ')

7. Validate authored on

Validate value in the field $.authored_on, datetime type, required

• Check current date >= authored_on >= (current date - DEVICE_REQUEST_DELAY_INPUT)

  • in case of error - return 422 “Authored on date must be in range of <current date> and <current date - DEVICE_REQUEST_DELAY_INPUT>”

• Check authored_on comply with the encounter period

  • check $.authored_on >= $.encounter.period.start and $.authored_on <= $.encounter.period.end

    • in case of error - return 422 ('Authored on date must be in between of Encounter period start and end')

8. Validate occurrence

Validate value in the field $.occurrence_period, Period type, required.

• Check ($.authored_on + DEVICE_REQUEST_EXTENDED_LIMIT_START_DAYS) >= $.occurrence_period.start >= $.authored_on

  • in case of error - return 422 error ('Start date must be greater than or equal to <authored_on> date, but less than or equal to <authoredOn + DEVICE_REQUEST_EXTENDED_LIMIT_START_DAYS> date')

• Check $occurrence_period.end >= $.occurrence_period.start

  • in case of error - return 422 error ('Occurrence end date must be greater than or equal to start date')

• In case based_on passed in request and activity referenced - check that this occurrence period matches with care plan occurrence period:

  • Get care plan that relates to referenced activity

  • if care plan activity has detail.scheduled_timing.repeat.bounds_period - validate occurrence within bounds_period

    • in case of error - return 422 error ('The occurrence period must be within the activity scheduled timing bounds period')

  • if care plan activity has detail.scheduled_period - validate occurrence within scheduled_period

    • in case of error - return 422 error ('The occurrence period must be within the activity scheduled period')

  • else - validate occurrence within care_plan.period

    • in case of error - return 422 error ('The occurrence period must be within the activity care plan period')

9. Validate reason

Validate value in the field $.reason, optional.

• Check that reason is an array with References on (condition, diagnostic_report, observation) resource

  • in case of error - return 422 ('value is not allowed in enum')

• Check that each {resource} belongs to the patient ($.subject)

  • in case of error - return 422 ('{resource} with such id is not found')

• Check that status of each {resource} is not "entered_in_error" (for condition verification status should be used)

  • in case of error - return 422 ("{resource} in status "entered_in_error" can not be referenced")

10. Validate Medical programs

If all checks below in the text passed for the program - save the response for this program with status = VALID; if not passed - save response with status = INVALID and corresponding reject_reason. Response for such validations should be returned with code 200.

Validate each medical program in the $.programs array:

• Check the program exists and is active

  • in case of error - return reject_reason = “Medical program not found”

• Check the program is of type DEVICE

  • in case of error - return reject_reason = “Invalid program type”

• Check request_allowed = true for the program

  • in case of error - return reject_reason = “It is not allowed to create Device requests for the program”

• Check there is at least one appropriate participant for a program:

  • Find program_devices, that:

    • is active

    • has device_request_allowed=true

    • its validity period (start_date and end_date) includes current date

    • max_daily_count >= $.quantity.value/(occurence_period.end - occurence_period.start+1)

    • relates to the Device Definition found at the 5. Validate quantity step

      • in case not found - return reject_reason = “No appropriate participants found for this medical program“

• Make validation according to medical program settings:

  • If skip_employee_validation = false (null/absent), then $.requester should be validated:

    • If employee_types_to_create_request parameter is set, then check if it contains employee type of the requester

      • in case is not found - return reject_reason = “Employee type of the requester doesn't allow to create Device Request with the medical program”

    • In case employee type of the requester is SPECIALIST, then additional validations may be performed:

      • If speciality_types_allowed is set, then check if it contains speciality of the requester (speciality_officio=true):

        • in case is not found - return reject_reason = "Employee's specialty of the requester doesn't allow to create Device Request with the medical program"

    • In case employee type of the requester is DOCTOR, then additional validations may be performed:

      • if skip_request_employee_declaration_verify = false (null/absent), then get declaration by employee_id of the requester, person_id and status=ACTIVE

        • in case is not found - return reject_reason = "Only doctors with an active declaration with the patient can create Device Request with the medical program"

      • if skip_request_legal_entity_declaration_verify = false (null/absent), then get declaration by requester's legal_entity_id, person_id and status=ACTIVE

        • in case is not found - return reject_reason = "Only legal entity with an active declaration with the patient can create Device Request with the medical program"

  • If conditions_icd10_am_allowed is set and $.encounter has primary diagnosis code from the eHealth/ICD10_AM/condition_codes dictionary, then check this code is in the conditions_icd10_am_allowed parameter

    • in case is not found - return reject_reason = "Encounter in the request has no primary diagnosis allowed for the medical program”

  • If conditions_icpc2_allowed is set and $.encounter has primary diagnosis code from the eHealth/ICD10_AM/condition_codes dictionary, then check this code is in the conditions_icpc2_allowed parameter

    • in case is not found - return reject_reason = "Encounter in the request has no primary diagnosis allowed for the medical program”

  • If skip_treatment_period = false (null/absent), then:

    • Get all active/completed Device Requests with $.code or $.code_reference (depending on attribute provided in request), $.medical_program_id, $person_id

    • If such was found, get the Device Request with the latest occurrence_period.end date and check:

      • its occurrence_period.end less then $.occurrence_period.start from the request

        • in case of error - return reject_reason = ”It can be only one active / completed Device Request for the same code and patient at the same period of time”

      • if its occurrence_period.end greater than or equal to current date, then in addition check:

        • If occurrence_period of found Device Request is greater than or equal to DEVICE_REQUEST_STANDARD_DURATION, then $.authored_on from the request should be greater then (occurrence_period.ended at - DEVICE_REQUEST_MAX_RENEW_DAYS) of the found Device Request

        • else $.authored_on from the request should be greater then (occurrence_period.ended at - DEVICE_REQUEST_MIN_RENEW_DAYS)

          • in case of error - return reject_reason = “It's to early to create new Device Request for such code and medical program”

  • If request_max_period_day is set, then check if it is not exceeded by the number of days in the $.occurrence_period of the request

    • if exceeded - return reject_reason = “Occurrence period length exceeds allowed value for the medical program“

  • if there is parameter device_request_allowed_code_types, then check values in the array:

    • if it includes CLASSIFICATION_TYPE - it is allowed to pass $.code in the request

    • if it includes DEVICE_DEFINITION - it is allowed to pass $.code_reference in the request

      • in case of a mismatch between the filled field and the config values - return 422 ("<Device definition/Device classification type> is not allowed to set for this medical program").

  • If care_plan_required = true, then:

    • Reference to activity in $.based_on is required

      • in case of error - return reject_reason = “Activity with the same program should be present in request”

11. Validate priority

Validate value in the field $.priority, string, optional.

• Check that value is in allowed active values from device_request_priority dictionary.

  • in case of error - return 422 ('value is not allowed in enum')

12. Validate supporting info

Validate values in the field $.supporting_info, array, optional. Validate each value with the following rules:

• Validate that referenced resource is one of the following (diagnostic_report, observation, condition, procedure, encounter, episode, device, device_association)

  • in case of error - return 422 ("Referenced resource in supporting_info is not allowed")

• Validate that entity is not in status "entered_in_error"

  • in case of error - return 422 ("Entity in status "entered_in_error" can not be referenced")

• Check that resource belongs to the patient ($.subject)

  • in case of error - return 422 ('Referenced resource not found')

13. Validate performer

Validate value in the field $.performer, Reference, optional.

• Validate that referenced resource is legal_entity and record with such id exists (is_active = true):

  • in case of error - return 422 ("LegalEntity with such ID is not found")

• Validate that entity status is "ACTIVE" or “SUSPENDED“

  • in case of error - return 422 ("Legal entity referenced as performer is in invalid status")

14. Validate parameter

Validate values in the field $.parameter, array, optional. Validate each value with the following rules:

• Check that value from $.parameter.code is in allowed active values from device_request_code_parameter dictionary.

  • in case of error - return 422 ('value is not allowed in enum')

• Check $.parameter.value[x] is one of the following: value_codeable_concept, value_quantity, value_boolean, value_range, value_string

  • in case of value[x] is missing - return 422 ('At least one of the parameters must be present')

  • in case of more than one value[x] provided - return 422 ('Only one of the parameters must be present')

  • in case of value[x] is provided with incorrect type - return 422 ('type mismatch. Expected [x] but got <type>')

Response structure

See on Apiary

Example:

{
  "meta": {
    "code": 200,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": [
    {
      "program_id": "59781de0-2e64-4359-b716-bcc05a32c10f",
      "program_name": "Доступні медичні вироби",
      "status": "INVALID",
      "rejection_reason": "No appropriate participants found for this medical program"
    }
  ]
}

{
  "meta": {
    "code": "422",
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "error": {
    "type": "unverified",
    "message": "Patient is not active"
  }
}

HTTP status codes