The design process

Introduction

When talking about the design process, it's mostly about modelling a low-code project. This project type supports designing all elements of a microservice based on Domain Driven Design. Solution Designer lets you model all parts in a structured and organized way, offers rich documentation possibilities for most of these elements with auto-generated UML diagrams to visualize the design model.

Usually, you would have had an Event Storming or similar purpose session to define how to solve a certain business problem for your users/customers. The outcome would be, that you need to create several microservices to solve that problem resulting in several projects built with IBM Financial Services Workbench. You can decide, whether to create a low-code project with full support for code generation based on e.g., Domain Driven Design or to create a pro-code project where you have full control over the implementation and only benefit from the deployment and security functionality.

Assuming you decided to create a low-code project, this article is intended to explain the whole process of modelling the microservice. Although there is full support for code generation and the generated source code can be run immediately, you will still have to write the business logic code to get the microservice solving the business problem. Implementing a project will be explained in the chapter implement low-code projects.

Project overview

Let's start with having a look on the project's structure and the UI elements used to represent the different components of a project.

After creating a new low-code project you will be directed to the project's Overview page ( see setting up projects). On the left there is the main navigation bar offering the following categories:

Overview page

The project's overview page is the starting point inside a project and provides the following information:

General information

Here you can find information about the project's "Acronym", "Name", "Category", "Type" (low-code or pro-code) and also the "Implementation Language". Besides, it shows information regarding the "Repository Group" and the "Git Provider" used to store the project's source code. Furthermore, there is additional information on "Tags" and the "Icon" , the project's "Description" and the name of the creator ("Created By") and the creation date ("Created On").

Note: Depending on the implementation language there can be additional fields, e.g. the "Package Name" required for low-code projects implemented with Java Spring Boot.

Documentation

The documentation section on a project's overview page is intended to provide an overall documentation of the project and all of its components. It is pre-filled with a basic table of contents and a UML diagram showing the coarse structure of the project. See General capabilities of Solution Designer for further details on the Markdown editor and the diagram generator.

Note: After creating a new project there will only be the headlines and some hints in the documentation section and the diagram will be empty as long as there are no elements modelled. The diagram will refresh automatically whenever you make changes to the design model.
Tip: Using the Documentation section is a perfect way to communicate ideas and concepts as well as to describe complex procedures or conditions. The built-in Markdown editor also offers support for creating native plantUML diagrams in case you want to visualize procedures that can't get auto-generated by Solution Designer.

namespaces overview

This section gives an overview of all existing namespaces in a project and lets you easily create new namespaces. It is separated into the following categories:

  • API namespaces

  • domain namespaces

  • Integration namespaces

Each category lists the existing namespaces in this category by adding a card for each namespace. By clicking on the header of this cards you will be directed to the namespace's instance page. Alternatively, you can use three-dots menu on each card to Edit or Delete a namespace. Each card also provides links to quickly access all its components.

Introduction to namespaces

A low-code project in IBM Financial Services Workbench is always separated into three layers:

  • APIs: This layer is used to provide one or more API(s) based on the OpenAPI standard that will get consumed by other projects or external systems

  • Domains: This layer holds the business logic of the microservice

  • Integrations: This layer is responsible for consuming REST APIs provided by other projects or external systems

Separating the project into these layers aims to protect the business logic through putting an anti-corruption layer around. It abstracts away the business logic from the API specification, so you can update or evolve the inner logic without changing the outer implementation. Same applies for the integration layer, where you could update or evolve how to process the queried data while still having the same implementation to communicate with the external service.

Tip: Depending on the purpose and intention of the project you are planning, you may not need to create all types of namespaces. In case you only want to provide an API that processes the user's input (request) and returns the result (response), you would not need to create an integration namespace.

API namespaces

As already mentioned, API namespaces in Solution Designer are used to build REST APIs that can be consumed by other projects or external systems. Each modelled API namespace results in a separate REST API based on the OpenAPI standard with its own API specification. That means, you can design the microservice to have as many separate APIs as needed or just model one single API depending on the requirements.

There are two different approaches when modelling an API namespace:

  • create the API from scratch

  • create the model of the API namespace based on an existing API specification

While the first approach fits best when you are not yet fully decided on how the API will look like exactly in the end, the second approach is intended for API First strategies. Solution Designer offers you to upload an API specification either in OpenAPI 3.0 (.yaml) or Swagger 2.0 (.json) format and auto-generates the whole API namespace with a single click. This includes all Paths, Operations, Parameters, Schemas and Responses that form the specified API.

See API namespaces for further details on creating and working with API namespaces.

domain namespaces

domain namespaces are used to put all the business logic away from communication logic. That ensures, that you don't have to touch the implementation code of the API operations if you intend to change the way how you process the input data. Any data exchange between an API namespace and a Domain namespace will be handled by mapping properties between them. Same applies when exchanging data with an integration namespace. You always have the business logic kept separate from communicating with external systems.

As the design model of low-code project is based on Domain Driven Design principles, domain namespaces are the place to model the following elements:

  • Root entities/aggregate roots

  • Entities

  • Services

  • Commands

  • Events

See domain namespaces for further details on creating and working with domain namespaces.

Note: Depending on your project's requirements you can create and model as many domain namespaces as needed.

Integration namespaces

The last of the three layers is the integration namespace which is used to model services, entities and their properties necessary to consume external REST APIs. Solution Designer offers to create API dependencies that support the user to integrate an external API. You have the chance to upload an existing API specification either in OpenAPI 3.0 (.yaml) or Swagger 2.0 (.json) format and Solution Designer will then create all necessary methods for implementing each of the HTTP operations stated in the API specification. This way, you don't have to prepare each API call on your own and instead can focus on implementing the business logic.

Furthermore, there is the concept of API bindings which can be specified for each API dependency. They allow specifying additional information regarding the consumption of an API, e.g. authorization token, URLs, API keys, or just any additional value needed to communicate with the external API.

Tip: You can specify values in API bindings and overwrite them for different deployment targets. This allows you to adjust certain values depending on the target environment without having to change your implementation code.

See integration namespaces for further details on creating and working with integration namespaces.

Note: Depending on your project's requirements you can create and model as many integration namespaces as needed.