...

Properties of a REST API method document

...

Document type

...

Метод REST API

...

Document title

...

[Document status] REST API [Назва методу] [ID методу]

...

Guideline ID

...

GUI-0011

...

Author

...

@

...

Document version

...

1

...

Document status

...

DRAFT

...

Date of creation

...

ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)

...

Date of update

...

ХХ.ХХ.ХХХХ (дата зміни версії)

...

Method API ID

...

API-007-001-001-0218

...

Microservices (namespace)

...

ME

...

Component

...

Care plan

...

Component ID

...

COM-007-001

...

Link на API-специфікацію

...

https://ehealthmedicaleventsapi.docs.apiary.io/#reference/care-plan/create-care-plan/create-care-plan

...

Resource

...

{{host}}/api/patients/{{patient_id}}/care_plans

Note
Сторінка знаходиться в процесі розробки. Інформація на ній може бути застарілою.

/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)

Properties of a REST API method document

Document type	Метод REST API
Document title	[DRAFT] Create Care Plan [API-007-001-001-0218]
Guideline ID	GUI-0011
Author	@
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-007-001-001-0218
Microservices (namespace)	ME
Component	Care plan
Component ID	COM-007-001
Link на API-специфікацію	https://medicaleventsmisapi.docs.apiary.io/#reference/care-plan/create-care-plan/create-care-plan
Resource	{{host}}/api/patients/{{patient_id}}/care_plans
Scope	care_plan:write
Protocol type	REST
Request type	POST
Sync/Async	Async(def)/Sync
Public/Private	Public

Purpose

This method allows to create Care Plan for a person in eHealth

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

Key points

Only authenticated and authorized user with employee_type from the list ofCARE_PLAN_AUTHOR_EMPLOYEE_TYPES_ALLOWED
config with appropriate speciality pointed in CARE_PLAN_<category>_SPECIALITIES_ALLOWEDconfig can create a Care plan.
Care plan can be created from MSP, PRIMARY_CARE or OUTPATIENT legal entity.
Care plan can be created for persons and prepersons.
Care plan should be signed with DS.
Care plan creates in async way as all MEs.
Activities are added to a Care plan using Create Care Plan activity method. Thus, Care plan is being initially created without activities.

Logic

This method allows to create Care Plan for a person in eHealth. Method receives signed message (pkcs7) that consists of signed content, digital signature and signer public key. All signature fields will be validated (including signer certificate authority). Service will store signed copy of Care Plan in Media Content Storage if all checks is passed.

Service logic

Save signed content to media storage
Save data to care_plans collection in DB according to RC_REHAB_Care plan data model+
Fill field managing_organization with data from token of the user (details.client_id)
Save link from media storage to the $.signed_content_links field in care plans collection
Create job and return it’s id.

Configuration parameters

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

Medical Events Dictionaries and configurations | ME_ALLOWED_TRANSACTIONS_LE_TYPES

Dictionaries

eHealth/care_plan_categories

...

eHealth/ICD10_AM/condition_codes

PROVIDING_CONDITION

Input

...

parameters

	Input parameter	Mandatory	Type	Description	Example
1	patient_id		String	MPI identifier of the person	`7075e0e2-6b57-47fd-aff7-324806efa7e5`

Request structure

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

...

-324806efa7e5

Request structure

See on API-specification

Expand

title	Request example

Code Block
{ "signed_data": "ew0KICAicGVyaW9kIjogew0KIC..." }

...

Expand

title	Request example

Code Block

language	json

{
  "id": "90a9e15b-b71b-4caf-8f2e-ff247e8a5600",
  "based_on": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "care_plan"
          }
        ]
      },
      "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
    }
  },
  "part_of": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "care_plan"
          }
        ]
      },
      "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
    }
  },
  "category": {
    "coding": [
      {
        "system": "eHealth/care_plan_categories",
        "code": "diabetics"
      }
    ]
  },
  "title": "Diabetics health plan",
  "description": "Some description of the care plan",
  "period": {
    "start": "2018-08-02T10:45:16.000Z",
    "end": "2018-08-02T11:00:00.000Z"
  },
  "supporting_info": [
    {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "episode_of_care"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    }
  ],
  "note": "Some notes",
  "intent": "order",
  "encounter": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "encounter"
          }
        ]
      },
      "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
    }
  },
  "addresses": [
    {
      "coding": [
        {
          "system": "eHealth/ICD10_AM/condition_codes",
          "code": "E11.9"
        }
      ]
    }
  ],
  "author": {
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "eHealth/resources",
            "code": "employee"
          }
        ]
      },
      "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
    }
  },
  "contributor": [
    {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "employee"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    }
  ],
  "terms_of_service": {
    "coding": [
      {
        "system": "PROVIDING_CONDITION",
        "code": "INPATIENT"
      }
    ]
  },
  "inform_with": {
    "auth_method_id": "cc949559-5dfe-420f-ac05-065e443b2cc6"
  },
  "status": "new"
}

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

...

API-key:{{mis_client_secret}}

...

Authorize

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)
Request to process the request using a token in the headers
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")

Validate request

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

Validate Digital Sign

Validate request is signed
1. 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)
1. Check that DRFO from DS and party.tax_id of the author matches
  1. in case of error - return 409 (“Signer DRFO doesn't match with requester tax_id“)

Validate legal entity

Extract client_id from token.
1. 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)
1. 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
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

Validate following within Care plan entity:

1. Subject

Validate value associated with person_id from URL, required.

...

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.
1. 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).
1. in case of error - return 403 ('Access denied')
Check author’s employee type:
1. for employees with employee_type from CARE_PLAN_AUTHOR_ROLE_CHECK_EMPLOYEE_TYPESconfig:
  1. Сheck it has at least one employee role that:
    1. is active and has active status
    2. refers to healthcare service with providing_conditions=$.terms_of_service value
      1. in case of error - return 422 ('Employee does not have active role that correspond to the submitted terms of service')
2. If DOCTOR, then no additional validations needed
Check author’s speciality (speciality_officio == true) pointed in config for a corresponding care plan category.
1. in case of error - return 409 (“Invalid employee speciality”)

3. Category

Validate value in the field $.category, required.

...

Info
If new category added to the dictionary, then corresponding config parameters in charts should be created

4. Encounter

Validate value in the field $.encounter, required.

Check the value is valid reference on encounter resource
1. Check encounter is active (status is not entered_in_error)
  1. in case of error - return 422 ('Encounter in "entered_in_error" status can not be referenced')
2. Check encounter belongs to patient ($.subject)
  1. in case of error - return 422 ('Encounter with such id is not found')
3. Check that encounter diagnosis is not empty in $.encounter.diagnosis
  1. in case of error - return 422 ('Encounter without diagnosis can not be referenced')
Validate primary diagnosis Condition in the Encounter:
1. Check condition codes is in allowed condition code list for the care plan’s category (chart variables in config: for employee types: SPECIALIST, DOCTOR and MED_COORDINATOR)
  1. in case of error - return 422 ('Primary diagnosis condition code and care plan category mismatch')
2. Check the condition system/codes has strict match with the value in the Addresses field
  1. 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:
1. exists
  1. in case of error - return 422 ('Encounter refers to episode that does not exist')
2. is active
  1. in case of error - return 422 ('Encounter refers to episode that is not active')
3. it’s managing organization matches with author’s legal entity (client_id)
  1. 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
1. 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
1. 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)
1. 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.
1. in case of error - return 422 ('value is not allowed in enum')
Check submitted value:
1. define allowed terms_of_service for employee_type using a set of chart variables CARE_PLAN_<employee_type>_TERMS_OF_SERVICE_ALLOWED
  1. 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 that $.period.start >= encounter.date (OR encounter.period.start)
1. in case of error and encounter.period.start - return 422 ('Care plan start date must be greater or equal than Encounter period start')
2. in case of error and encounter.date - return 422 ('Care plan start date must be greater or equal than Encounter start date')
Check that $.period.end >= $.period.start
1. 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:
1. Check it belongs to the same patient ($.subject)
  1. Return 422 ('Care plan with such id is not found')
Validate status of referenced care plan:
1. Check it is one of COMPLETED OR ACTIVE OR TERMINATED:
  1. 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:
1. Check it belongs to the same patient ($.subject)
  1. 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
1. in case of error - return 422 ('value is not allowed in enum')
Check that each reference:
1. is valid ME of defined type above
2. belongs to the patient ($.subject)
  1. 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
1. in case of error - return 422 ('value is not allowed in enum')
Check that each referenced employee is active and approved
1. 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
1. 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
1. 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

...

If $.auth_method_id is specified
1. Check authentication method:
  1. is exist in MPI.person_authentication_method
  2. is belong to patient (MPI.person_authentication_method.person_id = $.patient_id)
  3. is active (MPI.person_authentication_method.ended_at > now() and MPI.person_authentication_method.is_active = true)
2. in case of any validations 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

Processing

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.

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.

Response structure examples

...

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

...

See on API-specification

Expand

title	Example

Code Block

language	json

{
  "data": {
    "id": "90a9e15b-b71b-4caf-8f2e-ff247e8a5600",
    "based_on": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "care_plan"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "part_of": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "care_plan"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "category": {
      "coding": [
        {
          "system": "eHealth/care_plan_categories",
          "code": "diabetics"
        }
      ]
    },
    "title": "Diabetics health plan",
    "description": "Some description of the care plan",
    "period": {
      "start": "2018-08-02T10:45:16.000Z",
      "end": "2018-08-02T11:00:00.000Z"
    },
    "supporting_info": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "episode_of_care"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      }
    ],
    "note": "Some notes",
    "intent": "order",
    "encounter": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "encounter"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "addresses": [
      {
        "coding": [
          {
            "system": "eHealth/ICD10_AM/condition_codes",
            "code": "E11.9"
          }
        ]
      }
    ],
    "author": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "employee"
            }
          ]
        },
        "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
      }
    },
    "contributor": [
      {
        "identifier": {
          "type": {
            "coding": [
              {
                "system": "eHealth/resources",
                "code": "employee"
              }
            ]
          },
          "value": "9183a36b-4d45-4244-9339-63d81cd08d9c"
        }
      }
    ],
    "terms_of_service": {
      "coding": [
        {
          "system": "PROVIDING_CONDITION",
          "code": "INPATIENT"
        }
      ]
    },
    "inform_with": {
      "auth_method_id": "cc949559-5dfe-420f-ac05-065e443b2cc6"
    },
    "status": "active",
    "subject": {
      "identifier": {
        "type": {
          "coding": [
            {
              "system": "eHealth/resources",
              "code": "patient"
            }
          ]
        },
        "value": "7c3da506-804d-4550-8993-bf17f9ee0403"
      }
    },
    "status_history": [
      {
        "status": "active",
        "status_reason": {
          "coding": [
            {
              "system": "eHealth/care_plan_cancel_reasons",
              "code": "some code"
            }
          ]
        },
        "inserted_at": "2018-08-02T10:45:16.000Z",
        "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e"
      }
    ],
    "requisition": "0123-4567-89AB-CEIK",
    "inserted_at": "2017-04-20T19:14:13Z",
    "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
    "updated_at": "2017-04-20T19:14:13Z",
    "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd"
  },
  "meta": {
    "code": 201,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  }
}

Expand

title	Example

Code Block

language	json

{
  "data": {
    "status": "pending",
    "eta": "2018-08-02T10:45:16.000Z",
    "links": [
      {
        "entity": "job",
        "href": "/Jobs/NBXk9EyErUZv1RhXgyvgg"
      }
    ]
  },
  "meta": {
    "code": 202,
    "url": "http://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  }
}

HTTP status codes

8

	Response code	HTTP Status code	Message	Internal name	Description
1	Базові
2		1000201	404	Composition not found	COMPOSITION_NOT_FOUND_404	Не знайдено медичний висновокResponse
3		201 202	Response payload will be returned in the job details
4		202202	Use Get job details to get processing result. Response payload will be returned in the job details
5		401	Invalid access token	validation fails token is expired
6		403	Access denied	invalid scope(s)
7		403	Access denied. Party is not verified
8		403	Your scope does not allow to access this resource. Missing allowances: care_ plan:write Access denied	invalid scope(s)	7	409	Signer DRFO doesn't match with requester tax_id plan:write
9		409	client_id refers to legal entity that is not active	Validation failed
10		409	client_id refers to legal entity with type that is not allowed to create medical events transactions
11		409	Care plan with such id already exists
12		409	Invalid employee speciality
13		409	Patient is not verified
14		409	Person is not active Patient is not verified Invalid employee speciality
15		409	Signer DRFO doesn't match with requester tax_id
16		422	Authentication method doesn't exist, is inactive or does not belong to this person
17		422	Care plan with such id already exists	Validation failed	is not found
18		422	type mismatch or schema validation error list of validation errors in case validation failsCare plan start date must be greater or equal than Encounter period start
19		422	Care plan in status "<care_plan.status>" can not be referenced
20		422	Document must be signed by 1 signer but contains 0 signatures User is not allowed to create care plan for the employee
21		422	Employee does not have active role that correspond to the submitted terms of service Value is not allowed in enum Encounter in "entered_in_error" status can not be referenced Encounter with such id is not found
22		422	Encounter without diagnosis can not be referenced Primary diagnosis condition code and care plan category mismatch Primary diagnosis condition codes do not match with codes in addresses
23		422	Encounter refers to episode that does not exist
24		422	Encounter refers to episode that with such id is not active Encounter is from another legal entity ~~Start date must be in the future~~ Care plan start date must be greater or equal than Encounter period start Care plan start date must be greater or equal than Encounter start date found
25		422	Encounter in "entered_in_error" status can not be referenced
26		422	End date must be greater than or equal the start date Care plan with such id is not found
27		422	Encounter refers to episode that is not active
28		422	Encounter is from another legal entity
29		422	Invalid employee status
30		422	list of validation errors in case validation fails
31		422	<medical event type> with such ID is not found Invalid employee status Authentication method doesn't exist, is inactive or does not belong to this person	9	10	11
12		401	Unauthorized		Помилка підтвердження
13	Специфічні
14		422	Only for active MPI record can be created medication request!
32		422	Not allowed for <employee type>
33		422	Primary diagnosis condition codes do not match with codes in addresses
34		422	Primary diagnosis condition code and care plan category mismatch
35		422	type mismatch or schema validation error
36		422	Value is not allowed in enum
37		422	User is not allowed to create care plan for the employee
38	Специфічні
39

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

Название	ID ТМ	Статус
/wiki/spaces/ESOZ/pages/17378181218	TM0112
/wiki/spaces/YK/pages/17837688354

Page Comparison

Versions Compared

Old Version 2

New Version Current

Key

Properties of a REST API method document

Properties of a REST API method document

Purpose

Key points

Logic

Service logic

Configuration parameters

Dictionaries

Input

parameters

Request structure

Request structure

Headers

Request data validation

Authorize

Validate request

Validate Digital Sign

Validate legal entity

Validate Care plan

1. Subject

2. Author

3. Category

4. Encounter

5. Addresses

6. Terms of service

7. Period

8. Based on

9. Part of

10. Supporting info

11. Contributors

12. Care plan identifier

13. Status

14. Inform_with

Processing

Generate requisition

Send SMS notification

Response structure examples

HTTP status codes

Post-processing processes

Technical modules where the method is used

Technical modules where the method is used