Properties of a REST API method document

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.

Процеси роботи з планом лікування (care plan) | Створення первинного призначення плану лікування

Key points

1. Activity can be prequalified by the employee who has Approval granted by the patient on write Care plan resource

2. Activity shouldn’t be signed with DS

Logic

Render response with prequalification result in order to define whether the medical program could be applied in this particular case or not.

Configuration parameters

Care Plan dictionaries and configurable parameters_UA | Конфігураційні параметри

Medical Events Dictionaries and configurations | ME_ALLOWED_TRANSACTIONS_LE_TYPES

Dictionaries

eHealth/care_plan_activity_outcomes

...

PROVIDING_CONDITIONS_ALLOWED

INNM_DOSAGE

Input parameters

Description of input parameters

Request structure

See on API-specification (посилання на сторінку з API-специфікацією)

Description of the REST API request structure, exampleSee on API-specification

{
  "activity": {
    "author": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "employee"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "care_plan": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "care_plan"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "detail": {
      "kind": "service_request",
      "product_reference": {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "service"
              }
            ],
            "text": ""
          },
          "value": "97d57238-ffbe-4335-92ea-28d4de117ea3"
        }
      },
      "reason_code": [
        {
          "coding": [
            {
              "system": "eHealth/ICD10_AM/condition_codes",
              "code": "X85"
            }
          ]
        }
      ],
      "reason_reference": [
        {
          "identifier": {
            "type": {
              "coding": [
                {
                  "system": "eHealth/resources",
                  "code": "condition"
                }
              ]
            },
            "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
          }
        }
      ],
      "goal": [
        {
          "coding": [
            {
              "system": "eHealth/care_plan_activity_goals",
              "code": "diabetes_treatment"
            }
          ]
        }
      ],
      "quantity": {
        "value": 13,
        "system": "MEDICATION_UNIT",
        "code": "MG"
      },
      "scheduled_timing": {
        "event": [
          "2018-08-02T10:45:16Z"
        ],
        "repeat": {
          "bounds_duration": {
            "value": 10,
            "comparator": ">",
            "unit": "доба",
            "system": "eHealth/ucum/units",
            "code": "day"
          },
          "count": 10,
          "count_max": 20,
          "duration": 15,
          "duration_max": 25,
          "duration_unit": "day",
          "frequency": 1,
          "frequency_max": 4,
          "period": 1,
          "period_max": 3,
          "period_unit": "day",
          "day_of_week": [
            "mon"
          ],
          "time_of_day": [
            "16:00:00"
          ],
          "when": [
            "WAKE"
          ],
          "offset": 20
        },
        "code": {
          "coding": [
            {
              "system": "TIMING_ABBREVIATION",
              "code": "Q4H"
            }
          ]
        }
      },
      "location": {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "division"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      },
      "performer": {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "employee"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      },
      "daily_amount": {
        "value": 13.5,
        "system": "MEDICATION_UNIT",
        "code": "MG"
      },
      "description": "Some activity description",
      "do_not_perform": false,
      "status": "scheduled"
    }
  },
  "programs": [
    {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "medical_program"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    }
  ]
}

Headers

...

Headers

...

Request data validation

...

Mandatory

...

Description

...

Example

...

Content-Type

...

application/json

...

M

...

Тип контенту

...

Content-Type:application/json

...

Authorization

...

Bearer {{access_token}}

...

Authorization:Bearer {{access_token}}

...

API-key

...

{{mis_client_secret}}

...

API-key:{{mis_client_secret}}

Request data validation

Authorize

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)

Validate legal entity

1. Extract client_id from token

2. Check legal entity status is ACTIVE

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

3. Check legal entity type in ME_ALLOWED_TRANSACTIONS_LE_TYPES config parameter

   1. 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

1. Get Care plan identifier from the URL

2. Check Care plan:

   1. belongs to patient (from url)

      1. in case of error - return 422 ('Care plan with such id is not found')

   2. is not in final status

      1. in case of error - return 422 ('Invalid care plan status')

   3. Care plan’s period.end >= current date.

      1. in case of error - return 422 ('Care Plan end date is expired')

Validate Patient

1. Get person_id from URL

2. Validate patient status is active

   1. in case of error - return 409 ('Person is not active')

3. If patient is a person - validate patient'sverification_status is not equal to NOT_VERIFIED.

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

Validate User

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:

Validate care plan identifier

As care plan identifier should be contained in signed content, $.care_plan required in the request body.

1. Check value matches with care plan identifier from URL

   1. in case of error - return 409 ('Care Plan from url does not match to Care Plan ID specified in body')

Validate activity author

Validate value in the field $.author, required

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. Check the value is valid reference on medication resource.

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

   2. 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')

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

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

2. If $.detail.kind=service_request:

   1. Check that value is a reference on service or service_group

      1. Return 422 ('Cannot refer to medication for kind = service_request')

   2. Check service or service_group is active

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

   3. Check there is no activities (status=scheduled, in_progress) with the same service or service_group in the Care plan

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

3. Reason code

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

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

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

4. Reason reference

Validate value in the field $.detail.reason_reference, 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:

   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. 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, if submitted

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

   1. Return 422 schema validation error

...

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')

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>')

7. Scheduled

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

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

...

1. Validate value with schema of the Period type

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

2. 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')

8. Location

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

1. Check the value is valid reference on division resource

2. Check the division is active and division’s legal entity has active status

   1. Return 422 ('Division is not active')

9. Performer

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

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. Check it is false

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

12. Status

Validate value in the field $.status

1. Check it has value = scheduled

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

Validate programs

Validate value in the field $.programs

...

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

Processing

A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST APIN/A

Response structure examples

See on API-specification (посилання на сторінку з API-специфікацією)Description of the REST API response structure, example

{
  "meta": {
    "code": 200,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": [
    {
      "program_id": "59781de0-2e64-4359-b716-bcc05a32c10f",
      "program_name": "Fee-For-Service",
      "status": "INVALID",
      "rejection_reason": "Service is not included in the program"
    }
  ],
  "urgent": {
    "authentication_method_current": {
      "type": "OTP",
      "number": "+38093*****85"
    }
  }
}

{
  "meta": {
    "code": "422",
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "error": {
    "type": "unverified",
    "message": "Patient is not active"
  }
}

HTTP status codes

Post-processing processes

Description of actions performed on data after processing

Technical modules where the method is used

List of pages describing technical N/A

Technical modules where the method is used

...