Modelling Integrations

Integration namespaces are used to consume other REST APIs (provided by other projects or external APIs). They support the Business Analyst and the Solution Developer to call operations of the referenced API and to map the response to the ubiquitous language of the project.

Each integration namespace supports modelling the following elements:

The first thing after having created a new integration namespace is to create an API Dependency and to provide the API specification of the REST API that you want to consume. This API specification can be either in OpenAPI 3.0 (.yaml) or Swagger 2.0 (.json) format. After providing the API specification, Solution Designer will create a type-safe interface for the operations defined in the API specification. This allows developers to program against the API as if it was a service locally defined in the project. In addition, Solution Designer abstracts common components such as API URL, path-, query- and *header-*parameters away, so that the developer only needs to provide the parameter values and (optionally) a request body in order to invoke the operation.

Note: This step is not required but without providing an API specification the system cannot generate the methods to call the API operations. You can still make HTTP calls to any API, but you will have to implement each call on your own.

To use the operations, a REST Integration Service and its related Input- and Output- entities must be modelled in the integration namespace. When implementing the service, the developer can then call the operations and map from Input-entities to Parameters or Request Bodies as well as from Responses to Output -entities of services.

Tip: The entities in integration namespaces can be used as 'known entities' of External Entities in the domain namespace.

Create integration namespaces

To create an integration namespace, use the Create capability in the integration namespaces section on the project's * Overview* page. Alternatively, you can use the Create capability in the left navigation bar after clicking on * Integrations*.

An integration namespace is defined by the following master data:

  • Prefix: This is the prefix of the namespace. It is unique within a solution. Please note, that only the characters A-z (without special characters), digits and the special character "_" are permitted for a prefix! Furthermore, prefixes may not begin with a digit and the first character must be lowercase. A prefix cannot consist more than 6 characters. The prefix cannot be changed after creation (required)

  • Label: This is used to give a short description of the integration namespace and its lifecycle (required)

  • Description: This is long the description of the integration namespace and its lifecycle (optional)

You can also use the Open after creation checkbox to open the integration namespace for further editing after saving.

Edit integration namespaces

To edit the master data of an integration namespace, use the Info capability on the namespace's card in the Integration Namespaces section on the project's Overview page. Alternatively, you can use the Info capability on an integration namespace's instance page to open the Details view, navigate to the Master Data section and use the Edit Master Data capability there.

You can only edit the following fields:

  • Label

  • Description

Delete integration namespaces

To delete an integration namespace, use the Info capability on the namespace's card in the integration namespaces section on the project's Overview page or use the Info capability on an integration namespace's instance page to open the Details view, navigate to the Master Data section and use the Delete capability there.

You cannot delete an integration namespace if:

  • a Property definition in a different namespace uses an Entity of the current namespace as a Range

  • a Property association in a different namespace uses an Entity of the current namespace as a Range Restriction

  • an Entity of the current namespace is used as a Parent in a different namespace

  • an Error of the current namespace is used in a Service or Command in a different namespace

  • a Service or a Command in a different namespace uses an Entity of the current namespace as Input/Output/Payload

  • an Entity from an integration namespace is used as a known entity in an External Entity in the domain layer

Attention: You will need to confirm the action before the selected namespace is permanently deleted.