Modul und Modulinstanz Einstellungen

Jedes Modul und jede Modulinstanz (Komponente) kann festlegen welche Einstellmöglichkeiten es benötigt. Als Entwickler des Moduls legst du diese über JSON Dateien fest. Vom BPC Backend wird dann die Persistierung und vom BPC Frontend die Editiermöglichkeit zur Verfügung gestellt. Auch Module, welche nur aus einem Frontend Modul bestehen und keine eigene Backend-Modul-Implementierung besitzen bzw. benötigen, können Konfigurationsmöglichkeiten festlegen.

Backend

Es wird empfohlen, für die Festlegung der Modul und Instanzkonfigurationen JSON Dateien zu verwenden. Dies ist zwar nicht unbedingt notwendig, erspart aber einiges an Code und beschleunigt die Umsetzung. Deshalb wird im Rahmen dieser Dokumentation nur auf diese Möglichkeit eingegangen. Zum Einlesen der Konfigurationsdateien, sind in der Modul-Implementierung folgende beiden Methoden zu implementieren.

Eine gute Vorlage für eigene Modul Implementierungen stellt der Code aus dem bpc-be-template Repository dar. Daraus ist auch der folgende Code der 1:1 so übernommen werden kann.

public class TemplateModule extends AbstractInstantiableModule {
...
    @Override
    public ModuleConfiguration getDefaultConfiguration() {
        return ModuleConfigurationBuilder.newInstance()
                .withModuleId(getModuleId())
                .addSortableGroupedSettingsFromFile(getModuleBundle(), "defaults/default_module_settings.json")
                .build();
    }

    @Override
    public ModuleConfiguration getDefaultInstanceConfiguration() {
        return ModuleConfigurationBuilder.newInstance()
                .withModuleId(getModuleId())
                .withInstanceId(null)
                .addSortableGroupedSettingsFromFile(getModuleBundle(), "defaults/default_instance_settings.json")
                .build();
    }
...
}

Die Methode getDefaultConfiguration() stellt die Konfiguration des Moduls zur Verfügung und getDefaultInstanceConfiguration() die Konfiguration von Modulinstanzen.

Die beiden referenzierten JSON Dateien werden im eigenen Backend Modul Code wie folgt abgelegt:

Frontend

Sollte es sich um ein Modul ohne eigene Backend-Modul Implementierung handeln, dann sind die JSON Dateien an dieser Stelle im Frontend Code abzulegen.

Aufbau der JSON basierten Konfigurationsdateien

Der Aufbau der beiden JSON Dateien für Module und Modulinstanzen unterscheidet sich nicht. Die einzelnen Einstellungen werden über Gruppen gruppiert. Diese Gruppen dienen bei vielen Einstellmöglichkeiten zur besseren Organisation und auch um die eigenen Einstellungen von den vom BPC zur Verfügung gestellten Default-Einstellungen auseinander zu halten. Das bezieht sich nicht nur auf das JSON, auch im BPC Frontend kommen diese Gruppen zum Einsatz.

{
  "gruppenname1": {
    "sortPriority": 10,
    "settings": [ ... ]
  },
  "gruppenname2": {
    "sortPriority": 20,
    "settings": [ ... ]
  },
  "gruppenname3": {
    "sortPriority": 30,
    "settings": [ ... ]
  }, ...
}

Das JSON Object besteht aus den Namen der Gruppen mit der sortPriority und den settings.

Die sortPriority wird vom BPC Frontend verwendet, um die Gruppen in einer bestimmten Reihenfolge anzuzeigen. Dabei hat die BPC Default-Gruppe module die sortPriority von 1, so dass diese Gruppe immer an erster Position in der Tabelle dargestellt wird.

Das BPC legt für jedes Modul und jede Modulinstanz diverse Einstellungen an. Sollen die eigenen Einstellungen mit in die vom BPC angelegten Gruppen, dann ist der Name wie zum Beispiel module als Gruppenname zu verwenden. Die eigenen Einstellungen werden dann zu der Gruppe hinzugefügt.

Bei vorhandenen Einstellungen können abweichende Default-Werte festgelegt werden. Dabei muss der Name und Typ mit der vorhandenen Einstellung übereinstimmen.

In dem settings Array werden die Einstellungen/Konfigurationsmöglichkeiten des eigenen Moduls mit Name, Typ, Default-Wert sowie Lese/Schreibrechte festgelegt.

Beispiel Setting

{
    "name": "server_url",
    "value": "https://www.example.com",
    "type": "text",
    "_writeableByRoles": [ "bpcadmin" ],
    "_readableByRoles": [ "bpcadmin", "bpcuser" ],
    "_label": "CUSTOM_MODULE_SETTING_SERVER_URL_LABEL"
}

Erklärung der Felder eines Settings:

name
Name der Einstellung, dieser wir zur Referenzierung sowie zur Persistierung verwendet.
value
Den Default-Wert, welcher das Setting haben soll.
type
Den Typ der Einstellung. Je nach Typ kommen im Frontend zum Editieren unterschiedliche Editoren zum Einsatz. Die möglichen Typen wie text, boolean, json etc. sind unter 'Die möglichen Typen' aufgelistet.
_writeableByRoles
Legt die Rollen der Benutzer fest, welche die Einstellung editieren und löschen können.
_readableByRoles
Legt die Rollen der Benutzer fest, welche den Wert der Einstellung auslesen können.
_label
Der Key welcher für die Übersetzung des Namen verwendet werden soll. Siehe Multiple Language Support
_tooltip: Ein Verweis auf einen Sprachschlüssel für einen Hilfetext, der als Tooltip neben der Einstellung angezeigt wird.

Die möglichen Typen

Im Folgenden werden die verwendbaren Typen aufgelistet und auf deren Verwendung eingegangen.

An den welcher in Zukunft die Liste aktualisiert: Die Typen/Editoren der Ext JS Komponenten müssen den Alias-Prefix widget.bpcconfig. haben und sind dann leicht zu finden. Beispielsweise ist für den Typ list dann der Alias der Ext JS Komponente widget.bpcconfig.list.

Typ `text`

Ein einfaches Texteingabefeld für einzeilige Zeichenketten.

Beispiel

{
  "name": "url",
  "value": "jdbc:oracle:thin:@example.com:1521:XE",
  "type": "text",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin"],
  "_label": "CORE_SETTING_DATASOURCE_URL_LABEL",
  "_tooltip": "CORE_SETTING_DATASOURCE_URL_TOOLTIP",
  "disableEncoding": false
}

Über die Option disableEncoding kann das HTML Encoding deaktiviert werden, welches in der Voreinstellung aktiv ist. Dies sollte nur dann zum Einsatz kommen bzw. deaktiviert werden, wenn die Daten nicht wie gewünscht gespeichert und wieder ausgelesen werden. Zum Beispiel kann dies bei regulären Ausdrücken vorkommen.

Typ `icon`

Ermöglicht die Auswahl eines Icons aus der Font Awesome Bibliothek. Das Frontend stellt ein Auswahlfenster mit Vorschau zur Verfügung.

Beispiel

{
  "name": "module_iconCls",
  "value": "x-fal fa-database",
  "type": "icon",
  "_label": "CORE_SETTING_MODULE_ICONCLS_LABEL",
  "_tooltip": "CORE_SETTING_MODULE_ICONCLS_TOOLTIP"
}

Typ `boolean` or `bool`

Boolean Wert, der eine Checkbox darstellt und true oder false annehmen kann.

Beispiel

{
  "name": "allowUntrustedConnections",
  "value": false,
  "type": "boolean",
  "_writeableByRoles": ["bpcadmin"],
  "_readableByRoles": ["bpcadmin"],
  "_label": "CORE_SETTING_DEPLOYMENT_SYSTEM_ALLOW_UNTRUSTED_CONNECTIONS_LABEL",
  "_tooltip": "CORE_SETTING_DEPLOYMENT_SYSTEM_ALLOW_UNTRUSTED_CONNECTIONS_TOOLTIP"
}

Typ `number` oder `integer` oder `int`

Numerischer Wert, auch Zahl genannt.

Beispiel

{
  "name": "sortPriority",
  "value": 1000,
  "type": "int",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin", "bpcuser" ],
  "_label": "CORE_SETTING_DEPLOYMENT_SYSTEM_SORT_PRIORITY_LABEL",
  "_tooltip": "CORE_SETTING_DEPLOYMENT_SYSTEM_SORT_PRIORITY_TOOLTIP"
}

Typ `password`

Ein spezielles Eingabefeld für Passwörter. Die Eingabe wird maskiert (z.B. durch Sternchen) und der Wert serverseitig verschlüsselt gespeichert.

Beispiel

{
  "name": "password",
  "value": "",
  "type": "password",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin"],
  "_label": "CORE_SETTING_DATASOURCE_PASSWORD_LABEL",
  "_tooltip": "CORE_SETTING_DATASOURCE_PASSWORD_TOOLTIP"
}

Typ `list`

Erzeugt eine Dropdown-Liste mit vordefinierten Werten. Die verfügbaren Optionen werden im Attribut _valueList als Array von Strings definiert.

Einfache Werte Beispiel

{
  "name": "identityProvider",
  "value": "karaf",
  "type": "list",
  "_valueList": [ "karaf", "jdbc", "keycloak", "oidc" ],
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin" ],
  "_label": "CORE_SETTING_IDENTITYPROVIDER_LABEL",
  "_tooltip": "CORE_SETTING_IDENTITYPROVIDER_TOOLTIP"
}

Übersetzte Werte Beispiel

{
  "type": "list",
  "value": "table",
  "_valueList": [
    {"value": "columns", "label": "DASHBOARD_SETTING_LAYOUT_CONFIG_DEFAULT_LABEL"},
    {"value": "table", "label": "DASHBOARD_SETTING_LAYOUT_CONFIG_TABLE_LABEL"}
  ]
}

Typ `date`

Erzeugt einen Date Picker, der dem Benutzer ermöglicht, ein spezifisches Datum aus einem Kalender auszuwählen.

Beispiel

{
  "name": "validFrom",
  "value": "2025-10-01T00:00:00.000Z",
  "type": "date",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin", "bpcuser" ],
  "_label": "CORE_SETTING_VALID_FROM_LABEL",
  "_tooltip": "CORE_SETTING_VALID_FROM_TOOLTIP"
}

Typ `language`

Zur Auswahl einer verfügbaren Sprache.

Beispiel

{
  "name": "fallback_language",
  "value": "de",
  "type": "language",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin", "bpcuser" ],
  "_label": "CORE_SETTING_HTML_CONTENT_FALLBACK_LANGUAGE_LABEL",
  "_tooltip": "CORE_SETTING_HTML_CONTENT_FALLBACK_LANGUAGE_TOOLTIP"
}

Typ `json`

Für JSON Objekte bzw. Arrays. Kleinere Default-Werte können direkt gesetzt werden (siehe Inline JSON Object Beispiel). Für grössere Objekte empfiehlt es sich, diese auszulagern (siehe External Beispiel). Dabei wird der Pfad zur Resources Datei als String angegeben. Das BPC liest und setzt den Wert dann aus dieser JSON Datei.

JSON eignet sich besonders für dynamische oder unbekannte Strukturen, z.B. benutzerspezifische Metadaten. Wenn eine fest und bekannte Menge an Attributen konfiguriert werden soll, ist es dringend emfohlen, diese auf mehrere, einzelne Settings aufzuteilen. Dies erhöht die Übersichtlichkeit, Wartbarkeit und Datenintegrität, da jeder Wert den passenden Setting-Typ (number, boolean, etc.) erhält.

Inline JSON Object Beispiel

{
  "name": "configuration",
  "value": {
    "pool": "dbcp2",
    "xa": "true",
    "pool.maxTotal": "10",
    "pool.maxIdle": "5",
    "pool.minIdle": "2"
  },
  "type": "json",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin"],
  "_label": "CORE_SETTING_DATASOURCE_CONFIGURATION_LABEL",
  "_tooltip": "CORE_SETTING_DATASOURCE_CONFIGURATION_TOOLTIP"
}

Inline JSON Array Beispiel

{
  "type": "json",
  "value": [
    "red",
    "green",
    "blue"
  ]
}

External Beispiel

{
  "type": "json",
  "value": "defaults/pool_settings.json"
}

defaults/pool_settings.json

{
  "pool": "dbcp2",
  "pool.minIdle": "2",
  "pool.maxIdle": "5",
  "pool.maxTotal": "10"
}

Typ `sql`

Ein mehrzeiliges Textfeld, das für die Eingabe von SQL-Abfragen vorgesehen ist und im Frontend eine entsprechende Formatierung und Syntax-Hervorhebung bietet.

Beispiel

{
  "name": "sourceCommonTableExpressionQuery",
  "value": "SELECT * FROM articles;",
  "type": "sql",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin" ],
  "_label": "CORE_SETTING_REPLICATION_SOURCE_COMMON_TABLE_EXPRESSION_QUERY_LABEL",
  "_tooltip": "CORE_SETTING_REPLICATION_SOURCE_COMMON_TABLE_EXPRESSION_QUERY_TOOLTIP"
}

Typ `xml`

Stellt ein mehrzeiliges Textfeld zur Verfügung, das speziell für die Eingabe von XML-Daten konzipiert ist. Das Frontend bietet Syntax-Hervorhebung und eine Validierung, um die Korrektheit des XML-Dokuments sicherzustellen.

Beispiel

{
  "name": "legacy_system_config",
  "value": "<config>\n  <user role=\"admin\">\n    <id>user01</id>\n  </user>\n  <options>\n    <timeout>30</timeout>\n    <retries enabled=\"true\">5</retries>\n  </options>\n</config>",
  "type": "xml",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin" ],
  "_label": "CORE_SETTING_LEGACY_SYSTEM_CONFIG_LABEL",
  "_tooltip": "CORE_SETTING_LEGACY_SYSTEM_CONFIG_TOOLTIP"
}

Typ `css`

Ein mehrzeiliges Textfeld, das speziell für die Eingabe von CSS-Code vorgesehen ist und entsprechende Syntax-Hervorhebung bieten kann.

Beispiel

{
    "name": "editorStyles",
    "value": ".custom1{color : blue } .custom2{ color: green }",
    "type": "css",
    "_writeableByRoles": [ "bpcadmin","htmlcontent_editor" ],
    "_readableByRoles": [ " bpcadmin", "bpcuser" ],
    "_label": "CORE_SETTING_CSS_EDITOR_STYLES"
}

Typ `code`

Für Code Schnipsel. ein generischer Setting-Typ, der ein Eingabefeld darstellt, bei dessen Aktivierung sich ein separates, großes Code-Editor-Fenster öffnet. Mit editorLangauge kann die Sprache konfiguriert werden. Ohne Angabe findet keine Sprachvalidierung statt.

Beispiel

{
  "name": "processing_script",
  "value": "function process(data) {\n  // Implementierung hier\n  return data.value * 1.1;\n}",
  "type": "code",
  "_editorLanguage": "javascript",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin" ],
  "_label": "CORE_SETTING_PROCESSING_SCRIPT_LABEL",
  "_tooltip": "CORE_SETTING_PROCESSING_SCRIPT_TOOLTIP"
}

Typ `dataSourceCombo`

Zur Festlegung bzw. Auswahl einer vorhandenen Datenbank Data Source.

Beispiel

{
  "name": "rdmsDataSourceName",
  "value": "",
  "type": "dataSourceCombo",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin" ],
  "_label": "CORE_SETTING_REPLICATION_RDMS_DATASOURCE_NAME_LABEL",
  "_tooltip": "CORE_SETTING_REPLICATION_RDMS_DATASOURCE_NAME_TOOLTIP"
}

Typ `index`

Zur Festlegung bzw. Auswahl eines OpenSearch Index.

Beispiel

{
  "name": "data_index",
  "value": "",
  "type": "index",
  "_writeableByRoles": ["bpcadmin"],
  "_readableByRoles": ["bpcadmin", "bpcuser"],
  "_label": "MONITOR_SETTING_DATA_INDEX_LABEL",
  "_tooltip": "MONITOR_SETTING_DATA_INDEX_TOOLTIP"
}

Typ `datasourcefactoryselector`

Stellt eine Dropdown-Liste zur Auswahl einer verfügbaren "Datasource Factory" bereit, um Treiber für Datenbankverbindungen zu definieren.

Beispiel

{
  "name": "driverName",
  "value": "",
  "type": "datasourcefactoryselector",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin"],
  "_label": "CORE_SETTING_DATASOURCE_DRIVERNAME_LABEL",
  "_tooltip": "CORE_SETTING_DATASOURCE_DRIVERNAME_TOOLTIP"
}

Typ `linkedModuleInstance` oder `moduleInstance`

Ermöglicht die Verknüpfung zu einer anderen, einzelnen Modulinstanz. Filtert die auswählbaren Instanzen anhand von _linkedModuleId und _linkedInstanceType. Der value speichert die ID der verknüpften Instanz.

Beispiel

{
  "name": "identityProviderBackendConnection",
  "value": "idp_karaf",
  "type": "linkedModuleInstance",
  "_linkedModuleId": "backendconnection",
  "_linkedInstanceType": "identity_provider",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin" ],
  "_label": "CORE_SETTING_IDENTITYPROVIDER_BACKENDCONNECTION"
}

Typ `coreLogLevelSelector`

Eine spezialisierte Dropdown-Liste zur Auswahl eines Log-Levels (z.B. DEBUG, INFO, WARN, ERROR).

Beispiel

{
  "name": "logLevel",
  "type": "coreLogLevelSelector",
  "value": "warn",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin", "bpcuser" ],
  "_label": "CORE_SETTING_LOG_LEVEL"
}

Typ `corethemeselector`

Eine Dropdown-Liste zur Auswahl eines verfügbaren BPC-Themes für das Frontend.

Beispiel

{
  "name": "theme_name",
  "value": "Default",
  "type": "corethemeselector",
  "_writeableByRoles": [ "bpcadmin" ],
  "_readableByRoles": [ "bpcadmin", "bpcuser" ],
  "_label": "CORE_SETTING_THEME_NAME"
}

Typ `tag`

Stellt ein Eingabefeld zur Verfügung, das es dem Benutzer erlaubt, mehrere separate Textwerte einzugeben.

Beispiel

{
  "name": "content_tags",
  "value": [
    "wichtig",
    "abrechnung",
    "q3_2025"
  ],
  "type": "tag",
  "_writeableByRoles": [ "bpcadmin", "editor" ],
  "_readableByRoles": [ "bpcadmin", "bpcuser" ],
  "_label": "CORE_SETTING_CONTENT_TAGS_LABEL",
  "_tooltip": "CORE_SETTING_CONTENT_TAGS_TOOLTIP"
}

Zugriff auf die Modul-Einstellungen vom Backend Modul aus

Der Zugriff auf die Modul- und Modulinstanz-Einstellungen finden jeweils über die Methode getConfiguration() statt, welche eine de.virtimo.bpc.api.ModuleConfiguration zurückliefert. Der dann beste Weg um auf den Wert einer Einstellung zuzugreifen erfolgt über getSettingValue(settingName).

Beispiel-Zugriff von einem Modul aus

import de.virtimo.bpc.api.ModuleConfiguration;
import de.virtimo.bpc.module.AbstractInstantiableModule;

public class ExampleModule extends AbstractInstantiableModule {
    public static final String MODULE_SETTING_DATABASE_PREFIX = "databasePrefix";

    private String getDatabasePrefix() {
        ModuleConfiguration moduleConfig = getConfiguration();
        return moduleConfig.getSettingValue(MODULE_SETTING_DATABASE_PREFIX).asString();
    }
}

Beispiel-Zugriff von einer Modulinstanz aus

import de.virtimo.bpc.api.ModuleConfiguration;
import de.virtimo.bpc.module.AbstractModuleInstance;

public class ExampleModuleInstance extends AbstractModuleInstance {
    private static final String MODULE_INSTANCE_SETTING_WRITE_TO_DATABASE_ENABLED = "writeToDatabaseEnabled";

    private boolean isWriteToDatabaseEnabled() {
        ModuleConfiguration moduleInstanceConfig = getConfiguration();
        return moduleInstanceConfig.getSettingValue(MODULE_INSTANCE_SETTING_WRITE_TO_DATABASE_ENABLED).asBoolean();
    }

    private String getDatabasePrefixFromParentModule() {
        ModuleConfiguration moduleConfig = getParentModule().getConfiguration();
        return moduleConfig.getSettingValue(ExampleModule.MODULE_SETTING_DATABASE_PREFIX).asString();
    }
}

Zugriff vom Frontend Modul

Der Zugriff auf ein Setting in den Modul- und Modulinstanz-Einstellungen erfolgt über die Methode BpcCommon.Api.getSetting. Diese Methode liefert den Wert bzw. das Datenmodell des Settings zurück. Das Datenmodell wird unter anderem benötigt, um schreibende Zugriffe auf Settings zu ermöglichen.

Folgende Parameter müssen übergeben werden: . Modul- oder Instanz-ID (im Falle eines Core-Settings "_core") . Setting-Name . getModel (Default: false, steuert, ob das Datenmodell zurückgegeben wird) .Beispiel-Zugriff aus einer ExtJs Klasse im BPC

// Lesezugriff auf ein Core-Setting
BpcCommon.Api.getSetting("_core", "browser_title")

// Lesezugriff auf ein Monitor-Modul-Setting
BpcCommon.Api.getSetting("monitor", "moduleUrl")

// Lesezugriff auf ein Setting der Monitorinstanz "auditlog"
BpcCommon.Api.getSetting("auditlog", "module_name")

// Lesezugriff (über das Datenmodell) auf Inhalte einer Modulinstanz mit der Instanz-ID "myhtmlcontent"
BpcCommon.Api.getSetting("myhtmlcontent", "content", true).get("value")

// Schreibzugriff (über das Datenmodell) auf Inhalte einer Modulinstanz mit der Instanz-ID "myhtmlcontent"
BpcCommon.Api.getSetting("myhtmlcontent", "content", true).set("value", [])

Keywords:

Modul und Modulinstanz Einstellungen

Backend

Frontend

Aufbau der JSON basierten Konfigurationsdateien

Die möglichen Typen

Typ text

Typ icon

Typ boolean or bool

Typ number oder integer oder int

Typ password

Typ list

Typ date

Typ language

Typ json

Typ sql

Typ xml

Typ css

Typ code

Typ dataSourceCombo

Typ index

Typ datasourcefactoryselector

Typ linkedModuleInstance oder moduleInstance

Typ coreLogLevelSelector

Typ corethemeselector

Typ tag

Zugriff auf die Modul-Einstellungen vom Backend Modul aus

Zugriff vom Frontend Modul

Typ `text`

Typ `icon`

Typ `boolean` or `bool`

Typ `number` oder `integer` oder `int`

Typ `password`

Typ `list`

Typ `date`

Typ `language`

Typ `json`

Typ `sql`

Typ `xml`

Typ `css`

Typ `code`

Typ `dataSourceCombo`

Typ `index`

Typ `datasourcefactoryselector`

Typ `linkedModuleInstance` oder `moduleInstance`

Typ `coreLogLevelSelector`

Typ `corethemeselector`

Typ `tag`