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

RC._Create Specimen_EN

Purpose

This WS allows to create Specimen entity by employees without submitting Encounter Data Package.

Specification

Link

 Apiary

Resource

 api/patients/patient_id/specimens

Scope

 specimen:write

Components

 Specimen

Microservices

 

Protocol type

 REST

Request type

 POST

Sync/Async

 Async

Public/Private/Internal

 Public

Key points

  1. Only authenticated and authorized employee with appropriate scope can create a Specimen.

  2. Request should be signed with DS.

  3. The specimen is created asynchronously

  4. The specimen can be created both for persons and for prepersons.

 

Logic

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17629118915/RC.#%D0%A1%D1%82%D0%B2%D0%BE%D1%80%D0%B5%D0%BD%D0%BD%D1%8F-%D0%97%D1%80%D0%B0%D0%B7%D0%BA%D0%B0-%D0%B1%D0%B5%D0%B7-%D0%B2%D0%B7%D0%B0%D1%94%D0%BC%D0%BE%D0%B4%D1%96%D1%97-%D0%B7-%D0%BF%D0%B0%D1%86%D1%96%D1%94%D0%BD%D1%82%D0%BE%D0%BC

 

Global and configurable parameters

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17629119370/RC.+Specimen+dictionaries+and+configurable+parameters#Configurable-parameters

 

Input parameters

Input parameter

Values

Type

Description

Example

Input parameter

Values

Type

Description

Example

patient_id

 

String

Unique patient identifier

7075e0e2-6b57-47fd-aff7-324806efa7e5

Dictionaries

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17629119370/RC.+Specimen+dictionaries+and+configurable+parameters#Dictionaries

 

Request structure

{ "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b", "status": "available", "type": { "coding": [ { "system": "specimen_types", "code": "default" } ] }, "condition": { "coding": [ { "system": "specimen_conditions", "code": "default" } ] }, "note": "Some notes", "managing_organization": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "legal_entity" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" } }, "registered_by": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "employee" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" } }, "parent": [ { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "specimen" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" } } ], "request": [ { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "service_request" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" } } ], "collection": { "collector": { "identifier": { "type": { "coding": [ { "system": "eHealth/resources", "code": "employee" } ] }, "value": "9183a36b-4d45-4244-9339-63d81cd08d9c" } }, "collected_date_time": "2023-04-20T19:14:13Z", "duration": { "value": 5, "system": "eHealth/ucum/units", "code": "min", "comparator": ">" }, "quantity": { "value": 20, "system": "eHealth/ucum/units", "code": "g" }, "method": { "coding": [ { "system": "specimen_collection_methods", "code": "default" } ] }, "body_site": { "coding": [ { "system": "eHealth/body_sites", "code": "head" } ] }, "fasting_status_codeable_concept": { "coding": [ { "system": "fasting_statuses", "code": "default" } ] } }, "container": [ { "identifier": "1-3244-ABC", "description": "Some container description", "type": { "coding": [ { "system": "specimen_container_types", "code": "default" } ] }, "capacity": { "value": 30000, "system": "eHealth/ucum/units", "code": "mg" }, "specimen_quantity": { "value": 20, "system": "eHealth/ucum/units", "code": "g" }, "additive_codeable_concept": { "coding": [ { "system": "specimen_container_additives", "code": "default" } ] } } ] }

Authorization

  • 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 = 'specimen:write')

    • return 403 (“Your scope does not allow to access this resource. Missing allowances: specimen: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")

 

Headers

  • Content-Type:application/json

  • api-key:aFBLVTZ6Z2dON1V

  • Authorization:Bearer mF_9.B5f-4.1JqM

  • X-Custom-PSK:a2aa05c76f3f2d91870f923a53cc8aa8f23bbc01a8238d1c2c26d4299715a7e4

Request data validation

Validate legal entity

  • Extract client_id from token

  • Check legal entity status (status = ACTIVE)

    • In case of error - return 409 ('client_id refers to legal entity that is not active')

Validate Digital Sign

  • 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 employee who registered the Specimen ($.registered_by)

    • Check that DRFO from DS and party.tax_id of the registrar matches

      • in case of error - return 422 (“Does not match the signer drfo“)

Validate Patient

  • Get Patient identifier from the URL

  • Check it exists in the DB

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

  • Validate patient is an active person or preperson

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

  • Validate person's verification_status is not equal to NOT_VERIFIED (not for preperson).

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

Validate request

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

Validate Specimen

Validate root attributes of specimen entity:

1. Parent

Validate value in the field $.parent, array of Reference type, if submitted

  • Check each value is valid Reference on another Specimen resource

  • Validate referenced Specimen:

    • Check it belongs to the same patient ($.subject)

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

    • Check status is available

      • in case of error - return 422 ('Invalid specimen status')

2. Requests

Validate each value in $.request, array of Reference type, if submitted

  • Array item has type of {Reference} to Service Request resource

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

  • Service Request exists in the DB and relates to the patient ($.subject)

    • in case of error - return 422 ("Service request with such id is not found")

  • Service Request’s status is active or program_processing_status is in_progress (any status is valid in case program_processing_status= in_progress)

    1. in case of error - return 422 ("Service request is not active or in progress")

  • If used_by_legal_entity is set in the Service request (program_processing_status=in_progress), then check it matches the client_id from token

    • in case of error - return 422 ("Service request must be related to the same legal entity")

  • Check if Service Request’s expiration date is less then or equal to current date

    1. in case of error - return 422 ("Service request expiration date must be greater than or equal to current date")

3. Type

Validate value in the field $.type, CodeableConcept type, required.

  • Check that value is in allowed values from specimen_types dictionary.

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

4. Condition

Validate value in the field $.condition, CodeableConcept type, optional.

  • Check that value is in allowed values from specimen_conditions dictionary.

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

5. Registered by

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

  • Extract user_id from token. Check that employee belongs to one of the user’s employee.

    • in case of error - return 422 ('User is not allowed to register a specimen for the employee')

  • Check that employee is active and approved

    • in case of error - return 422 ('Invalid employee status')

  • Check that employee is related to the legal entity (client_id) from token

    • in case of error - return 422 ('Employee doesn't belong to your legal entity')

6. Status

Validate value in the field $.status, string, required

  • Check it is available , according to specimen_statuses dictionary

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

7. Id

Validate value in the field $.id, uuid, required

  • Check there is no specimen with the same ID in the DB

    • in case of error return 422 “Specimen with such id already exists“

8. Managing organization

Validate value in the field $.managing_organization, Reference on legal entity, required

  • Check $.managing_organization.identifier.value is equal to client_id from token

    • in case of error return 422 "Managing_organization does not correspond to user's legal_entity"

Validate Collection

Validate $.collection object in the specimen, required

1. Collector

Validate value in the field $.collection.collector, Reference type, required.

  • Check it references to employee or patient resource

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

  • If collector is an employee:

    • Check it exists in the DB

      • in case of error - return 422 ('Employee with such ID is not found')

    • Check it is active and approved

      • in case of error - return 422 ('Invalid employee status')

    • Check that employee is related to the legal entity (client_id) from token

      • in case of error - return 422 ('Employee doesn't belong to your legal entity')

  • If collector is a patient:

    • Check it is current patient (subject)

      • in case of error - return 422 ('In case collector is patient it must be the current patient')

2. Collected

Validate there is one of the required $.collection.collected_[x] field is set: collected_date_time or collected_period.

  • Return 422 ('At least one of the parameters must be present') in case more then one submitted

Validate collected_date_time:

  • Check value is a timestamp

    • in case of error - return 422 schema validation error

  • Check it is greater then (current_date - SPECIMEN_MAX_DAYS_PASSED) date

    • in case of error - return 422 ('Date must be greater than <current date - SPECIMEN_MAX_DAYS_PASSED>')

  • Check it is less then or equal to current datetime

    • in case of error - return 422 ('Must be in past')

Validate collected_period:

  • Validate value with schema of the {Period} type

    • in case of error - return 422 schema validation error

  • Check if period start is greater then (current_date - SPECIMEN_MAX_DAYS_PASSED) date

    • in case of error - return 422 ('Date must be greater than <current date - SPECIMEN_MAX_DAYS_PASSED>')

  • Check if period start is less then or equal to current datetime

    • in case of error - return 422 ('Start date must be in past')

  • Check end >= start

    • in case of error - return 422 ('End date must be greater than or equal the start date')

  • Check end <= current datetime (is not in the future)

    • in case of error - return 422 ('End date must be in past')

3. Quantity

Validate value in the field $collection.quantity, SimpleQuantity type, optional

  • Check that $.collection.quantity.system is eHealth/ucum/units dictionary, required

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

  • Check that $.collection.quantity.code comply with $.collection.quantity.system, required

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

  • Check $.collection.quantity.value is not empty, is float, greater than zero

    • in case of error - return corresponding 422 ('value must be greater than 0')

  • Check that $.collection.quantity.value >= sum($.container.specimen_quantity.value)

    • in case of error - return 422 ('Collected quantity must not be exceeded by the specimen quantity distributed among the containers')

4. Duration

Validate value in the field $collection.duration, Duration type, optional

  • Check that $.collection.duration.system is eHealth/ucum/units dictionary, required

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

  • Check that $.collection.duration.code comply with $.collection.duration.system and one of SPECIMEN_DURATION_ALLOWED_CODES, required

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

  • Check $.collection.duration.value is not empty, is float, greater than zero

    • in case of error - return corresponding 422 ('must be greater than 0')

5. Method

Validate value in the field $.collection.method , CodeableConcept type, optional.

  • Check that value is in allowed values from specimen_collection_methods dictionary.

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

6. Body site

Validate value in the field $.collection.body_site, CodeableConcept type, optional.

  • Check that value is in allowed values from eHealth/body_sites dictionary.

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

7. Fasting status

Validate value in the field $.collection.fasting_status_codeable_concept, CodeableConcept type, optional.

  • Check that value is in allowed values from fasting_statuses dictionary.

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

Validate Container

Validate $.container array in the specimen, required. Should contain at least one item.

1. Identifier

Validate value in the field $.container.identifier, string, required.

  1. Check it is unique within the Specimen

    1. in case of error - return 422 ('Identifier already exists in the specimen')

2. Type

Validate value in the field $.container.type, CodeableConcept type, required.

  • Check that value is in allowed values from specimen_container_types dictionary.

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

3. Capacity

Validate value in the field $container.capacity, SimpleQuantity type, required

  • Check that $.container.capacity.system is eHealth/ucum/units dictionary, required

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

  • Check that $.container.capacity.code comply with $.container.capacity.system, required

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

  • Check $.container.capacity.value is not empty, is float, greater than zero

    • in case of error - return corresponding 422 ('value must be greater than 0')

4. Specimen quantity

Validate value in the field $container.specimen_quantity, SimpleQuantity type, required

  • Check that $.container.specimen_quantity.system is eHealth/ucum/units dictionary, required

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

  • Check that $.container.specimen_quantity.code comply with $.container.specimen_quantity.system, required

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

  • Check $.container.specimen_quantity.value is not empty, is float, greater than zero

    • in case of error - return corresponding 422 ('value must be greater than 0')

  • Check that $.container.specimen_quantity.code matches to $.collection.quantity.code

    • in case of error - return 422 (Does not match the code of the collected quantity)

5. Additive

Validate value in the field $.container.additive_codeable_concept, CodeableConcept type, optional.

  • Check that value is in allowed values from specimen_container_additives dictionary.

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

Processing

  1. Save signed content to media storage, in the bucket pointed in MEDIA_STORAGE_SPECIMEN_BUCKET chart parameter

  2. Generate accession_identifier number:

    1. Generate requisition number (see Human readable requisition number) based on the specimen id. Note: requisition number should be unique for each specimen and should not match with number of another entities. So, if generated number match to existing in DB - it should be regenerated

    2. Encode and set it into $.accession_identifier attribute

  3. Set display_value for:

    1. registered_by attribute

    2. managing_organization attribute

    3. collection.collector attribute, only if type is employee (not patient)

  4. Set context, received_time, status_reason, collection.procedure to null

  5. Set subject with hashed mpi identifier

  6. Save data to specimens collection in DB according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17629118845

  7. Save link from media storage to the $.signed_content_links field in specimens collection

  8. Create job and return it’s id.

 

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

HTTP status code

Message

What caused the error

400

Invalid signed content

 

401

Invalid access token

 

403

Access denied. Party is deceased

 

403

Access denied. Party is not verified

 

403

Your scope does not allow to access this resource. Missing allowances: specimen:write

 

404

Person is not found

 

409

client_id refers to legal entity that is not active

 

409

Patient is not verified

 

409

Person is not active

 

422

Collected quantity must not be exceeded by the specimen quantity distributed among the containers

 

422

Date must be greater than <current date - SPECIMEN_MAX_DAYS_PASSED>

 

422

Does not match the code of the collected quantity

 

422

Does not match the signer drfo

 

422

Employee doesn't belong to your legal entity

 

422

Employee with such ID is not found

 

422

End date must be greater than or equal the start date

 

422

End date must be in past

 

422

Identifier already exists in the specimen

 

422

In case collector is patient it must be the current patient

 

422

Invalid employee status

 

422

Invalid specimen status

 

422

Legal entity not found

 

422

Managing_organization does not correspond to user's legal_entity

 

422

must be greater than 0

 

422

Must be in past

 

422

Only one of the parameters must be present

 

422

Person is not active

 

422

Person is not found

 

422

schema validation error

 

422

Service request expiration date must be greater than or equal to current date

 

422

Service request is not active or in progress

 

422

Service request must be related to the same legal entity

 

422

Service request not found

 

422

Specimen not found

 

422

Specimen with id <id> already exists

 

422

Start date must be in past

 

422

User is not allowed to register a specimen for the employee

 

422

value is not allowed in enum

 

422

value must be greater than 0

 

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