Creating projects

Whenever you want to implement a solution with Solution Designer, you need to create a project first. Solution Designer currently supports the following project types:

Service Projects

This project type is used to create a single microservice that you decided to implement on your own. The creation of a project requires some information on the project's category, type and implementation language. You have two options to create a project:

  • Create a new project from scratch

  • Create a project based on an existing asset

Note: When creating a project from scratch, you will have to provide all the information stated below. When creating a project based on an asset, some information will be set by the Asset such as the category, type and implementation language.

Create new projects

Attention: Within Solution Designer, there is no possibility to grant permissions to a project. To make a team workable with the project you must manage the permissions in the Git repository.

Project type

Solution Designer offers different project types that support different approaches of development:

  • Service Projects: Represents a single microservice modelled and implemented by the user which can be used as component for an application composition project. Every service project is based on a Stack, which defines the base technology and available capabilities in the project.

  • Application Composition Projects: This project type is used to compose applications based on already existing, reusable components.

Service Projects are distingushed to Domain Services and Generic Services.

Domain Services support designing all elements of the component in a Design2code way. The Solution Designer lets you model all parts in a structured and organized way, offers rich documentation possibilities for most of these elements with e.g., auto-generated UML diagrams to visualize the design model. 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 component solving the business problem.

Generic Services give ou full flexibility and control in regard of how you design and implement the project. You can easily re-use organization best practices, cross-cutting functionality as well as use-case-specific code-frameworks while you are free in design and implementation the features like the integrated developer documentation or pre-defined build and deploy pipelines are available for this type of projects as well.

A Stack is used as a base for any service project and defines the used technology, implementation language and the available capabilities during the service development. The following service projects are currently available:

Service project master data

Finally, you can define the Master Data of the new project as follows:

  • Acronym: The project's acronym must be unique and must not contain more than 20 characters in capital letters and numbers without special characters (required)

  • Name: The name of the project (required)

  • Git Provider: A list of all Git providers for which you have an access token (required)

  • Repository Group: All repository groups in the specified Git provider for which you have at least read rights (required)

  • Package Name: Only available for Domain Services based on Java Spring Boot (required)

  • Persistence Support: Only available for Domain Services based on Java Spring Boot; MongoDB or RDBMS are supported (required)

  • Event Support Version: Only available for Domain Services; Version 1.0 or 2.0 available (required)

  • Saga Pattern Support: Only available for Domain Services based on Java Spring Boot (optional)

  • Tags: To tag the projects (optional)

  • Icon: Name of the icon used on the project card (required)

  • Description: Description of the project. Shown on the project card (optional)

Note: Based on the type of the project the master data contain additional input fields to manage the project extensions.
Note: The Project Category used in earlier versions of IBM Industry Solutions Workbench is no longer available.

Confirming the entries completes the creation of a new service project.

Project states

The state of the creation process is shown in the Projects overview. It shows Processing while the project is being created. In this state you can open the project, but you cannot proceed any action. In case of an error, it is also shown on the project in the overview. In this case you can open the project in order to delete it.

If a project was created successfully it is stated as New for the first 24 hours after creation. If its state is Error after creation, it means that the creation or initialization of the project on the remote Git repository failed. In this case it cannot be guaranteed, that the project is now ready to work.

Possible reasons for this are:

  • The remote Git repository is not available at the moment

  • Invalid Git username and Git token combination defined

  • The defined Git token does not provide enough permissions to create a new repository

Recommendation:

  • Ensure that the above-mentioned points are set up correctly

  • Delete the project in Solution Designer

  • Ensure that the remote Git repository was deleted as well (if necessary, delete it by hand)

  • Try to re-create the project using Solution Designer. If it still fails, please contact your administrator

Note: The user who created a project has the possibility to read it while the project is in state Processing or Error.
Tip: In order to hide your project, make sure to set your project to private in the Git repository.

Creating projects from an asset

In case you want to build a project based on an existing asset you will be guided by a wizard.

The wizard has four steps:

  1. Select Catalog

  2. Select Asset

  3. View Details

  4. Import Project

Select catalog

This step is for selecting the assets grouping container that contains all the available assets. User can search on the catalog using a search textbox that searches through asset catalog's name and description. A Git provider field can be used to filter the displayed list of asset catalog. Click on any asset catalog card in the displayed list to select an asset catalog.

Select asset

It enables the user to select the required asset from the preselected asset catalog. User can search on the catalog using a search textbox that searches through asset catalog's name and description. It has four filters:

  • All tags: Filters the assets based on the tags assigned to the asset

  • All languages: Select the project language to filter the asset result

Click on any asset card in the displayed list to select an asset catalog.

View details

It displays the details for the selected project asset in the latest available version. You can access earlier versions by simply change it in the drop down.

  • Acronym

  • Version

  • Contributor

  • Export date

  • Description

  • Tags

The information for the asset are displayed for each version.

Note: For assets created from a Domain Service also API Operations, Domain Services and Integration Services are displayed.

  • Click on the Next button to go to the next step.

Import project

This step has a pre-filled form to create a new project based on the selected asset. It has the following fields:

  • Selected Asset: displays the selected asset name

  • Acronym: allows users to create a new acronym for the newly added project

  • Name: allows users to set a new name for the newly added project

  • Git Provider Repository Group: allows users to select a Git provider and repository group for the new added project

  • Stack: displays the stack of the asset (not editable)

  • Stack Version: displays the version of the stack used in the asset (not editable)

  • Package name: allows to specify the package name for Domain Services based on Java Spring Boot

  • Event Support Version: displays for Domain Services the used version in the asset (not editable)

  • Persistence Support: displays Domain Services the used persistence in the asset (not editable)

  • Saga Pattern Support: displays usage for Domain Services based on Java Spring Boot (not editable)

  • Tags: allows users to edit/add/remove a tag for the newly added project

  • Icon: allows users to select a new icon for the newly added project

  • Description: displays the selected asset description, and it allows the user to edit it

Click on the Create button to create the project. The wizard will navigate you to the newly created project's instance page.

Share project

To share a project with other users or teams, open the project and navigate to the Overview page and then select the Share project capability at the top right of the page. Then you are asked to enter the following information for sharing the project as an asset:

  • Asset Name: The display name of the asset (required)

  • Asset Catalog: The catalog name in which you want to share this asset (required)

  • Version: The version of this asset (e.g. 1.0.0). Each version will be represented as its own asset in the selected catalog (required)

  • Tags: Tags that allow other users to search for (optional)

  • Contributed By: Name or organization (required)

  • Description: Description of the asset (optional)

  • Replace existing version: If enabled, it will replace the existing version of this asset. By default, it is disabled (optional)

Confirming the entries will create an asset in the selected asset catalog, which can be reused by other users having access to this asset catalog.

Note: The Share project button will only be enabled for user's having either of the below mentioned accesses:

  • admin access in Git and dc_developer in Solution Designer.

  • write access in Git and dc_developer in Solution Designer.

  • write access in Git and dc_analyst in Solution Designer.

Export an Asset as a zip file

This feature allows user to download an asset as a zip file and then share this asset to a different cluster without having a direct connection between two systems/cluster. To Download an asset as a zip file, user need to use the api interface for k5-asset-manager. By default the external route for service is disabled and can be enabled by updating the configuration in Extended configuration. Once the route is enabled use the api "/export" with GET method and following parameters:

  • catalogAlias: Alias of the asset catalog where asset is available

  • acronym: Acronym for the asset that need to be exported

  • version: asset version to be exported

Curl for api call:

curl -X 'GET' \
  '{{K5_ASSET_MANAGER_BASE_URL}}/api/v1/{{catalogAlias}}/assets/{{acronym}}/{{version}}/export' \
  -H 'accept: application/json; charset=utf-8' \
  -H 'Authorization: Bearer {{Bearer_Token}}'

Once this api request is successful, the asset will be available to download as a zip file.

Import Asset from Zip

This feature allows user to use the zip file of an asset exported with Export Asset and import it as a new asset in a different designer/cluster. To import an asset from a zip file, user need to use the api interface for k5-asset-manager. By default the external route for service is disabled and can be enabled by updating the configuration in Extended configuration.

Use the api "/importAsset" with GET method and following parameters:

  • file: zip file from previous step

  • catalogAlias: Alias of the asset catalog in new designer where asset has to be shared

  • gitProviderAlias: git provider alias in the new designer where user want to store the asset

  • groupKey: groupKey in the new designer where user want to store the asset

  • repositoryKey: repositoryKey in the new designer where user want to store the asset, this can be same as acronym of original asset only if it's already not used by a different service project in the designer where we want to import the asset. Multiple versions of same asset can use the same acronym.

Curl for api call:

curl -X 'POST' \
  '{{K5_ASSET_MANAGER_BASE_URL}}/api/v1/{{catalogAlias}}/assets/importAsset' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{Bearer_Token}}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file={{ASSET_ZIP}};type=application/zip' \
  -F 'gitProviderAlias={{GIT_PROVIDER_ALIAS}}' \
  -F 'groupKey={{GROUP_KEY}}' \
  -F 'repositoryKey={{REPOSITORY_KEY}}'

Once this API operation is successful, the asset should be available to use in the catalog {{catalogAlias}} with the acronym specified in the request.

Delete service projects

To delete a service project or a single branch of a service project, open it in Solution Designer, navigate to the Overview page and select the Delete project or the Delete current branch capability. Then you are asked to confirm the deletion.

Note: Delete is only shown if the user has the needed privileges granted in the Git repository.

When deleting a service project, multiple steps are done in order to clean up the project properly. The following list shows the data that is cleaned up while deleting:

  • Artifacts of the project in the database

  • Cached data related to that project

  • Git repository with its data

  • All deployments of the service project that are deployed via a deploy pipeline

Attention: Restoring a deleted project is not possible.

When deleting a single branch of a service project, you have the option to check wether the branch should be deleted only locally, or if also the related remote branch in the repository should be deleted.

The following list shows the data that is cleaned up while deleting:

  • Artifacts of the project in the database

  • Cached data related to that project

  • Git repository with its data (optional)

Attention: Restoring a deleted project is not possible.

solution.yml in service projects

In each service project, there is a /solution.yml created automatically in the root directory. It holds meta information around the

PropertyTypeTitle/Description
appAcronym *stringUnique acronym of the project
appName *stringFull name of the project
appDescriptionstringBrief explanation about the purpose of this project
appType *Enum (of string)Type of project, used to resolve available capabilities within the project
Supported values:
- "DDD"
- "CUSTOM"
appIconstringIcon of the project, used for displaying purposes
language *Enum (of string)Implementation language of the project
Supported values:
- "TYPESCRIPT"
- "JAVA"
categoryEnum (of string)Service category of project - DEPRECATED SINCE 4.1.0
Supported values:
- "EXPERIENCE_API"
- "DOMAINSERVICE"
- "SYSTEMS_API"
domainTagsArray of stringProject tags, used to organize multiple projects together
Can be an empty array
basePackagestringDefines package structure for generated solution
Only has to be filled if language is "JAVA"
extensionsObject of type Project Extensions
creationTs *StringCreation timestamp in milliseconds
creator *StringCreator of the item
creatorIdStringID of the creator of the item

* Mandatory field

Example file:

appAcronym: "ORDERS"
appName: "Service providing the possibility to order stuff"
appDescription: ""
appType: "DDD"
appIcon: "home"
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
domainTags:
  - "order"
  - "business"
language: "TYPESCRIPT"
basePackage: ""
extensions:
  databaseType: "Mongo"
  supportedEventVersion: "2.0"
  saga: "true||false"
  java: 17

Project Extensions

PropertyTypeTitle/Description
databaseTypeEnum (of string)Supported persistance mechanism
Supported values:
- "Mongo"
- "RDBMS"
- "None"
supportedEventVersionEnum (of string)Flag defining whether only new events or also old events (prior to 4.0.5) are supported. If it's not set, the default behavior should fall back to "1.0" which means both old and new events are supported
Supported values:
- "1.0"
- "2.0"
sagaBooleanFlag, defining whether Saga support is enabled in the current project
If yes, additional features will be available when designing and implementing
javaEnum (of integer)Java Version used in the project. Generic projects prior to 4.1 do not have that property
Supported values:
- 17

Course Project Types