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

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/EH/pages/17782014108#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

device_definition_names

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