Dynamics AX Blog - email - Microsoft Dynamics AX (Axapta)

Der nachstehende Job demonstriert, wie man per Code ein E-Mail versenden kann und dabei sowohl den Betreff als auch den Text flexibel steuern kann.

Dafür stehen in Dynamics AX die sog. E-Mail-Vorlagen zur Verfügung, die in verschiedenen Sprachen hinterlegt werden können und wo auch Platzhalter (in meinem Beispiel CustAccount und CustName) verwendbar sind.

Die E-Mails werden vor dem Versand in einer Tabelle SysOutgoingEmailTable gespeichert wo man deren Sendestatus bebachten kann.

Voraussetzung für den Job sind eingerichtete E-Mail-Parameter (Stichwort SMTP-Server) sowie daß die Stapelverarbeitung läuft, die für die Abarbeitung der Tabelle SysOutgoingEmailTable verantwortlich ist.

static void sendMailOutgoingEmailTable(Args _args)
{
    Map mappings = new Map(Types::String, Types::String);        
    
    mappings.insert("CustAccount", "4711");
    mappings.insert("Custname", "schweda.net");
    
    SysEmailTable::sendMail("MyTemplate",                   // Template-ID
                            "de-at",                        // Language
                            "heinz.schweda@schweda.net",    // Recipient
                            mappings,                       // Placeholder-Map
                            "",                             // Attachment-Filename
                            "",                             // XML
                            true);                          // Use SysOutgoingEmailTable
}

In Dynamics AX 2012 gibt es - wie auch schon in früheren Versionen - mehrere Möglichkeiten E-Mails zu versenden.
Eine recht komfortable und bekannte Möglichkeit bietet die Tabelle SysOutgoingEmailTable und die dazugehörige Klasse SysEmailDistributor. Diese Tabelle ist über den Client unter Systemverwaltung > Periodisch > E-Mail-Verarbeitung > E-Mail-Sendestatus einsehbar.

Die Verarbeitung dieser Datensätze wird unter  Systemverwaltung > Periodisch > E-Mail-Verarbeitung > Stapel initiert und setzt voraus, daß die E-Mail-Parameter unter Systemverwaltung > Einstellungen > System entsprechend gepflegt sind.

Weniger bekannt ist, daß es über dieses Framework auch möglich ist, Mails mit Attachements zu verschicken. Dazu muss eine weitere Tabelle namens SysOutgoingEmailData entsprechend befüllt werden.

Im folgenden nun ein kurzer Job, der demonstriert, wie diese Tabellen per Code befüllt werden. 

Folgende Schritte sind in Dynamics AX notwendig, um allen Online-Benutzern eine E-Mail zu senden:

1. Eintragen des zu verwendenden SMTP-Servers unter Verwaltung / Einstellungen / E-Mail-Parameter
2. Erstellen eines E-Mail-Vorlage vom Typ System unter Grundeinstellungen / Einstellungen /  E-Mail-Vorlage
   Hier kann der Betreff und der Text der zu versendenden Mail um den Platzhalter %username% erweitert werden.
3. Versenden der Mail unter Verwaltung / Periodisch / E-Mail-Aussendung

Man kann auch an alle Benutzer einer Installation versenden.

Für technisch Interessierte: Die verantwortliche Klasse ist die SysEmailBroadCast.

Wenn ein Absender Microsoft Outlook oder Outlook-Express verwendet kommt es vor, dass der Empfänger die im Mail enthaltenen Attachements als winmail.dat erhält. Das Problem tritt dann auf wenn der Empfänger keinen Mail-Client von Microsoft verwendet, und der Absender das Mail im "Microsoft Outlook Rich Text Format" (RTF) versendet.

Leider versendet auch Dynamics AX genau in diesem Format, wenn man z.B. einen Report aus AX heraus als PDF einem Empfänger schicken möchte (und selbst auf seinem PC als Mail-Client Outlook verwendet).

Der einzige Workaround für dieses Problem besteht darin, den zu schickenden Report zuerst als PDF zu speichern, und anschließend manuell mit Outlook zu versenden. Der Nachteil dabei ist natürlich der etwas höhere Aufwand, der Vorteil ist daß der Text des Mails angegeben werden kann - auch AX 2009 verwendet immer noch den Fixtext axapta report - und auch eine evtl. vorhandene Standardsignatur verwendet wird.

In Dynamics AX 4.0 haben sich in der Klasse SysMailerAddressField in Methode appendAddress einige Fehler eingeschlichen. Diese Fehler treten immer dann auf, wenn man per SysMailer Mails an mehr als einen Empfänger versenden möchte bzw. zusätzlich zur Empfängeradresse auch Empfängernamen angibt.

Hier wird bisweilen das Mail entweder nur an die zuletzt hinzugefügte Mail-Adresse versandt oder aber die send-Methode des SysMailers verweigert ganz ihren Dienst, wenn man Empfängernamen angibt.

Nachstehend der - aus meiner Sicht - korrekte Code:

// Add item to the collection
void appendAddress(str addr, str name='')
{
    str address;
    str addresses;

    if (prmisdefault(name))
    {
        address = addr;
    }
    else
    {
        address = name + ' <' + addr + '>';
    }

    addresses = this.get();

    if (strlen(addresses) > 0)
    {
        address = addresses + ',' + address;
    }

    this.set(address);

    addressCount++;
}

Aufgefallen sind mir die Fehler bislang bei Version 4.0 bis inkl. SP2.

Manchmal ist es notwendig, eingegebene E-Mail-Adressen auf deren Syntax hin zu überprüfen. Genau für dieses Zweck habe ich die nachfolgende Methode geschrieben. Schliesslich verfügt MS Dynamics AX erst ab Version 4.0 über eine entsprechende eigene Methode (SysEmailDistributor.validateEmail).

static boolean isValidMailAddress(str _mailAddress, str 2 _separator4MultipleAddresses = ";")
{
    // Prüft Mail-Adressen auf ihre Gültigkeit.
    // Es können auch mehrere Adressen auf einmal geprüft werden, dabei ist der Parameter _separator4MultipleAddresses zu verwenden

    boolean     ret = true;
    int         i = 0;
    str 1       buchstabe, firstZeichen = '', firstDomainZeichen;
    int         firstAT = 0, firstDot = 0, lastDot = 0;
    str         errorText = '';
    int         z, x, y;
    email       SubMailAddr;
    container   SubMailAddrContainer, c;

    container str2conLocal(str _value, str 10 _sep = ',')    // str2con von AX30 ist fehlerhaft, wenn der ein Teilstring mit einer
    {                                                        // Zahl beginnt und als Separatir , verwendet wird
        int length = strlen(_value);
        int u = 1;
        int j = strscan(_value, _sep, 1, length);
        container retContainer;
        while (j)
        {
            retContainer+=(substr(_value, u, j-u));
            u = j+1;
            j = strscan(_value, _sep, u, length);
        }
        retContainer+=(substr(_value, u, length-u+1));
        return retContainer;
    }
    ;

    if(strLen(_MailAddress) == 0)
    {
        return true;
    }

    SubMailAddrContainer = str2conLocal(_MailAddress, _separator4MultipleAddresses);

    for(z=1;z<=ConLen(SubMailAddrContainer);z++){
        SubMailAddr = ConPeek(SubMailAddrContainer,z);
        if(subMailAddr == '')
        {
            continue;
        }
        // Variablen initieren
        i=0;
        firstzeichen='';
        firstDomainZeichen='';
        lastdot=0;
        firstDot=0;
        firstAT=0;
        buchstabe='';
        errorText = StrFmt('Die E-Mail-Adresse "%1" wurde falsch eingegeben', subMailAddr) + '. ';

        // ###### Start der Prüfung ###########
        lastDot = strFind(SubMailAddr, '.', strLen(SubMailAddr), -1 * strLen(SubMailAddr));

        // @ muß zumindest einmal vorkommen
        firstAT = StrScan(SubMailAddr, '@', 1, strLen(SubMailAddr));
        if(firstAT == 0)
        {
            return checkFailed(errorText + 'In der Mail-Adresse muß zumindest ein @-Zeichen vorkommen');
        }
        // @ darf nur einmal vorkommen
        if(StrScan(SubMailAddr, '@', firstAT + 1, strLen(SubMailAddr)) != 0)
        {
            return checkFailed(errorText + 'Das @-Zeichen darf nur einmal vorkommen');
        }

        // . muß zumindest einmal vorkommen
        firstDot = StrScan(SubMailAddr, '.', 1, strLen(SubMailAddr));
        if(firstDot == 0)
        {
            return checkFailed(errorText + 'In der Mail-Adresse muß zumindest ein Punkt vorkommen');
        }

        // nach dem @ muß zumindest 1 punkt kommen
        if(StrScan(SubMailAddr, '.', firstAT, strLen(SubMailAddr)) == 0)
        {
            return checkFailed(errorText + 'Nach dem @-Zeichen muss zumindest ein Punkt vorkommen');
        }

        // nach dem letzten punkt darf nur 2 bis 4 zeichen kommen
        if(StrLen(SubStr(SubMailAddr,lastDot +1,strLen(SubMailAddr))) > 4 || StrLen(SubStr(SubMailAddr,lastDot +1,strLen(SubMailAddr))) < 2)
        {
            return checkFailed(errorText + 'Die Domän-Endung muss aus mindestens 2 und maximal 4 Zeichen bestehen');
        }

        // Sub-Domänen müssen zumindest 2 Stellen gross sein und müssen mit A-Z oder 0-9 anfangen
        c = str2conLocal(SubStr(SubMailAddr, firstAT + 1, strLen(SubMailAddr)), ".");
        for (x=1; x<=conLen(c); x++)
        {
            firstDomainZeichen = SubStr(conPeek(c,x), 1,1);
            if( !( ( char2num(firstDomainZeichen,1) >= 97 && char2num(firstDomainZeichen,1) <= 122 ) ||
                   ( char2num(firstDomainZeichen,1) >= 48 && char2num(firstDomainZeichen,1) <= 57 ) ||
                   ( char2num(firstDomainZeichen,1) >= 65 && char2num(firstDomainZeichen,1) <= 90 ) ) )
            {
                return checkFailed(errorText + 'Jede Subdomäne muss mit einem Buchstaben oder einer Zahl beginnen');
            }

            if(strLen(conPeek(c,x)) < 2)
            {
                return checkFailed(errorText + 'Jede Subdomöne muss aus zumindest 2 Zeichen bestehen');
            }

            // Subdomänen dürfen nur aus A-Z 0-9 oder - bestehen
            for(y=1;y<=strLen(conPeek(c,x));y++)
            {
                buchstabe = SubStr(conPeek(c,x),y,1);
                if( !(char2num(buchstabe,1) == 45 ||    // -
                      ( char2num(buchstabe,1) >= 97 && char2num(buchstabe,1) <= 122 ) ||
                      ( char2num(buchstabe,1) >= 48 && char2num(buchstabe,1) <= 57 ) ||
                      ( char2num(buchstabe,1) >= 65 && char2num(buchstabe,1) <= 90 ) ) )
                {
                    return checkFailed(errorText + strFmt('In der Subdomäne "%1" ist das Zeichen "%2" nicht erlaubt!',conPeek(c,x),buchstabe));
                }
            }
        }

        // Text vor dem @ (durch Punkte getrennt) muss mindestens 1 Stelle lang sein
        c = ConNull();
        c = str2conLocal(SubStr(SubMailAddr, 1, firstAT-1), ".");
        for (x=1; x<=conLen(c); x++)
        {
            if(strLen(conPeek(c,x)) < 1)
            {
                return checkFailed(errorText + 'Der Text vor dem @-Zeichen ist ungültig');
            }
        }

        // muß mit a-z oder A-Z oder 0-9 beginnen
        firstZeichen = SubStr(SubMailAddr, 1,1);
        if( !(( char2num(firstZeichen,1) >= 97 && char2num(firstZeichen,1) <= 122 ) ||
            ( char2num(firstZeichen,1) >= 48 && char2num(firstZeichen,1) <= 57 ) ||
            ( char2num(firstZeichen,1) >= 65 && char2num(firstZeichen,1) <= 90 )) )
        {
            return checkFailed(errorText + 'Die Mailadresse muss mit einem Buchstaben oder einer Zahl beginnen');
        }

        // Gültiges Zeichen
        i = 0;
        for(i=1;i<=StrLen(SubMailAddr);i++)
        {
            buchstabe = SubStr(SubMailAddr,i,1);

            if( !(char2num(buchstabe,1) == 46 ||    // .
                  char2num(buchstabe,1) == 45 ||    // -
                  char2num(buchstabe,1) == 95 ||    // _
                  char2num(buchstabe,1) == 64 ||    // @
                  char2num(buchstabe,1) == 228 ||   // ä
                  char2num(buchstabe,1) == 252 ||   // ü
                  char2num(buchstabe,1) == 246 ||   // ö
                  char2num(buchstabe,1) == 196 ||   // Ä
                  char2num(buchstabe,1) == 220 ||   // Ü
                  char2num(buchstabe,1) == 214 ||   // Ö
                  ( char2num(buchstabe,1) >= 97 && char2num(buchstabe,1) <= 122 ) ||
                  ( char2num(buchstabe,1) >= 48 && char2num(buchstabe,1) <= 57 ) ||
                  ( char2num(buchstabe,1) >= 65 && char2num(buchstabe,1) <= 90 ) ) )
            {
                return checkFailed(errorText + strFmt('Ungültiges Zeichen "%1" in der Mail-Adresse', buchstabe));
            }
        }
    }

    return true;
}

Obiger Code sollte in allen AX-Versionen funktionieren. Verwendung natürlich auf eigene Gefahr.