Properties of a REST API method document

Purpose

This method allows to create Composition of all types and categories for a person/pre-person in eHealth.

Used in processes:

2.1. МВН - Створення нового

2.2. МВТН - Створення нового

Logic

Open

Configuration parameters

N/A

Dictionaries

COMPOSITION_CATEGORIES

COMPOSITION_TYPES

COMPOSITION_EVENTS

eHealth/resources

Input parameters

Request structure

See on SwaggerHub

Headers

Headers

Request data validation

Authorize

Check user scopes in order to perform this action (scope = 'composition:create')

• return 401 (Unauthorized) in case of invalid scope(s)

1. Validation before createComposition task

   1. Check dictionary in “system“ parameter for “category” attribute:

      1. If value is not matched with value in EMAL_VALIDATION_CATEGORY_NEWBORN_SYSTEM or EMAL_VALIDATION_CATEGORY_DISABILITY_SYSTEM - return 1081 INVALID_NEWBORN_CATEGORY) or 1085 (INVALID_DISABILITY_CATEGORY)

   2. Check for “category” attribute:

      1. If value is not matched with value in EMAL_VALIDATION_CATEGORY_NEWBORN_CODES or EMAL_VALIDATION_CATEGORY_DISABILITY_CODES - return 1081 INVALID_NEWBORN_CATEGORY) or 1085 (INVALID_DISABILITY_CATEGORY)

   3. Check “category” attribute for the need to specify the same values for the attributes subject and focus (subject.value == focus.value):

      1. If values in “subject” and “focus” attributes conflict with the requirement in EMAL_VALIDATION_SUBJECT_FOCUS_REQUIRE_EQUALITY_BY_CATEGORY - return 1182 (SUBJECT_FOCUS_EQUALITY_REQUIRED)

   4. Check “category” attribute for possibility to use extensions for such category:

      1. If extensions are not allowed for this category in EMAL_VALIDATION_EXTENSION_ALLOWED_BY_CATEGORY (ExtensionByCategoryValidator) - return 1175 (INVALID_EXTENSION_FOR_CATEGORY)

   5. Check dictionary in "system" parameter for "relatesTo" attribute (if it’s exist)(allowedIdentifierSystem):

      1. If value is not matched with value in EMAL_VALIDATION_RELATES_TO_IDENTIFIER_ALLOWED_SYSTEM - return 1216 (CANT_CREATE_INVALID_RELATES_TO_IDENTIFIER_SYSTEM)

   6. Check for “relatesTo.code” (allowedIdentifierCode):

      1. If value is not matched with value in EMAL_VALIDATION_RELATES_TO_IDENTIFIER_ALLOWED_CODE - return 1215 (CANT_CREATE_INVALID_RELATES_TO_IDENTIFIER_CODE)

2. prechecks - Initial checks of request input data

   1. Check for “encounter.value” attribute:

      1. If another Composition with the same type and category in the "Final" status has the same encounter.value - return 1127 (FINAL_COMPOSITION_FOR_ENCOUNTER_ALREADY_EXISTS)

   2. If “relatesTo” isn’t null:

      1. For Newborn Composition:

         1. Validate that replacement is enabled

            1. In case of error (replacement isn’t enabled) - return 1181 (REPLACEMENT_FLOW_NOT_IMPLEMENTED_YET)

      2. For Temporary Disability Composition:

         1. If Composition.subject=person in current composition, Composition.subject = preperson in indicated composition in relatesTo.target.identifier and composition.status is FINAL, then the Refinement process is initiated

         2. If Composition.status in indicated composition in relatesTo.target.identifier is ENTERED_IN_ERROR and replacement is enabled, then the Raplacement process is initiated

            1. In case of error (replacement isn’t enabled) - return 1181 (REPLACEMENT_FLOW_NOT_IMPLEMENTED_YET)

         3. in other cases - return 1160 (INVALID_REPLACEMENT_ARGUMENT)

   3. For Newborn Composition:

      1. Checking for an already created Composition for preperson (“subject” attribute) which are according such requirements: Composition.type is Newborn and Composition.status isn’t ENTERED_IN_ERROR:

         1. In case of existing appropriate Compositions - return 1002 (COMPOSITION_ALREADY_EXISTS_FOR_SUBJECT)

      2. If in item b. was initiated Replacement flow:

         1. Checking the Composition.type in current Composition and Composition.type indicated in relatesTo.target.identifier

            1. In case of difference - return 1146 (CANT_REPLACE_DIFFERENT_TYPE)

         2. Check if the indicated Composition is last in the chain:

            1. In case of error (indicated Composition isn’t last in the chain) - return 1153 (CANT_AMEND_IS_APPENDED)

         3. Check if the indicated Composition has ENTERED_IN_ERROR status:

            1. In case of error (indicated Composition hasn’t ENTERED_IN_ERROR status) - return 1148 (CANT_REPLACE_IS_APPENDED)

         4. Check if the indicated Composition was canceled with Replacement’s reason

            1. In case of right Replacement’s reason - check validity period of Composition according to the configuration parameter EMAL_FILTER_REPLACEMENT_CANCEL_TIMEOUT_NEWBORN. In case of error - return 1039 (INVALID_PERIOD)

            2. In case of common cancelation reason - check validity period of Composition according to the configuration parameter EMAL_FILTER_PERIOD_START_NEWBORN. In case of error - return 1039 (INVALID_PERIOD)

   4. For Temporary Disability Composition:

      1. If in item b. was initiated Replacement flow:

         1. Checking the Composition.type in current Composition and Composition.type indicated in relatesTo.target.identifier

            1. In case of difference - return 1146 (CANT_REPLACE_DIFFERENT_TYPE)

         2. Check if the indicated Composition is last in the chain:

            1. In case of error (indicated Composition isn’t last in the chain) - return 1153 (CANT_AMEND_IS_APPENDED)

         3. Check if the indicated Composition has ENTERED_IN_ERROR status:

            1. In case of error (indicated Composition hasn’t ENTERED_IN_ERROR status) - return 1148 (CANT_REPLACE_IS_APPENDED)

         4. Check if the indicated Composition was canceled with Replacement’s reason

            1. In case of right Replacement’s reason - check validity period of Composition according to the configuration parameter EMAL_FILTER_REPLACEMENT_CANCEL_TIMEOUT_DISABILITY. In case of error - return 1039 (INVALID_PERIOD)

            2. In case of common cancelation reason - check validity period of Composition according to the configuration parameter EMAL_FILTER_PERIOD_START_DISABILITY. In case of error - return 1039 (INVALID_PERIOD)

         5. Check “event.period.start” attribute for the possibility to specify in the future:

            1. If event.period.start is specified in the future and it's not PREGNANCY category - return 1039 (INVALID_PERIOD)

         6. Check the time difference between the start date (event.period.start) and the task creation date:

            1. If the difference is more than allowed - return 1040 (PERIOD_TOLERANCE_EXCEEDED)

         7. Check for TREATMENT_VIOLATION_DATE extension:

            1. If TREATMENT_VIOLATION_DATE is outside the period of incapacity (event.period.start - event.period.end) - return 1172 (TREATMENT_VIOLATION_DATE_OUT_OF_BOUNDS)

      2. If in item a. wasn’t initiated Replacement flow:

         1. In case of IS_FORCE_RENEW=true - the function completes it's execution and does not perform further checks

         2. Check for IS_FOREIGN_TREATMENT extension:

            1. If extension IS_FOREIGN_TREATMENT= true - checks 3 and 4 don’t perform

         3. Check of maximum length of one link of a medical opinion (disabilitySingleSpanFilter)

            1. In case of error - return 1039 (INVALID_PERIOD), 1031 (DURATION_SINGLE_PERIOD_TOO_LONG)

         4. Check for event.period.start attribute (periodStartFilter)

            1. In case of error - return 1039 (INVALID_PERIOD), 1040 (PERIOD_TOLERANCE_EXCEEDED)

         5. Search for previous compositions with the same type and category as in the request, overlapping with the period of validity for this composition for at least 1 day

            1. If previous compositions wasn’t found - the function completes it's execution

            2. If previous compositions was found - check validity period of compositions

               1. In case of error - return 1143 (NEW_START_DATE_IS_BEFORE_PREVIOUS_START_DATE), 1103(SAME_END_DATE_FOR_NEW_AND_EXISTING_COMPOSITION)

         6. Check for the maximum total length of the validity period (disabilityTotalSpanFilter)

            1. In case of error - return 1039 (INVALID_PERIOD), 1032 (DURATION_TOTAL_PERIOD_TOO_LONG)

      3. Additional checks for PREGNANCY category:

         1. If event.period.start <= taskCreated - the procedure begins to create a New Pregnancy Composition

            1. Check for “relatesTo” attribute:

               1. If it’s not null - return 1218 (NEW_PREGNANCY_COMPOSITION_CANT_HAVE_RELATIONSHIPS)

            2. Check for the length of the period of incapacity:

               1. If it’s not match with value in EMAL_VALIDATION_PREGNANCY_NEW_COMPOSITION_ALLOWED_PERIODS - return 1219 (NEW_PREGNANCY_COMPOSITION_INVALID_PERIOD)

            3. Check for “event.period.start” attribute:

               1. If event.period.start > taskCreated - return 1220 (NEW_PREGNANCY_COMPOSITION_INVALID_PERIOD_STARTS_IN_FUTURE)

         2. If event.period.start > taskCreated - the procedure begins to create a Prolongation for Previous Pregnancy Composition (appendingPregnancyComposition)

            1. Check the connections between the first and second Compositions (in “relatesTo” attribute) and check for “event.period.start” attribute in second Composition:

               1. If event.period.start < taskCreated - return 1222 (PREGNANCY_COMPOSITION_CONTINUATION_INVALID_PERIOD_STARTS_IN_PAST)

            2. Check for “event.period.start” attribute:

               1. If Event.period.startTempDisabilityComposition2 isn’t equal to Event.period.endTemporaryDisabilityComposition1+1day - return 1223 (PREGNANCY_COMPOSITION_CONTINUATION_INVALID_PERIOD_WRT_PREVIOUS)

            3. Check for the length of the period of incapacity for Prolongation Pregnancy Composition (appendedPregnancyAllowedPeriod):

               1. If it’s not match with value in EMAL_VALIDATION_PREGNANCY_APPENDED_COMPOSITION_ALLOWED_PERIOD - return 1224 (PREGNANCY_COMPOSITION_CONTINUATION_INVALID_PERIOD_LENGTH)

            4. Check for “relatesTo” attribute:

               1. If relatesTo.code = appends and it’s not a first prolongation - return 1225 (PREGNANCY_COMPOSITION_DEPTH_EXCEEDED)

               2. If “relatesTo.code” it’s not “appends“ - return 1221 (PREGNANCY_COMPOSITION_INVALID_RELATIONSHIP).

3. Encounter Processing - Receiving and processing medical records (Encounter)

   1. Search for Encounter using the RPC call by ME service encounter_by_id

      1. In case of error - return 1016 (ENCOUNTER_NOT_FOUND)

   2. Check for Composition.author (CompositionAuthorFilter)

      1. If Composition.author.value does not match with Encounter.performer.identier.value and Composition.author.type.coding does not match with Encounter.performer.identier.type.coding - return 1030 (INVALID_ENCOUNTER_PERFORMER)

   3. Check for Encounter.type (EncounterTypeFilter)

      1. If Encounter.status isn’t “finished" - return 1037 (INVALID_ENCOUNTER_STATUS)

      2. If Encounter.type.code does not match with value in EMAL_FILTER_ENCOUNTER_TYPE_DISABILITY, EMAL_FILTER_ENCOUNTER_TYPE_NEWBORN - return 1038 (ENCOUNTER_TYPE_DISALLOWED_FOR_COMPOSITION_TYPE)

   4. Check for Encounter.Diagnose(encounterDiagnosesFilter)

      1. If no primary diagnosis was found - return 1034 (NO_PRIMARY_DIAGNOSIS)

      2. If a few primary diagnosis was found - return 1035 (MULTIPLE_PRIMARY_DIAGNOSES)

   5. Check for allowed values of Encounter.diagnoses[].code.code

      1. In case of error - return 1036 (PRIMARY_DIAGNOSIS_NOT_ALLOWED)

   6. Check for allowed Encounter.date (or Encounter.period.start)

      1. If Encounter.date does not match with value in EMAL_VALIDATION_ENCOUNTER_MAX_AGE_DAYS_BY_CATEGORY - return 1183 (INVALID_ENCOUNTER_DATE)

4. Employee Processing - Receiving and processing Employee record (Composition.author)

   1. Search and check for Composition.author by id in IL with method employee_by_id

      1. In case of error - return 1015 (EMPLOYEE_NOT_FOUND)

   2. Check for Author.speciality (doctorSpecialityFilter)

      1. In case of error - return 1133 (NO_SPECIALIST_SPECIFIED), 1033 (DOCTOR_LACKS_SPECIALITY)

   3. Check for Composition.author

      1. If employee.status does not match with value in EMAL_VALIDATION_AUTHOR_ACTIVE_STATUS_VALUE - return 1165 (INVALID_AUTHOR_STATUS)

      2. If employee.type does not match with value in EMAL_VALIDATION_AUTHOR_CATEGORIES_BY_TYPE - return 1166 (INVALID_AUTHOR_TYPE)

      3. If employee.position does not match with value in EMAL_VALIDATION_AUTHOR_CATEGORIES_BY_POSITION - return 1167 (INVALID_AUTHOR_POSITION)

      4. If specialist.specialities або doctor.specialities with speciality_officio=true does not match with value in EMAL_VALIDATION_AUTHOR_CATEGORIES_BY_SPECIALITY_OFFICIO - return 1168 (INVALID_AUTHOR_SPECIALITY_OFFICIAL)

      5. If specialist.specialities or doctor.specialities with speciality_officio=false or null does not match with value in EMAL_VALIDATION_AUTHOR_CATEGORIES_BY_SPECIALITY - 1169 (INVALID_AUTHOR_SPECIALITY)

5. Division Processing - Receiving and processing Division record (Employee Division)

   1. Check for Encounter.division

      1. If Encounter.division does not match with value in EMAL_FILTER_DIVISION_REQUIREMENTS_DISABILITY, EMAL_FILTER_DIVISION_REQUIREMENTS_NEWBORN - return 1089 (DIVISION_IS_REQUIRED)

      2. Search for Encounter.division by id in IL with method division_by_id

         1. In case of error - return 1012 (DIVISION_ENTITY_NOT_FOUND)

6. Legal Entity Processing - Receiving and processing Legal Entity record (Employee Legal Entity)

   1. Search for Legal Entity by id with RPC method legal_entity_by_id

      1. In case of error - return 1011 (LEGAL_ENTITY_NOT_FOUND)

   2. Check for Custodian

      1. If legal_entity.type does not match with value in EMAL_VALIDATION_CUSTODIAN_CATEGORIES_BY_TYPE - return 1162 (INVALID_CUSTODIAN_TYPE)

      2. If legal_entity.status does not match with value in EMAL_VALIDATION_CUSTODIAN_ALLOWED_STATUSES_DISABILITY and EMAL_VALIDATION_CUSTODIAN_ALLOWED_STATUSES_NEWBORN - return 1164 (STATUS_NOT_ALLOWED_FOR_CUSTODIAN)

7. Subject Processing - Receiving and processing Subject record

   1. Getting a record about the Composition's patient by id with RPC method get_preperson_by_id if subject.type.coding.code = preperson or get_person_by_id if subject.type.coding.code = person and Composition.type is Temporary Disability

      1. In case of error - return 1013 (BAD_SUBJECT_CODING), 1014 (SUBJECT_NOT_FOUND), 1112 (SUBJECT_IS_NOT_ACTIVE)

   2. For Newborn Composition:

      1. Check for preperson.birth_date

         1. In case of error (date of birth of the patient is not indicated) - return 1113 (NO_SUBJECT_PREPERSON_BIRTH_DATE)

      2. Check for Composition.event.period.start

         1. If Composition.event.period.start does not match with preperson.birth_date - return 1115 (SUBJECT_PREPERSON_BIRTH_DATE_MISMATCH)

      3. If preperson.gender is null - return 1114 (NO_SUBJECT_PREPERSON_GENDER)

   3. Сheck for presence of age restrictions in the configuration parameter for the person

      1. In case of error - return 1128 (AGE_NOT_ALLOWED)

   4. Сhecks for subject:

      1. If attribute subject.status is absent - return 1189 (INVALID_NEWBORN_SUBJECT_STATUS) or 1190 (INVALID_DISABILITY_SUBJECT_STATUS)

      2. If subject.status does not match with value in EMAL_VALIDATION_SUBJECT_ALLOWED_STATUSES_BY_CATEGORY - return 1189 (INVALID_NEWBORN_SUBJECT_STATUS) or 1190 (INVALID_DISABILITY_SUBJECT_STATUS)

      3. If subject.type.code does not match with value in EMAL_VALIDATION_SUBJECT_CATEGORIES_BY_TYPE - return 1188 (INVALID_DISABILITY_SUBJECT_CATEGORY)

      4. If subject.type=preperson and IS_FOREIGN_TREATMENT extension is TRUE - return 1199 (FOREIGN_TREATMENT_FOR_SUBJECT_PREPERSON_NOT_ALLOWED)

      5. Additional checks for subject.type=person:

         1. Check for patient’s verification_status:

            1. If verification_status does not match with value in EMAL_VALIDATION_SUBJECT_ALLOWED_VERIFICATION_STATUSES_BY_CATEGORY or it not specified - return 1192 (INVALID_DISABILITY_SUBJECT_VERIFICATION_STATUS)

         2. Check for subject age

            1. If age of the person does not match with value in EMAL_VALIDATION_SUBJECT_ALLOWED_AGES_BY_CATEGORY - return 1194 (INVALID_DISABILITY_SUBJECT_AGE)

         3. Check for allowed patient’s documents:

            1. If patient’s document not allowed in EMAL_VALIDATION_SUBJECT_DOCUMENTS_BY_CATEGORY - return 1196 (INVALID_DISABILITY_SUBJECT_DOCUMENTS)

         4. Check for tax_id

            1. In case of error - return 1198 (INVALID_DISABILITY_SUBJECT_TAX_ID)

         5. Check for patient’s gender

            1. If patient's gender not allowed in EMAL_VALIDATION_SUBJECT_GENDERS_BY_CATEGORY - return 1210 (INVALID_NEWBORN_SUBJECT_GENDER) or 1211 (INVALID_DISABILITY_SUBJECT_GENDER)

   5. For Newborn Composition:

      1. If subject.type.coding.code isn’t preperson - return 1082 (INVALID_NEWBORN_SUBJECT)

      2. If date in “NEWBORN_BIRTH_DATE” does not match with value in preperson.birth_date - return 1173 (INVALID_NEWBORN_BIRTH_DATE_EXTENSION_VALUE)

      3. If date in "NEWBORN_BIRTH_DATE" does not match with value in composition.event.perion.start - return 1173 (INVALID_NEWBORN_BIRTH_DATE_EXTENSION_VALUE)

      4. If gender in "NEWBORN_SEX" does not match with value in preperson.gender - return 1174 (INVALID_NEWBORN_SEX_EXTENSION_VALUE)

8. Focus Processing - Receiving and processing Focus record

   1. For Newborn Composition:

      1. If focus.type.coding.code isn’t person - return BAD_FOCUS_CODING(1009)

   2. Getting a record about the Composition's patient by id with RPC method get_preperson_by_id if focus.type.coding.code = preperson or get_person_by_id if focus.type.coding.code = person and Composition.type is Temporary Disability

      1. In case of error - return 1009 (BAD_FOCUS_CODING), 1010 (FOCUS_NOT_FOUND), 1111 (FOCUS_IS_NOT_ACTIVE)

   3. Getting a record about the Composition.focus’s authorization methods by id with RPC method get_auth_methods.

      1. If authorization method is expired such method isn't not used

      2. If specified authorization method wasn't found - return 1171 (FOCUS_AUTH_NOT_SPECIFIED)

   4. Checks for “section.focus” attribute:

      1. If focus.type.code does not match with value in EMAL_VALIDATION_FOCUS_CATEGORIES_BY_TYPE - return 1201 (INVALID_DISABILITY_FOCUS_CATEGORY)

      2. If focus.status does not match with value in EMAL_VALIDATION_FOCUS_ALLOWED_STATUSES_BY_CATEGORY - return 1202 (INVALID_DISABILITY_FOCUS_STATUS) or 1203 (INVALID_NEWBORN_FOCUS_STATUS )

      3. If focus.type=preperson and IS_FOREIGN_TREATMENT extension is TRUE - return 1214 (FOREIGN_TREATMENT_FOR_FOCUS_PREPERSON_NOT_ALLOWED)

      4. Additional checks for focus.type=person:

         1. Check for patient’s verification_status:

            1. If verification_status does not match with value in EMAL_VALIDATION_FOCUS_ALLOWED_VERIFICATION_STATUSES_BY_CATEGORY or it doesn't specified - return 1204 (INVALID_NEWBORN_FOCUS_VERIFICATION_STATUS) or 1205 (INVALID_DISABILITY_FOCUS_VERIFICATION_STATUS)

         2. Check for tax_id

            1. In case of error - return 1138 (PERSON_HAS_NO_TAX_ID)

         3. Check for focus document.type

            1. If it is not match with value in EMAL_ERLN_CREATE_RECORD_JOB_DOCUMENT_TYPE_CODES - return 10916 (IDENTIFICATION_FAILED_DOCUMENT_ABSENT)

            2. If focus.documen_type is not match with value in EMAL_VALIDATION_FOCUS_DOCUMENTS_BY_CATEGORY - return 1212 (INVALID_NEWBORN_FOCUS_DOCUMENTS) or 1213 (INVALID_DISABILITY_FOCUS_DOCUMENTS)

         4. Check for focus.gender

            1. If focus gender is not match with value in EMAL_VALIDATION_FOCUS_GENDERS_BY_CATEGORY or it's not specified - return 1208 (INVALID_NEWBORN_FOCUS_GENDER) or 1209 (INVALID_DISABILITY_FOCUS_GENDER)

         5. Check for focus age

            1. If age of the person is not match with value in EMAL_VALIDATION_FOCUS_ALLOWED_AGES_BY_CATEGORY - return 1206 (INVALID_NEWBORN_FOCUS_AGE) or 1207 (INVALID_DISABILITY_FOCUS_AGE)

      5. For Rectification cases:

         1. If the records of identified and unidentified patients are not combined - return 1155 (CANT_AMEND_NO_MERGE_PAIR)

9. getSmsPhoneNumber - Receiving phone number for sending SMS about creation of composition

   1. This procedure is performed if extension “AUTHORIZE_WITH” was specified in the request. In other cases, the procedure is not performed

      1. search for a person's authorization method by RPC call to the MPI service get_auth_method

         1. If phone number was found - this number is saving for future SMS sending

         2. If phone number wasn't found - return 1017 (PHONE_NOT_FOUND)

10. Saving the record of the Сomposition into database

11. Task status updating in DONE

Processing

1. Validation before createComposition task

2. Prechecks - Initial checks of request input data

3. Encounter Processing - Receiving and processing medical records (Encounter)

4. Employee Processing - Receiving and processing Employee record (Composition.author)

5. Division Processing - Receiving and processing Division record (Employee Division)

6. Legal Entity Processing - Receiving and processing Legal Entity record (Employee Legal Entity)

7. Subject Processing - Receiving and processing Subject record

8. Focus Processing - Receiving and processing Focus record

9. getSmsPhoneNumber - Receiving phone number for sending SMS about creation of composition

10. Saving the record of the Сomposition into database

11. Task status updating in DONE

Response structure examples

See on SwaggerHub

HTTP status codes

Post-processing processes

N/A

Technical modules where the method is used