Setting Up and Managing E-mails and Batch Processing

Simon Buxton

November 2013

(For more resources related to this topic, see here.)

Setting Up and Managing E-mails and Batch Processing

The batch framework processes more than the recurring system tasks; users can submit jobs from many places within AX. This allows them to continue with their primary tasks without having to wait for the operation to finish. An alert can be set up to alert them about the success or failure of the task.

Using e-mails correctly makes the system look more professional and user friendly; instead of the basic text details in system-generated e-mails, they can be branded with your corporate identity and laid out in a more appealing manner.

There are two methods by which e-mails are sent in AX: SMTP and MAPI.

MAPI (Messaging Application Programming Interface) is a client-side method that opens a new message in your e-mail client (Microsoft Outlook, for example), potentially setting the recipients and subject from the data in AX. Attachments can also be added via MAPI (for example, while sending a report via an e-mail from AX). SMTP (Simple Mail Transfer Protocol) is a server-side method and is used for server-generated e-mails such as alerts and workflow notifications.

MAPI is not always desirable due to its client-side dependence on an e-mail client, which causes problems when running the client as a remote app. A common modification is to replace it with SMTP as the e-mail is then sent by the server without requiring a client-side e-mail client. There are add-ons that achieve this and some can even autoroute the documents based on the routing information.

The other advantage of SMTP server-side e-mails is that they can be richly formatted using HTML templates created through a built-in editor, and can use placeholders for information such as the details of a system alert.

SMTP requires the mail server to act as a relay for AX, as is the case of Microsoft Exchange. Your SMTP server should be configured to allow Dynamics AX to relay e-mails through it.

The batch framework allows many AX functions to be processed either as scheduled recurring jobs, or as once-only tasks to be processed asynchronously to the AX client by the AOS.

Typically, the tasks performed by the batch framework are scheduled jobs (for example, nightly sales invoice posting), or a process triggered by a user for which the user does not require an immediate response (for instance, processing an MRP calculation). In this case, the user may request an alert of its completion. Although users usually prefer the comfort of a progress bar and a message to state that it has been completed, submitting it as a batch job for many tasks is far more efficient as it allows them to perform other tasks while the server processes the task.

Developers also have the ability to use the batch framework to submit asynchronous requests from within a transaction, so as to improve the user response time. This may strike an element of fear in those who consider that the transactions should obey the ACID ( Atomic, Consistent, Isolation, and Durability) transaction principle; these will be for tasks where a compensation pattern can be implemented in order to handle an inconsistent state. A real-life example of this is the coffee shop queue, where you order and pay for your coffee, complete the transaction, and then wait for the coffee. If the coffee is not available, you would be compensated by the shop giving you your money back post transaction.

Not all transactions can ACID principle; for example, posting a supplier payment that sends remittances by e-mail. If the transaction fails after the e-mail has been sent, the database transaction will be rolled back, leaving the e-mail in the supplier's inbox.

There are some important yet not so obvious points to consider when working with the batch framework:

  • The batch framework runs on the server tier, and therefore, on a Windows Server that hosts the AOS service. This means that the server should be able to access any file paths, printers, and so on. The tasks will run as the security context of the user who submitted the task, but any external access (for example, files) is performed using the AOS service account.
  • This note is mainly for developers. The tasks will run in CIL; this means you may find that the old code is executed even when a change has been made to your X++ code. This includes reports that run interactively, all code that runs on the server tier, and certain code that is client-side and pushed to the server tier for performance. The only way to ensure that the new code is being run is to restart the AOS service.
  • Setting up e-mail parameters

    The e-mail parameters control the connection to your SMTP server, for example, Microsoft Exchange Server, if configured.

    Getting ready

    You will need the details of the SMTP server, including any special login details for the server.

    How to do it...

    Carry out the following steps to set up the e-mail parameters:

    1. Launch the Dynamics AX client as a system administrator.
    2. Navigate to System administration | Setup | System | E-mail parameters.
    3. The details you enter are dependent on your SMTP server configuration. Typically, you only need to specify the Outgoing mail server value (which should be Fully Qualified Domain Name (fqdn), if externally hosted) or the IP address of the SMTP server, as shown in the following screenshot:

    4. You should leave the Local computer name field blank; if you specify Outgoing mail server, this setting is ignored.
    5. The login details (User name and Password) should be set as per your server's requirements.
    6. If you check Use NTLM, you will not be able to enter the username and password; it will use the security context of AX Server if the code is running on the server tier, or of the user if the code is running on the client tier.

      You may find that if you do not set the username and password, it will work in some cases and not in others (for example, if you are using an add-on that sends the SMTP e-mail using the AX client's process, the username and password are required). This is normally due to the relay configuration within the SMTP server.

    7. The Attachment size limit (MB) value is useful to prevent the user from attaching documents greater than what the size of your e-mail system allows.

    How it works...

    These settings are used by the SMTP e-mails sending business logic. When an e-mail is sent, it logs on to the SMTP server using the information in E-mail parameters. If this fails, an error is returned and the e-mail will be marked as failed within the e-mail-sending status form. This is shown later in the Monitoring e-mails recipe.

    If you are sending a report from AX using the AX client, the SMTP mail is not used as the standard AX uses MAPI (for example, using your e-mail client) to send the mail.

    Configuring the e-mail templates

    E-mail templates are used in several instances in AX in order to send neatly formatted e-mails, often with the ability to include personalization, for example, recipient-specific information, like a mail merge.

    In this recipe, we will set up a template to use in the e-mail broadcasting feature of AX in order to ask the users to log out of AX.

    If you are configuring a template to use from an add-on or a custom code, you should ask the author or the supplier about the available template fields in order to personalize the message.

    Getting ready

    In order to set up this e-mail, you will need to have an e-mail account that the system will send on behalf of, and of course, the design of the e-mail template you wish to create.

    You can paste in the prepared HTML code, if required; this is useful if you have the branding already designed in HTML format.

    How to do it...

    To configure the e-mail template, please follow these steps:

    1. Launch AX as the system administrator.

      You would normally select the company that the alert is for; in the case of system e-mails (alerts, broadcasts) that run independent of the company context, this is not necessary.

    2. Navigate to Organization administration | Setup | E-mail templates.
    3. In this case, we are configuring a system e-mail, so you should check Show system e-mails, as shown in the following screenshot:

      The Show system e-mails checkbox is unchecked by default as it assumes that you are configuring an e-mail for your current company. This checkbox determines whether the alert is created for the company DAT (which is where the system-wide configuration is stored), or for your current company.

    4. To create a new e-mail template, press Ctrl + N.
    5. The E-mail ID value (for example, Logout) is an identifier for the template.
    6. Enter the description of the e-mail template in the E-mail description column, for example, Logout E-mail Template.
    7. The e-mail content can be written and stored in multiple languages. Here you can specify a default language to which the e-mail messages will default if the requested language is not found.
    8. The Sender name value is the name you wish the e-mail to be from, for example, Dynamics AX.
    9. The Sender address is the e-mail address to be used, for example,; you may need this to be configured within your SMTP server.
    10. On the General tab, you can set further parameters. Specifying a batch group will instruct AX to send the e-mails using the batch framework, which can improve performance when sending large volumes of e-mails.

      If the batch framework is used, the user is not made aware of errors and any code that runs will not be able to trap errors sending the e-mail (that is, should the process rollback if the e-mail doesn't send?)

    11. For each language you wish to send the e-mail in, create a record in the lower grid, as shown in the following screenshot:

    12. On this grid, you should specify the language and subject of the e-mail.
    13. In most cases, you will use HTML as the e-mail message format; but you can also use XSLT, which will be transformed when the e-mail is generated.
    14. Click on E-mail message.
    15. The HTML editor has three tabs:
    16. Normal: This is a rich text editor for composing an HTML message that is similar to using a word processor
    17. HTML: This allows you to write or edit HTML code
    18. Preview: This previews the resulting message, although it's basically a read-only view of the Normal tab
    19. If you have HTML code to paste in, use the HTML tab. If you intend to insert images, they should be a URL or placed on a network share to which the user, AOS host server, and AOS Service account has access.
    20. You can begin by writing the e-mail in the Normal tab and then move to the HTML tab for finer control. A change in one tab updates the other.
    21. In this case, the broadcast feature has the tag UserName available, so we shall use this, surrounding it by % characters as follows:

      Dear %UserName%,
      Please log out of your AX client, we will send a
      separate e-mail once the system is available. Kind regards, Dynamics AX Support Team

    22. Check the code in the HTML tab. It has used <p> tags for the blank lines, but I prefer <br/ >
      in order to follow HTML standards. This can be changed in the HTML tab.

      <p>Dear %UserName%,</P> <br/ > <p>Please log out of your AX client, we will send a
      separate e-mail once the system is available.</p> <p>Kind regards,</p> <br/ > <p>Dynamics AX Support team</p>

      Switching to the Normal tab and back again will cause the editor to recreate the HTML code, replacing the <br/ > tag with <BR>, which can't be controlled.

    23. Once complete, click on the Save icon and close the e-mail editor.
    24. To test this, navigate to System administration | Periodic | E-mail processing | E-mail broadcast. This form states that the tag %UserName% can be used, as shown in the following screenshot:

    25. Select the e-mail template using the E-mail ID drop-down list.

      If the e-mail template does not appear, it means that it was not created as a system e-mail. You will need to recreate the e-mail template with Show system e-mails checked.

    26. Select All online users.
    27. Click on OK.

    How it works...

    When e-mails are submitted to the e-mail queue, they are done so with the e-mail ID of the template. The code that creates the e-mail message will use the template to set the sender, subject, and e-mail body as HTML.

    The actual sending of the message is done using CDO (Collaborative Data Objects, a library that is part of the Windows operating system). If errors are reported, they can be difficult to interpret. The most common causes of a failure are:

  • The SMTP server was not configured to allow AX to relay through it
  • The SMTP server could not be contacted
  • The target e-mail address was invalid
  • The e-mail parameters were not configured correctly
  • Sometimes, using the IP address of the SMTP server instead the hostname can fix the problem, if the cause was a problem with the DNS resolution or Kerberos (specifying an IP address in this case bypasses the Kerberos authentication).

    There's more...

    The use of tags or variable maps was touched on in this example. The actual variables you can use depends on the function that is sending the e-mail. The e-mail broadcast only contains UserName. The alerts support the variables that contain the details of the alerts.

    You may find far more information available in the custom code or add-ons, especially if you are using a document-routing application that sends documents (for example, sales invoices) to your customers and suppliers.

    The e-mails can also contain hyperlinks that can launch the AX client and navigate to a specific form, showing the record in question. This is currently implemented for alerts as a "drill through target", but a developer can extend this feature for other purposes.

    See also

  • How Outlook, CDO, MAPI, and Providers Work Together:
  • Monitoring e-mails

    Occasionally, e-mails may fail to send. If they are being sent through the batch framework, the message will remain in the Outgoing e-mail table.

    This table only shows e-mails that were sent via the batch framework. E-mails that are sent directly (for example, the e-mails that don't have the Batch group set) report errors directly to the user in Infolog.

    Getting ready

    Simply log in to AX as the system administrator.

    How to do it...

    To monitor the outgoing e-mails or to resend failed e-mails, please follow these steps:

    1. Navigate to System administration | Periodic | E-mail processing | E-mail sending status. This opens the date filter from the Outgoing e-mail table, filtered to only those with errors, as shown in the following screenshot:

    2. You can view the sent e-mails by clicking on Also show sent e-mails. Again, only e-mails that are sent via batch framework are visible here.
    3. You can click on Show message to display the e-mails rendered as HTML.
    4. In order to retry sending a failed message, click on Restart send.
    5. You can create an alert against the records that have failed; you can thus avoid having to manually check the table.
    6. If the fault is with the SMTP configuration, the message will not be created in this table, it will be in the batch queue as an error.

    7. Click on Log to see the message; in this case, the SMTP server cannot be contacted.
    8. To correct the e-mail parameters, navigate to Function | Change status and change the Batch Job status to Waiting.

    How it works...

    All the e-mails sent via the batch queue are created in the Outgoing e-mail table. If the e-mail process fails, the record is updated with an error status. The form is simply a view of this table, filtered to those with the status of not sent.

    There's more...

    If you see the e-mails not sent and just sitting in outgoing e-mail table, it will most likely be because the batch process has not been triggered or has failed.

    To trigger the batch service:

    1. Navigate to System administration | Periodic | E-mail processing | Batch .
    2. In the batch submission form, select a Batch group that will process the e-mails and check Batch processing .
    3. Next, click on Recurrence .
    4. Ensure that No end date is selected (by default, it runs once).
    5. Set the frequency at which any unsent e-mails in the queue should be sent; the default is 10 minutes and should suffice.
    6. Click on OK in the recurrence form.
    7. Click on Alerts, ensure that only Error is selected, and click on OK.
    8. Click on OK that appears on the batch dialog, which submits the task to the batch framework.

    Setting up batch groups

    Technically, there is no requirement to have more than one batch group and that group could be "blank" (so you can assign batch jobs to an AOS that does not have a batch group). However, this would be a poor configuration as it will limit future scalability.

    Batch groups need to be assigned to one or more AOS instances. If a batch group is not assigned to an AOS, none of the jobs assigned to that group will run. The AOS instance may also have a window of operation. This way you can utilize an AOS that is normally used for user connections; for example, at times it runs when users are less likely to be using the system.

    Getting ready

    Before we start, we should decide the batch groups required. There are some standard system batch groups, common user batch groups, and some others that you feel are required.

    We should not create unnecessary batch groups as the users will see all the batch groups when they submit their jobs.

    The following are examples of commonly used batch groups:

    User batch groups


    General tasks requested by users


    Reports submitted by users

    System batch groups


    For processing AIF queues and other operations


    Alerts for change-based alerts.


    Alerts for due-date-based alerts.


    Workflow message processing jobs


    Workflow due date processing jobs


    Workflow line-item notifications jobs

    You should ensure that the system groups appear last, so as to avoid users selecting them by mistake.

    Batch groups designated to process date-based jobs should be configured to only run once a day (depending on the time-zone requirements). This is an example of a batch group that could be configured to run out of hours on an AOS that users would normally connect to.

    Remember to schedule the date-based jobs to run after midnight (noting the time zone) otherwise, it will be a day late!

    How to do it...

    A batch group is created by following these steps:

    1. Launch AX as a system administrator.
    2. Navigate to System administration | Setup | Batch group

      You will notice there is a group with a blank ID called Empty batch group ; do not try to delete this group. This is needed as a default in case a user submits a job without specifying the batch group.

    3. In the Batch Group form, click on New.
    4. Enter ID of the group (limited to 10 characters), remembering that user groups should appear at the top of the list.
    5. Enter Description; it should be easy to understand as the users will see this, and you may want to prefix the system groups with "System-only".
    6. Select the Batch server tab.
    7. You will notice the server(s) are all in the right-hand pane, which means that the group will not execute.
    8. Select the appropriate AOS and drag (or click on) to the left-hand pane.

      You should have a dedicated batch server for routines that run during the day (that is, while the users are logged in); however, it is fine to add other AOS instances if they are configured to only run batch jobs out of hours.

    9. Once complete (when all the batch groups are added and configured) close the form.

    How it works...

    When jobs are submitted to the batch framework, the user selects a batch group (or leaves the field blank, which selects the empty batch group).The batch group determines the AOS that will execute the job.

    Mapping batch groups to batch servers

    One of the main reasons for creating separate batch groups is to assign the jobs to be run on specific batch servers within them. When created, batch groups are by default not assigned to any batch servers, so any jobs assigned to them will not run.

    Getting ready

    This is an extension to creating a batch group. All we need is a batch group and an AOS configured to run as a batch server, either full time or within specific windows.

    How to do it...

    To map a batch group to a batch server (AOS configured to run batch jobs), follow these steps:

    1. Navigate to System administration | Setup | Batch group, and select the batch group to assign to a batch server.

      You will notice all AX Servers (AOS) will appear in the Remaining servers pane, regardless of whether or not the AOS has been designated as a batch server.

    2. Select the AOS to assign and click or drag it over to the Selected servers pane.
    3. Continue the same for each batch group that needs to be assigned to one or more batch servers.
    4. Once complete, close the form and the changes are made immediately.

    How it works...

    The mapping between AOS and the batch group can be done from the Server configuration ( System administration | Setup | System |Server configurationBatch server groups fast tab) or from the Batch group form; the data is the same, just shown from a different perspective.

    When a batch server looks for its next job, it does so by looking for jobs that are assigned to batch groups to which it, the AOS, is mapped. It then marks the job as "executing" so that no other batch server tries to start the job. We can therefore configure more than one AOS to process the same batch group.

    Assigning a task to be performed as a batch task

    This process would be a common process for your users. This allows users to submit long-running tasks to the server, allowing them to continue using AX while the server processes the task. This is often underused, leaving users to watch an unresponsive screen while they wait for complex routines to finish (for example, a set of delivery notes to be printed).

    Getting ready

    Most users will be able to submit jobs as batch tasks. This example submits a Master plan schedule to be run as a batch task, so we will require appropriate privileges. The process is similar for most tasks that utilize the batch framework.

    How to do it...

    We proceed as follows:

    1. Navigate to Master planning | Periodic | Master Scheduling.
    2. Select a master plan as required (for the purpose of this exercise, any will suffice).
    3. Click on the Select button and use the query dialog to filter on an item or item group; this is merely to show that this information is stored against the batch task.
    4. Select the Comment tab and enter a comment in the Comment textbox, for example, Master plan for procured items.
    5. Select the Batch tab.
    6. Check Batch processing and select an appropriate Batch group .
    7. The task description appears against the item in the batch queue, so you may change this if you want to easily identify it later. However, this is normally left as default.

      Ignore the private checkbox as this applies only to client tasks and is considered a "legacy" feature.

    8. Click on Recurrence.

      The default options here are to start as soon as possible and run only once.

    9. Adjust the start date and time if required.
    10. Change the option for No end date, End After, or End by. The default is End after 1.
    11. If this is a recurring task, you should review the Recurring pattern (which is straightforward).

      If this is a recurring task that you wish to run frequently (for example, monitoring a folder to import files), don't set this to every minute without considering if this is actually necessary as this may add unnecessary load to the server.

    12. Click on OK on the Recurrence dialog.
    13. Click on Alerts.
    14. You have the options to limit what you are alerted about and whether or not you should be alerted. If this is a task that runs frequently, you will almost certainly not want Ended alerts (which would send an alert every time the job is executed successfully).

      The Batch processing setting is remembered and becomes default when the next task is run. If the users want to run the task interactively, they will need to clear this checkbox.

    How it works...

    Many of the tasks you can perform interactively have a Batch tab that allows you to submit the task as a batch job. When the task is submitted, it is written to the batch queue with the following information:

  • The task to be performed
  • The batch group in which the job should be processed (remember, "blank" is also a valid batch group)
  • Alert setting information
  • The information entered into the dialog; the query and other parameters that were entered when the task was submitted
  • Recurrence information
  • The batch server(s) will select the jobs to process based on the following:

  • Does the batch group on the batch task fall within its list of batch groups?
  • The time it should start, which is more accurately called "Do not start before"
  • The status is Waiting
  • The batch server will rehydrate (unpacked from the batch job record's packed data container) the task and execute it under the security context of the user who submitted it, with the options the user specified.

    Should the task succeed, the status will be updated to Ended and an alert will be sent to the user (if this was configured). If the job failed, the status will be changed to Error and an alert will be sent to the user (again, only if configured). In both the cases, the infolog (message) that was created by the task will be stored against the task, allowing the user or administrator to investigate any errors.

    You can go to an item in the batch queue anytime before it starts executing to view and change the information on the initial dialog, alert request, or the recurrence information. You should first change the status to Waiting, as you will not be able to save the changes if the job starts in the mean time.

    There's more...

    You can also create batch jobs directly in the queue. For instance, the AIF-processing jobs are configured in this way.

    The following example is to add the AIF tasks to a batch job:

    1. Navigate to System administration | Inquiries | Batch jobs.
    2. Click on New (Ctrl + N or File | New).
    3. Enter the description AIF Processing.

      The start time will be set to now, which is fine in this case; this can be made to be the initial start time (for example, 02:00 tomorrow for nightly jobs).

    4. Click on View tasks.
    5. In the batch tasks form, click on New (Ctrl + N, or File | New).
    6. In the task's description, enter AIF Receive.
    7. Select or enter AifGatewayReceiveService for the class name.
    8. Select an appropriate batch group, for example, Sys-AIF.
    9. Press the down arrow (or Ctrl + N) to create additional tasks for the following, in the order stated:AifInboundProcessingService
    10. AifOutboundProcessingService
    11. AifGatewaySendService
    12. To set conditions for the task so that they only run based on the result of the previous task, click in the lower grid and press Ctrl + N, as shown in the following screenshot:

    13. Once complete, close the form, which brings us back to the batch job form.
    14. You can now decide to enable alerts and set the recurrence as before.
    15. Finally, click on Functions | Change status to move the status from Withhold to Waiting; this enables the batch job.

    Query functions

    You can also use functions to generate relative dates; these are not documented formally, but the code is well-documented and easily read by a developer.

    A developer can even extend them to provide more functions to the user.

    These are the static methods on the class SysQueryRangeUtil.

    The common methods are:


    Example usage in a query range criteria








    (day(10)) current date plus 10 days


    (dayRange(1, 5)) date range of today plus 1 and today plus 5


    (greaterThanDate(-5)) records where the date is greater than the current minus 5 days


    (greaterThanUtcDate(1)) for UTC dates, records from tomorrow


    (greaterThanUtcNow()) for UTC dates, records from now


    (lessThanDate(-90)) records older than 90 days


    (lessThanUtcDate(-90)) for UTC dates


    (lessThanUtcNow()) for UTC dates, record before now


    (monthRange(1, 2)) records from the start of the next month to for 2 months


    (yearRange(0, 1)) records in this year

    Resources for Article:

    Further resources on this subject:

    You've been reading an excerpt of:

    Microsoft Dynamics AX 2012 R2 Administration Cookbook

    Explore Title