Categorizing available services 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.

1. General description

The user portal displays all services in one list, which can be inconvenient for registers with many available services.

It is suggested to implement the ability to categorize services using groups and control the order of their display, improving the user experience.

2. Actors and user roles

Citizens
Officers
Registry regulations developer

3. General principles and provisions

A business process cannot be bound to two or more groups.
A group is optional. Business processes that are not bound to a group are displayed outside the group. If you do not configure groups, no workflow is considered to be bound to the group.
Groups containing no business process available to a user are not displayed on the user portal. The administrative portal interface displays all groups.
Nesting of groups is not supported.
Implementation of internationalization for group names is not considered of this document.

4. Functional scenarios

Setting up the grouping and sorting of business processes by a regulations developer using the web interface of the administrative portal.
Validating changes to business process grouping and sorting settings when publishing regulations
Viewing a list of business processes divided into groups and ordered according to the settings using the web interface of the user portal.

5. Configuration management design

To save the grouping and sorting settings, a new registry regulations element is created — the bp-grouping.yaml configuration file, which is stored in the bp-grouping folder.

The configuration file has the following structure:

Name	Type	Description
groups	[]object	List of groups
groups[index]	object	Group
groups[index].name	string	Group name
groups[index].processDefinitions	[]string	Business processes in a group
groups[index].processDefinitions[index]	string	processDefinitionId of a business process
ungrouped	[]string	Business processes outside groups
ungrouped[index]	string	processDefinitionId of a business process

Name

Type

Description

groups

[]object

List of groups

groups[index]

object

Group

groups[index].name

string

Group name

groups[index].processDefinitions

[]string

Business processes in a group

groups[index].processDefinitions[index]

string

processDefinitionId of a business process

ungrouped

[]string

Business processes outside groups

ungrouped[index]

string

processDefinitionId of a business process

The order of groups and business processes displaying on the user interface is determined by the order in the configuration file.

The registry administrator creates or edits the configuration using the web interface of the administrative portal, or manually changes the configuration file. As a result, the settings get into the registry regulations.

When publishing the registry regulations, the regulations publication pipeline propagates settings to the user business process management service.

Based on the settings, the user business process management service returns in its response the grouped and ordered services available for a user.

The portal user sees the services divided into groups on the page with available services in the order determined by the administrator.

5.1. Administrative portal

5.2. Display in portals

The Display in portals section has to be added to the web interface of the administrative portal, in accordance with the agreed layout. This section should enable:

View business processes in groups.
Create groups.
Change group name.
Delete groups.
Add business processes to a group.
Delete business processes from a group.
Change the display order of groups.
Change the order of business processes displayed in groups and outside groups.

When you delete a group, only the group is deleted. Business processes that were tied to it go to the ungrouped category.

5.2.1. Version overview

The Changes section on the Version overview page has to display the status of changes made to the bp-grouping.yaml file, the same as it is done for the form files and business processes.

5.2.2. REST API

The API of the service for providing the configuration of the registry regulations must be supplemented with methods that support the functionality of the web interface.

OpenAPI Specification (Load)

To ensure backward compatibility with the existing registry regulations, and to simplify the logic of working with the configuration file, requests must be processed taking into account the following rules:

When generating a response:
- Groups and business processes in the response must be organized in the same way as in the configuration file.
- If the bp-grouping.yaml configuration file does not exist, the response must contain all available business processes in the ungrouped section, ordered alphabetically by name.
- Existing business processes that are not in the bp-grouping.yaml configuration file must be added in the response to the end of the ungrouped section, ordered alphabetically by name.
* If the bp-grouping.yaml configuration file does not match validation rules, return error 422.
When receiving a request to change the bp-grouping.yaml configuration file:
* If the bp-grouping.yaml configuration file does not exist in the regulations, then it has to be created.
- If the bp-grouping.yaml configuration file exists, then its contents are completely replaced by the data received in the body of the request.
- If the contents of the request body do not match validation rules, return error 422.
When the DELETE /versions/candidates/{versionCandidateId}/business-processes/{businessProcessName} request to delete a business process is sent, its processDefinitionId from the bp-grouping.yaml file also has to be deleted.

5.3. User portal

The Available services page of the user portal web interface (officer and citizen portals) must be supplemented, in accordance with the agreed layouts, with the ability to view business processes in groups. The order of displaying groups and business processes must match the order in the REST API response.

5.3.1. REST API

In the API of the user business process management service, the response to the endpoint that returns the list of business processes must be supplemented with information about grouping and display order.

OpenAPI Specification (Download)

To ensure backward compatibility with the existing register regulations, and to simplify the logics of working with the configuration file, the following rules must be taken into account when generating the response:

Groups and business processes in the response must be ordered in the same way as in the configuration file.
If there is no business process in a group available to the user, such a group must not be included in the response.
If the bp-grouping.yaml configuration file does not exist or is empty, the response must contain all available business processes in the ungrouped section, ordered alphabetically by name.
The available business processes that are not in the bp-grouping.yaml configuration file must be added in the response to the end of the ungrouped section, ordered alphabetically by name.

5.4. System components and their designation in the solution design

This section includes a list of system components that are involved or require changes/creation during implementation of the functional requirements according to the technical design of the solution.

Component	Official name	Designation / Changes
Registry regulations	registry-regulation	Extension of the regulations with the bp-grouping setting
Regulations publication pipeline	registry-jenkins	Propagation of the bp-grouping.yaml settings to the user-process-management service
CLI-utility for validation of regulations integrity	registry-regulations-validator-cli	Validation of bp-grouping.yaml
User business process management service	user-process-management	Enrichment of the list of business processes with information about the groups to which they belong
Service for managing configuration of registry regulations	registry-regulation-management	Adding methods to create, edit, and remove groups, and methods to add and remove business processes from groups
Web components and portals	common-web-app	Add UI elements to manage and view groups

Component

Official name

Designation / Changes

Registry regulations

registry-regulation

Extension of the regulations with the bp-grouping setting

Regulations publication pipeline

registry-jenkins

Propagation of the bp-grouping.yaml settings to the user-process-management service

CLI-utility for validation of regulations integrity

registry-regulations-validator-cli

Validation of bp-grouping.yaml

User business process management service

user-process-management

Enrichment of the list of business processes with information about the groups to which they belong

Service for managing configuration of registry regulations

registry-regulation-management

Adding methods to create, edit, and remove groups, and methods to add and remove business processes from groups

Web components and portals

common-web-app

Add UI elements to manage and view groups

6. Modeling of the registry regulations

6.1. Structure of the registry configuration procedure

As part of the task of extending the settings, it is necessary to extend the corresponding default registry configuration in the empty_regulation_template template of the regulation repository. By default, the bp-grouping.yaml grouping settings are empty.

Figure 1. Structure of the registry regulations

Example of the bp-grouping/bp-grouping.yaml registry configuration

groups:
  - name: First group
    processDefinitions:
      - bp-1-process_definition_id
      - bp-2-process_definition_id
  - name: Second group
    processDefinitions:
      - bp-3-process_definition_id
  - name: Third group
ungrouped:
  - bp-4-process_definition_id
  - bp-5-process_definition_id

6.2. Validation of the registry regulations

As part of implementation of the solution, it is necessary to extend the registry-regulations-validator-cli CLI utility for validating the regulations with additional rules:

Group names are unique.
Business processes in the processDefinitions and ungrouped arrays occur no more than once. That is, a business process cannot be tied to different groups at the same time, or more than one time to one group.
Business processes specified in the processDefinitions and ungrouped arrays exist in the regulations (bpmn folder).

6.3. Publication of changes to the registry regulations

The bp-grouping.yaml configuration is mounted as ConfigMap to the user business process management service (user-process-management). The regulations publication pipeline must update the content of ConfigMap bp-grouping.yaml in accordance with the content of the published registry regulations.

7. High level development plan

7.1. Technical expertise

BE
FE
DevOps

7.2. Development Plan

Extend the default registry configuration in the regulations repository template.
Extensions _ Pipeline Publications Regulations _ logic promotion settings bp-grouping.yaml in the service user-process-management.
Create the JSON validation scheme for grouping settings and validation according to the rules.
Extend the API service with user-process-management.
Extend the API service with registry-regulation-management.
Extend the administrative portal web interface for configuring business processes with the ability to manage groups and sorting.
Extend the user portal web interface for viewing business processes with the ability to display groups and business processes in groups organized according to the settings.
Develop instructions for the regulations developer and reference examples.

8. Security

8.1. Business data

Data Category

Description

Privacy

Integrity

Accessibility

Registry data containing open information

Information in the format that allows its automated processing using electronic devices, free and gratuitous access to it, as well as its further reuse

None

High

8.2. Simplified threat model

8.3. Security risk countermeasures and compliance with security requirements

Risk	Security controls	Implementation	Priority
The risk of exploiting a Gerrit web vulnerability due to incorrect typing in new API endpoints. The versionCandidateId parameter is typed as a string, but is an identifier that is then passed directly to Gerrit as a merge request number that can potentially lead to the web vulnerability	It is necessary to change the type of expected data from string to int that, in the case of transmitting incorrect data, results in a common error that can be safely processed	Not taken into account in the original design	Low

Risk

Security controls

Implementation

Priority

The risk of exploiting a Gerrit web vulnerability due to incorrect typing in new API endpoints. The versionCandidateId parameter is typed as a string, but is an identifier that is then passed directly to Gerrit as a merge request number that can potentially lead to the web vulnerability

It is necessary to change the type of expected data from string to int that, in the case of transmitting incorrect data, results in a common error that can be safely processed

Not taken into account in the original design

Low