Text-Autovervollständigungsskripte

Mit Skripten des Typs Text-Autovervollständigung können Text-Autovervollständigungsfelder implementiert werden. Das sind Textfelder, die eine Liste mit Vorschlägen passend zum eingegebenen Text anzeigen.

Text-Autovervollständigungsfelder bieten viele Vorteile:

• Referenzieren Sie Vorgänge, Kontakte, Ressourcen oder Benutzer, die in ConSol CM gespeichert sind
• Suchen Sie innerhalb der Listenwerte
• Fügen Sie kundenspezifische Logik zur Bestimmung der auswählbaren Werte hinzu

Anwendungsbeispiele für Text-Autovervollständigungsfelder:

• Erstellen eines Feldes, das den verantwortlichen Benutzer eines Kontakts enthält
• Text-Autovervollständigungsfelder als Hilfe für das Erstellen von Relationen in einem Aktivitätsformular
• Speichern des Namens des Benutzers, der Benachrichtigungen zu einem Vorgang erhalten soll

Schritte zur Verwendung eines Text-Autovervollständigungsskripts:

1. Schreiben Sie auf der Seite Skripte ein Skript des Typs Text-Autovervollständigung, siehe Erstellen des Text-Autovervollständigungsskripts.
2. Erstellen Sie das Datenfeld, für das das Skript verwendet werden soll, siehe Erstellen des Datenfeldes.

Beschränkungen

Diese neue Methode der Konfiguration von Text-Autovervollständigungsfeldern ersetzt die alte Methode, die die Einstellung Textdarstellung mit dem Wert Autocomplete verwendet hat. Vorhandene Felder, die die alte Methode verwenden, bleiben funktionsfähig. Diese Felder werden bei einer Aktualisierung nicht verändert. Die vorher verwendete Methode onEditDisplayEntered funktioniert für vorhandene Felder weiterhin. Sie wird allerdings nicht mehr benötigt und in einer zukünftigen Version von ConSol CM entfernt.

Bei der Verwendung der neuen Methode zum Konfigurieren von Text-Autovervollständigungsfeldern gibt es folgende Einschränkungen:

• Keine Übertragung an das DWH. Text-Autovervollständigungsfelder werden nicht an das DWH übertragen und können nicht in Berichten verwendet werden.
• Keine Unterstützung von ETL. Der Import und Export von Text-Autovervollständigungsfeldern mittels ETL wird nicht unterstützt.
• Text-Autovervollständigungsfelder können nicht indiziert werden. Sie stehen daher in Suchen nicht zur Verfügung.
• Wenn ein Objekt, das in einem Text-Autovervollständigungsfeld referenziert wird, gelöscht wird, kann das Feld auf ein nicht existierendes Objekt zeigen. Dies muss berücksichtigt werden, wenn der Feldwert später in Skripten verwendet wird.
• Text-Autovervollständigungsfelder können nicht in Textvorlagen und Dokumentvorlagen verwendet werden.

Informationen über die bisherige Art und Weise, Text-Autovervollständigungsfelder zu konfigurieren, finden Sie im ConSol CM Administratorhandbuch der Version 6.11.1.0.

Berechtigungen in Text-Autovervollständigungsfeldern

Die Berechtigungen werden während der Ausführung des Text-Autovervollständigungsskripts beim Editieren des Felds im Web Client oder CM/Track überprüft, d. h. der Benutzer kann nur Einträge sehen und auswählen, die zu Objekten gehören, die er mit den ihm zugewiesenen Rollen sehen darf. Beim Anzeigen von Text-Autovervollständigungsfeldern findet keine Überprüfung der Berechtigungen statt. Das bedeutet, dass der Benutzer in Text-Autovervollständigungsfeldern und Protokolleinträgen Bezeichnungen sehen könnte, die sich auf Objekte beziehen, für die er keine Berechtigung hat.

Permissions in CM/Track:

Berechtigungen für Text-Autovervollständigungsfelder funktionieren wie im Web Client. Spezifische Einschränkungen für CM/Track, insbesondere die Einschränkung, dass der Benutzer nur seine eigenen Vorgänge (oder Vorgänge anderer Personen seiner Firma, sofern konfiguriert) und Personen seiner Firma sieht, gehören nicht zur Standardkonfiguration. Dies bedeutet, dass der Benutzer standardmäßig die Berechtigung hat, Einträge zu sehen und auszuwählen, die sich auf Vorgänge beziehen, die sich in Queues befinden, für die der Track-Benutzer mindestens Leseberechtigungen hat, und die sich auf Kontakte beziehen, die Kundengruppen angehören, für die der Track-Benutzer mindestens Leseberechtigungen hat. Zusammengefasst, der Kunde würde Daten sehen, die zu anderen Kunden gehören. In Anpassen der Berechtigungen für CM/Track ist beschrieben, wie dies vermieden werden kann.

Erstellen des Text-Autovervollständigungsskripts

Text-Autovervollständigungsfelder speichern zwei Werte:

• Interner Wert: Der interne Wert hängt vom Feldtyp ab. Bei Feldern des Typs Vorgang, Kontakt, Ressource oder Benutzer ist es die Referenz auf das entsprechende Objekt. Bei Feldern des Typs Text ist es der Text selber.
• Anzeigewert: Der Anzeigewert ist der Wert, der den Benutzern im Web Client oder in CM/Track angezeigt wird. Für den Anzeigewert gibt es zwei Optionen:
  • Dynamisch: Der Anzeigewert wird aus dem referenzierten Objekt selber abgerufen. Wenn das referenzierte Objekt verändert wird, wird der Anzeigewert entsprechend aktualisiert.
  • Statisch: Der Anzeigewert ist ein String, der im Skript definiert ist. Dies kann ein Wert des referenzierten Objekts sein oder ein beliebiger anderer Text. Der Anzeigewert ändert sich nicht, wenn das referenzierte Objekt verändert wird.

Dynamische Anzeigewerte verwenden Templates für die Darstellung in der Vorschlagsliste und im Datenfeld. Die folgenden Templates werden verwendet:

• Benutzer: engineer description template name
• Kontakte: Kundensuchergebnis-Template. Wenn nicht vorhanden, wird das Standard-Template verwendet.
• Ressourcen: Suche-Template. Wenn nicht vorhanden, wird das Standard-Template verwendet.
• Vorgänge: Festes internes Template mit dem Namen und Thema des Vorgangs.

Struktur des Skripts

Das Skript muss die Methode onSearchInput implementieren. Diese Methode hat zwei Signaturen, eine für normale Datenfelder und eine für Datenfelder, die zu Listen gehören. Wenn Sie ein neues Skript des Typs Text-Autovervollständigung erstellen, wird die Vorlage der Methode automatisch eingefügt, sodass Sie die korrekte Methode leicht finden können.

Das Skript muss ein Objekt der Klasse ScriptAutocompleteResult zurückgeben, das die Suchergebnisse enthält. Die Objekte, die als Suchergebnisse hinzugefügt werden, müssen dem Objekttyp entsprechen, der für das Datenfeld definiert ist (siehe Erstellen des Datenfeldes), d. h. Sie können entweder Vorgänge oder Kontakte oder Ressourcen oder Benutzer oder Strings hinzufügen.

Die Meldung, die standardmäßig angezeigt wird, wenn die Suche keine Ergebnisse liefert, ist Keine Suchergebnisse. Mit der Methode noResults('String') können Sie die Meldung anpassen, z. B.:

return ScriptAutocompleteResult.noResults('No matching engineers found')

Methoden zum Hinzufügen von Werten zur Liste

Der Typ des Anzeigewerts (statisch oder dynamisch) hängt von der Methode ab, die verwendet wurde, um die Werte zur Liste hinzuzufügen.

Zuerst erstellen Sie ein Objekt der Klasse ScriptAutocompleteResult.

ScriptAutocompleteResult resultset = new ScriptAutocompleteResult();

Fügen Sie danach mit einer der folgenden Methoden Werte zur Liste hinzu:

• Statische Anzeigewerte: Fügen Sie neue Elemente zur Liste hinzu, indem Sie das Objekt und einen String mit dem Anzeigewert als Parameter übergeben:

  resultset.add(ticket, ticket.getSubject());
  // or
  resultset.add(ticket, "my display value");

• Dynamische Anzeigewerte: Fügen Sie neue Elemente zur Liste hinzu, indem Sie das Objekt als Parameter übergeben:

  resultset.add(ticket);

Details über die Methoden-Signaturen finden Sie in der ConSol CM API Dokumentation der Klasse ScriptAutocompleteResult.

Anwendungsfälle für das Zurückgeben von Strings

Es gibt zwei zusätzliche Anwendungsfälle für Objekte des Typs ScriptAutocompleteResult, die Strings enthalten:

• Suche in externen Quellen, z. B. in einer externen Datenbank
• Anzeige einer Meldung, dass der Benutzer eine bestimmte Anzahl von Zeichen eingeben muss, um die Suche zu starten

Arbeiten mit dem Kontext

Sie können die Variable pContext verwenden, um das Objekt abzurufen, zu dem das Datenfeld gehört. Der Inhalt von pContext hängt vom Typ des Objekts ab.

• Vorgang: pContext.ticket enthält das aktuelle ticket-Objekt
• Kontakt: pContext.unit enthält das aktuelle unit-Objekt
• Ressource: pContext.resource enthält das aktuelle resource-Objekt
• Alle Objekte: controlForm und formFields enthalten das Aktions- oder Aktivitätsformular, bzw. eine Map mit den Datenfeldern und ihren Werten im Formular

Dadurch können Sie die Suchergebnisse so beeinflussen, dass sie das Objekt, zu dem das Text-Autovervollständigungsskript gehört (Vorgang, Kontakt oder Ressource), berücksichtigen.

Anpassen der Berechtigungen für CM/Track

Die Klasse customerSecurityCriteriaBuilder enthält Methoden, um das Verhalten von Text-Autovervollständigungsfeldern an die standardmäßigen Berechtigungen in CM/Track anzupassen, sodass die Benutzer nur Ergebnisse sehen können, die sich auf ihre Vorgänge oder Personen, die zu ihrer Firma gehören, beziehen.

Das folgende Beispiel zeigt, wie die Suchergebnisse eines in CM/Track verwendeten Text-Autovervollständigungsfelds auf die Vorgänge beschränkt werden können, die dem Benutzer gehören.

ScriptAutocompleteResult onSearchInput(String pSearchStr, FieldKey pKey, Context pContext) {
  def result = new ScriptAutocompleteResult();
  def criteria= new TicketCriteria();
  criteria.setPattern(pSearchStr+ "*");
  customerSecurityCriteriaBuilder.setMyCaseCriteria(criteria);
  for (Ticket ticket : ticketService.getByCriteria(criteria)) {
    result.add(ticket);
  }
  return result;
}

Programmierbeispiel

Das folgende Beispielskript implementiert ein Text-Autovervollständigungsfeld, das Suchergebnisse für Ressourcen enthält. Die Variable pSearchStr wird verwendet, um zu prüfen, wie viele Zeichen eingegeben wurden. In diesem Beispiel zeigt die Drop-down-Liste eine Meldung an, dass mindestens drei Zeichen erforderlich sind, wenn der Benutzer nicht genügend Zeichen eingibt, um die Suche zu starten. Wenn keine Ergebnisse gefunden werden, wird eine benutzerdefinierte Meldung angezeigt. Ansonsten enthält die Drop-down-Liste die Suchergebnisse. Das Skript arbeitet mit dynamischen Anzeigewerten.

import com.consol.cmas.common.model.autocomplete.script.*

/**
* This method is called by web client when the user clicks or types into the autocomplete field
* @param pSearchStr the search String types or NULL if user clicked into field without typing
* @param pKey fieldKey
* @param pContext (Ticket/Unit/Resource) holder. More about this later in the specification (Context section)
*/

ScriptAutocompleteResult onSearchInput(String pSearchStr, FieldKey pKey, Context pContext) {
  ScriptAutocompleteResult resultset = new ScriptAutocompleteResult();
  // Add matching resource when entering more than 2 characters
  if (pSearchStr.length() < 3) {
    return new ScriptAutocompleteResult("NOTE: Please enter at least 3 characters!");
  } else {
    ResourceCriteria criteria = new ResourceCriteria();
    criteria.setPattern("*"+pSearchStr+"*")
    def resources = resourceService.getByCriteria(criteria)
    if(resources.size() < 1){
      return ScriptAutocompleteResult.noResults('No matching resources found')
    } else {
      resultset.add(resources);
    }
  }
  return resultset;
}

Erstellen des Datenfeldes

Text-Autovervollständigungsfelder können in Vorgangs-, Kontakt- und Ressourcenfeldern verwendet werden. Gehen Sie folgendermaßen vor, um ein neues Text-Autovervollständigungsfeld zu erstellen:

1. Öffnen Sie die Seite Vorgangsfelder, Kontaktfelder oder Ressourcenfelder.
2. Erstellen Sie ein Feld mit dem Datentyp Autocomplete.
3. Wählen Sie das gewünschte Objekt aus der Drop-down-Liste Typ. Die verfügbaren Optionen sind Vorgang, Kontakt, Ressource, Benutzer oder Text.
4. Wählen Sie das Skript in der Drop-down-Liste Skript. Es sind nur Skripte des Typs Text-Autovervollständigung verfügbar, siehe Erstellen des Text-Autovervollständigungsskripts.

Arbeiten mit den Werten von Autocomplete-Feldern

Der Wert eines Text-Autovervollständigungsfelds gehört zur Klasse AutocompleteValue. Er kann über die Methoden getInternalValue() und getDisplayValue() dieser Klasse abgerufen werden.

Das folgende Beispiel zeigt, wie der Wert des Text-Autovervollständigungsfelds engineers_autocomplete in die Log-Datei geschrieben wird. Das Feld enthält eine Referenz auf einen Benutzer und gehört zu einem Vorgang.

// display engineer of ticket field (not engineer field in header!)
def ticket = workflowApi.ticket

AutocompleteValue myAutocompleteValue = ticket.get("serviceDesk_fields.engineers_autocomplete")
def intValue = myAutocompleteValue.getInternalValue()
log.info 'The internal value is ' + intValue
def dispValue = myAutocompleteValue.getDisplayValue()
log.info 'The display value is ' + dispValue

Um die Werte eines Text-Autovervollständigungsfelds zu setzen, müssen Sie ein Objekt der Klasse AutocompleteValue mit dem internen Wert und dem Anzeigewert erstellen. Verwenden Sie die Methode setDynamicDisplayValue(true), um ein Feld mit einem dynamischen Anzeigewert zu erstellen.

Das folgende Beispiel zeigt, wie der Benutzer Susan ServiceDesk mit der ID 26 unter Verwendung eines dynamischen Anzeigewerts im Vorgangs-Autovervollständigungsfeld engineers_autocomplete referenziert wird.

def ticket = workflowApi.ticket

myAutocompleteValue = new AutocompleteValue()
myAutocompleteValue.setInternalValue("26")
myAutocompleteValue.setDynamicDisplayValue(true)

ticket.set("serviceDesk_fields.engineers_autocomplete", myAutocompleteValue);