Managing external integrations

🌐 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

Management of external integrations plays a critical role in ensuring information exchange between different systems and data sources.

REST (Representational State Transfer) and SOAP (Simple Object Access Protocol) are the primary protocols for interacting with other registries and systems to transmit data.

Based on the HTTP protocol, REST allows interaction with other registries on the Platform and external systems by sending requests and receiving responses in JSON format.
On the other hand, SOAP uses an XML schema to interact with other systems, invocating methods and passing parameters using a specific set of rules.

Fundamental principles of integration with other registries on the Platform and external systems:

  1. The registry regulations do not contain environment-specific settings to ensure configuration consistency across all instances.

  2. The registry regulations do not contain any confidential data in any form to prevent unauthorized use.

  3. Configuration settings for external integrations are not duplicated and are centrally used to ensure consistency.

  4. Adding external systems for integration with the registry does not require manual configuration of network policies to facilitate fast and secure integration.

  5. Secrets with access parameters to external systems are stored in a secure vault service called HashiCorp Vault to prevent unauthorized access to this data.

  6. The registry administrator configures integrations with other systems at the registry instance level in the Control Plane administrative panel, including integration protocol, address, authentication protocol, secrets, etc.

  7. The registry administrator is responsible for secret rotation and access parameter management for external systems.

  8. The administrator provides minimal pre-configuration at the registry regulation level for external integrations in business processes.

  9. Cross-registry SOAP integration uses standard extension connectors in the registry and does not require additional configuration at the regulation level. Such integration is performed via the Ukrainian "Trembita" Secure exchange gateway.

    This functionality is specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions. Please consult the local guidelines or documentation if you are implementing this outside Ukraine.

  10. The SOAP integration is also possible through the universal SOAP connector that extends Platform capabilities. See Data exchange via SOAP for more details.

  11. Integration with third-party systems requires additional configuration at the registry regulation level, including defining a list of operations and their types used by the registry through the standard REST integration extension—Connect to external system or simply REST connector.

    For Platform versions 1.9.3 and above, major configurations are performed at the registry instance level in the Control Plane console.

    For versions 1.9.2 and below, all configurations are performed at the registry regulations level.

Interaction settings with external systems are only possible during registry editing.

By default, when deploying the registry, three unconfigured endpoints are created for the "Trembita" SOAP services and one for the external system "Diia".

"Trembita" and "Diia" services are specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions. Please consult the local guidelines or documentation if you are implementing this outside Ukraine.

2. Integration types

The Platform allows for flexible integration with other registries and systems and supports the following interaction:
SOAP API

Interaction through the API using SOAP integration connectors is the primary type of integration interaction. An instance of the API is installed at the Platform level. Each external system of this kind must have an instance of the API installed on its side and be a registered participant in the unified, secure space where SOAP is the primary protocol for integration.

REST API

Interaction with other registries on the Platform and external systems beyond its boundaries through REST interfaces is an additional universal connection that extends the integration capabilities.

2.1. Data exchange via SOAP

The Platform allows modeling data exchange with other registries and their services in the regulation’s business processes using SOAP integration connectors.

Data exchange between such systems occurs via the SOAP (Simple Object Access Protocol) in XML format.

For more details see SOAP integration connectors with other registries.

2.2. Data exchange via REST

The REST integration of registries with other registries on the Platform and external systems allows data transfer from one registry to another or between external systems using REST requests.

REST (Representational State Transfer) is a software architecture style for creating web services. In the REST architecture, there is a set of constraints that ensure the interaction between the client and the server. REST utilizes the HTTP protocol for data transmission.

Such interaction utilizes the REST API and HTTP requests to obtain information. The interface can access the registry’s functionality and allow reading and modifying data. Data is transmitted in the JSON format. Data can be transferred in both directions—from the external system to the registry or from the registry to the external system.

To set up the interaction with other systems using REST, you need to:

  1. Configure the interaction with registries in the Control Plane administrative panel.

    For more information, see Configuring integrations with external systems in Control Plane.

  2. Perform minimal configuration at the registry regulations level.

    For more information, see REST connector: Registry regulations' settings.

  3. Model data exchange with other systems in business processes using the Connect to external system REST integration connector.

    For more information, see REST connector: Business process modeling.
For detailed information on REST integration, see Interacting via REST between Platform registries and with external systems.

3. Related pages