https://e-health-ua.atlassian.net/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)

• Properties of a REST API method document

• Purpose

• Logic

• Configuration parameters

• Dictionaries

• Input parameters

• Request structure

• Headers

• Request data validation

• Processing

• Response structure examples

• HTTP status codes

• Post-processing processes

• Technical modules where the method is used

Properties of a REST API method document

Purpose

This WS allows to set date and time when Specimen was received for processing by laboratory employee.

Key points

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

2. DS isn't used here.

3. The specimen is processed asynchronously

Logic

RC._Процеси роботи зі зразком біоматеріалу | Облік дати та часу отримання Зразка

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

Request structure

See on API-specification

Headers

Headers

Request data validation

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 scopes in order to perform this action (scope = 'specimen:process')

  • return 403 (“Your scope does not allow to access this resource. Missing allowances: specimen:process”) 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 legal entity status (status = ACTIVE)

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

Validate data consistency

• Ensure that submitted Specimen relates to the Patient (from URL)

  • in case of error - return 404 (not found)

Validate status transition

• Get Specimen by id

• Check Specimen’s status is available

  • in case of error - return 409 ('Specimen is not in available status')

Validate request

Validate request by schema and return 422 error code with the list of validation errors in case of fails. User fills following fields in the request:

1. Received datetime

Validate value in the field $.received_time, timestamp, required

• Check it hasn’t set yet (empty before the process invoked)

  • in case of error - return 422 ('Value is already set and cannot be changed')

• Check $.received_time is between current datetime and (collected_date_time OR collected_period.end)

  • in case of error - return 422 ('Should be between collected datetime and current datetime')

Processing

1. Create job and return it’s id.

2. Update specimen record with following:

   1. received_time = $.received_time

   2. updated_at = current datetime

   3. updated_by = user_id from token

Response structure examples

See on API-specification

HTTP status codes

Post-processing processes

N/A

Technical modules where the method is used