Solution Structure

Each solution folder must contain a solution.yaml file in which the relevant information about the solution must be entered. This includes, for example, the solution's name, description, tags, and parameters.

Resolution Process

As soon as a solution is to be used, parameter values are replaced in the permitted files, transferred to the project files, and automatically loaded into the configuration.

The following points must be noted:

• Parameters in the files must follow the format ${parameter_id}. Snake_case is recommended for the parameter ID notation.
• Files whose content has been modified by parameter resolution are written using UTF-8 encoding.
• Only the filename is used for the ParameterReplacementFileRegex check, not the entire file path.
• Parameters without a default value, an optional specification, and no entered value are replaced with an empty value. This can cause unintended behavior and should be checked beforehand.

Definitions

solution.yaml

Field Name	Type	Description
FormatVersion	int	Specifies the format version
CompatibleVersionRange	string	Version specification in loose Semver format. Used to check if the product version is compatible. If not, the solution is hidden. A missing specification accepts any version.
Tags	List (string)	List of tag IDs. See tags.yaml
DisplayName	TranslatableString	Display name
IconFile	string	File name of the icon file at the solution level. All common image formats such as PNG, JPG, and SVG are supported.
ShortDescription	TranslatableString	Short description of a solution used in the overview.
Description	TranslatableString	Description of the solution with usage notes. Can be overridden by a Markdown file (see below).
Parameters	Mapping (Solution Parameters)	Key: Parameter ID. Used when applying the solution in the format ${<parameter_id>}. Value: Solution parameter
ParameterReplacementFileRegex	string	Regex for filtering filenames during parameter resolution when using the solution. Omitting this value allows all files. If specified, only matching files are resolved.

Solution Parameters

Basic

The base configuration applies to all parameter types.

Field Name	Type	Description
Label	TranslatableString	Name of the parameter
HelpText	TranslatableString	Help text
Required	bool	Specifies whether the parameter is required. Default is true.

Boolean

Used to specify a Boolean value (true/false).

Field Name	Type	Description
Default	bool	Default value for user input. No value specified results in false.

Dropdown

Used to provide a selection of constant values.

Field Name	Type	Description
Default	string	Default value for user input. Refers to the internal value of an item in the selection.
Items	List (DropdownItem)	Available selection.

DropdownItem

Field Name	Type	Description
DisplayText	TranslatableString	Display name
Value	string	Internal value. Used during parameter resolution.

Integer

Used to specify an integer.

Field Name	Type	Description
Default	int	Default value for user input.
Min	int	Minimum value
Max	int	Maximum value

SecretKey

Used to specify a secret key from a secret store.

No additional fields available.

String

Used to specify a string.

Field Name	Type	Description
Default	string	Default value for user input.
MinLength	int	Minimum length
MaxLength	int	Maximum length

FileName

Used to specify a file name. Differences from the String parameter include validation for allowed characters and updating the display for conflicts.

Field Name	Type	Description
Default	string	Default value for user input.
MinLength	int	Minimum length
MaxLength	int	Maximum length

Markdown Description

A Markdown file can optionally be created to describe a solution. The following naming conventions apply:

• The file must be located at the solution level (at the level of solution.yaml).
• The base filename is description. Translations are optional and can be indicated using a _de or _en suffix.
  • Example: description.md or description_de.md
• The file must end with .md.
• Only features from the CommonMark Standard are supported.

Example of a solution.yaml

solution.yaml

FormatVersion: 1
ParameterReplacementFileRegex: .*yaml
CompatibleVersionRange: =>5.2 <=6.0
Tags:
  - Example
IconFile: "example.svg"
DisplayName:
  DE: "Beispiel"
  EN: "Example"
ShortDescription:
  DE: "Kurze Beschreibung"
  EN: "Short description"
Parameters:
  # String parameter
  example_string:
    Type: "String"
    Label:
      DE: "Ein String"
      EN: "A string"
    HelpText:
      DE: "Hilfetext"
      EN: "Help text"
    Default: "Test"
    MinLength: 5
    MaxLength: 30
  # File Name Example
  example_file_name:
    Type: "FileName"
    Label:
      DE: "Ein Dateiname"
      EN: "A file name"
    HelpText:
      DE: "Hilfetext"
      EN: "Help text"
    Default: "test-file-name"
  # Integer parameter
  example_integer:
    Type: "Integer"
    Label:
      DE: "Beispiel Ganzzahl"
      EN: "Example integer"
    Default: 1234
    Min: 10
    Max: 9999
  # Dropdown parameter
  example_dropdown:
    Type: "Dropdown"
    Label:
      DE: "Beispiel Dropdown"
      EN: "Example dropdown"
    Items:
      - DisplayText:
          DE: "Option 1"
          EN: "Option 1"
        Value: "1"
      - DisplayText:
          DE: "Option 2"
          EN: "Option 2"
        Value: "2"
    Default: "1"
  # Secret key parameter
  example_secret_key:
    Type: "SecretKey"
    Label:
      DE: "Geheim"
      EN: "Secret"
  # Boolean parameter
  example_boolean:
    Type: "boolean"
    Label:
      DE: "Beispiel Boolean"
      EN: "Example Boolean"
    Default: true
```</parameter_id>