Digital registry regulations

🌐 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 Registry regulations is a digital representation of important aspects of the registry functioning, consisting of declarative descriptions of the organizational structure, data model, information and administrative services, access rights, templates of excerpts and messages, settings of integrations with external systems, etc.

The registry regulation together with the operational registry configuration constitute a necessary and sufficient description of the functionalities implemented in the registry and settings to ensure that the appropriate level of quality of their provision to end users.

The Platform for state registries implements a Low-code approach to development of digital regulations using service web interfaces — Registry Regulation Modeling Subsystems. Registry regulations, along with change history, are stored in the appropriate version control repository Git (Gerrit) of the registry instance on the Platform to ensure auditability and rollback.

The registry regulations deployment subsystem handles validation, automated testing, and applying changes to the regulations of the registry operational zone services.

2. Structure

2.1. Logical representation

This flowchart shows the components of the registry regulations that are currently supported by the Platform to implement the functionality of the registries.

When modeling regulations, the relationships shown in the diagram below are supported between their components.

2.2. Physical representation

The registry regulations are represented in the Git repository as a set of directories with files. Each file is responsible for configuring a separate aspect of registry functioning according to requirements.

3. Components

3.1. General registry settings

Redesign planned and documented. You can find out more in the Management of registry settings at the regulation level section.

This component of the regulations is responsible for configuring registry customizations, and is represented in the repository as two directories and settings files in the YAML format:

./settings/settings.yml: Registry customization settings (short name, full name, etc.)

The format of defining general registry settings in the YAML format:

settings:
  general:
    title: "<Setting value>"
    titleFull: "<Setting value>"

./global-vars/camunda-global-system-vars.yml: Registry settings (applied portal theme, email address of Support, etc.)

The format of defining general registry settings in the YAML format:

supportEmail: "<Setting value>"
themeFile: "<Setting value>"

You can find out more about design of the subsystems responsible for configuring and applying general registry settings in the corresponding sections:

3.2. Registry data model

This component of the regulations is represented as an individual directory:

./data-model - contains a set of Liquibase files for management of:
- Physical model of the database
- Specification of API access to data
- Data access rights
- Data for initial download

You can learn more about the design of the subsystems responsible for modeling and using the data model in the corresponding sections:

3.3. Registry business processes

This component of the regulations is responsible for the models of business processes, business rules and is represented as individual directories:

./bpmn: Contains files in BPMN format with models of administrative and information registry services.
./dmn: Contains files in DMN format with models of business rules for using in registry business processes.
./bp-grouping/bp-grouping.yml: Contains settings of grouping and the order of display in portals of user of business processes of the registry administrative and information services.

The format of defining settings for business processes grouping in the YAML format:

groups:
  - name: "<Group name>"
    processDefinitions:
      - "<Business process key>"
      - ...
  - ...
ungrouped:
  - "<Business process key>"
  - ...

You can read more about the design of subsystems responsible for modeling and using business processes and business rules in the relevant sections:

3.4. UI forms of registry business processes

This component of the regulations is responsible for setting up UI forms of user tasks in the registry business processes. It is represented as two directories:

./forms: Contains files with a description of the UI form structures in JSON format, compatible with Form.UI.
./form-scripts: Contains JavaScript files describing functions used in UI forms.

You can find out more about the design of subsystems responsible for modeling and using UI forms in business processes in the relevant sections:

3.5. Registry user roles

This component of the regulations is responsible for setting up the roles of registry users and is represented in the repository as an individual directory with two settings files in YAML format:

./roles/citizen.yml: Contains a list of the citizen roles.
./roles/officer.yml: Contains a list of the officer roles.

The format of defining the registry regulatory roles in YAML format:

roles:
  - name: "<Role service name>"
    description: "<Description of regulations role>"
  - ...

3.6. Access rights to the registry business processes

This component of the regulations is responsible for setting access rights to business processes and is represented in the repository as an individual directory with three settings files in YAML format:

./bp-auth/officer.yml: Settings of access rights for officers to business processes.
./bp-auth/citizen.yml: Settings of access rights for citizens to business processes.
./bp-auth/external-system.yml: Settings of access rights for external systems to business processes.

The format of defining access rights to business processes in YAML format:

authorization:
  realm: "<realm: [officer,citizen,external-system]>"
  process_definitions:
    - process_definition_id: "<Business process key>"
      process_name: "<Business process name>"
      process_description: "<Business process description>"
      roles:
        - '<Role>'
        - '...'
    - ...

You can learn more about the design of the subsystems responsible for setting up and using access rights in the corresponding sections:

3.7. Templates for analytical reports

This component of the regulations is responsible for setting up dashboard templates for viewing data and registry audit event logs. It is represented as the relevant directory:

./reports: Contains templates of information panels as JSON-format files compatible with Redash.

You can find out more about the design of the subsystems responsible for modeling and using dashboard templates in the corresponding sections:

3.8. Templates of excerpts from the registry

This component of the regulations is responsible for setting templates for generating excerpts from the registry. It is represented as three directories, taking into account the types of excerpts supported by the Platform for state registries:

./excerpts: Contains template files in FTLH format for generating PDF excerpts.
./excerpts-docx: Contains template files in DOCX format for generating DOCX excerpts.
./excerpts-csv: Contains template files in JSON format for generating CSV excerpts.

You can learn more about the design of the subsystems responsible for modeling and using excerpt templates in the corresponding sections:

3.9. Templates for registry information notifications

This component of the regulations is responsible for setting up templates for sending informational messages to registry users. It is represented as three directories, taking into account the communication channels supported by the Platform for state registries:

./notifications/inbox: Contains template files in FTL format for generating in-app notifications.
./notifications/email: Contains template files in FTLH format for generating the body of email notifications.
./notifications/diia: Contains template files in the DIIA text format used in the Diya ecosystem to generate notifications.

You can read more about the design of the subsystems responsible for modeling and using information notification templates in the corresponding sections:

3.10. Registry integration with external systems

This component of the regulations is responsible for setting up the outgoing and incoming integrations of the registry and is represented as an individual directory with two settings files in YAML format:

./bp-trembita/configuration.yml: Configuration of integration points with external systems according to registry configuration.

The format of defining general registry settings in YAML format:

external-systems:
  external-system-name1:
        operations:
          ...
  external-system-name2:
        operations:
          ...
  ...

./bp-trembita/external-systems.yml: API settings for calling business processes by external systems.

The format of defining general registry settings in YAML format:

trembita:
  process_definitions:
    - process_definition_id: '<Business process key>'
      start_vars: []
      return_vars: []
   - ...

You can learn more about the design of the subsystems, responsible for configuring and using the settings for integrations with external systems, in the corresponding sections:

3.11. Registry regulations testing

This component of the regulations is responsible for setting up the API modeling of external systems and a set of automated tests. It is represented as two directories:

./autotests: A suite of BDD functional tests for automated registry testing.
./mock-integrations: A set of JSON-files in Wiremock-format with a description of the API rules for mocking external systems for the purpose of their further modeling in the process of manual and automated registry testing.

You can read more about the design of the subsystems responsible for modeling and using the regulation component in the corresponding sections: