Profile-Konfiguration Referenz

Zweck

Profile definieren in centraQuest, wie ein Objekt fachlich verwendet, angezeigt, gesucht, importiert, bearbeitet und in Tabellen dargestellt wird. Ein Profil ist dabei nicht zwingend identisch mit einer Datenbanktabelle oder einem DMS-Aspekt. Es ist eher die fachliche Sicht auf eine oder mehrere technische Masken/Aspekte.

Diese Seite dokumentiert die Struktur eines Eintrags unter profiles: und erklärt die Wirkung der wichtigsten und in den Konfigurationen tatsächlich vorkommenden Eigenschaften. Für die Analyse wurden die Standardkonfigurationen in centraquest und die kundenspezifischen Konfigurationen unter C:\Users\danie\IdeaProjects\centraquestCustom berücksichtigt.

Grundprinzip

Ein Profil steht in einer YAML-Datei unter dem Schlüssel profiles::

profiles:
  - id: obj_table_invoice_account
    label: Accounts
    profile_type: ["insert", "internal", "view"]
    mask: obj_table_invoice_account
    fields:
      - id: cq_account_no
        label: Account
        type: string
        searchable: true
    result_columns:
      - id: cq_account_no
        label: Account
    table:
      enabled: true
      route: /webui/profile_table?profile_id=obj_table_invoice_account

Die wichtigsten Bausteine sind:

• id: fachliche Profil-ID. Diese ID wird in URLs, obj_profile, Importen, Dialogen und Details verwendet.
• profile_type: Kontext, in dem das Profil gültig ist, zum Beispiel insert, view, search, table, internal oder folder.
• mask: technische Maske oder Aspekt, auf dem die Felder gespeichert werden.
• fields: Felder und UI-Verhalten im Detailformular.
• result_columns: Spalten für Trefferlisten und Tabellen.
• table: moderne Tabellen-/Admin-Konfiguration für /webui/profile_table.

Lade- und Transformationslogik

Die Profile werden beim Start aus allen geladenen YAML-Konfigurationen zusammengeführt. Danach transformiert der Default-Configurator die Profile:

• Globale fields und field_groups werden in Profile expandiert.
• inherit wird aufgelöst.
• Für view-Profile können automatisch search-Profile erzeugt werden, wenn create_search_profiles aktiv ist.
• Bei Vererbung werden Listen mit id nicht stumpf ersetzt, sondern Einträge mit gleicher id aktualisiert und neue Einträge angehängt.

Wichtig: Die am Ende wirksame Konfiguration ist nicht immer exakt die YAML-Datei. Sie ist das Ergebnis aus globalen Feldern, Field-Groups, Vererbung und automatischer Search-Profil-Erzeugung.

Top-Level-Eigenschaften eines Profils

Identität und Typ

Eigenschaft	Wirkung
id	Eindeutige fachliche Profil-ID. Wird unter anderem in profile_id, obj_profile, Import-URLs und Tabellenlinks verwendet.
label	Sichtbarer Name des Profils. Wird in Dialogen, Details, Tabellen und Menüs verwendet.
title	Alternativer Titel für spezielle Reports oder Dialoge. Wenn vorhanden, kann dieser statt label verwendet werden.
profile_type	Gültigkeitsbereich des Profils. Häufige Werte sind insert, view, search, table, internal, folder. Kann String oder Liste sein.
mask	Technische Maske oder Aspekt. Kann ein String oder eine Liste sein. Bei Listen nimmt generische Tabellenlogik oft den ersten Eintrag als Hauptaspekt.
table_name	Alternativer technischer Tabellen-/Aspektname, vor allem bei tabellarischen oder importnahen Profilen.
type	Fachlicher Sondertyp. Kommt in gewachsenen Konfigurationen vor und wird von Speziallogik interpretiert.

Formulare und Details

Eigenschaft	Wirkung
fields	Liste der Felder, die im Profil sichtbar, editierbar, suchbar oder technisch relevant sind.
tab_ids	Tabs für generische Detailseiten. Felder mit tab_id werden diesen Tabs zugeordnet.
invoice_tab_ids	Invoice-spezifische Tab-Liste für Rechnungsdetailseiten.
visible_tabs	Einschränkung oder Steuerung sichtbarer Tabs in älteren oder kundenspezifischen Masken.
edit_tabs	Tabs für Editierdialoge, wenn Bearbeitungs- und Anzeigeansicht auseinanderfallen.
properties_dialog	Pfad zu einem Microclient-/YAML-Properties-Dialog. Wird für klassische Dialoge und bestimmte Import-/Edit-Flows genutzt.
main_dialog	Hauptdialog für Spezialmasken. Kommt in Custom-Konfigurationen vor.
detail_page_template	Eigene HTML-Detailseite statt generischer Detaildarstellung.
form	Report- oder Spezialformular-Konfiguration. Häufig mit tab_ids, Eingabefeldern oder Filterfeldern.
form_columns	Anzahl Spalten im generischen Formularlayout.
form_height	Vorgabe für Dialog- oder Formularhöhe.
label_spacing	Abstand/Label-Layout in Formularen.
initial_window_width	Startbreite für Dialogfenster.
initial_window_height	Starthöhe für Dialogfenster.
width	Breite eines Dialogs, Reports oder Formularbereichs. Kontextabhängig.
height	Höhe eines Dialogs, Reports oder Formularbereichs. Kontextabhängig.
edit_side_panel	Aktiviert oder konfiguriert seitliche Bearbeitungspanels in Spezialansichten.
split_window	Steuert geteilte Ansichten bei älteren Microclient-/Viewer-Flows.

Tabellen, Listen und Suche

Eigenschaft	Wirkung
result_columns	Trefferlisten-/Tabellenspalten auf Profilebene. Wird verwendet, wenn table.result_columns fehlt.
result_columns_short	Kürzere Spaltenvariante für kompakte Listen.
short_result_columns	Alternative Bezeichnung für kompakte Spaltenlisten.
columns	Spaltenliste bei Reports oder Speziallisten.
table	Moderne Tabellenkonfiguration für Profil-Tabellen. Siehe eigener Abschnitt.
query	DQL- oder SQL-Query für Report-/Listenprofile.
params	Parameterliste für Queries oder Value-Assistance-Konfigurationen.
dql_template	DQL-Template, häufig in generischen Reports oder kundenspezifischen Listen.
initial_search	Vorgabewerte oder Startverhalten für Suchprofile.
result_limit	Maximale Anzahl Treffer in Report-/Suchansichten.
limit_field	Feld, über das ein Limit oder Mandantenfilter gesteuert wird.
map_results	Mapping für Query-Ergebnisse in Reports oder Speziallisten.
report_type	Report-Variante oder Renderer-Auswahl.
refresh_on	Ereignisse oder Felder, bei denen eine Liste/ein Report neu geladen wird.
double_click_action	Aktion beim Doppelklick auf einen Treffer.

Navigation, Menüs und Aktionen

Eigenschaft	Wirkung
menu	Menüeinbindung oder Menüdefinition für klassische Navigation.
show_menu	Steuert, ob Menüeinträge angezeigt werden.
context_menu	Kontextmenü für Objekte oder Tabellenzeilen.
portlet_menu	Menüeinträge für Portlets/Dashboards.
button_ids	Liste aktivierter Buttons in klassischen Dialogen.
buttons	Direkte Button-Konfiguration in kundenspezifischen Profilen.
action	Zielaktion, URL oder Import-/Microclient-Aktion.
attachments	Konfiguration für Anhänge oder zugehörige Dokumente.
references	Referenzbeziehungen oder verknüpfte Objekte.
list_versions	Steuert, ob Versionen in Listen/Details angezeigt werden.

Sicherheit und Sichtbarkeit

Eigenschaft	Wirkung
acl	Rollen-/ACL-Beschränkung auf Profilebene. Wird von einigen Menüs, Reports oder Spezialansichten ausgewertet.
insert_grp	Rollen/Gruppen, die dieses Profil für Neuanlage/Import verwenden dürfen.
read_only_disabled	Schaltet Readonly-Verhalten in bestimmten Masken aus oder um.
show_subscription	Steuert Abonnement-/Benachrichtigungsfunktionen.
notify_on_save	Benachrichtigung nach Speichern, wenn von Speziallogik unterstützt.
debug / debug0	Aktiviert Debug-Verhalten in einzelnen Profilen oder historischen Custom-Flows.

Import, Integration und Sonderlogik

Eigenschaft	Wirkung
import_dialog	Dialog für Importprozesse.
import_excel	Excel-Import-Konfiguration.
database_connection	Datenbankverbindung für import- oder reportnahe Profile.
controller	Spezialcontroller für ein Profil.
mode	Modus für Spezialrenderer, Importer oder Reports.
constants	Profilbezogene Konstanten für Templates, Queries oder Controller.
variables	Variablen für Templates, Reports oder kundenspezifische Logik.
keyinfo_query	Query für Kontextinformationen.
keyinfo_dql	DQL für Kontextinformationen.
keyinfo_function	Funktion zur Ermittlung von Kontextinformationen.
folder_mask	Ziel- oder Kontextmaske für Ordnerprofile.
filename_field	Feld, das Dateinamen oder Exportnamen liefert.
has_obj_name	Hinweis für Speziallogik, ob obj_name vorhanden ist.
center_on	Zentrier-/Fokusfeld in bestimmten Speziallisten.
layout	Layoutvariante für kundenspezifische Seiten.
style	Stilvariante, meistens Custom- oder Portal-spezifisch.

Client-Unterstützung

Die folgende Matrix zeigt, welche Profileigenschaften vom klassischen Microclient und/oder von der WebUI ausgewertet werden. Ein x bedeutet: Der Client unterstützt diese Eigenschaft direkt oder über die generischen Profile-/Tabellen-/Formularrenderer. Leere Zellen bedeuten nicht zwingend, dass der Key wirkungslos ist; er kann trotzdem von kundenspezifischen Templates, Jobs, Imports oder Spezialcontrollern gelesen werden.

Top-Level-Profileigenschaften

Eigenschaft	microclient	webui	Hinweis
id	x	x	Zentrale Profil-ID für beide Clients.
label	x	x	Sichtbarer Name in Dialogen, Listen und Admin-Seiten.
title	x	x	Alternativer Titel in Reports, Dialogen oder Tabellen.
profile_type	x	x	Filtert Profile nach insert, view, search, table usw.
mask	x	x	Technische Maske bzw. Aspektbasis.
table_name	x	x	Wird vor allem von Tabellen-/Importlogik verwendet.
type	x	x	Spezialtyp für gewachsene Renderer oder Controller.
fields	x	x	Formular-, Such- und Tabellenbasis.
tab_ids	x	x	Generische Tab-Struktur.
invoice_tab_ids		x	Invoice-WebUI-Detailseiten.
visible_tabs	x	x	Legacy- und Spezialmasken.
edit_tabs	x	x	Editieransichten mit separater Tab-Steuerung.
properties_dialog	x		Klassischer YAML-/Microclient-Dialog.
main_dialog	x		Historische Spezialdialoge.
detail_page_template		x	Eigene WebUI-Detailseite.
form	x	x	Reports und Spezialformulare.
form_columns	x	x	Formularlayout.
form_height	x	x	Dialog-/Formularhöhe, je nach Renderer.
label_spacing	x	x	Layoutsteuerung.
initial_window_width	x		Microclient-Fensterbreite.
initial_window_height	x		Microclient-Fensterhöhe.
width	x	x	Kontextabhängige Breite.
height	x	x	Kontextabhängige Höhe.
edit_side_panel		x	WebUI-Spezialansichten.
split_window	x		Klassische geteilte Microclient-Ansichten.
result_columns	x	x	Trefferlisten, Reports und WebUI-Tabellen.
result_columns_short	x	x	Kompakte Listenvarianten.
short_result_columns	x	x	Alternative Schreibweise.
columns	x	x	Report- und Speziallisten.
table		x	Moderne /webui/profile_table-Konfiguration.
query	x	x	Report-/Listenabfragen.
params	x	x	Query- und Formularparameter.
dql_template	x	x	DQL-Templates für Reports/Speziallisten.
initial_search	x	x	Startfilter oder Suchvorgaben.
result_limit	x	x	Trefferbegrenzung.
limit_field	x	x	Limit-/Mandantensteuerung.
map_results	x	x	Mapping für Queryresultate.
report_type	x	x	Report-Renderer-Auswahl.
refresh_on	x	x	Neuladen bei Ereignissen/Feldänderungen.
double_click_action	x		Klassische Listenaktion.
menu	x	x	Navigation/Legacy-Menüeinbindung.
show_menu	x	x	Sichtbarkeit von Menüeinträgen.
context_menu	x	x	Kontextmenüs.
portlet_menu	x		Microclient-/Portlet-Menüs.
button_ids	x		Klassische Dialogbuttons.
buttons	x	x	Spezialbuttons, je nach Renderer.
action	x	x	URL, Controller- oder Client-Aktion.
attachments	x	x	Anhänge/Zusatzdokumente.
references	x	x	Verknüpfte Objekte.
list_versions	x	x	Versionsanzeige.
acl	x	x	Rollen-/ACL-Beschränkung.
insert_grp	x	x	Berechtigung für Anlage/Import.
read_only_disabled	x	x	Readonly-Sonderlogik.
show_subscription	x	x	Abonnements/Benachrichtigungen.
notify_on_save	x	x	Benachrichtigung nach Speichern.
debug / debug0	x	x	Debug-Sonderlogik.
import_dialog	x		Klassischer Importdialog.
import_excel	x	x	Excel-Import-Konfiguration.
database_connection	x	x	Import-/Report-Verbindungen.
controller	x	x	Spezialcontroller.
mode	x	x	Renderer-/Import-/Reportmodus.
constants	x	x	Template-/Controller-Konstanten.
variables	x	x	Template-/Controller-Variablen.
keyinfo_query	x	x	Kontextinformationen per Query.
keyinfo_dql	x	x	Kontextinformationen per DQL.
keyinfo_function	x	x	Kontextinformationen per Funktion.
folder_mask	x	x	Ordner-/Importkontext.
filename_field	x	x	Dateiname/Exportname.
has_obj_name	x	x	Hinweis für Objektname-Logik.
center_on	x		Fokus/Zentrierung in klassischen Listen.
layout	x	x	Layoutvariante in Spezialseiten.
style	x	x	Stilvariante in Spezialseiten.

Feld- und Spalteneigenschaften

Eigenschaft	microclient	webui	Hinweis
id	x	x	Feld- oder Spalten-ID.
label	x	x	Sichtbarer Text.
type	x	x	Renderer/Datentyp.
value	x	x	Default oder statischer Wert.
read_only	x	x	Sperrt Bearbeitung.
hidden	x	x	Technisch vorhanden, nicht sichtbar.
display_only	x	x	Nur Anzeige, keine persistente Eingabe.
external_only	x	x	Nicht direkt in der Maske gespeichert.
required / min	x	x	Pflichtfeld/Validierung.
max	x	x	Maximalwert/-länge.
length	x	x	technische/UI-nahe Länge.
tab_id	x	x	Tab-Zuordnung.
field_size	x	x	Formularbreite.
width	x	x	Feld-/Spaltenbreite.
height	x	x	Feldhöhe.
new_line	x	x	Layoutumbruch.
hide_label	x	x	Label ausblenden.
invisible_label	x	x	Labelplatz ohne sichtbares Label.
label_orientation	x	x	Labelausrichtung.
label_spacing	x	x	Labelabstand.
group_title	x	x	Gruppentitel.
group_description	x	x	Gruppenbeschreibung.
group_column	x	x	Gruppenspalte.
group_pair	x	x	Paarweise Anordnung.
fieldset	x	x	Fieldset-/Rahmenzuordnung.
render_zone		x	WebUI-Spezialrenderer.
draw_line	x	x	Trennlinie.
style	x	x	Inline-/Renderer-Stil.
background_color	x	x	Hintergrundfarbe.
hide_on_mobile		x	Mobile WebUI.
keywords	x	x	Werteliste.
keywords_only	x	x	Nur Wertelistenwerte zulassen.
keyword	x	x	Legacy-/Alternativwerteliste.
combo	x	x	Suchoperatoren.
value_assistance	x	x	Value Assistance.
value_assistance_properties	x	x	Mapping aus Value Assistance.
select2		x	WebUI-Select2-Verhalten.
multivalue	x	x	Mehrwertfeld.
multi_value	x	x	Historische Alternative.
keywords_separator	x	x	Trenner für Mehrwerte.
translate	x	x	Übersetzung von Werten/Labels.
add_wildcard	x	x	Such-/Value-Assistance-Wildcards.
searchable	x	x	Such-/Tabellenfeld.
filter	x	x	Spalten-/Tabellenfilter.
priority		x	Fallback-Spalten in generischen WebUI-Tabellen.
result_width	x	x	Spaltenbreite generierter Result-Columns.
label_template	x	x	Spalten-/Suchresultat-Template.
click	x	x	Klickaktion.
actions	x	x	Feld-/Spaltenaktionen.
validation_type	x	x	Formularvalidierung.
change_script	x		Klassische Feldänderungslogik.
change	x	x	Feldänderungskonfiguration.
focus	x	x	Initialfokus.
placeholder	x	x	Platzhaltertext.
tooltip	x	x	Tooltip/Hilfe.
info	x	x	Zusatzinformation.
exec_sum	x	x	Summen-/Berechnungslogik.
make_paths	x	x	Pfadgenerierung.
wysiwyg	x	x	Rich-Text-Editor, je nach Renderer.
rows	x	x	Zeilenanzahl.
acl	x	x	Feld-/Spalten-ACL.
tab_off	x	x	Feld/Tab deaktivieren.

table-Eigenschaften

Eigenschaft	microclient	webui	Hinweis
enabled		x	Aktiviert generische WebUI-Profil-Tabelle.
id		x	HTML-/DataTable-ID.
title		x	Seitentitel.
route		x	Tabellenroute.
details_route / detail_route		x	Detail-/Editroute.
edit_mode		x	Modal/Detail-Editiermodus.
server_side		x	Serverseitiges Paging/Suchen/Sortieren.
order_by		x	DQL-Sortierung.
row_template		x	Eigene Row-Darstellung.
detail_modal_base		x	Basis-Template für Modal-Details.
allow_add_item		x	Add-Button.
fixed_filters		x	Permanente Tabellenfilter.
result_columns		x	Tabellenspalten.
search		x	Suchkonfiguration.
placement		x	Admin-/Invoice-Admin-Einordnung.
filters		x	Erweiterte Filterkonfiguration.
search.enabled		x	Aktiviert Suche.
search.fields		x	Suchfelder.
placement.area		x	Hauptbereich.
placement.section		x	Gruppe/Sektion.
placement.navigation		x	Navigationsschlüssel.
placement.menu_label		x	Menülabel.
placement.icon		x	Icon.
placement.order		x	Sortierung.
placement.acl		x	Rollenbeschränkung.
placement.group_title		x	Gruppentitel.
placement.group_order		x	Gruppenreihenfolge.
placement.group_icon		x	Gruppenicon.

profile_type

profile_type entscheidet, in welchem Kontext ein Profil gefunden wird.

Wert	Bedeutung
insert	Profil darf für Neuanlage oder Import verwendet werden.
view	Profil darf für Detailanzeige verwendet werden.
search	Profil ist Suchprofil. Kann automatisch aus view erzeugt werden.
table	Profil beschreibt eine tabellarische Stammdaten- oder Admin-Ansicht.
internal	Internes Profil. Oft für technische Tabellen, Admin-Objekte oder Systemprozesse.
folder	Ordnerprofil. Wird bei Ordnerimporten oder Baumstrukturen verwendet.

Ein Profil kann mehrere Typen haben:

profile_type: ["insert", "internal", "view"]

Bei getProfileById(profile_id, profile_type='view') wird nur ein Profil gefunden, dessen profile_type view enthält. Darum kann dieselbe id mehrfach existieren, zum Beispiel einmal als view und einmal als search.

mask und obj_profile

mask ist der technische Speicherort. id ist die fachliche Sicht.

Beispiel:

id: cq_acc_invoice
mask: ["obj_accounting", "object"]

Das bedeutet:

• Die Objekte werden technisch auf den Aspekten obj_accounting und object gespeichert.
• Fachlich werden sie als Profil cq_acc_invoice behandelt.
• In vielen Tabellen wird zusätzlich nach obj_profile='cq_acc_invoice' gefiltert, wenn der Aspekt ein Feld obj_profile besitzt.

Bei Tabellenprofilen ist id häufig identisch mit mask, zum Beispiel obj_table_invoice_currency. Bei Dokumentprofilen ist das oft nicht der Fall.

Vererbung mit inherit

inherit erlaubt, ein bestehendes Profil als Basis zu verwenden:

profiles:
  - id: cq_acc_invoice_custom
    inherit: cq_acc_invoice
    profile_type: ["view"]
    label: Custom Invoice
    fields:
      - id: cq_custom_field
        label: Custom Field

Wirkung:

• Das Elternprofil wird kopiert.
• Felder und Listen mit gleicher id werden aktualisiert.
• Neue Felder werden angehängt.
• Normale Werte wie label, mask, properties_dialog werden überschrieben.

Wenn inherit auf eine Liste zeigt, werden mehrere Profile nacheinander gemerged. Wenn kein Profil mit passender id und passendem profile_type existiert, bricht die Konfiguration mit einem Fehler ab.

fields

fields ist die wichtigste Liste innerhalb eines Profils. Jeder Eintrag beschreibt ein Feld im Formular, in der Suche, in Tabellen oder für technische Verarbeitung.

Basis-Eigenschaften

Eigenschaft	Wirkung
id	Feld-ID. Muss zur technischen Maske passen, außer bei external_only oder display_only.
label	Sichtbarer Feldname. Wird in Formularen, Tabellen und Suchmasken angezeigt.
type	Feldtyp oder UI-Renderer, zum Beispiel string, text, date, timestamp, select, multiselect, textarea, checkbox, number.
value	Defaultwert oder statischer Wert. In automatisch erzeugten Search-Profilen wird value meist entfernt.
read_only	Feld ist nicht editierbar.
hidden	Feld wird nicht sichtbar angezeigt, bleibt aber technisch Teil des Profils.
display_only	Feld existiert nur für Anzeigezwecke und wird als read-only Property erzeugt.
external_only	Feld kommt nicht aus der Maske, wird aber als Profileigenschaft in Dialogen/Flows bereitgestellt.
required / min	Pflicht-/Validierungslogik. In den gewachsenen Konfigurationen wird häufig min: 1 als Pflichtfeld genutzt.
max	Maximalwert oder maximale Länge, je nach Renderer.
length	Technische oder UI-nahe Länge.

Layout-Eigenschaften

Eigenschaft	Wirkung
tab_id	Tab, in dem das Feld angezeigt wird. Muss zu tab_ids oder invoice_tab_ids passen.
field_size	Breite im Formular. Häufig small, mid, large, full.
width	Direkte Breitenangabe für spezielle Renderer.
height	Höhe für Textareas, WYSIWYG-Felder oder Spezialfelder.
new_line	Beginnt eine neue Zeile im Formularlayout.
hide_label	Blendet das Label aus.
invisible_label	Reserviert ggf. Labelplatz, ohne sichtbares Label.
label_orientation	Ausrichtung des Labels.
label_spacing	Abstand zwischen Label und Feld.
group_title	Gruppentitel im Formular.
group_description	Beschreibung einer Feldgruppe.
group_column	Gruppierung/Spaltensteuerung.
group_pair	Paarweise Anordnung von Feldern.
fieldset	Fieldset-/Rahmenzuordnung.
render_zone	Zielbereich für Spezialrenderer.
draw_line	Visuelle Trennlinie.
style	Inline- oder Renderer-Stil.
background_color	Hintergrundfarbe, sofern vom Renderer unterstützt.
hide_on_mobile	Feld auf mobilen Ansichten ausblenden.

Auswahl und Value Assistance

Eigenschaft	Wirkung
keywords	Statische Werte oder URL/DQL-basierte Werteliste.
keywords_only	Nur Werte aus keywords zulassen.
keyword	Historische oder alternative Einzelwert-Konfiguration.
combo	Suchoperatoren in Search-Profilen, zum Beispiel enthält/gleich.
value_assistance	Verweist auf eine konfigurierte Value Assistance.
value_assistance_properties	Mapping zwischen Auswahlwerten und Zielfeldern.
select2	Aktiviert Select2-ähnliches UI-Verhalten.
multivalue	Technisches Multivalue-Feld. Werte werden zusätzlich in <aspect>_multivalue gespeichert.
multi_value	Historische/alternative Schreibweise. Wenn möglich multivalue verwenden.
keywords_separator	Trenner für mehrwertige Keyword-Darstellung.
translate	Werte oder Labels übersetzen.
add_wildcard	Fügt bei Suche oder Value Assistance Wildcards hinzu.

Suche und Tabellenverhalten

Eigenschaft	Wirkung
searchable	Feld darf in globaler Tabellen-/Reportsuche verwendet werden.
filter	Filtertyp für Tabellen, zum Beispiel select oder multiselect.
priority	Feld kann als Fallback-Spalte in generischen Tabellen verwendet werden.
result_width	Breite der automatisch erzeugten Result-Column in Search-Profilen.
label_template	Template für Spalten-/Suchergebnisdarstellung.
click	Klickaktion auf Feld oder Tabellenspalte.
actions	Feldbezogene Aktionen.

Validierung und dynamisches Verhalten

Eigenschaft	Wirkung
validation_type	Validierungsart, wenn vom Formularrenderer unterstützt.
change_script	Script bei Feldänderung.
change	Alternative oder ältere Änderungskonfiguration.
focus	Feld erhält initialen Fokus oder dient als Fokusziel.
placeholder	Platzhaltertext im Eingabefeld.
tooltip	Hilfetext/Tooltip.
info	Zusatzinformation im Formular.
exec_sum	Summen-/Berechnungslogik in Spezialmasken.
make_paths	Pfadgenerierung oder Pfadlogik in Dokument-/Folder-Profilen.
wysiwyg	Aktiviert Rich-Text-Editor.
rows	Zeilenanzahl für Textareas oder Tabellenfelder.

Sicherheit auf Feldebene

Eigenschaft	Wirkung
acl	Feld nur für bestimmte Rollen/Gruppen anzeigen oder editieren, sofern der Renderer das prüft.
tab_off	Feld oder Tab abhängig von Kontext deaktivieren.
read_only	Wichtigste Feldsperre. Kann zusätzlich von Workflow- oder Rechte-Logik überschrieben werden.

Beobachtete Legacy-/Tippfehler-Keys

In den gewachsenen Konfigurationen kommen auch Tippfehler oder historische Varianten vor, zum Beispiel:

• lable statt label
• filed_size statt field_size
• keywordd statt keywords

Diese Keys sollten nicht neu verwendet werden. Wenn sie in einer bestehenden Kundenkonfiguration vorkommen, muss vor dem Aufräumen geprüft werden, ob Speziallogik sie auswertet oder ob sie wirkungslos sind.

result_columns

result_columns beschreibt Spalten in Trefferlisten, Reports und Tabellen.

result_columns:
  - id: obj_date
    label: Date
    type: date
    width: 120px
    searchable: true

Eigenschaft	Wirkung
id	Feld-ID oder Sonderspalte wie _checkbox oder _actions.
label	Spaltenüberschrift.
type	Renderer/Formatierung, zum Beispiel date, timestamp, amount.
width	Spaltenbreite.
searchable	Darf in der globalen Tabellensuche verwendet werden.
filter	Spaltenfiltertyp.
multivalue	Kennzeichnet Multivalue-Spalten. Relevant für Suche und Filter.
label_template	Template zur Darstellung des Werts.
click / action	Klick- oder Zeilenaktion, wenn vom Row-Template unterstützt.

Wenn keine result_columns definiert sind, versuchen generische Tabellen eine Fallback-Auswahl:

1. table.result_columns
2. profile.result_columns
3. Felder mit priority
4. Standardfelder wie obj_name, obj_title, obj_description, obj_status, obj_modified, obj_modifier

table

table ist die neuere Konfiguration für generische Profil-Tabellen, insbesondere /webui/profile_table?profile_id=....

table:
  enabled: true
  route: /webui/profile_table?profile_id=obj_user
  details_route: /webui/profile_details?profile_id=obj_user
  edit_mode: modal
  server_side: true
  order_by: Aobj_user_id
  result_columns:
    - id: obj_login_name
      label: Login Name
      searchable: true
  search:
    enabled: true
    fields:
      - obj_login_name
      - obj_email
  placement:
    area: admin
    section: users
    navigation: admin.users
    menu_label: User Management
    icon: users
    order: 100
    acl: ["rolle_Administrator"]

Eigenschaft	Wirkung
enabled	Aktiviert die generische Tabellenansicht.
id	HTML-/DataTable-ID. Wenn nicht gesetzt, wird sie aus der Profil-ID abgeleitet.
title	Seitentitel für die Tabelle.
route	URL zur Tabellenansicht. Empfohlen ist /webui/profile_table?profile_id=<profile>.
details_route / detail_route	Ziel für Detail-/Editansicht.
edit_mode	Bearbeitungsmodus, häufig modal.
server_side	Serverseitiges Paging/Suchen/Sortieren. Wichtig bei großen Tabellen.
order_by	DQL-Sortierung. In DQL keine SQL-DESC-Syntax verwenden, sondern bestehende Sortierpräfixe wie A.../D..., wo im Code unterstützt.
row_template	Eigenes Row-Template.
detail_modal_base	Basis-Template für Modal-Details.
allow_add_item	Steuert, ob der Add-Button angeboten wird.
fixed_filters	Feste Filter, die immer an die generierte DQL-Query angehängt werden.
result_columns	Spalten nur für diese Tabellenansicht. Überschreibt Profilebene.
search	Suchkonfiguration. Siehe unten.
placement	Einordnung in Admin-/Invoice-Admin-Menüs.
filters	Erweiterte Filterkonfiguration in einzelnen Profilen.

table.search

Eigenschaft	Wirkung
enabled	Aktiviert Suchfunktion.
fields	Feld-IDs, die in der globalen Suche berücksichtigt werden.

Wenn search.fields fehlt, nimmt die generische Tabelle alle Spalten mit searchable: true. Wenn auch das fehlt, werden textartige Felder als Fallback verwendet.

table.placement

placement beschreibt, wo ein Profil in Admin- oder Invoice-Admin-Übersichten erscheinen soll.

Eigenschaft	Wirkung
area	Hauptbereich, zum Beispiel admin oder invoice.
section	Gruppe innerhalb des Bereichs.
navigation	Logischer Navigationsschlüssel.
menu_label	Sichtbarer Menüname.
icon	Icon-ID, häufig Tabler/Lucide-kompatibel.
order	Sortierung innerhalb der Gruppe.
acl	Rollenbeschränkung für diesen Menüpunkt.
group_title	Gruppentitel in einigen Admin-Layouts.
group_order	Reihenfolge der Gruppe.
group_icon	Icon der Gruppe.

Report-Profile

Profile mit IDs wie report_* oder cq_*_report verwenden häufig zusätzliche Eigenschaften:

Eigenschaft	Wirkung
query	DQL/SQL-Grundquery.
columns / result_columns	Ergebnisdarstellung.
form	Filter-/Eingabeformular für den Report.
dql_template	DQL mit Platzhaltern.
params	Parameter für Query oder Template.
map_results	Mapping der Querywerte auf Anzeigenamen.
report_type	Auswahl eines Report-Renderers.
initial_search	Startfilter.

Reports sind historisch sehr flexibel. Vor Änderungen immer prüfen, welches Template oder welcher Controller das konkrete Report-Profil rendert.

Invoice-spezifische Profile

Invoice-Profile verwenden zusätzlich fachliche Felder und einige Invoice-spezifische Konventionen:

Konvention	Bedeutung
cq_acc_invoice*	Rechnungs-/Belegprofile für Kreditoren, Debitoren, Kreditkarten, Orders, PO usw.
obj_table_invoice_*	Invoice-Stammdaten- und Admin-Tabellen.
invoice_tab_ids	Tabs in den großen Invoice-Detailseiten.
cq_client_accounting	Mandanten-/Buchhaltungskreis. Viele Tabellen werden darüber automatisch eingeschränkt.
cq_doctype	Dokumenttyp innerhalb eines Invoice-Profils.
cq_currency, cq_amount_*, cq_tax_*	Rechnungsbeträge, Währung und Steuerlogik.
cq_accounting_area	Buchungs-/Kontierungsbereich.
obj_assignee*	Workflow-Zuweisungen.

Bei obj_table_invoice_* und obj_table_address fügt die generische Tabellenansicht mandantenbezogene Filter hinzu, wenn das Feld cq_client_accounting existiert und ein aktiver Mandant ausgewählt ist.

Multivalue-Felder

Ein Feld mit multivalue: true wird technisch speziell behandelt:

• Im Hauptaspekt liegt meist eine JSON-/Textrepräsentation.
• Zusätzlich existiert eine Tabelle <aspect>_multivalue mit einem Datensatz pro Einzelwert.
• DQL-Filter auf Multivalue-Felder müssen über EXISTS statt Join laufen, sonst werden Objekte mehrfach zurückgegeben.

Beispiel:

- id: obj_user_roles
  label: Roles
  multivalue: true
  searchable: true
  filter: multiselect

Beim Suchen nach Rollen darf ein User mit mehreren Rollen trotzdem nur einmal in der Trefferliste erscheinen. Deshalb ist Multivalue-Suche ein sensibler Bereich.

URLs und empfohlene Links

Für neue generische Tabellenlinks bevorzugen:

/webui/profile_table?profile_id=<profile_id>

Für Details:

/webui/profile_details?profile_id=<profile_id>&id=<obj_id>

Historische Routen wie /admin/users können weiter existieren, sollten aber für neue Admin-/Invoice-Admin-Links möglichst durch Profil-URLs ersetzt werden, wenn die generische Tabelle das Profil vollständig abbildet.

Häufige Fehlerquellen

Gleiche id mehrfach

Mehrere Profile mit gleicher id sind erlaubt, wenn sie unterschiedliche profile_type haben. Problematisch wird es, wenn dieselbe id und derselbe profile_type mehrfach geladen werden. Dann hängt das Ergebnis von Lade- und Merge-Reihenfolge ab.

mask passt nicht zu fields

Jedes normale Feld muss in der technischen Maske existieren. Ausnahmen sind external_only und display_only. Wenn ein Feld nicht existiert, taucht es im generischen Formular nicht wie erwartet auf oder verursacht Fehler.

tab_id ohne passenden Tab

Wenn ein Feld tab_id: accounting hat, aber tab_ids diesen Tab nicht enthält, kann das Feld je nach Renderer verschwinden oder in einem Fallback landen.

searchable auf Multivalue-Feldern

Multivalue-Felder in der globalen Suche müssen korrekt durch DQL behandelt werden. Bei Funktionswrappern wie lower(obj_user_roles) muss die Query weiterhin über EXISTS laufen, nicht über einen Join.

Tippfehler in Keys

lable, filed_size oder keywordd sehen harmlos aus, werden aber von Standardrenderern normalerweise nicht verstanden. Solche Keys sind Kandidaten für Bereinigung, aber nur nach Prüfung der betroffenen Custom-Logik.

Zu viel Logik im Profil

Profile sollten Struktur und UI-Verhalten definieren. Wenn Fachlogik zu komplex wird, sollte sie in Controller, Value Assistance, Extension oder Service-Code ausgelagert werden.

Praktische Checkliste für neue Profile

1. id, label, profile_type und mask definieren.
2. Prüfen, ob alle fields.id technisch in der Maske existieren oder bewusst external_only/display_only sind.
3. Tabs mit tab_ids oder invoice_tab_ids definieren und jedes sichtbare Feld einem sinnvollen tab_id zuordnen.
4. Für Tabellen table.enabled, route, details_route, result_columns, search.fields und order_by setzen.
5. Für Admin-/Invoice-Admin-Anzeige table.placement ergänzen.
6. Bei Mandantenbezug cq_client_accounting bewusst setzen und prüfen, ob automatische Filter greifen sollen.
7. Multivalue-Felder nur dann searchable setzen, wenn die Suche fachlich gewünscht ist.
8. Keine neuen Legacy-Schreibweisen verwenden.
9. UI-Labels in Englisch pflegen und bei sichtbaren Texten Übersetzungen ergänzen.

Gescannte Quellen

Der Scan umfasste:

• config/**/*.yaml
• apps/invoice/**/*.yaml
• C:\Users\danie\IdeaProjects\centraquestCustom/**/*.yaml

Dabei wurden über 500 YAML-Dateien mit profiles: und über 1'000 Profileinträge gefunden. Die häufigsten Top-Level-Keys waren unter anderem label, fields, profile_type, mask, icon, result_columns, insert_grp, tab_ids, visible_tabs, menu, table, properties_dialog und inherit.

Diese Referenz beschreibt die derzeit beobachtete Praxis. Einzelne Kundenprofile können zusätzliche Spezialkeys enthalten, die nur durch kundenspezifische Templates oder Controller ausgewertet werden.