Datenreferenzen

Datenreferenzen definieren die "Datenbeschaffung" für Kombinationsfelder oder Auswahllisten. Datenreferenzen sind kein Metadatenobjekt, dass an einen Oberflächen-Element gebunden werden kann, sondern sie werden Datenfeldern zugeordnet. Datenreferenzen können folgenden Datenfeldern zugeordnet werden:

Datenquellenfelder (Anzeige in der Filterzeile und in den Feldern im Dialog "Datensätze wählen"
Datensatzfelder
Datenstrukturfelder

Eigenschaften Datenreferenz

Bereich	Eigenschaft	Wert
Allgemeines	Name (Name)	Name der Datenreferenz
	Titel (wird aktuell nicht verwendet) (Title)	Titel der Datenreferenz
	Schlüsselfeld (KeyFieldName)	Feldname aus der Feldliste der Datenreferenz Hinweis: der Inhalt dieses Feldes wird nach Auswahl in das Element (Daten-Edit-Element, Selektionsdialog etc.) übernommen.
	Auswahl erforderlich? (IsSelectionMandatory)	Es ist eine Auswahl erforderlich. Hierzu wird – je nach Einsatzzweck – dort ein Vorbelegungswert definiert. Ist kein Vorbelegungswert definiert, wird automatisch der erste Wert der Liste vorbelegt. Die Auswahl kann nicht gelöscht werden. Beim Einsatz in Datenstrukturen und Datensätzen gilt jeweils das dortige Attribut „Pflichtfeld?“.
	Freie Eingabe erlaubt? (IsExtensible)	Ist eine freie Eingabe erlaubt?
	Kommentar (Comment)	Beliebiger Kommentar zur Dokumentation. Der Kommentar wird nicht zum Client übertragen und dient nur zur Dokumentation von Besonderheiten, Hinweisen, etc. Bei Auslieferung/Weitergabe der Lösung wird der Kommentar eingeschlossen, so dass der Empfänger ihn im AppDesigner sieht.
SQL	globale Datenbank verwenden? (UseGlobalDatabase)	Soll die globale Datenbank (anstelle der Mandanten-Datenbank) verwendet werden?
	SQL-Tabellen (Tables)	Tabelle(n) (Komma-separiert) oder komplette JOIN inkl. ON (ist „SQL-Tabellen“ leer, erfolgt keine SQL-Abfrage und es wird nur eine leere Datenquelle mit den definierten Datenfeldern aufgebaut. Das Füllen der Datenquelle muss in diesem Fall von einem Geschäftsprozess übernommen werden)
	SQL-Distinct verwenden? (UseDistinct)	Soll die Abfrage als SQL-DISTINCT ausgeführt werden. Bei der Verwendung ist die Performance zu prüfen. Bei Memo-Feldern ist "ja" nicht zulässig.
	SQL-Where-Bedingung (WhereClause)	SQL-Where der Abfrage. Muss leer sein, wenn "SQL-Tabellen" leer ist.
	SQL-Gruppierung (GroupBy)	SQL-Group By der Abfrage. Muss leer sein, wenn "SQL-Tabellen" leer ist.
	Sortieren nach Feld (SortFieldName)	Name des Feldes für die Sortierung. Muss leer sein, wenn "SQL-Tabellen" leer ist.
	Ergänzende Sortierung (AdditionalOrder)	Ergänzende Sortieranweisung in Form einer Liste (wird automatisch an die bei den einzelnen Feldern definierte Sortierung angehängt, um immer gleichlautende Unter-Sortierungen nicht bei jedem Feld angeben zu müssen; doppelte Sortierungen werden entfernt, wenn das Sortierfeld des Feldes bereits ein solches Sortier-Kriterium besitzt): angegeben werden jeweils Feldname der Datenreferenz (d.h. ein Feld-Verweis; „Name“) und „ASC“ bzw. „DESC“ für aufsteigende bzw. absteigende Sortierung (nachfolgende Felder definieren jeweils Untersortierungen; „Direction“) im Beispiel „f1;ASC;f2;DESC“ wird zunächst nach Feld „f1“, danach nach Feld „f2“ sortiert soll ein Feld, das für die Sortierung benötigt wird, ausschließlich hierfür benutzt werden und nicht angezeigt werden, ist es mit „IsInternal“ zu markieren wenn leer, ist keine Sortierung der Spalte möglich Achtung: Da der SQL-Datentyp Text nicht sortiert werden kann, muss der Inhalt eines solchen Feldes bei Bedarf mit „CONVERT(varchar(max), feldname)“ explizit konvertiert werden, was allerdings Performance-relevant ist
Geschäftsprozess	Geschäftsprozess (BusinessProcessPartnerId, BusinessProcessPackageId, BusinessProcessName)	Partner-Kennung, Lösungs-Kennung und Name des Geschäftsprozesses
	SQL-Sortierung vor Geschäftsprozess-Aufruf? (BusinessProcessOrderBefore)	SQL-Order-String, der anstelle des normalen Order-Strings bei der ersten Ermittlung der Daten verwendet wird, um eine definierte Sortierung für den Geschäftsprozess zu gewährleisten. Hinweis: In diesem Fall werden intern immer alle Datensätze vom SQL-Server geladen, was bei großen Datenbeständen zu Performance- und ApplikationServer-Speicher-Problemen führen kann. Die Anwendung dieser Einstellung sollte daher speziellen Fällen vorbehalten bleiben.
	Geschäftsprozess-Parameter (BusinessProcessParameters)	Parameterliste für parametergesteuerte Geschäftsprozesse mit folgenden Werten: "Parametername": Parametername des durch „Geschäftsprozess“ referenzierten vordefinierten parametergesteuerten Geschäftsprozesses "Parameterwert": Wert oder Feldname des jeweiligen Parameters
Lizenzierung	Lizenz-Kürzel (LicenseTokens)	Applikationskürzel der zu prüfenden Lizenz (nur in Nicht-Sage-Lösungen verwendbar und änderbar)
	Lizenz-Kürzel für Sage (SageLicenseTokens)	Applikationskürzel der zu prüfenden Lizenz (nur in Sage-Lösungen verwendbar und änderbar)

Eigenschaften Datenreferenzfelder

Bereich

Eigenschaft

Wert

Allgemeines

Feldname

(Name)

Eindeutiger Feldname (muss eine korrekte SQL-Feldbezeichnung sein, da der Wert direkt für den Alias-Namen der SQL-Abfrage benutzt wird).

Feldtitel

(Title)

Titel des Feldes

Priorität

(Precedence)

Priorität des Datenfeldes zur Festlegung der Spaltenreihenfolge

0 = keine Priorität und damit keine Anzeige im Client (z.B. für den Schlüssel eines Kombinationsfeldes)
1 bis n = aufsteigende Priorität (1 ist die höchste Priorität)

internes Feld?

(IsInternal)

Datenfeld ermitteln, aber nicht nach außen geben (d.h. nur AppServer-seitig vorhanden. Falls das Feld nur als Schlüssel oder für die Sortierung genutzt werden soll).

berechnetes Feld?

(IsFieldCalculated)

Für Geschäftsprozess-Datenermittlung (bei vordefinierten parametergesteuerten Geschäftsprozessen wird dieser Wert in der Definition des Geschäftsprozesses festgelegt).

Datenfeld wird berechnet, daher werden die Datensätze

erst nach der Berechnung sortiert, wenn nach diesem Feld sortiert wird,
nach der Berechnung nochmals gefiltert, wenn nach diesem Feld gefiltert wird, und
es werden alle Datensätze ermittelt und nach der Berechnung, ggf. abgeschnitten, wenn nach diesem Feld gefiltert wird oder dieses Feld in der Summenzeile vorkommt.

Hinweis: In diesem Fall werden (sobald der Anwender nach dem Feld filtert oder sortiert) intern immer alle Datensätze vom SQL-Server geladen, was bei großen Datenbeständen zu Performance- und ApplikationServer-Speicher-Problemen führen kann. Besser ist daher die SQL-Server-seitige Berechnung. Alternativ kann das Feld auch nicht für Sortierung und Filterung angeboten werden.

Ausrichtung

(Alignment)

Ausrichtung:

0 = linksbündig
1 = rechtsbündig
2 = mittig

Bei Sage wird die Ausrichtung in Abhängigkeit des Datentypes gewählt:

1 bei Integer und Decimal
sonst 0

SQL

SQL-Abfrage

(SqlQuery)

SQL-Abfrage für das Feld (im einfachsten Fall der Feldname der Tabelle).

Bei Abfragen mehrerer Tabellen muss der Tabellenname vorangestellt werden. Unterabfragen sind möglich, Alias darf hier nicht angegeben werden, da dafür „Feldname“ verwendet wird.

Muss leer sein, wenn „SQL-Tabellen“ der Datenquelle auch leer ist, ansonsten erforderlich (das Füllen der Datenquelle wird dann von einem Geschäftsprozess übernommen).

Datentyp

(DataType)

Datentyp:

1 = Boolean
2 = Integer
3 = Decimal
4 = Date
5 = String
6 = DateTime
15 = indizierter String
16 = indiziertes Bild

Datentyp-Ergänzung

(DataTypeIndexedInfos)

Liste mit Schlüssel sowie mit „LösungsId“, „PartnerId“, „Name“ und „Id“ zur Referenzierung eines Strings aus „Grundlagen/ Strings“.

Bei „Datentyp“ = "indizierter String": Mit Index = Wert des Datenquellenfeldes

Bei „Datentyp“ = "indiziertes Bild": Mit Index = Wert des Datenquellenfeldes und Wert = Verweis auf ein Bild in „Shared\Bitmaps\UI“, Dateinamen ohne Erweiterung, Standard ist automatisch hier ".png"

Nachkommastellen

(DecimalPlaces)

Anzahl Nachkommastellen oder variable Anzahl (d.h. Nachkomma-Nullen ausblenden)

für mehr als 4 Nachkommastellen ist der Datentyp "FLOAT" in der SQL-Datenbank erforderlich

Sortierung

(Order)

Sortieranweisung in Form einer Liste:

angegeben werden jeweils Feldname der Datenreferenz (d.h. ein Feld-Verweis; „Name“) und „ASC“ bzw. „DESC“ für aufsteigende bzw. absteigende Sortierung (nachfolgende Felder definieren jeweils Untersortierungen; „Direction“)
im Beispiel „f1;ASC;f2;DESC“ wird zunächst nach Feld „f1“, danach nach Feld „f2“ sortiert
soll ein Feld, das für die Sortierung benötigt wird, ausschließlich hierfür benutzt werden und nicht angezeigt werden, ist es mit „IsInternal“ zu markieren
wenn leer, ist keine Sortierung der Spalte möglich

Achtung: Da der SQL-Datentyp Text nicht sortiert werden kann, muss der Inhalt eines solchen Feldes bei Bedarf mit „CONVERT(varchar(max), feldname)“ explizit konvertiert werden, was allerdings Performance-relevant ist

Datenreferenz-Typen

Es gibt die folgenden Typen von Datenreferenzen:

Statische Datenreferenzen

Das ist der einfachste Fall einer Datenreferenz (die Daten werden mittels SQL oder mit einem hinterlegten Geschäftsprozess ermittelt).

Dieser Typ ermittelt beim Laden eines Elementes seine Einträge. Diese sind während der "Laufzeit" des Elementes konstant, also unabhängig von eingegebenen Daten.

Zu hinterlegende Metadaten-Eigenschaften für ein Datenquellen-, Datenstruktur- oder Datensatzfeld (bei Datenquellen gibt es nur die Eigenschaft "Datenreferenz"):

Gefilterte Datenreferenz

Die gefilterte Datenreferenz hat als Grundlage eine statische Datenreferenz, dessen SQL in der WHERE-Bedingung durch den Filter erweitert wird. Technisch gesehen ermittelt dieser Datenreferenz-Typ die Einträge der Auswahlliste nur beim Anzeigen der Auswahlliste, ein "Vorab"-Laden beim Laden des Elementes erfolgt nicht.

Dieser Typ findet sinnvollerweise Verwendung, wenn man die Einträge durch einfache WHERE-Bedingungen im SQL filtern kann. Hierbei ist zu beachten, dass die Syntax hier kein natives SQL, sondern "SData Query Language" ist (siehe hierzu "http://sage.github.io/SData-2.0/").

Zu hinterlegende Metadaten-Eigenschaften für ein Datenstruktur- oder Datensatzfeld:

Folgende Eigenschaften sind einzugeben:

Die statische Datenreferenz angeben in der Eigenschaft "Datenreferenz".
Den Filter (sinngemäß eine WHERE-Bedingung eines SQL) angeben in der Eigenschaft "Datenreferenz-Filter".
In den "Datenreferenz-Info-Feldern" die Felder angeben, die die die Anzeigewerte enthalten (da beim initialen Anzeigen der Werte ja noch keine Einträge in der Auswahlliste vorhanden sind):

Dynamische gefilterte Datenreferenz

Die dynamische gefilterte Datenreferenz hat als Grundlage eine statische Datenreferenz dessen Einträge durch einen Aufruf in eine .Net-Klassen gefiltert werden können. Die zugrunde liegende statische Datenreferenz wird beim Laden des Parts ausgeführt und beim Anzeigen der Auswahlliste wird die Funktion "Execute" der hinterlegten .Net-Klasse ausgeführt.

Dieser Typ findet sinnvollerweise Verwendung, wenn man die Einträge filtern möchte, dies aber nicht durch eine einfache SQL-ähnliche Anweisung machbar ist.

Zu hinterlegende Metadaten-Eigenschaften für ein Datenstruktur- oder Datensatzfeld:

Folgende Eigenschaften sind einzugeben:

Die statische Datenreferenz angeben in der Eigenschaft "Datenreferenz".
Den Namen der DLL der .Net-Klasse hinterlegen.
Den Namen der Klasse hinterlegen. Diese Klasse muss von der Klasse "DataReferenceProcessBase" ableiten und mindestens die Funktion "Execute" überschreiben (dort werden die Werte der dynamischen Datenreferenz ermittelt und als Variable vom Typ "NamedParameters" zurückgegeben). Bei der Übergabe der Parameter aus der Oberfläche in die Funktion "Execute" enthalten die NamedParameter als Name den Namen des Anzeigefeldes (also z.B. "Bearbeiter") und als Wert den Anzeigewert und als Datatype-Eigenschaft erhält man den Datentyp. Die Rückgabe muss die Einträge des Schlüsselfeldes der statischen Datenreferenz enthalten.
Die Datenreferenz-Parameter hinterlegen. Diese werden der "Execute"-Funktion der o.g. Klasse übergeben, die sie dann auswerten kann. Diese Parameter verweisen auf Felder der Datenstruktur oder des Datensatzes.

Die Filterung erfolgt vom Client aus, nachdem die Daten zuerst komplett eingelesen und über das Web verschickt wurden.
Dies kann zu gravierenden Performance Problemen führen.

Hinweis für Developer Partner

WDB-Eintrag 203334:

Dokument Zusatzdokumentation zum Wiki für Developer Partner, DataReferenceProcessBase

Dynamische Datenreferenz

Die dynamische Datenreferenz ist die flexibelste Verwendung von Datenreferenzen, da diese ihre Einträge frei gestalten und anhand von aktuellen Anzeigewerten im Client filtern kann.

Folgende Eigenschaften sind anzulegen:

Anlage eines Geschäftsprozesses
Zuordnung des Geschäftsprozesses in der Datenreferenz
Die statische Datenreferenz angeben in der Eigenschaft "Datenreferenz".
In den "Datenreferenz-Info-Feldern" die Felder angeben, die die die Anzeigewerte enthalten (siehe hierzu auch obigen Abschnitt zu Gefilterten Datenreferenzen).
Die Parameter für den Geschäftsprozess hinterlegen (Eigenschaft "Datenreferenz-Parameter"). Diese Paramter sind im .Net-Code des Geschäftsprozesses als Property "ServiceParameters" der Basisklasse von Geschäftsprozessen "BusinessProcessBase" verfügbar.

Hinweis für Developer Partner

WDB-Eintrag 203334:

Dokument Zusatzdokumentation zum Wiki für Developer Partner, BusinessProcessBase

Gruppieren in der Auswahlliste

Es gibt Anwendungsfälle, da lassen sich die Einträge in Datenreferenzen nicht einfach alphabethisch sortieren, sondern müssen auch noch in Gruppen aufgeteilt werden. Ein Beispiel hierfür ist der Buchungstextvorschlag beim Anlegen einer Buchung. Hier gibt es 2 Teile, der erste Teil sind die letzten selbst eingegebenen Buchungstexte und der zweite Teil die Standard Buchungstexte.

Die Sortierung sieht ohne Trennstrich für den Anwender sehr verwirrend aus.

Technische Lösung: eine Trennlinie wird dort erzeugt, wo ein Datenreferenz-Eintrag mit leerem Eintrag vorliegt:

(SELECT CAST(Value AS VARCHAR(255)) AS Bezeichnung, '' AS Short, 1 AS Sort, Property FROM USysAppConfig WHERE Mandant = $[Mandant] AND UserName = $[UserName] AND App = $[ApplicationName] AND Token = 'Buchungserfassung' AND Resource = 'ediBuchungserfassung.Sage.Rewe' AND Property LIKE 'Buchungstext[1-4]'
UNION
SELECT null AS Bezeichnung, '' AS Short, 2 AS Sort, '' AS Property 
UNION
SELECT KHKGruppen.Bezeichnung AS Bezeichnung, KHKGruppen.Gruppe AS Short, 3 AS Sort, '' AS Property FROM KHKGruppen WHERE Mandant = 0 AND Typ = 10011) AS MyUnion
ORDER BY Sort, Property, Bezeichnung