Toolmaker Produkt-Dokumentation
Mailstatus Feedback - Exitprogramm
- Robert E. Schneider
verfügbar seit Version 5.60, PTF 14
Das Exit-Programm für den Mailstatus Feedback kann eingesetzt werden, um weitere Informationen über das "Schicksal" eines versandten E-Mails an die sendende Anwendung weiterzugeben.
Mit directspool können E-Mails auf verschiedenen Wegen versandt werden:
- Versand über SpoolMail- (AutoMail-) Definitionen:eine Kundenanwendung kann Dokumente in Form einer Spooldatei in einer OUTQ zum Versand per directspool bereitstellen. Diese SPLFs werden dann über eine Spoolmail (AutoMail-) Definition automatisch in PDF-Dokumente konvertiert und versandt.
- Versand mit den Befehlen OPN-, WRT- und CLSEMLAPI
In beiden Fällen können mit dem unten beschriebenen Exit-Programm Fehler erkannt und gemeldet/bearbeitet werden.
Anforderung und Lösungsansatz
Über ein EXIT Programm könnte jede Änderung des Versandstatus einer Email an die Kundenanwendung zurückgemeldet werden.Dies kann erforderlich sein, wenn Geschäftsvorfälle schnell abgewickelt werden müssen und der Absender der Email sicher sein muss, dass die Email erfolgreich versandt wurde, bevor der nächste Schritt eingeleitet wird (z.B. ein Telefonat führen).
Voraussetzungen und Verfügbarkeit
Als Basisversion ist directmail 5.60 mit PTF 14 ab KW 33 in 2021 erforderlich oder eine evtl. später erscheinende Version des Produkts. Das IBM i Release muss V7R1M0 oder höher sein.
Mögliche Hindernisse beim Mailversand
Der beschriebene Ablauf wird im Batch, also unsichtbar für den Benutzer, ausgeführt. Kommt es aufgrund von Massenaussendungen, temporären Fehlern auf dem Mailserver oder einer fehlerhaften Mailadresse zu Verzögerungen ist die Kenntnis über den aktuellen Versandstatus wichtig.
Da eine SPLF mehrere Dokumente mit verschiedenen Email Empfängern enthalten kann, besteht die Aufgabe darin, die Spur einer Email zurück zum Dokument und dann weiter bis zu dem Vorgang in der Anwendung zu verfolgen.
Datei DMSPLMID als Basis
Beim Versand einer E-Mail wird von directspool ein Satz in die Datei DMSPLMID geschrieben. Er enthält die folgende Information für das E-Mail:
- die SPLF Attribute (SPLF-Name, Jobinformation, SPLF-Nummer)
- die eindeutige Mail-ID (internes 20-stelliges Schlüsselfeld SMMID)
- die erste Email Adresse des Empfängers
- den Namen der Mailbox
- die verwendete directspool Definition
- Datumsinformationen zur Erstellung der Email.
Reservierte Indizes &APPLKEY01N+A und 02N+A
Falls erforderlich, können in der Automail Definition zur Verarbeitung der SPLF reservierte Indexnamen mit Werten oder Texten aus dem Spoolinhalt oder aus einer Kundendatei angegeben werden. Da wären z.B. Kunden-Nr., Auftrags-Nr., Rechnungs-Nr. oder andere Schlüsselwerte denkbar, die es erlauben, den Weg zurück zum Vorgang in der Kundenanwendung zu gehen, um den Status einer Email dort abzuspeichern.
Es gibt 4 Datenfelder in der Datei DMSPLMID, die durch die reservierten Indizes automatisch gefüllt werden, wenn für den jeweiligen Index ein passender Wert gefunden wurde. Ansonsten wird Blank oder 0 gespeichert.
SMAPK1A - &APPLKEY01A - Alfanum. Länge 20 SMAPK2A - &APPLKEY02A - Alfanum. Länge 20 SMAPK1N - &APPLKEY01N - Numerisch 15,0 SMAPK2N - &APPLKEY02N - Numerisch 15,0
Hinweis 1: Wird in der Ausführungsphase ein falscher numerischer Wert gefunden, wird -1 als Fehlerhinweis in das Feld gestellt.
Hinweis 2: Werden statt directspool (Automail) die Batch- und Spool-APIs verwendet, können aus der SPLF keine Datenfelder oder Texte entnommen werden. Ist es trotzdem erforderlich, alfanumerische oder numerische Daten mitzugeben, kann der Befehl IDXEMLAPI F4 (selbst erklärend) zwischen WRTEMLAPI und CLSEMLAPI eingesetzt werden.
Arbeitsweise des Exit-Programmes
Das anfangs erwähnte EXIT Programm greift mit der Mail-ID auf die Datei DMSPLMID zu und stellt alle Werte bereit. Der Entwickler vor Ort kann dann die erforderlichen Schlüsselwerte nehmen, daraus einen Zugriff auf eine bestimmte Datei der Kundenanwendung generieren und den Status als Kennzeichen in die Datei schreiben. Dieser Zugriff und die Fortschreibung kann mit Operationen wie SETLL/READ, CHAIN, UPDATE oder per SQL UPDATE erfolgen.
Erkennen von nicht behebbaren Fehlern
Im Falle, dass eine temporäre Störung im Mailversand zu lange dauert oder es sich um einen nicht behebbaren Fehler handelt, kann ein anderes EXIT Programm eingesetzt werden. Dies wird automatisch gestartet, wenn ein Versandvorgang nach x vergeblichen Versuchen damit endet, dass die Email in den Ordner Fehler verschoben wird.
In diesem Fall wird das EXIT Programm eine Nachricht an den Operator senden (entweder an QSYSOPR oder an einen angemeldeten Benutzer) und um Klärung bitten.
Zwar wurde der Status der Email mit E (Error) zuvor an die Kundenanwendung gemeldet, aber der Mitarbeiter kann die Ursache i.d.R. nicht erkennen und beheben. Es ist eine Analyse mit WRKMBX, Auswahl 8 und der Option 1 vor dem Ordner Fehler erforderlich.
Mit Auswahl 25 vor der Email kann die Ursache ermittelt werden. Die Lösung des Problems kann in der Reaktivierung der Email liegen, falls die technische Ursache sich erledigt hat, oder mit dem Löschen der Email enden.
Vorlage für ein Exit-Programm
Eine Vorlage für solch ein Exit-Programm befindet sich in der Teildatei DIRMAIL/QDMSPLMID(DMEMLSTSEX).
Diese sollte in eine andere Bibliothek kopiert und umbenannt werden. Die Kopie kann dann an die inviduellen Erfordernisse angepasst werden.
Das Exit-Programm kann ein CL-Programm sein, das den 20-stelligen Parameter MAILID empfängt und eine Nachricht an QSYSOPR sendet. Hier ist ein Beispiel, welche Befehle im Programm genutzt werden können:
TIPP: Aus dem EXIT Programm kann man statt mit
SNDMSG MSG('EMAIL im Ordner - Fehler - prüfen +- siehe WRKMBX Auswahl 8') TOUSR(*SYSOPR)
auch eine kleine Email senden (Werte <...> müssen durch echte Daten ersetzt werden):
SNDSPLEML FILE(*NONE)
SPLNBR(*LAST) MAILBOX(<name>) +
SENDER('<absendername>' +
'<name>@<domaene>.ch') +
RCVR('<name>@<domaene.ch') +
SUBJECT('EMAIL + im Ordner Fehler prüfen - siehe WRKMBX + Auswahl 8')
Hinweis 1: Die als Parameter (20A) an das EXIT Programm übergeben Mail-ID wird hier nicht genutzt, muss aber im CL definiert sein. Eine SPLF ist nicht erforderlich, siehe Param. FILE(*NONE)
Hinweis 2: Sollte der interne Emailversand ins Stocken geraten sein, kann die Nachricht natürlich auch nicht sofort zugestellt werden. Sie ist aber wichtig, damit die fehlerhafte Email überhaupt bearbeitet wird.
Exit-Programme registrieren
Es ist möglich zwei verschiedene Exit-Programme zu registrieren:
- allgemein für den EMail-Status
- speziell für den Ordner Fehler
Exit-Programmnamen für Email Status erfassen
Wenn das EXIT Programm vom lokalen Entwickler für den Zugriff auf die Kundenanwendung vorbereitet und einer eigenen Bibliothek bereitgestellt wurde, muss es durch Eingaben im Datenbereich DMDTAARA aktiviert werden:
CHGDTAARA DTAARA(DIRMAIL/DMDTAARA (1281 20)) VALUE('PROGRAMM1 QGPL')
Value = 10 Stellen Programm und 10 Stellen Bibliothek = 20 in der Summe
Exit-Programmnamen für Ordner Fehler erfassen
Soll ein EXIT Programm für das Handling der Benachrichtigung von nicht behebbaren Fehlern genutzt werden, muss es durch Eingaben im Datenbereich DMDTAARA aktiviert werden:
CHGDTAARA DTAARA(DIRMAIL/DMDTAARA (1101 20)) VALUE('PROGRAMM2 QGPL')
Value = 10 Stellen Programm und 10 Stellen Bibliothek = 20 in der Summe
Meldung von Fehlern bei der Spooldateikonvertierung
Die automatischen, für den Benutzer nicht sichtbaren Vorgänge beim Erstellen einer Email mit einer PDF-Datei im Anhang können scheitern, wenn die zu konvertierende Spooldatei (SPLF) z.B. nicht zu finden oder leer ist, die SPLF kann auch noch im Aufbau begriffen oder von einem Benutzer bzw. einer anderen Anwendung geöffnet und blockiert sein.
Diese Art Fehler werden zwar gemeldet, aber es hängt von der Anwendung ab, ob der Fehler nur abgefangen oder auch so weitergemeldet wird, dass eine geschulte Person sie erhält und weiß, was zu tun ist.
Das Produkt wurde jetzt im Zusammenhang mit dem Feedback des Mailstatus an die Anwendung so erweitert, dass der Kunde die Kontrolle behält, d.h. die Email nicht ohne Anhang versendet wird. Der Ablauf sieht dann im Detail so aus:
- Die Email wird mit der Übergabe der Kopfdaten (Absender, Empfänger, Betreff und Mailbody) erstellt. Hierbei wird die interne MAIL-ID generiert, die alle nachfolgenden Schritte miteinander verbindet.
- Dann wird die gesamte Spooldatei oder Teile davon in eine PDF-Datei konvertiert. Diese wird im IFS zwischengespeichert.
- Es erfolgt das Hinzufügen der PDF-Datei zur Email (als sogenannter Anhang).
- Bei Bedarf werden weitere Anhänge hinzugefügt (z.B. ein AGB Blatt oder zum Vorgang gehörige Dokumente).
- Am Ende erfolgt mit CLSEMLAPI die Übergabe des fertigen Objekts an die Warteschlange für den Versand (das ist der Ordner Ausgang in der Mailbox).
Da die Email eröffnet wurde und bei einem Abbruch der Spoolkonvertierung nicht einfach so halbfertig zurückgelassen werden kann, müssen alle 5 Schritte auch bei Fehlern durchlaufen werden. Falls der Prozess den CLSEMLAPI nicht durchführen kann, ist das Erstellen der nächsten Email unmöglich.
Das Email Erstellungsprogramm greift jetzt so ein, dass es alle zu dem Vorgang verfügbaren Informationen sammelt und in einer umfangreichen Nachricht an QSYSOPR sendet. Beispiel:
----------------------------------------------------------------------------------------
Nachrichten-ID . . . . : ERR0420 Bewertung . . . . . . : 00 Nachrichtenart . . . . : Information
Sendedatum . . . . . . : 10.08.21 Sendezeit . . . . . . : 12:30:13
Nachricht . . . : Error: DIRECTMAIL ohne Anhang - siehe Mail in WRKMBX Opt 8 (Uhrzeit
dieser Nachricht und erw. Hilfetext beachten)
Der erweiterte Nachrichtentext enthält folgende Infos:
SPLF: QPRINT Job 706360/WOIDT/DIST2WOIDT SPLNBR=7 MAILID=1G4O5H53KC9N64IGA
MBX=WOIDT ERRMSG=ERR0012 SPLF not found
----------------------------------------------------------------------------------------
Der erste Teil der Nachricht weist auf das Problem hin und empfiehlt, die Uhrzeit der Nachricht zu notieren.
Der zweite Teil (erweiterter Hilfetext) zählt alle Merkmale auf, um die SPLF zu identifizieren. Des weiteren werden Mail-ID und Mailbox sowie die Fehler-Nr und ein Teil des Fehlertextes genannt.
Damit die unvollständige Email (der Hauptanhang fehlt) nicht versendet wird, wurde der Status HOLD erteilt.
Sie finden die Email dann mit Befehl WRKMBX <name> und können mit Auswahl 8 vor der Mailbox, dann 1 vor dem Ordner Ausgang, die Email im Status Hld finden. Meist ist es die einzige Email dort, die anderen (ohne Fehler) wurden ja sofort versandt. Falls es mehrere Vorfälle gibt, hilft die Uhrzeit der Fehlernachricht, die betreffende Email zu orten.
Um die zugehörige SPLF zu finden, können Sie den folgenden Befehl zusammen mit Taste F4 verwenden:
WRKSPLF SELECT({*}ALL ALL *ALL *ALL *ALL *QPRINT) JOB(706360/WOIDT/DIST2WOIDT)
Falls die SPLF nicht mehr im System ist, können Sie anhand der Email Eigenschaften (Absender, Empfänger, Betreff etc) den Vorgang möglicherweise mit dem Absender zusammen klären. Danach kann die Email gelöscht und die erneute Erstellung angestoßen werden.
Ist bis hier hin der Grund des Fehlers unklar, kann mit WRKACTJOB SBS(DIRMAIL) in den Joblogs mit Namen DMATMxx unter Berücksichtigung der Fehleruhrzeit nach der Ursache gesucht werden.
Falls die Email Erstellung mit den Batch- und Spool-API Befehlen per Anwendungsprogramm durchgeführt wurde, sollte der Entwickler oder Betreuer der kundeneigenen Software hinzugezogen werden.
Liste der Mailstatus Kennzeichen
* -------------------------------------------------- * §ITMSTS Mailstatus Kennzeichen * primär als Feld IHSTS in Datei DMITMHDR vorhanden * -------------------------------------------------- d itm_newsts C 'NRHSTEYU' * d itm_Delete C 'D' d itm_Error C 'E' d itm_hold C 'H' d itm_ok C 'K' d itm_New C 'N' d itm_Open C 'O' d itm_ErrOpn C 'P' d itm_Ready C 'R' d itm_Send C 'S' d itm_Retry C 'T' d itm_use C 'U' d itm_schedule C 'Y' d itm_warning C 'W'
Bei itm_newsts sind alle Kennzeichen gelistet, die als NEU gelten, d.h. die Email ist noch nicht endgültig versandt worden.
Nach dem erfolgreichen Versand wird das Kennzeichenfeld auf "K" = OK gesetzt.
Viele Kennzeichen kommen in der Praxis kaum vor, da sie nur Sekundenbruchteile existieren. Bei "E" = Error oder "W" = Warning steht die Email im Ordner Fehler, d.h. wenn der Fehler, der mit Auswahl 25 vor der Email angezeigt wird, behebbar ist und korrigiert wurde, kann die Email noch versandt werden, sie muss nur wieder in den Ordner "Ausgang" gelangen und die Fehlercodes müssen zurückgesetzt werden.