Customization
Open Modeling Language (OML)
The modeling vocabulary (element types, relationship types, properties, layers, validations, and guidelines) is defined by the Open Modeling Language (OML). OML uses modeling configurations composed of modeling profiles: versioned, shareable artifacts that define what can be modeled in a project. Projects reference a modeling configuration (by id and version).
Customization is done by providing own profiles directly within each project. Therefore place your profiles in a .k5 folder and reference them in the k5-oml.yaml.
To understand how modeling languages are defined and how to use or compose configurations and profiles, see Open Modeling Language (OML) and the OML configuration reference with its examples. As starting point you can use OML profile reference.
For troubleshooting during customization you may find helpful the log outputs of the pods k5-designer-backend and k5-diagram-modeler-sevice. The names may differ for your installation from the standard.
Custom fields
On the Overview page, you can also define and manage your own fields for model elements, diagrams and decisions within your Software architecture 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.
Instead of using custom fields, we currently recommend to use OML definitions and adaption of the fields herein.
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.