ЕСОЗ - публічна документація

RC_[UPD] Create equipment

Owned by Mykhaylo Khapchyk (SoE eHealth)
Nov 28, 2024
5 min read

Purpose

This WS is designed to create equipment in the system

Specification

https://uaehealthapi.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/equipment/create-equipment

Authorization

  • Verify the validity of access token

    • Return (401, 'Invalid access token') in case of validation fails

  • Verify that token is not expired

    • in case of error - return (401, 'Invalid access token')

  • Check user scopes in order to perform this action (scope = 'equipment:write')

    • Return (403, 'Your scope does not allow to access this resource. Missing allowances: equipment:write') in case of invalid scope(s)

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

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

Validate legal entity

  • Extract client_id from token

  • Check that legal_entity exists and is_active = true

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

  • Check legal entity status (status = ACTIVE or SUSPENDED)

    • In case of error - return 409 ('Legal entity is not active.')

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

2. Division

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

  • Get division by $.division_id

  • Check that division exists and is_active = true

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

  • Check division status = "ACTIVE"

    • in case of error return 409 "Division is not active." 

  • Check that division belongs to the same legal entity as user (prm.division.legal_entity_id = token.client_id)

    • in case of error return 409 "User is not allowed to create equipment for this division."

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

5. 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 and is_active = true

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

  • prm.device_definitions.classification_type = $.type Check $.type in prm.device_difinition_classification_types that are related to $.device_definition_id

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

6. 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."

7. Status

Only active device can be created

  • Check that $.status == 'active'

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

8. Availability status

Only available device can be created

  • Check that $.availability_status == 'available'

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

9. 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"

10. 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_<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')

11. Validate inventory number

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

If $.inventory_number is missing or is empty - do not check it is unique

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

12. 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 ('Values are not unique by 'type'.')

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

Service logic

  1. Save equipment record to the prm.equipments table (see RC_[NEW] Equipment Data Model ) 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 = client_id from token

    14. division_id = $.division_id

    15. note = $.note

    16. parent_id = $.parent_id

    17. lot_number = $.lot_number

    18. expiration_date = $.expiration_date

    19. is_active = true

    20. employee_id = $.recorder

    21. inserted_at = current datetime

    22. inserted_by = user_id from token

    23. updated_at = current datetime

    24. updated_by = user_id from token

  2. 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

ЕСОЗ - публічна документація