Stand: Analyse der Funktion RunAutoRestart in Codeunit 5518689 „Auto Restart Runner“ (brAG E4M, BC25).
1. Zweck und Überblick
Auto Restart sucht automatisch nach fehlgeschlagenen, wiederholbaren Vorgängen und stößt diese erneut an, sofern für den Fehlertext eine passende, aktive Regel existiert.
Betroffen sind folgende Bereiche:
Aufgabenwarteschlange: In der Tabelle Job Queue Entry werden Einträge berücksichtigt, deren Status „Error“ ist und deren E4M Priority mindestens dem konfigurierten Priority Filter entspricht. Der relevante Fehlertext steht im Feld Error Message.
Marktplatz: Die Tabellen Mp Order, Mp Customer, Mp Shipment, Mp RMA, Mp Invoice, Mp CrMemo und Mp Document werden geprüft. Voraussetzung ist, dass Last Action Status den Wert „Error“ hat. Der Fehlertext steht im Feld Last Action Message.
Betrugsprüfung: Die Tabelle Fraud Check wird bei Last Action Status = Error geprüft. Der Fehlertext steht im Feld Last Action Message.
Exporto: In der Tabelle Exporto Sales Shipment werden Datensätze mit Last Action Status = Error geprüft. Der Fehlertext steht ebenfalls im Feld Last Action Message.
Riverty/Aqount: Die Tabellen Riverty Order, Riverty Return und Riverty GoodWill werden geprüft, wenn Transaction State GetDoc den Wert „Error“ hat. Der relevante Fehlertext steht im Feld Transaction Description.
Nur Fehler, für die der Anwender eine Regel angelegt hat, werden automatisch behandelt. Alle anderen Datensätze bleiben unverändert im Fehlerstatus und müssen manuell bearbeitet werden.
2. Ablauf eines Laufs
Der Einstiegspunkt ist die Funktion RunAutoRestart. Sie wird über OnRun der Codeunit oder über den Bericht „Auto Restart Batch“ mit der ID 5518704 aufgerufen.
Zu Beginn wird der Datensatz Auto Restart Setup gelesen. Existiert dieser nicht oder ist Enabled = false, passiert nichts. Es wird weder ein Fehler ausgelöst noch eine Meldung ausgegeben.
Anschließend werden die fehlerhaften Job-Queue-Einträge geprüft. Danach folgen die Marktplatz-Tabellen in dieser Reihenfolge: Order, Customer, Shipment, CrMemo, Invoice, RMA und Document. Im Anschluss werden Fraud Check und Exporto Shipment verarbeitet.
Die Verarbeitung von Riverty/Aqount erfolgt nur, wenn der jeweilige Schalter im Setup aktiviert ist. Dabei werden Orders, Returns und GoodWills geprüft.
Zum Abschluss werden alte Status-Einträge in Auto Restart State und alte Log-Einträge entsprechend den konfigurierten Aufbewahrungsfristen gelöscht.
Für jeden fehlerhaften Datensatz gilt grundsätzlich folgender Ablauf:
-
Es wird geprüft, ob ein Fehlertext vorhanden ist.
-
Es wird nach einer aktiven Regel für die betreffende Tabelle gesucht, deren Fehlertext und gegebenenfalls Aktion passen.
-
Die Regel muss aktiv sein und AutoRestart Allowed muss aktiviert sein.
-
Der Wiederholschutz prüft die maximale Anzahl an Versuchen, die Mindestwartezeit und das globale Stundenlimit.
-
Wenn alle Bedingungen erfüllt sind, wird die vorgesehene Aktion ausgeführt und gegebenenfalls ein Log-Eintrag geschrieben.
Die ausgeführte Aktion hängt von der Quelle ab.
Bei Job-Queue-Einträgen mit der Aktion Restart Job wird Restart() ausgeführt und der Eintrag neu gestartet.
Bei der Aktion SalesHeader wird versucht, den Verkaufsbeleg zurückzusetzen. Dabei werden Applies-to Doc. No. geleert, der Verarbeitungsstatus zurückgesetzt und die Hintergrundbuchung abgebrochen. Falls dies aufgrund unpassender Filter oder Parameter nicht gelingt, wird stattdessen der Job neu gestartet.
Bei Job-Queue-Einträgen mit einer anderen Aktion wird der Job ebenfalls neu gestartet.
Bei MP-Tabellen, Fraud Check und Exporto werden Next Action auf Last Action gesetzt, die Fehlermeldung und der Fehlerstatus geleert und die betreffende Aktion unmittelbar erneut ausgeführt.
Bei Riverty/Aqount werden Status und Beschreibung geleert und der Beleg erneut an Riverty gesendet.
3. Einrichtung
Die Einrichtung erfolgt über E4M Setup. Dort stehen die Seiten Auto Restart Setup, Auto Restart Rules und Auto Restart Log zur Verfügung.
3.1 Auto Restart Setup (Pflicht)
Das Setup enthält folgende Felder und Standardwerte:
Enabled: Nein. Dies ist der Hauptschalter. Ohne Aktivierung läuft Auto Restart nicht.
Default Max Retries: 3. Maximale Anzahl an Versuchen je Datensatz und Regel, sofern die Regel keinen eigenen Wert vorgibt.
Default Min Wait (Sec): 15. Mindestabstand zwischen zwei Versuchen, sofern die Regel keinen eigenen Wert vorgibt.
Max Restarts per Hour: 200. Globale Begrenzung der automatischen Neustarts pro Stunde. Bei 0 ist das Limit unbegrenzt.
Logging Enabled: Ja. Legt fest, ob Log-Einträge geschrieben werden.
State Retention (Days): 30. Aufbewahrungsdauer der Zählerstände. Bei 0 werden diese nicht automatisch gelöscht.
Log Retention (Days): 90. Aufbewahrungsdauer des Protokolls. Bei 0 werden Log-Einträge nicht automatisch gelöscht.
Priority Filter: 1000. Es werden nur Job-Queue-Einträge berücksichtigt, deren E4M Priority mindestens diesem Wert entspricht.
Process Aqount Orders / Returns / GoodWills: Nein. Diese Schalter aktivieren die Riverty-Verarbeitung für die jeweilige Belegart.
Wichtig: Der Setup-Datensatz muss einmalig angelegt werden. Dazu muss die Seite geöffnet und gespeichert werden. Die Marktplatz-, Fraud-Check- und Exporto-Verarbeitung besitzen keinen eigenen Schalter. Sie laufen, sobald Enabled aktiviert ist und passende Regeln existieren.
3.2 Regeln anlegen
Die Regeln werden unter Auto Restart Rules angelegt und sind in Abschnitt 4 beschrieben.
Ohne Regeln wird kein Vorgang automatisch neu gestartet. Bei Job-Queue-Fehlern kann lediglich der Log-Eintrag NotMatched entstehen.
3.3 Planmäßigen Aufruf einrichten
Auto Restart läuft nicht automatisch im Hintergrund, solange kein entsprechender Aufruf eingerichtet ist.
Es muss ein Job-Queue-Eintrag angelegt werden, der den Bericht 5518704 „Auto Restart Batch“ oder die Codeunit 5518689 in kurzen Abständen ausführt. Ein Intervall von fünf bis fünfzehn Minuten ist beispielsweise möglich.
Zusammen mit Min Wait bestimmt dieses Intervall die tatsächliche Wiederholfrequenz.
Der Job für Auto Restart selbst sollte eine Priorität unterhalb des Priority Filters haben, beispielsweise kleiner als 1000. Dadurch wird verhindert, dass sich der eigene Job bei einem Fehler selbst als Fehler-Job behandelt.
3.4 Priorität der Job-Queue-Einträge
Das Feld E4M Priority in Job Queue Entry bestimmt, welche Jobs überhaupt berücksichtigt werden.
Jobs mit einer Priorität unterhalb des Priority Filters, standardmäßig 1000, werden ignoriert. Daher muss sichergestellt werden, dass die Jobs, die automatisch neu gestartet werden sollen, eine ausreichend hohe Priorität besitzen.
4. Regeln (Auto Restart Rules)
Die Regeln enthalten folgende Felder:
Active: Gibt an, ob die Regel aktiv ist.
AutoRestart Allowed: Legt fest, ob ein automatischer Neustart erlaubt ist. Dieser zweite Schalter ermöglicht beispielsweise, eine Regel nur zur Dokumentation anzulegen.
Action: Definiert die Aktion. Mögliche Werte sind Restart Job, SalesHeader, MP Tables sowie Aqount Resend Order, Return oder GoodWill.
Source Table ID: Gibt die Tabelle an, in der der Fehler auftritt. Beispiele sind die Tabelle 472 Job Queue Entry oder die jeweilige Tabelle der Mp Order.
Error Text Contains: Enthält das Textfragment, das im Fehlertext vorkommen muss.
Action Filter Contains: Wird nur für SalesHeader verwendet. Das Textfragment muss in der Job-Beschreibung vorkommen.
Action Param 1: Wird ebenfalls nur für SalesHeader verwendet. Das Feld enthält die Vorlage der erwarteten Job-Beschreibung. %1 steht für die Belegnummer. Ein Beispiel ist „Reklamation %1 Gutschrift buchen.“
Max Retries / Min Wait (Sec): Enthalten optionale, regelbezogene Werte. Bei leerem Wert oder 0 werden die Werte aus dem Setup verwendet.
Comment: Enthält einen Freitextkommentar.
Für die Zuordnung gelten folgende Regeln:
Der Vergleich der Fehlertexte ist nicht groß- und kleinschreibungsabhängig. Zeilenumbrüche und Tabs werden entfernt, führende und nachfolgende Leerzeichen abgeschnitten.
Error Text Contains darf nicht leer sein. Eine Regel ohne Fehlertext trifft nie zu.
Es gilt die erste passende Regel, sortiert nach Entry No. Spezifische Regeln sollten deshalb vor allgemeinen Regeln angelegt werden.
Bei MP, Fraud Check, Exporto und Riverty muss die Action zur Quelle passen. Für Marktplatz-Datensätze ist dies MP Tables, für Riverty/Aqount die entsprechende Aqount-Aktion. Andernfalls wird die Regel ignoriert.
Bei Job-Queue-Einträgen wird die Aktion nicht zur Auswahl der Regel herangezogen. Eine unpassende Aktion führt dort zu einem normalen Restart.
Source Table ID muss exakt der Tabelle entsprechen, in der der Fehler auftritt. Bei Job-Queue-Einträgen ist dies die Tabelle des Feldes Record ID to Process, beispielsweise Tabelle 36 Sales Header, und nicht Tabelle 472 Job Queue Entry.
5. Wiederholschutz und Limits
Für jeden Datensatz und jede Regel wird ein Zähler in der Tabelle Auto Restart State geführt.
Ein Versuch wird nur ausgeführt, wenn alle folgenden Bedingungen erfüllt sind:
Max Retries: Der Zähler muss kleiner als der Regelwert sein. Falls kein eigener Wert definiert ist, wird der Standardwert aus dem Setup verwendet. Wenn der wirksame Wert 0 ist, besteht keine Begrenzung.
Min Wait: Seit dem letzten Versuch muss die konfigurierte Mindestwartezeit vergangen sein.
Stundenlimit: Die Anzahl der Neustarts in der laufenden Stunde muss unter Max Restarts per Hour liegen.
Weitere Eigenschaften des Wiederholschutzes:
Wenn sich der Fehlertext ändert, werden die ersten 64 Zeichen des normalisierten Textes verglichen. Bei einer Änderung wird der Zähler auf 0 zurückgesetzt. Ein neuer Fehler erhält damit wieder die volle Anzahl an Versuchen.
Der Zähler wird bei Erfolg nicht zurückgesetzt. Tritt derselbe Fehler nach erfolgreicher Bearbeitung später erneut auf, kann das Limit deshalb bereits erreicht sein. Der Zählerstand bleibt bestehen, bis er entsprechend der State Retention gelöscht wird.
Ist das Limit erreicht, bleibt der Datensatz dauerhaft im Fehlerstatus und wird nicht mehr automatisch behandelt. Eine manuelle Prüfung ist dann erforderlich. Siehe Abschnitt 8.
6. Ermittlung der wiederkehrenden Aufgaben
Dieser Abschnitt beschreibt, wie das System die zu behandelnden Datensätze ermittelt und welche Aufgaben beim Anwender verbleiben.
6.1 Job Queue
Zunächst werden alle Job-Queue-Einträge mit Status = Error und E4M Priority >= Priority Filter ermittelt.
Ist kein Fehlertext vorhanden, erfolgt keine Verarbeitung und es wird kein Log-Eintrag geschrieben.
Fehlt Record ID to Process, wird der Log-Eintrag NoRecordId erzeugt. Der Datensatz muss manuell geprüft werden.
Existiert der referenzierte Datensatz nicht mehr, wird der Job-Queue-Eintrag gelöscht und DeletedMissingRec protokolliert.
Wird keine passende Regel für Tabelle und Fehlertext gefunden, entsteht der Log-Eintrag NotMatched. Der Fehler muss manuell geprüft werden. Gegebenenfalls ist eine neue Regel anzulegen.
Wurde eine Regel gefunden, verhindert aber der Wiederholschutz den Versuch, wird Wait/Max protokolliert. Dieser Eintrag entsteht bei jedem Lauf erneut, solange der Job im Fehlerstatus bleibt.
Wird der Versuch freigegeben, erfolgt der Neustart. Im Log erscheint abhängig von der Aktion Restarted oder SalesHeader.
6.2 MP-Tabellen, Fraud Check, Exporto und Riverty/Aqount
Zunächst werden alle Datensätze mit Fehlerstatus und nicht leerem Fehlertext ermittelt.
Danach wird nach einer passenden aktiven Regel gesucht. Dabei müssen Tabelle, Aktion und Fehlertext übereinstimmen.
Anschließend wird der Wiederholschutz geprüft. Wird der Versuch freigegeben, wird die Aktion ausgeführt und ein entsprechender Log-Eintrag geschrieben. Beispiele sind MPOrderRestart, MPCustomerRestart, MPShipmentRestart, MPRMARestart, MPInvoiceRestart, MPCrMemoRestart, MPDocumentRestart, MPFraudCheckRestart, MPExportoShipRestart und AqountResend.
Bei fehlender Regel oder einem durch den Wiederholschutz verweigerten Versuch wird kein Log-Eintrag geschrieben. Solche Datensätze lassen sich nur anhand ihres Fehlerstatus in der jeweiligen Tabelle erkennen.
6.3 Was bleibt für den Anwender?
Fehler ohne passende Regel: Der Datensatz bleibt im Fehlerstatus. Bei Job-Queue-Einträgen ist dies am Log-Eintrag NotMatched erkennbar. Die Ursache muss geprüft und gegebenenfalls eine Regel angelegt werden.
Maximale Anzahl an Versuchen erreicht: Der Datensatz bleibt im Fehlerstatus. Bei Job-Queue-Einträgen weist der Log-Eintrag Wait/Max mit hohem Retry Count darauf hin. Die Ursache muss behoben und der Datensatz manuell neu gestartet werden.
Job ohne Datensatzbezug: Der Log-Eintrag NoRecordId weist darauf hin. Der Job muss manuell bearbeitet werden.
Job mit Priorität unterhalb des Filters: Es entsteht kein Log-Eintrag. Der Job wird nie automatisch behandelt und muss manuell überwacht werden.
Riverty ohne aktivierten Schalter: Der Datensatz bleibt im Fehlerstatus. Die Schalter im Setup müssen geprüft werden.
7. Protokoll (Log) und Aufbewahrung
Das Protokoll ist über die Seite Auto Restart Log erreichbar. Die zugrunde liegende Tabelle hat die ID 5518802.
Das Log enthält unter anderem Zeitpunkt, Job Queue Entry ID beziehungsweise Nummer, Source Table ID, Rule Entry No., Aktion, Retry Count und den Fehlertext mit maximal 250 Zeichen.
Log-Einträge werden nur geschrieben, wenn Logging Enabled aktiviert ist.
Die Log-Einträge werden nach der in Log Retention (Days) definierten Aufbewahrungsfrist gelöscht. Der Standardwert beträgt 90 Tage.
Zählerstände werden entsprechend State Retention (Days) gelöscht. Der Standardwert beträgt 30 Tage. Maßgeblich ist dabei der letzte Neustart.
8. Regelmäßige Überwachung durch den Anwender
Tägliche Prüfungen
Die Job Queue Entries mit Status Error müssen geprüft werden. Hierfür kann beispielsweise der Cue „Fehler“ im Administrationsrollencenter verwendet werden. Jeder Eintrag, der länger als einige Auto-Restart-Zyklen im Fehlerstatus verbleibt, wurde nicht automatisch gelöst.
Das Auto Restart Log sollte nach den Aktionen NotMatched, Wait/Max, NoRecordId und DeletedMissingRec gefiltert und ausgewertet werden.
Die Marktplatz-Tabellen Order, Customer, Shipment, RMA, Invoice, CrMemo und Document sowie Fraud Check und Exporto Shipment müssen auf Datensätze mit Last Action Status = Error geprüft werden. Für nicht behandelte Fälle wird dort kein Log geschrieben.
Riverty Orders, Returns und GoodWills müssen auf Transaction State GetDoc = Error geprüft werden.
Außerdem ist zu prüfen, ob der Job-Queue-Eintrag für Auto Restart Batch den Status Ready oder In Process hat und weder im Fehlerstatus noch auf On Hold steht.
Wöchentliche Prüfungen
Das Log sollte auf Häufungen untersucht werden. Tritt dieselbe Regel oder derselbe Fehler häufig auf, sollte die Ursache behoben werden, statt dauerhaft Neustarts auszuführen.
Es ist zu prüfen, ob Max Restarts per Hour erreicht wurde. Viele Wait/Max-Einträge zum selben Zeitpunkt können darauf hindeuten.
Neue Fehlertexte aus NotMatched sollten in Regeln überführt werden, sofern ein automatischer Neustart sinnvoll ist.
Monatliche Prüfungen und Prüfungen nach Änderungen
Die Regeln sollten auf Aktualität überprüft werden. Dazu gehören inaktive oder veraltete Regeln und zu allgemeine Textfragmente.
Die Aufbewahrungsfristen und Standardwerte müssen regelmäßig überprüft werden.
Nach Änderungen an Jobs oder Prioritäten ist der Priority Filter zu kontrollieren.
9. Typische Fehlerbilder und Abhilfe
Wenn überhaupt nichts passiert, kann dies daran liegen, dass das Setup nicht angelegt wurde, Enabled nicht aktiviert ist oder der Auto-Restart-Job nicht eingeplant wurde.
Wenn ein Job im Fehlerstatus nicht behandelt wird, kann seine Priorität unterhalb des Priority Filters liegen. Weitere mögliche Ursachen sind eine inaktive Regel, ein deaktiviertes AutoRestart Allowed, eine falsche Source Table ID oder ein nicht passender Fehlertext.
Wenn ein Riverty-Fehler nicht behandelt wird, ist zu prüfen, ob der entsprechende Schalter Process Aqount aktiviert ist und ob die Regelaktion Aqount Resend lautet.
Wenn ein MP-Fehler nicht behandelt wird, muss geprüft werden, ob die Regelaktion MP Tables und die Source Table ID korrekt sind.
Wenn Neustarts nach wenigen Versuchen aufhören, wurde möglicherweise Max Retries erreicht. Dies ist das vorgesehene Verhalten des Wiederholschutzes.
Wenn Neustarts nicht zeitnah erfolgen, können Min Wait, das globale Stundenlimit oder ein zu selten ausgeführter Auto-Restart-Job die Ursache sein.
Wenn ein Job-Queue-Eintrag verschwindet, existiert möglicherweise der referenzierte Datensatz nicht mehr. In diesem Fall wird DeletedMissingRec protokolliert.
10. Hinweise und Besonderheiten
Bei erschöpften Versuchen wird keine Benachrichtigung versendet. Die regelmäßige Überwachung aus Abschnitt 8 ist deshalb zwingend erforderlich.
Zu allgemeine Fehlertext-Fragmente, beispielsweise „Fehler“, können unbeabsichtigt dazu führen, dass viele unterschiedliche Fehler automatisch neu gestartet werden.
Bei der Aktion SalesHeader werden Belege zurückgesetzt. Dazu gehören der Verarbeitungsstatus, die Hintergrundbuchung und Applies-to Doc. No. Action Filter und Action Param sollten gesetzt werden, um ausschließlich die gewünschten Jobs zu treffen.
Die Erkennung gleicher Fehler erfolgt anhand der ersten 64 Zeichen des normalisierten Fehlertextes. Fehlertexte, die sich erst nach diesen 64 Zeichen unterscheiden, gelten als derselbe Fehler.