Working with digital documents in the user portal

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

The current technical design focuses on implementing the requirements for working with files through the user portals and the interaction features between the Low-code and Data Factory subsystems.

1. Functional capabilities

To meet the requirements for working with digital documents through the user portals, the Platform provides the following capabilities:

Users can upload digital documents through the UI forms of business process tasks.
Users can download and view digital documents through the UI forms of business process tasks.

2. General implementation principles

Digital document files uploaded through the UI forms are stored in the Ceph object storage until the completion of the business process.
For each digital document uploaded through the UI form, a SHA256 hash is generated and stored as a Ceph document attribute for later use in applying a signature.
Digital document files uploaded through the UI forms and form data are stored as separate Ceph documents in different buckets (lowcode-file-storage and lowcode-form-data-storage).
To ensure the integrity of user-provided data and digital document files uploaded through the UI forms, the form’s Ceph document contains unique identifiers of the Ceph document files and the SHA256 hashes generated for them.
Unlike their IDs, digital document files are not subject to operations at the level of business processes.
When applying a signature with the user’s private key to the UI form data with digital document files, the signature is generated for the UI form data document, which contains unique identifiers of Ceph documents and SHA256 file hashes.
The exchange of digital documents between the Low-code and Data Factory subsystems of the Platform is implemented by exchanging unique identifiers and their Ceph documents via a dedicated lowcode-file-storage Ceph bucket.
All documents uploaded via a business process are stored as Ceph objects in the lowcode-file-storage bucket under the keys grouped by the prefix of the process (process/{processInstanceId}/{id}).
The low-code-file-storage bucket is used for temporary storage of digital documents during the execution of business processes. For permanent storage, a separate Data Factory registry-file-storage bucket is used.

3. System components interaction

The following diagram presents Platform services involved in the implementation and their interactions. The diagram also outlines aspects that are important to consider during the implementation.

3.1. Digital documents service

The requirements for working with digital documents through user portals are implemented via a separate Digital document service component, which uses Ceph as a file repository.

For details on the Digital documents service, see architecture/registry/operational/bpms/services/digital-document-service/digital-document-service.adoc.

3.2. Digital documents exchange between the Platform subsystems

Digital document files are an integral part of the entity within which they were saved.
The Data Factory subsystem’s REST API only handles the UUIDs and SHA256 hashes at the entities' data structure level.
When a request is made to save an entity containing UUIDs, the Data Factory expects the following:
- The lowcode-file-storage bucket must have Ceph documents with the keys that follow the process/{processInstanceId}/{UUID} naming convention. The processInstanceId value is passed as the "X-Source-Business-Process-Instance-Id" header along with the request.
- Document SHA256 hashes must match those provided with the request.
When a request is made to retrieve an entity containing UUIDs, the Data Factory ensures the lowcode-file-storage bucket has Ceph documents with the keys that follow the process/{processInstanceId}/{UUID} naming convention (the processInstanceId value is passed as the "X-Source-Business-Process-Instance-Id" header along with the request), and their SHA256 hashes match those provided as part of the entity.
Access to files uploaded as attachments to an entity at the Low-code subsystem level is only possible by obtaining the entity data and retrieving the document using the document’s UUID through the Digital documents service component.

3.3. Interaction contract between the Platform subsystems

Canonical body of the Data Factory request to save entity data with file attachments

{
  "<file_property_name>": [
    {
      "id": "{UUID}",
      "checksum": "{SHA256-hash}"
    }
  ]
}

Canonical Data Factory response to the request to receive entity data with file attachments

{
  "<file_property_name>": [
    {
      "id": "{UUID}",
      "checksum": "{SHA256-hash}"
    }
  ]
}

3.4. General structure of Ceph objects involved in the exchange between "Low-code" and "Data Factory"

Attribute name	JSON document attribute	Ceph object attribute	Value
Ceph object key		key	A unique Ceph document identifier for storing a file within the access zone of the current business process. Created automatically based on the generated id according to the process/<processInstanceId>/<id> convention.
Digital document ID	id	UserMetaData.id	A unique file ID generated using a pseudo-random number generator (cad2e994-0e32-4a9f-9959-b420e20d4522).
File name	name	UserMetaData.name	<File name>
Content type	type	Content-Type (UserMetaData.type)	application/pdf, image/png, image/jpeg
Size	size	Content-Length (UserMetaData.size)	<File size>
Document content	content	input	<File content>
Document hash	checksum	(UserMetaData.checksum)	Generated SHA256 file hash

Attribute name

JSON document attribute

Ceph object attribute

Value

Ceph object key

key

A unique Ceph document identifier for storing a file within the access zone of the current business process. Created automatically based on the generated id according to the process/<processInstanceId>/<id> convention.

Digital document ID

UserMetaData.id

A unique file ID generated using a pseudo-random number generator (cad2e994-0e32-4a9f-9959-b420e20d4522).

File name

name

UserMetaData.name

Content type

type

Content-Type (UserMetaData.type)

application/pdf, image/png, image/jpeg

Size

size

Content-Length (UserMetaData.size)

Document content

content

input

Document hash

checksum

(UserMetaData.checksum)

Generated SHA256 file hash

4. User interaction scenarios

4.1. Uploading digital documents

The following diagram demonstrates a scenario where data is provided with file attachments during a user task, processed by the business process, and used to pre-populate the next user task.

Canonical document structure in the body of a request to save form data through a server application

{
  "data": {
      "<file_property_name>": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  }
}

Format of saving documents in Ceph when processing a task request

{
  "data": {
      "<file_property_name>": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  },
  "x-access-token": "<X-Access-Token>"
}

4.2. Downloading digital documents

The following diagram demonstrates a scenario of obtaining an entity with file attachments from the Data Factory and its subsequent preparation for display via the UI form of a user task.

Canonical response from a server application to the request to obtain form data

{
  "data": {
      "<file_property_name>": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  }
}

4.3. Signing UI form data with digital documents

The following diagram demonstrates a scenario of signing data with file attachments during a user task, processing data by the business process, and saving it to the Data Factory.

Canonical document structure in the body of a request to save signed data through a server application

{
  "data": {
      "<file_property_name>": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  },
  "signature": "<e-Signature>"
}

Format of saving signed documents in Ceph

{
  "data": {
      "passport_scans": [
        {
          "id": "{UUID}",
          "checksum": "{SHA256-hash}"
        }
      ]
  },
  "x-access-token": "<X-Access-Token>",
  "signature": "<e-Signature>"
}

5. UI forms modeling

5.1. Typical configuration of the "File" type field for the regulations administrators

Menu section	Setting	Value	Description
Display	Label	<At the administrator’s discretion>	Field label for the user.
API	Property Name	<At the administrator’s discretion>	The field name in the data structure JSON document.
File	Storage	URL	Saving the content of the downloaded file on the server.
File	Url	/documents	Digital documents service address.
File	Display as Image(s)	false	Display icons for images instead of tabular view.
Data	Multiple Values	false	Support for uploading multiple files.
File	File Pattern	application/pdf,image/jpeg,image/png	A pattern of files allowed for download.
File	File Maximum Size	<At the administrator’s discretion>	Maximum file size per file.

Menu section

Setting

Value

Description

Display

Label

Field label for the user.

API

Property Name

The field name in the data structure JSON document.

File

Storage

URL

Saving the content of the downloaded file on the server.

File

Url

/documents

Digital documents service address.

File

Display as Image(s)

false

Display icons for images instead of tabular view.

Data

Multiple Values

false

Support for uploading multiple files.

File

File Pattern

application/pdf,image/jpeg,image/png

A pattern of files allowed for download.

File

File Maximum Size

Maximum file size per file.

5.2. JSON schema describing the structure of a UI form with a "File" type field

{
  "components": [
    {
      "label": "<file_property_label>",
      "storage": "url",
      "key": "<file_property_name>",
      "type": "file",
      "url": "/documents",
      "input": true
    }
  ]
}