Build-On Tutorial:

Upcoming Tasks

Upcoming Tasks: Lesson 3

Send Upcoming Task Email

Lesson Overview

In this lesson you will set up an email routine so your users can email each other reminders about their upcoming tasks. You will allow users to select one, many, or all tasks, and you will create a PDF report layout so you can send the task list as an email attachment.

Here is a sneak peak of what you will build:

Step 1 - Add fields to the Task table

First you will add fields to the Task table to help track which tasks should be included in the email.

  1. In the Manage Database dialog, navigate to the Fields tab for the Task table. Create a flag field to indicate whether the task should be included in the email:
    Flag_Send_Email, of Type: Number.
  2. Create a summary field to count how many tasks in the found set are selected. z_Flag_Send_Email_Count, of Type: Summary. This should be a Count of the Flag_Send_Email field, like this
  1. Create two fields to gather the email addresses of staff assigned to tasks:
    1. z_Staff_Email, of Type: Calculation. Enter the following formula, and set the result to Text:

      Task_Staff::Email

    2. zz_ListOf_Email, of Type: Summary. This should be a List of the z_Staff_Email field, like this:

Step 2 - Update the Upcoming Task List layout

Next, you will update the layout with a checkbox so users can select tasks to include in the email, and buttons they can use to trigger the email.

  1. Navigate to the Upcoming Task List layout and enter Layout mode. Add the Flag_Send_Email field to the layout by dragging it from the Fields tab onto the Body of the layout, next to the z_Name_Display field. You won’t need a label for the field, so delete the label if one gets created.
  2. In the Data tab of the Inspector panel, set the Control style to Checkbox Set.
  3. Show values from the list 1.
  1. On the Position tab of the Inspector, add the tooltip "Select to send email”.
  2. Resize the Flag_Send_Email field so all that appears is the checkbox.
  3. Add three buttons (titled Select All, Deselect All and Email Selected Tasks) in the footer (Insert > Button). You will attach scripts to the buttons later.

    On the Styles tab of the Inspector style the buttons as the following:

    1. “Select All”, styled btn White.
    2. “Deselect All”, styled btn White.
    3. “Email Selected Tasks”, styled Default.
  4. Your layout should look like this:

Step 3 - Create Upcoming Task List PDF layout

When you email a PDF of the task list, much of the information on the interactive layout will not be needed. Here you will make a simpler layout specific to printing.

  1. Using the Manage Layouts dialog (File > Manage > Layouts...), duplicate the Upcoming Task List layout using the Duplicate button, and double-click on the new layout and rename it "Upcoming Task List PDF" and click OK.
  2. Select the new layout in the Manage Layouts dialog and click Open. In Layout mode make the following changes in the Header part:
    1. Remove the filter field and Clear button.
    2. Remove the side navigation button on the top right corner of the Header part.
    3. Remove the Job label.
    4. Slide the remaining field labels higher in the Header part to remove the extra white space.
    5. Select the Header part label and in the Position tab of the Inspector set the Height of the part to 113 pt .
  3. To remove the Trailing Grand Summary part, select the Trailing Grand Summary part, then press the delete button to delete the entire layout part.
  4. Remove the Footer by selecting the Footer part, then press the delete button.
  5. In the Styles tab of the Inspector style the Job_name field as txt Minimal.Gray.Left. Style the Total: <<z_Count>> text object as label Right.
  6. Remove the transparent background button from the Body by clicking the white space behind the fields in the body part and clicking Delete. Also, remove the Flag_Send_Email checkbox field to the left of the z_Name_Display field. Make sure nothing is selected (you can do this by clicking in the gray area below the layout parts) and then edit the Width of the layout to 575 pt via the Postion tab of the Inspector.
  7. Reorganize and resize the fields and labels so all of the text is visible on the layout, as show below.

    NOTE: The z_Name_Display field and the Job_Name field will overlap eachother with the z_Name_Display field slightly higher so that the text of both fields display in Preview mode.
  1. In Browse mode, verify that you are looking at one or more records and sort the records using the z_Due_Group field. Enter Preview mode to check your work.

    The layout should look like this (assuming that you have tasks that are due between today and the next 14 days):

Step 4 - Create script to select and deselect current tasks

When a user emails a task list, they may want to pick and choose which tasks to send. This script either selects all found records or deselects all records (in case a record outside of the found set still is selected from a previous interaction). It is best suited to one user at a time, so you may want to consider another approach if you will have multiple users sending the reminder list at the same time.

This script uses what is often called a “utility window” to find flagged records and clear the flag. A utility window is a new window you open and then close off-screen, to accomplish a task without changing the user’s current found set of records.

  1. Open the Script Workspace (Scripts > Script Workspace…). Duplicate the Template script.
  2. Name the new script “Select/Deselect all Tasks (action)“. Any time you copy the template script, be sure to amend the comments at the top to fit your current script, and move the script to the "Upcoming Tasks" folder. 
  3. Add the following steps to your script:

    NOTE: See step 4 for details on the Replace Field Contents script step.

Set Variable [ $action ; Value: Get (ScriptParameter) ]
Commit Records/Requests [ With dialog: On ]

If [ $action = "select"]

# Check if all records in found set haven't been selected already
If [ Get ( FoundCount ) ≠ TASK::z_Flag_Send_Email_Count ]
   Replace Field Contents [With dialog: Off ; TASK::Flag_Send_Email ; 1 ]
End If

Else If [ $action = "deselect" ]

# Use a new window to check if there are any selected records (maintains found set in first window)
New Window [Style: Document ; Name: "Utility" ; Using layout: "dev_TASK" (TASK) ; Height: 1; Width: 1; Top: -5000 ; Left: -5000 ]

Set Error Capture [ On ]
Enter Find Mode [Pause: Off]
Set Field [ TASK::Flag_Send_Email ; 1]
Perform Find []

If [ Get (FoundCount) > 0 ]
   Replace Field Contents [With dialog: Off ; TASK::Flag_Send_Email ; "" ]
End If

   Close Window [ Current Window ]
End If

  1. For the first Replace Field Contents step in the script, select the gear icon to the right and select Specify target field, then select the TASK table and the Flag_Send_Email field.

    Click the icon again and next to Replace with click Specify. In the dialog, select Replace with calculated result and enter ”” (no space between).

    Exit the Script Workspace and save your script when prompted.

Step 5 - Update Find Upcoming Task script

There are many ways to handle flag selection, and ensure the user always knows which records are selected. For a simple way to avoid having records remain selected even if they aren’t visible, you will clear the selection any time the user changes the filter.

  1. In the Script Workspace, click the Find Upcoming Task (action) script to edit it.
  2. Add the following step to the beginning of the script, after the $action variable is set:

Perform Script [Specified: From list; “Select/Deselect all Tasks (action)“ ; Parameter: “deselect"]

Step 6 - Create script for sending upcoming tasks

Now that the pieces are in place, you can write a new script that will create an email and attach the PDF report of selected tasks.

  1. Open the Script Workspace. Duplicate the Template script.
  2. Name the new script “Send Upcoming Tasks“. Any time you copy the template script, be sure to amend the comments at the top to fit your current script, and move the script to an appropriate folder.
  3. Add the following steps to your script to find selected tasks and create the PDF, if at least one task is selected:

    NOTE: See Steps 4 - 7 for the Send Mail, Show Custom Dialog and Sort Records script step details.

Commit Records/Request [With dialog: Off]

If [ TASK::z_Flag_Send_Email_Count > 0]
   New Window [Style: Document ; Using layout: "Upcoming Task List PDF" (TASK) ]

   Set Error Capture [On]
   Enter Find Mode [Pause: Off]
   Set Field [ TASK::Flag_Send_Email ; 1 ]
   Constrain Found Set []

   Sort Records [ Restore ; With dialog: Off ]

   Set Variable [ $path ; Value: Get (TemporaryPath) & "Due_tasks.pdf" ]
   Set Variable [ $send_to ; Value: UniqueValues (TASK::zz_ListOf_Email) ]

   Save Records as PDF [ With dialog: Off ; "$path" ; Records being browsed ; Create directories: Off]
   Close Window [ Current Window ]
   Send Mail [ Send via E-Mail Client ; With dialog: On ]

Else
   Show Custom Dialog [ “Select at least one task.” ]
End If

  1. For the Send Mail script step, in the Options window, set it up as shown below. Note that you can customize the message however you like.
  1. For the Attach Files button to add the PDF attachment. Enter the variable created earlier in the script, which is the file location: $path.
  1. For the Show Custom Dialog script step, clear out the text for Button 2 so that the user can only select the Default Button with the text OK.
  2. For the Sort Records script step, select the gear icon to the right and select Specify sort order. Set up the Sort Records dialog as shown below.
  1. At this point, the “Send Upcoming Tasks“ script should look like this:
  1. Save and close the script.

Step 7 - Button set-up

Attach scripts to the buttons you placed on the Upcoming Task List layout.

  1. Navigate to the Upcoming Task List layout. In Layout mode, double-click the Select All button, and have it perform the Select/Deselect all Tasks (action) script. Set the Optional Script Parameter: to "select".
  2. Double-click the Deselect All button, and have it perform the Select/Deselect all Tasks (action) script. Set the Optional Script Parameter: to "deselect".
  3. Double-click the Email Selected Tasks button, and have it perform the Send Upcoming Tasks script.

Step 8 - Review your work

In Browse mode, test your new routine. You should be able to:

  1. Select as many tasks as you want.
  2. Deselect all tasks.
  3. Select all tasks.
  4. Send a PDF of the selected tasks via email.
  5. The recipient list of the email should consist of the staff members assigned to the selected tasks.