Das Exit-Programm für den Mailstatus Feedback
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.
Es kann beim E-Mail-Versand über verschiedene Wege eingesetzt 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.
Seitens Toolmaker wird dafür ein RPGLE Beispielprogramm als Quelle bereitgestellt. Auf Basis dieses Programms kann ein Programmierer vor Ort die Verbindung mit der kundeneigenen IBM i Anwendung herstellen.
Dies kann erforderlich sein, 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.
...
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.
...
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.
EXIT Programmnamen für Email Status erfassen
Wenn das EXIT Programm vom lokalen Entwickler für den Zugriff auf die Kundenanwendung vorbereitet wurde (siehe Vorlage DMEMLSTSEX in Quellendatei QDMSPLMID in Bibliothek DIRMAIL) und unter einem neuen Namen als Quelle und Objekt in 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
Das 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)
...
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.
...
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
| Code Block |
|---|
* -------------------------------------------------- * §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' |
...