RC_(CSI-2483,CR-441)_API. Create Care plan

Purpose

This WS allows to create Care plan with activities for a single patient.

Key points

1. Only authenticated and authorized user with employee_type from the list of CARE_PLAN_AUTHOR_EMPLOYEE_TYPES_ALLOWED config with appropriate speciality pointed in CARE_PLAN_<category>_SPECIALITIES_ALLOWED config can create a Care plan.

2. Care plan can be created from MSP, PRIMARY_CARE or OUTPATIENT legal entity.

3. Care plan can be created for persons and prepersons.

4. Care plan should be signed with DS.

5. Care plan creates in async way as all MEs.

6. Activities are added to a Care plan using Create Care Plan activities method. Thus, Care plan is being initially created without activities.

Specification

Apiary

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

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

Validate request

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

Validate Digital Sign

• Validate request is signed

  • in case of error - return 422 (“document must be signed by 1 signer but contains 0 signatures”)

• Check DS is valid and not expired

• Validate that DS belongs to the author of the Care plan ($.author)

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

    • in case of error - return 409 (“Signer DRFO doesn't match with requester tax_id“)

Validate legal entity

• Extract client_id from token.

  • in case of error - return 403 (“Your scope does not allow to access this resource. Missing allowances: care_plan:write”)

• Check legal entity status (status = ACTIVE)

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

• Check legal entity type in ME_ALLOWED_TRANSACTIONS_LE_TYPES config parameter

  • in case of error - return 409 ('client_id refers to legal entity with type that is not allowed to create medical events transactions')

Validate Care plan

Validate following within Care plan entity:

1. Subject

Validate value associated with person_id from URL, required.

• Get patient_id from URL

• Validate person\preperson status is active

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

• Hash patient_id and store into the field $.subject

2. Author

Validate value in the field $.author, required.

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

  • in case of error - return 422 ('User is not allowed to create care plan for the employee')

• Check that author is an active and approved employee and related to the legal entity (client_id from token).

  • in case of error - return 403 ('Access denied')

• Check author’s employee type:

  • for employees with employee_type from CARE_PLAN_AUTHOR_ROLE_CHECK_EMPLOYEE_TYPES config :

    • Сheck it has at least one employee role that:

      • is active and has active status

      • refers to healthcare service with providing_conditions=$.terms_of_service value

        • in case of error - return 422 ('Employee does not have active role that correspond to the submitted terms of service')

  • If DOCTOR, then no additional validations needed

• Check author’s speciality (speciality_officio == true) pointed in config for a corresponding care plan category.

  • in case of error - return 409 (“Invalid employee speciality”)

3. Category

Validate value in the field $.category, required.

• Check that value is in allowed values from eHealth/care_plan_categories dictionary (diabetics, default).

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

4. Encounter

Validate value in the field $.encounter, required.

• Check the value is valid reference on encounter resource

  • Check that encounter is active (status is not entered_in_error)

    • in case of error - return 422 ('Encounter in "entered_in_error" status can not be referenced')

  • Check that encounter belongs to patient ($.subject)

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

  • Check that encounter diagnosis is not empty in $.encounter.diagnosis

    • in case of error - return 422 ('Encounter without diagnosis can not be referenced')

• Validate primary diagnosis Condition in the Encounter:

  • Check condition codes is in allowed condition code list for the care plan’s category (chart variables in config)

    • in case of error - return 422 ('Primary diagnosis condition code and care plan category mismatch')

  • Check the condition system/codes has strict match with the value in the Addresses field

    • in case of error - return 422 ('Primary diagnosis condition codes do not match with codes in addresses') in case condition code in addresses is not the same as in the encounter diagnosis.

• Validate Episode related to the Encounter:

  • exists

    • in case of error - return 422 ('Encounter refers to episode that does not exist')

  • is active

    • in case of error - return 422 ('Encounter refers to episode that is not active')

  • it’s managing organization matches with author’s legal entity (client_id)

    • in case of error - return 422 ('Encounter is from another legal entity')

5. Addresses

Validate value in the field $.addresses, required.

• Check there is array with one element of codeable concept type

  • in case of error return 422 with type mismatch or schema validation error

• Check system is eHealth/ICD10_AM/condition_codes or eHealth/ICPC2/condition_codes dictionary

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

• Check code is value within specified dictionary above (should match primary diagnosis system/code in the Encounter)

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

6. Terms of service

Validate value in the field $.terms_of_service, required

• Check that there is values from a dictionary PROVIDING_CONDITION.

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

• Check submitted value:

  • define allowed terms_of_service for employee_type using a set of chart variables CARE_PLAN_<employee_type>_TERMS_OF_SERVICE_ALLOWED

    • in case terms_of_service not allowed for the employee_type - return 422 ('Not allowed for <employee type>')

7. Period

Validate value in the field $.period, required.

• Check $.period.start:

  • if encounter with ‘date’ check $.period.start >= encounter.date

    • in case of error - return 422 ('Care plan start date must be greater than Encounter start date')

  • if encounter with ‘period’ check $.period.start >= encounter.period.start

    • in case of error - return 422 ('Care plan start date must be greater than Encounter period start')

• Check that $.period.end >= $.period.start

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

8. Based on

Validate value in the field $.based_on, if submitted.

• Check the value is valid reference on another Care plan resource

• Validate referenced care plan:

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

    • Return 422 ('Care plan with such id is not found')

• Validate status of referenced care plan:

  • Check it is one of COMPLETED OR ACTIVE OR TERMINATED:

    • in case of error return 422 ('Care plan in status "<care_plan.status>" can not be referenced')

9. Part of

Validate value in the field $.part_of, if submitted

• Check the value is valid reference on another Care plan resource

• Validate referenced care plan:

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

    • Return 422 ('Care plan with such id is not found')

10. Supporting info

Validate value in the field $.supporting_info, if submitted

• Check that value is an array with references of type episode_of_care, procedure or diagnostic report

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

• Check that each reference:

  • is valid ME of defined type above

  • belongs to the patient ($.subject)

    • in case of error - return 422 ('<medical event type> with such ID is not found')

11. Contributors

Validate value in the field $.contributor, if submitted

• Check that value is an array with references of type employee

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

• Check that each referenced employee is active and approved

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

12. Care plan identifier

Validate that field $.id, required

• Check it is unique and in UUID format

  • in case of error - return 409 ("Care plan with such id already exists")

13. Status

Validate that field $.status, required

• Check it has value = new

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

14. Inform_with

User can pass the id of patient’s authentication method with which he wants to receive requisition number of the created care plan. The necessary authentication method can be found by Get person's auth methods

This field is optional for patient that shouldnt be authorized by confidant and set in new field inform_with and save type and phone_number in care_plans.urgent.informing_method_current. Phone number should be hashed before storing in medical_data.care_plans.urgent.informing_method_current.phone_number

This field is mandatory with type = THIRD_PERSON for patient that shouldnt be authorized by confidant using following logic:

1. persons age < no_self_registration_age global parameter

2. persons age between no_self_registration_age and person_full_legal_capacity_age global parameters and person does not have document with type from PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter

3. persons age > person_full_legal_capacity_age global parameter and exists at least one active and approved confidant person relationship for person (using following process Check confidant person relationship with person_id = person from request - expected :ok, :approved response)

   1. in case field with type does not passed for such patient - return 422 “Authentication method with type THIRD_PERSON must be submitted for this patient”

Validate value in the field $.inform_with, if submitted:

• If $.auth_method_id is specified

  • Check authentication method:

    • is exist in MPI.person_authentication_method

    • is belong to patient (MPI.person_authentication_method.person_id = $.patient_id)

    • is active (MPI.person_authentication_method.ended_at > now() and MPI.person_authentication_method.is_active = true)

      • in case of any validations fails generate error: 422, "Authentication method doesn't exist, is inactive or does not belong to this person"

  • Get value of THIRD_PERSON_CONFIDANT_PERSON_RELATIONSHIP_CHECK config parameter, if it is set to true - for authentication method type = THIRD_PERSON, check that person from value is an approved confidant for a patient from request – exists active and approved confidant person relationship between patient from request and person_id from authentication method value (using following logic: Check confidant person relationship with person_id = patient from request and confidant_person_id = value from auth method - expected :ok, :approved response)

    • in case validation fails generate error: 422, “Authentication method doesn't exist, is inactive or does not belong to this person”

• If Create Care Plan doesn't have this field, then choose that method which is returned from mpi as 

  Determination of a default authentication method and return person's active auth_methods

Generate requisition

• Generate requisition number (see Human readable requisition number) based on the care plan id

• Set care plan attribute $.requisition

Note: requisition number should be unique for each care plan and should not match with number of another entities.

Service logic

1. Save signed content to media storage

2. Save data to care_plans collection in DB according to Care plan data model

3. Fill field managing_organization with data from token of the user (details.client_id)

4. Save link from media storage to the $.signed_content_links field in care plans collection

5. Create job and return it’s id.

Send SMS notification

If patient not a preperson and his default authentication method determined by Determination of a default authentication method and return person's active auth_methods is OTP or third_person.OTP, send SMS to that patient with requisition number.

If field inform_with specified then send SMS to that patient with requisition number according to the specified communication channel.