Arbeiten mit Datenfeldern

Einführung in Datenfelder

Der Zugriff auf die Datenfelder ist ein wesentlicher Bestandteil der ConSol CM-Programmierung. Er kann in allen Skripten des Systems notwendig sein, sowohl in Workflow-Skripten als auch in Admin-Tool-Skripten und zwar unabhängig vom Skripttyp. An dieser Stelle konzentrieren wir uns auf die Workflow-Programmierung, der Zugriff auf die Datenfelder funktioniert aber in allen Skripten grundsätzlich gleich.

Es gibt drei Arten von Datenfeldern:

Regeln für die Arbeit mit Datenfeldern

Wenn Sie mit Ticketfeldern, Kundenfeldern oder Ressourcenfeldern arbeiten, müssen Sie zwei Grundregeln berücksichtigen:

  1. Alle Datenfelder werden immer in Datenfeldgruppen verwaltet und referenziert, z. B. verwenden Sie <Name Ticketfeldgruppe>.<Name Ticketfeld>, wenn Sie den Wert eines Ticketfeldes abrufen möchten.
  2. Sie müssen immer den eindeutigen technischen Namen verwenden, um eine Datenfeldgruppe oder ein Datenfeld zu referenzieren, nie den lokalisierten Wert.

Datentypen für Datenfelder

Ein Datenfeld hat immer einen bestimmten Datentyp. Bei Variablen für die Programmierung hängt es vom Datentyp ab, wie Sie den Wert des Feldes verarbeiten müssen, ein Feld des Datentyps string kann z. B. nicht für die Berechnung von Zahlen verwendet werden und Felder des Datentyps enum benötigen eine spezielle Zugriffsmethode.

Die folgenden Datentypen sind für Ticketfelder, Kundenfelder und Ressourcenfelder verfügbar:

Der Datentyp, den Sie beim Erstellen eines Datenfeldes verwenden, kann danach nicht mehr verändert werden!

Details über String-Felder: Verwenden von Annotationen zum Anpassen von Strings

String-Felder werden häufig für Kunden-, Ticket- und Ressourcendaten verwendet und in Strings kann unterschiedlicher Inhalt gespeichert werden, zum Beispiel ein Textfeld mit einem Kommentar, ein einfaches Eingabefeld mit nur 20 Zeichen, eine URL oder ein Passwort. Das Anpassen von String-Feldern erfolgt mithilfe von speziellen Annotationen, die auf der Seite Annotationen des Anhangs aufgeführt sind. Da die Arbeit mit diesen Annotationen zu den alltäglichen Aufgaben eines CM-Administrators gehört, sind die wichtigsten und am häufigsten verwendeten Annotationen zusätzlich an dieser Stelle erklärt.

Wie kann ich ...

... statt einer einzelnen Zeile ein Textfeld einfügen?

Wert für Annotation text-type: textarea

Die Größe des Textfeldes kann angepasst werden. Es wird je nach Webbrowser als Standardtextfeld angezeigt. Verwenden Sie die Annotation field-size, wenn das Textfeld eine bestimmte Größe haben soll.

... die Eingabe des Feldes für Passwörter ausblenden?

Wert für Annotation text-type: password

Es werden nur Punkte angezeigt. Diese Annotation legt nicht fest, dass das Feld ein Passwort enthält! Es definiert nur den Anzeigemodus! Verwenden Sie die Annotation password, um ein String-Feld zu definieren, das das CM/Track-Passwort enthält.

... einen Hyperlink anzeigen, den Namen statt dem Link anzeigen?

Wert für Annotation text-type: url

Die Eingabe wird im Ansichtsmodus als Hyperlink angezeigt. Der String muss einem bestimmten URL-Muster entsprechen:

Der erste Teil des Strings ist der Link (URL) und der zweite Teil ist der Name, der angezeigt werden soll.

Beispiel: "http://consol.de ConSol"

... einen Dateilink anzeigen?

Wert für Annotation text-type: file-url

Die Eingabe wird als Link auf eine Datei im Dateisystem angezeigt. Der Webbrowser muss solche Links zulassen/unterstützen!

Beispiel: Aktivieren von file://-URLs in einem Firefox-Browser

Fügen Sie die folgenden Zeilen entweder zur Konfigurationsdatei prefs.js oder zu user.js im Benutzerprofil hinzu. Auf einem Windows-System befindet sich diese normalerweise in einem Ordner wie C:\Benutzer\<BENUTZERNAME>\AppData\Roaming\Mozilla\Firefox\Profiles\uvubg4fj.default

Alternativ kann ein Add-on des Firefox-Browsers wie Local Filesystem Links installiert werden, um einfacher auf die referenzierten Dateien und Ordner zugreifen zu können.

Dieser Link wird auch als Tooltip angezeigt.

Die URL ist korrekt formatiert, wenn folgende Bedingungen erfüllt sind:

Beispiel-URLs:

Siehe auch die Erklärung von file-url im Abschnitt Liste der Feldannotationen

... ein Label definieren?

Wert für Annotation text-type: label

Dies ist ein schreibgeschütztes Feld, das grau angezeigt wird. Verwenden Sie die Annotation label-group, um das Label und die dazugehörigen Eingabefelder zu verknüpfen. Berücksichtigen Sie die Annotationen für Label (show-label-in-edit, show-label-in-view), bevor Sie spezielle Label-Felder implementieren!

... ein Feld für gültige E-Mail-Adressen definieren?

Wert für Annotation email: true

Das Feld darf nur gültige E-Mail-Adressen enthalten. Die Eingabe wird gemäß des Standardformats für E-Mail-Adressen validiert <name>@<domain>.

... eine skriptbasierte Autocomplete-Liste definieren? 

Wert für die Annotation text-type = autocomplete

Optional: Wert für die Annotation autocomplete-script = <Name des entsprechenden Skripts>

Eine skriptbasierte Autocomplete-Liste wird verwendet, um ein Drop-down-Menü bereitzustellen, das anhand der Eingabe, die der Bearbeiter bereits vorgenommen hat, dynamisch gefüllt wird. Wenn der Benutzer zum Beispiel "Mei" eingibt, werden die möglichen Werte "Meier", "Meister" und "Meinert" als Liste angezeigt und der Bearbeiter kann den für das Feld erforderliche Wert auswählen. Sie kennen dieses Verhalten von anderen Autocomplete-Feldern, z. B. der Suche nach Bearbeitern für ein Ticket oder die Suche nach Kunden bei der Ticketerstellung. In diesen Fällen erzeugt CM die Liste allerdings automatisch und das Verhalten kann nicht beeinflusst oder angepasst werden. Im Gegensatz dazu können skriptbasierte Autocomplete-Listen vom CM-Administrator implementiert werden. Die Werte basieren auf einem Ergebnissatz, der dynamisch erstellt wird. Der Ergebnissatu kann Strings, Bearbeiter, Kunden (Units) und Ressourcen enthalten.

Eine detaillierte Beschreibung von skriptbasierten Autocomplete-Listen finden Sie im Abschnitt Skriptbasierte Autocomplete-Listen des Administratorhandbuchs.

... ein Feld für das CM/Track-Login definieren?

Wert für Annotation username: true

Wird für die Authentifizierung beim CM/Track-Server verwendet. Nur für Kundenfelder in einem Kontaktobjekt.

... ein Feld für das CM/Track-Passwort definieren?

Wert für Annotation password: true

Wird (im Datenbankmodus) für die Authentifizierung beim CM/Track-Server verwendet. Nur für Kundenfelder in einem Kontaktobjekt.

... ein Feld für persönliche Daten definieren?

Wert für Annotation personal-data: true

Diese Annotation kann Ticket- und Kontaktfeldern zugewiesen werden. Kontaktfelder mit dieser Annotation werden gelöscht, wenn ein Kontakt anonymisiert wird. Ticketfelder mit dieser Annotation werden gelöscht, wenn der Hauptkunde des Tickets anonymisiert wird.

Beachten Sie bei der Definition von Feldern für persönliche Daten, dass das Löschen des Feldes während des Anonymisierungsprozesses wie eine normale Aktualisierung behandelt wird. Das heißt, Business-Event-Trigger, die auf Änderungen an Ticketfeldern reagieren, feuern und das Aktionsskript zur Kontaktaktualisierung wird ausgeführt.

Dies kann zu unerwünschten Nebeneffekten führen.

... ein Rich-Text-Feld definieren?

Erstellen Sie ein Feld des Typs long string.

Wert für Annotation string-content-type: html-inline (der Feldinhalt wird im Ansichtsmodus direkt auf der GUI angezeigt) oder html-link (der Feldinhalt wird in einem Pop-up-Fenster angezeigt, das im Ansichtsmodus durch Klicken auf den Link Inhalt anzeigen geöffnet wird)

Ein Rich-Text-Feld kann Bilder und formatierten Text enthalten. Im Bearbeitungsmodus ist ein einfacher Editor vorhanden.

Methoden für den Zugriff auf Datenfelder

Die grundlegenden Methoden, um auf Datenfelder zuzugreifen, sind für Tickets, Kunden und Ressourcen gleich. Die folgenden Abschnitte enthalten eine kurze Einführung in jeden Objekttyp und beschreiben die verfügbaren Methoden.

Ticketdaten

Im Admin Tool werden die Ticketfelder in der Navigationsgruppe Tickets, Navigationselement Ticketfelder definiert.

Abbildung 134: ConSol CM Admin Tool - Verwaltung der Ticketfelder für Ticketdaten

Für die Arbeit mit Ticketfeldern benötigen Sie vier Methoden der Klasse Ticket:

Details zum Umgang mit den verschiedenen Datentypen finden Sie im Abschnitt Programmierbeispiele mit verschiedenen Datentypen.

Kundendaten

Das Kundendatenmodell enthält Kundenfeldgruppen und Kundenfelder. Sie werden im Admin Tool, Navigationsgruppe Kunden, Navigationselement Datenmodelle definiert.

Abbildung 135: ConSol CM Admin Tool - Verwaltung von Kundenfeldern für Kundendaten

Für die Arbeit mit Kundenfeldern benötigen Sie vier Methoden der Klasse Unit:

Alternativ können Sie den Feldgruppennamen und das Feld durch einen Doppelpunkt trennen.

Details zum Umgang mit den verschiedenen Datentypen finden Sie im Abschnitt Programmierbeispiele mit verschiedenen Datentypen.

Bei der Arbeit mit Kundendaten müssen Sie auch auf die verschiedenen Kundenobjekte zugreifen. Die folgenden Beispiele zeigen die Convenience-Methoden, die die ConSol CM API für diesen Zweck zur Verfügung stellt.

Sie können die Methoden verketten, zum Beispiel um die Anzahl der Tickets des ersten Kontakts einer Firma zu erhalten:

Integer count = contact.get("company().contacts()[0].tickets()[count]");

Programmierbeispiele aus dem ConSol CM Action Framework finden Sie im ConSol CM Administratorhandbuch, Abschnitt Skripte für das Action Framework.

Ressourcendaten

Mit dem optionalen Modul CM/Resource Pool können Sie die CM-Datenbank erweitern und Ressourcenobjekte speichern. Dies können unterschiedliche Objekte wie IT-Assets, Verträge, Produkte oder andere in der entsprechenden Firma benötigte Objekte sein. Das Ressourcendatenmodell wird in der Navigationsgruppe Ressourcen, Navigationselement Datenmodelle definiert.

Abbildung 136: ConSol CM Admin Tool - Definition des Ressourcendatenmodells

Für die Arbeit mit Ressourcenfeldern benötigen Sie vier Methoden der Klasse Resource:

Details zum Umgang mit den verschiedenen Datentypen finden Sie im Abschnitt Programmierbeispiele mit verschiedenen Datentypen.

Beim Programmieren mit Ressourcen ist es häufig erforderlich, Ressourcen abzurufen, die mit einem bestimmten Ticket oder einem bestimmten Kunden verknüpft sind. Dieses Thema wird detailliert im Abschnitt Arbeiten mit Ressourcenrelationen.

Programmierbeispiele aus dem ConSol CM Action Framework finden Sie im ConSol CM Administratorhandbuch, Abschnitt Skripte für das Action Framework.

Programmierbeispiele mit verschiedenen Datentypen

Der folgende Abschnitt zeigt Beispiele für die Arbeit mit Datenfeldern verschiedener Datentypen. Die Beispiele beziehen sich auf Ticketfelder, sie gelten aber auch für Kunden- und Ressourcenfelder. Die Felder werden immer mit ihrem technischen Namen nach dem folgenden Muster referenziert:

<ticket|unit|resource>.<get|set|add|remove>("<technischer Name der Feldgruppe>.<technischer Name des Feldes>")

Einfache Datentypen

Einfache Datentypen sind Datenfelder, die einen einzelnen Wert oder ein einzelnes Objekt enthalten. Die folgende Liste zeigt die verfügbaren einfachen Datentypen mit den Klassen ihrer Werte:

Abrufen und Setzen von einfachen Feldwerten

Das folgende Beispiel zeigt, wie der Boolean-Wert eines Ticketfeldes abgerufen werden kann, um ihn in einem Bedingungsskript zu verwenden.

boolean vip_info = ticket.get("am_fields.vip")

 

if(vip_info == true){

return true

}

else {

return false

}

Code-Beispiel 29: Bedingungsskript, in dem ein Boolean-Wert überprüft wird

Dasselbe Verhalten kann erreicht werden, indem Sie den Wert direkt zurückgeben:

return ticket.get("am_fields.vip")

Code-Beispiel 30: Bedingungsskript, in dem ein Boolean-Wert überprüft wird, Kurzversion

Das folgende Beispiel zeigt, wie ein Wert in einem Ticketfeld gesetzt werden kann. Da das Feld den Datentyp date hat, benötigt es ein Date-Objekt, das direkt in der Anweisung erstellt werden kann.

ticket.set("fields.reaction_time", new Date());

Code-Beispiel 31: Setzen eines Ticketfeldwertes für ein Feld des Typs Date

Wenn Sie mit Feldern des Typs number oder date arbeiten, können Sie sogar bequem mit den Feldwerten rechnen, siehe folgendes Beispiel.

ticket.add("fields.orders_number", 1)

Code-Beispiel 32: Eins zur Anzahl der Bestellungen addieren

Abrufen und Setzen von Enum-Werten

Ein Feld des Typs enum (sortierte Liste) ist ein Feld, in dem der Wert einer von mehreren Listenwerten ist. Zum Beispiel kann eine Liste mit Prioritäten die Grundlage für ein Enum-Feld bilden. Sie können zum Abrufen des Wertes eines Enum-Feldes die gleiche Syntax verwenden wie für einfache Datentypen. Die Methode get liefert ein Objekt der Klasse EnumValue. Verwenden Sie die Methode getName(), um den string mit dem technischen Namen des Wertes abzurufen. Die Notation .name ist die Groovy-Version der Getter-Methode.

def prio = ticket.get("helpdesk_standard.priority")

log.info 'Priority is now ' + prio.getName()

//or shorter:

log.info 'Priority is now ' + prio.name

Code-Beispiel 33: Abrufen eines Enum-Wertes für ein Ticketfeld

Wenn Sie den lokalisierten Wert eines Enum-Feldes abrufen möchten, müssen Sie LocalizationService verwenden.

def my_enum_field = ticket.get("helpdesk_standard.priority")

def my_enum_field_localized = localizationService.getLocalizedProperty(EnumValue.class, "name", my_enum_field.id, engineerService.getCurrentLocale())

Um einen Enum-Wert zu setzen, verwenden Sie den technischen Wert mit der folgenden Syntax. Der neue Wert muss in der Sortierten Liste, die von dem Ticketfeld referenziert wird, vorhanden sein.

ticket.set("helpdesk_standard.priority", "URGENT");

Code-Beispiel 34: Setzen eines Enum-Wertes

Abrufen von MLA-Werten und -Pfaden

Die Java-Klasse für MLAs (Multi Level Attributes) ist MultiEnumField. MLAs werden bezüglich des Abrufens und Setzens der Werte wie normale Enum-Felder behandelt.

Die folgenden Beispiele zeigen die grundlegenden Methoden:

Das folgende Beispiel zeigt, wie Sie den gesamten Pfad zum ausgewählten MLA-Wert abrufen können:

List<EnumValue> mlaPathElements = mlaService.getAssignedMla(ticket, "helpdesk_standard", "categories")

def mlaPath1=""

mlaPathElements.each() {elem ->

mlaPath1 = elem.name + ' -- ' + mlaPath1

}

 

//or shorter:

def mlaPath2 = mlaService.getAssignedMla(ticket, "helpdesk_standard", "categories").reverse()*.name.join(" -- ")

Code-Beispiel 35: Abrufen des gesamten Pfads zum ausgewählten MLA-Wert

Listen und Tabellen

Listen und Tabellen sind „Container“ für andere Datenfelder. Ein Datenfeld des Typs list enthält entweder ein Feld eines einfachen Datentyps oder ein struct, das aus mehreren Feldern mit einfachen Datentypen besteht. Ein Listenfeld kann mehrere Werte enthalten.

Listen

Jede Zeile einer Liste enthält einen Wert eines einfachen Datentyps, in unserem Beispiel ein Datum. Das Ticketfeld des Typs date muss den Parameter Gehört zu haben, der auf die Liste zeigt.

Abbildung 137: ConSol CM Admin Tool - Ticketfeld für eine Liste mit Datumsfeldern

Abbildung 138: ConSol CM Web Client - Liste der Datumsfelder in einem Ticket (Bearbeitungsmodus)

Der folgende Abschnitt zeigt die wichtigsten Methoden für die Arbeit mit Listen anhand der Liste aus dem obigen Beispiel:

Tabellen (Lists of Structs)

Die Datenstruktur list of structs bildet die technische Grundlage für eine Tabelle mit mehreren Spalten im Web Client. Die Liste ist das übergeordnete Objekt, das Zeilen enthält. Jede Zeile ist eine Instanz eines struct. Jedes struct) enthält so viele Ticketfelder (Tabellenspalten) wie erforderlich (siehe Abbildung in der Einleitung dieses Abschnitts).

Um die Daten aus einer List of Structs abzurufen, arbeiten Sie mit einer Iteration über die Zeilen. Im folgenden Beispiel arbeiten wir mit einer Tabelle, in der ...

Abbildung 139: ConSol CM Admin Tool - Ticketfelder für eine mehrspaltige Liste (= Tabelle)

Abbildung 140: ConSol CM Web Client - Ticket mit ausgefüllter Tabelle

Ein- und Ausblenden von Datenfeldgruppen

Datenfeldgruppen können abhängig von den Prozessanforderungen eingeblendet (sichtbar gemacht) und ausgeblendet (unsichtbar gemacht) werden. Dies hilft dabei, die Objekte übersichtlich zu halten, so dass die Bearbeiter nur Datenfelder sehen, die für den entsprechenden Prozessschritt relevant sind.

Ein typischer Anwendungsfall ist eine Ticketfeldgruppe, die zuerst unsichtbar ist (Gruppenannotation group-visibility = false) und zu dem Zeitpunkt eingeblendet wird, an dem der Bearbeiter im Prozess mit den Daten arbeiten muss. Eine Ticketfeldgruppe, die zum Beispiel das Feedback eines Kunden enthält, wird nur angezeigt, wenn der Bearbeiter auf die Workflow-Aktivität Feedback erhalten ... klickt, da diese Information vorher nicht erforderlich ist. Auf diese Weise können auch Ticketfeldgruppen, die nicht mehr benötigt werden, ausgeblendet werden.

Mit den folgenden Methoden können Sie die Sichtbarkeit von Ticketfeldgruppen steuern:

Zusätzlich kann GroupPropertyType.VISIBLE den Wert open haben, was bedeutet, dass der Tab der Feldgruppe im Bereich Detaildaten ausgewählt/geöffnet ist.

Derselbe Mechanismus kann auch für Kunden und Ressourcen verwendet werden. In diesen Fällen lauten die Methoden:

Verwenden von Datenfeldern für Variablen

Manchmal ist es erforderlich, mit Variablen zu arbeiten, die für die Workflow-Programmierung benötigt werden, aber nicht auf der GUI sichtbar sein sollen. Abhängig vom Objekt, für das sie benötigt werden, können Sie Ticket-, Kunden- oder Ressourcenfelder für diese Variablen verwenden.

Erstellen Sie die Datenfelder mit dem benötigten Datentyp und machen Sie sie durch Zuweisen der Annotation visibility = none unsichtbar.

Wenn Sie die Variablenwerte während der Entwicklungsphase kontrollieren möchten, können Sie das Feld sichtbar lassen und die Annotation erst zuweisen, wenn die Entwicklung abgeschlossen ist.