1 Purpose
2 Key points
3 Specification
4 Authorization
5 Validate legal entity
6 Validate request
- 6.1 File example
7 Service logic
- 7.1 Field matching
  - 7.1.1 device_definitions
  - 7.1.2 device_definition_names

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

This is a GraphQL method that is used in Administration panel only.
Only authenticated and authorized NHS employee with appropriate scope can upload device definitions registry.
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.
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 ).
Each Device definition in registry is validated the same as in https://e-health-ua.atlassian.net/wiki/pages/createpage.action?spaceKey=RMDN&title=%5BNEW%5D%20%28GraphQl%29%20Create%20Device%20definition WS.

Specification

  "Creates a single `DeviceRegistryJob`."
  uploadDeviceRegistry(input: UploadDeviceRegistryInput!): UploadDeviceRegistryPayload

"""
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

Create job with type upload_device_definition_registry in jobs table in JABBA DB.
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
For each created task:
1. Validate device definition records according to RС_[NEW] (GraphQl) Create Device definition_EN | Validate device definitionarchived
  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
Render job identifier with result according to specification.

Field matching

device_definitions

Attribute	Source and Logic	Type and Constraints	O/M

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

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

E-Health

RС_[NEW] (GraphQl) Upload Device definitions registry_EN