Zum Hauptinhalt springen

Verwenden von Datenfeldern in Skripten

Zugriff auf Datenfelder​

Die grundsätzlichen Methoden, um auf Datenfelder zuzugreifen, sind für Vorgänge, Kontakte und Ressourcen gleich.

Vorgänge​

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

  • Daten abrufen: 
    ticket.get("<group name>.<field name>")
  • Daten in ein Feld schreiben: 
    ticket.set("<group name>.<field name>", <value>)
  • Wert zu einem Feld hinzufügen (eine neue Zeile zu einem Listenfeld hinzufügen oder mit Daten rechnen): 
    ticket.add("<group name>.<field name>", <value>)
  • Feldwert entfernen (den Wert auf null setzen): 
    ticket.remove("<group name>.<field name>")

Kontakte​

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

  • Daten abrufen: 
    unit.get("<group name>.<field name>")
  • Daten in ein Feld schreiben: 
    unit.set("<group name>.<field name>", <value>)
  • Wert zu einem Feld hinzufügen (eine neue Zeile in einem Listenfeld hinzufügen oder mit Daten rechnen): 
    unit.add("<group name>.<field name>", <value>)
  • Feldwert entfernen (den Wert auf null setzen): 
    unit.remove("<group name>.<field name>")
Notation

Alternativ können Sie den Namen der Feldgruppe und des Feldes durch einen Doppelpunkt trennen.

Bei der Arbeit mit Kontaktdaten benötigen Sie auch Zugriff auf die verschiedenen Kontaktobjekte.

  • Hauptkontakt eines Vorgangs abrufen: 
    Unit mainContact = ticket.mainContact
  • Firma einer Person abrufen: 
    Unit company = mainContact.get("company()");
  • Firma einer Person setzen: 
    mainContact.set("company()", company);
  • Personen, die zu einer Firma gehören, abrufen: 
    List contacts = company.get("contacts()");
  • Vorgänge eines Kontakts abrufen: 
    List tickets = company.get("tickets()");
    List tickets = mainContact.get("tickets()");
  • Namen des Kontaktdatenmodells, das für den Kontakt verwendet wird, abrufen: 
    mainContact.customerDefinition.name
  • Typ eines Kontakts (Person oder Firma) und den Namen der Definition abrufen: 
    mainContact.definition.name
    mainContact.definition.type

Ressourcen​

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

  • Daten abrufen: 
    resource.get("<group name>.<field name>")
  • Daten in ein Feld schreiben: 
    resource.set("<group name>.<field name>", <value>)
  • Wert zu einem Feld hinzufügen (eine neue Zeile zu einem Listenfeld hinzufügen oder mit Daten rechnen): 
    resource.add("<group name>.<field name>", <value>)
  • Feldwert entfernen (den Wert auf null setzen): 
    resource.remove("<group name>.<field name>")

Der Inhalt eines Datenfelds hängt vom Datentyp ab und ist entweder ein Wert oder ein Objekt. Details zum Umgang mit den verschiedenen Datentypen finden Sie im Abschnitt Arbeiten mit verschiedenen Datentypen.

Arbeiten mit verschiedenen Datentypen​

Der folgende Abschnitt zeigt Beispiele für die Arbeit mit Datenfeldern verschiedener Datentypen. Die Beispiele beziehen sich auf Vorgangsfelder, gelten aber auch für Kontakt- und Ressourcenfelder.

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 Vorgangsfeldes abgerufen werden kann, um ihn in einem Entscheidungsskript zu verwenden:

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

if(vip_info == true){
  return true
}
else {
  return false
}

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

return ticket.get("am_fields.vip")

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

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

Wenn Sie mit Feldern des Typs number oder date arbeiten, können Sie sogar bequem mit den Feldwerten rechnen, zum Beispiel, indem Sie Eins zur Anzahl der Bestellungen addieren:

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

Suchen nach Feldwerten​

Sie können mit den Methoden getByCriteria aus den entsprechenden Services (ticketService, unitService und resourceService) über die Werte in Datenfeldern nach Vorgängen, Kontakten und Ressourcen suchen.

Beispiel 1: Suchen nach allen Vorgängen der Queue Helpdesk 1st Level mit der Priorität hoch

def tickets = ticketService.getByCriteria("HelpDesk_1st_Level", [
  "helpdesk_standard:priority": "high"
])

Beispiel 2: Suchen nach allen offenen Vorgängen der Queue Helpdesk 1st Level mit der Priorität hoch

ticketService.getByCriteria("HelpDesk_1st_Level", [
  "helpdesk_standard:priority": "high"
], { ticketCriteria ->
  ticketCriteria.setStatus(TicketCriteria.Status.OPEN)
})

Suchen nach leeren Feldern​

Sie können nach Vorgängen, Kontakten und Ressourcen suchen, bei denen ein bestimmtes Feld nicht gesetzt ist, indem Sie ein null-Kriterium zu den Suchkriterien hinzufügen.

TicketCriteria ticketCriteria = new TicketCriteria();
ticketCriteria.fields = new CustomFieldCriteriaBuilder()
  .set("helpdesk_standard:myBoolean", CriteriaWithCustomFields.NOT_SET_BOOLEAN)
  .build();

Das Objekt, das in CriteriaWithCustomFields genutzt wird, hängt vom Typ des Datenfeldes ab:

  • Boolean: NOT_SET_BOOLEAN
  • Datum: NOT_SET_DATE
  • Festkommazahl: NOT_SET_DECIMAL
  • Sortierte oder hierarchische Liste: NOT_SET_ENUM_VALUE
  • Ganzzahl: NOT_SET_NUMBER
  • Text: NOT_SET_STRING
Verschachtelte Felder

Die Suche nach leeren Feldern funktioniert nur für einfache Felder. Verschachtelte Felder, wie Felder, die zu Listen oder Tabellen gehören, können nur durchsucht werden, wenn das criteria-Objekt mindestens ein anderes Kriterium enthält, das nach einem nicht-leeren Feld sucht, das zum gleichen übergeordneten Feld gehört.

Abrufen und Setzen von Enum-Werten​

Ein Feld des Typs Sortierte Liste ist ein Feld, in dem der Wert einer von mehreren vordefinierten Listenwerten ist, zum Beispiel von einer Liste mit Prioritäten. 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(), oder .name in Groovy, um den technischen Namen des Wertes abzurufen.

def prio = ticket.get("helpdesk_standard.priority")
log.info 'Priority is now ' + prio.getName()

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())

Beim Setzen eines Enum-Wertes muss der zweite Parameter der technische Name eines vorhandenen Enum-Wertes des Enums, das vom Vorgangsfeld referenziert wird, sein.

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

Die gleiche Syntax kann für hierarchische Listen verwendet werden, sofern der technische Name des Enum-Wertes innerhalb der hierarchischen Liste nur einmal vorkommt.

Listen und Tabellen​

Listen und Tabellen sind "Container" für andere Datenfelder. Ein Datenfeld des Typs Liste enthält entweder ein Feld eines einfachen Datentyps oder ein Feld des Typs Spalten, das aus mehreren Feldern mit einfachen Datentypen besteht. Ein Listenfeld kann mehrere Werte enthalten, wobei es für jeden Wert eine Zeile gibt.

Listen​

Jede Zeile einer Liste enthält einen Wert eines einfachen Datentyps. Im folgenden Beispiel ist es ein Vorgangsfeld des Typs Datum, das den Parameter Gehört zu hat, der auf die Liste zeigt.

  • Alle Werte der Liste abrufen: 
    def convs = ticket.get("conversation_data.conversation_list").each() {
      conv ->
        log.info "NEXT DATE is :" + conv
    }
  • Wert an einer bestimmten Listenposition anhand seines Indexes abrufen: 
    def mydate = ticket.get("conversation_data.conversation_list[1]")
  • Neue Zeile zu einer Liste hinzufügen: 
    ticket.add("conversation_data.conversation_list", date)
  • Bestimmten Wert der Liste anhand des Indexes der Listenposition ersetzen: 
    ticket.set("conversation_data.conversation_list[last]", date)

Tabellen (Spalten)​

Die Datenstruktur Spalten, auch Struct genannt, bildet die technische Grundlage für eine Tabellenstruktur mit mehreren Spalten. Die Liste ist das übergeordnete Objekt, das Zeilen enthält. Jede Zeile ist eine Instanz eines struct. Das struct enthält so viele Vorgangsfelder (Tabellenspalten) wie erforderlich.

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

  • das Vorgangsfeld orders_list die Liste darstellt.
  • sich das Vorgangsfeld orders_list innerhalb der Vorgangsfeldgruppe order_data befindet.
  • der Iterator str das struct darstellt.
  • das struct drei Felder hat:
    • orders_hardware ist der Artikel, der bestellt werden soll (sortierte Liste)
    • orders_contact ist die Kontaktperson (Text)
    • orders_number ist die Anzahl der Artikel, die bestellt werden sollen (Ganzzahl)

Es können folgende Methoden verwendet werden:

  • Daten einer Struct-List durch Iteration über die Liste abrufen: 
    def structs = ticket.get("order_data.orders_list").each() { str ->
      log.info("Hardware is " + str.orders_hardware.getName())
      log.info("Contact is " + str.orders_contact)
      log.info("Number is " + str.orders_number)
    }
  • Neue Zeile durch Erstellen eines neuen struct hinzufügen und die benötigten Werte im struct setzen: 
    ticket.add("order_data.orders_list", new Struct()
    .set("orders_hardware", newhardware)
    .set("orders_contact", newcontact)
    .set("orders_number",newnumber)
  • Neuen Wert in einer bestimmten Tabellenzeile über den Index ihrer Position in der Liste setzen: 
    ticket.set("order_data.orders_list[0].contact", "John");
  • Zeile aus der Tabelle durch Setzen der entsprechenden Listenposition auf null entfernen: 
    ticket.set("order_data.orders_list[last]", null);