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
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
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:
- Domain Service based on NodeJS TypeScript
- Domain Service based on Java Spring Boot
- Generic Service based on NodeJS TypeScript
- Generic Service based on NodeJS JavaScript
- Generic Service based on Java Spring Boot
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)
- Repository Key Path: The full path of the Git repository for the project (optional)
- 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)
- 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)
Based on the type of the project the master data contain additional input fields to manage the project extensions.
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
The user who created a project has the possibility to read it while the project is in state Processing or Error.
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:
- Select Catalog
- Select Asset
- View Details
- 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.
Asset details
- Acronym
- Version
- Contributor
- Export date
- Description
- Tags
Stack and extensions
- Stack
- Stack version
- List of enabled extensions enabled
The information for the asset are displayed for each version.
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 Repository Key Path: The full path of the Git repository for the project (optional)
- 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; the name consists of the specified path combined with the acronym of the project
- 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.
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.
Import Service Project from GIT repository
In case you have an already existing Service Project in a connected GIT repository, you can now simply import it to the Solution Designer. Either in a Workspace you click on Add project and then select Create project from repository or in the Project Overview you select in the DropDown Creat project from repository.
In the action you have to provide the following data:
- Project Acronym: used for the project in the GIT repository
- Git Provider: select the Git provider where the project is stored
- Repository Group: select the repository group where the project is located
After clicking Create the project will be created in the Solution Designer.
As a pre-requisite for the import the files in the connected GIT repository must comply with the structure of the projects.
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.
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
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)
Restoring a deleted project is not possible.
Project configuration files in service projects
In each service project, there is a project configuration file created automatically in the root directory. It holds meta data about the project, as well as project specific configurations e.g. which extensions are enabled.
For projects, created with version 4.1.0 or earlier, the project configuration is stored in the file solution.yml.
After version 4.1.0, projects that are based on a Java Spring Boot Stack, also allow the file k5-project.yml to hold advanced project configuration. It unlocks additional capabilities, e.g. the disabling of extensions in the project. Nevertheless, projects having a solution.yml file are still valid. If both solution.yml and k5-project.yml files are provided, the precedence will be given to k5-project.yml.
Please consider, that a commit via the Solution Designer will automatically migrate your solution.yml into a k5-project.yml.
solution.yml
The solution.yml contains the following properties:
| Property | Type | Title/Description |
|---|---|---|
| appAcronym * | string | Unique acronym of the project |
| appName * | string | Full name of the project |
| appDescription | string | Brief 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" | ||
| appIcon | string | Icon of the project, used for displaying purposes |
| language * | Enum (of string) | Implementation language of the project |
| Supported values: | ||
| - "TYPESCRIPT" | ||
| - "JAVA" | ||
| - "JAVASCRIPT" | ||
| category | Enum (of string) | Service category of project - DEPRECATED SINCE 4.1.0 |
| Supported values: | ||
| - "EXPERIENCE_API" | ||
| - "DOMAINSERVICE" | ||
| - "SYSTEMS_API" | ||
| domainTags | Array of string | Project tags, used to organize multiple projects together |
| Can be an empty array | ||
| basePackage | string | Defines package structure for generated solution |
| Only has to be filled if language is "JAVA" | ||
| extensions | Object of type Project Extensions | |
| creationTs * | String | Creation timestamp in milliseconds |
| creator * | String | Creator of the item |
| creatorId * | String | ID 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
| Property | Type | Title/Description |
|---|---|---|
| databaseType | Enum (of string) | Supported persistance mechanism |
| Supported values: | ||
| - "Mongo" | ||
| - "RDBMS" | ||
| - "None" | ||
| supportedEventVersion | Enum (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" | ||
| saga | Boolean | Flag, defining whether Saga support is enabled in the current project |
| If yes, additional features will be available when designing and implementing | ||
| java | Enum (of integer) | Java Version used in the project. Generic projects prior to 4.1 do not have that property |
| Supported values: | ||
| - 17 |
k5-project.yml
The k5-project.yml contains the following properties:
| Property | Type | Title/Description |
|---|---|---|
| schemaVersion * | Enum (of string) | Item version, describing what kind of item it is |
| Must be /v1/projectConfiguration.schema.json | ||
| acronym * | string | Unique acronym of the project |
| displayName * | string | Full name of the project |
| description | string | Brief explanation about the purpose of this project |
| icon | string | Icon of the project, used for displaying purposes |
| tags | Array of string | Project tags, used to organize multiple projects together |
| Can be an empty array | ||
| creationTs * | String | Creation timestamp in milliseconds |
| creator * | String | Creator of the item |
| creatorId | String | ID of the creator of the item |
| stackReference * | Object of type Stack Reference | Reference to the used stack, which is identified by a combination of name and version |
| extensions * | Object of type Java Spring Boot Stack 2.0.0 Extensions | Extensions object, defining which extensions are enabled and which configuration options are set (if necessary). If an extension is not defined, it is treated as disabled. |
| additionalConfig * | Object of type Java Spring Boot Stack 2.0.0 Configuration | Additional project configuration for projects based on k5-JavaSpringBoot 2.0.0 |
* Mandatory field
Example file:
schemaVersion: /v1/projectConfiguration.schema.json acronym: ORDERS displayName: Orders project icon: home tags: - "order" - "business" stackReference: name: k5-JavaSpringBoot version: 2.0.0 extensions: apiModelling: enabled: true domainModelling: enabled: true integrationModelling: enabled: false aggregatePersistenceSupport: enabled: true databaseType: Mongo businessEventSupport: enabled: true version: '2.0' sagaPatternSupport: enabled: false swaggerUISupport: enabled: false unitTestingSupport: enabled: true additionalConfig: basePackage: myPackage creationTs: '1687780358190' creator: John Doe creatorId: 12345678-1234-1234-1234-123456789012
Stack Reference
Reference to the used stack, which is identified by a combination of name and version. Currently, only Java Spring Boot Stack 2.0.0 is supported.
| Property | Type | Title/Description |
|---|---|---|
| name * | Enum (of string) | Name of stack, which is used as base for the project |
| Supported values: | ||
| - "k5-JavaSpringBoot" | ||
| version * | Enum (of string) | Version of stack, which is used as base for the project. Applies semantic versioning |
| Supported values: | ||
| - "2.0.0" |
Java Spring Boot Stack 2.0.0 Extensions
Extensions object, defining which extensions are enabled and which configuration options are set (if necessary). If an extension is not defined, it is treated as disabled.
| Property | Type | Title/Description |
|---|---|---|
| apiModelling | Object of type Extension | Model and implement a secure Rest API and publish it as Open API specification |
| domainModelling | Object of type Extension | Model and implement your business logic based on DDD principles |
| integrationModelling | Object of type Extension | Model and implement integrations to other services |
| aggregatePersistenceSupport | Object of type Aggregate Persistence Extension | Easily persist your business data in a database (RDBMS / MongoDB) |
| businessEventSupport | Object of type Business Events Extention | Model and implement Business Events and Agents |
| sagaPatternSupport | Object of type Extension | Model and implement your services using the Saga Pattern for distributed transactions |
| unitTestingSupport | Object of type Extension | Autogenerate unit testing stubs for your implementation |
| swaggerUISupport | Object of type Extension | Visualize and easily access your Rest API |
Extension
| Property | Type | Title/Description |
|---|---|---|
| enabled * | Boolean | Defines, whether the extension is enabled or not |
Aggregate Persistence Extension
Aggregate Persistence Support Extension info with special configuration options.
| Property | Type | Title/Description |
|---|---|---|
| enabled * | Boolean | Defines, whether the extension is enabled or not |
| databaseType * | Enum (of string) | Supported database type |
| Supported values: | ||
| - "Mongo" | ||
| - "DB2" | ||
| namingStrategies | Enum (of string) | Defines whether it uses the default 3rd party libraries naming strategies, or custom legacy naming strategies (defaults to 'legacy' if not set). |
| Supported values: | ||
| - "legacy" | ||
| - "default" |
Business Events Extension
Business Event Support Extension info with special configuration options.
| Property | Type | Title/Description |
|---|---|---|
| enabled * | Boolean | Defines, whether the extension is enabled or not |
| version * | Enum (of string) | Defines, whether only new events or also old events (prior to 4.0.5) are supported. |
| Supported values: | ||
| - "1.0" | ||
| - "2.0" |
Java Spring Boot Stack 2.0.0 Configuration
Additional project configuration for projects based on k5-JavaSpringBoot 2.0.0.
| Property | Type | Title/Description |
|---|---|---|
| basePackage | String | Defines package structure for generated code |