Release notes

These release notes present the current version 4.1.0 of IBM Industry Solutions Workbench, which became generally available on 2023 November 3rd (GA).

New features

FeatureDescriptionAvailable since version
Java Spring Boot Stack 2.0 StackNew Java Spring Boot Stack 2.0 introduced (based on Java 17 and Spring Boot 3)4.1.0
Saga Support for distributed transactionsFor Java Spring Boot Stack 2.0 Saga Pattern Support can now be enabled4.1.0
Update of default dependencies in Generic Service ProjectsNewly created Generic Serivce Projects (TypeScript and JavaScript) will automatically use the latest dependencies of the modules that are available by default. Already created projects will not be updated automatically.4.1.0
Extended validation supportAPI specifications are now validated when cloning and during pipeline execution. Also, additional warnings are shown if business events that still use entities as payloads as Event Support 1.0 is deprecated.4.1.0
Custom API binding values at Application Composition ProjectsFor API bindings in the Application Composition Projects, custom key/value pairs can be added as additional parameters.4.1.0
Access deployed Application Composition ProjectYou can directly jump from the Solution Designer to a deployed Application.4.1.0
Get Argo CD Data visualized in the Solution HubFor all deployed Application Composition Project you can now access the most important information directly in the Solution Hub.4.1.0
Show schema usagesWithin the schema instance page now a new part shows where the schemas are used.4.1.0
Share your workspaces with co-workersYou now simply can share your workspace with co-workers by simply handing over a token. Co-workers then easily create the same setup based on that token and later also can synchronize with the source workspace.4.1.0
Sort the properties of an entityIn Domain Namespaces you can now sort the properties of an Entity or a Root Entity according to your needs4.1.0
Branching SupportSolution Designer now shows the current branch and gives the possibility to checkout remote branches for the projects. Also deletion of single branches is supported.4.1.0
Design Model Validation for CLITo validate the local state of the design model a new validation method has been introduced in the CLI4.1.0
Event EnhancementsAdded flexibility to set headers and the message key when publishing events as well as accessing headers and the message key in agents.4.1.0
Enhancement for Domain Service ProjectsFrom this version on, you can specify 0-50 number of decimal places for Decimal properties in the Domain & Integration Namespaces4.1.0
Enhancement for better user experienceComponent source is now shown for Application Composition Projects.4.1.0
Enhancement for better user experienceAPI bindings and Topic bindings are refreshed after any change of a component of an application.4.1.0
Create via header navigationThe user has the possibility to access different create actions without navigating away from the current context.4.1.0
BAW Toolkit generation for API NamespacesImproved usage of generated toolkits. Please see Modelling APIs for more details.4.1.0
Event Support 2.0With that version the product offers the possibility to connect to a central Schema Registry and manage schemas via the Solution Designer. The current functionality Event Support 1.0 is still supported with a compatability mode.4.0.5
Fully customizable Helm ChartsThe helm charts that are used for the build and deployment of service project can now be modified or completely overridden for specific projects if needed, see customized helm charts.4.0.5
Custom secrets for application composition projectsIt's now possible in the Solution Designer to add kubernetes secrets for Application Composition Projects such that it can be used by the external component.4.0.5
Enhancement for Domain Service ProjectsInline and referenced responses in context of an API operation can now be edited via the Solution Designer.4.0.5

Changes

TopicDescriptionChanged in version
Creation of projectsThe naming of the available project types changed. For more information please check the Projects Overview4.1.0
Creation of projectsNew created service projects of type Domain Service (Java) are based on Java Spring Boot Stack 2.04.1.0
Creation of projectsDuring service project creation, specifying a "Category" for the service is no longer possible. To classify services, it is recommended to use "Tags" instead4.1.0
Implementation of API operations (Java)For Domain Service (Java) projects, the generated method signature of API operations might change, which requires code adaptions. Please check the Upgrade notes for further details.4.1.0

Resolved Issues

TopicDescriptionResolved since version
Solution DesignerCheckout of a branch into the Solution Designer now shows proper error message if there is an invalid API, that cannot be handled4.1.0
Domain Service ProjectsEditing of a schema property of type array is now possible4.1.0
Domain Service ProjectsGeneration of invalid APIs including duplicates is now avoided4.1.0
Domain Service Projects (Java)Using the date type for sending events is blocked by the sender due to wrong validation4.1.0
Domain Service Projects (Java)Required API headers are ordered before optional parameters in the implementation4.1.0
Domain Service Projects (Java)Using the date type for sending events is blocked by the sender due to wrong validation4.1.0
Swagger-UINew Generic Service Projects (Java) use correct baseURL for the Swagger UI. For existing projects check migration documentation4.1.0
Certificate handling in CLIDuplicate and invalid certificates are not handled well in CLI4.1.0
Solution DesignerLeft menu navigation is available in case of an error4.0.5
Solution Designer & Solution HubIn case of an invalid entered URL a 404 page is shown4.0.5
Asset CatalogsAssets can now be filtered by tag4.0.5
Asset CatalogsWhen sharing an asset the version (SemVer) is now checked properly4.0.5
Asset CatalogsNew Service Projects created from Assets have no invalid references4.0.5
Asset CatalogsCorrect error message is now shown in case of missing permissions4.0.5
Asset CatalogsBitbucket is now supported for Asset Catalog4.0.5
WorkspacesFilter options are now in relation to each other4.0.5
WorkspacesAdding a project now supports filtering by tag4.0.5
Application Composition ProjectsAdjusted error message in case of missing permissions4.0.5
Application Composition Projectsyaml editor for component configuration does not display more than 8 lines4.0.5
Application Composition ProjectsError message is not displayed correctly if a selected component is not in the Helm repository4.0.5
Service ProjectsDeploy pipeline cannot check deployment status4.0.5
Domain Service ProjectsWhile changing an API using the Expert View adjusted meta information and documentation on API Namespace level is now kept4.0.5
Domain Service ProjectsAPI Dependency in Integration Namespacesnow uses the full height for the code view4.0.5
Domain Service ProjectsDescription of business errors in Domain Namespaces migrated to a simple text field4.0.5
Domain Service ProjectsProblem navigation not working properly in case of missing k5_propagate_security_token4.0.5
Domain Service ProjectsSidebar action now closes after creation of a namespace4.0.5
Domain Service ProjectsPrefix of namespace allows now camelCase4.0.5
Domain Service ProjectsAdded validation for invalid path parameters4.0.5
Domain Service Projects"required" is now shown on the instance page of a schema4.0.5
Domain Service ProjectsValidation fails in a nested oneOf hierarchy due to discriminator validation4.0.5
Domain Service ProjectsOneOf Discriminator property error message is not clear4.0.5
Domain Service ProjectsAfter changing an API using the Expert View default parameters are shown as modelled Header Parameters4.0.5
Domain Service ProjectsThe service instances page displays the inputs and outputs of the deleted services4.0.5
Domain Service Projects (Java)Documentation Setup Java for local profile is not correct4.0.5
Domain Service Projects (Java)When creating or editing enums, spaces that are entered at the beginning or end are automatically deleted4.0.5
Domain Service Projects (Java)External entity constructor input properties cause Java code to fail4.0.5
Domain Service Projects (Java)It is now possible to call an integration service from within an agent execution and the required JWT token will be provided4.0.5
Domain Service Projects (Java)API parameters do not support uppercase for enum values4.0.5
Domain Service Projects (Java)Using same service name in different namespaces may cause server errors4.0.5
Domain Service Projects (Java)Incorrect alignment of the configuration in the generated local configuration template4.0.5
Domain Service Projects (Java)oneOf schema discriminator enum value is generated incorrectly4.0.5
Domain Service Projects (Java)Setting table names for Java RDBMS on abstract root entities is now possible. Also, the limitation for table names to 30 chars has been removed.4.0.5
Domain Service Projects (Java)Repo variable is not assigned to associated field in services constructor4.0.5
Domain Service Projects (Java)Changing property type does not delete additional information of associations4.0.5
Domain Service Projects (Java)Indentations in example application-local.template.yaml are incorrect4.0.5
Domain Service Projects (TypeScript)Projects can't be compiled if an API schema contains enum values4.0.5
Domain Service Projects (TypeScript)SchemaFactory always returns the same instance4.0.5
Domain Service Projects (TypeScript)References of linked schemas are not created and linked incorrectly4.0.5
Domain Service Projects (TypeScript)API Schemas with AllOf-schemas ignore the directly associated properties in the code4.0.5
Domain Service Projects (TypeScript)Error cloning TypeScript Domain Service projects when using a custom schema type as query parameter in an API operation4.0.5
Domain Service Projects (TypeScript)Schemas with allOf schema ignore the directly assigned properties4.0.5
Domain Service Projects (TypeScript)isInstanceOf is missing for external entities4.0.5
BAW Toolkit generation for API NamespacesError when using the BAW toolkit if the x tracing header object is not set4.0.5
BAW Toolkit generation for API NamespacesBAW toolkit now also works in container environments4.0.5
Product InstallationError regarding k5-project resource when Istio support is enabled4.0.5
Product InstallationConfigMap k5-solution-global-values is not created automatically in k5-projects4.0.5

Known issues

TopicDescriptionKnown since version
Domain Service Projects (Java)In Java projects created from an asset, the build step in the CI/CD pipeline might fail, because while importing a Java project asset all comments in the pom.xml are removed, including needed comments for the code generation.
Remediation: Please compare the imported pom.xml file of the created project with the origin pom.xml file of the asset and add the missing comments. Please see also Implement Domain Service Java for more information about the structure of the pom.xml of Java projects.
4.1.0
Deletion of Saga ParticipantsUser is unable to delete the participant or change its Saga role to None in spite of being not used in the service project. The same named domain namespace and the same named service (Saga participant) is linked to a Saga orchestrator either in a different branch or in a different service project.
Workaround: Remove the link of that specific Saga participant from the Saga orchestrator(s) and then only you can delete the Saga participant from the desired domain namespace
4.1.0
Implementing Domain Services (Java)In Java Spring Boot Stack 2.0, saving domain entities with BigDecimal property (or any type from java.math) to MongoDB will throw an InaccessibleObjectException. As a workaround for single deployment services, use the following API to add the following to JAVA_OPTIONS --add-opens=java.base/java.time=ALL-UNNAMED --add-opens=java.base/java.math=ALL-UNNAMED and for application composition, add the following to values.yaml: additionalJavaOptions: "--add-opens=java.base/java.time=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED"4.1.0
Domain Service Projects (Java)Log tracing in Java Spring Boot Stack 2.0 can be fixed with the following steps:
  1. Adjust *Application class by updating @SpringBootApplication annotation to exclude org.springframework.boot.actuate.autoconfigure.tracing.otlp.OtlpAutoConfiguration.class
    @SpringBootApplication(
    exclude = {
    .., org.springframework.boot.actuate.autoconfigure.tracing.otlp.OtlpAutoConfiguration.class
    }
  2. Update application.yaml
    management.tracing.propagation.produce: W3C, B3_MULTI
    otel:
      traces.exporter: none
      metrics.exporter: none
      logs.exporter: none
      exporter.otlp.enabled: false
  3. Add the following dependencies to dependencies section in pom.xml
    <dependency>
      <groupId>io.opentelemetry.instrumentation</groupId>
      <artifactId>opentelemetry-instrumentation-api</artifactId>
      <version>1.32.0</version>
    </dependency>
    <dependency>
      <groupId>io.opentelemetry.instrumentation</groupId>
      <artifactId>opentelemetry-spring-boot-starter</artifactId>
      <version>1.32.0-alpha</version>
    </dependency>
    <dependency>
      <groupId>io.opentelemetry.instrumentation</groupId>
      <artifactId>opentelemetry-instrumentation-api-semconv</artifactId>
      <version>1.32.0-alpha</version>
    </dependency>
  4. Enable the console by adjusting logback-spring.xml
    <property name="CONSOLE_LOG_PATTERN" value="${CONSOLE_LOG_PATTERN:-%clr(%d{yyyy-MM-dd HH:mm:ss.SSSZ}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr(---){faint} %clr([%15.15t]){faint} %clr([USER:%X{X-USER},%X{traceId:-},%X{spanId:-}]) %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}}"/>
4.1.0
Domain Service Projects (Java)Java Spring Boot Stack 2.0 Domain properties of type offsetDateTime throws a DateTimeException when persisting in MongoDB with offsetDatetime.MAX or offsetDatetime.MIN. You may safely work with dates with years within the inclusive range 0 through 9999. MongoDB Manual4.1.0
Domain Service Projects (Java)Java Spring Boot Stack 2.0 Saga orchestrator service with list input or output is currently not supported. As a workaround, create a single entity containing the list property of the desired entity.4.1.0
Generic Service Projects (Java)Entries in application-local.template.yaml are not aligned with the expected configuration keys in Java Spring Boot Stack 2.0. Now it is:
k5.sdk:
  consumer:
   kubernetes:
    namespace: ""
  oidc:
   clientRegistrationId: <OAuth2 client Id>
while it should be:
k5.sdk.springboot:
  kubernetes:
     namespace: <kubernetes-namespace>
  oidc:
   clientRegistrationId: <oauth2-client-id>
4.1.0
Implementing Domain Services (Java)Domain Properties of type "Geo Point" and "Currency" are using the old location of the GeoPoint/Money class, causing a compilation error for Java Stack version 2.
Workaround: Create a new package [BasePackage].sdk.domain.type in /src/main/java. Copy the Money and GeoPoint class located in src/main/generated/[BasePackage].sdk.domain.type inside the newly created package and adjust the package declaration of the copied classes to [BasePackage].sdk.domain.type.
4.1.0
Generic Service Projects (Java)The JSON formatted logs are no longer printed out. Instead only java.lang.NoSuchMethodError: 'java.time.Instant ch.qos.logback.classic.spi.ILoggingEvent.getInstant()' is logged.
Workaround: In your pom.xml of the application please add the following line to the section of the properties:
<logstash-logback-encoder.version>7.3</logstash-logback-encoder.version>
and in the section of the dependencies:
<dependency>
  <groupId>net.logstash.logback</groupId>
  <artifactId>logstash-logback-encoder</artifactId>
  <version>${logstash-logback-encoder.version}</version>
</dependency>
4.1.0
Saga Support for distributed transactionsIn case that there is an invalid URL for the lra coordinator configured, the error handling is insufficient
Remediation: Provide the correct URL for the lra coordinator.
4.1.0
Implementing Domain Services (TypeScript)Event using entity as payload fails if property "id" is used.
Remediation: Use schema for event payload or rename the property to a different naming
4.0.5
Domain Service ProjectsWhen creating a "OneOf Schema" and specifying a discriminator, a required property is created with the name of the discriminator, which is automatically attached to each schema belonging to the "OneOf Schema".
Remediation: If one of these schemas is used independently, the discriminator property must be set to #/components/schemas/<schema_localIdentifier> accordingly.
4.0
Domain Service ProjectsIf one of the schemas of a oneOf-schema contains a property with the same name as the name of the discriminator, then this property will be replaced by the discriminator. The discriminator is an Enum value of type String.
Remediation: Make sure that there are no properties in any of the schemas of a "oneOf-schema" that have the same name as the discriminator.
4.0
Domain Service ProjectsWork with multiple developers on a project can lead to conflicts.
Remediation: In case of conflicts, delete the package-lock.json of the project and execute k5 pull.
4.0
Domain Service Projects (Java)The root level "pom.xml" file is not automatically updated when the Java SDK version has changed.
Remediation: Update the pom.xml file manually if the Java SDK version has changed.
4.0
Git Provider ConnectivityThe first commit to GitHub Enterprise shows incorrect user data in the Git repository.4.0
Git Provider ConnectivityWhen getting new permissions or when permissions are changed in the repository membership or role assignment, it may take up to a maximum of 3 minutes to activate them if the repository membership is changed. This time period is currently not configurable.
Remediation: If the role assignment is changed, you have to log out and log back in to activate the permissions. To reduce the time required to activate the new permissions, you can clear the cache manually by calling the appropriate API, for example, via the Swagger UI interface.
4.0
Runtime ConfigurationExisting default or custom bindings in runtime namespaces are working, but are not displayed through the Configuration Management REST API.4.0
Environment ConfigurationIt is not possible to configure more than one Message Hub Service Binding (Kafka binding) at the environment level in Solution Hub.
Remediation: You can still configure and use multiple Message Hub service bindings at the project level.
4.0
Implementing Domain Services (TypeScript)Local debugging of TypeScript Domain Service Projects that contain events requires additional manual configuration to connect to the Kafka cluster.
Remediation: Manually configure the local debugging to connect to the Kafka cluster.
4.0
Implementing Domain ServicesSending an array / a complex payload entity (i.e. has properties that are entities) is not supported due to the way an entity is represented (nested value dictionaries) that are not able to be constructed back when consuming events and firing agents. If the event payload is a simple structure (an entity with simple properties), it is successfully reconstructed, the event is consumed, and the agent is fired.4.0
Application Composition ProjectsWhen the version of a component in use is changed, the associated binding information (API binding(s) and theme binding(s)) is not automatically updated.
Remediation: When you have changed the configuration of the component, please save a copy of the content and then remove the component. Then click the "cog wheel" icon and click the "API Bindings/Theme Bindings" button. Finally, add the component back in the desired version and paste the configuration again.
4.0
Swagger-UI - Execute button does not responseThe Swagger UI API has two known issues that can cause the "Execute" button to not work: #6295 Execute button is not working with 'malformed' JSON body, and #7784 OAS2: Execute button doesn't work if the request body fails schema validation4.0
Domain Service ProjectsAdding an entity name with a suffix "Entity" (e.g. petEntity) in the domain namespace results in a compilation error because the SDK currently uses the "Entity" suffix as the reserved name for the entity interface. In the future, the generated interfaces will be removed.4.0
Domain Service ProjectsIf you add any primitive type as operation response body this will lead to 502 statusCode.4.0
Service ProjectsThe default branch name of a project cannot be changed later.4.0
Domain Service Projects (Java)Enum values in API parameters that are not written in uppercase only lead to the exception MethodArgumentTypeMismatchException
Workaround: The missing converters have to be created manually for each enum class, which is affected:
  1. Create a package web under your application package
  2. Create for each affected enum class a converter similar to:
    package [MYAPP].web;
    import org.springframework.core.convert.converter.Converter;
    import [MYAPP].sdk.api.[MYAPI].model.[MYENUM];
    public class StringTo[MYENUM]Converter implements ConverterString, [MYENUM] {
    @Override
    public [MYENUM] convert(String source) {
    return [MYENUM].fromValue(source);
    }
    }
  3. Register all converters by creating a class similar to:
    package [MYAPP].web;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.format.FormatterRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
    @Configuration
    public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
    registry.addConverter(new StringTo[MYENUM]Converter());
    // one line per converter...
    }
    }
4.0
Domain Service Projects (TypeScript)Any designed query parameter with type boolean or number will be represented as string. This will lead to validation errors while using them as service input Workaround:
  1. Boolean Case: check if the value can be converted to boolean as following
    const booleans: string = ['true', 'false'];
    if(booleans.includes(request.query.booleanProperty)){
    const convertedBooleanProp = JSON.parse(request.query.booleanProperty);
    }
  2. Number Case: check if the value can be converted to number as following
    if (!Number.isNaN(+request.query.numberProperty) ){
    const convertedNumProp = +data.myNumber;
    }
4.0
Domain Service ProjectsApicurio cannot handle event evolution with compatibility rules enabled. This is due to a bug in apicurio and leads to the situation that the Solution Designer cannot register a new schema or update it. Remediation: do not enable the compatibility rules for apicurio schema registry4.0
Enums of a schema propertyIf you try to create a new version of a schema from the schema registry and want to change a property with enum values via the modeling editor, these enum values are not displayed in the 'Edit Property' view and are therefore deleted when saving. As a workaround in this case, you can use the 'Expert view' when changing the property.4.0