Creating components

Introduction

IBM Financial Services Workbench offers you to use three different types of components when composing applications: the built-in framework components, external 3rd party components and customer-built components. This article is about creating new customer-built components. If you want to know how to add external components to an application composition project, please see working with 3rd party components.

Basically, there are two starting points when creating new components. The first is when you compose an application and figure out that the component repository doesn't offer the business capability you were searching for. In this case you would add a planned component to the application and use the three-dots menu on it to create a service project ( click on "Create project"). The planned component's card will now show a link to the new project, so you can access it directly from here.

The second starting point is when you plan to create a new business capability in order to add it to your repository. In this case you would start on the Projects overview page in Solution Designer and use the "Create" button to create a new service project. Please see setting up service projects on how to create new projects.

Depending on the development type you choose you can find additional information on low-code development or pro-code development. After having implemented the service project according to your requirements and tested everything, the next step is to release the project to the component repository to make it available as a component for applications.

Releasing service projects

IBM Financial Services Workbench offers two pipeline definitions for service projects, one is the release pipeline and the other is the deploy pipeline. While the deploy pipeline is used to deploy a single microservice to a deploy target mainly to do testing in a real environment, the release pipeline publishes a service project to the component repository ( see build & deploy).

General idea of releasing

In order to use and deploy a service project the helm charts and related docker image(s) has to be released and published.

Releasing also includes dedicated versioning and a release management. So it is ensured, that the correct package of changes are delivered in one released version. IBM Financial Services Workbench supports SemVer 2.0 to do so.

And the second part is to publish the versioned release and use the release version for all the artifacts: helm chart and docker image.

Usage in application composite projects

Only released artifacts can be used in the application composite projects. There support not only releases but also pre-releases, hence also work in progress releases can be deployed tested and previewed.

Usage of pre-releases

It is recommended to use several different stages like development, testing and production for example. And only development might use the unstable pre-release version, and the other stages only use stable releases.

In the application composite project is ArgCD used for the deployment of that project. ArgoCD does take per default only releases in account and ignores pre-releases, if expression used like these

  • 1.*

  • >=2.0.0

If pre-releases have to be taken into account expressions like these has to be used:

  • 1.0.1-alpha

  • >=2.3.2-0

  • >=3.0.0-0,<3.0.1-0

Versioning service projects

General idea of versioning

The general idea is to create released artifacts based on the version information on project itself, e.g., the package.json in case of TypeScript or JavaScript service projects or pom.xml in case of Java service project.

So the native way is used to managing the version of that project, hence the native toolchain to maintain and read the version can be used.

Features

The approach support

  • using the own development and release workflow in manner of versioning

  • creation pre-release versions using the SemVer v2 postfix -

  • re-releasing of same version is prevented by default, but can be disabled

  • developer friendly releasing of pre-releases as per default in this case an increasing number is added to the pre-release version

Limitations

The known limitations are

Usage of version

The feature is limited by SemVer 2.0, which is supported and required by Helm/General Conventions/Version Numbers.

The general idea is to distinguish between

  • pre-releases e.g., 0.0.1-alpha: used for development and intermediate deployments on the related stage(s) for example DEV

  • releases e.g., 0.0.1: used for tested and approved released versions, and deployments on the releated stage(s) for example TEST or PROD

If a version is released. It is not recommended to re-release that version. Hence, if for example 2.0.0 was released once, but a bug was found, the next bugfix version has to be created e.g., 2.0.1, otherwise it is not guaranteed, that the correct states are deploy on all systems.

Precedence of versions

The precedence defined by SemVer:

  1. Precedence refers to how versions are compared to each other when ordered.

    1. Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence).

    2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically.

      Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1

    3. When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version:

      Example: 1.0.0-alpha < 1.0.0.

    4. Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows:

      1. Identifiers consisting of only digits are compared numerically.

      2. Identifiers with letters or hyphens are compared lexically in ASCII sort order.

      3. Numeric identifiers always have lower precedence than non-numeric identifiers.

      4. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.

      Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

Life-cycle

Preparation:

  1. The project is created and will start automatically with 0.1.0

  2. The "build and release" pipeline has to be created

Daily work:

  1. The planned changes on the project will be applied

    • Adjusting model

    • Adjusting code

    • Adjusting the (pre-)release version (e.g., 0.2.0-alpha)

  2. Either manually or automatically the build & release pipeline will be triggered

  3. Optional: Continue with step 1.

  4. Promotes release by removing the pre-release information e.g., 0.2.0

  5. Either manually (optional) or automatically trigger the build & release pipeline

  6. Define next version and adds pre-release information e.g., 0.3.0-alpha

  7. Continue with step 2.