...

Link

...

Jabba service

...

Посилання на Apiary або Swagger

...

Resource

...

Jabba service

...

Посилання на ресурс, наприклад: /api/persons/create

...

Scope

...

medication_registry:write

...

Scope для доступу

...

Components

...

ePrescription

...

Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription

...

Microservices

...

API paragraph not found

...

Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC

...

Protocol type

...

API paragraph not found

...

Тип протоколу, який використовується запитом, наприклад: SOAP | REST

...

Request type

...

API paragraph not found

...

Тип запиту API, наприклад: GET, POST, PATCH…

...

Sync/Async

...

API paragraph not found

...

Метод є синхронним чи асинхронним?

...

Public/Private/Internal

...

Internal

...

Потрібно зазначити тип методу за ступенем доступності

  "Creates a single `MedicationRegistry`."
  createMedicationRegistry(
    input: CreateMedicationRegistryInput!
  ): CreateMedicationRegistryPayload

"""
Input for `createMedicationRegistry` mutation.

User must have a scope **medication_registry:write**
"""
input CreateMedicationRegistryInput {
  "Type of register originating medication registry data. The value should be present in the `REGISTER_TYPE` dictionary."
  registerType: String!
  "Create medication registry reason description."
  reasonDescription: String!
  "Input file in csv format with medication register."
  csvData: Upload!    
}

"""
Return type for `createMedicationRegistry` mutation.
"""
type CreateMedicationRegistryPayload {
  "Created `MedicationRegistryJob`."
  medicationRegistryJob: MedicationRegistryJob
}

"""
An object for MedicationRegistryJob.
"""
type MedicationRegistryJob implements Node {
  "The ID of an object"
  id: ID!
  "Primary key identifier from the database"
  databaseId: UUID!
  "Job name."
  name: String
  "Medication registry Job status."
  status: JobStatus!
  "Job execution strategy."
  strategy: JobStrategy!
  "Date and time when the job starts."
  startedAt: DateTime!
  "Date and time when the job ends."
  endedAt: DateTime
  "Tasks within this job."
  tasks(
    "A condition to be used in determining which values should be returned by the collection."
    filter: TaskFilter
    "The method to use when ordering collection items."
    orderBy: TaskOrderBy
    "Read all values in the set after (below) this cursor."
    after: String
    "Read all values in the set before (above) this cursor."
    before: String
    "Only read the first _n_ values of the set."
    first: Int
    "Only read the last _n_ values of the set."
    last: Int
  ): MedicationRegistryTaskConnection!
  "Type of register originating medication registry data. The value should be present in the `REGISTER_TYPE` dictionary."
  registerType: String!
  "Medication registry job reason description."
  reasonDescription: String!
}

"""
A connection to a list of `MedicationRegistryTask` values.
"""
type MedicationRegistryTaskConnection {
  "Information to aid in pagination."
  pageInfo: PageInfo!
  "A list of nodes."
  nodes: [MedicationRegistryTask]
  "A list of edges."
  edges: [MedicationRegistryTaskEdge]
}

"""
Reads and enables pagination through a set of `MedicationRegistryTask`.
"""
type MedicationRegistryTaskEdge {
  "The item at the end of the edge."
  node: MedicationRegistryTask!
  "A cursor for use in pagination."
  cursor: String!
}

"""
A child of a `MedicationRegistryJob`, contains the result of task execution.
"""
type MedicationRegistryTask implements Node {
  "The ID of an object"
  id: ID!
  "Primary key identifier from the database"
  databaseId: UUID!
  "Task name."
  name: String
  "Task status, is set automatically."
  status: TaskStatus!
  "Task meta data."
  meta: MedicationRegistryTaskMeta
  "Date and time when task was executed."
  endedAt: DateTime
  "Task error."
  error: TaskError
  "Technical information when task was inserted into the DB."
  insertedAt: DateTime!
  "Technical information when task was updated in the DB."
  updatedAt: DateTime!
}

"""
Metadata of a `MedicationRegistryTask`.
"""
type MedicationRegistryTaskMeta {
  "Primary key identifier of an entity from the database."
  databaseId: UUID
  "Line number of csv file from input."
  csvDataLine: Int  
}

...

Purpose

The service is designed to upload a new medication registry. The process uses the Jabba service. Upon execution of the request, a job is created, on the basis of which tasks are created. Each task is one request to create an entity from the registry.

Key points

1. NHS admin user download file with fields according to its structure.

2. The file should be in .csv format.

Specification

...

Purpose

The service is designed to uploading new medication registry. The process uses the jabba service. Upon execution of the request, a job is created, on the basis of which tasks are created. Each task is one request to create entity from registry.

Key points

1. NHS admin user download file with fields according to its structure.

2. File should be in .csv format.

3. Full medication registry input data for GraphQL mutatiuon should be in .csv format and with escaped symbols (i.e. quotes, new lines - " as \"; new line replaced as \r\n ). Please note that UI of NHS Admin panel converts csv file to appropriate GraphQL input.

Specification

  "Creates a single `MedicationRegistry`."
  createMedicationRegistry(
    input: CreateMedicationRegistryInput!
  ): CreateMedicationRegistryPayload

"""
Input for `createMedicationRegistry` mutation.

User must have a scope **medication_registry:write**
"""
input CreateMedicationRegistryInput {
  "Type of register originating medication registry data. The value should be present in the `REGISTER_TYPE` dictionary."
  registerType: String!
  "Create medication registry reason description."
  reasonDescription: String!
  "Input file in csv format with medication register."
  csvData: Upload!    
}

"""
Return type for `createMedicationRegistry` mutation.
"""
type CreateMedicationRegistryPayload {
  "Created `MedicationRegistryJob`."
  medicationRegistryJob: MedicationRegistryJob
}

"""
An object for MedicationRegistryJob.
"""
type MedicationRegistryJob implements Node {
  "The ID of an object"
  id: ID!
  "Primary key identifier from the database"
  databaseId: UUID!
  "Job name."
  name: String
  "Medication registry Job status."
  status: JobStatus!
  "Job execution strategy."
  strategy: JobStrategy!
  "Date and time when the job starts."
  startedAt: DateTime!
  "Date and time when the job ends."
  endedAt: DateTime
  "Tasks within this job."
  tasks(
    "A condition to be used in determining which values should be returned by the collection."
    filter: TaskFilter
    "The method to use when ordering collection items."
    orderBy: TaskOrderBy
    "Read all values in the set after (below) this cursor."
    after: String
    "Read all values in the set before (above) this cursor."
    before: String
    "Only read the first _n_ values of the set."
    first: Int
    "Only read the last _n_ values of the set."
    last: Int
  ): MedicationRegistryTaskConnection!
  "Type of register originating medication registry data. The value should be present in the `REGISTER_TYPE` dictionary."
  registerType: String!
  "Medication registry job reason description."
  reasonDescription: String!
}

"""
A connection to a list of `MedicationRegistryTask` values.
"""
type MedicationRegistryTaskConnection {
  "Information to aid in pagination."
  pageInfo: PageInfo!
  "A list of nodes."
  nodes: [MedicationRegistryTask]
  "A list of edges."
  edges: [MedicationRegistryTaskEdge]
}

"""
Reads and enables pagination through a set of `MedicationRegistryTask`.
"""
type MedicationRegistryTaskEdge {
  "The item at the end of the edge."
  node: MedicationRegistryTask!
  "A cursor for use in pagination."
  cursor: String!
}

"""
A child of a `MedicationRegistryJob`, contains the result of task execution.
"""
type MedicationRegistryTask implements Node {
  "The ID of an object"
  id: ID!
  "Primary key identifier from the database"
  databaseId: UUID!
  "Task name."
  name: String
  "Task status, is set automatically."
  status: TaskStatus!
  "Task meta data."
  meta: MedicationRegistryTaskMeta
  "Date and time when task was executed."
  endedAt: DateTime
  "Task error."
  error: TaskError
  "Technical information when task was inserted into the DB."
  insertedAt: DateTime!
  "Technical information when task was updated in the DB."
  updatedAt: DateTime!
}

"""
Metadata of a `MedicationRegistryTask`.
"""
type MedicationRegistryTaskMeta {
  "Primary key identifier of an entity from the database."
  databaseId: UUID
  "Line number of csv file from input."
  csvDataLine: Int  
}

Authorization

• 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 = 'medication_registry:write')

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

Validate request

1. Validate request

   1. Check that request using schema

      1. Return 422 with the list of validation errors in case validation fails.

   2. Check that registerType = 'FULL_MEDICATIONS_REGISTRY'

      1. Return 422 with the list of validation errors in case validation fails.

   3. Check csv_data input according to file structure

      1. Return 422 with the list of validation errors in case validation fails

   4. Check csv_data input file size - csv file with max 30000 lines is allowed.

      1. Return 422 The number of tasks for the job with a sequential execution strategy is limited to 30,000 in case validation fails

   File example:

*Note. Fields innms.sctid, innms.name, innms.name_original, innm_dosage_ingredients.is_primary, innm_dosage_ingredients.dosage.numerator_value, innm_dosage_ingredients.dosage.numerator_unit, innm_dosage_ingredients.dosage.denumerator_value, innm_dosage_ingredients.dosage.denumerator_unit, brand.code_atc can exist as an array. Values should be separated as | (respectively).

Service logic

1. Validate input according to schema

2. Create job with type create_medication_registry

3. For each line of input file create separate task of job

4. Each task must validate existing and create new entities of medications registry:

   1. Extract and search medications with type = INNM_DOSAGE, is_active = TRUE, innm_dosage.name, innm_dosage.form and innm_dosage.ingredients.dosage, innm_dosage.ingredients.is_primary):

      1. in case found extract connected medications more than one medication with type = BRANDINNM_DOSAGE ,is_active = TRUE, brandinnm_dosage.name, brand.form, brand.package_qty, brand.package_min_qty, brand.certificate, brand.container and brand.ingredients.dosage, brand.ingredients.is_primary, brand.manufacturer.name, brand.manufacturer.country, brand.certificate_expired_at:

         1. in case found extract connected program medication by medication_id and program_medications.medical_program_id and insert program medication with brand according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17205985289/Create+full+medication+registry#program_medications in case program medication not found

         in case innm_dosage not found insert it according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17205985289/Create+full+medication+registry#medications-(type-%3D-INNM_DOSAGE) and its ingredients https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17205985289/Create+full+medication+registry#ingredients-(for-INNM_DOSAGE)

         check existence of INNMs by innms.name_original

      2. in case innm not found - insert it according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17205985289/Create+full+medication+registry#innms

      3. in case innm is found - skip innm creation.

      in case more than one innm

      innm_dosage.form is found - return FAILED task status with error ('More than one INNM_DOSAGE with such name and form exist in medications table')

      4. in case more than one ingredient is found - return FAILED task status with error ('More than one INNM_DOSAGE ingredient with such fields exist in ingredients table')

      5. in case single medication with type = INNM_DOSAGE is found then check ingredients, in case ingredients of INNM_DOSAGE in DB are not equal to ingredients in uploaded register - return FAILED task status with error ('INNM_DOSAGE has different INNMS in ingredients table')

      6. in case medication with type = INNM_DOSAGE is not found - insert it according to Create full medication registry | medications (type = INNM_DOSAGE), its ingredients according to Create full medication registry | ingredients (for INNM_DOSAGE), brand according to Create full medication registry | medications (type = BRAND), its ingredient according to Create full medication registry | ingredients (for BRAND) and program medication with brand according to Create full medication registry | program_medications

         1. check existence of INNMs by innms.name_original

            1. in case innm is not found - insert it according to Create full medication registry | innms

            2. in case innm is found - skip innm creation.

            3. in case more than one innm is found - return FAILED task status with error ('More than one INNM with such name_original exist in innms table')

      7. in case medication with type = INNM_DOSAGE is found - proceed to brand.

   2. Extract and search connected medications with type = BRAND, is_active = TRUE, brand.name, brand.form, brand.package_qty, brand.package_min_qty, brand.certificate, brand.container, brand.manufacturer.name, brand.manufacturer.country, brand.certificate_expired_at and brand.ingredients.dosage, brand.ingredients.is_primary, brand.drlz_sku_id:

      1. in case more than one medication with such params is found - return FAILED task status with error ('More than one

         INNM with such name_original exist in innms table')

      2. in case brand not found insert brand according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17205985289/Create+full+medication+registry#medications-(type-%3D-BRAND) and its ingredient https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17205985289/Create+full+medication+registry#ingredients-(for-BRAND) .

         1. insert program medication with brand according to https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17205985289/Create+full+medication+registry#program_medications

      3. in case brand and program medication found - return FAILED task status with error ('Such medication already exist')

5. Return job identifier with result.

innms

...

Attribute

...

Source and Logic

...

Type and Constraints

...

O/M

...

id

...

uuid_generate_v4(), auto

...

uuid

...

M

...

sctid

...

innms.sctid, from request

...

varchar(255)

...

O

...

name

...

innms.name, from request

...

varchar(255)

...

M

...

name_original

...

innms.name_original, from request

...

varchar(255)

...

M

...

is_active

...

true, auto

...

bool

...

M

...

inserted_by

...

user_id, from token

...

uuid

...

M

...

updated_by

...

user_id, from token

...

uuid

...

M

...

inserted_at

...

now(), auto

...

timestamp

...

M

...

updated_at

...

now(), auto

...

timestamp

...

M

...

1. 1. 1. BRAND with such fields exist in medications table')

      2. in case single medication with type = BRAND is found then check ingredients, in case ingredient of BRAND in DB is not equal to ingredient of a brand in uploaded register - return FAILED task status with error ('Invalid BRAND ingredients in ingredients table')

      3. in case medication with type = BRAND is not found OR is absent in registry - insert brand according to Create full medication registry | medications (type = BRAND), its ingredient according to Create full medication registry | ingredients (for BRAND) and program medication with brand according to Create full medication registry | program_medications

      4. in case medication with type = BRAND is found - proceed to program medication.

   2. Extract and search connected program medication by:
      In case registry_number = NULL then search by medication_id (with type = BRAND) and program_medications.medical_program_id and program_medication.registry_number IS NULL;
      In case registry_number has id then search by medication_id (with type = BRAND) and program_medications.medical_program_id and program_medication.registry_number;

      1. in case more than one program medication with such params is found - return FAILED task status with error ('More than one PROGRAM_MEDICATION with such fields exist in program_medications table')

      2. in case program medication is not found - insert program medication with brand OR with innm_dosage according to Create full medication registry | program_medication

      3. in case program medication is found - return FAILED task status with error ('Such medication already exist')

2. Return job identifier with result.

innms

...

medications (type = INNM_DOSAGE)

...

ingredients (for INNM_DOSAGE)

ingredients (for BRAND)

medications (type = BRAND) (may be absent)

...

ingredients (for BRAND)

program_medications

...

...

float8

...

O

...

consumer_price

...

program_medications.consumer_price

...

float8

...

O

...

reimbursement_daily_dosage

...

program_medications.reimbursement_daily_dosage

...

float8

...

O

...

estimated_payment_amount

...

program_medications.estimated_payment_amount

...

float8

...

O

...

start_date

...

program_medications.start_date

...

date

...

O

...

end_date

...

program_medications.end_date

...

date

...

O

...

registry_number

...

program_medications.registry_number

...

varchar(255)

...

O

Example with values:

View file
name medication_registries.csv

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 = 'medication_registry:write')

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

Headers

Наприклад:

• Content-Type:application/json

• Authorization:Bearer c2778f3064753ea70de870a53795f5c9

• api-key:uXhEczJ56adsfh3Ri9SUkc4en

Request data validation

Validate request

1. Check that request using schema

   1. Return 422 with the list of validation errors in case validation fails.

2. Check that registerType = 'FULL_MEDICATIONS_REGISTRY'

   1. Return 422 with the list of validation errors in case validation fails.

3. Check that reasonDescription filled

   1. Return 422 with the list of validation errors in case validation fails.

4. Check input file according to file structure

   1. Return 422 with the list of validation errors in case validation fails.

5. Check input file size - csv file with max 30000 lines is allowed.

   1. Return 422 The number of tasks for the job with a sequential execution strategy is limited to 30,000 in case validation fails

File example:

*Note. Fields innms.sctid, innms.name, innms.name_original, innm_dosage_ingredients.is_primary, innm_dosage_ingredients.dosage.numerator_value, innm_dosage_ingredients.dosage.numerator_unit, innm_dosage_ingredients.dosage.denumerator_value, innm_dosage_ingredients.dosage.denumerator_unit, brand.code_atc can exist as an array. Values should be separated as | (respectively).

HTTP status codes

...

HTTP status codes