Purpose

This WS allows prequalifying care plan activity in order to define whether the medical program could be applied in this particular case or not.

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/2125038637/care+plan#%D0%A1%D1%82%D0%B2%D0%BE%D1%80%D0%B5%D0%BD%D0%BD%D1%8F-%D0%BF%D0%B5%D1%80%D0%B2%D0%B8%D0%BD%D0%BD%D0%BE%D0%B3%D0%BE-%D0%BF%D1%80%D0%B8%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%BD%D1%8F-%D0%BF%D0%BB%D0%B0%D0%BD%D1%83-%D0%BB%D1%96%D0%BA%D1%83%D0%B2%D0%B0%D0%BD%D0%BD%D1%8F

Specification

...

Link

...

https://medicaleventsmisapi.docs.apiary.io/#reference/care-plan/prequalify-care-plan-activity/prequalify-care-plan-activity

...

Resource

...

/api/patients/{{patient_id}}/care_plans/{{care_plan_id}}/activities/prequalify

...

Scope

...

care_plan:write

...

Components

...

Care plan

...

Microservices

me/api-medical-events

me/event-consumer

...

Purpose

This WS allows prequalifying care plan activity in order to define whether the medical program could be applied in this particular case or not.

https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/2125038637/care+plan#%D0%A1%D1%82%D0%B2%D0%BE%D1%80%D0%B5%D0%BD%D0%BD%D1%8F-%D0%BF%D0%B5%D1%80%D0%B2%D0%B8%D0%BD%D0%BD%D0%BE%D0%B3%D0%BE-%D0%BF%D1%80%D0%B8%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%BD%D1%8F-%D0%BF%D0%BB%D0%B0%D0%BD%D1%83-%D0%BB%D1%96%D0%BA%D1%83%D0%B2%D0%B0%D0%BD%D0%BD%D1%8F

Specification

...

1. Verify the validity of access token

   1. Return (401, 'Invalid access token') in case of validation fails

2. Verify that token is not expired

   1. in case of error - return (401, 'Invalid access token')

3. Check user scopes in order to perform this action (scope = 'care_plan:write')

   1. Return (403, 'Your scope does not allow to access this resource. Missing allowances: care_plan:write') in case of invalid scope(s)

Headers

Наприклад:

Content-Type:application/json
Authorization:Bearer {{access_token}}
API-key:{{mis_client_secret}}

...

1. Extract user_id from token.

2. Check user has an active and approved employee from legal entity (token) that:

   1. has an active Approval granted by the Patient on write the Care plan resource (care plan id from URL)

      1. Return 403 ('Access denied') in case employee has no Approval on write

3. Check user's employee is from the same legal entity (token) as managing_organisation from the care_plan:

   1. Return 422 ('User is not allowed to create care plan activity for this care plan') in case employee’s legal_entity do not match managing_organisation of related care_plan

Validate activity

1. Activity should be validated. User fills following fields in the activity:

...

1. Check employee belongs to the user and legal entity (from token)

2. Employee is:

   1. an employee who has active Approval on write the Care plan

   2. belongs to user

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

Validate activity detail

1. Kind

Validate value in the field $.detail.kind, required

1. Check value in enum: medication_request, service_request

   1. Return 422 ('value is not allowed in enum')

2. Product

Validate value in the field $.detail.product_reference, required

1. If $detail.kind=medication_request:

   1. 1. of error - return 422 ('User is not allowed to create care plan activity for the employee')

Validate activity detail

1. Kind

Validate value in the field $.detail.kind, required

1. Check value in enum: medication_request, service_request

   1. Return 422 ('value is not allowed in enum')

2. Product

Check there is one of the required $.detail.product_[x] field is set: product_reference or product_codeable_concept.

• Return 422 ('Only one of the parameters must be present') in case more then one submitted

1. If $detail.kind=medication_request:

   1. Check $.detail.product_reference field is submitted and has Reference type

      • in case it isn’t submitted - return 422 ('can't be blank')

      • in case of wrong type - return 422 ('type mismatch')

   2. Check the value is valid reference on medication resource.

      1. Return 422 ('Cannot refer to service <resource> for kind = medication_request')

   3. Check medication:

      1. is active

         1. in case of error - return 422 ('Medication should be active')

      2. type is INNM_DOSAGE

         1. in case of error - return 422 ('Medication does not exist')

2. If $.detail.kind=service_request:

   1. Check $.detail.product_reference field is submitted and has Reference type

      • in case it isn’t submitted - return 422 ('can'

      Medication should

      • t be

      active

      • blank')

      type is INNM_DOSAGE

      • in case of

      error

      • wrong type - return 422 ('

      Medication does not exist

      • type mismatch')

   2. Check there is no duplicated activities (status=scheduled, in_progress) with the same medication in the Care plan

      Return 422 (“Another activity with status ‘scheduled' or ‘in_progress' already exists in the current Care plan”

      that value is a reference on service or service_group

      1. Return 422 ('Cannot refer to <resource> for kind = service_request')

   3. Check service or service_group is active

      1. Return 422 ('<Service/Service group> should be active')

3. If $.detail.kind=service_requestdevice_request:

   • Validate product_reference:

     • Check

   that

   • • there value is

   a reference on service or service_group

   • • valid Reference on device_definition resource

       • Return 422 ('Cannot refer to

   medication

   • • • <resource> for kind =

   service

   • • • device_request')

     • Check

   service or service_group

   • • the device_definition is active

       • Return 422 ('

   <Service/Service group> should be active'

   • • • Device definition is not active')

   • Validate product_codeable_concept:

     • Check that value matches with active values in device_definition_classification_type dictionary.

       • Return 422 ('value is not allowed in enum')

   Check there is no another activities (status=scheduled, in_progress) in the Care plan with the same

   service or service_group in the Care plan

   product_reference or product_codeable_concept, and program = $.detail.program

   • Return 422 (“Another activity with status ‘scheduled' or ‘in_progress' already exists in the current Care

   plan“

   • plan within current program value“)

3. Reason code

Validate value in the field $.detail.reason_code, if submitted

...

1. Check that value is an array with references of condition, observation, diagnostic report, clinical impression types.

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

2. Check that each reference:

   1. is valid ME

   2. belongs to the patient ($.subject)

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

3. If $.detail.reason_reference=clinical_impression:

   Check that value matches with values in eHealth/care_plan_activity_goals dictionary

   1. Check that clinical impression is valid based on clinical_impression.code.coding.code and CLINICAL_IMPRESSION_PATIENT_CATEGORIES_<CODE.VALUE>_VALIDITY_PERIOD chart parameter: difference between now() and $.clinical_impression.effective_date_time OR $.clinical_impression.effective_period.end date must be less than a value in chart parameter (pointed in config for a corresponding care plan category) for clinical impression code

      1. in case of error - return 422 ("Clinical impression with patient category exceeds validity period")

   2. Check that clinical impression is based on active rule engine rule (exists record in rule_engine_rules collection with is_active=true, code.code=clinical_impression.code.coding.code, code.system=clinical_impression.code.coding.system)

      1. if true - check that clinical impression still corresponds to configured rule

         1. in case of error - return 422 (“Clinical impression with patient category does not correspond to rule engine rule“)

      2. if false - skip rule validation

5. Goal

Validate value in the field $.detail.goal, if submitted

1. 1. $.clinical_impression.effective_date_time OR $.clinical_impression.effective_period.end date must be less than a value in chart parameter (pointed in config for a corresponding care plan category) for clinical impression code

      1. in case of error - return 422 (

      'value is not allowed in enum')

6. Quantity

Validate value in the field $.detail.quantity, if submitted

1. Check $.detail.quantity.value is not empty, is fractional, greater than zero

   1. Return 422 schema validation error

Validate $.detail.quantity.system, $.detail.quantity.code and their values in the object $.detail.quantity

1. If $.detail.kind=medication_request:

   1. Check (by schemata) the $.detail.quantity.system field’s value is MEDICATION_UNIT.

      1. Return 422 ('value is not allowed in enum')

   2. Check the $.detail.quantity.code field’s value equals to dosage.denumerator_unit of one of INNMs of a INNM_DOSAGE where innms with is_primary = true

      1. Return 422 ('Code field of quantity object should be equal to denumerator_unit of one of medication’s innms')

2. If $.detail.kind is other than medication_request:

   1. Check the $.detail.quantity.system field is not present.

      1. Return 422 ('System field of quantity object is not allowed for kind other than medication_request')

   2. Check the $.detail.quantity.code field is not present.

      1. Return 422 ('Code field of quantity object is not allowed for kind other than medication_request')"Clinical impression with patient category exceeds validity period")

   3. Check that clinical impression is based on active rule engine rule (exists record in rule_engine_rules collection with is_active=true, code.code=clinical_impression.code.coding.code, code.system=clinical_impression.code.coding.system)

      1. if true - check that clinical impression still corresponds to configured rule

         1. in case of error - return 422 (“Clinical impression with patient category does not correspond to rule engine rule“)

      2. if false - skip rule validation

5. Goal

Validate value in the field $.detail.goal, if submitted

1. Check that value matches with values in eHealth/care_plan_activity_goals dictionary

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

6. Quantity

Validate value in the field $.detail.quantity

1. Check it is submitted if $.detail.kind=device_request

   • Return 422 ('required property quantity was not present')

2. Check $.detail.quantity.value is not empty, is fractional, greater than zero

   1. Return 422 schema validation error

Validate $.detail.quantity.system, $.detail.quantity.code and their values in the object $.detail.quantity

1. If $.detail.kind=servicemedication_request:

2. Validate value with schema of Timing type

   1. in case of error - return 422 schema validation error

3. If submitted, check values of the event within $.CarePlan.Period value

   1. in case of error - return 422 ('event is not within care plan period range')

4. If submitted, check bounds_period within $.CarePlan.Period value

   1. in case of bounds_period.end validation error - return 422 ('Period end time must be within care plan period range, after period start date')

   2. in case of bounds_period.start validation error - return 422 ('Period start time must be within care plan period range')

5. If submitted, check bounds_duration within $.CarePlan.Period value. Calculate bounds start date as care plan period start date if activity creates before care plan has started, else if activity creates during care plan performing - bound start date calculates as activity creation date. Bounds end date as bounds start date plus count of days specified in bounds_duration.

   1. If comparator field in bounds_duration - use it to compare bounds_duration value and care plan duration (possible values >, >=, =, <=, <)

   2. in case of error - return 422 ('Bounds duration must be within care plan period range')

6. If submitted, check when field values are in EVENT_TIMING dictionary

   1. Check that (by schemata) the $.detail.quantity.system field’s value is SERVICEMEDICATION_UNIT, if submitted.

      1. Return 422 ('value is not allowed in enum')

      If care plan category is class_23, class_24 or class_25:

      Check

   2. Check the $.detail.quantity.

      system and $.detail.quantity.code are set, $.detail.quantity.code = MINUTE

      1. Return 422 ('Code field of quantity object should be in MINUTE for care plan’s category <category code>')

7. Scheduled

1. If submitted, validate there is one of the $.detail.scheduled_[x] field: scheduled_timing, scheduled_period or scheduled_string.

2. Return 422 ('Only one of the parameters must be present') in case more then one submitted

Validate value in scheduled_timing, if submitted:

1. 1. in case of error - return code field’s value equals to dosage.denumerator_unit of one of INNMs of a INNM_DOSAGE where innms with is_primary = true

      1. Return 422 ('Code field of quantity object should be equal to denumerator_unit of one of medication’s innms')

2. Check the $.detail.quantity.code field’s value equals to dosage.denumerator_unit of one of INNMs of a INNM_DOSAGE where innms with is_primary = true

   • Return 422 ('Code field of quantity object should be equal to denumerator_unit of one of medication’s innms')

3. If $.detail.kind=service_request:

   1. Check that $.detail.quantity.system field’s value is SERVICE_UNIT, if submitted.

      1. Return 422 ('value is not allowed in enum')

   2. If care plan category is class_23, class_24 or class_25:

      1. Check $.detail.quantity.system and $.detail.quantity.code are set, $.detail.quantity.code = MINUTE

         1. Return 422 ('Code field of quantity object should be in MINUTE for care plan’s category <category code>')

4. if $.detail.kind=device_request:

   if submitted, check time_of_day match regex ^([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?$

   • Check $.detail.quantity.value is not empty, is integer, greater than zero

     • Return 422 schema validation error

   • Check the $.detail.quantity.system is device_unit dictionary.

     • Return 422 ('value is not allowed in enum')

   • Check that $.detail.quantity.code matches to active values from $.detail.quantity.system.

     • Return 422 ('value is not allowed in enum')

5. If submitted, check bounds_range within $.CarePlan.Period value: calculate bounds start - end date for bounds_range.low and bounds_range.high as described for bounds_duration (but w/o comparator field). Also, validate low.code = high.code, high.value > low.value

   1. in case bounds_range.low validation error - return 422 ('low must be within care plan period range, less than high, have the same code as high')

   2. in case bounds_range.high validation error - return 422 ('high must be within care plan period range')

6. if submitted, check day_of_week field values are in DAYS_OF_WEEK dictionary

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

7. • Validate Device Definitions in case $.detail.product_codeable_concept and $.detail.program was set:

     • Find all active Device Definitions with packaging_unit that matches to $.detail.quantity.code

     • Check that there is at least one device definition where the remainder of division $.detail.quantity.value/packaging_count is equal to zero

       • Return 422 ('Not found any appropriate Device Definition')

   • Validate Device Definition in case $.detail.product_reference was set:

     • Get Device Definition in the $.detail.product_reference (depends on what was set)

     • Check it has packaging_unit that matches to $.quantity.code of the Activity

       • Return 422 ('Device Definition must have the same units of measure as pointed in the quantity of the Activity')

     • Check the remainder of division $.detail.quantity.value / device_definition.packaging_count is equal to zero

       • Return 422 ('The amount of devices in device request must be divisible to device package quantity')

7. Scheduled

As this method always requires medical programs on its input, so scheduled_period required also:

1. Validate value with schema of the Period type

   1. in case of error - return 422 ('string does not match pattern')

Validate value in scheduled_period, if submitted:

1. Validate value with schema of the Period type

   1. in case of error - return 422 schema validation errorschema validation error

2. Validate $.scheduled_period.end is present:

   • in case it isn’t submitted - return 422 ('can't be blank')

3. Check values within $.CarePlan.Period

   1. in case period.end validation error - return 422 ('Period end time must be within care plan period range, after period start date')

   2. in case period.start validation error - return 422 ('Period start time must be within care plan period range')

...

1. Check the value is valid reference o employee resource

2. Check employee is active and approved

   1. Return 422 ('Invalid employee status')

10. Daily amount

1. If submitted, check $.detail.daily_amount has the same code and system as quantity field.

   1. Return 422 ('Units of daily_amount field should be equal to units of quantity field')

2. Validate value in the field $.detail.daily_amount, if submitted.

3. Check activity kind is medication_request

   1. Return 422 ('Field is allowed for medication request activities only') in case kind is not medication_request

4. Validate $.detail.daily_amount.system, $.detail.daily_amount.code fields and their values in the object $.detail.daily_amount

5. If $.detail.kind=medication_request:

   1. Check (by schemata) the $.detail.daily_amount.system field’s value is MEDICATION_UNIT.

      1. Return 422 ('value is not allowed in enum')

   2. Check the $.detail.daily_amount.code field’s value equals to dosage.denumerator_unit of one of INNMs of a INNM_DOSAGE where innms with is_primary = true

      1. Return 422 ('Code field of daily_amount object should be equal to denumerator_unit of one of medication’s innms')

6. If $.detail.kind is other than medication_request:

   1. Check the $.detail.daily_amount.system field is not present.

      1. Return 422 ('System field of daily_amount object is not allowed for kind other than medication_request')

   2. Check the $.detail.daily_amount.code field is not present.

      1. Return 422 ('Code field of daily_amount object is not allowed for kind other than medication_request')

11. Do not perform flag

Validate value in the field $.do_not_perform

...

1. Сheck program exists and active

   1. in case not found or is_active==false return 422 'Program not found'

2. Validate product is program participant:

   1. If product is medication - validate:

      1. that medication has brand that is an active member of the program (program_medications table)

         1. in case not found or is_active==false return 200 with status = INVALID and rejection_reason "Medication is not included in the program"

      2. that care_plan_activity_allowed for program medication == true

         1. in case ==false return 422 "Forbidden to create care plan activity for this medication!"

   2. If product is service - validate that service is an active member of the program

      1. in case not found or is_active==false return 200 with status = INVALID and rejection_reason "Service is not included in the program"

   3. if product is service_group - validate that service group is an active member of the program

      in case not found or is_active==false return 200 with status = INVALID and rejection_reason "Service group is not included in the program"

      the program

      1. in case not found or is_active==false return 200 with status = INVALID and rejection_reason "Service group is not included in the program"

   4. If product is code from device_definition_classification_type dictionary (product_codeable_concept was set) or product is device_definition (product_reference was set):

      • Find all program devices with:

        • is_active=true

        • care_plan_activity_allowed = true

        • period (start_date and end_date) that includes current date

        • max_daily_count >= $.quantity.value/($.detail.scheduled_period.end - $.detail.scheduled_period.start + 1). Count scheduled_period length in days, without taking into account time

        • related to the Device Definitions that has successfully passed Quantity and Product validations before

          • in case not found return 422 ('No appropriate participants found for this medical program')

3. Validate medical program settings (prm.medical_programs table):

   1. if there is a parameter speciality_types_allowed:

      1. Check author’s speciality is present in speciality_types_allowed

         1. in case of error - return 200 with status = INVALID and rejection_reason “Author’s specialty doesn't allow to create activity with medical program from request”

   2. if there is a parameter conditions_icd10_am_allowed or/and conditions_icpc2_allowed:

      1. Check related Care plan has condition codes in addresses field that correspond to codes pointed in conditions_icd10_am_allowed or/and conditions_icpc2_allowed (depending on dictionary - eHealth/ICD10_AM/condition_codes or eHealth/ICPC2/condition_codes)

         1. in case of error - return 200 with status = INVALID and rejection_reason “Care plan diagnosis is not allowed for the medical program“

   3. If there is a parameter providing_conditions_allowed:

      1. Check related Care plan has a value in terms_of_service field that is included in the list of providing_conditions_allowed parameter

         1. in case of error - return 200 with status = INVALID and rejection_reason “Care plan’s terms

         _of_service field that is included in the list of providing_conditions_allowed parameter

         1. of service are not allowed for the medical program“

   4. if there is a parameter patient_categories_allowed:

      1. check that patient_categories_allowed has codes in $.detail.reason_reference.[].clinical_impression.code.[].codethat correspond to codes pointed in patient_categories_allowed

         1. in case of error - return 200 with status = INVALID and with rejection_reason “Care plan’s terms of service are not allowed for the medical program“

      if there is a parameter patient_categories_allowed:

      1. check that patient_categories_allowed has codes in $.detail.reason_reference.[].clinical_impression.code.[].codethat correspond to codes pointed in patient_categories_allowed

         1. in case of error return 200 with status = INVALID with rejection_reason ("Clinical impression with patient category should be present in request ("Clinical impression with patient category should be present in request for this medical program")

   5. if there is parameter device_request_allowed_code_types and activity kind=device_request, then check values in the array of values:

      • if it includes CLASSIFICATION_TYPE - it is allowed to set $.detail.product_codeable_concept in the activity

      • if it includes DEVICE_DEFINITION - it is allowed to set $.detail.product_reference in the activity

        • in case of a mismatch between the filled field and the config values - return 422 ("<Device definition/Device classification type> is not allowed to set for this medical program").

If program meets the requirements write status "VALID" according to apiary.

...