Managing applications

After creating an application composition project you will be presented with the Overview page of the new project. This page gives an overview on the project, e.g., the creator, the creation date, in which Git repository it is stored, etc. But there is also the Documentation tab which lets you describe all aspects of this application including UML diagrams.

The documentation section

Every project built with IBM Financial Services Workbench provides a documentation section and so do application composition projects. The built-in Markdown editor lets you write extensive documentation in a WYSIWYG or text mode with support for text formatting, links, tables and code-blocks. The text editor supports both CommonMark and GitHub Flavoured Markdown (GFM) specifications.

Besides that, there is a built-in diagram generator that renders UML diagrams using the plantUML language. To draw a diagram you have two options:

WYSIWYG mode:

  1. Place your cursor where you want to insert a diagram

  2. In the menu bar of the text editor click on "CB" (code block) to create a new code block at the cursor position

  3. On the right side of the line with the code block there will appear a button called "Editor" - click on it

  4. This will open a new CodeBlock Editor window

  5. Select plantuml from the Choose language dropdown menu on the top of the window

  6. This will start the diagram renderer, and you can start creating your UML diagram with live preview

  7. When you're done, click on "OK" to save your diagram

Markdown mode:

  1. Place your cursor where you want to insert a diagram

  2. Type three back-ticks followed by "plantuml": ```plantuml

  3. This will start the diagram renderer, and you can start creating your UML diagram with live preview

  4. When you're done, hit "Enter" to create a new line and enter three back-ticks again to close the UML renderer

Tip: Please see the official PlantUML Language Reference Guide for extensive description on how to draw plantUML diagrams.

Deployment targets

These are the targets to where you want to deploy your application. These deployment targets have to be configured in advance to be available for applications. Please refer to creating new deployment targets if you don't have configured them yet.

Each deployment target represents a separate stage, so you can apply your own staging concept. Typically, this includes DEV, TEST, STAGE and PROD, but you are not limited to these. As these deployment targets are separated, each of them has its very own configuration and also the components added to each of these targets can be configured individually. This enables you to adjust every component to the requirements of the environment it is running in.

All deployment targets can be easily accessed on the Components page by clicking on their tab.

Adding deployment targets:

  1. Click on the "Add deployment target" button

  2. Select the deployment target from the dropdown menu

  3. Click on "Add"

Removing deployment targets:

  1. Click on the trash icon next to the "Commit" button (not the big icon in the right upper corner)

  2. Confirm the action in the confirmation dialog

Components

Now that you have added at least one deployment target you can add components to it.

Adding components

First, you have to select one of the deployment targets by clicking on its tab. Then you can add components by clicking on the "+" icon next to the "Commit" button. This opens a dialog showing you the content of the component repository. As described in composing applications you can either add one of the components listed or add a planned component (placeholder for to-be-built components).

Planned components:

Within the "Add Component" dialog click on the "Planned Component" card which will be shown as the first card (if no filters are applied). You will then be prompted to provide the following information:

  • Component Name (required)

  • Tags (optional)

  • Icon (optional)

  • Description (optional)

Click on "Add" to add the planned component.

Tip: If you're working with multiple planned components we recommend providing extensive description, so you have proper information regarding the requirements when creating a service project to implement this component .

Existing components:

If you want to add existing components from the component repository you can use the three-dots menu on each component's card to either

  • add the component directly using its latest version (can be changed later) or

  • view its details and choose the version to use before adding the component

Note: Any component will be added only to the deployment target that is currently selected (active tab). You can add different components on the different namespaces or use the same components but different versions of them.
Attention: It is not possible to add the same component multiple times to an application on the same deployment target.

Removing components

You can easily remove a component by clicking on the three-dots menu button on a component's card and click on "Delete".

Note: Deleting a component from one deployment target will not remove it from any other deployment target.

Compare deployment targets

When working with multiple deployment targets it is most likely that they consist of the same components but may use different versions. In case you composed your initial stage (e.g., DEV) then you would have to do the same setup again for the succeeding deployment target (e.g., TEST) resulting in adding all components again to the second target. To avoid that, there is feature called "compare deployment targets" located left of the "+" icon to add components.

This feature allows you to choose a source target and compare it with another target. The dialog will list all components and their used version of the source target and lets you set a version for the second target. This way, you can duplicate a whole deployment target and edit the version in one go. This will only add the components you selected from the list.

When you're done, click on "Set" to apply the changes to the current deployment target.

Edit versions

There will be times when you want to edit the version of multiple components without having to click on each of the components' cards. You can use the "Edit versions" feature by clicking on the pencil icon next to the "Commit" button. This will open a dialog listing all components added to the currently selected deployment target and their version. Here you can edit the version of multiple components and set them in one action.

Configuring bindings

Bindings are a way to configure the connection of components to other resources, e.g., external REST APIs or messaging. To edit these bindings you can use the cogwheel icon next to the "Commit" button. This lets you choose between the following bindings:

  • API bindings: used to store information required to call external REST APIs (e.g., URL, certificates, token, etc.)

  • Topic bindings: used to store information on the event topic used for messaging

Attention: The configuration of these bindings will only apply for the currently selected deployment target. The bindings need to be configured for each component on each deployment target.

Deploying applications

After having added all necessary components and configured them according to the requirements of the different deployment targets you need to commit your changes to the Git repository to actually apply these changes.

Clicking on the "Commit" button will persist your changes in the linked Git repository and trigger the GitOps mechanism which will look for deviations between the live state and the desired target state and then sync them. This results in re-deploying one or more components according to your changes.

Attention: The "Commit" button only applies changes for the currently selected deployment target. To persist your changes on other deployment targets select the corresponding target tab and click on "Commit" again.