Skip to main content

Zusammenstellen Ihrer Aktionsabfolge

Abfolge erstellen

Die Aktionsabfolgenkarte sieht teilweise so aus wie die Aktionskarten für E-Mails und HTTP-Requests. Sie geben an, ob und wo die Aktionsabfolge aktiv sein soll und verknüpfen Ereignisse.

In diesem Thema wird lediglich erklärt, wie die Aktionsabfolge erstellt wird. Weitere Informationen zur Vorbereitung auf die Erstellung einer Aktionsabfolge und zu den verschiedenen Tools, die Ihnen zur Verfügung stehen, finden Sie unter Aktionsabfolgen.

Um eine Abfolge zu erstellen:

  1. Öffnen Sie die neue automatisierte Aktion auf eine der folgenden Arten:

    • Gehen Sie zu Module > Aktionsmanagement > Automatisierte Aktionen und klicken Sie auf Neue automatisierte Aktion.

    • Gehen Sie zu Module > Aktionsmanagement > Neu > Automatisierte Aktion.

  2. Wählen Sie im Menü Neue automatisierte Aktion den entsprechenden (Karten-) Typ.

  3. Klicken Sie auf Aktion erstellen.

    Die neue Aktion wird in einem neuen Tab geöffnet.

  4. Klicken Sie oben hinter ‚Neue Aktion‘ auf das Stiftsymbol, um einen Namen für die Aktion einzugeben.

  5. Legen Sie fest, wann die Aktion ausgelöst werden soll. Sie können dies später ändern.

    Anmerkung

    Bei den meisten Kartentypen können Sie Ereignisse auswählen und Kontextmenüs auswählen. Für einige sind nur Ereignisse verfügbar. Für das Assetmanagement wählen Sie Auslösertypen und bestimmte Kartentypen aus. Unter Ereignisse erstellen erfahren Sie mehr über das Einrichten von Ereignissen für Ihre Aktionen.

    Tipp

    Verwenden Sie die Schaltfläche Ereignis bearbeitenlightning bolt, um jedes im Menü Ereignisse auswählen verfügbare Ereignis zu öffnen.

    1. Klicken Sie auf Ereignisse auswählen, Kontextmenüs auswählen oder Kartentypen auswählen, je nachdem, welchen Kartentyp Sie gewählt haben.

    2. Suchen Sie nach Ereignissen, oder durchsuchen Sie die Liste.

    3. Wenn Sie das Menü Ereignisse auswählen verwenden, können Sie auch die Schaltfläche Ereignis bearbeitenlightning bolt verwenden, um jedes verfügbare Ereignis zu öffnen.

    4. Markieren Sie jene Ereignisse, die Sie mit der Aktion verknüpfen wollen.

    5. Klicken Sie auf Übernehmen.

    Sie haben Auslöser für Ihre Aktion gewählt. Die Auslöser werden unter dem Namen der Kartenart angezeigt und können durch Klicken auf das x-Symbol wieder entfernt werden. Sie können diese Auswahl zu einem späteren Zeitpunkt jederzeit wieder aufgreifen.

  6. Klicken Sie auf Konfigurieren der Aktion.

  7. Wählen Sie unter Was möchten Sie auslösen? die Option Aktionsabfolge.

    Anmerkung

    Wenn Sie eine der anderen Optionen wählen, können Sie diese später in eine Aktionsabfolge einbauen.

  8. Setzen Sie bei Bedarf Variablen und Wertzuordnungen.

  9. Erstellen Sie die verschiedenen Schritte der Abfolge, indem Sie eine der Optionen für Schritte hinzufügen. Jeder HTTP-Schritt enthält:

    1. Einen Namen. In darauf folgenden Schritten verwenden Sie diesen Namen, um sich auf die Antwort auf diesen Schritt zu beziehen. Der Name darf nur Buchstaben, Zahlen und Unterstriche enthalten, also keine Leerzeichen. Er darf nicht mit einer Zahl beginnen.

    2. Die HTTP-Methode: GET, POST, PUT, PATCH oder DELETE.

    3. Die URL des Endpunkts. Dies und die Inhalte der Felder "Header" und "Body" werden in den Abschnitten Die URL und Header und Der Body erläutert.

    4. Ein oder mehrere Header. Klicken Sie auf die Schaltfläche plus, um einen Header hinzuzufügen.

    5. Wenn Sie POST, PUT oder PATCH verwenden: der Body. Geben Sie den Body des Requests hier ein.

    6. Eine Ausführungsregel. Geben Sie an, ob alle Schritte immer oder nur dann ausgeführt werden sollen, wenn alle vorherigen Schritte erfolgreich waren, oder nur unter einer bestimmten Bedingung. Ist letzteres der Fall, richten Sie eine Bedingung in Freemarker ein. Dieser Schritt wird ausgeführt, wenn der Ausgabewert von FreeMarker 'true' ist, und übersprungen, wenn der Wert 'false' oder '' (leer) ist. Ein Beispiel dafür erhalten Sie unter Benutzerdefinierte Bedingung zur Ausführung eines Schrittes einrichten

    Anmerkung

    Weitere Optionen sind ein E-Mail-Schritt, ein Schritt zum Generieren von Dokumenten, ein Wiederholungsschrittund ein Schritt zur Variablenzuweisung.

  10. Erfassen Sie im Beschreibungsfeld, was bei jedem Schritt erledigt wird. Die Namen der verschiedenen Schritte können nicht ausreichen, um auf einen Blick zu erkennen, was die Abfolge genau macht.

  11. Speichern Sie die Karte.

  12. Klicken Sie auf Ihre Automatisierte Aktion abschließen, um fortzufahren.

  13. Wenn die Aktion bereits einsatzbereit ist, klicken Sie auf Aktion aktivieren. Damit die Aktion funktioniert, markieren Sie Anwenden im Self Service Portal und/oder Anwenden im Bearbeiterbereich.

  14. Speichern Sie die Karte.

Sie haben eine Aktionsabfolge erstellt. Lösen Sie das Ereignis aus, um zu sehen, ob es funktioniert.

Anmerkung

Stellen Sie sicher, dass das letzte Zeichen in einem Feld kein Leerzeichen ist. Die Abfolge funktioniert nicht, wenn der Inhalt eines Feldes mit einem Leerzeichen endet.

Tipp

Tools wie RequestBin und Postman sind nützlich, um zu sehen, wie ein Request für das empfangende Programm aussieht.

Im folgenden Beispiel wird ein Incident in TOPdesk erstellt:

example for action sequence.

Beispiel für die Angabe, welcher JSON- oder XML-Wert verwendet werden soll

Schauen wir uns ein Beispiel an, um herauszufinden, wie man das Eingabefeld Angeben, welchen JSON- oder XML-Wert Sie aus dem Request-/Antwort-Body übernehmen möchten korrekt ausfüllt.

Mit einem vorherigen Schritt haben wir einen Antwort-Body erhalten. Durch die Verwendung von Websites wie JSONLint wird die Antwort automatisch so formatiert, dass die Struktur klarer wird. Dadurch erhalten Sie einen besseren Einblick, welche Werte in bestimmten Blöcken verschachtelt sind, was wichtig ist, um den richtigen Wert in Ihrem nächsten Schritt der Aktionsabfolge zu finden und zu verwenden.

Beispiel 1: Verschachtelter Wert

In einem früheren Schritt unserer Aktionsabfolge haben wir den folgenden Antwortbody erhalten. Wenn Sie diesen ersten Schritt erfolgreich getestet haben, befindet sich der Antwortbody in den Ausführungsprotokollen der Aktionsabfolge. Suchen Sie dazu nach Antwortbody: und kopieren Sie die Daten dahinter. Nachfolgend sehen Sie einen solchen Antwortbody, der in diesem Fall bereits mit JSONLint formatiert wurde:

{
  "id": "27f69cfe-2855-4250-b166-b6b8d9d12193",
  "status": "firstLine",
  "number": "I 2204 150",
  "request": "02-04-2022 10:30 [GMT +2:00] John Smith: \nThe coffee machine does not work anymore",
  "requests": "/tas/api/incidents/id/27f69cfe-2855-4250-b166-b6b8d9d12193/requests",
  "action": "/tas/api/incidents/id/27f69cfe-2855-4250-b166-b6b8d9d12193/actions",
  "attachments": "/tas/api/incidents/id/27f69cfe-2855-4250-b166-b6b8d9d12193/attachments",
  "caller": {
      "id": "8a3956ef-d07d-4b67-816a-c432ef54e0ed",
      "dynamicName": "John Smith",
      "phoneNumber": "0610101010",
      "email": "jsmith@topdesk.com",
      "branch": {
          "id": "794fdd0c-254f-4991-b32c-8dcce199ab9f",
          "name": "TOPdesk USA",
          }
      }
}

Um das Feld Angabe des JSON- oder XML-Wert der aus dem Request-/Antwort-Body gelesen werden soll korrekt auszufüllen, beginnen Sie mit einem ., gefolgt von einem Wertnamen der ersten Ebene. In diesem Fall finden wir auf der ersten Ebene id, Status, Nummer, Request, Requests, Aktion, Anhänge und Melder.

Wenn wir Melder wählen, müssen wir eine Ebene tiefer gehen, um TOPdesk mitzuteilen, welche Informationen über den Melder wir verwenden wollen. Für jede Ebene, die wir tiefer gehen, fügen wir ein weiteres . in unser Eingabefeld ein.

Nehmen wir an, wir müssen den Namen der Niederlassung des Melders verwenden. Im obigen JSON-Beispiel sehen wir, dass wir zum Melder (erste Ebene) gehen müssen, dann zur Niederlassung (zweite Ebene), zum Namen (dritte Ebene). Am Ende ergibt dies die folgende Eingabe:

.caller.branch.name

Die von TOPdesk umgewandelt wird in:

${_responses["stepname"]["body"].call.caller.branch.name}

Eine alternative Notationsmethode sieht wie folgt aus:

${_responses["stepname"]["body"]["call"]["caller"]["branch"]["name"]}

Beispiel 2: Aufgelistete Werte

Nicht alle Requests führen zu einer Antwort mit der gleichen Struktur. Im obigen Beispiel geht es zwar um Informationen zu nur einer Incidentkarte, aber manchmal erhält man auch eine Liste ähnlicher Werte (oder Karten). Nachstehend finden Sie ein Beispiel mit einer Liste der möglichen Statuswerte:

{
    {
    "id": "1b79a18e-d912-4e7f-861a-730402ad1c58",
    "name": "Registered",
    "onHold": "NOT_ON_HOLD",
    "processingState": "NOT_COMPLETED",
    "response": "NOT_RESPONDED",
    "default": false
    },
    {
    "id": "8a2a122e-cc63-41e2-92bd-5b9da1772aa0",
    "name": "Planned",
    "onHold": "NOT_ON_HOLD",
    "processingState": "NOT_COMPLETED",
    "response": "RESPONDED",
    "default": false
    },
    {
    "id": "ed5af114-0f70-4b40-8268-95135f6e66dc",
    "name": "In progress",
    "onHold": "NOT_ON_HOLD",
    "processingState": "NOT_COMPLETED",
    "response": "NOT_RESPONDED",
    "default": false
    }
}

In diesem Fall führen wir die gleichen Schritte aus wie im vorherigen Beispiel. Zuvor müssen wir TOPdesk jedoch mitteilen, welchen Eintrag in dieser Liste wir uns ansehen wollen. Geben Sie dazu [x] ein, wobei x für den gewünschten Eintrag steht. Der erste Eintrag ist 0, der zweite ist 1 usw.

Wenn wir in diesem Beispiel den Namen des zweiten Eintrags verwenden wollen, geben wir folgendes ein:

[1].name

Daraus ergibt sich:

${_responses["stepname"]["body"][1].name}

Umgang mit Fehlermeldungen bei Aktionen

Wenn eine Aktion nicht vollständig ausgeführt werden kann, wird eine Fehlermeldung in den Ausführungsprotokollen angezeigt. Das Protokoll enthält Daten darüber, wann die Aktion ausgeführt wurde (auch bei erfolgreichen Aktionsabfolgen) und für welche Karten die Aktion durchgeführt wurde. Es werden maximal 50 erfolgreiche und erfolglose Ausführungen gespeichert, bevor die ältesten Protokolleinträge gelöscht werden.

Um die Ausführungsprotokolle zu öffnen:

  1. Öffnen Sie eine Aktion in der Übersicht der automatisierten Aktionen.

  2. Klicken Sie auf Ausführungsprotokolle öffnen.

    Sie haben die Ausführungsprotokolle Ihrer Aktion geöffnet.

Auf der linken Seite wird eine Liste der Ausführungen angezeigt. Klicken Sie auf einen Protokolleintrag, um die Ausführungsprotokolle einer bestimmten Ausführung anzuzeigen. Auf der rechten Seite erscheinen die Protokolle der gewählten Ausführung und können analysiert werden. Sie können die automatische Aktualisierung der Seite aktivieren (oder deaktivieren) und die Liste der Ausführungen nach ihrem Status filtern.

Wird für eine bestimmte Karte eine Aktion ausgeführt, finden Sie direkt über der Zusammenfassung und den Angaben einer Ausführung einen klickbaren Link zur Karte.

Die angezeigten Ausführungsdaten werden standardmäßig in UTC-Zeit angezeigt. Dies kann nicht geändert werden.

Berechtigungen

Damit Protokolleinträge zugänglich sind, muss einem Bearbeiter die Berechtigung Ausführungsprotokolle lesen (im Block Aktionsmanagement - Automatisierte Aktionen) zugewiesen sein.

Ausführung abbrechen

Steht die Ausführung einer Aktion auf „In der Warteschleife“ oder ist sie „In Bearbeitung“, erscheint unter dem Abschnitt Ausführungsprotokolle eine Schaltfläche Ausführung abbrechen.

Abort execution button under 'Execution logs' header.

Wenn Sie eine bereits laufende Ausführung abbrechen, wird diese nach Beendigung des aktuellen Schritts angehalten.

[Aktionsmanagement] API-Statuscodes

Bei der Fehlersuche in Ihrer Aktionsabfolge suchen Sie zuerst nach Informationen, warum ein bestimmter Schritt nicht funktioniert. Die Ausführungsprotokolle von TOPdesk beinhalten Einzelheiten zu jedem Schritt einer Abfolge, einschließlich, was korrekt und was falsch gelaufen ist.

Jedes durchgeführte Request wird einen HTTP-Statuscode beinhalten. Diese Statuscodes sind standardisiert und bedeuten somit in jeder Anwendung das gleiche. Eine ausführliche Liste sämtlicher HTTP-Statuscodes finden Sie auf der Wikipedia-Seite der HTTP-Statuscodes.

In diesem Thema werden wir einige der häufigeren Fehlercodes behandeln.

Kein Ausführungsprotokoll?

Sollte kein Ausführungsprotokoll vorhanden sein, wurde die Aktion nicht ausgelöst. In diesem Fall sollten Sie beim Auslöser auf Fehlersuche gehen.

Wahrscheinlich ist der Inhalt des Requests ungültig. Meistens werden zusätzliche Informationen angegeben, da dieser Statuscode nicht nur eine bestimmte Ursache hat. Einige Optionen sind:

  • Das Feld [...] existiert nicht: Der Feldname könnte falsch geschrieben sein, noch kein Teil dieses API sein, oder noch nicht in Ihrer TOPdesk-Version verfügbar sein.

  • Request kann nicht gelesen werden: Es sind zu viele oder wenige Leerzeichen, (Rückwärts-)Schrägstriche, Anführungszeichen, etc. vorhanden, oder Sie versuchen, ein Feld mit einem PUT- oder PATCH-Request zu aktualisieren, was nicht über das API durchgeführt werden kann.

  • Die [...]-ID kann nicht gelesen werden: Eine einzigartige ID beinhaltet keine Bindestriche, oder ist allgemein ungültig.

  • Der Wert des Felds [...] kann nicht gelesen werden: Falls der Inhalt eines Felds ein Sonderzeichen enthält (bspw. "), welches escaped werden muss, indem ein Rückwärtsschrägstrich vorangestellt wird (\"). Eine weitere Möglichkeit ist, dass der Inhalt des Datumsfelds nicht das Format jjjj-MM-ttTHH:mm:ssZ (z. B. 2023-01-01T09:00.00Z) aufweist.

Bei jedem Request, also prinzipiell jedem Schritt einer Aktionsabfolge, müssen Sie TOPdesk die Anmeldeinformationen der Bearbeiterkarte bereitstellen, die für das Request benutzt werden soll. Diese müssen korrekt sein: der Benutzername und ein gültiges Anwendungskennwort.

Genau wie bei normalen Bearbeitern muss auch die Bearbeiterkarte zur Verwendung im API-Request über ausreichende Berechtigungen verfügen, um eine bestimmte Aktion ausführen zu dürfen. Dieser Fehler wird allgemein durch unzureichende Berechtigungen ausgelöst, kann aber auch durch einen Filter entstehen, welcher verhindert, dass der Bearbeiter auf alle relevanten Karten zugreifen kann. Vergewissern Sie sich auch, dass Hat Zugriff und (idealerweise) API-Konto auf der Bearbeiterkarte aktiviert sind.

Ein 404 Statuscode gibt an, dass die Seite nicht gefunden werden konnte. Üblicherweise deutet das auf einen Schreibfehler in der URL hin (z. B. https:// fehlt, oder Großbuchstaben wurden falsch verwendet), oder die einzigartige ID einer Karte ist falsch.

Dies ist eine sehr generische Fehlermeldung. In TOPdesk erscheint diese Fehlermeldung meist, wenn zwei Aktionen versuchen, eine Karte gleichzeitig zu bearbeiten.