Overview

This API method is designed to create Device Dispense via Trembita.

Key points

1. This web service works asynchronously

2. This web service is designed for integration with Trembita

Request

URL: min_sp/device_dispenses

Method: POST

Headers

Body

device_detail

Validations

Validate headers

1. Check that header Uxp-Client exists and is not empty

   1. in case of error - generate response with code 400:

      • $Response.error.type = “bad_request“

      • $Response.error.code = “1008”

      • $Response.error.message = “Missed Uxp-Client header”

2. Check that header Uxp-Service exists and is not empty

   1. in case of error - generate response with code 400:

      • $Response.error.type = “bad_request“

      • $Response.error.code = “1009”

      • $Response.error.message = “Missed Uxp-Service header”

3. Check that header Uxp-Transaction-Id exists and is not empty

   1. in case of error - generate response with code 400:

      • $Response.error.type = “bad_request“

      • $Response.error.code = “1010”

      • $Response.error.message = “Missed Uxp-Transaction-Id header”

4. Check that header Uxp-Client contains 4 strings that are separated by / symbol

   1. in case of error - generate response with code 400:

      • $Response.error.type = “bad_request“

      • $Response.error.code = “1011”

      • $Response.error.message = “Invalid Uxp-Client format”

5. Check that header Uxp-Service contains 4 or 5 strings that are separated by / symbol

   1. in case of error - generate response with code 400:

      • $Response.error.type = “bad_request“

      • $Response.error.code = “1012”

      • $Response.error.message = “Invalid Uxp-Service format”

Validate JSON Schema

1. Validate request according to JSON Schema (validate status= preperation or completed, primary_source =true, sell_price and payment_amount are greater than 0(if present))

   1. in case of errors generate response with code 422

      1. $Response.error.type = “validation_failed“

      2. $Response.error.code = “1013” “0000013”

      3. $Response.error.message = Request structure error”

      4. $Response.error.invalid = {{json_schema_errors}}

Validate request structure

1. Validate id

   • Check there is no Device Dispense with the same ID for this patient in the DB

     • in case Device Request not found update job with code 409:

       • $Response.error.type = “conflict“

       • $Response.error.code = “1021” “0050021”

       • $Response.error.message = “Device Dispense with id <id> already exists”

2. Validate based_on

   1. Search for Device Request where id=$.based_on, patient_id =$.subject, status=active

      1. in case Device Request not found update job with code 422:

         • $Response.error.type = “validation_failed“

         • $Response.error.code = “1019” “0050019”

         • $Response.error.message = “Device Request not found”

   2. Check that device_request.intent is order

      1. in case of error update job with code 409:

         • $Response.error.type = “conflict“

         • $Response.error.code = “1022” “0050022”

         • $Response.error.message = “Only device request with intent = 'order' can be dispensed”

   3. If device_code is present in the request check that device code in the Device Dispense is compliant with prescribed device code:

      • Check device_request.code_reference is not present in the Device Request

        • in case of error update job with code 409:

          • $Response.error.type = “conflict“

          • $Response.error.code = “1023” “0050023”

          • $Response.error.message = “Dispense with device code is not allowed, since prescription is for device or device definition”

      • Check device_request.code is equal to device_dispense.detail.device_code

        • in case of error update job with code 409:

          • $Response.error.type = “conflict“

          • $Response.error.code = “1024” “0050024”

          • $Response.error.message = “Dispensed device code doesn’t match with prescribed device code”

      • If device_reference is present in the request check that device reference in the Device Dispense is compliant with prescribed device reference:

        • Check device_request.code is not present in the Device Request

          • in case of error update job with code 409:

            • $Response.error.type = “conflict“

            • $Response.error.code = “1036” “0050036”

            • $Response.error.message = “Dispense with device reference is not allowed, since prescription is for device code”

        • Check device_request.code_reference is equal to device_dispense.detail.device_reference

          • in case of error update job with code 409:

            • $Response.error.type = “conflict“

            • $Response.error.code = “1037” “0050037”

            • $Response.error.message = “Dispensed device reference doesn’t match with prescribed device reference”

        • Check that Device Definition referenced in device_dispense.detail.device_reference is active

          • in case of error update job with code 409:

            • $Response.error.type = “conflict“

            • $Response.error.code = “1038” “0050038”

            • $Response.error.message = “Device Definition is not active”

   4. Check that device_dispense.details.quantity.code matches with device_request.quantity.code(in case device_request.quantity not null)

      • in case of error update job with code 409:

        • $Response.error.type = “conflict“

        • $Response.error.code = “1025” “0050025”

        • $Response.error.message = “Dispensed packaging unit doesn’t match with prescribed packaging unit”

   5. Check that dispensed device quantity is equal or less then remaining_quantity in the Device Request(in case device_request.quantity not null) :

      • Select all Device Dispenses with following parameters:

        • based_on is current Device Request

        • status = completed, preparation

      • Sum quantity in the filtered Device Dispenses as dispensed_quantity

      • Calculate remaining_quantity = requested_quantity- dispensed_quantity

      • Check that remaining_quantity is greater or equal to device_dispense.details.quantity

        • in case of error update job with code 409:

          • $Response.error.type = “conflict“

          • $Response.error.code = “1026” “0050026”

          • $Response.error.message = “Dispensed quantity must be equal or less then prescribed remaining quantity in Device Request”

   6. Validate Activity and Care Plan (if present in device_request.based_on):

      • Verify care plan Activity from $.based_on where coding.code=activity:

        1. Check Activity status is scheduled or in_progress

           1. in case of error update job with code 409:

           2. $Response.error.type = “conflict“

           3. $Response.error.code = “1027” “0050027”

           4. $Response.error.message = “Invalid Activity status” 

      • Verify Care Plan from $.based_on where coding.code=care_plan:

        1. Check Care Plan status is active

           1. in case of error update job with code 409:

           2. $Response.error.type = “conflict“

           3. $Response.error.code = “1028” “0050028”

           4. $Response.error.message = “Invalid Care Plan status” 

        2. Check care_plan.period.end(if exist) greater or equal to current date

           1. in case of error update job with code 409:

           2. $Response.error.type = “conflict“

           3. $Response.error.code = “1029” “0050029”

           4. $Response.error.message = “Care Plan expired” 

3. Validate subject verification status

   1. Search for Person's merged person

      1. in case empty response returned or person is a master person check person verification status is not equal to NOT_VERIFIED

         1. in case of error update job with code 409:

            1. $Response.error.type = “conflict“

            2. $Response.error.code = “1030” “0050030”

            3. $Response.error.message = “Person is not verified” 

      2. else, in case person is a merged person, validate master person verification status is not equal to NOT_VERIFIED

         1. in case of error update job with code 409:

            1. $Response.error.type = “conflict“

            2. $Response.error.code = “1030” “0050030”

            3. $Response.error.message = “Person is not verified” 

4. Validate external_provider

   1. Check external_provider.provider_legal_entity_edrpou mathes with one of following regexp:
      ([0-9]{8,10}|[А-ЯЁЇIЄҐ]{2}\d{6})
      ([0-9]{9,10}|[А-ЯЁЇIЄҐ]{2}\d{6})

      1. in case of error update job with code 422:

         • $Response.error.type = “validation_failed“

         • $Response.error.code = “1031” “0050031”

         • $Response.error.message = “Invalid provider_legal_entity_edrpou format”

5. In case $.status = preparation

   1. Check that when_handed_over, sell_price, payment_amount is NOT present

      1. in case of error update job with code 422:

         1. $Response.error.type = “validation_failed“

         2. $Response.error.code = “1032” “0050032”

         3. $Response.error.message = “Parameters when_handed_over, sell_price, payment_amount are not allowed for Device Dispense in status preparation”

   2. Check that details.device_code is present

      1. in case of error update job with code 422:

         1. $Response.error.type = “validation_failed“

         2. $Response.error.code = “1035” “0050035”

         3. $Response.error.message = “Parameter device_code is required for Device Dispense in status preparation”

      2. Check that primary_source is true

         1. in case of error update job with code 422:

            1. $Response.error.type = “validation_failed“

            2. $Response.error.code = “1040” “0050040”

            3. $Response.error.message = “Parameter primary_source must be set in true for Device Dispense in status preparation”

6. In case $.status = completed

   1. Check that when_handed_over is present

      1. in case of error update job with code 422:

         1. $Response.error.type = “validation_failed“

         2. $Response.error.code = “1033” “0050033”

         3. $Response.error.message = “Parameters when_handed_over is required for Device Dispense in status completed ”

   2. check that when_handed_over is greater or equal to device_request.authored_on and less or equal to current date

      1. in case of error update job with code 422:

         1. $Response.error.type = “validation_failed“

         2. $Response.error.code = “1034” “0050034”

         3. $Response.error.message = “Invalid dispense period”

7. In case $.primary_source= false check that $.report_origin is present

   1. in case of error update job with code 422:

      1. $Response.error.type = “validation_failed“

      2. $Response.error.code = “1039” “0050039”

      3. $Response.error.message = “Parameter report_origin is required when primary_source is false”

Service logic

1. Parse Uxp-Client header using pattern <client_instance>/<client_member_class>/<client_member_code>/<client_subsystem_code>

2. Parse Uxp-Service header using patter <service_instance>/<service_member_class>/<service_member_code>/<service_subsystem_code>/<service_service_code>[/<service_service_version>]

   1. <service_service_version> - optional parameter

3. Save parsed headers (Uxp-Client, Uxp-Service, Uxp-transaction-Id), request body, response body, job_id to Trembita Integration Layer

4. Save data to device_dispenses collection in MongoDB according to https://e-health-ua.atlassian.net/wiki/spaces/REHABILIT/pages/18430755049/UPD+Device+dispense+data+model

   1. inserted_at = {{current_date_time}}

   2. updated_at = {{current_date_time}}

   3. inserted_by = {{trembita_user_id}}

   4. updated_by = {{trembita_user_id}}

   5. external_performer = {{client_member_code}}(from Uxp-Client header)

   6. origin_episode_id = device request.context_episode_id (from based_on)

   7. details.quantity.unit. Set description according to quantity code and system

5. If Device Dispenses status is changed to completed and related Device Request has a reference on Activity as device_request.based_on, then

   • add reference on the Device Dispense resource to the outcome_reference attribute of the related Activity

   • if Activity.status is scheduled change it to in_progress

6. If Device Dispenses status is changed to completed and there is quantity specified in the Device Request:

   1. calculate remaining_quantity of the related Device Request:

      1. Select all Device Dispenses with following parameters:

         • based_on is current Device Request

         • status = completed

      2. Sum quantity in the filtered Device Dispenses as dispensed_qty

      3. Calculate remaining_quantity = device_request.quantity- dispensed_quantity

   2. If remaining_quantity is equal to device_dispense.details.quantity, change status of the related Device Request($.based_on) to completed

7. Send StatusChangeEvent to Event Manager

8. Update job

Response

Response structure

Job

link

Error codes