Purpose

This WS is designed to create a new procedure separately from encounter pckg. 

Specification

...

Link

...

https://medicaleventsmisapi.docs.apiary.io/#reference/medical-events/procedures/create-procedure

...

Resource

...

/api/patients/{{patient_id}}/procedures

...

Scope

...

procedure:write

...

Components

...

Episode of Care

...

Microservices

...

API paragraph not found

...

Protocol type

...

REST

...

Request type

...

POST

...

Sync/Async

...

Async

...

Public/Private/Internal

...

Public

Logic

Procedure can be registered in eHealth as a part of encounter pckg or just by itself with reference on Service Request. Procedure should be registered in the system after it was performed for a patient.

Реєстрація запису про проведену процедуру в ЦК

Input parameters

...

Input parameter

...

Values

...

Type

...

Description

...

Example

...

patient_id

...

String

...

Unique patient identifier

...

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

Request structure

See on Apiary

Example:

{
  "signed_data": "ew0KICAicGVyaW9kIjogew0KIC..."
}

Authorize

• Verify the validity of access token

  • Return (401, 'unauthorized') in case of validation fails

• Verify that token is not expired

  • in case of error - return (401, 'unauthorized')

• Check user scopes in order to perform this action (scope = 'procedure:write')

  1. Return (403, 'invalid scopes') in case of invalid scope(s)

Request to process the request using a token in the headers

Headers

Наприклад:

• Content-Type:application/json

• Authorization:Bearer {{access_token}}

• API-key:{{secret}}

Request data validation

Validate digital signature

Decode content that is encrypted in an electronic digital signature.
Use Digital signature WS. Method checks digital signature and returns result.
See service specification

1. Ensure that digital signature is valid

1. Validate that recorded_by of procedure is a current user

2.1. Get token metadata

• Extract user_id, client_id, client_type

2.2. Determine the party_id associated with this user_id

SELECT pu.party_id 
FROM party_users pu 
WHERE pu.user_id = :user_id;

2.3. Determine employees related to this party_id in current MSP

SELECT e.id 
FROM employees e 
WHERE e.party_id = :party_id AND e.legal_entity_id = :client_id;

2.4 Ensure that $.recorded_by.identifier.value matches with user employees

1. Validate that DS belongs to recorded_by

3.1. Determine the party_id associated with recorded_by ($.recorded_by.identifier.value)

SELECT p.tax_id 
FROM employees e, parties p 
WHERE e.party_id = p.id AND e.id = :recorded_by;

Validate request using JSON Schema

Return 422 with the list of validation errors in case validation fails

Validate procedure

1. Validate id

   1. ID is unique for MongoDB.procedures

   2. ID is UUID

2. Validate referrals

   1. As a referral it can be referenced electronic (registered in the system) OR paper service request

   2. Validate $.procedure.based_on OR $.procedure.paper_referral is in request

   3. Validate based_on as Reference(Referencevalidation)

   4. Validate paper referral as Object (paper_referral)

   5. Validate that service_request is

      1. in status is active or in progress

         1. in case of error return 409 "Invalid service request status"

      2. if used_by_legal_entity != NULL:

         1. check used_by_legal_entity.identifier.value == token.client_id 

            1. in case of error return 409 "Service request is used by another legal_entity"

      3. service_request.expiration date should be <= now

         1. in case error return 422, "Service request expiration date must be a datetime greater than or equal"

      4. check that service_request contains based_on parameter

         1. in case based_on present in service_request

            1. verify care_plan:

               1. It should be in active status

               2. Care plan's period end (if exist) should be greater than current date or equal.

            2. verify activity:

               1. It has activity.detail.kind=service_request; activity.detail.product_reference=service_id. 

               2. It has scheduled, in_progress status

         2. in case based_on not present in request skip previous validations.

3. Validate status

   1. On create procedure status could be only `completed`. There is no necessity to publish another procedure to e-Health. `entered_in_error` could be set on update procedure.

      1. error 422 by json schema

4. Validate code
   Note. For procedure.code pass only "service", and the "service_group" does not pass
   

   1. Validate code as Reference(Referencevalidation)

   2. If service_requests.code.identifier.value is service, validate $procedure.code.identifier.value = service_requests.code.identifier.value

      1. in case error return 409, "Service in procedure differ from service in service request"

   3. if service_requests.code.identifier.value is service_group, validate $procedure.code.identifier.value in (SELECT service_id from service_inclusions where service_group_id='service_requests.code.identifier.value')

      1. in case error return 409, "Service in procedure differ from services in service request's service_group"

   4. Validate procedure.service.is_active = true

      1. in case error return 409, "Service should be active"

5. Validate performed_date_time

   1.  performed_date_time is real

      1. in case error return 422, "Performed_date_time in invalid"

   2. performed_date_time <= now

      1. in case error return 422 "Procedure cannot be registered in future"

6. Validate recorded_by

   1. Validate recorded_by as Reference(Referencevalidation)

   2. $..recorded_by.identifier.value is an ID of existing employee in PRM.employee

      1. in case of error  return 422, "Employee with such id is not found"

   3. Validate recorded_by is employee with status='APPROVED' and is_active= true and end_date is null or more than today and PRM.employees.employee_type in ('DOCTOR','SPECIALIST','ASSISTANT')

      1. in case error return 409, "This action is prohibited for current employee" 

   4. Validate employees.legal_entity_id=$managing_organization.identifier.value

      1. in case error return 409, "Employee should be from current legal entity"

7. Performer(asserter) validation

   1. case $..primary_source==true

      1. $..performer(or $..asserter) must be filled

         1. in case of error "Performer (asserter) must be filled"

      2. $..report_origin must be absent

         1. in case of error "Report_origin can not be submitted in case primary_source is true" 

      3. validate performer(asserter) is a valid value from corresponding dictionary

         1. $..performer.identifier.type.coding[*].system == "eHealth/resources"

            1. in case of error "Submitted system is not allowed for this field"

         2. $..performer.identifier.type.coding[*].code=="employee"

            1. in case of error "Submitted code is not allowed for this field"

      4. validate performer(asserter) is an active medical staff from current legal_entity

         1. $..performer.identifier.value is an ID of existing employee in PRM.employee

            1. in case of error "Employee with such id is not found"

         2. $..performer.identifier.value == PRM.employees.id where (PRM.employees.status == "APPROVED" and PRM.employees.employee_type in ('DOCTOR','SPECIALIST','ASSISTANT'))

   2. case primary_source=false

      1.  error 422. (Procedure with primary_source=false could be send only with encounter package)

8. Validate division

   1. Validate division as Reference(Referencevalidation)

   2. $division is an ID in PRM.divisions

      1. in case return 422, "Division with such id is not found"

   3. division.status=ACTIVE and is_active=true

      1. in case error return 409, "Division is not active"

   4. division.legal_entity_id = $client_id

      1. in case error return 409, "Division is not in current legal_entity"

9. Validate patient status

   1. Medical_data status for this patient must be in "active" status

      1. in case of error return 409 - "Patient is not active"

10. Validate managing_organization is a current active legal_entity with proper type

    1.  as Reference(Referencevalidation)

    2. $managing_organization is an ID in PRM.legal_entities

       1. in case return 422, "Legal entity with such id is not found"

    3. validate managing_organization status is 'ACTIVE' and is_active=true

       1. in case error return 422 ('Legal entity is not active')

    4. validate legal_entity type is in ('PRIMARY_CARE','MSP','MSP_PHARMACY','MSP_PHARMACY') (use `ME_ALLOWED_TRANSACTIONS_LE_TYPES` from charts)

       1. in case error return 422, "Legal entity with type $legal_entity.type cannot perform procedures"

    5. validate $managing_organization.identifier.value = $client_id

       1. in case of error 409 "Managing organization does not correspond to user's legal entity."

11. Validate reason_references

    1. Validate reason_reference as a Reference (Referencevalidation)

    2. Validate reason_refernce.identifier.value is condition not in status ENTERED_IN_ERROR

       1. in case error return 422, "Condition is canceled"

12. Validate outcome

    1. validate outcome as a Reference (Referencevalidation)

    2. validate outcome.coding.object.system is in dictionary eHealth/procedure_outcomes

       1. in case error return 422, "outcome not in dictionary eHealth/procedure_outcomes"

13. Validate category

    1. according to the dictionary 'eHealth/procedure_categories' - by schemata

    2. Validate that procedure category corresponds to service category, that is references as code in procedure

       1. $.procedure.category=PRM.services.category where PRM.services.id=$.procedure.code.identifier.value

          1. in case of error return 422 "Procedure category does not match with the service category"

14. Related care plan validation in case service request has reference on care plan and procedure has reference on service request check possibility to create procedure depending on service_request[].activity remaining quantity

    1. calculate the quantity of artifacts that are contained in the request and have a link to the service request. Compare remaining_quantity from activity with the quantity of artifacts. Check that difference is greater then or equal to zero

       1. in case of error return 409 "The total amount of the prescribed service quantity exceeds quantity in care plan activity"

15. Validate patient verification status:

    1. If procedure has based_on with valid and active service request, then skip this validation.

    2. Else check patient verification_status is not equal to NOT_VERIFIED.

       1. in case of error return 409, "Patient is not verified"

Processing

API paragraph not found

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"
  }
}

Post-processing processes

...

Save signed_content to Media Storage

...

Purpose

This WS is designed to create a new procedure separately from encounter pckg. 

Specification

Logic

Procedure can be registered in eHealth as a part of encounter pckg or just by itself with reference on Service Request. Procedure should be registered in the system after it was performed for a patient.

Реєстрація запису про проведену процедуру в ЦК

Input parameters

Request structure

See on Apiary

Example:

{
  "signed_data": "ew0KICAicGVyaW9kIjogew0KIC..."
}

Authorize

• Verify the validity of access token

  • Return (401, 'unauthorized') in case of validation fails

• Verify that token is not expired

  • in case of error - return (401, 'unauthorized')

• Check user scopes in order to perform this action (scope = 'procedure:write')

  1. Return (403, 'invalid scopes') in case of invalid scope(s)

Request to process the request using a token in the headers

Headers

Наприклад:

• Content-Type:application/json

• Authorization:Bearer {{access_token}}

• API-key:{{secret}}

Request data validation

Validate digital signature

Decode content that is encrypted in an electronic digital signature.
Use Digital signature WS. Method checks digital signature and returns result.
See service specification

1. Ensure that digital signature is valid

1. Validate that recorded_by of procedure is a current user

2.1. Get token metadata

• Extract user_id, client_id, client_type

2.2. Determine the party_id associated with this user_id

SELECT pu.party_id 
FROM party_users pu 
WHERE pu.user_id = :user_id;

2.3. Determine employees related to this party_id in current MSP

SELECT e.id 
FROM employees e 
WHERE e.party_id = :party_id AND e.legal_entity_id = :client_id;

2.4 Ensure that $.recorded_by.identifier.value matches with user employees

1. Validate that DS belongs to recorded_by

3.1. Determine the party_id associated with recorded_by ($.recorded_by.identifier.value)

SELECT p.tax_id 
FROM employees e, parties p 
WHERE e.party_id = p.id AND e.id = :recorded_by;

Validate request using JSON Schema

Return 422 with the list of validation errors in case validation fails

Validate procedure

1. Validate id

   1. ID is unique for MongoDB.procedures

   2. ID is UUID

2. Validate referrals

   1. As a referral it can be referenced electronic (registered in the system) OR paper service request

   2. Validate $.procedure.based_on OR $.procedure.paper_referral is in request

   3. Validate based_on as Reference(Referencevalidation)

   4. Validate paper referral as Object (paper_referral)

   5. Validate that service_request is

      1. in status is active or in progress

         1. in case of error return 409 "Invalid service request status"

      2. if used_by_legal_entity != NULL:

         1. check used_by_legal_entity.identifier.value == token.client_id 

            1. in case of error return 409 "Service request is used by another legal_entity"

      3. service_request.expiration date should be <= now

         1. in case error return 422, "Service request expiration date must be a datetime greater than or equal"

      4. check that service_request contains based_on parameter

         1. in case based_on present in service_request

            1. verify care_plan:

               1. It should be in active status

               2. Care plan's period end (if exist) should be greater than current date or equal.

            2. verify activity:

               1. It has activity.detail.kind=service_request; activity.detail.product_reference=service_id. 

               2. It has scheduled, in_progress status

               3. For an old activities (has no units in quantity) validate remaining_quantity as described at Submit Encounter Data Package: Related care plan validation

         2. in case based_on not present in request skip previous validations.

      5. Check if service request quantity is not exhausted as described at Submit Encounter Data Package: Related service request validation

3. Validate status

   1. On create procedure status could be only `completed`. There is no necessity to publish another procedure to e-Health. `entered_in_error` could be set on update procedure.

      1. error 422 by json schema

4. Validate code
   Note. For procedure.code pass only "service", and the "service_group" does not pass
   

   1. Validate code as Reference(Referencevalidation)

   2. If service_requests.code.identifier.value is service, validate $procedure.code.identifier.value = service_requests.code.identifier.value

      1. in case error return 409, "Service in procedure differ from service in service request"

   3. if service_requests.code.identifier.value is service_group, validate $procedure.code.identifier.value in (SELECT service_id from service_inclusions where service_group_id='service_requests.code.identifier.value')

      1. in case error return 409, "Service in procedure differ from services in service request's service_group"

   4. Validate procedure.service.is_active = true

      1. in case error return 409, "Service should be active"

5. Validate performed_date_time

   1.  performed_date_time is real

      1. in case error return 422, "Performed_date_time in invalid"

   2. performed_date_time <= now

      1. in case error return 422 "Procedure cannot be registered in future"

6. Validate performed_period

   1. $.performed_period.start<= now

      1. in case of error return 422 "Procedure cannot be registered in future"

   2. $.performed_period.end>= $.performed_period.start

      1. in case of error return 422 "End date must be greater than start date"

   3. Validate $.performed_period as required field in case if procedure based on service request with quantity that has code=MINUTE (system=SERVICE_UNIT)

      1. in case of error return 422 "Period is required"

7. Validate recorded_by

   1. Validate recorded_by as Reference(Referencevalidation)

   2. $..recorded_by.identifier.value is an ID of existing employee in PRM.employee

      1. in case of error  return 422, "Employee with such id is not found"

   3. Validate recorded_by is employee with status='APPROVED' and is_active= true and end_date is null or more than today and PRM.employees.employee_type in ('DOCTOR','SPECIALIST','ASSISTANT')

      1. in case error return 409, "This action is prohibited for current employee" 

   4. Validate employees.legal_entity_id=$managing_organization.identifier.value

      1. in case error return 409, "Employee should be from current legal entity"

8. Performer(asserter) validation

   1. case $..primary_source==true

      1. $..performer(or $..asserter) must be filled

         1. in case of error "Performer (asserter) must be filled"

      2. $..report_origin must be absent

         1. in case of error "Report_origin can not be submitted in case primary_source is true" 

      3. validate performer(asserter) is a valid value from corresponding dictionary

         1. $..performer.identifier.type.coding[*].system == "eHealth/resources"

            1. in case of error "Submitted system is not allowed for this field"

         2. $..performer.identifier.type.coding[*].code=="employee"

            1. in case of error "Submitted code is not allowed for this field"

      4. validate performer(asserter) is an active medical staff from current legal_entity

         1. $..performer.identifier.value is an ID of existing employee in PRM.employee

            1. in case of error "Employee with such id is not found"

         2. $..performer.identifier.value == PRM.employees.id where (PRM.employees.status == "APPROVED" and PRM.employees.employee_type in ('DOCTOR','SPECIALIST','ASSISTANT'))

   2. case primary_source=false

      1.  error 422. (Procedure with primary_source=false could be send only with encounter package)

9. Validate division

   1. Validate division as Reference(Referencevalidation)

   2. $division is an ID in PRM.divisions

      1. in case return 422, "Division with such id is not found"

   3. division.status=ACTIVE and is_active=true

      1. in case error return 409, "Division is not active"

   4. division.legal_entity_id = $client_id

      1. in case error return 409, "Division is not in current legal_entity"

10. Validate patient status

    1. Medical_data status for this patient must be in "active" status

       1. in case of error return 409 - "Patient is not active"

11. Validate managing_organization is a current active legal_entity with proper type

    1.  as Reference(Referencevalidation)

    2. $managing_organization is an ID in PRM.legal_entities

       1. in case return 422, "Legal entity with such id is not found"

    3. validate managing_organization status is 'ACTIVE' and is_active=true

       1. in case error return 422 ('Legal entity is not active')

    4. validate legal_entity type is in ('PRIMARY_CARE','MSP','MSP_PHARMACY','MSP_PHARMACY') (use `ME_ALLOWED_TRANSACTIONS_LE_TYPES` from charts)

       1. in case error return 422, "Legal entity with type $legal_entity.type cannot perform procedures"

    5. validate $managing_organization.identifier.value = $client_id

       1. in case of error 409 "Managing organization does not correspond to user's legal entity."

12. Validate reason_references

    1. Validate reason_reference as a Reference (Referencevalidation)

    2. Validate reason_refernce.identifier.value is condition not in status ENTERED_IN_ERROR

       1. in case error return 422, "Condition is canceled"

13. Validate reason_references

    1. Validate reason_reference as a Reference (Referencevalidation)

    2. Validate reason_refernce.identifier.type.coding.[0].code is condition or observation

       1. in case error return 422 "value is not allowed in enum"

    3. Validate reason_refernce.identifier.value is condition or observation not in status ENTERED_IN_ERROR

       1. in case error return 422, "Observation in "entered_in_error" status can not be referenced" if observation, else - "Condition is canceled"

14. Validate outcome

    1. validate outcome as a Reference (Referencevalidation)

    2. validate outcome.coding.object.system is in dictionary eHealth/procedure_outcomes

       1. in case error return 422, "outcome not in dictionary eHealth/procedure_outcomes"

15. Validate category

    1. according to the dictionary 'eHealth/procedure_categories' - by schemata

    2. Validate that procedure category corresponds to service category, that is references as code in procedure

       1. $.procedure.category=PRM.services.category where PRM.services.id=$.procedure.code.identifier.value

          1. in case of error return 422 "Procedure category does not match with the service category"

16. Related care plan validation in case service request has reference on care plan and procedure has reference on service request check possibility to create procedure depending on service_request[].activity remaining quantity

    1. calculate the quantity of artifacts that are contained in the request and have a link to the service request. Compare remaining_quantity from activity with the quantity of artifacts. Check that difference is greater then or equal to zero

       1. in case of error return 409 "The total amount of the prescribed service quantity exceeds quantity in care plan activity"

17. Validate patient verification status:

    1. If procedure has based_on with valid and active service request, then skip this validation.

    2. Else check patient verification_status is not equal to NOT_VERIFIED.

       1. in case of error return 409, "Patient is not verified"

18. Validate used_codes

    1. Check that the $.used_codes[*].coding[*].code belongs to the dictionary in $.used_codes[*].coding[*].system

       1. in case of error - return 422 "Value is not allowed in enum"

    2. Validate 'used_codes.coding.code'  is_active = true

       1. in case error return 409, "Value is not active"

Processing

API paragraph not found

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"
  }
}

Post-processing processes

1. Save signed_content to Media Storage

2. Save data to corresponding collection in DB

3. In case procedures.based_on was filled set $.procedures.id to related to $.service_request $.activity[].outcome_reference

4. Update $ .activity.status to in_progress if previous activity status was scheduled

5. Update the $ .activity.remaining_quantity parameter by the value achieved at  Submit Encounter Data Package: Related care plan validation (for an old activities only that has no quantity units)

6. Update remaining_quantity in the service request with a value that was calculated in the  Submit Encounter Data Package: Related care plan validation

HTTP status codes