Purpose

This WS is designed to create relationship for reorganized legal entities by NHS admin using DS.

Key points

1. This is a graphQl method used in Administration panel only.

2. Only authenticated and authorized NHS employee with appropriate scope can reorganize legal entities.

3. Request should be signed with DS.

Specification

"""
Input for `reorganizeLegalEntity` mutation.
"""
input ReorganizeLegalEntityInput {
  "Input for Signed Content"
  signedContent: SignedContent!
}

"""
Return type for `reorganizeLegalEntity` mutation.
"""
type ReorganizeLegalEntityPayload {
  "payload LegalEntityReorganizationJob."
  legalEntityReorganizationJob: LegalEntityReorganizationJob
}

Input parameters

Input is signed data in PKCS7 format. The data must be unpacked and validated using Json Schema.

Based on reorganization type, signedData must contain following fields:

Reorganization types ACCESSION, MERGING, DIVIDING, SEPARATING

Fields to sign:

...

field

...

type

...

limit

...

required/optional

...

merged_from_legal_entity (object)

...

id

...

uuid

...

required

...

name

...

string

...

required

...

edrpou

...

string

...

required

...

merged_to_legal_entity (array of objects)

...

id

...

id

...

required

...

name

...

string

...

required

...

edrpou

...

string

...

required

...

type

...

string

...

required

...

reason

...

string

...

255 characters

...

required

...

reason_date

...

date

...

required

Reorganization type TRANSFORMATION

Fields to sign:

...

field

...

type

...

limit

...

required/optional

...

merged_from_legal_entity (object)

...

id

...

uuid

...

required

...

name

...

string

...

required

...

edrpou

...

string

...

required

...

type

...

string

...

required

...

reason

...

string

...

255 characters

...

required

...

reason_date

...

date

...

required

Validations

Authorization

• Verify the validity of the access token

  • in case of error - return 401 (“Invalid access token”)

• 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 = 'legal_entity:merge')

  • in case of invalid scope(s) - return 403 (“Your scope does not allow to access this resource. Missing allowances: legal_entity:merge”)

Validate Digital signature

• Validate decoded input data is signed

  • 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 user

  • Check that EDRPOU from DS and legal_entities.edrpou matches

    • in case of error - return 409 (“Signer EDRPOU doesn’t match with requester edrpou”)

  • Check that DRFO from DS and party.tax_id matches

    • in case of error - return 409 (“Signer DRFO doesn't match with requester tax_id“)

Validate request

1. Check input data contains all required fields

   1. in case of error - return 422 ('Required property <field_name> was not present')

2. Validate value of type is presented in LEGAL_ENTITY_REORGANIZATION_TYPES dictionary.

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

3. Validate value of reason_date is within merged_from legal entity inserted_at date and current_date (not earlier than merged_from legal entity registration date and not later than the date of reorganization process).

   1. in case of error - return 422 error ('Reorganization reason date can’t be earlier than legal entity registration date and later than reorganization date')

4. Validate merged_from and merged_to legal entities are not in the process of reorganization (request: select * from related_legal_entities where merged_from_id in ($merged_from_id, $merged_to_id) and is_active=true and type in ('ACCESSION', ‘MERGING’, ‘DIVIDING’); returns empty result):

   1. in case of error - return 409 ('Reorganized and successor legal entities must not be in the process of reorganization')

5. Validate merged_from legal_entity

   1. Check merged_from legal entity exists

      1. in case of error - return 404 ('Reorganized legal entity was not found')

   2. Check merged_from legal entity is in status='active' or 'suspended'

      1. in case of error - return 409 ('Reorganized legal entity must be active or suspended')

   3. Validate merged_from_legal_entity.name from request=legal_entites.name

      1. in case of error - return 422 ('Invalid reorganized legal entity name')

   4. Validate merged_from_legal_entity.edrpou from request=legal_entites.edrpou

      1. in case of error - return 422 ('Invalid reorganized legal entity edrpou')

   5. Validate merged_from_legal_entity.id<>merged_to_legal_entity.id

      1. in case of error - return 422 ('Reorganized and successor legal entities must be different')

6. (Applies for reorganization types ACCESSION, MERGING, DIVIDING, SEPARATING)
   Validate merged_to legal_entity (each object in array).

   1. Check that each merged_to legal entity exists and unique in array

      1. in case of error - return 422 ('Successor legal entities must be different and exist')

   2. Check that each merged_to legal entity is in status='active' 

      1. in case of error - return 409 ('Successor legal entity must be active')

   3. Validate merged_to_legal_entity.name from request=legal_entites.name

      1. in case of error - return 422 ('Invalid successor legal entity name')

   4. Validate merged_to_legal_entity.edrpou from request=legal_entites.edrpou

      1. in case of error - return 422 ('Invalid successor legal entity edrpou')

7. (Applies for reorganization type TRANSFORMATION)
   Validate merged_from.legal_entity_type. Valid types: MSP, PRIMARY_CARE, EMERGENCY, OUTPATIENT.

   1. in case of error - return 422 ('Invalid legal entity type')

8. (Applies for reorganization types ACCESSION, MERGING, DIVIDING, SEPARATING)
   Validate merged_to.legal_entity_type and merged_from.legal_entity_type. Valid type transitions see in the table below.

   1. in case of error - return 422 ('Invalid legal entity type')

Valid type transitions for legal entities

...

merged_from

...

merged_to

...

MSP, PRIMARY_CARE

...

MSP, PRIMARY_CARE

Service logic

...

Logic

Service logic differs based on reorganization type:

Reorganization types ACCESSION, MERGING, DIVIDING

Create and start async job with type reorganize_legal_entities

...

1. Update merged_from legal entity active employees (except OWNER) in ‘APPROVED’ status, update status in employees table (PRM DB):

   1. set status = ‘REORGANIZED’

   2. set updated_at = now()

   3. set updated_by = $user_id

2. Update merged_from legal entity reorganized employees' declarations, update expiry date in declarations table (OPS DB):

   1. set end_date = now() + value of LEGAL_ENTITY_REORGANIZATION_TRANSITION_PERIOD config

   2. set updated_at = now()

   3. set updated_by = $user_id

3. Update client type for merged_from legal entity in clients table (MITHRIL DB):

   1. set client_type_id = $MSP_LIMITED_ID(3770c4b3-05cd-42d9-8e15-233b193aee86)

   2. set updated_at = now()

4. Remove all approvals by merged_from legal entity in apps table (MITHRIL DB)

5. Make all tokens by merged_from legal entity expired in tokens table (MITHRIL DB):

   1. set expires_at=now(unix time)

   2. set updated_at = now()

6. Set merged_from legal entity contract as suspended in contracts table (PRM DB):

   1. set is_suspended = true

   2. set status_reason = ‘DEFAULT’

   3. set reason = ‘Реорганізація СГуСОЗ’

   4. set updated_at = now()

   5. set updated_by = $user_id

7. For each pair of merged_from legal entity and merged_to legal entity create separate task.
   Task must contain metadata with merged_to_legal_entity values from input parameters.
   Each task must do next steps

   1. Insert legal entities relations record in related_legal_entities table (PRM DB) according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/16898293829

   2. Save signed content to media storage for each related_legal_entities record

8. After all task from job are successfully completed, update merged_from legal entity status in legal_entities table (PRM DB):

   1. set status = 'REORGANIZED'

   2. set updated_at = now()

   3. set updated_by = $user_id

Reorganization type SEPARATING

Create and start async job with type reorganize_legal_entities

...

1. Update merged_from legal entity employees with type ‘DOCTOR’, status ‘APPROVED’ and party_id in successor legal entity, update status in employees table (PRM DB):

   1. set status = ‘REORGANIZED’

   2. set updated_at = now()

   3. set updated_by = $user_id

2. Update merged_from legal entity reorganized employees' declarations, update expiry date in declarations table (OPS DB):

   1. set end_date = now() + value of LEGAL_ENTITY_REORGANIZATION_TRANSITION_PERIOD config

   2. set updated_at = now()

   3. set updated_by = $user_id

3. Update roles for merged_from legal entity employees in status ‘reorganized’ in user_roles table (MITHRIL DB):

   1. set role_id = $DOCTOR_LIMITED_ID(c61f8475-6474-4314-a99a-e0eb193f2996)

   2. set updated_at = now()

4. Remove all apps by merged_from legal entity employees in status ‘reorganized’ in apps table (MITHRIL DB)

5. Make all tokens by merged_from legal entity employees in status ‘reorganized’ expired in tokens table (MITHRIL DB):

   1. set expires_at=now(unix time)

   2. set updated_at = now()

6. Set merged_from legal entity contract as suspended in contracts table (PRM DB):

   1. set is_suspended = true

   2. set status_reason = ‘DEFAULT’

   3. set reason = ‘Реорганізація СГуСОЗ’

   4. set updated_at = now()

   5. set updated_by = $user_id

7. For each pair of merged_from legal entity and merged_to legal entity create separate task.
   Task must contain metadata with merged_to_legal_entity values from input parameters.
   Each task must do next steps:

   1. Insert legal entities relations record in related_legal_entities table (PRM DB) according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/16898293829

   2. Save signed content to media storage for each related_legal_entities record

Reorganization type TRANSFORMATION

Create and start async job with type reorganize_legal_entities

...

1. Update merged_from legal entity EDR data fields in legal_entities table (PRM DB):

   1. set edr_data_id = null

   2. set updated_at = now()

   3. set updated_by = $user_id

2. Perform upsert_edr_data process, that is used to update or insert EDR Data for Legal Entity:

   1. Update or insert edr_data for merged_from legal entity edrpou based on EDR Data response in edr_data table (PRM DB)

   2. Update merged_from legal entity EDR Data info based on EDR Data response in legal_entities table (PRM DB)

   3. Update edr_data_id of merged_from legal entity in legal_entities table (PRM DB)

3. Set merged_from legal entity contract as suspended in contracts table (PRM DB):

   1. set is_suspended = true

   2. set status_reason = ‘DEFAULT’

   3. set reason = ‘Реорганізація СГуСОЗ’

   4. set updated_at = now()

   5. set updated_by = $user_id

4. Update merged_from legal entity status in legal_entities table (PRM DB):

   1. set status = 'SUSPENDED'

   2. set updated_at = now()

   3. set updated_by = $user_id

5. Insert legal entities relations record with merged_from and merged_to data of reorganized legal entity in related_legal_entities table (PRM DB) according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/16898293829
   In case if relations record already exists (legal entity was reorganized with type TRANSFORMATION earlier), get id of related_legal_entities record.

6. Save signed content to media storage with following name: MEDIA_STORAGE_MERGED_LEGAL_ENTITIES_RESOURCE_NAME_<REORGANIZATION_DATE_IN_UNIX_TIME>

Input parameters

Input is signed data in PKCS7 format. The data must be unpacked and validated using Json Schema.

Based on reorganization type, signedData must contain following fields:

Reorganization types ACCESSION, MERGING, DIVIDING, SEPARATING

Fields to sign:

Reorganization type TRANSFORMATION

Fields to sign:

Request structure

API paragraph not found

Authorize

• Verify the validity of the access token

  • in case of error - return 401 (“Invalid access token”)

• 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 = 'legal_entity:merge')

  • in case of invalid scope(s) - return 403 (“Your scope does not allow to access this resource. Missing allowances: legal_entity:merge”)

Headers

API paragraph not found

Request data validation

Validate Digital signature

• Validate decoded input data is signed

  • 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 user

  • Check that EDRPOU from DS and legal_entities.edrpou matches

    • in case of error - return 409 (“Signer EDRPOU doesn’t match with requester edrpou”)

  • Check that DRFO from DS and party.tax_id matches

    • in case of error - return 409 (“Signer DRFO doesn't match with requester tax_id“)

Validate request

1. Check input data contains all required fields

   1. in case of error - return 422 ('Required property <field_name> was not present')

2. Validate value of type is presented in LEGAL_ENTITY_REORGANIZATION_TYPES dictionary.

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

3. Validate value of reason_date is within merged_from legal entity inserted_at date and current_date (not earlier than merged_from legal entity registration date and not later than the date of reorganization process).

   1. in case of error - return 422 error ('Reorganization reason date can’t be earlier than legal entity registration date and later than reorganization date')

4. Validate merged_from and merged_to legal entities are not in the process of reorganization (request: select * from related_legal_entities where merged_from_id in ($merged_from_id, $merged_to_id) and is_active=true and type in ('ACCESSION', ‘MERGING’, ‘DIVIDING’); returns empty result):

   1. in case of error - return 409 ('Reorganized and successor legal entities must not be in the process of reorganization')

5. Validate merged_from legal_entity

   1. Check merged_from legal entity exists

      1. in case of error - return 404 ('Reorganized legal entity was not found')

   2. Check merged_from legal entity is in status='active' or 'suspended'

      1. in case of error - return 409 ('Reorganized legal entity must be active or suspended')

   3. Validate merged_from_legal_entity.name from request=legal_entites.name

      1. in case of error - return 422 ('Invalid reorganized legal entity name')

   4. Validate merged_from_legal_entity.edrpou from request=legal_entites.edrpou

      1. in case of error - return 422 ('Invalid reorganized legal entity edrpou')

   5. Validate merged_from_legal_entity.id<>merged_to_legal_entity.id

      1. in case of error - return 422 ('Reorganized and successor legal entities must be different')

6. (Applies for reorganization types ACCESSION, MERGING, DIVIDING, SEPARATING)
   Validate merged_to legal_entity (each object in array).

   1. Check that each merged_to legal entity exists and unique in array

      1. in case of error - return 422 ('Successor legal entities must be different and exist')

   2. Check that each merged_to legal entity is in status='active' 

      1. in case of error - return 409 ('Successor legal entity must be active')

   3. Validate merged_to_legal_entity.name from request=legal_entites.name

      1. in case of error - return 422 ('Invalid successor legal entity name')

   4. Validate merged_to_legal_entity.edrpou from request=legal_entites.edrpou

      1. in case of error - return 422 ('Invalid successor legal entity edrpou')

7. (Applies for reorganization type TRANSFORMATION)
   Validate merged_from.legal_entity_type. Valid types: MSP, PRIMARY_CARE, EMERGENCY, OUTPATIENT.

   1. in case of error - return 422 ('Invalid legal entity type')

8. (Applies for reorganization types ACCESSION, MERGING, DIVIDING, SEPARATING)
   Validate merged_to.legal_entity_type and merged_from.legal_entity_type. Valid type transitions see in the table below.

   1. in case of error - return 422 ('Invalid legal entity type')

Valid type transitions for legal entities

Processing

API paragraph not found

Response structure

API paragraph not found

Post-processing processes

API paragraph not found

HTTP status codes

API paragraph not found