Purpose

This WS is designed to create Device Request

Key points

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

2. Device Request is created in async way. Successful result of the job should return a link on the created Device Request (look at https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782015159).

3. Device Request should be signed with DS. Signed content stores in the media storage.

4. All validations within Device request attributes should be executed by internal call of https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014958 function

5. Device Request can be created for a person only

6. Medical program is optional in the Device Request

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 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)

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

Validate digital signature

1. Validate request is signed

   1. in case of error - return 400 (“Invalid signed content”)

2. Check DS is valid and not expired

3. Validate that DS belongs to the requester

   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 Patient

Execute validation as described here

RС_[UPD] PreQualify Device request | Validate Patientarchived

Skip the following validation in case madical_program is not specified in the request

Validate request

Validate request using schema.

1. Validate requester

Execute validation as described here

RС_[UPD] PreQualify Device request | 1. Validate requesterarchived

2. Validate based on

Execute validation as described here

RС_[UPD] PreQualify Device request | 2. Validate based onarchived

3. Validate intent

Execute validation as described here

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014958#3.-Validate-intent

4. Validate code or code_reference

Execute validation as described here

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014958#4.-Validate-code-or-code_reference

Skip the following validation in case madical_program is not specified in the request

5. Validate quantity

If quantity provided in request - execute validation as described here

RС_[UPD] PreQualify Device request | 5. Validate quantityarchived

• 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')

6. Validate encounter

Execute validation as described here

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014958#6.-Validate-encounter

7. Validate authored on

Execute validation as described here

RС_[UPD] PreQualify Device request | 7. Validate authored onarchived

8. Validate occurrence

Execute validation as described here

RС_[UPD] PreQualify Device request | 8. Validate occurrencearchived

9. Validate reason

Execute validation as described here

RС_[UPD] PreQualify Device request | 9. Validate reasonarchived

10. Validate Package unit and quantity

Execute validation as described here

RС_[UPD] PreQualify Device request | 10. Validate Package unit and quantityarchived

11. Validate Medical program

Execute validation as described here

RС_[UPD] PreQualify Device request | 11. Validate Medical programsarchived

12. Validate priority

Execute validation as described here

RС_[UPD] PreQualify Device request | 12. Validate priorityarchived

13. Validate supporting info

Execute validation as described here

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014958#13.-Validate-supporting-info

14. Validate performer

Execute validation as described here

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014958#14.-Validate-performer

15. Validate parameter

Execute validation as described here

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014958#15.-Validate-parameter

Validate status

The target status value must be submitted in the order of display in the signed content (media storage)

1. Validate $.status is active

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

Service logic

1. Save signed content to media storage, in bucket pointed in MEDIA_STORAGE_DEVICE_REQUEST_BUCKET chart parameter

2. Fill in the following fields:

   1. requisition. Generate requisition number as described at https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/583405396, but based on the Device Request identifier and put it in the field.

   2. signed_content_links. Add string item in the array with a link on saved content in media storage

   3. status = ACTIVE

   4. status_reason = null

   5. subject. Set hashed patient_id from URL

   6. requester_legal_entity. Set client_id from token

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

   8. dispense_valid_to. dispense_valid_to. Set (current_date + dispense_period_day) if medical program was set and it has dispense_period_day setting. Otherwise, if medical program was set and it has NO dispense_period_day setting, set the value using device_dispense_period global parameter. Else, if medical program was NOT set dispense_valid_to = null.

      1. Save dispense_valid_to as datetime but truncate time to beginning of date (2013-08-02T00:00:00Z)

   9. verification_code. Generate random 4-digit code if medical program was set

   10. context_episode_id. Set episode from the $.encounter

   11. context_care_plan_id. Get Activity from $.based_on, set activity.care_plan as context_care_plan_id

   12. based_on. Set based_on from the $.based_on

   13. priority. Set priority from the $.priority

   14. parameter. Set parameter from the $.parameter

   15. performer. Set performer from the $.performer

   16. supporting_info. Set supporting_info from the $.supporting_info

   17. inserted_at. Set current date and time

   18. updated_at. Set current date and time

   19. inserted_by. Set current user from token

   20. updated_by. Set current user from token

3. Send notification to patient:

   1. Determine patient's default authentication method as described at Determination of a default authentication method and return person's active auth_methods

   2. Get program from request and (if provided) get program setting request_notification_disabled:

      1. if program provided and request_notification_disabled == true:

         1. do not send SMS notification to patient

      2. if program provided and request_notification_disabled == false and OTP defined on patient:

         1. generate text according to CREATE_DEVICE_REQUEST_SMS_TEMPLATE and send SMS with verification_code

      3. if program not provided and OTP defined on patient:

         1. check config parameter DEVICE_REQUESTS_SMS_ENABLED is set to true

            1. generate text according to CREATE_DEVICE_REQUEST_SMS_TEMPLATE_WITHOUT_CODE and send SMS without verification_code

4. Save data to device_requests collection in MongoDB according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014841

5. If device request is based on activity - recalculate and set remaining_quantity for the activity

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

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

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

   4. Update activity set remaining quantity (activity.detail.remaining_quantity)

6. Send StatusChangeEvent to Event Manager