• Purpose

• Specification

• Logic

• Request structure

• Authorize

• Headers

• Request data validation

  • Validate legal entity

  • Validate patient

  • Validate User

• Processing

• Response structure

• Post-processing processes

• HTTP status codes

Purpose

This web service allows to cancel encounter and other components of Data Package such as conditions, observations, allergy_intolerances and immunizations in case they were entered in error.

Note : You have only one attempt to cancel each package via API. In case you signed and cancelled package partly and now you need to cancel more entities from this package - appeal to eHealth administrator.

Specification

Logic

This web service allows to cancel encounter and other components of Data Package they were entered in case in error.

Request structure

See on Apiary

Example:

Authorize

Request to process the request using a token in the headers

• Verify the validity of access token

  • return 401 (“Invalid access token”) in case validation fails

• Verify token is not expired

  • in case of error - return 401 (“Invalid access token”) 

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

  • Return 403 in case 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")

Headers

Наприклад:

• Content-Type:application/json

• Authorization:Bearer {{access_token}}

• API-key:{{secret}}

Request data validation

1. Validate digital signature

   1. ds.drfo == PRM.parties.tax_id where PRM.parties.id==PRM.employees.party_id where:

      1. PRM.employees.id==$.encounter.performer.identifier.value)

      2. OR PRM.employees.id==$.approval.granted_to.identifier.value ($.approvals.granted_resources.identifier.value==$.encounter_id AND $.approvals.access_level='write')

      3. OR PRM.employees.employee_type==MED_ADMIN

2. Compare signed_content to previously created content

   1. select encounter, select * from observations, conditions, immunizations, allergy_intolerances where context.identifier.value=encounter_id and compare to signed_content (do not include statuses to comparation, cancellation_reason and  explanatory_letter )

      1. in case of inconsistencies return "Submitted signed content does not correspond to previously created content"

3. Validate diagnoses still valid

   1. if ($.encounter.status!="entered_in_error") validate ($.conditions[?(@.verification_status=="entered_in_error")].id is not IN $.encounter.diagnoses[*].condition.identifier.value)

      1. in case of error "The condition can not be canceled while encounter is not canceled" 

4. Validate encounter.status in DB != entered_in_error.

5. Validate entities refers to encounter.

6. Validate cancellation_reason

   1. $.cancellation_reason.coding[*].system == "eHealth/cancellation_reasons"

7. Validate status_reason if present

   1. $.status_reason.code is a value from the dictionary that is referenced in $.status_reason.coding[*].system

      1. in case of error - return 422 ("value is not allowed in enum")

8. If cancellation_reason in DB !=null

   1. Check cancellation_reason = ( cancellation_reason in DB)

      1. in case of error - return 422 ("cancellation_reason can’t be changed")

9. Validate entities are not canceled yet (status!= "entered_in_error")

   1. in case of error "Invalid transition"

10. Validate at least one entity in the request marked as "entered_in_error"

    1. in case of error "At least one entity should have status "entered_in_error""

11. Validate user performs action with an episode that belong to his legal entity

    1. ME.patient{patinet_id}.episodes{episode_id}.managing_organization==token.client_id

       1. in case of error return 422 "Managing_organization in the episode does not correspond to user`s legal_entity"

12. If entity is device_dispense:

    1. Check that status != “entered_in_error” and status != “completed”

       1. in case of error - return 409 error ('Device dispense in status <status> cannot be marked in error')

13. If status = entered_in_erroris set for encounter

    1. check that all entities are in request

       1. in case of error - return 422 error (“required entities %{entities}{id} was not present”)

    2. status = entered_in_erroris set for each entities

       1. in case of error - return 422 ("value is not allowed in enum")

    3. if some entities was canceled (status in DB = entered_in_error) ignore rule 8

Validate legal entity

• Validate episode belongs to the legal entity where the current user works

  • ME.episode.managing_organization==token.client_id

    • in case of error return 409 "User is not allowed to perform actions with an episode that belongs to another legal entity"

Validate patient

• Validate patient is active

  •  ME.patient.status=="active"

    • in case of error return "Patient is not active"

Validate User

• Extract user_id from token

• Get list of APPROVED employees with this user_id in current Legal Entity

• Check that for user one of the conditions is TRUE:

  • user has an employee that specified as author of the encounter ($.encounter .recorded_by.identifier.value is in the list of APPROVED employees)

  • OR check that user has an employee which has approval granted by the patient with access_level:write for this encounter resource ($.approvals.granted_resources.identifier.value==$.encounter_id AND $.approvals.granted_to.identifier.value==PRM.employees.id AND $.approvals.access_level='write')

  • OR user has an employee has MED_ADMIN employee type

  • otherwise, return error 409  "Employee is not performer of encounter, don't has approval or required employee type"

Processing

1. Save signed_content to Media Storage

2. Set status `entered_in_error` for objects, submitted with status `entered_in_error`

3. Set cancellation_reason

4. Set explanatory_letter for entities, submitted with status entered_in_error

   1. if some entities was canceled (status in DB = entered_in_error) before ignore this step

5. Deactivate corresponding diagnoses in the episode in case encounter was entered_in_error

   1. Find episode where id == encouners{encounter_id}.context.identifier.value

   2. Find record in episodes{episode_id}.diagnoses_hstr.evidence.identifier.value==encounter_id

   3. Set is_active = false for this record

6. Replace current diagnoses 

   1. Set in episodes.current_diagnoses the last record from diagnoses_history where is_active==true

Response structure

See on Apiary

Example:

Post-processing processes

API paragraph not found

HTTP status codes