Introduction

This article describes how to adjust an existing task to notify the task administrator that a task instance has generated failed emails.

Scenario

You have a task that sends emails to multiple contacts, either different per task run or during each task run-time. Either yourself or the task administrator (owner) wants to be notified each time an email attempt fails.

Required Tools

►

Decision The Decision tool is used to control the flow of a task process, based on the result of one or more expressions. The decision works by testing a sequence of Boolean (true/false) conditions in turn until an expression returns true. When a true condition is returned then that particular branch of the process is followed. — The Decision step uses the FailCount property from the original Send Email (SMTP) The Send Email (SMTP) tool sends messages to any SMTP compliant mail server. This tool is capable of sending multiple messages in either text or HTML formats, incorporating data from Input and Format steps to any number of recipients. If recordset data being used from an Input step includes a column containing email addresses, then this can be used as a "dynamic" recipient address. step to trigger whether the rest of the task continues

►

Database Query (either ODBC or OLEDB) — This step queries the BPA Platform store for the email addresses that the task failed to deliver to.

►

Format as HTML — The results from the query are saved to an HTML report as a table .

►

Send Email (SMTP) — The report is emailed to the task administrator.

Prerequisites

A global connection to the BPA Platform store is required. You can do this in your preferred Database Query tool. Typically, the BPA Platform store is held in the BPAPlatform database, however, a different database name can be entered at configuration time. To find the name of your store, do the following:

1. Launch the Configurator You use the Configurator to install third-party software that may be required by available tools. Connection to required agents are also configured here. Note that you can only launch the Configurator if logged into the machine with Administrator rights..
2. Expand the Server > Store > Configuration nodes.
3. Enable Change store configuration and click Next.
4. The current store name is under Database. Click Close then No to not save any changes. Avoid changing the store database name as events and tasks in the original store may not be available to you.

Logging and Notifying Failed Emails

The required tools are added after the Send Email (SMTP) step in your task. Do the following:

1. Open the relevant task.
2. Open the existing Send Email (SMTP) step and go to the Options tab.
3. Change If an error occurs to Continue.
4. Click OK to save and close the Send Email (SMTP) step.
5. Add a Database Query step.
   1. In the General tab, choose the global connection you created in Prerequisites.
   2. In the Query tab, expand the EventLog node.
   3. Add the following columns to the Columns pane:

      EventSource
      TaskID
      EventCategory
      EventDesc
      EventTime

   4. Add Criteria for the following (these are all linked by AND):

      EventSource = The original Send Email (SMTP) step's name
      

      How Do I Do This?

      1. Drag the EventSource column to the Criteria pane.
      2. Select a criteria of equals [C].
      3. From the Task Browser's Environment tab, change Scope to be Task.
      4. Expand Steps > <the_original_Send Email (SMTP)_step>.
      5. Drag the Name property to the available criteria box for EventSource.

      TaskID = This task's ID
      

      How Do I Do This?

      1. Drag the TaskID column to the Criteria pane.
      2. Select a criteria of equals [I].
      3. From the Task Browser's Environment tab, change Scope to be Task.
      4. Drag the TaskID property to the available criteria box for TaskID.

      EventTime = The start time of the original Send Email (SMTP) step during the task run
      

      How Do I Do This?

      1. Drag the EventTime column to the Criteria pane.
      2. Select a criteria of equals [D].
      3. From the Task Browser's Environment tab, change Scope to be Task.
      4. Expand Steps > <the_original_Send Email (SMTP)_step>.
      5. Drag the Started property to the available criteria box for EventTime.

   5. Add the Sorting pane to the view ().
   6. Add EventTime to the sorting pane.

   We need to add a few more things to our SQL statement that, at the time of writing, aren't handled by the interface.

   1. Click to change into free-type mode. Accept the warning.
   2. Add an additional AND criteria to the WHERE statement: EventLog.EventDesc LIKE 'Sending%@%'. This searches for event descriptions that start with "Sending" and have an @ symbol somewhere in the description.
   3. Change the ORDER BY statement to be descending (DESC).

   The final SQL statement should look like:

   SELECT
     EventLog.EventSource AS EventSource
     EventLog.TaskID AS TaskID
     EventLog.EventCategory AS EventCategory
     EventLog.EventDesc AS EventDesc
     EventLog.EventTime AS EventTime
   FROM
     EventLog
   WHERE
     EventLog.EventSource = '{=Steps("<Send Email (SMTP) step name>").Name}'
     AND EventLog.TaskID = {=Task.TaskID}
     AND EventLog.EventTime = {=Steps("<Send Email (SMTP) step name>").Started}
     AND EventLog.EventDesc LIKE 'Sending%@%'
   ORDER BY
     EventLog.EventTime DESC

   Click OK to save and close the Database Query step.

6. Add a Decision step which uses a decision branch to check for a failed Send Email (SMTP) step. If none is found, the remaining task steps do not fire.
   How Do I Do This?

   1. Add a new decision branch.
   2. In the General tab, Name the branch and choose the new Database Query step (step 5) as the To step.
   3. In the Script tab, drag the FailCount property for the original Send Email (SMTP) step to the available script box.
   4. Add >0 to the end of the line so the script reads: Steps("<Send Email (SMTP) step name>").FailCount>0.

   Click OK to save and close the Decision step.

7. Add a Format as HTML step which consumes the recordset from the Database Query step from step 5 and presents the data in an HTML table.
   How Do I Do This?

   1. In the General tab, enable Use a Recordset.
   2. From the Input Recordset drop-down, select the new Database Query step from step 5.
   3. Go to the Formatting tab and click Design.
   4. From the Task Browser's Environment tab, change Scope to be This Step.
   5. Expand FormatData > Recordset and drag each column in turn to the HTML Table Designer.

      

      Click the image to view full size.

   6. Adjust the column attributes as required — for more information, see How to Add a Format as HTML Task Step.
   7. Click OK to save the HTML table.
   8. If required, add further HTML elements to the document else click OK to save and close the Format as HTML step.
8. Finally, add another Send Email (SMTP) step which emails the output from the Format as HTML step to the task administrator.
   How Do I Do This?

   1. In the General tab, enable Read documents from a source.
   2. From the Document Source drop-down, select the Format as HTML step.
   3. Go to the Connection tab and choose the SMTP server to send this email through.
   4. In the Main tab, add relevant From and To email addresses and a Subject.
   5. In the Message Contents pane, enable Document Output.
   6. Click OK to save and close the Send Email (SMTP) step.
9. Link the new steps as follows:

   

   How Do I Do This?

   1. Steps are linked left-to-right in the order of the process flow. Click the first step to show the step controls. Click and hold then draw the connection to its succeeding step.
   2. Repeat for all steps. Note that the Decision step is automatically linked to its successor.

That's all the required configuration. It may be an idea to run a quick test of your completed task to ensure the correct details are sent for a failed email attempt.