Purpose

This WS is designed to create equipment in the system

Specification

Logic

1. Only authenticated and authorized HR, ADMIN, OWNER employees can register equipments.

2. Equipments can be registered in MSP, OUTPATIENT, PRIMARY_CARE and EMERGENCY legal entities.

3. Equipment has to be linked to division. One division can have many equipments.

4. Legal entity can register equipments for its own divisions only.

5. Save equipment record to the prm.equipments table (see RC_[NEW] Equipment status modelarchived) with the following:

   1. id = generate uuid

   2. inventory_number = $.inventory_number

   3. serial_number = $.serial_number

   4. device_definition_id = $.device_definition_id

   5. status = $.status

   6. error_reason = null

   7. availability_status = $.availability_status

   8. manufacturer = $.manufacturer

   9. manufacture_date = $.manufacture_date

   10. model_number = $.model_number

   11. type = $.type

   12. properties = $.properties

   13. legal_entity_id = $.token.client_id

   14. division_id = $.division_id

   15. note = $.note

   16. parent_id = $.parent_id

   17. lot_number = $.lot_number

   18. expiration_date = $.expiration_date

   19. udi = $.udi

   20. is_active = true

   21. recorder = $.recorder

   22. inserted_at = current datetime

   23. inserted_by = user_id from token

   24. updated_at = current datetime

   25. updated_by = user_id from token

6. Insert each name from $.names into prm.equipment_names with the following:

   1. id = generate uuid

   2. equipment_id = reference to equipment

   3. type = $.names.type

   4. name = $.names.name

   5. inserted_at = current datetime

   6. inserted_by = user_id from token

   7. updated_at = current datetime

   8. updated_by = user_id from token

Request structure

Example:

Authorize

1. Verify the validity of access token

   1. Return (401, 'Invalid access token') in case 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 = 'equipment:write')

   1. Return (403 'Your scope does not allow to access this resource. Missing allowances: equipment:write') in case 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):

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

   • in case of error - return 403 ("Access denied. Party is deceased")

Headers

Наприклад:

Content-Type:application/json

Authorization:Bearer c2778f3064753ea70de870a53795f5c9

API-key:uXhEczJ56adsfh3Ri9SUkc4en

Request data validation

Validate legal entity

Check that legal entity is active (status = ACTIVE, SUSPENDED)

1. Extract client_id from token (token.client_id == legal_entity_id)

2. Check that legal_entity exists and is_active = true

   • in case of error - return 409 ("Legal entity not found")

3. Check legal entity status (status = ACTIVE, SUSPENDED)

   1. In case of error - return 409 ('client_id refers to legal entity that is not active') (Legal entity must be ACTIVE or SUSPENDED)

Validate request

Validate request using schema. Return 422 with the list of validation errors in case validation fails.

1. Type

Validate value in the field $.type, required.

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

1. Validate that an equipments type value exists in dictionary "EQUIPMENT_TYPE"

   1. in case of error "Submitted code is not allowed for this field"

2. Division

A division_id should be passed in request body:

Validate $.division_id. Division referenced in request must be active and belongs to the same legal entity as user

1. Get division by $.division_id Validate division_id in request body - division exists and is_active = true

   1. Return 422 in case validation fails

2. Check that division exists and is_active = true

   • in case of error - return 409 ("Division not found")

3. Check division status =ACTIVE.

   1. Return 422 with message "Division is not active" in case validation fails.

4. Check division_id belongs to the same  legal entity legal_entity_id (from token) as user (prm.division.legal_entity_id = token.client_id)

   1. in case of error return 409 "User is not allowed to create devices for this division" Return 422 with message  "Division is not within current legal entity" in case validation fails.

Validate external identifier 

1. Check an external_id field is not empty

   1. Return 422 (required property external_id was not present) in case of error

3. Parent

Validate $.parent_id. Equipment (device) referenced in request must be active and belongs to the same legal entity as user

• Get equipment by $.parent_id

• Check that parent equipment exists and is_active = true

  • in case of error - return 409 ("Parent equipment not found")

• prm.equipments.status = "active"

  • in case of error return 409 "Referenced parent equipment is not active" 

• prm.equipments.legal_entity_id = token.client_id

  • in case of error return 409 "Referenced parent equipment belongs to another legal entity"

4. Device definition

Validate $.device_definition_id if passed. Device definition referenced in request must be active and has the same type as equipment

• Get device definition by $.device_definition_id

• Check that device definition exists

  • in case of error - return 409 ("Device definition not found")

• prm.device_definitions.is_active = True

  • in case of error return 409 "Device definition not found" 

• prm.device_definitions.type = $.type

  • in case of error return 409 "Referenced device definition must be of the same type as equipment"

5. Serial number

Serial number is required for some types of equipment

• Get value from configuration parameter (EQUIPMENT_TYPES_WITH_REQUIRED_SERIAL_NUMBER)

• If $.type is in list then $.serial_number is required

  • in case of error return 422 "Serial number is required for this type of equipment"

6. Status

Only active device can be created

• Check that $.status == 'active'

  • in case of error - return 422 ('Status must be active')

7. Availability status

Only available device can be created

• Check that $.availability_status == 'available'

  • in case of error - return 422 ('Availability status must be available')

8. Manufacture date

Validate $.manufacture_date if passed. Manufacture date must be in the past

• $.manufacture_date <= current_date

  • in case of error return 422 "Manufacture date must be equal to or earlier than current date"

9. Validate properties

Check that each property is valid within device_properties dictionary. Some properties correspond to specific dictionaries and their values are valid

• Check that $.properties.type is in allowed values from device_properties dictionary.

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

• Check $.properties.value[x] is one of the following: value_integer, value_decimal, value_boolean, value_string

  • in case of value[x] is missing - return 422 ('One and only one key is allowed from the list: [value_integer, value_decimal, value_boolean, value_string], but the following are present: [].')

  • in case of more than one value[x] provided - return 422 ('One and only one key is allowed from the list: [value_integer, value_decimal, value_boolean, value_string], but the following are present: [value[x], value[x], …].')

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

• Check config DEVICE_PROPERTY_DICTIONARIES - if device property is associated with dictionary in this configuration parameter

  • only value_string is allowed for this property

    • in case of error - return 422 ('Only value_string is allowed for dictionary values')

  • check that value_string is one of the corresponding dictionary for this property

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

10. Validate inventory number

Inventory number must be unique within legal entity if it is set in request

• Get equipments by legal_entity_id (client_id from token) in status == ACTIVE

• Check that there are no equipment with such $.inventory_number

  • in case of error (there is existing equipment with such inventory number) - return 422 ('Inventory number must be unique')

11. Validate device names

Check that at least one name provided and validate each name in $.names if there are more than one

• Check that there is at least one object in $.names

  • in case of error - return 422 ('At least one name must be provided')

• Check that $.names.type is in allowed values from device_name_type dictionary

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

• Check that there are no duplicated types within $.names ($.names.type must be unique within $.names)

  • in case of error - return 422 ('Device name type must not be duplicated ')

12. Validate recorder

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

• Extract user_id from token.

• Check that employee exists and is_active = true

  • in case of error - return 409 ("Employee not found")

• Check that recorder belongs to one of the user’s employee.

  • in case of error - return 422 ('Employee doesn’t match with user')

• Check recorder is an active and approved employee.

  • in case of error - return 422 ('Employee is not active ')

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

  • in case of error - return 422 ('Employee does not belong to legal entity from token')

• Get party (prm.parties) related to this employee

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

• Check that party.verification_status any but NOT_VERIFIED

  • in case of error - return 422 ('Employee is not verified')

Processing

Save object to DB

1. equipments table

2. equipment_status_hstr table

Response structure

Example:

HTTP status codes