Datenwert-Listen

Allgemeines

Name

(Name)

Name der Datenwert-Liste

Anhängen an Datenwertliste der Partner-Kennung

(AppendToPartnerId, AppendToPackageID)

Partner- und Lösungs-Kennung (bei Sage „Sage“) der gleichnamigen Datenwertliste, an die diese Definition angehängt werden soll;

Einsatzzwecke:

• Makro-Funktionen an Ereignisse der Datenwertliste bzw. deren Felder anhängen

• Felder an die Datenwertliste anhängen

Hinweis: Anhängen ist immer einstufig, Verkettungen sind nicht möglich

Titel

(Title)

Titel des Datenwert-Liste

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.

Ereignisse

(Makros)

Vor Änderung

(BeforeUpdate)

Makros, die vor Änderungen einer Datenwertliste (d.h. direkt vor dem Speichern) aufgerufen werden

• In in diesem Ereignis aufgerufenen Geschäftsprozessen (siehe Makro-Befehl "AufrufenDll") werden automatisch die neuen und alten Daten zur Verfügung gestellt.

• Rückgabe eines Cancel-Flags und einer Cancel-Meldung

• Server-seitige Ausführung innerhalb der Transaktion

Die Ereignisse werden auf Client- und Server-Seite ausgelöst (sinnvollerweise im Makro die Funktion „IsRunningOnServer“ verwenden, um nur auf dem Server auszuführen und Roundtrips zu vermeiden).

• Die Ereignisse können bei angehängten Datenwertlisten (siehe „AppendToPartnerId“ und „AppendToPackageId“) definiert werden, um zusätzliche Makros ausführen zu lassen. Die Ausführung der Makros erfolgt jeweils nach aufsteigenden Partner- und Lösungs-Ids mit Sage beginnend.

Nach Änderung

(AfterUpdate)

Makros, die nach dem Ändern einer Datenwertliste aufgerufen werden (Server-seitige Ausführung innerhalb der Transaktion)

Hinweis: Werden in der Datenwertliste Felder verwendet, die auf einer verbundenen Datenbank beruhen, werden diese erst nach der Transaktion aktualisiert, wobei das Ereignis "AfterUpdate" bereits am Ende der Transaktion ausgeführt wird.

Die Ereignisse werden auf Client- und Server-Seite ausgelöst (sinnvollerweise im Makro die Funktion „IsRunningOnServer“ verwenden, um nur auf dem Server auszuführen und Roundtrips zu vermeiden).

• Die Ereignisse können bei angehängten Datenwertlisten (siehe „AppendToPartnerId“ und „AppendToPackageId“) definiert werden, um zusätzliche Makros ausführen zu lassen. Die Ausführung der Makros erfolgt jeweils nach aufsteigenden Partner- und Lösungs-Ids mit Sage beginnend.

Vor Änderung durch API

(BeforeUpdateByApi)

(ab Version 9.0.4)

Makros, die vor Änderung und Neuanlage eines Datensatzes nach dem Setzen der Standard-Werte und vor der Feldvalidierung aufgerufen werden.

Der Zweck des Ereignisses ist es, Werte von Feldern zu setzen, die als Pflichtfelder definiert sind oder Daten-abhängig befüllt werden müssen, im zugehörigen API-Endpunkt jedoch nicht zur Verfügung gestellt werden.

• Die Funktion "IsRecordInsert" gibt im Makro an, ob es sich um einen neuen Datensatz handelt.

• In in diesem Ereignis aufgerufenen Geschäftsprozessen (siehe Makro-Befehl "AufrufenDll") werden automatisch die neuen und alten Daten zur Verfügung gestellt.

• Rückgabe eines Cancel-Flags und einer Cancel-Meldung.

Beispiel: Der API-Endpunkt für Kunden enthält zwar die Felder "Name" und "LieferOrt", zur Speicherung wird allerdings auch das Pflichtfeld "Matchcode" benötigt. Dieses kann im Makro gebildet werden.

Das Ereignis wird nicht auf Client- sondern nur Server-Seite ausgelöst, wenn das Speichern durch einen API-Aufruf initiiert wurde.

Lizensierung

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)

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, für Anwender nicht sichtbar)

Feldtitel

(Title)

Titel des Feldes (für Anwender sichtbar)

Feld-Attribute anhängen?

(DoAppendTo)

Sollen Eigenschaften an das gleichnamige Feld der in "Anhängen an..." referenzierten Datenwert-Liste angehängt werden?

Einsatzzweck:

• Makro-Funktionen an Ereignisse des Feldes anhängen

• Datenreferenz-Filter, Datenreferenz-Parameter und Datenklassen-Filter erweitern/anhängen

• Festlegen/Überschreiben von Eigenschaften von Standard und benutzerdefinierten Feldern (siehe Anhängen an…)

SQL

SQL-Tabelle

(Table)

Datentabelle

SQL-Abfrage

(SqlQuery)

SQL-Abfrage für Feld aus der Datentabelle (im einfachsten Fall Feldname der Tabelle; rein lesende Unterabfragen sind möglich; Alias darf hier nicht angegeben werden, da hier „Name“ verwendet wird);
die Update-Fähigkeit muss gewährleistet sein, d.h. bei allen nicht beschreibbaren Feldern muss das „IsReadOnly“-Attribut gesetzt werden)

Konvertierung SQL-Datentyp

(SqlDataTypeConversion)

Konvertierung des SQL-Datenwertes in den in "DataType" angegebenen Typ beim Lesen/Schreiben in/aus der SQL-Datenbank:

• 0 = Keine

• 1 = Konvertierung SQL-String

  • Datumswerte sind in deutschem Format gespeichert

  • Zahlenwerte sind mit Punkt als Dezimalzeichen gespeichert

Mandantenfeld

(MandantField)

Feldname des Mandaten-Feldes (die Primärschlüsselfelder und das Mandanten-Feld bilden automatisch die Where-Clause)

Primärschlüsselfelder

PrimaryKeyFields

Liste der Primärschlüsselfelder, besteht aus folgenden Feldern (die Primärschlüsselfelder und Mandanten-Felder bilden automatisch die Where-Clause):

• SQL-Feldname des Primärschlüsselfeldes

• Datentyp des Primärschlüsselfeldes:

  • 1 = Boolean

  • 2 = Int32

  • 3 = Decimal

  • 4 = Date

  • 5 = String

  • 6 = DateTime

  • 7 = Time

  • 8 = Duration

  • 23 = Currency

• Fester Wert für das Primärschlüsselfeld
  (Die Angabe eines Ausdrucks (muss mit "=" beginnen) ist zulässig, wobei dort kein Zugriff auf andere Felder erlaubt ist;
  hier ist als Ausdruck auch „GeschaeftsjahrClient“ zulässig;
  Datumswerte müssen im ISO-Format („yyyy-mm-dd“ bzw. „yyyy-mm-ddThh:mm:ss“) angegeben werden;
  Zahlen mit Nachkommastellen müssen Kultur-invariant angegeben werden, d.h. mit Punkt und nicht mit Komma)

Zusatzfelder

(AdditionalFields)

Liste der optionalen zusätzlichen Felder, besteht aus folgenden Feldern (werden bei Neuanlage und Updates zusätzlich gespeichert):

• SQL-Feldname des zusätzlichen Felds

• Datentyp des zusätzlichen Felds:

  • 1 = Boolean

  • 2 = Int32

  • 3 = Decimal

  • 4 = Date

  • 5 = String

  • 6 = DateTime

  • 7 = Time

  • 8 = Duration

  • 23 = Currency

• Fester Wert für das zusätzliche Feld

RowVersion-Feld

(RowVersionField)

Feldname des RowVersion-Feldes

Datentyp

Datentyp

(DataType)

Datentyp:

• 1 = Boolean

• 2 = Int32

• 3 = Decimal

• 4 = Date

• 5 = String

• 6 = DateTime

• 7 = Time

• 8 = Duration

• 7 = Time

• 8 = Duration

• 15 = indexed String

• 16 = indexed Image

• 23 = Currency

• 100 = Schlüssel 1 einer Data Class (zusätzlich sind ggf. Felder der Typen 101, 110, 111, 120 und 121 erforderlich: wird intern als Datentyp „String“ behandelt (z.B. in Makros), unabhängig vom konkreten Datentyp des Schlüssels in der Datenklassen-Definition bzw. der Datenbank)

• 101 = Matchcode für Schlüssel 1 einer Data Class

Datentyp 101 erfordert, dass ein Feld des Datentyps 100 vorhanden ist, das die gleiche Klasse referenziert;

Datenklassen mit mehreren Schlüsseln werden hier nicht unterstützt

Datentyp-Ergänzung

(DataTypeIndexedInfos)

Liste mit Key sowie mit "PackageId", "PartnerId", "Name" und "Id" zur Referenzierung eines Strings aus "StringResources.xml";

bei Datentyp 16 (indexed Image) zusätzlich:

• "Reference" als Verweis auf ein Bild in "Shared\Bitmaps\UI" (bei Datentyp 15 (indexed String) leer; „empty“ = leere Anzeige, d.h. kein Icon; Dateinamen ohne Erweiterung, Standard ist automatisch hier ".png")

Anzeigereihenfolge gemäß der Liste

Datenklasse

(DataClassPartnerId, DataClassPackageId, DataClassName)

Partner- und Lösungs-Kennung und Name der Datenklasse.

Datenklassen-Schlüsselfeld

(DataClassKeyField)

Verweis auf das Schlüsselfeld der Datenklasse (zugehöriges Feld mit Datentyp "Schlüssel 1 einer Datenklasse"), bzw. bei "Land/PLZ/Ort“ Verweis auf das Landes-Feld (zugehöriges Feld mit Datentyp "Land/PLZ/Ort: Land").

Suchfilter

(FilterParameters)

Übergabe von Werten an die Datenklasse und an den angeschlossenen Suchdialog, um die Daten zu filtern. Dort können sie als Platzhalter für SQL verwendet werden (z.B. “$[Parameter(name)]”) bzw. werden direkt an das dem Such-/Filterfeld zugeordnete Such-Element übergeben.

Außerdem Übergabe von Werten zur Verwendung in den Makros des Kontextmenüs der Datenklasse. Die Namen werden automatisch um einen führenden Unterstrich ergänzt und stehen damit in den Makros als lokale Variablen zur Verfügung.

Format:

• Semikolon-separierte Liste von Name-/Ausdruck-Paaren

• Konstante Texte müssen in Anführungszeichen eingefasst werden, innenliegende Anführungszeichen sind zu verdoppeln

Syntax:

• <name>:=Makroausdruck[;...]

Beispiel:

• Art:=1;Typ:=[Typ];Kahn:="Kahn ""Der Titan"""

Standard-Wert

(DefaultValue)

Standardwert für die Eingabe.

Die Angabe eines Ausdrucks (muss mit „=“ beginnen) ist zulässig, wobei dort kein Zugriff auf andere Felder erlaubt ist.

Gilt auch bei Datenreferenzen, wobei dort geprüft wird, ob der Wert in der Liste vorhanden ist, ansonsten dort keine Vorbelegung.

Datumswerte müssen im ISO-Format („yyyy-mm-dd“ bzw. „yyyy-mm-ddThh:mm:ss“) angegeben werden.

Zahlen mit Nachkommastellen müssen Kultur-invariant angegeben werden, d.h. mit Punkt und nicht mit Komma.

Schreibschutz?

(IsReadOnly)

Markierung für Nur-Lese-Felder

"Schreibschutz?" wird für folgende Fälle aktiviert:

• nicht Update-fähige Felder, z.B. Aggregate oder Sub-Queries

• Felder, die für interne, rein Client-seitige Steuerungen verwendet werden
  (und die nicht im Datenbankschema enthalten sind)

Wird "Schreibschutz?" aktiviert, hat dies folgende Auswirkungen:

• Die Einstellung kann zur Laufzeit nicht mehr umgeschaltet werden (auch nicht mit dem Makro-Befehl "FestlegenNurLesen").

• Wird der Feldinhalt geändert (dies kann für interne oder auch temporäre Zwecke sinnvoll sein), führt dies nicht dazu, dass die Daten dirty werden.

Wird "Schreibschutz?" nicht aktiviert, kann zur Laufzeit Client-seitig mit dem Makro-Befehl "FestlegenNurLesen" die Einstellung auf "True" gesetzt werden.

• Hierbei entsteht ein im UI schreibgeschütztes Feld, welches aber auf Datenebene beschreibbar bleibt.

• Im UI wird dadurch eine direkte Änderung im Eingabefeld durch den Benutzer verhindert. Das Eingabefeld kann aber weiterhin fokussiert werden, z.B. um den Inhalt kopieren zu können und um am Feld hängende Funktionen ausführen zu können.

• Programmatische Änderungen des Feldinhaltes (Client- und Server-seitig) werden nicht eingeschränkt. Das Dirty-Flag wird bei Änderungen gesetzt.

• Das Dirty-Flag wird bei Änderungen nur dann gesetzt, wenn das Feld auch tatsächlich Update-fähig ist. Zum Abfragen dieses Zustandes steht in den Metadaten des Clients das ermittelte Flag "IsUpdateable" zur Verfügung (True, wenn die zugeordnete SQL-Anweisung gefüllt ist, bzw. bei Datenstrukturen immer, da es dort kein zugeordnetes SQL gibt).

Ein Anwendungsbeispiel ist z.B. in der Belegerfassung zu finden:

• Bei Artikeln mit Dimensionen wird das Mengenfeld gesperrt. Der Inhalt kann aber per Funktions-Schaltfläche über einen Zusatzdialog, in dem Länge/Breite/Höhe eingegeben werden, geändert werden.

Rechteverwaltung:

• Hat der Benutzer keine Schreib-Berechtigung für das Feld, wird diese Eigenschaft vom System beim Lesen der Metadaten automatisch auf True gesetzt.

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

Nachkommastellen-Definition in übergeordnetem Element?

(IsDecimalPlacesDefinitionInParent)

Erfolgt die Definition der Anzahl der Nachkommastellen über ein Feld des jeweils übergeordneten Elementes (bzw. deren jeweiligen Datenquelle)?

Nachkommastellen gemäß Feld

(DecimalPlacesDefinedByField)

Name des Feldes, das zur Laufzeit die Anzahl der Nachkommastellen enthält.

Das referenzierte Feld muss Int16 oder Int32 als Datentyp haben.

Datenreferenz

(DataReferencePartnerId, DataReferencePackageId, DataReferenceName)

Partner-Kennung, Lösungs-Kennung und Name für die Datenreferenz, die als Grundlage für ein Auswahllisten-Eingabefeld dient.

Wenn die Eigenschaften "Datenreferenz-Filter", "Datenreferenz-Service-Dll-Name" und "Datenreferenz-Service-Klassenname" nicht verwendet werden, handelt es sich um eine sogenannte "statische" Datenreferenz. In diesem Fall werden die Daten beim Öffnen des jeweiligen Elementes einmalig eingelesen. Zum manuellen Aktualisieren steht der Makro-Befehl "DatenReferenzAktualisieren" zur Verfügung. Anderenfalls wird sie zur "dynamischen" Datenreferenz. Der Client liest dann jeweils beim Aufklappen der Liste die Daten automatisch neu ein.

Eine detaillierte Beschreibung der Datenrefernztypen finden Sie in Datenreferenzen.

Datenreferenz-Filter

(DataReferenceFilter)

Zusätzliche Bedingungen, welche die WHERE-Bedingung der SQL-Abfrage zur Laufzeit erweitern. Der Client liest jeweils beim Aufklappen der Liste die Datenreferenz neu ein.

Format:

• Aus Sicherheitsgründen kann auf dem Client nicht direkt in SQL formuliert werden. Stattdessen wird die "SData Query Language" (siehe http://sage.github.io/SData-2.0/pages/core/0212/) verwendet, welche einem vereinfachten SQL entspricht.
  
  Einschränkungen:

  • Eine Negierung mit "not" muss sich immer auf einen booleschen Ausdruck beziehen.
    Richtig: not (UserName like '%Sage%')
    Falsch: UserName not like '%Sage%'

Platzhalter:

• Im Filter können Platzhalter verwendet werden, um die Daten des aktuell geladenen Datensatzes im Filter zu verwenden. Das Format entspricht den üblichen Makro-Ausdrücken/Feldreferenzen.

Beispiel:

MyUnion.Periode=[Periode] AND MyUnion.Benutzer=[Benutzer]

Datenreferenz-Info-Felder

(DataReferenceInfoFields)

In einem Datenreferenz-Feld werden im UI neben dem eigentlichen Schlüssel (optional) auch alle anderen in der Datenreferenz referenzierten Felder angezeigt. Bei einem zusätzlichen Filter ("Datenreferenz-Filter") oder wenn eine DLL/Klasse und "Datenreferenz-Parameter“ hinterlegt sind wird die Datenreferenz erst beim Anzeigen der Auswahlliste komplett geladen. Für die Anzeige im Datenreferenz-Feld sind in der Datenstruktur die dort verwendeten Felder anzulegen und über die Liste "Datenreferenz-Info-Felder" in der gleichen Reihenfolge zu referenzieren.

Datenreferenz-Parameter

(DataReferenceServiceParameters)

Übergabe von Werten an die aufzurufende Klasse, um die Daten zu filtern. Der angeschlossene Suchdialog bekommt die Platzhalter ebenfalls.

Semikolon-separierte Liste von Name-/Ausdruck-Paaren. Konstante Texte müssen in Anführungszeichen eingefasst werden, innen liegende Anführungszeichen sind zu verdoppeln.

• Format:
  Name:=Ausdruck[;...]

• Beispiel:
  Art:=1;Typ:=[Typ];Kahn:="Kahn ""Der Titan"""

Datenreferenz-Service-Dll-Name

(DataReferenceServiceAssemblyName)

Definition einer DLL, über die die Datenreferenz dynamisch gefiltert wird. Der Geschäftsprozess liefert aus der Gesamtmenge der Daten nur die gültigen Schlüssel zurück.

Der Client liest jeweils beim Aufklappen der Liste die Datenreferenz neu ein.

Achtung: Die Daten werden zuerst komplett eingelesen und an den Client übertragen, der dann die Filterung initiiert. Bei großen Datenbeständen kann dies zu Performance-Problemen führen.

Hier wird der Name der aufzurufenden DLL (ohne Verzeichnisname, aber mit Dateinamenerweiterung „.dll“) angegeben.

Die DLL wird immer im OL-Shared-Verzeichnis gesucht

Datenreferenz-Service-Dll-Klassenname

(DataReferenceServiceClassName)

Name der aufzurufenden Klasse.

Als Basisklasse ist "DataReferenceProcessBase" zu verwenden.

Hinweis für Developer Partner

WDB-Eintrag 203334:
Dokument "Zusatzdokumentation zum Wiki für Developer Partner", DataReferenceProcessBase

Validierung

Pflichtfeld?

(IsMandatory)

Markierung für Pflichtfeld

(ab Version 9.0)

Bei nummerischen Nicht-Pflicht-Feldern werden leere Felder und der Wert '0' unterschiedlich behandelt:

• Leeres Feld: Wird als NULL in der Datenbank gespeichert, falls die SQL-Spalte Nullable ist.

• Feldinhalt '0': Wird als '0' in der Datenbank gespeichert.

Beispiel-Szenario ist die erfasste Menge in der Inventur, bei der zwischen "noch nicht eingegeben" (NULL) und dem Lagerbestand '0' unterschieden werden muss.

Felder der Datentypen 15 und 16 (indexed String und indexed Image) werden immer als Pflichtfeld behandelt, aber im UI nicht markiert, da sie generell immer eine Vorbelegung haben).

Minimalwert

(MinValue)

Minimalwert für Validierung; bei nicht Pflicht-Feldern kann das Feld zusätzlich leer bleiben.

Maximalwert

(MaxValue)

Maximalwert für Validierung; bei nicht Pflicht-Feldern kann das Feld zusätzlich leer bleiben.

Liste zulässiger Werte

(ValueList)

Werteliste für Validierung (Auswertung nach Min/Max, falls definiert); bei nicht Pflicht-Feldern kann das Feld zusätzlich leer bleiben.

Validierungs-Ausdruck

(ValidationExpression)

Validierungs-Ausdruck mit Boolean-Rückgabewert (bei nicht Pflicht-Feldern kann das Feld zusätzlich leer bleiben):

• True = Validierung in Ordnung

• False = Validierungsfehler

(Auswertung nach Min/Max und Werteliste, falls definiert)

Hinweis: Dieser Ausdruck ist nicht geeignet, um Abhängigkeiten zwischen mehreren Feldern zu validieren, weil es keinen mehrfachen Feldbezug gibt (wie beispielsweise beim Makro-Befehl „FehlerMelden“).

Validierungs-Ausdruck-Fehlermeldung

(ValidationExpressionMessage)

Fehlermeldung, falls ein Validierungsfehler auftritt

Ereignisse (Makros)

Validierung nach Änderung

(ValidationAfterChange)

Makros zur Validierung, die sowohl Client- als auch Server-seitig ausgeführt werden, damit aus Komfortgründen die Validierung schon Client-seitig erfolgen kann.

Client-seitig wird das Ereignis bei Änderungen wie folgt aufgerufen:

• in Eingabefeldern für Texte, Zahlen, etc. beim Fokusverlust

• bei Kombinationsfeldern und Checkboxen sofort

• bei programmgesteuerten Änderungen, beispielsweise nach dem Makro-Befehl „FestlegenFeldwert“

Das Ereignis tritt beim Erzeugen der Defaultwerte für einen neuen bzw. beim Laden eines vorhandenen Datensatzes nicht auf.

Server-seitig wird das Ereignis vor dem Speichern ausgelöst. Eine fehlgeschlagene Validierung führt dort zur Ablehnung der Operation. Die Ausführung erfolgt innerhalb der Transaktion.

Hinweise für den Einsatz:

• Segmentierten Schlüsseln (z.B. Artikel/Variante) werden als Einheit gesehen. Bei Änderungen an beiden Segmenten wird aus Performance-Gründen jeweils das "Nach Aktualisierung"-Ereignis des ersten Segmentes aufgerufen. Das "Nach Aktualisierung"-Ereignis des zweiten Segmentes sollte daher nicht genutzt werden.

• Server-seitig werden beim Speichern
  
  

  • zuerst für alle Felder die generischen Validierungen durchgeführt (Pflichtfeld-Prüfungen, Min-/MaxValue, etc.),

  • dann für alle Felder die hier im "Nach Aktualisierung"-Ereignis definierten Validierungen durchgeführt und

  • dann die ggf. im nachfolgenden Datensatz-"Vor Änderung"-Ereignis definierten Validierungen durchgeführt.

• Treten bei den Feld-Validierungen Fehler auf, werden die Meldungen gesammelt und die Verarbeitung wird nach Vollendung des jeweiligen Schrittes abgebrochen.

Das Ereignis wird auf Client- und Server-Seite ausgelöst (sinnvollerweise im Makro die Funktion „IsRunningOnServer“ verwenden, um nur auf dem Server auszuführen und Roundtrips zu vermeiden)

Das Ereignis kann bei angehängten Feldern (siehe „DoAppendTo“) definiert werden, um zusätzliche Makros ausführen zu lassen. Die Ausführung der Makros erfolgt jeweils nach aufsteigenden Partner- und Lösungs-Ids mit Sage beginnend.

Falls ein Feld in einem "ValidationAfterChange"-Makro eines anderen Feldes als Feldbezug in Parameter 3 des Makrobefehls "FehlerMelden" genannt wird, wird auch das "ValidationAfterChange"- Makro des anderen Feldes ausgeführt.