Configuring the regulations to provide access to data via SOAP and REST APIs

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

If your registry is the data owner, and you wish to establish integration API points, receive requests, and provide data to other registries and systems, configure the following regulations settings:

  1. Set up authorization and grant permission to call the business process.

  2. Model the business process to be called by another registry.

  3. Create a data model and provide read access to the registry data via the API representation).

For REST interactions, you must also grant access to the registry in the Control Plane admin console. For details, see Configuring registry access.

1. Setting up authorization to access the registry business processes

Registry administrators must set up authorization at the registry regulations level.

Configure the following files:

  • bp-auth/external-system.yml defines access to business processes

  • bp-trembita/external-system.yml configures the exchange of parameters for starting the business processes

  1. Set up access to the business processes in the target registry, which will provide a data exchange API.

    To do this, configure the bp-auth/external-system.yml file in the regulations:

    Example 1. A configuration that grants access to the business processes in the target registry
    authorization:
  realm: 'external-system'
  process_definitions:
    - process_definition_id: 'my-process-id'
      process_name: 'Your business process name'
      process_description: 'Your business process description'
      roles:
        - 'trembita-invoker'

    In this example, access to the my-process-id business process is granted for the trembita-invoker role from the -external-system Keycloak realm. The process_name and process_description parameters are optional and do not affect authorization.

    The trembita-invoker client with the same role is automatically created by the Keycloak operator in the -external-system realm when the registry is deployed. All external systems that require access to the registry on the Platform must use this client’s credentials.

  2. Configure the bp-trembita/external-system.yml file in the regulations:

    1. Configure the start variables for the business process. To do this, specify which parameters the business process will expect in the start_vars section.

      If start_vars are not defined, the business process will not work.

    2. Configure the return variables. To do this, specify which parameters the business process will return in the return_vars section.

      Example 2. Configuring an API contract for a business process
      trembita:
  process_definitions:
    - process_definition_id: 'my-process-id'
      start_vars:
        - eduname
      return_vars:
        - id
        - name

      In this example, the my-process-id business process in a target registry requires start variables to run. Without them, the process cannot be initiated. In particular, the process expects the eduname parameter to contain a student’s name.

      For an example of accepting variables in a target process, jump to Modeling the business process to be called in a target registry.

    3. Configure the return variables. In this example, the business process will return the id and name parameters. They will be written to the result variable in the Output Parameters of the same service task with the delegate.

2. Configuring the data model

Create a registry data model. Add new search conditions to provide read access to database data through the registry API representation.

For details on configuring the data model, see Configuring access to the registry’s API views.

3. Modeling the business process to be called in a target registry

Model a business process that other registries will call to obtain data. This can be any process within your registry’s business logic.

To start a business process in your registry, the system needs to accept the incoming start variables it expects. This is done using a scripted task, as shown in the following example.

accept map params bp
Figure 1. Accepting the process start variables in a target registry
Where can I find an example of a reference business process?

The Platform administrator can deploy for you a demo-registry  — a reference registry containing reference and other example files for creating a digital registry regulations. It includes various elements for developing data models, business processes, UI forms, analytical reporting, extracts, notifications, external integrations, and more.

Detailed instructions on deploying the demo-registry and obtaining reference modeling examples can be found on page Deploying demo registry with reference examples.

An example of a BPMN process diagram will be available in the demo-registry’s regulations by searching for the keywords — create-school-auto-sign. The names of the forms can be found inside the corresponding User Tasks of the business process in the Form key field.