| Table of Contents |
|---|
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
Only authenticated and authorized users with appropriate scope can invoke Create Device Request
Device Request is created in async way. Successful result of the job should return a link on the created Device Request (look at /wiki/spaces/CSI/pages/17467310277 ).
Device Request should be signed with DS. Signed content stores in the media storage.
All validations within Device request attributes against medical program configurations should be executed by internal call of /wiki/spaces/CSI/pages/17467474119 function
Validations, which are not part of medical program configurations are performed by this call
Device Request can be created for any device code or device definition which comply with prescribable_device_codes dictionaries configuration
Additional validations might be applied to the parameters in Device request in accordance with devices configurations and device parameters configurations
Devices listed in the assistive_devices dictionaries configuration might be prescribed only by specific specialities listed in the ASSISTIVE_DEVICES_SPECIALITIES_ALLOWED chart parameter
Device Request can be created for a person only
Medical program is optional in the Device Request
Specification
...
| id | API_Specification |
|---|
...
Link
...
...
Посилання на Apiary або Swagger
...
Resource
...
/api/patients/{{patient_id}}/device_requests
...
Посилання на ресурс, наприклад: /api/persons/create
...
Scope
...
device_request:write
...
Scope для доступу
...
Components
...
Devices
...
Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription
...
Microservices
...
Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC
...
Protocol type
...
REST
...
Тип протоколу, який використовується запитом, наприклад: SOAP | REST
...
Request type
...
POST
...
Тип запиту API, наприклад: GET, POST, PATCH…
...
Sync/Async
...
Async
...
Метод є синхронним чи асинхронним?
...
Public/Private/Internal
...
Public
...
Потрібно зазначити тип методу за ступенем доступності
Logic
Save signed content to media storage, in bucket pointed in MEDIA_STORAGE_DEVICE_REQUEST_BUCKET chart parameter
Fill in the following fields:
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.
signed_content_links. Add string item in the array with a link on saved content in media storage
status = ACTIVE
status_reason = null
subject. Set hashed patient_id from URL
requester_legal_entity. Set client_id from token
quantity.unit. Set description according to quantity code and system
dispense_valid_to. dispense_valid_to. Set (current_date + dispense_period_day) if medical program was set and it has dispense_period_day setting. Otherwise, if medical program was set and it has NO dispense_period_day setting, set the value using device_dispense_period global parameter. Else, if medical program was NOT set dispense_valid_to = null.
Save dispense_valid_to as
datetimebut truncate time to beginning of date (2013-08-02T00:00:00Z)
verification_code. Generate random 4-digit code if medical program was set
context_episode_id. Set episode from the $.encounter
context_care_plan_id.Get Activity from $.based_on, set activity.care_plan as context_care_plan_idbased_on. Set based_on from the $.based_on
priority. Set priority from the $.priority
parameter. Set parameter from the $.parameter
performer. Set performer from the $.performer
supporting_info. Set supporting_info from the $.supporting_info
inserted_at. Set current date and time
updated_at. Set current date and time
inserted_by. Set current user from token
updated_by. Set current user from token
Send notification to patient:
Determine patient's default authentication method as described at Determination of a default authentication method and return person's active auth_methods
Get program from request and (if provided) get program setting
request_notification_disabled:if program provided and
request_notification_disabled== true:do not send SMS notification to patient
if program provided and
request_notification_disabled== false and OTP defined on patient:generate text according to CREATE_DEVICE_REQUEST_SMS_TEMPLATE and send SMS with verification_code
if program not provided and OTP defined on patient:
check config parameter
DEVICE_REQUESTS_SMS_ENABLEDis set to truegenerate text according to CREATE_DEVICE_REQUEST_SMS_TEMPLATE_WITHOUT_CODE and send SMS without verification_code
Save data to device_requests collection in MongoDB according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17782014841
If device request is based on activity - recalculate and set remaining_quantity for the activity
select all device requests based on current activity and calculate previously reserved quantity as sum of DR.quantity.value.
calculate reserved at the moment quantity as sum of previously reserved quantity and quantity from current DR
calculate remaining quantity by subtracting reserved at the moment quantity from activity's quantity
Update activity set remaining quantity (activity.detail.remaining_quantity)
Send
StatusChangeEventto Event Manage
Input parameters
...
Input parameter
...
Values
...
Type
...
Description
...
Example
...
patient_id
...
String
...
MPI identifier of the person
...
7075e0e2-6b57-47fd-aff7-324806efa7e5
Request structure
See on Apiary
Example:
| Expand | ||
|---|---|---|
| ||
|
Authorize
Verify the validity of access token
in case of error - 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 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)
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")
Request data validation
Validate digital signature
Validate request is signed
in case of error - return 400 (“Invalid signed content”)
Check DS is valid and not expired
Validate that DS belongs to the requester
Check that DRFO from DS and party.tax_id matches
in case of error - return 422 (“Signer DRFO doesn't match with requester tax_id“)
...
| Table of Contents |
|---|
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
Only authenticated and authorized users with appropriate scope can invoke Create Device Request
Device Request is created in async way. Successful result of the job should return a link on the created Device Request (look at /wiki/spaces/CSI/pages/17467310277 ).
Device Request should be signed with DS. Signed content stores in the media storage.
All validations within Device request attributes against medical program configurations should be executed by internal call of /wiki/spaces/CSI/pages/17467474119 function
Validations, which are not part of medical program configurations are performed by this call
Device Request can be created for any device code or device definition which comply with prescribable_device_codes dictionaries configuration
Additional validations might be applied to the parameters in Device request in accordance with devices configurations and device parameters configurations
Devices listed in the assistive_devices dictionaries configuration might be prescribed only by specific specialities listed in the ASSISTIVE_DEVICES_SPECIALITIES_ALLOWED chart parameter
Device Request can be created for a person only
Medical program is optional in the Device Request
Specification
| Page Properties | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||
|
Logic
Save signed content to media storage, in bucket pointed in MEDIA_STORAGE_DEVICE_REQUEST_BUCKET chart parameter
Fill in the following fields:
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.
signed_content_links. Add string item in the array with a link on saved content in media storage
status = ACTIVE
status_reason = null
subject. Set hashed patient_id from URL
requester_legal_entity. Set client_id from token
quantity.unit. Set description according to quantity code and system
dispense_valid_to. dispense_valid_to. Set (current_date + dispense_period_day) if medical program was set and it has dispense_period_day setting. Otherwise, if medical program was set and it has NO dispense_period_day setting, set the value using device_dispense_period global parameter. Else, if medical program was NOT set dispense_valid_to = null.
Save dispense_valid_to as
datetimebut truncate time to beginning of date (2013-08-02T00:00:00Z)
verification_code. Generate random 4-digit code if medical program was set
context_episode_id. Set episode from the $.encounter
based_on. Set based_on from the $.based_on
priority. Set priority from the $.priority
parameter. Set parameter from the $.parameter
performer. Set performer from the $.performer
supporting_info. Set supporting_info from the $.supporting_info
inserted_at. Set current date and time
updated_at. Set current date and time
inserted_by. Set current user from token
updated_by. Set current user from token
Send notification to patient:
Determine patient's default authentication method as described at Determination of a default authentication method and return person's active auth_methods
Get program from request and (if provided) get program setting
request_notification_disabled:if program provided and
request_notification_disabled== true:do not send SMS notification to patient
if program provided and
request_notification_disabled== false and OTP defined on patient OR THIRD_PERSON authentication method with active confidant person relationship:If device_request is for assistive device (device_request.code OR at least one classification type of device_request.code_reference is in dictionary configuration “assistive_devices”):
generate SMS text with template CREATE_ASSISTIVE_DEVICE_REQUEST_SMS_TEMPLATE_WITH_CODE
Else generate text according to CREATE_DEVICE_REQUEST_SMS_TEMPLATE and send SMS with verification_code
if program not provided and OTP defined on patient OR THIRD_PERSON authentication metod with active confidant person relationship:
check config parameterDEVICE_REQUESTS_SMS_ENABLEDis set to trueIf device_request is for assistive device (device_request.code OR at least one classification type of device_request.code_reference is in /wiki/spaces/REHABILIT/pages/18430754993 “assistive_devices”) and chart parameter ASSISTIVE_DEVICE_REQUESTS_SMS_ENABLED == true:
generate SMS text with template CREATE_ASSISTIVE_DEVICE_REQUEST_SMS_TEMPLATE_WITHOUT_CODE
Else if
DEVICE_REQUESTS_SMS_ENABLED== true:generate text according to CREATE_DEVICE_REQUEST_SMS_TEMPLATE_WITHOUT_CODE and send SMS without verification_code
Save data to device_requests collection in MongoDB according to RC_[UPD] Device request data model
If device request is based on activity - recalculate and set remaining_quantity for the activity
select all device requests based on current activity and calculate previously reserved quantity as sum of DR.quantity.value.
calculate reserved at the moment quantity as sum of previously reserved quantity and quantity from current DR
calculate remaining quantity by subtracting reserved at the moment quantity from activity's quantity
Update activity set remaining quantity (activity.detail.remaining_quantity)
Send
StatusChangeEventto Event Manage
Input parameters
Input parameter | Values | Type | Description | Example |
|---|---|---|---|---|
patient_id | String | MPI identifier of the person |
|
Request structure
See on Apiary
Example:
| Expand | ||
|---|---|---|
| ||
|
Authorize
Verify the validity of access token
in case of error - 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 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)
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")
Request data validation
Validate digital signature
Validate request is signed
in case of error - return 400 (“Invalid signed content”)
Check DS is valid and not expired
Validate that DS belongs to the requester
Check that DRFO from DS and party.tax_id matches
in case of error - return 422 (“Signer DRFO doesn't match with requester tax_id“)
Validate requester
Execute validation as described here
Validate based on
Execute validation as described here
Validate intent
Execute validation as described here
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
Execute validation as described here
Skip the following validation in case medical_program is not specified in the request
| Note |
|---|
|
Validate request
Validate request using schema.
Invoke validations described at https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/18493276250/RC_+UPD+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/EH/pages/18493276250/RC_+UPD+PreQualify+Device+request#10.-Validate-Medical-programs . 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)
Validate $.status is active
in case of error - return 422 ("value is not allowed in enum")
Validate code or code_reference
Execute validation as described here
Skip the following validation in case madical_program is not specified in the request
| Note |
|---|
|
One and only one of $.code (CodeableConcept) and $.code_reference (Reference) must be provided
Check that $.code or $.code_reference provided in request
in case of error - return 422 ('At least one of the parameters must be present')
Check that both $.code or $.code_reference not provided at the same time
in case of error - return 422 ('Only one of the parameters must be present')
If $.code provided:
Check that code.coding[] array contains only 1 element
in case of error - return 422 ('expected a maximum of 1 items but got <actual number>')
Check that code.coding[].code is an active value from the dictionary specified in code.coding[].system
in case of error - return 422 ('value is not allowed in enum')
Check that value is allowed by dictionary configuration “prescribable_device_codes”
in case of error - return 422 ('Value is not allowed by {{dictionary_configuration_name}} dictionary configuration')
If value also included in dictionary configuration “assistive_devices”, then check speciality of the author (speciality_officio=true) in the ASSISTIVE_DEVICES_SPECIALITIES_ALLOWED chart parameter
in case not found in the chart parameter - return 422 ('Speciality is not allowed for {{dictionary_configuration_name}} dictionary configuration')
If config in /wiki/spaces/REHABILIT/pages/18431017079 exists for the $.code, then check all parameters from DEVICE_REQUIRED_PARAMETERS attribute of the config are present in the $.parameter attribute
in case of error - return 422 ('Required parameters for {{device_configuration_name}} device configuration are missed')
If medical_program is specified in the request, then check that there is at least one active device_definition with the same device_definitions.classification_type
device_definitions.is_active = true
in case of error - return 422 ('No appropriate participants found for this medical program')
If $.code_reference provided:
Validate value in the field $.code_reference is Reference on device_definitions resource
Check that device definition exists
in case of error - return 422 ('Device definition not found')
Check that device definition is_active
in case of error - return 422 ('Device definition is not active')
Validate classification types of the device_definition:
Check at least one classification type is allowed by dictionary configuration “prescribable_device_codes”
in case of error - return 422 ('Value is not allowed by {{dictionary_configuration_name}} dictionary configuration”
If one of classification types has also included in the dictionary configuration “assistive_devices”, then check speciality of the author (speciality_officio=true) in the ASSISTIVE_DEVICES_SPECIALITIES_ALLOWED chart parameter
in case not found in the chart parameter - return 422 ('Speciality is not allowed for {{dictionary_configuration_name}} dictionary configuration')
For each classification type check If config in /wiki/spaces/REHABILIT/pages/18431017079 exists for it:
If exists, then check all parameters from DEVICE_REQUIRED_PARAMETERS attribute of the config are present in the $.parameter attribute OR in the properties of the device definition ($.code_reference).
in case of error - return 422 ('Required parameters for {{device_configuration_name}} device configuration are missed')
Validate quantity
| Info |
|---|
If medical program is not specified in request then:
|
If quantity provided in request - execute validation as described here
Check that $.quantity.system isdevice_unitdictionary, requiredin case of error - return 422 ('value is not allowed in enum')
Check that $.quantity.code comply with $.quantity.system, requiredin case of error - return 422 ('value is not allowed in enum')
Check that $.quantity.value is integer, requiredin case of error - return 422 ('Value should be an integer')
Validate encounter
Execute validation as described here
Validate authored on
Execute validation as described here
https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/1757308539518493276250/RC_+UPD+PreQualify+Device+request#1request#7.-Validate-authored-requesteron
Validate
...
occurrence
Execute validation as described here
https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/1757308539518493276250/RC_+UPD+PreQualify+Device+request#2request#8.-Validate-based-onoccurrence
Validate
...
reason
Execute validation as described here
https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/1757308539518493276250/RC_+UPD+PreQualify+Device+request#3.-Validate-intent
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
Validate Package unit and quantity
| Info |
|---|
If medical program is not specified in request then skip this step |
Execute validation as described here
https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/
...
18493276250/RC_+UPD+PreQualify+Device+
...
Skip the following validation in case madical_program is not specified in the request
| Note |
|---|
|
Validate request
Validate request using schema.
...
Validate Medical program
Validate priority
Execute validation as described here
https://e-health-ua.atlassian.net/wiki/spaces/
...
...
18493276250/RC_+UPD+PreQualify+Device+
...
...
Validate supporting info
Execute validation as described here
https://e-health-ua.atlassian.net/wiki/spaces/
...
...
18493276250/RC_+UPD+PreQualify+Device+
...
...
Validate status
The target status value must be submitted in the order of display in the signed content (media storage)
Validate $.status is active
in case of error - return 422 ("value is not allowed in enum")
...
Validate performer
Execute validation as described here
https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/1757308539518493276250/RC_+UPD+PreQualify+Device+request#4.-Validate-code-or-code_reference
Skip the following validation in case madical_program is not specified in the request
| Note |
|---|
|
Validate quantity
| Info |
|---|
If medical program is not specified in request then quantity is optional here |
If quantity provided in request - execute request#13.-Validate-performer
Validate parameter
Execute validation as described here
https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/1757308539518493276250/RC_+UPD+PreQualify+Device+request#5request#14.-Validate-quantityparameter
Validate values in the field $.parameter, array, optional. Validate each value with the following rules:
Check that value from $.quantityparameter.system code is in allowed active values from
device_request_code_unitparameterdictionary, required.in case of error - return 422 ('value is not allowed in enum')
Check that $.quantity.code comply with $.quantity.system, required
in case of error - return 422 ('value is not allowed in enum')
Check that $.quantity.value is integer, required
in case of error - return 422 ('Value should be an integer')
Validate encounter
Execute validation as described here
Validate authored on
Execute validation as described here
Validate occurrence
Execute validation as described here
Validate reason
Execute validation as described here
Validate Package unit and quantity
| Info |
|---|
If medical program is not specified in request then skip this step |
Execute validation as described here
Validate Medical program
Validate priority
Execute validation as described here
Validate supporting info
Execute validation as described here
Validate performer
Execute validation as described here
Validate parameter
Execute validation as described here
Response structure
See on Apiary
Example:
...
parameter.value[x] is one of the following:
value_codeable_concept,value_quantity,value_boolean,value_range,value_stringin case of value[x] is missing - return 422 ('At least one of the parameters must be present')
in case of more than one value[x] provided - return 422 ('Only one of the parameters must be present')
in case of value[x] is provided with incorrect type - return 422 ('type mismatch. Expected [x] but got <type>')
Check $.parameter.code and $.parameter.system are unique within the request, except $.parameter.code is “default”
in case of error - return 422 ('Parameter is already present in the request')
If $.code is set and config in devices configurations exists for the $.code, and DEVICE_PARAMETER_ALLOWED_VALUES attribute is set there:
Check parameter values are included in the DEVICE_PARAMETER_ALLOWED_VALUES attribute
in case of error - return 422 ('Value is not allowed for {{device_configuration_name}} device configuration')
If $.code_reference is set:
If device definition has properties:
If device definition does not have a duplicate property in its property set, then check the request has no such parameter at all OR this parameter has the same value
in case of error - return 422 ('Device request should include a parameter matching the device definition property or omit it')
If device definition has a duplicate property, then check the request has the same parameter which value matches one of the values of the properties
in case of error - return 422 ('Device request should include a parameter matching one of the values of the duplicate properties in the device definition')
For each classification type check If config in devices configurations with DEVICE_PARAMETER_ALLOWED_VALUES attribute exists for it:
If exists, then check parameter values are included in the DEVICE_PARAMETER_ALLOWED_VALUES attribute
in case of error - return 422 ('Value is not allowed for {{device_configuration_name}} device configuration')
If config in device parameters configurations exists for the $.parameter.code and $.parameter.system, then check $.parameter.value[x] matches the conditions defined in the config:
Check the value[x] datatype is correspond to those pointed in the variable DEVICE_PARAMETER_DATA_TYPE of the config
in case of error - return 422 ('Value has datatype that does not correspond {{parameter_configuration_name}} parameter configuration')
If value[x] is value_codeable_concept, then additionally check if value_codeable_concept.coding[].system corresponds to those pointed in the variable DEVICE_PARAMETER_DICTIONARY of the config
in case of error - return 422 ('System does not correspond {{parameter_configuration_name}} parameter configuration')
Response structure
See on Apiary
HTTP status codes
| Page Properties | ||||||
|---|---|---|---|---|---|---|
| ||||||
|
...