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 category

Starting with the project category, Solution Designer offers the following categories of projects:

  • Experience API: Experience APIs refer to a project that will be connected to an external channel. For example a mobile or a web-based application.

  • Domain Service: Domain services encapsulate the core business logic of a business domain.

  • System API: Refers to projects that will be integrated to other projects in order to enhance the functionality of the latter.

All options work basically as a flag expressing the overall purpose of the application.

The idea is that, while all of these could easily be incorporated in one big monolith, this would be considered a bad design as any small change would affect the entire project. In other words, by putting each project in the corresponding layer, it allows for a modular design where a small change will affect only the altered project.

Project type

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

  • Low-Code Projects: Modelling based on Domain Driven Design principles with rich code support for all modelled elements

  • Pro-Code Projects: Full control over model and implementation with basic code support for build and deploy

Implementation language

The third information necessary to create a new project is the implementation language of the project. Since both project types generate supporting code, you need to specify the implementation language for the project. Currently, the following languages are supported:

  • TypeScript: Available for both Low-Code and Pro-Code Projects

  • Java: Available for both Low-Code and Pro-Code Projects (you need to provide a package name for the project)

  • JavaScript: Available only for Pro-Code Projects

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)

  • Domains: Tags to group the projects on the Overview page (optional)

  • Icon: Name of the icon used on the Overview page (required)

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

Confirming the entries completes the creation of a new 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 categories: Select the project category to filter the asset result

  • All types: Select the project type to filter the asset result

  • 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

  • Acronym

  • Version

  • Contributor

  • Description

  • Tags

Note: For assets created from a low-code-project 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

  • Category: displays the selected asset category (not editable)

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

  • Type: displays the selected asset type (not editable)

  • Implementation Language: displays the selected asset implementation language (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)

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

  • Contributed By: Name or organization (required)

  • Description: Description of the asset (optional)

  • 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)

  • 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 projects

To delete a project, open it in Solution Designer, navigate to the Overview page and select the Delete 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 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

  • Git repository with its data

  • All deployments of that projects

  • Cached data related to that project

Warning: Restoring a deleted project is not possible.

Application Composition Projects

This project type is used to compose applications by adding multiple components from a repository.

Create new projects

You can create new application projects by clicking on the "Create" button on the Projects overview page and providing the following information:

  • In the "Create Project" dialog choose Application Composition Project

  • Specify a unique acronym for this project

  • Give the application a name

  • Select the Git provider that should be used to store the project's source code

  • Choose a repository group at this Git provider

  • Choose one or more tags (optional)

  • Choose an icon (optional)

  • Enter a description of your application (optional)

  • Click on create

Now that you have a new application composition project you need to add at least one deployment target before you can start adding components.

  • Click on "Add deployment target"

  • Select a namespace from the drop-down (you will see all configured deployment targets)

After having added deployment targets you can start adding components by clicking on the "+" button.

Read more about managing application composition projects.

Delete projects

To delete an application composition project you just have to click on the trash icon in the right upper corner inside an application project. You will be prompted with a confirmation screen where you have to type the acronym of the application to delete it.

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