Purpose

This WS is designed to create Device Request

This method allows to create Device Request for a person (or preperson) in eHealth. Method receives signed message (pkcs7) that consists of signed content, digital signature and signer public key. All signature fields will be validated (including signer certificate authority). Service will store signed copy of Device Request in Media Content Storage if all checks is passed.

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/CSI/pages/17467310277/Get+Device+request+details ).

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 PreQualify Device request /wiki/spaces/CSI/pages/17467474119 function

5. Device Request can be created for a person only

6. Medical program is optional in the Device Request

Specification

...

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 Human readable Medication request number , 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. Set (current_date + dispense_period_day) if medical program was set and it has dispense_period_day setting. Otherwise, set the value using device_dispense_period global parameter.

   9. verification_code. Generate random 4-digit code

   10. context_episode_id. Set episode from the $.encounter

   11. inserted_at. Set current date and time

   12. updated_at. Set current date and time

   13. inserted_by. Set current user from token

   14. updated_by. Set current user from token

3. Send verification code:

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

      1. if OTP defined, then generate text according to TEMPLATE_SMS_FOR_CREATE_DEVICE_REQUEST and send SMS with verification_code

4. Save data to device_requests collection in MongoDB according to /wiki/spaces/CSI/pages/17467375685

5. Send StatusChangeEvent to Event Manager

Input parameters

Request structure

See on Apiary

Example:

{
  "signed_data": "ew0KICAicGVyaW9kIjogew0KIC..."
}

Authorize

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

Headers

• Content-Type:application/json

• Authorization:Bearer mF_9.B5f-4.1JqM

• api-key:aFBLVTZ6Z2dON1V

Request data validation

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”“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““Signer DRFO doesn't match with requester tax_id“)

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

• 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) and has status active

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

  Validate person status is active

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

  Validate person'sverification_status is not equal to NOT_VERIFIED.

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

• Validate person isnot a preperson

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

Validate request

Validate request using schema.

• Invoke validations described at https://e-health-ua.atlassian.net/wiki/spaces/CSI/pages/17467474119/PreQualify+Device+request#Validate-Device-request

• If Device Request has a medical program, then in addition execute validations described at https://e-health-ua.atlassian.net/wiki/spaces/CSI/pages/17467474119/PreQualify+Device+request#Validate-Medical-programs

Service logic

...

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

...

Fill in the following fields:

1. requisition. Generate requisition number as described at Human readable Medication request number , 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. Set (current_date + dispense_period_day) if medical program was set and it has dispense_period_day setting. Otherwise, set device_dispense_period global parameter.

9. verification_code. Generate random 4-digit code

10. context_episode_id. Set episode from the $.encounter

11. inserted_at. Set current date and time

12. updated_at. Set current date and time

13. inserted_by. Set current user from token

14. updated_by. Set current user from token

...

Send verification code:

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

   1. if OTP defined, then generate text according to TEMPLATE_SMS_FOR_CREATE_DEVICE_REQUEST and send SMS with verification_code

   2. if OFFLINE defined - return verification_code in the urgent block of the response (if Create was processed synchronously).

...

Save data to device_requests collection in MongoDB according to Device request data model

...

• . Also, quantity is required in this case

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

Response structure

See on Apiary

Example:

{
  "data": {
    "status": "pending",
    "eta": "2018-08-02T10:45:16.000Z",
    "links": [
      {
        "entity": "job",
        "href": "/Jobs/NBXk9EyErUZv1RhXgyvgg"
      }
    ]
  },
  "meta": {
    "code": 202,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  }
}

HTTP status codes