Generating excerpts in user portals

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

To fulfill the requirements of providing information services on the Platform, support for two approaches to modeling business processes has been implemented, depending on how data is displayed in the User portal:

Business process resulting in data display through a UI form in the portal
Business process resulting in a formatted excerpt, available for download from the portal and offline viewing

Current technical design focuses on the requirements for supporting information services, resulting in the generation of an excerpt from the registry at the Low-code Platform level.

For more details about the Reporting subsystem design, please refer to the following link.

1. Basic principles

Excerpts can only be generated within the scope of providing information services through business processes
Access to the information service for excerpt generation is controlled at both the business process level and the data access level required for excerpt generation
An excerpt must be presented as a distinct template at the registry regulations level and is uniquely identified by the excerpt type
Within a single business process, only one excerpt can be generated, taking into account the access rights of the user who initiated the business process for the data
A request to the "Reporting subsystem"for excerpt generation must be signed by the user’s key or a system key.
Generated excerpts can only be downloaded by the user who ordered the information service
Generated excerpts must be available for download within a specified time frame in their original form according to data access rights at the time of generation
System-level digital signatures may be applied to generated excerpts depending on the type of information service and the data upon which the excerpt is based
The necessity of applying a system-level digital signature to the excerpt is determined by the regulations administrator at the business process modeling level
The excerpt generation process must not obstruct the user’s work with the portal
Portal users have the ability to obtain information about the excerpt generation status on the "Services in progress" page and to download the excerpt document from the "Ordered services" page once it is ready.
Data preparation for generating an excerpt request is modeled at the business process level using the auxiliary Search Conditions functionality of the Platform
It is recommended to minimize the volume of data loaded at the business process level for generating the excerpt request

2. Low-level interaction design

This diagram depicts the Platform’s engaged services for requirement implementation, their interaction in terms of directions and types of data flows. Additionally, important features that need to be considered within the scope of implementation and modeling are illustrated.

2.1. Ordering an information service for excerpt generation

The information service for excerpt generation must be modeled as a distinct business process utilizing the following tools and modeling capabilities:

Synchronous or asynchronous approach to generating an excerpt within the business process framework.
Use of the Call Activity element in BPMN notation to encapsulate the interaction logic with the "Excerpt generation API"
Standard extension for generating an excerpt request.
Standard extension for obtaining information about the excerpt generation status
Standard extension for acquiring access token of the system user.
System variables of the business process instance used to display the result of excerpt generation and establish an association between the business process instance and the generated document

2.2. Logical model of the excerpt generation business process

This diagram presents the logical model of the business process for creating a request to generate an excerpt. There are two user-centric UX organizational approaches supported:

Synchronous approach to modeling the excerpt generation business process (sync), where the user, upon initiation through the portal, awaits the completion of the generation process. Subsequently, the system automatically redirects them to the "Ordered services" page, where the generated excerpt from the initial business process can be downloaded. This approach expedites user access to downloads but may also be utilized for excerpts whose generation time doesn’t worsen the UX concerning waiting time.

Asynchronous approach to modeling the excerpt generation business process (beforeAsync), where the user, upon initiating a request for excerpt generation, is redirected to the "Services in progress" page. Here, they can monitor the status of excerpt generation or continue working with the portal. In this scenario, the user will need to manually navigate to the "Ordered services" page upon completion of the excerpt generation business process.

2.3. Involved business process system variables

In order to establish an association between the initiated instance of the business process and the generated excerpt document, process variables are used. They are stored in the historical table of the business processes operational repository.

System variable name	Description
SYS_VAR_PROCESS_EXCERPT_ID	This variable is used to retain the identifier of the excerpt in case the excerpt is a result of service provision or business process execution.
SYS_VAR_PROCESS_COMPLETION_RESULT	Description of the execution result specified by the regulations administrator during business process modeling.

System variable name

Description

SYS_VAR_PROCESS_EXCERPT_ID

This variable is used to retain the identifier of the excerpt in case the excerpt is a result of service provision or business process execution.

SYS_VAR_PROCESS_COMPLETION_RESULT

Description of the execution result specified by the regulations administrator during business process modeling.

2.4. Retrieving generated excerpts through the portal

The outcome of the informational service business process is a generated document, preserved within the distributed object storage Ceph. Furthermore, the identifier of the excerpt document will be saved as an instance variable, SYS_VAR_PROCESS_EXCERPT_ID. The presence of this variable signifies an informational service where the result is an excerpt, as opposed to others. For ordered services with this characteristic, a separate "Download excerpt" option becomes available in the user portal. This option permits the download of the complete document via the "Excerpt retrieval API".

Access to the retrieval of generated documents via a unique identifier and access control is managed by a distinct backend service, the "Excerpt retrieval API". For the API contract details of the "Reporting subsystem," refer to the link.

Table 1. Error codes returned upon unsuccessful attempt to process excerpt retrieval request
Code	Description
200	OK with return of the generated excerpt file
400	Malformed request (incorrect data format)
401	Authentication error (missing access token)
404	Excerpt file not found by identifier
500	Server-side request processing error

2.5. Authorization of user access to generated excerpts

Access to the generated excerpt should only be granted to users who are authenticated in the system and who initiated the order for the informational service of excerpt generation through the business process, in accordance with the access rights configured at the regulation level.

3. Typical modeling extensions

3.1. Configuration of the standard excerpt generation extension

To facilitate the modeling of informational services that yield generated excerpt documents, a dedicated standard Java Delegate extension is employed within the modeling catalog. This extension allows the definition of all necessary parameters for the generation request.

System context variables are automatically added to the call context as HTTP headers:

X-Source-System - Names the subsystem executing the request (Low-code Platform)
X-Source-Application - Names the subsystem component initiating the request (business-process-management)
X-Source-Business-Process - Specifies the name of the business process defined by the regulation administrator during modeling (Process Name)
X-Source-Business-Process-Definition-Id - The unique identifier of the business process as defined by the regulation administrator during modeling (Process Id)
X-Source-Business-Process-Instance-Id - Automatically generated unique identifier of the instance of the business process in which the request is executed (Automatically generated, maximum length of 64 characters)
X-Source-Business-Activity - Names the service task as defined by the regulation administrator during modeling (Name)
X-Source-Business-Activity-Definition-Id - The unique identifier of the service task as defined by the regulations administrator during modeling (Id)
X-Source-Business-Activity-Instance-Id - Automatically generated unique identifier of the instance of the business process’s service task in which the request is executed (Maximum length of 64 characters)

Additionally, the extension adds the following automatically generated HTTP headers:

X-Digital-Signature-Derived - A link to the Ceph document where the system signature is stored, which is automatically applied to the request body

Configuration parameter	Input/Output	Service name	Type	Request component	Description
Access Token	in	X-Access-Token	string		HTTP header
User token used for the excerpt generation request	Original signed request document	in	X-Digital-Signature	string	HTTP header
Link to the Ceph document containing the user’s original request and signature	Report type	in	excerptType	string	JSON request body part
Type of the excerpt to be generated within the business process	System signature overlay	in	requiresSystemSignature	boolean	JSON request body part
Indicates the necessity of overlaying a system signature for the specified report type	Generation input data	in	excerptInputData	map	JSON request body part
Set of data to be transmitted as parameters for excerpt generation	Excerpt identifier	out	excerptIdentifier	string	Response body

Configuration parameter

Input/Output

Service name

Type

Request component

Description

Access Token

X-Access-Token

string

HTTP header

User token used for the excerpt generation request

Original signed request document

X-Digital-Signature

string

HTTP header

Link to the Ceph document containing the user’s original request and signature

Report type

excerptType

string

JSON request body part

Type of the excerpt to be generated within the business process

System signature overlay

requiresSystemSignature

boolean

JSON request body part

Indicates the necessity of overlaying a system signature for the specified report type

Generation input data

excerptInputData

map

JSON request body part

Set of data to be transmitted as parameters for excerpt generation

Excerpt identifier

out

excerptIdentifier

string

Response body

Example request body for excerpt generation (system signature applied to the entire request body and conveyed as a link to the Ceph document in the HTTP header X-Digital-Signature-Derived):

{
  "excerptType": "subject-laboratories-accreditation-excerpt",
  "requiresSystemSignature": true,
  "excerptInputData": {
    "subjectId": "<UUID>"
  }
}

Example response for successful excerpt generation request:

{
  "excerptIdentifier": "<UUID>"
}

Table 2. Error codes returned upon unsuccessful attempt to process request:
Code	Description
200	OK with the return of the excerpt identifier, which allows obtaining the generation status.
400	Malformed request (unknown excerpt type, missing required fields, or incorrect data format).
401	Authentication error (missing access token or digital signature).
403	Insufficient permissions to perform the operation.
500	Server-side request processing error

3.2. Configuration of the standard extension for retrieving excerpt generation status

.=== Конфігурація типового розширення для отримання інформації про статус генерації витягів

In order to provide monitoring capabilities for the execution status of an excerpt generation request, a dedicated standard Java Delegate extension is utilized within the modeling catalog. This extension allows for the definition of all necessary request parameters and obtaining the current document formation status.

Additionally, system context variables are automatically added to the call context as headers:

X-Source-System - Names the subsystem executing the request (Low-code Platform)
X-Source-Application - Names the subsystem component initiating the request (business-process-management)
X-Source-Business-Process - Specifies the name of the business process defined by the regulation administrator during modeling (Process Name)
X-Source-Business-Process-Definition-Id - The unique identifier of the business process as defined by the regulation administrator during modeling (Process Id)
X-Source-Business-Process-Instance-Id - Automatically generated unique identifier of the instance of the business process in which the request is executed (Automatically generated, maximum length of 64 characters)
X-Source-Business-Activity - Names the service task as defined by the regulation administrator during modeling (Name)
X-Source-Business-Activity-Definition-Id - The unique identifier of the service task as defined by the regulations administrator during modeling (Id)
X-Source-Business-Activity-Instance-Id - Automatically generated unique identifier of the instance of the business process’s service task in which the request is executed (Maximum length of 64 characters)

Configuration parameter	Input/Output	Service name	Type	Request component	Description
Access token	in	X-Access-Token	string	HTTP header	Token of the system user obtained within the framework of Configuration of the typical extension for obtaining a system user access token, separate stage of business process.
Excerpt identifier	in	excerptIdentifier	string	Request parameter	Unique identifier of the excerpt document, which can be used to retrieve information about the generation status
Excerpt generation status	out	status	string	Response body	Status of excerpt document generation (IN_PROGRESS, COMPLETED, FAILED)

Configuration parameter

Input/Output

Service name

Type

Request component

Description

Access token

X-Access-Token

string

HTTP header

Token of the system user obtained within the framework of Configuration of the typical extension for obtaining a system user access token, separate stage of business process.

Excerpt identifier

excerptIdentifier

string

Request parameter

Unique identifier of the excerpt document, which can be used to retrieve information about the generation status

Excerpt generation status

out

status

string

Response body

Status of excerpt document generation (IN_PROGRESS, COMPLETED, FAILED)

Example request body to retrieve the status of an excerpt generation using the key

{
  "excerptIdentifier": "<UUID>"
}

Example response for a successfully generated excerpt

{
  "status": "COMPLETED"
}

Example response for an unsuccessfully generated excerpt

{
  "status": "FAILED",
  "statusDetails": "Технічний опис помилки"
}

Table 3. Error codes returned in case of unsuccessful request processing:
Code	Description
200	OK with status returned in the response body
400	Malformed request (invalid data format)
401	Authentication error (missing access token)
404	Tracking record for excerpt generation status not found for the identifier
500	Server error processing the request

3.3. Configuration of the typical extension for obtaining a system user access token

In some cases, there is a need for business processes to interact with internal platform services at the service-2-service level, and the context of the call does not necessarily require the access token of the user who initiated the business process or is the task performer. In this scenario, the Platform provides a typical extension for obtaining an access token on behalf of a system user (service account) from Keycloak, enabling internal system requests or authorization.

Configuration parameter	Input/Output	Service name	Type	Description
Access token	out	systemUserAccessToken	string	System user token (service account created for the bpms service)

Configuration parameter

Input/Output

Service name

Type

Description

Access token

out

systemUserAccessToken

string

System user token (service account created for the bpms service)