Purpose

This web service is designed to return episodes by search parameters.

Specification

Link	https://medicaleventsmisapi.docs.apiary.io/#reference/medical-events/episode-of-care/get-episodes-by-search-params
Resource	/api/patients/{{patient_id}}/episodes
Scope	episode:read
Components	Episode of Care
Microservices	API paragraph not found
Protocol type	REST
Request type	GET
Sync/Async	Async
Public/Private/Internal	Public

Logic

Use period_from period_to to find episodes that were active in a certain period of time.

Filters

Filter	Type	Description	Example
patient_id	String	Patient identifier	`70a9e15b-b71b-4caf-8f2e-ff247e8a5677`
page	Number	Page number	`2`
page_size	Number	A limit on the number of objects to be returned, between 1 and 100. Default: 50	`50`
period_from	String		`2017-01-01`
period_to	String		`2017-01-01`
code	String		`R80`
status	String		`active`
managing_organization_id	String		`80a9e15b-b71b-4caf-8f2e-ff247e8a5677`

Request structure

API paragraph not found

Authorize

Request to process the request using a token in the headers

Verify the validity of access token
- Return 401 in case validation fails
Verify token is not expired
- in case of error return 401
Check user scopes in order to perform this action (scope = 'episode:write')
- Return 403 in case invalid scope(s)

Headers

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

Request data validation

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"
Validate episode id is unique
1. $.id is unique
  1. in case of error return 422 - "Episode with such id already exists"
~~Validate that episode number is unique~~
1. ~~$.number is unique~~
  1. ~~in case of error return 409 - "Episode with such number already exists. Episode number must be unique"~~
Validate request according to JSON Schema LINK
1. in case of error return 422
Validate type
1. according to legal entity type: Medical Events Dictionaries and configurations#legal_entity_episode_types
  1. in case of error return 409 "Episode type <type> is forbidden for your legal entity type"
2. according to employee type: Medical Events Dictionaries and configurations#employee_episode_types
  1. in case of error return 409 "Episode type <type> is forbidden for your employee type"
~~Validate status= "active"~~ - resolved by JSON schema
Validate managing_organization
1. Only one item is allowed in coding array
  1. in case of error return 422 "Only one item is allowed in "coding" array "
2. $.managing_organization.identifier.type.coding.[0].code = "legal_entity"
  1. in case of error return 422 "Only legal_entity could be submitted as a managing_organization"
3. $.managing_organization.identifier.value = token.client_id
  1. in case of error return 422 "Managing_organization does not correspond to user`s legal_entity"
4. $.managing_organization.identifier.type.coding.[0].system = "eHealth/resources"
  1. in case of error return 422 "Submitted system is not allowed for this field"
Validate period
1. $.period.start <= current_date
  1. in case of error return 422 - "Start date of episode must be in past"
2. $.period.end is absent
  1. in case of error return 422 - "End date of episode could not be submitted on creation"
Validate care_manager
1. $.care_manager.identifier.type.coding.[0].code = "employee"
  1. in case of error return 422 "Only employee could be submitted as a care_manager"
2. $.care_manager.identifier.type.coding.[0].system = "eHealth/resources"
  1. in case of error return 422 "Submitted system is not allowed for this field"
3. $.care_manager.identifier.value must meet the following requirements
  1. PRM.employee.type = "DOCTOR" OR "SPECIALIST" OR "ASSISTANT"
    1. in case of error return 409 "Employee submitted as a care_manager is not in the list of allowed employee types"
  2. PRM.employee.status= "active"
    1. in case of error return 409 "Employee submitted as a care_manager is not active"
  3. PRM.employee.legal_entity = token.client_id
    1. in case of error return 409 "User can create an episode only for the doctor that works for the same legal_entity"
4. $.care_manager.identifier.value belongs to one of the user’s employee
  1. in case of error return 422 "Employee is not care manager of episode"

Error example:

{:error, [{%{

description: "Episode with such id already exists",

params: [],

rule: :invalid

}, "$.id"}]}

Access to the resource is also managed by ABAC module.

Processing

Set episodes.care_manager.display_value = ((PRM.parties.first_name + PRM.parties.second_name + PRM.parties.last_name) where PRM.parties.id == PRM.employees.party_id) where PRM.employees.id== $.care_manager.identifier.value
Set episodes.managing_organization.display_value = PRM.legal_entities.public_name where ( PRM.legal_entities.id == $.managing_organization.identifier.value)
Create a record in status_hstr

Response structure

See on Apiary

Example:

Response example

{
  "meta": {
    "code": 200,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": [
    {
      "id": "90a9e15b-b71b-4caf-8f2e-ff247e8a5600",
      "inserted_at": "2018-08-02T10:45:16.000Z",
      "updated_at": "2018-08-02T10:45:16.000Z",
      "type": {
        "system": "eHealth/episode_types",
        "code": "primary_care"
      },
      "status": "active",
      "name": "Діабет 2018",
      "current_diagnoses": [
        {
          "condition": {
            "identifier": {
              "type": {
                "coding": [
                  {
                    "system": "eHealth/resources",
                    "code": "condition"
                  }
                ]
              },
              "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
            },
            "display_value": "null"
          },
          "code": {
            "coding": [
              {
                "system": "eHealth/ICPC2/conditions",
                "code": "A20"
              }
            ]
          },
          "role": {
            "coding": [
              {
                "system": "eHealth/diagnosis_roles",
                "code": "CC"
              }
            ]
          },
          "rank": 1
        }
      ],
      "diagnoses_history": [
        {
          "date": "2018-08-02T10:45:16.000Z",
          "evidence": {
            "identifier": {
              "type": {
                "coding": [
                  {
                    "system": "eHealth/resources",
                    "code": "encounter"
                  }
                ]
              },
              "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
            },
            "display_value": "null"
          },
          "diagnoses": [
            {
              "condition": {
                "identifier": {
                  "type": {
                    "coding": [
                      {
                        "system": "eHealth/resources",
                        "code": "condition"
                      }
                    ]
                  },
                  "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
                },
                "display_value": "null"
              },
              "code": {
                "coding": [
                  {
                    "system": "eHealth/ICPC2/conditions",
                    "code": "A20"
                  }
                ]
              },
              "role": {
                "coding": [
                  {
                    "system": "eHealth/diagnosis_roles",
                    "code": "CC"
                  }
                ]
              },
              "rank": 1
            },
            {
              "condition": {
                "identifier": {
                  "type": {
                    "coding": [
                      {
                        "system": "eHealth/resources",
                        "code": "condition"
                      }
                    ]
                  },
                  "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
                },
                "display_value": "null"
              },
              "code": {
                "coding": [
                  {
                    "system": "eHealth/ICPC2/conditions",
                    "code": "A20"
                  }
                ]
              },
              "role": {
                "coding": [
                  {
                    "system": "eHealth/diagnosis_roles",
                    "code": "CC"
                  }
                ]
              },
              "rank": 1
            }
          ]
        }
      ],
      "status_history": [
        {
          "status": "active",
          "status reason": {
            "coding": [
              {
                "system": "eHealth/episode_closing_reasons",
                "code": "cured"
              }
            ]
          },
          "inserted_at": "2018-08-02T10:45:16.000Z"
        }
      ],
      "managing_organization": {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "legal_entity"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        },
        "display_value": "Медікал Солюшнc"
      },
      "period": {
        "start": "2018-08-02T10:45:16.000Z",
        "end": "2018-08-03T10:45:16.000Z"
      },
      "care_manager": {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "employee"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        },
        "display_value": "null"
      },
      "closing_summary": "Носові шляхи вільні, горло рожеве, температура в нормі",
      "status_reason": {
        "coding": [
          {
            "system": "eHealth/episode_closing_reasons",
            "code": "cured"
          }
        ]
      },
      "explanatory_letter": "Епізод був відмінений у зв'язку з помилкою при виборі пацієнта"
    }
  ],
  "paging": {
    "page": 2,
    "page_size": 50,
    "total_entries": 1000,
    "total_pages": 20
  }
}

Order by inserted_at
In case of searching by code:
1. select episode where ME.patients.episodes.current_diagnoses[*].code.coding[*].code == code(search param)

Post-processing processes