Hintergrundaufträge

Manche Arbeit dauert länger als eine Anfrage: eine Website einlesen, das Wissen nachrechnen, einen Shop abgleichen, Mails und Webhooks zustellen, die Prüffragen eines Assistenten durchlaufen. XICBOT nimmt solche Arbeit als Hintergrundauftrag an, antwortet sofort und erledigt den Auftrag danach. Diese Seite beschreibt, welche Aufträge es gibt, in welcher Reihenfolge sie an die Reihe kommen, was bei einem Fehler geschieht und wie lange ein Auftrag gespeichert bleibt.

Was im Hintergrund läuft

Jeder Auftrag hat eine Art (task), eine Bahn und eine Priorität. Die Bahn ergibt sich aus der Art, die Priorität legt die Stelle fest, die den Auftrag anlegt. Eine kleinere Zahl heißt: früher an der Reihe.

Wann der tägliche Auffrischungslauf, der stündliche Shopabgleich und die Wochenauswertung anlaufen, steht unter Zeitpläne.

Bahnen und Reihenfolge

Die Bahn index trägt die langen Läufe: Einlesen, Nachrechnen, Einrichtung, Abnahmeläufe und Shopabgleich. Die Bahn default trägt alles Übrige, also Mails, Webhooks und die Wochenauswertung. Die Trennung soll verhindern, dass eine Mail oder ein Webhook minutenlang hinter einem Einlesen wartet.

Auf jeder Bahn nimmt XICBOT den wartenden Auftrag mit der kleinsten Prioritätszahl, bei gleicher Zahl den älteren. Ein Auftrag, der nach einem Fehlversuch seine Wartezeit absitzt, wird bis zu deren Ende übergangen.

Zustände eines Auftrags

Wiederholung nach einem Fehler

Ein Auftrag hat bis zu drei Versuche. Ein Versuch zählt, sobald XICBOT den Auftrag aufnimmt. Scheitert er und sind Versuche übrig, geht der Auftrag mit einer Wartezeit zurück auf pending. Scheitert der dritte Versuch, steht der Auftrag endgültig auf failed. Der Fehlertext bleibt am Auftrag, gekürzt auf 500 Zeichen. Ein endgültig gescheiterter Auftrag erzeugt für den Betrieb eine kritische Meldung der Quelle queue, siehe Meldungen.

Was als Fehlschlag zählt

• Einlesen: Steht die Quelle nach dem Lauf nicht auf fertig, ist der Versuch gescheitert. Jeder gescheiterte Versuch löst das Webhook-Ereignis knowledge.failed aus, ein gelungener knowledge.indexed mit der Zahl der Dokumente und Abschnitte. Scheitert der Aufbau nach dem Abruf, steht die Quelle auf nicht aufgenommen mit dem Grund ingest_failed, und der bisherige Inhalt antwortet weiter. Ist die Quelle inzwischen gelöscht, gilt der Auftrag ohne Ausführung als erledigt; sein Ergebnis trägt skipped mit source_deleted.
• Abnahme: Ist der Prüflauf mit seinem Assistenten gelöscht, gilt der Auftrag ohne Ausführung als erledigt (skipped mit run_deleted). Scheitert der Auftrag endgültig, wird er geborgen oder verfällt er, steht der Prüflauf auf abgebrochen mit dem Grund job_failed, siehe Probierdialog und Abnahme.
• Webhook: Nur eine Antwort mit Status 2xx gilt als zugestellt. Einer Weiterleitung (3xx) folgt XICBOT nicht, sie zählt als Fehlschlag, ebenso eine Antwort, die länger als 8 Sekunden braucht. Ist der Webhook inzwischen gelöscht oder abgeschaltet oder enthält das Paket die Funktion für Schlüssel und Webhooks nicht mehr, gilt der Auftrag ohne Zustellung als erledigt.
• Abschalten eines Webhooks: Nach 20 gescheiterten Zustellversuchen in Folge schaltet XICBOT den Webhook ab; jeder Wiederholungsversuch zählt mit. Eine gelungene Zustellung setzt den Zähler zurück.
• Mail: Ist eine Mail bereits als versendet vermerkt, geht sie bei einem weiteren Versuch nicht noch einmal hinaus. Eine Mail zu einer Übergabe wird nicht mehr versandt, wenn das Gespräch inzwischen gelöscht ist.
• Shopabgleich: Ein gescheiterter Abruf beim Shop lässt den Auftrag nicht scheitern: er endet auf done, sein result trägt ok: false und unter error den Grund. Der bisherige Katalog bleibt, der Fehler steht an der Anbindung, und der nächste Abgleich nach Zeitplan versucht es erneut.

Signatur, Kopfzeilen und Ereignisse der Webhooks beschreibt API-Schlüssel und Webhooks, die Anbindung eines Shops Katalog, Warenkorb und Shopanbindung.

Hängende und liegengebliebene Aufträge

Ein Auftrag, der seit mehr als einer Stunde als laufend geführt wird oder dessen Arbeitsprozess nicht mehr läuft, gilt als verwaist. XICBOT setzt ihn beim Start des Hintergrunddienstes und bei der stündlichen Wartung zurück: auf pending, solange Versuche übrig sind, sonst auf failed. Der Fehlertext nennt den Grund, bei der Stundenfrist „seit mehr als 3600 Sekunden ohne Fortschritt“.

Ein Auftrag, der 7 Tage nach seiner Anlage noch wartet oder läuft, verfällt bei der Wartung. Er endet ohne weitere Ausführung auf failed mit dem Fehler expired; als sein Ende gilt der Zeitpunkt 7 Tage nach der Anlage. Wartet dazu noch eine Mail auf den Versand, gilt sie als gescheitert mit dem Vermerk „Versandauftrag nach 7 Tagen abgelaufen“.

Doppelte Aufträge

An mehreren Stellen legt XICBOT keinen zweiten Auftrag an, solange ein gleichartiger offen ist, also wartet oder läuft:

• Neu einlesen bei einer Quelle, für die schon ein Einlese- oder Auffrischungsauftrag offen ist, auch die erste Aufnahme einer neuen Website, übernimmt diesen Auftrag; die Antwort trägt already_open: true. Haken Sie Vollständig neu aufbauen an, während ein Auftrag ohne Neuaufbau noch wartet, übernimmt er den Neuaufbau. Läuft er schon, antwortet die Schnittstelle mit 409 und refresh_running, und die Anwendung meldet „Für diese Quelle läuft oder wartet ein Aufbau. Bitte danach erneut versuchen.“ Wird ein offener Auftrag übernommen, reiht es das Nachrechnen trotzdem zusätzlich ein.
• Der tägliche Auffrischungslauf und die Auffrischung während einer Antwort überspringen eine Quelle, für die schon ein Einlese- oder Auffrischungsauftrag offen ist.
• POST /api/v1/knowledge/embed übernimmt einen offenen Nachrechen-Auftrag des Kontos, auch einen für eine andere Quelle; eine mitgegebene source_id wirkt dann nicht.
• Der Abgleich von Hand übernimmt einen offenen Abgleich; die Anwendung meldet dann „Ein Abgleich wartet bereits.“, sonst „Der Abgleich ist eingereiht.“ Ist kein Abgleich offen, gilt bis 15 Minuten nach der letzten Anfrage von Hand eine Sperre: Antwort 429 mit sync_too_soon, retry_after (Sekunden) und dem Kopf Retry-After. Die Anwendung meldet dann „Ein Abgleich von Hand ist höchstens alle 15 Minuten möglich. Der regelmäßige Abgleich läuft davon unabhängig weiter.“
• Der stündliche Abgleich nach Zeitplan lässt ein Konto aus, für das schon ein Abgleich offen ist.
• Der wöchentliche Zeitplan lässt ein Konto aus, für das in dieser Woche schon ein Auftrag zur Wochenauswertung angelegt oder die Auswertung schon versandt ist.
• Ein Abnahmelauf für einen Assistenten, der schon einen offenen Lauf hat, liefert diesen Lauf zurück, sofern er vor weniger als einer Stunde angelegt wurde.
• Solange für eine Quelle ein Einlese- oder Auffrischungsauftrag offen ist, lässt sich keine frühere Fassung dieser Quelle wiederherstellen: Antwort 409 mit refresh_running.

Aufträge über die Schnittstelle verfolgen

Legt eine Anfrage einen Auftrag an, antwortet die Schnittstelle mit 202 und einem Objekt job mit id, status und task: beim Anlegen einer Website-Quelle, bei POST /api/v1/knowledge/sources/{id}/refresh und bei POST /api/v1/knowledge/embed. Der Abgleich von Hand über POST /api/v1/catalog/shop/sync nennt die Kennung als job_id, dazu already_pending; er verlangt die Rolle Verwaltung. Den Stand jedes dieser Aufträge liefert GET /api/v1/knowledge/jobs/{id}, auch den des Abgleichs.

Wie lange Aufträge gespeichert bleiben

• Ist ein Auftrag erledigt oder endgültig gescheitert, kürzt XICBOT seine Nutzdaten auf Verweise wie Quelle, Lauf, Konto, Mailvorlage, Versand, Webhook und Ereignis. Empfänger, Mailinhalt und der Inhalt einer Webhook-Meldung fallen weg; ist etwas weggefallen, trägt der Auftrag die Marke reduced.
• Erledigte und gescheiterte Aufträge werden 14 Tage nach ihrem Ende gelöscht. Bis dahin bleiben Art, Zeiten und Fehlertext.
• Löschen Sie ein Gespräch, gehen die zugehörigen Mail- und Webhook-Aufträge mit. Stehen bleiben offene Webhook-Zustellungen der Ereignisse lead.created und appointment.requested, weil sie einen Vorgang melden.
• Die Aufträge Ihres Kontos gehören zum Datenexport. Unter Recht und Daten zählt die Tabelle Gespeicherte Daten sie in der Zeile Hintergrundaufträge. Mit dem Konto werden sie gelöscht.

Fristen für Gespräche und andere Daten stehen unter Aufbewahrung und Löschung, Export und Kontolöschung unter Datenschutz und Recht.

Häufige Fragen