Purpose

This WS is designed to complete Device Dispense

Key points

1. Only authenticated and authorized users with appropriate scope can invoke Complete Device Dispense

2. Device Dispense is completed in async way. Successful result of the job should return a link to the existing Device Dispense (look at [UPD] Get Device dispense details)

3. Complete request must be signed with Digital Signature. So, all the Device dispense data must be signed and submitted.

4. The method is used only for Device requests with the medical program.

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 = 'device_dispense:complete')

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

Validations

Validate digital signature

• Validate request is signed

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

• Validate that DS is valid and not expired

• Validate that DS belongs to the user

  • Check that DRFO from DS and party.tax_id matches

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

Validate legal entity

• Extract client_id from token

• Check legal entity status is ACTIVE

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

Validate Device dispense

• Get Device dispense identifier from the URL

  • Check Device dispense exists in DB (ME DB)

    • in case of error - Return 404 ('not_found')

  • Check Device dispense belongs to the same legal entity

    • in case of error - Return 404 ('not_found')

• Validate payment_amount

  • Check it is present if program was set

    • in case of error - Return 422 (Required property payment_amount was not present)

• Validate when_handed_over

  • Check that when_handed_over is in period specified in Device request (when_handed_over = current_date() and when_handed_over <= device_request.dispense_valid_to)

    • in case of error - return 409 error ('Invalid dispense period')

• Validate status

  • As target status value must be submitted in the order of display in the signed content, check $.status is completed

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

Validate Device request

Validate value in the field $.based_on ($.based_on.identifier.value), Reference on device request, required.

• Сheck that Device request is_active = true and status == 'ACTIVE'

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

Validate related Care plan

Verify care plan Activity as described in https://e-health-ua.atlassian.net/wiki/spaces/RMDN/pages/17670996847/UPD+Qualify+Device+request#Validate-related-Care-plan

Validate User

• Extract user_id from token

• Check that device dispense is completed by the same user who created it

  • User from token must match with device_dispense.inserted_by

    • in case of error - Return 409 ('Employee is not an author of device dispense')

Validate signed content

• Check that signed content is equal to device dispense stored in DB

  • Do not compare:

    • payment_amount field

    • payment_id field

    • status

    • when_handed_over

• in case error return 422 ("Signed content does not match to previously created dispense")

Validate transition

• Get status of Device dispense by $.id in ME DB. Check that Device dispense is in status ‘IN_PROGRESS’

  • in case of error - return 409 ("Can't update device dispense status from {status} to COMPLETED")

For more information look at [UPD] Device dispense status model

Service logic

• Save signed content to media storage, in bucket pointed in MEDIA_STORAGE_DEVICE_DISPENSE_BUCKET chart parameter

• Fill in the following fields:

  • signed_content_links. Add string item in the array with a link(s) to saved content in media storage

  • status = COMPLETED

  • updated_at. Set current date and time

  • updated_by. Set current user from token

• If Device request has quantity:

  • Save (update) data to device_requests collection in MongoDB according to [UPD] Device dispense data model: set device_requests.status = COMPLETED (as all its quantity has been provided by Device dispense)

  • If related Device request has a reference on an Activity as device_request.based_on, then

    • add the 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

• Send StatusChangeEvent to Event Manager for Device Dispense and related Device Request