Integration modelling

Introduction

When developing microservices, the integration of other services via REST API is a highly popular scenario. Visualizing integrations to external services in a model, helps to keep the overview of the dependencies a service has, and therefore, eases the managing of those dependencies.

Integration Modelling

Integration Modelling in IBM Industry Solutions Workbench helps, to easily manage integrations to external services within the Solution Designer UI. By providing auto-generated code, it also supports during the implementation of integration logic.

The extension is available for the following stacks:

Java Spring Boot Stack 2.0.0
Java Spring Boot Stack 1.0.0 (only for Domain services and always enabled)
NodeJS TypeScript Stack (only for Domain services and always enabled)

Modelling of integrations is organized in integration namespaces, where each namespace will represent the integration to one external service. It allows to model integration services, entities and other items in order to fully cover the integration use case. Using API Dependencies also offers the capability to upload REST API specifications, which describe the API provided by the external service, which helps to ensure that the APIs are used correctly. To learn more about the modelling of integration use cases please see Modelling Integrations. In Integration namespaces all REST API based services can be easily integrated. Integrated services are not forced to be developed by IBM Industry Solutions Workbench .

💡tip

It is always recommended to use the Integration Modelling extension, when building multiple services using IBM Industry Solutions Workbench , as there are various features, which ease the integrations of those.

When implementing integration use cases, consumers need to take care, that requests to the external service are implemented correctly. With the help of the uploaded REST API specifications, it can be ensured, that the implementation matches the describe request and response structures. To learn more about this part, please check Implement integration services (Java) or Implement integration services (TypeScript).

Integration Namespaces

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:

Entities
Properties
REST Integration Services
Errors
API Dependencies

ℹ️note

For NestJs projects only API dependencies are available.

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 (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

You can edit the master data of a integration namespace by clicking the Edit namespace details button in the Namespace Details section on the integration namespace's instance page. The fields that can be edited are Label and Description.

Delete Integration Namespaces

You can delete an integration namespace by clicking the Delete namespace button in the upper right corner of the integration namespace instance page.

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

⚠warning

You will be asked to confirm the action before the selected namespace is permanently deleted.

Migration of integration namespace with multiple API dependencies

It is suggested to have one API dependency for an integration namespace from IBM Industry Solutions Workbench 3.1 onwards. Hence, user's having Integration namespace with multiple API dependencies will be seeing the first API Dependency for the integration namespace in the General tab and a warning message on the right side of the page (above the Integration namespace details section).

The following steps are suggested to migrate the old API dependencies into individual Integration Namespaces:

The user can click on the warning message which will open a sidebar card API Dependencies with the list of all existing API dependencies.
A table listing all the API dependencies will be shown with three-dots-menu for each of the API dependencies.
Use the three-dots-menu on the right side of a table row and click on Info. This will open a detailed View of the selected API dependency.
In the Info view download the API specification file by clicking on the file name. Make sure to also copy the DEV binding if one exists in order to use it when recreating the namespace.
Go ahead and create a new integration namespace.
Create an API Dependency using the downloaded API specification file and if it exists the DEV binding.
Repeat step 3 to 6 for all the API dependencies.

⚠warning

The user will be able to use the older API dependencies without migrating but won't be able to add any new dependencies to an existing integration namespace (having more than one API dependency). Support for multiple API dependencies will be removed in a future release.

Course Integration Namespaces

API dependencies

The main purpose of an API dependency is to easily call an external REST API. It consists of the two steps:

Create API specification
Configuration for Development via DEV Binding or Local Lookup

Creating an API dependency is not required to call a REST API. It is just a convenience functionality that you can use to make implementation easier. You can use the native capabilities to make HTTP calls too. Even if you create an API dependency you don't have to use all the capabilities. You can upload an API specification to get all the defined operations generated in the SDK or only use a DEV binding to store your own key/value pairs outside the implementation code and replace these values later for different deployment targets with API bindings.

💡tip

If you want to integrate an API that is provided by another project that has also been deployed with IBM Industry Solutions Workbench , you can instead use the Local Lookup function.

Solution Designer will create methods for each operation available in the API specification. These methods can be used while implementing integration services. The uploaded API specification will be placed inside the Git repository of the service project and is available to the developer while implementation.

Create an API dependency

There are two methods to create an API Dependency:

Uploading API specification file. By uploading an API specification either as OpenAPI 3 file (.yaml) or as Swagger 2.0 file (.json).
Importing API specification from an existing service project. Choosing an API from an existing service project.

Note: Only Domain Service Projects are available to import from.

Uploading specification file

To create an API dependency in Solution Designer, open an integration namespace of your service project and click on the "Dependency" tab and then click on "Add API dependency" button. Kindly fill in the required information as described below:

Property	Description
Name	This is the name of the API dependency. It is unique within an Integration Namespace. Please note that only the characters A-Za-z (without special characters), digits and the special character "_" are permitted for naming API dependency! Furthermore, names may not begin with a digit and the first character must be lowercase. This field is mandatory.
API specification	This is the specification of the API that is being integrated and it has two options: 1. "Upload specification file" for uploading specification file it shows an upload button when selected. The expected formats are JSON and YAML. The uploaded specification is later shown on the instance page of the API dependency. Please notice, that SWAGGER specifications will always be converted to a OpenAPI 3 specification while uploading the file. In all cases the file will have the suffix `.yaml`. This field has two values 2. "Choose from existing project" to import API dependency from another existing project, it also takes you through wizard steps to select API Namespace to import. This field is optional.
DEV binding	A binding always consists of a JSON string that may also include a URL (as specified in OpenAPI 3). This field is optional.
Local lookup	By using this option no additional binding information is necessary. The URL of the dependency will be changed dynamically depending on the deployment namespace. Also, the JSON Web Token (JWT) will be forwarded and used to call the API dependency. This field is optional.

After creating an API dependency, you will be able to view all the details of the API dependency in the sidebar's API dependency details card. In case an API specification has been added to the API dependency, the General tab will show the API spec in a colored graphical view. You can switch to the detailed swagger view by clicking on the script button (left of trash button). You can use the search bar to filter by methods, tags and description.

⚠warning

From IBM Industry Solutions Workbench 3.1, a user will only be able to have one API dependency for an integration namespace. For every new API dependency, a new Integration namespace has to be created.

⚠warning

User's using IBM Industry Solutions Workbench 3.0 and prior, only the first API Dependency for the integration namespace will be shown in the General tab and a warning message will be popped up on the right side (above the Integration namespace details section). For seamless use, please follow the migrations steps to migrate the old API dependencies into new Integration Namespaces.

Import from another service project

To create an API dependency based on another existing project, first you need to make sure that the modeled API you want to import is already committed to your repository then follow the following steps:

Fill in the 'Main Data' step and select "Choose from existing project" in "API Specification" field and click on button "Next".
In "Select Service Project" step you can see and select service project you want to import the API specification from. Note: Only Domain Service Projects are available to select.
In the step "Select API" you can see and select one of the modeled APIs of the choosen service project. Note: If the choosen service project contains only one modeled API, this is selected automatically and you will be guided to the next step.
The last step is "View API" step, and it displays the operations available of the selected API. And finally click on "Create" button to add the API as dependency to your Integration Namespace.

Edit an API dependency

You can edit the master data of an API dependency by using the Update API dependency button. The name of the API dependency cannot be changed. When editing the master data of an API dependency, you can update the Name, API specification, DEV binding and Local lookup.

Delete an API dependency

You can delete the API dependency by clicking on the trash button (left of Update API dependency button) in the General tab.

You will need to confirm the action before the selected API dependency is permanently deleted.

Configuring API Dependencies

To call an API Dependency some additional configurations (API bindings) are needed. Those API bindings are normaly externalized and managed per stage via Configuration Management. For development purposes IBM Industry Solutions Workbench allows to work with a development configuration, a so called DEV Binding or, for the interaction between service deployments that have been built with IBM Industry Solutions Workbench , to use a so called Local Look Up.

DEV binding

DEV bindings are optional specifications created per API dependency. This means that the DEV binding only lives as a part of the API dependency and shares its life-cycle. It is assigned a unique name internally and will not receive an identifier within Solution Designer.

You can use DEV bindings to append important information about the API you want to integrate and store it inside the integration namespace. This may be URLs, certificates, token, credentials or anything else that you want to have at hand when implementing your requests to another REST API. These bindings only consist of key/value pairs in JSON notation.

ℹ️note

Please be aware, that everybody with read access to your project can see this information! Furthermore, the DEV binding will also be stored in the Git repository that holds this service project.

Usage of DEV bindings

There are two different scenarios to provide binding information, either

for a single-deployed microservice
for a component of an application composition project

Usage in single-deployed microservices

In case you work on a service project that should get deployed directly to a deployment target (e.g. for testing purposes) you can use the DEV binding if this microservice should call an external API. Here you could provide info like the URL of this external API or a required API token to access this API.

The DEV binding will be applied to all deployments of this service project on deployment targets that have enabled the usage of DEV bindings. For deployment targets that don't allow their usage, you will have to provide an API binding with identical content. With API bindings you can provide individual values for each provided key to match the requirements of each deployment target.

If a service project has a DEV binding and also an API binding for a deployment target, the API binding will have precedence over the DEV binding on that particular deployment target.

⚠warning

If you need to provide sensitive or confidential data, we recommend using an API binding instead. While DEV bindings get stored in the Git repository, API bindings get stored as OpenShift secrets.

Usage for components in application projects

In case you work on a service project that should get released to the Component Repository (in order to use it as component) and you need to provide binding information, you have to use the DEV binding.

ℹ️note

The information provided will be published to the resulting Helm chart when you release the project. This process only uses the provided keys and ignores all values! So we recommend providing only the required keys in the DEV binding and leaving their values empty.

When someone adds this component to their application project(s), a new API binding will be generated for each deployment of the application and each binding will provide input fields to enter the values for each of the binding keys. This allows you to enter individual values for different applications and also for each deployment target. See API bindings for more details on API binding component configuration in application projects.

Local lookup

Can be used for API dependencies between microservices that also have been developed with IBM Industry Solutions Workbench and allows calling these dependencies without the need to provide additional binding information. This makes it easy and convenient to call operations provided by external APIs since the URL of the dependency will be changed dynamically and the JWT will be automatically forwarded.

Example

Example implementation:

You have a service project with an integration namespace called "Customer Need Registration". This integration namespace's acronym is cnr. Inside this namespace you have created an integration service called "AcceptOffer" and this service should call another API. To do so, you also created an API dependency with the name cnrdependency inside this integration namespace and uploaded a valid OpenAPI 3 or Swagger 2.0 file.

This API provides the operation "acceptOffer" (amongst others) that will be called in this example.

Now to implement this service you can do the following inside the implementation file of this service ( e.g., src-impl/integration/cnr/services/AcceptOffer.ts):

import { services } from 'solution-framework';

export default class extends services.cnr_AcceptOffer {

  public async execute(): Promise<void> {
    const log = this.util.log;
    log.debug('cnr_AcceptOffer.execute()');

    // Get the values for the request parameters from the input
    const {customerNeed_id, customer_ID, finPropId} = this.input;

    // Use the created API operations
    const response = await this.apis.cnrdependency.acceptOffer({customerNeed_id: customerNeed_id},{customerID_query: customer_ID,finPropId: finPropId});

...

⚠warning

Whenever you are querying external services, you should make sure, that all communication to such services are encrypted and all TLS-encrypted protocols including HTTPS use version 1.2+. The connection to the target service should be authenticated (certificate validation should be enabled)!

Implementing with DEV bindings

Example of a binding:

{
  "url": "https://example.com",
  "k5_propagate_security_token": true
}

Entering this key/value pair into the DEV binding section of an API dependency will provide the value of url in the solution framework (SDK) when implementing. They will be accessible by typing this.apiBindings.<integration namespace acronym>. inside an implementation file of an integration namespace.

Example implementation:

You have a service project with an integration namespace called "Customer Need Registration". The integration namespace's acronym is "cnr". Inside this namespace you have created an integration service called "AcceptOffer" and this service should call another API. You also created an API dependency with the name "cnrdependency" inside this integration namespace and added the information to the DEV binding as stated in the example above.

Now to implement this service you can do the following inside the implementation file of this service ( e.g., src-impl/integration/cnr/services/AcceptOffer.ts):

import { services } from 'solution-framework';

export default class extends services.cnr_AcceptOffer {

  public async execute(): Promise<void> {
    const log = this.util.log;
    log.debug('cnr_AcceptOffer.execute()');

    // Retrieve the API binding information (async call)
    const binding = await this.apiBindings.getcnrdependency();

    // Built-in parameters (url, ca_cert, k5_propagate_security_token) can be retrieved like this
    const url = binding.url;

    // the value of url will be 'https://example.com'

    ...

This will work for the following pre-defined parameters:

url - Used to pass the URL of the API to the SDK and can be overwritten with stage-dependent values by adding API bindings for the different stages.
k5_propagate_security_token - If set to true, the JSON Web Token (JWT) used in your service project will be forwarded to call the API dependency.
ca_cert - By using this option no additional binding information is necessary. The URL of the dependency will be changed dynamically depending on the deployment namespace. Also, the JSON Web Token (JWT) will be forwarded and used to call the API dependency. This option should only be used for API dependencies that have been designed and implemented with IBM Industry Solutions Workbench and are deployed within the same projects/namespaces.

⚠warning

The line length of the certificates must comply with the standard for PEM messages, with each line containing exactly 64 printable characters except the last line and 64 or fewer printable characters in the last line.

If you want to use your own custom parameters, you just have to add them to your DEV binding in the same manner.

{
  "my-custom-key": "A32k-9IFKl123",
  "another-key": 123456
}

The only difference is the way to call them:

...

    // Retrieve the API binding information (async call)
    const binding = await this.apiBindings.getCnrdependency();

    // Now call the binding parameter 'my-custom-key' like this
    const mycustomkey = binding['my-custom-key'];

...

⚠warning

The PEM contents need to be given as single line json values with line breaks encoded with \n. It is necessary to give the full certificate chain from the root, optionally the leaf certificate can be omitted. In case of error due to dev binding, please make sure the ca_cert is created properly.

💡tip

You can find detailed information on how to test and debug your project involving these bindings. See Testing and debugging for TypeScript projects or Develop Java locally for Java projects.

Entities and Properties

The entities in Integration Namespaces do not differ much from the entities in Domain Namespaces. One of the main differences is that root entities and external entities are not allowed in Integration Namespaces.

Moreover, the entities that are modelled in Integration Namespaces are used to map the external object that is returned by the API operation to the current project. Then this entity can be attached as a known entity to an external entity in the domain namespace, thus, mapping the external object to the domain logic.

Create entities

You can create new entities on the Entities tab of an integration namespace's Overview page.

entities are defined using the following master data:

Type: Integration Namespaces only support type entities
Local Identifier: This is the local identifier (name) of the entity. It is unique within a namespace. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming entities! Furthermore, local identifiers may not begin with a digit and the first character must be uppercase. The local identifier cannot be changed after creation (required)
Abstract: This is a checkbox field. When checked, it indicates that the entity will be abstract. If the field is checked, no instances of this entity can be created by the Solution Envoy environment. The default value is unchecked. This field is only available for entities and root entities
Label: This is used to name the entity (required)
Short Label: This is used to give an even shorter label (optional)
Tags: To tag the entity (optional)
Notes: This is a long description of the entity and its lifecycle (optional)
Parents: This specifies one or more entities from which the new entity will inherit properties and commands. entities can only add other entities as parents.

You can also use the Open after creation check-box to open the entity for further editing after saving.

Associate Properties

Associating properties to an entity in an integration namespace follows the same rules as in domain Namespaces. See associate properties to entities for further details.

Edit Property Associations

See edit property associations for further details.

Remove property associations

See remove property associations for further details.

Edit entities

You can edit the master data of an entity by clicking the Edit entity details button in the Entity Details section on the entity's instance page. Alternatively, you can use the Edit capability of each table row on the Entities tab of a integration namespace's Overview page. The fields that can be edited are Type, Abstract, Label, Short Label and Notes.

ℹ️note

It is not possible to change the Local Identifier for an entity.

Delete entities

You can delete an entity by clicking the Delete entity button in the upper right corner of the entity instance page. Alternatively, you can use the Delete capability of each table row on the Entities tab of a integration namespace's Overview page.

⚠warning

You can only delete an entity if it is not in use.You can check the usages of an entity by using the Information capability and navigating to the Usages section. You will need to confirm the action before the selected entity is permanently deleted.

A property is a type specific variable/field for a value or range. properties are organized into value properties and range properties.

Create properties

You can create a new property by using the Create property capability on the Properties tab of an integration namespace's Overview page.

They are defined by using the following master data:

Local Identifier: Identifier of the property. this value must be unique within the namespace and cannot be changed afterwards. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming fields! Furthermore, identifiers may not begin with a digit (required)
Type: Defines the type of the property to be created. Types could be primitive such as text, number etc. or references such as modelled Root Entities, Entities or External Entities (required)
Label: Label of the property (optional)
Short Label: Short label of the property (optional)
Tags: To tag the property (optional)
Notes: Useful information regarding the property definition (optional)

ℹ️note

If the entity you want to reference does not exist you can directly create it by using the inline "Create" action in the field Type.

Property types

The following property types are available:

Name	Type	Remark
Text	Value	Text field for short, un-formatted texts
Text/E-mail	Value	Text field for MAIL content
Text/URL	Value	Text field for URL content
Integer	Value	Allows you to save a number without decimal places
Long	Value	Type definition for a 64 bit integer
Boolean	Value	Type definition for truth values with the "true" or "false" property
Currency	Value	Type definition for monetary amounts consisting of quantity and currency code
Selection Element	Value	Type definition of a property that can take only specific values. The Enumeration Elements define the available options. If no specific values are specified for a used Selection Element, a warning appears in the Problems section. In this case, the generated source code cannot be compiled.
Date	Value	Type definition for dates without time specification
Time	Value	Type definition for time without dates specification
Decimal	Value	Allows you to save a number with decimal places
Geo Point	Value	Type definition of a Geo Point with latitude and longitude (only available for MongoDB)
Localized Text	Value	Localizable text, consisting of locale and name, for shorter texts up to 200 characters (without formatting)
Timestamp	Value	Type definition for specifications with date and time
Reference	Range	A link to another entity. Can also be defined as an array

To create a new property and immediately associate it to an entity, you must use the Add property capability within the entity's instance page and select the Create new property option. In order to add and associate an existing property to an entity, you must use the Add property capability within the entity's instance page and select the Add existing property option. In this case, you are able to select any property created in any namespace within the Domain and integration namespace of the project.

Edit properties

You can edit the master data of a property by clicking the Edit property details button in the Property Details section on the property's instance page. Alternatively, you can use the Edit capability of each table row on the Properties tab of a integration namespace's Overview page. It can also be accessed by using the capability within the Edit Property Association action.

⚠warning

If the Type of a property is changed, the type-specific values are deleted.

Delete properties

You can delete a property by clicking the Delete property button in the upper right corner of the property instance page. Alternatively, you can use the Delete capability of each table row on the Properties tab of a integration namespace's Overview page.

You will need to confirm the action before the selected property is permanently deleted.

⚠warning

When a property is used, an extended dialog appears. For control, all places where the property is used are displayed and then you are asked to confirm the deletion. When the deletion is confirmed, the selected property is permanently deleted, as well as in all places where it was used.

Course Model Entities

REST Integration Services

REST integration services are used to call operations provided by external APIs. The output of an integration service is usually the same as the response of the external API.

Create services

A service can be created by using the Create service capability on the Services tab of an integration namespace's Overview page.

Services are defined using the following master data:

Type: There is one option available and this is the REST Integration Service (required)
Local Identifier: Identifier of the service. this value must be unique within the namespace and cannot be changed afterwards. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming fields! Furthermore, identifiers may not begin with a digit (required)
Label: Label of the service (optional)
Short Label: Short label of the service (optional)
Notes: Useful information regarding the service definition (optional)

Saga Pattern Role

For Domain Service Projects (Java) where the extension Saga Pattern Support is enabled, each Integration Service can be marked as a Saga Participant.

For a service marked as a Saga Participant the following input fields are needed:

On Compensate Method: If set to true automatically an onCompensate method will be generated.
On Complete Method: If set to true automatically an onComplete method will be generated.
Propagation Level: reuqired, requires_new, mandatory, supports, not_supported, never
Completion mode: auto or manual
Options Expressions: Allows to add Key Value pairs.

⚠warning

Please note that changing the "Saga Pattern Role" field can destroy already implemented code!

Edit services

Edit master data

You can edit the master data of an service by clicking the Edit service details button in the Service Details section on the service's instance page. Alternatively, you can use the Edit capability of each table row on the Services tab of a integration namespace's Overview page. The fields that can be edited are Label, Short Label and Notes.

ℹ️note

It's not possible to edit the Type and the Local Identifier of a service.

Add input entity

It is possible to assign an Input entity to a service by either clicking on Create new private entity or Select existing entity in the Input section of the service's instance page. To add properties to the input entity click on the Add capability and choose

Create new property
Associate existing property

See Integration Properties for further details on creating properties.

Add output entity

It is possible to assign an Output entity to a service by either clicking on Create new private entity or Select existing entity in the Output section of the service's instance page. To add properties to the input entity click on the Add capability and choose

Create new property
Associate existing property

See Integration Properties for further details on creating properties.

Add business errors

To add a Business Error to a service that will get returned each time the service cannot be executed, click on Add error in the Business Errors section of the service's instance page. There are two options when adding an Error to a service:

Add new error
Add existing error

Regarding already existing errors, a list of all the errors that have been created in a project is shown. It is also possible to search for a specific error using the Search capability. One or more errors can be selected in order to be added to the service.

Delete services

You can delete a service by clicking the Delete service button in the upper right corner of the service instance page. Alternatively, you can use the Delete capability of each table row on the Services tab of a integration namespace's Overview page.

⚠warning

You will need to confirm the action before the selected service gets permanently deleted.

Business errors

These errors reflect business errors and not technical errors. That means, that every time a business condition is not met, a business error is thrown to inform the end user about the reason.

Create errors

Errors are created by using the Create error capability on the Errors tab of an integration namespace's Overview page.

Errors are defined using the following master data:

Local Identifier: This is the identifier (name) of the error. It is unique within a namespace. Please note, that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming errors! Furthermore, names may not begin with a digit and the first character must be uppercase (required)
Error Message: This is a short message that will be used to inform the user about the business condition that is not satisfied (required)
Tags: To tag the business error (optional)
Error Description: This is used to give a longer description of the error that occurred (optional)

Edit errors

You can edit the master data of an error by clicking the Edit error details button in the Error Details section on the error's instance page. Alternatively, you can use the Edit capability of each table row on the Errors tab of a integration namespace's Overview page. The fields that can be edited are Local Identifier Error Message Tags and Error Description.

Delete errors

You can delete an error by clicking the Delete error button in the upper right corner of the error instance page. Alternatively, you can use the Delete capability of each table row on the Errors tab of a integration namespace's Overview page.

⚠warning

You will need to confirm the action before the selected error gets permanently deleted. You can only delete an error if it is not in use. You can check the usages of an error by using the Info capability and navigating to the Usages section.

Using configurable bindings

IBM Industry Solutions Workbench provides bindings to abstract the modelling part from the implementation part. This allows to use an identifier of such a binding while modelling a project and later, when implementing, the user has the option to edit the value of these bindings. This is especially helpful when working on multiple stages that require different settings of the deployments.

If you were working on three different stages (DEV, TEST, PROD), it is most likely that your deployments must meet different requirements on each of those stages. If they were configured inside the project itself, one had to edit code inside the project when moving to the next stage. By using bindings, this can be done very easily simply by editing the bindings value. This can be compared with using environment variables, where a program just searches for a given key and reads its value. While the value can differ on each environment, the key always remains the same.

API bindings

Used to store additional information for API dependencies, like the URL, token information, etc. Only used when calling external REST APIs.

Introduction​