Custom model elements
The graphical service design tool provides extensive customization capabilities, allowing you to tailor the available model elements and their properties to align with your organization's specific architectural patterns, design methodologies, and software engineering practices.
By utilizing this customization capability, you can define custom model elements that encapsulate domain-specific concepts, extend existing elements with additional properties, and configure the modelling environment to reflect your team's preferred design workflows and conventions.
This customization capability is currently available as a technology preview. The feature may undergo significant changes or be discontinued in future releases without prior notice.
Configuration
Custom modelling configurations should be implemented with caution. Incorrect or malformed configuration files may compromise the integrity of your design environment and adversely impact the modelling tool's functionality.
Customization is achieved through a dedicated modelling configuration file located at .k5/modelling-config.yaml within your project's git repository. This configuration file serves as the central point for defining custom model elements, their properties, validation rules, and behavioral characteristics.
For comprehensive examples of configuration syntax, including both default configurations and advanced customization scenarios, refer to the Custom modelling config reference documentation.
Custom form fields
On the Overview page, you can also define and manage your own fields for model elements, diagrams and decisions within your System Architecture Design project. This provides flexibility to tailor data entry to your specific needs, ensuring that all relevant information can be captured efficiently.
You can find the option to Configure custom fields in the overflow menu in the top right corner of the starting page.
Custom fields are defined and saved within a .yaml file for the entire project. Within this file, you can define the following:
- Field name: An identifier for the field
- Display name: The display label of the field in the form
- Type:
textField(small text field),textArea(large text field),multiSelect(dropdown),singleSelect(dropdown),checkbox,rating,number,date - Description: Text that will be displayed below the field (optional)
- Help URL: URL that will be accessible via an info icon next to the label (optional)
- Availability: The form where this field will be displayed. Custom fields can be created for Decisions (
architecturalDecision), Diagrams (diagram), Actors (actor), Systems (system), Containers (container), Components (component), and Relationships (relationship). - Selection options for multiSelect and singleSelect fields: Name (label), icon and color code for the dropdown entries (optional)
Example for the .yaml file:
- fieldName: author
type: textField
availability:
- architecturalDecision
displayName: Author
description: The author of this description
helpUrl: https://help.url
- fieldName: reach
type: singleSelect
availability:
- architecturalDecision
displayName: Reach
description: The reach of this decision
options:
- name: System
- name: Project
- name: Company
- fieldName: technicalFit
type: rating
availability:
- system
- container
displayName: Technical Fit
description: >-
The rating whether this item is fit for the future from a technical
perspective
- fieldName: businessFit
type: rating
availability:
- system
- container
displayName: Business Fit
description: >-
The rating whether this item is fit for the future from a business
perspective
- fieldName: modernization
type: multiSelect
availability:
- system
- container
displayName: Modernization Phase
description: In which phases is this item tackled
options:
- name: Horizon 1
- name: Horizon 2
- name: Horizon 3`
- fieldName: estimatedCost
type: number
availability:
- system
- container
displayName: Estimated Cost
description: >-
The number estimating the overall cost for the project
- fieldName: nextEvaluationDate
type: date
availability:
- system
- container
displayName: Next Evaluation Date
description: >-
The date to determine when is the next phase of evaluation
Defined fields will be displayed in the order that is given within the .yaml file, directly after non-custom fields of the form that has been specified (decisions, diagrams, or a model element type), as well as in creation dialogs of said elements. In tables, the fields are available as optional columns that can be displayed by adjusting the table settings in the table tool bar.
Custom fields are always optional fields by definition.
Changes to the form fields defined in the .yaml file after their initial setup may lead to inconsistencies, data loss, or unexpected behaviour in existing views. To ensure stability, configure these fields only once and avoid modifications unless absolutely necessary.