ЕСОЗ - публічна документація

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1

Purpose

The WS is used to upload device definitions 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. This is a GraphQL method that is used in Administration panel only.

  2. Only authenticated and authorized NHS employee with appropriate scope can upload device definitions registry.

  3. This WS 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.

  4. Device definition registry input data for should be in .csv format and with escaped symbols (i.e. quotes, new lines - " as \"; new line replaced as \r\n ).

  5. Each Device definition in registry is validated the same as in /wiki/spaces/RMDN/pages/18339135535 WS.

Specification

 index.graphql
  "Creates a single `DeviceRegistryJob`."
  uploadDeviceRegistry(input: UploadDeviceRegistryInput!): UploadDeviceRegistryPayload
 deviceRegistryJobs.graphql
"""
Input for `uploadDeviceRegistry` mutation.

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

"""
Return type for `uploadDeviceRegistry` mutation.
"""
type UploadDeviceRegistryPayload {
  "Created `DeviceRegistryJob`."
  deviceRegistryJob: DeviceRegistryJob
}

"""
An object for DeviceRegistryJob.
"""
type DeviceRegistryJob implements Node {
  "The ID of an object"
  id: ID!
  "Primary key identifier from the database"
  databaseId: UUID!
  "Job name."
  name: String
  "Device 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
  ): DeviceRegistryTaskConnection!
  "Type of register originating device registry data. The value should be present in the `REGISTER_TYPE` dictionary."
  registerType: String!
  "Device registry job reason description."
  reasonDescription: String!
}

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

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

"""
A child of a `DeviceRegistryJob`, contains the result of task execution.
"""
type DeviceRegistryTask 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: DeviceRegistryTaskMeta
  "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 `DeviceRegistryTask`.
"""
type DeviceRegistryTaskMeta {
  "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 = 'device_registry:write')

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

Validate legal entity

  • Extract client_id from token.

  • Check legal entity status (status = ACTIVE)

    • In case of error - return 409 ('client_id refers to legal entity that is not active')

  • Check client type (type = NHS)

    • In case of error - return 403 ('You don't have permission to access this resource')

Validate request

  • Check that required fields according to specification are submitted

    • in case of error - return 422 ('required property <field_name> was not present') where field_name - name of missing field

  • Check that no additional fields that do not correspond to schema are submitted

    • in case of error - return 422 ('Unknown field')

  • Check that each field in request corresponds to its type in specification

    • in case of error - return 422 (In field <<field_name>>: Expected type <<field_type>>, found <<actual_value>>.') where field_name - name of error field, field_type - expected type of field, actual_value - value that was submitted to field

  • Check that $.registerType = 'UPLOAD_DEVICE_DEFINITIONS_REGISTRY'

    • in case of error - return 422 ('Invalid register_type')

  • Check that $.csvData input file size is valid - csv file with max 30000 lines is allowed.

    • in case of error - return 422 ('The number of tasks for the job with a sequential execution strategy is limited to 30,000')

  • Check that $.csvData input corresponds to file structure (described in table below)

    • in case of error - return 422 with the list of validation errors

File example

*Note. Fields device_names.name, device_names.type, properties.type, properties.value_integer, properties.value_string, properties.value_boolean, properties.value_decimal can exist as an array. Values should be separated with | (respectively).

Service logic

  1. Create job with type upload_device_definition_registry in jobs table in JABBA DB.

  2. For each line of input file create separate task of job in tasks table in JABBA DB with additional task metadata:

    1. name = ‘Create device definition’

    2. meta.csv_data_line = line from csv_file

  3. For each created task:

    1. Validate device definition records according to https://e-health-ua.atlassian.net/wiki/spaces/RMDN/pages/17670799630/NEW+GraphQl+Create+Device+definition#Validate-device-definition

      1. in case of validation error - update task status to FAILED with corresponding error message, go to next task

    2. Create new device definition in device_definitions and device_definition_names tables (PRM DB) according to field matching

    3. Update task status to PROCESSED, go to next task

  4. Render job identifier with result according to specification.

Field matching

device_definitions

Attribute

Source and Logic

Type and Constraints

O/M

id

uuid_generate_v4(), auto

uuid

M

external_id

external_id, from request

varchar(255)

O

classification_type

classification_type, from request

varchar(255)

M

description

description, from request

varchar(2000)

O

manufacturer_name

manufacturer_name, from request

varchar(255)

M

manufacturer_country

manufacturer_country, from request

varchar(255)

M

model_number

model_number, from request

varchar(255)

M

part_number

part_number, from request

varchar(255)

O

packaging_type

packaging_type, from request

varchar(255)

M

packaging_count

packaging_count, from request

int

M

packaging_unit

packaging_unit, from request

varchar(255)

M

note

note, from request

varchar(2000)

O

is_active

true, auto

boolean

M

inserted_at

now(), auto

timestamp

M

updated_at

now(), auto

timestamp

M

inserted_by

user_id, from token

uuid

M

updated_by

user_id, from token

uuid

M

properties

properties.type + properties.value[X], from request, array of objects

jsonb

O

parent_id

parent_id, from request

uuid

O

device_definition_names

For each object of device_names.name and device_names.type array create separate record.

Attribute

Source and Logic

Type and Constraints

O/M

id

uuid_generate_v4(), auto

uuid

M

device_definition_id

device_definition_id, value of device_definitions.id from created record

uuid

M

type

device_names.type, from request

varchar(255)

M

name

device_names.name, from request

varchar(255)

M

inserted_at

now(), auto

timestamp

M

updated_at

now(), auto

timestamp

M

inserted_by

user_id, from token

uuid

M

updated_by

user_id, from token

uuid

M

  • No labels