Purpose

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

Specification

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

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 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 id <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 ('Only 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, 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