Solution Structure

Every solution folder must contain a solution.yaml file. This file describes the solution from both a business and technical perspective.

Using the solution.yaml file, you specify, among other things:

• how the solution is displayed in the Solution Gallery
• for which OPC Router versions it should be offered
• which parameters the user must enter or select during import
• in which files parameter values may be replaced

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 should be noted:

• Parameters in the files must follow the format ${<parameter_id>}. The snake_case¹ convention is recommended for parameter IDs.
• Files whose content has been modified by parameter resolution are saved 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, or an entered value are replaced with an empty value. This can cause unintended behavior and should be checked beforehand.

In practice, this means: Any information that may vary in the target project should be deliberately modeled as a parameter. This helps you avoid rework after the import and reduces the risk of incomplete or incorrect project customizations.

Definitions

solution.yaml

Field Name	Type	Description	Example
FormatVersion	int	Format version	1
CompatibleVersionRange	string	Version specification in loose Semver format. This is used to check whether the product version is compatible. If not, the solution is hidden. If left blank, any version is accepted.	"=>5.2 <=6.0"
Tags	List (string)	List of tag IDs. Tags are used in the Solution Gallery as search and filter aids to find solutions by topic or technology. See tags.yaml	["Example"]
DisplayName	TranslatableString	Display name	DE: "Example"
IconFile	string	File name of the icon file at the solution level. All common image formats such as PNG, JPG, and SVG are supported.	"example.svg"
ShortDescription	TranslatableString	Short description of a solution used in the overview.	DE: "Short description"
Description	TranslatableString	Description of the solution with usage notes. Can be overridden by a Markdown file (see below).	DE: "Detailed description"
Parameters	Mapping (Solution Parameters)	Mapping with the parameter ID as the key and the solution parameter as the value. The parameter ID is used in the format ${<parameter_id>} when the solution is used.	example_string:
ParameterReplacementFileRegex	string	Regular expression for filtering filenames during parameter resolution when using the solution. Omitting this parameter allows all files. If specified, only matching files are resolved.	".*yaml"

Solution Parameters

Parameters define the values that a user enters or selects when importing a solution. They allow you to control which parts of the solution can be customized for the target project without manually editing the project files.

Each parameter consists of a parameter ID and an associated configuration. The parameter ID is used in the project files as a placeholder in the format ${<parameter_id>}.

Select the parameter type so that it matches the expected input. This makes the input clearer for the user and avoids error-prone free-text entry.

Basic

The basic configuration applies to all parameter types.

Field Name	Type	Description	Example
Label	TranslatableString	Name of the parameter in the input form	DE: "Server Name"
HelpText	TranslatableString	Help text for the user, for example regarding the expected format or purpose	DE: "Enter the hostname for the target server."
Required	bool	Specifies whether the user must enter a value. Default is true.	true

Boolean

Use this type for yes/no decisions or to enable or disable a feature.

Field Name	Type	Description	Example
Default	bool	Default value for user input. Omitting a value results in false.	true

Dropdown

Used to provide a selection of constant values.

Field Name	Type	Description	Example
Default	string	Default value for user input. Refers to the internal value of an item in the selection.	"1"
Items	List (DropdownItem)	Available options.	"Option 1", "Option 2"

DropdownItem

Field Name	Type	Description	Example
DisplayText	TranslatableString	Display name	DE: "Option 1"
Value	string	Internal value. Used during parameter resolution.	"1"

Integer

Used to specify an integer.

Field Name	Type	Description	Example
Default	int	Default value for user input.	1234
Min	int	Minimum value	10
Max	int	Maximum value	9999

SecretKey

Use this type if the user is to select a secret key from an existing secret store. This ensures that sensitive values do not have to be stored in plain text in the solution or in project files.

No additional fields available.

String

Use this type for free-form text entries, such as URLs, server names, client IDs, or other identifiers.

Field Name	Type	Description	Example
Default	string	Default value for user input.	"server01"
MinLength	int	Minimum length	3
MaxLength	int	Maximum length	50

FileName

Use this type when the user is required to enter a filename.
Unlike the string parameter, the input is checked for valid characters. Additionally, the user interface can display filename conflicts more specifically.

Field Name	Type	Description	Example
Default	string	Default value for user input.	"export.csv"
MinLength	int	Minimum length	3
MaxLength	int	Maximum length	64

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 added 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 file

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: "A string"
      EN: "A string"
    HelpText:
      DE: "Help text"
      EN: "Help text"
    Default: "Test"
    MinLength: 5
    MaxLength: 30
  # File Name Example
  example_file_name:
    Type: "FileName"
    Label:
      DE: "A file name"
      EN: "A file name"
    HelpText:
      DE: "Help text"
      EN: "Help text"
    Default: "test-file-name"
  # Integer parameter
  example_integer:
    Type: "Integer"
    Label:
      DE: "Example integer"
      EN: "Example integer"
    Default: 1234
    Min: 10
    Max: 9999
  # Dropdown parameter
  example_dropdown:
    Type: "Dropdown"
    Label:
      DE: "Example 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: "Secret"
      EN: "Secret"
  # Boolean parameter
  example_boolean:
    Type: "Boolean"
    Label:
      DE: "Example Boolean"
      EN: "Example Boolean"
    Default: true

Footnotes

1. snake_case refers to a naming convention using lowercase words and underscores as separators, for example, server_url or project_name. ↩