Project overview page
Navigation menu structure
Side Navigation Menu
Workbench provides the following main navigation sections:
Core Views
- Overview - Project overview and documentation
- Diagrams - Visual representations of your architecture
- Spotlight - Focused views on specific aspects
- Relationships - Connections between model elements
- Decisions - Architectural decision records
Model Elements
The Model Elements section provides access to different model elements, which depend on the available profiles.
Header Actions
- Commit and push - Push changes to remote repository
- Branch selector - Switch between branches
- Design Assistant - AI-powered design assistance (beta)
- Create new - Quick creation menu
- Settings - Project and workspace settings
- Help - Documentation and support
- Account - User profile and preferences
Status Bar
- Connected - Connection status indicator
- Problems - Validation issues and warnings
- Git - Git operations and status
Starting page
The project's overview page is the starting point inside a project and provides information about the project and settings.
General information
Here you can find information about the project's "Acronym", "Git Provider", "Repository group", "Git repository path", "Stack", and "Stack version". Besides, it shows information the used "Event Support version" (1.0 or 2.0) for Domain Service Projects and furthermore, 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").
Depending on the implementation language there can be additional fields
Using the "Edit general information" action capability you´ll get the possibility to change "Name", "Tags", "Icon" and "Description" of the project.
Manage baselines
The following operations are only available if there are no uncommitted changes pending.
The baseline management functionality is accessible through an menu in the top right corner of the project overview page. This menu provides key capabilities for managing project baselines.
Change baseline
Updates the baseline in the Git repository if changes have been made. Users can choose from a later version for that baseline.
When there are migrations needed due to an updated baseline, which introduces breaking changes, users should perform the migration in their IDE with the help of a coding assistants. The recommendation is to provide a command, which tells the coding assistant to perform the necessary steps.
Use a common name for the command to upgrade the baseline like k5-upgrade-baseline and incorporate that into every new/updated baseline. this will result in a consistent user experience.
This action is only available, when there are no uncomitted changes.
If no baseline was choosen yet, users have the chance to choose a baseline. As consequence, they will be required to ensure their project data will fit to the new baseline. After choosing a baseline, custom profiles within the project are not supported any more. This only applies to projects created before 26.03
Sync baseline
Available in product edition: ProfessionalThis will update the baseline in the Git repository if changes have been made. It actually will trigger a commit of all the recipes of the referenced baseline to the repository.
This action is only available, when there are no uncomitted changes.
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.
The documentation section is a Markdown editor that allows you to write and edit documentation in Markdown format.
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 covered by Solution Builder.
Project settings
See Project settings
Manage projects
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 write access in Git.
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 manually added when needed. 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 manually added when needed.
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 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 project from GIT repository
In case you have an already existing project in a connected GIT repository, you can now simply import it to the Solution Builder. 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 Builder.
As a pre-requisite for the import the files in the connected GIT repository must comply with the structure of the projects.
If the project acronym already exists in the Solution Builder or the project cannot be found in the repository, an error message is shown.
Project configuration files in projects
In each project, there is a project configuration file (k5-project.yml) created automatically in the root directory. It holds meta data about the project, as well as project specific configurations e.g. which profiles are enabled.
For more information and the dataformat please see Project configuration files
Delete project
To delete a project or a single branch of a project, open it in Solution Builder, 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 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 project that are deployed via a deploy pipeline
Restoring a deleted project is not possible.
When deleting a single branch of a 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.