ЕСОЗ - публічна документація
Create Equipment
- 1 Purpose
- 2 Specification
- 3 Logic
- 4 Request structure
- 5 Authorize
- 6 Headers
- 7 Request data validation
- 7.1 Validate legal entity
- 7.2 Validate request
- 7.3 Validate external identifier
- 7.3.1 3. Parent
- 7.3.2 4. Device definition
- 7.3.3 5. Serial number
- 7.3.4 6. Status
- 7.3.5 7. Availability status
- 7.3.6 8. Manufacture date
- 7.3.7 9. Validate properties
- 7.3.8 10. Validate inventory number
- 7.3.9 11. Validate device names
- 7.3.10 12. Validate recorder
- 8 Processing
- 9 Response structure
- 10 HTTP status codes
Purpose
This WS is designed to create equipment in the system
Specification
Link | Посилання на Apiary або Swagger | |
Resource | /api/equipment | Посилання на ресурс, наприклад: /api/persons/create |
Scope | equipment:write | Scope для доступу |
Components | Devices and equipment | Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription |
Microservices | API paragraph not found | Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC |
Protocol type | REST | Тип протоколу, який використовується запитом, наприклад: SOAP | REST |
Request type | POST | Тип запиту API, наприклад: GET, POST, PATCH… |
Sync/Async | Sync | Метод є синхронним чи асинхронним? |
Public/Private/Internal | Public | Потрібно зазначити тип методу за ступенем доступності |
Logic
Only authenticated and authorized HR, ADMIN, OWNER employees can register equipments.
Equipments can be registered in MSP, OUTPATIENT, PRIMARY_CARE and EMERGENCY legal entities.
Equipment has to be linked to division. One division can have many equipments.
Legal entity can register equipments for its own divisions only.
Save equipment record to the prm.equipments table (see RC_[NEW] Equipment status modelarchived) with the following:
id = generate uuid
inventory_number = $.inventory_number
serial_number = $.serial_number
device_definition_id = $.device_definition_id
status = $.status
error_reason = null
availability_status = $.availability_status
manufacturer = $.manufacturer
manufacture_date = $.manufacture_date
model_number = $.model_number
type = $.type
properties = $.properties
legal_entity_id = $.token.client_id
division_id = $.division_id
note = $.note
parent_id = $.parent_id
lot_number = $.lot_number
expiration_date = $.expiration_date
udi = $.udi
is_active = true
recorder = $.recorder
inserted_at = current datetime
inserted_by = user_id from token
updated_at = current datetime
updated_by = user_id from token
Insert each name from $.names into prm.equipment_names with the following:
id = generate uuid
equipment_id = reference to equipment
type = $.names.type
name = $.names.name
inserted_at = current datetime
inserted_by = user_id from token
updated_at = current datetime
updated_by = user_id from token
Request structure
Example:
Authorize
Verify the validity of access token
Return (401, 'Invalid access token') in case 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 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")
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)
Extract client_id from token (token.client_id == legal_entity_id)
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, SUSPENDED)
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')
Validate that an equipments type value exists in dictionary "EQUIPMENT_TYPE"
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
Get division by $.division_id Validate division_id in request body - division exists and is_active = true
Return 422 in case validation fails
Check that division exists and is_active = true
in case of error - return 409 ("Division not found")
Check division status =ACTIVE.
Return 422 with message "Division is not active" in case validation fails.
Check division_id belongs to the same legal entity legal_entity_id (from token) as user (prm.division.legal_entity_id = token.client_id)
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
Check an external_id field is not empty
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 parameteronly
value_string
is allowed for this propertyin 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 propertyin 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
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')
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
dictionaryin 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
Parameter | Source | Description |
---|---|---|
id | UUID | Autogenerated |
type | Request: type | Get from request body |
external_id | Request: external_id | Get from request body |
division_id | Request: division_id | Get from request body |
udi | Request: udi | Get from request body |
lot_number | Request: lot_number | Get from request body |
manufacturer | Request: manufacturer | Get from request body |
manufacture_date | Request: manufacture_date | Get from request body |
expiration_date | Request: expiration_date | Get from request body |
model_number | Request: model_number | Get from request body |
part_number | Request: part_number | Get from request body |
version | Request: version | Get from request body |
name | Request: name | Get from request body |
serial_number | Request: serial_number | Get from request body |
note | Request: note | Get from request body |
legal_entity_id | Token: client_id | Extract client from token |
status | Const: ACTIVE | By default ACTIVE for new records |
is_active | Const: TRUE | Always TRUE for new records |
inserted_at | Timestamp: now() | Get current date-time |
inserted_by | Token: user_id | Extract user from token |
updated_at | Timestamp: now() | Get current date-time |
updated_by | Token: user_id | Extract user from token |
2. equipment_status_hstr table
Parameter | Source | Description |
---|---|---|
id | UUID | Autogenerated |
equipment_id | UUID | Reference to equipments.id |
status | Const: ACTIVE | By default ACTIVE for new records |
inserted_by | Token: user_id | Extract user from token |
inserted_at | Timestamp: now() | Get current date-time |
Response structure
Example:
HTTP status codes
HTTP status code | Message | What caused the error |
---|---|---|
201 | Response |
|
401 | Invalid access token | Access token validation failed |
403 | Your scope does not allow to access this resource. Missing allowances: equipment:write | Invalid scope(s) |
403 | Access denied. Party is not verified |
|
403 | Access denied. Party is deceased |
|
409 | Legal entity not found | Validation failed |
409 | client_id refers to legal entity that is not active |
|
409 | Division not found |
|
409 | User is not allowed to create devices for this division |
|
409 | Parent equipment not found |
|
409 | Referenced parent equipment is not active |
|
409 | Referenced parent equipment belongs to another legal entity |
|
409 | Device definition not found |
|
409 | Referenced device definition must be of the same type as equipmen |
|
409 | Employee not found |
|
422 | 422 value is not allowed in enum | Validation failed |
422 | Division is not active |
|
422 | Serial number is required for this type of equipment |
|
422 | Status must be active |
|
422 | Availability status must be available |
|
422 | Manufacture date must be equal to or earlier than current date |
|
422 | One and only one key is allowed from the list: [value_integer, value_decimal, value_boolean, value_string], but the following are present: [] |
|
422 | type mismatch. Expected <expected_type> but got <actual_type> |
|
422 | Only value_string is allowed for dictionary values |
|
422 | Inventory number must be unique |
|
422 | At least one name must be provided |
|
422 | Device name type must not be duplicated |
|
422 | Employee doesn’t match with user |
|
422 | Employee is not active |
|
422 | Employee does not belong to legal entity from token |
|
422 | Employee is not verified |
|
ЕСОЗ - публічна документація