Entitäten

Grundlagen

Im Knoten Entitäten können zusätzliche Objekte ("Customized Entitäten" sog. C2-Entitäten) in der Datenbank angelegt und mit anderen Objekten (Entitäten) verknüpft werden.

Abbildung: Entitäten

Tipp

Bevor Sie eine C2-Entität anlegen, sichern Sie Ihre Datenbank.

Neuanlage einer Entität

So legen Sie eine C2-Entität an (prinzipieller Ablauf):

1.	Öffnung des Knotens Entitäten führt implizit zur Neuanlage-Maske einer C2-Entität. Mit dem Schalter Neu legen Sie eine neue Entität an, wenn Sie vorher z.B. eine vorhandene C2-Entität geladen haben. Die Eingabefelder Name der Entität und Beschriftung der Entität sind bereits mit C2 vorbelegt. Gleichzeitig existiert in der Feldliste auf der rechten Seite der Maske bereits ein Textfeld mit der Bezeichnung Pk. Dieses Feld wird später den Primärschlüssel der Tabelle aufnehmen und kann nicht entfernt oder bearbeitet werden.
2.	Legen Sie jetzt einen eindeutigen Namen für die neue Entität fest. Beachten Sie, dass der Name zwingend mit der Zeichenkombination C2 beginnen muss. Es handelt sich hierbei um eine programminterne Konvention, um selbst erstellte Entitäten bereits am Namen identifizieren zu können. Wenn Sie versuchen, einen Namen ohne führendes C2 einzutragen, ändert das Eingabefeld seine Hintergrundfarbe. Der Name der Entität bleibt später programmintern, der Anwender sieht lediglich die Beschriftung der Entität. Im EntityCreator können insgesamt 15 Zeichen eingegeben werden, die ersten Zeichen müssen der Identifikation dienen: Cxx / C2 (wobei xx die zweistellige Partnernummer ist) 12 bzw. 13 Zeichen sind für freie Eingabe des Namens vorgesehen
3.	Tragen Sie unter Beschriftung der Entität die gewünschte Bezeichnung ein, so wie sie später im System in Erscheinung treten soll. Die Beschriftung der Entität ist für mehrere Sprachen möglich, obwohl das Beschriftungsfeld nur 1x vorhanden ist. Melden Sie sich als Administrator auf Deutsch an und tragen Sie die Beschriftung ein, so gilt die Beschriftung für Clients auf Deutsch. Möchten Sie dagegen die Beschriftung auch für z.B. englischsprachige Clients festlegen, müssen Sie sich als Administrator auf Englisch einloggen. Die Beschriftung kann man nachträglich ändern.
4.	Über die beiden Kontrollkästchen Hauptfenster und Unterfenster legen Sie fest, ob die neu erstellte Entität später als Hauptentität aufrufbar ist, ob sie lediglich als verknüpfte Unterentität z.B. bei einem Geschäftspartner in Erscheinung treten soll, oder beides.
5.	Über den Schalter Icons der Entität laden Sie die Icons für die neue Entität. Erlaubte Formate sind: gif, jpg und png. Laden Sie das Icon in 5 Auflösungsvarianten: 16x16 Pixel 24x24 Pixel 32x32 Pixel 128x128 Pixel 256x256 Pixel Der Name der Datei soll wie folgt aufgebaut sein: `<Name><Auflösung>.<Erweiterung>`
6.	Fügen Sie jetzt nach Bedarf über die Schalterleiste neue Felder zu der Entität hinzu: einfache Felder Schlüsselfelder Nachschlagefelder Die Feldnamen (auch "Spaltennamen" bzw. "Tabellenspalten-Namen" genannt) dürfen nur bis zu 15 Zeichen lang sein.
7.	Über die Kontrollkästchen im Bereich Verknüpfte Entitäten legen Sie die Verknüpfungen fest. Die hier vorgenommenen Einstellungen haben Auswirkungen auf die Erreichbarkeit der neuen Entität. Beispielsweise wird ein neues Objekt Zusatzinformationen mit den Attributen Hauptfenster und Unterfenster angelegt und lediglich mit der bestehenden Entität Ansprechpartner verknüpft. Dann kann später bei jedem Ansprechpartner im Unterbereich auf die Zusatzinformationen zugegriffen werden. Öffnet man im Gegenzug das Hauptfenster Zusatzinformationen, so kann zu jeder Information der verknüpfte Ansprechpartner angezeigt werden. Die Zuordnung zu anderen Entitäten können Sie nachträglich ändern.
8.	Eine Konfiguration kann zuerst ohne Speicherung überprüft werden. Die Prüffunktion rufen Sie über den Schalter Prüfen auf
9.	Nachdem Sie alle benötigten Felder fehlerfrei in der Liste angelegt haben, muss die Entität abgespeichert werden. Dies geschieht über den Schalter Speichern . Sollte es in Ihrer Konfiguration doch noch Fehler geben, so werden Sie durch eine Meldung darauf hingewiesen. Die Konfiguration ist dann nicht gespeichert. Der Fehler muss zuerst behoben werden, damit sie die Konfiguration erfolgreich speichern können. Beim Speichern werden zusätzlich systembedingte Felder hinzugefügt. Hinweis Wurde die Entität abgespeichert, werden die Schalter (Enfernt alle Felder) und (Entfernt alle selektierten Felder) ausgegraut dargestellt. Diese Funktionalitäten stehen nicht mehr zur Verfügung. Einmal gespeicherte Felder dürfen nicht mehr gelöscht werden. Dies ist nur über einen SQL-Statement möglich.
10.	Nach erfolgreicher Neuanlage einer zusätzlichen Entität benötigt sie eine grafische Oberfläche (Maske). Diese wird über den GUI-Builder erzeugt. Dieses Modul starten Sie direkt über den entsprechenden Schalter in der Schalterleiste. Der GUI-Builder lädt auf diese Art direkt die neu erstellte Entität. Mehr Informationen hierzu finden Sie im Kapitel GUI-Builder.
11.	Ebenfalls muss noch eine Standardsuche für die neu erstellte Entität festgelegt werden. Das geschieht über die Administrationskonsole über den Knoten Feldeigenschaften. Weitere Informationen hierzu finden Sie im Kapitel Feldeigenschaften. Ein Feld für die generierte Standardsuche soll als Suchfeld aktiviert werden. Wurde die Option Suchergebnisfeld aktiviert, wird das Feld als Spalte in der Suchmaske erscheinen.
12.	Mit dem Schalter können Sie zu dem Knoten Maskenkonfiguration wechseln, wo Sie die neue Maske (Kontrollkästchen in der Spalte Hauptfenster) aktivieren. Der Schalter ist nur dann aktiv, wenn eine gespeicherte Entität geladen wurde.
13.	Die Definition einer zusätzlichen Entität kann zur Übertragung in eine andere Applikation ebenfalls in einer externen Datei gespeichert werden oder aus einer externen Datei geladen werden. Dies geschieht über die beiden entsprechenden Schalter Importieren und Exportieren in der Schalterleiste.
14.	Damit die Einstellungen greifen, muss der Client neu gestartet werden.

Einfache Felder

Hierbei handelt es sich um Felder, die ausschließlich Daten aus einer Maske abspeichern sollen. Wird der Schalter betätigt, so wird in der Feldliste ein neues Feld mit der Bezeichnung NeuesFeld angelegt. Geben Sie dem Feld in der Spalte Feld einen neuen Namen. Bitte beachten Sie, hier keine Leer- oder Sonderzeichen zu verwenden. Sie können jetzt in der Spalte Dateityp über eine Drop Down Liste den gewünschten Dateitypen für das Feld auswählen. Unterschieden wird hierbei zwischen Text-, Zahlen-, Datums- und Memofeldern, sowie Feldern für logische Werte. Die Spalte Länge ist per Voreinstellung mit einer Größe von 255 Zeichen belegt. Bei der Neuanlage eines Textfeldes kann diese Größe individuell angepasst werden. In der Spalte Anzeigename kann individuell ein abweichender Name für das Feld angegeben werden. Hier dürfen dann auch Leer- und Sonderzeichen verwendet werden.

Schlüsselfelder

Hinweis

Das Schlüsselfeld soll möglichst vom Typ String sein. Intern geht die Logik davon aus, dass es sich bei Nachschlagefeldern um Text- oder Zahlenfelder handelt. Schlüsselfelder führen zwar nicht sofort zu Fehlern, sind aber fehleranfällig, da die Programmierung nicht davon ausgeht, dass dort dieser Typ hinterlegt ist.

Bei der Neuanlage eines Schlüsselfeldes öffnet sich zuerst der Dialog zur Neuanlage einer Schlüsselgruppe.

Abbildung: Neuanlage Schlüsselgruppe

Abbildung: Neuanlage Schlüsselgruppe

Geben Sie der neuen Schlüsselgruppe einen Namen im Feld Wert und eine sprechende Bezeichnung, unter der Sie den Schlüssel später zur Pflege identifizieren können. Über das Kontrollkästchen Zweiseitiger Schlüssel können Sie definieren, ob es sich um einen normalen Nachschlageschlüssel handelt oder um einen Schlüssel mit doppelter Relation analog zur Funktion Konzern Mutter zu Konzern Tochter. Über das Kontrollkästchen Schlüssel sind neue Gruppen legen Sie fest, ob es sich bei dem Schlüssel um einen mehrstufigen Schlüssel mit Untergruppen handeln soll. Die weitere Anlage erfolgt analog zur Anlage von einfachen Feldern.

Nachschlagefelder auf anderen Entitäten

Bei der Neuanlage eines solchen Nachschlagefeldes müssen Sie zuerst das Datenfeld einer anderen Entität auswählen, auf dem später nachgeschlagen werden soll. Hierzu sind zwei Schritte notwendig:

Die Auswahl der Datenbankentität:

Abbildung: Neuanlage Nachschlagefeld - Auswahl der Entität

Sind für die ausgewählte Entität (z.B. Mitarbeiter) im System bereits Standardsuchen definiert, erscheint ein entsprechender Hinweis.

Abbildung: Neuanlage Nachschlagefeld - Hinweis

In diesem Fall können die festgelegten Nachschlagedefinitionen nur so übernommen werden:

Abbildung: Neuanlage Nachschlagefeld - Übernahme vorhandener Nachschlagedefinition

Sind noch keine Nachschlagedefinitionen für die ausgewählte Entität im System hinterlegt, erscheint der Auswahldialog zur Festlegung der Nachschlagefelder:

Abbildung: Neuanlage Nachschlagefeld - Auswahl der Nachschlagefelder

Über die mittleren Schalter Zuordnen und Zuordnung entfernen können einzelne Felder gewählt bzw. abgewählt werden.

Bildfelder

Mit dem Feldtyp 'Bild' (RecordableImageSelectionField) in den C2-Entitäten können Sie auf der Maske Bildfelder platzieren.

Abbildung: Bild-Feld auf der Maske einer C2-Entität

Die Größe und die Auflösung des Bildes definieren Sie über die Feldeigenschaften. Die Felder platzieren Sie auf der Maske mithilfe des GUI-Builders (Administrationsrechte sind notwendig). So definierte Felder können von dem Anwender mit einem Klick auf der Maske bearbeitet werden.

Löschen einer Relation und Sicherheitsabfrage

Wird im EntityCreator eine Relation entfernt, bekommt der Anwender unter den folgenden Umständen eine Meldung.

Die Relation wird beim erneuten Anklicken mit einem anderen Namen erstellt werden.
Es sind in der Relation Daten enthalten.

Je nach Datenbestand kann auch nur eine der beiden Meldungen kommen.

CSV-Import von Tabellen für C2-Entitäten im EntityCreator

Kommt es zur Umsetzung der Anforderungen, müssen die definierten Felder vom Zuständigen händisch über den EntityCreator der Administrationskonsole angelegt werden. Dabei handelt es sich nicht selten um Entitäten, die eine große Anzahl von Feldern besitzen sollen, sodass ein nicht unerheblicher Zeitaufwand entsteht. Ein CSV-Template, in dem die internen Feldnamen, Datentypen der jeweiligen Felder, Feldlängen sowie Anzeigenamen gepflegt werden, kann über einen Export aus der Word-Datei und Umwandlung hierfür verwendet werden. Über einen Import im EntityCreator werden die Felder erzeugt und schließlich regulär gespeichert. So kann der Aufwand zur Erstellung neuer Entitäten gesenkt werden.

Weiterhin können zu Dokumentationszwecken die internen Feldnamen, Datentypen, Feldlängen und Anzeigenamen als CSV über den EntityCreator exportiert werden. Auch eine Erweiterung einer Entität um zusätzliche Felder ist so mit minimalem Aufwand möglich.

Abbildung: Schalter für den Import eines CSV-Templates

Es existiert ein fest vorgegebenes CSV-Template, in dem die anzulegenden Felder für die anzulegende C2-Entität gepflegt werden können. Der Schalter ist nur auf C1- und C2-Entitäten aktiv. Beim Klick auf den Schalter öffnet sich der FileBrowser zur Auswahl, einzig zulässiges Importformat ist .csv. Nach Auswahl der Datei und Bestätigung des Dialogs durch den Administrator wird die Datei verarbeitet. Enthält der Import Schlüssel- oder Nachschlagefelder, erscheint eine Hinweismeldung.

Leere Feldnamen sowie leere Datentypen werden beim Import ignoriert. Für leere I18n-Werte wird der Feldname genommen. Angaben wie Name, Beschriftung, Shortcut und Icon der Entität, Hauptfenster sowie Unterbereich müssen vom Administrator regulär über den EntityCreator getätigt werden. Die zugeordneten Entitäten sind ebenfalls von Administrator manuell zu pflegen. Die Validierung der getätigten Angaben (systemseitig reservierte Feldnamen, Längenbeschränkung, ungültige Feldnamen, Vollständigkeit der Eingaben, doppelte Felder) erfolgt beim Speicherversuch im EntityCreator. Bei erfolgreicher Validierung wird die Entität inklusive der angegebenen Felder angelegt. Bei fehlgeschlagener Validierung bricht der Speichervorgang ab.

Entität zum Zwischenspeichern von Daten

Mit der Entität Zwischenspeicher wurde eine generischen Möglichkeit geschaffen, Daten temporär zu speichern, deren Ermittlung zeit- und / oder rechenintensiv ist, um diese Daten später zu verwenden (z.B. für Kacheln, Skripten). Daten werden mit einer Möglichkeit versehen, zeitlich begrenzt gültig zu sein.

Das Zwischenspeichern ist auch aus Datenbankskripten heraus möglich.

Techn. Feldname	Fachl. Feldname	Datentyp	Beschreibung
TextValue	Textwert	Memofeld	Fachlicher Wert als String Expizit als Memofeld definiert, damit auch große Text (JSon-Strukturen) gespeichern werden können
NumberValue	Double	Dezimalzahl	Fachlicher Wert als Zahl
Id	Fachl. ID	varchar(255)	Fachliche ID für diesen Eintrag Pflichtfeld Doppelte Felderwerte verhindern = true
ExpiresAt	Gültig bis	Datetime	Zeitpunkt, bis zu dem dieser Eintrag fachlich gültig ist
DateValue	Datumswert	Datetime	Fachlicher Wert als Datum
BooleanValue	Ja/Nein Wert	Boolean	Fachlicher Wert Ja/Nein

Allgemeiner Zugriff

Prinzipiell kann auf die Entität über die normalen BPM-Möglichkeiten (WorkSpaceScriptUtils ...) zugegriffen werden.
Der Zugriff insbesondere in Kacheln erfolgt über die vorhandenen Möglichkeiten (i. d. R. Suchen, bei Bedarf Kapselung in BPM-Prozessen oder separate Skriptbibliotheksmethoden)

Bereitstellung Util-Methoden

Die nachfolgend beschriebenen Methoden sollen einer Util-Klasse ResultStoreUtils bereitgestellt werden und dienen der vereinfachten Nutzung für die klassischen Anwendungszwecke
Es handelt sich defacto nur um Wrapper-Methoden um die Util-Klasse WorkSpaceProxyUtils. Daraus folgt, dass
- die nachfolgend beschriebenen Methoden überall da verwendet werden können, wo die Util-Klasse WorkSpaceProxyUtils verwendet werden kann
- die normalen BPM-Events bei der Veränderung von Daten in der Entität "Zwischenspeicher" ausgelöst werden

Definition Methoden

Nachfolgend wird der Begriff "Gültig" gemäß der zuvor getroffenen fachlichen Definition verwendet.

Methode	Beschreibung
void ResultStoreUtils.delete(String id)	Setzt den Eintrag mit dieser ID auf inaktiv. Gibt es keinen derartigen Eintrag, macht die Methode de facto nichts
void ResultStoreUtils.save(String id, Object value) void ResultStoreUtils.save(String id, Object value, Date expiresAt)	Legt einen neuen Eintrag für diese ID an oder aktualisiert einen bestehenden Eintrag. Es werden auch vorhandene inaktive Einträge aktualisiert. id: Fachliche ID des Eintrag value: Muss vom Typ String, Zahl, Datetime oder Boolean und wird in das entsprechende Feld geschrieben. Bei einem nicht unterstützten Typ wird eine sprechende Fehlermeldung geworfen. "null" wird explizit nicht als zu speichernder Wert unterstützt expiresAt: optional, Zeitpunkt der Gültigkeit. Bei "null" ist der Datensatz immer gültig. String-Werte werden immer in das Memofeld geschrieben. Für kurze Texte ist dies oversized, für JSon-Strukturen hilfreich. Sich auf ein Feld zu beschränken bringt die Einfachheit in der Nutzung.
Serializable ResultStoreUtils.get(String id)	Gibt den gefüllten Wert (Text, Datum, Zahl, Boolean) für den Eintrag "ID" zurück, sofern dieser existiert und gültig ist. Existiert kein Eintrag mit dieser ID bzw. ist dieser zeitlich nicht mehr gültig oder inaktiv, liefert die Methode null zurück. Die Methode liefert den korrekten Datentyp zum gefüllten Feld zurück, d. h. ist das Feld "NumberValue" gefüllt, kommt ein Double zurück, ist "BooleanValue" gefüllt, kommt Boolean zurück usw. Double wert = ResultStoreUtils.get("de.cursor.churnscore.average");

Bereitstellung einer Standardregel für den Löschlauf

Um die zyklische Bereinigung von ungültigen Einträgen zu unterstützen, wird eine Standardregel für den Löschlauf erstellt. Die dahinterliegende Suche sucht alle Einträge in der Entität "Zwischenspeicher", die
- inaktiv sind oder
- deren "Gültig bis" Datum gefüllt ist und in der Vergangenheit liegt.
Die Regel ist im Auslieferungsstandard nicht aktiviert.