Unterstützung benutzerdefinierter URLs

Die meisten OTRS-Frontends unterstützen die Automatisierung über benutzerdefinierte URL-Adressen, sei es zur Angabe von Konfigurationsparametern oder zur Automatisierung von Formularen. Dieser Mechanismus kann verwendet werden, um OTRS einfach in bestehende Arbeitsabläufe zu integrieren oder einfach nur einen schnellen, vorkonfigurierten Überblick über die Objekte zu erhalten. Die Anzahl der Anwendungsfälle ist nicht begrenzt.

Auslösen von Aktionen

Aktionen im Agenten-Interface können automatisch über einen speziellen URL-Parameter namens TriggerAction ausgelöst werden. Der unten beschriebene Ansatz funktioniert für jede Aktion, die für die aktuelle Ansicht registriert ist.

Lassen Sie uns zum Beispiel die Aktion Freie Felder ändern auslösen, die in der Ticket-Detailansicht verfügbar ist.

  1. Identifizieren Sie den Slug-Namen der fraglichen Ansicht. Für die Ticket-Detailansicht und das Ticket mit der ID 1 ist dies:

    /agent/ticket/1
    

    Sie können das Ticket über die Ticket-Nummer aufrufen, die Sie auf den Slug-Namen der Ansicht weiterleitet. Wenn das Ticket mit der ID 1 die Ticketnummer 2022042710123456 hat, können Sie diese verwenden:

    /agent/ticket/number/2022042710123456
    
  2. Identifizieren Sie den BusinessObjectType der Ansicht, in der die Aktion ausgelöst werden soll. In unserem Fall, für die Ticket-Detailansicht, ist dies der BusinessObjectType:

    Ticket
    
  3. Gehen Sie zur Systemkonfiguration im Administrator-Interface und suchen Sie nach der betreffenden Aktionsregistrierungs-Einstellung. In unserem Fall ist dies:

    AgentFrontend::Ticket::Action###FreeText
    
  4. Identifizieren Sie den Wert des Schlüssels Komponente in der Einstellung, das ist der Name der Front-End-Komponente. In unserem Fall ist das der Name:

    TicketFreeText
    
  5. Konstruieren Sie den Aktionsbezeichner in Form von <BusinessObjectType>::<Komponente>. In unserem Fall ist dies:

    Ticket::TicketFreeText
    
  6. Hängen Sie einen Abfrageparameter an die URL der Detailansicht mit dem Namen TriggerAction an und setzen Sie ihn auf den Action Identifier, dessen Wert im vorherigen Schritt konstruierte wurde:

    /agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText
    

    Bemerkung

    Im Falle von benutzerdefinierten URL-Abfrageparameterwerten müssen wir darauf achten, alle Sonderzeichen zu kodieren, die normalerweise in URLs verwendet werden (z.B. doppelte Anführungszeichen). Dieser Prozess wird als „URL-Kodierung“ bezeichnet und kann mit jedem frei verfügbaren Online-Tool, wie den Online Text Tools, durchgeführt werden.

Beim Besuch der URL, wie oben konstruiert, wird die Aktion automatisch ausgelöst:

Automatically Triggered Change Free Fields Action

Automatisch ausgelöste Aktion „Freie Felder ändern“

Bemerkung

Bitte beachten Sie, dass alle Einschränkungen, die für die regulären Ansichten gelten, trotzdem eingehalten werden. Zum Beispiel können Sie keine Aktion auslösen, auf die derzeit nicht zugegriffen werden kann, z.B. weil Sie keine Berechtigungen dafür haben, oder weil sie durch die geltenden ACL-Regeln herausgefiltert wurde.

Vorbefüllen von Formularfeldern

OTRS-Formularfelder können mit Werten vorbefüllt werden, die über URL-Abfrageparameter geliefert werden. Der unten beschriebene Ansatz funktioniert für jedes Formular im Agenten und im externen Interface.

Sehen wir uns zum Beispiel an, wie wir das Feld Titel des Aktionsformulars Freie Felder ändern vorbefüllen können, das wir im vorherigen Beispiel ausgelöst haben.

Da diese Aktion zunächst nicht auf der Ansicht angezeigt wird, behalten wir den Parameter trigger action bei und fügen ihn einfach hinzu:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText
  1. Identifizieren Sie den Namen des betreffenden Formularfeldes.

    In unserem Fall haben wir es mit der folgenden Form zu tun:

    Forms###AgentFrontend::Ticket::Action::FreeText
    

    Gemäß der the form fields reference wird das Feld treffend benannt:

    Title
    
  2. Hängen Sie einen Query-Parameter mit dem Namen des Feldes an die URL der Detailansicht an und setzen Sie ihn auf den gewünschten Wert:

    /agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText&Title=Some+text
    

    Bemerkung

    Zusätzliche URL-Abfrageparameter können mit einem kaufmännischen Und-Zeichen (&) verkettet werden.

    Bemerkung

    Im Falle von benutzerdefinierten URL-Abfrageparameterwerten müssen wir darauf achten, alle Sonderzeichen zu kodieren, die normalerweise in URLs verwendet werden (z.B. doppelte Anführungszeichen). Dieser Prozess wird als „URL-Kodierung“ bezeichnet und kann mit jedem frei verfügbaren Online-Tool, wie den Online Text Tools, durchgeführt werden.

Beim Besuch der URL, wie oben konstruiert, wird die Aktion automatisch ausgelöst und das Feld vorbelegt:

Pre-populated Title Field of the Change Free Fields Action

Vorausgefülltes Titelfeld der Aktion „Freie Felder“ ändern

Der Ansatz kann für alle anderen Felder des Formulars wiederholt werden, z.B. wenn wir auch das Feld Service (Feldname ServiceID) auf einen hypothetischen Wert Service 2 mit einer ID von 2 setzen möchten, können wir es so zur bestehenden URL hinzufügen:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText&Title=Some+text&ServiceID=2

Beim Besuch der URL, wie oben konstruiert, wird die Aktion automatisch ausgelöst und beide Felder werden vorausgefüllt:

Pre-populated Title and Service Fields of the Change Free Fields Action

Vorbefüllte Titel- und Service-Felder der Aktion „Freie Felder ändern“

Bemerkung

Bei den meisten Dropdown-Feldern, die Business-Objekte enthalten (z. B. Services, Queues usw.), müssen Sie immer die ID des Objekts angeben, nicht seine Bezeichnung. Sie erkennen diese Formularfelder an dem ID Suffix in ihrem Namen. Sie sollten immer den Wert der Objekt-ID nachschlagen und das Feld auf diesen Wert setzen.

Bemerkung

Bitte beachten Sie, dass alle Einschränkungen, die für die regulären Aktionsfelder gelten, weiterhin berücksichtigt werden. Beispielsweise können Sie keinen Wert auf ein deaktiviertes Feld setzen oder eine Option auswählen, die durch die geltenden ACL-Regeln herausgefiltert wurde.

Übermitteln von Aktionen

Aktionen im Agenten-Interface können automatisch über einen speziellen URL-Parameter namens SubmitForm übermittelt werden. Der unten beschriebene Ansatz funktioniert für jede Aktion, die für die aktuelle Ansicht registriert ist.

Sehen wir uns zum Beispiel an, wie wir das Aktionsformular Freie Felder ändern übermitteln können, das wir bereits in früheren Beispielen ausgelöst und vorausgefüllt haben.

Da diese Aktion zunächst nicht auf der Ansicht angezeigt wird, werden wir den Parameter trigger action sowie einige form field parameters beibehalten und einfach ergänzen:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText&Title=Some+text&ServiceID=2

Hängen Sie einen Query-Parameter an die URL der Detailansicht namens SubmitForm an und setzen Sie 1 als Wert:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText&Title=Some+text&ServiceID=2&SubmitForm=1

Beim Besuch der URL, wie oben konstruiert, wird die Aktion automatisch ausgelöst, beide Felder vorbelegt und die Aktion sofort eingereicht:

Automatically Submitted Change Free Fields Action

Automatisch übermittelte Aktion „Freie Felder ändern“

Bemerkung

Bitte beachten Sie, dass alle Einschränkungen, die für die regulären Aktionsformen gelten, weiterhin eingehalten werden. Beispielsweise können Sie kein ungültiges Formular einreichen, wenn Sie ein Pflichtfeld auslassen oder ein Feld auf einen ungültigen Wert setzen.

Benutzerdefinierte Business-Objekt-Listen

Alle statischen Listen von Business-Objekten im Agent-Interface unterstützen die benutzerdefinierte Konfiguration über einen speziellen URL-Parameter namens Config. Die im Folgenden skizzierte Vorgehensweise funktioniert für ähnliche Ansichten, die unter im folgenden Abschnitt aufgelistet sind, sowie für alle in der YAML-Referenz dokumentierten Schlüssel.

Sehen wir uns zum Beispiel an, wie wir eine aktive Filtervoreinstellung für eine Business-Objektliste festlegen können, indem wir sorgfältig eine direkte URL für die Ansicht konstruieren.

  1. Identifizieren Sie den slug name der betreffenden Ansicht. Wir werden AgentFrontend::TicketList::Static verwenden, die diesen Slug hat:

    /agent/tickets/static
    
  2. Gehen Sie auf Systemkonfiguration im Administrator-Interface und suchen Sie nach der betreffenden Ansicht der Systemkonfigurations-Einstellung, in unserem Fall ist dies:

    AgentFrontend::TicketList::Static###DefaultConfig
    
  1. Stellen Sie sicher, dass der Schlüssel AllowGETConfig in der Ansicht Konfiguration die Eigenschaften FilterPresets und FilterPresetSelected enthält, die wir über den Query-Parameter übergeben werden.

    Um diese Schlüssel ändern zu können, müssen sie in der Liste vorhanden sein, sonst werden sie ignoriert. Weitere Informationen finden Sie in der Schlüsselreferenz.

    Screen Configuration with Defined Allowed Keys

    Ansichtskonfiguration mit definierten erlaubten

  2. Konstruieren Sie eine gültige YAML-Konfiguration, die eine benutzerdefinierte Filtervoreinstellung definiert und als vorgewählt setzt.

    ---
    FilterPresets:
      "Total Tickets":
        CustomerID:
          Value: my-customer@otrs.com
    FilterPresetSelected: "Total Tickets"
    
  3. Konvertieren Sie die YAML-Struktur aus dem vorherigen Schritt in die JSON-Syntax, da YAML für die Übergabe über Parameter ungeeignet ist. Wenn wir dies tun, erhalten wir die folgende analoge Struktur.

    {
       "FilterPresets": {
          "TotalTickets": {
             "CustomerID": {
                "Value": "my-customer@otrs.com"
             }
          }
       },
       "FilterPresetSelected": "Total Tickets"
    }
    
  1. Entfernen Sie den gesamten zusätzlichen weißen Bereich, um diese Konfiguration in eine einzige Zeile zu komprimieren.

    {"FilterPresets":{"Total Tickets":{"CustomerID":{"Value":"my-customer@otrs.com"}}},"FilterPresetSelected":"Total Tickets"}
    
  2. Um die Konfiguration an die Ansicht unter /agent/tickets/static zu übergeben, müssen wir nur einen URL-Abfrageparameter namens Config definieren und die obige JSON-Struktur als seinen Wert festlegen.

    Bemerkung

    Im Falle von benutzerdefinierten URL-Abfrageparameterwerten müssen wir darauf achten, alle Sonderzeichen zu kodieren, die normalerweise in URLs verwendet werden (z.B. doppelte Anführungszeichen). Dieser Prozess wird als „URL-Kodierung“ bezeichnet und kann mit jedem frei verfügbaren Online-Tool, wie den Online Text Tools, durchgeführt werden.

    /agent/tickets/static?Config=%7B%22FilterPresets%22%3A%7B%22Total%20Tickets%22%3A%7B%22CustomerID%22%3A%7B%22Value%22%3A%22my-customer%40otrs.com%22%7D%7D%7D%2C%22FilterPresetSelected%22%3A%22Total%20Tickets%22%7D
    
    Example of the Filter Preset Defined Via URL Query Parameter

    Beispiel für die über URL-Abfrageparameter definierte Filter-Voreinstellung

Bemerkung

Wussten Sie, dass Sie viele frei zugängliche Online-Tools nutzen können, um die oben beschriebenen Umstellungsschritte durchzuführen? Einige von ihnen unterstützen sogar die Verkettung, wie die Online YAML Tools für das obige Beispiel.