NetResults Tracker
Submit via Email


The ability to add records to Tracker via an email message is available as an additional option. This feature allows your end users or customers to send an email to a POP3 or IMAP email account. One email account is required for each combination of Project and Form where this feature is to be used. Optionally, if you wish to have the incoming email settings based on each option menu item within a pulldown, an email account will be required for each option menu item. Tracker's Email Processor reads and parses the information in the email message and uses the information to create a new record.

The subject and body of the email can be saved as fields within the record created. You can also configure Tracker to attach the original email message to the record created. Some of the options include setting the status of the new record, choosing whether to map the sender's email to set the "Reported By", and sending a reply to the unmapped emails. A complete list of options can be found when configuring the Incoming Email Settings options.

The requirements and steps for enabling this feature are described in the sections below.

Requirements for using Submit via Email

The following items are required for use of the Submit via Email feature:

Mail Server
A POP3 or IMAP Mail Server configured with at least one user account (see below) for use by Tracker is required. Most "Internet" email accounts are POP3 or IMAP server accounts.

User Accounts (Mailboxes)
A user account (mailbox) on a supported mail server is required for each combination of Project and Form that will use this feature. Optionally, if you wish to have incoming email settings set differently for each option menu item in a pulldown, one user account will be needed for each option menu item. If you are using multiple workgroups on the same Tracker installation, all projects where this feature will be used must have a unique user account even if the products are located in different workgroups. Warning: Tracker will delete emails that it reads from its mailbox. As such, if it is important that you keep a copy of all emails sent to a particular email address (e.g., you should not configure Tracker to read directly from the mailbox for that address. Instead, you should create an email account for Tracker that receives copies (for example, via a mailing list or forward option) of all emails sent to the mission critical email account. In general, it is a good idea to set up the Tracker mailboxes as "secondary" email accounts at least until you are certain you have the Submit via Email feature configured properly.

Mail Client
A mail client program which can send email to the Mail Server you are using and which uses (or can be configured to use) one of the supported character sets (us-ascii, iso-8859-1, windows-1252, or utf-8) is required for each user who sends email to Tracker. Typically the mail client program will use SMTP to communicate with the mail server, though your Mail Server may support additional protocols. Most mail programs which can send email over the Internet (e.g. Microsoft Outlook Express, Netscape Mail, Microsoft Outlook, etc.) or which can send email to a server which can send email over the Internet (e.g. newer versions of Microsoft Exchange, newer versions of IBM Lotus Notes, etc.) will meet the Mail Client requirement.

The following components are required to be installed on the Tracker server machine for use of the Submit via Email feature.

Operating System
Windows 2000 Server or Windows Server 2003 is required for use of the Submit via Email feature.

SOAP Interface
Microsoft SOAP Toolkit 3.0 must be installed on the machine where Tracker is installed. To download this component, browse to the Microsoft SOAP Toolkit 3.0 Download Page.

Microsoft WinHTTP 5.1 and Microsoft XML Core Services (MSXML) 4.0 are included when SOAP Toolkit 3.0 is installed.

Windows Installer
Windows Installer 2.0 or later is required to install SOAP. If you have Windows 2000 with Service Pack 3 or newer, you already have Windows Installer 2.0 installed. When installing SOAP, you will be prompted if you do not have the appropriate Windows Installer version. To download this component if needed, browse to the Microsoft Windows Installer 2.0 Download Page for Windows 2000.

Internet Explorer 5.0 or newer is required for installation of Microsoft SOAP Toolkit 3.0. To download the latest version of Internet Explorer, browse to the Microsoft Internet Explorer Download Page.

Enabling the Submit via Email feature

Perform the following steps to enable this feature:

Enter the Email license key into the License Manager
You must enter a license key into the License Manager in order to use this feature feature.

Install Required Components
Install the required components on the Tracker server as mentioned in the Server Requirements section above.

Enable the Submit via Email option in General Preferences
For each workgroup where this feature will be used

  1. Login to the workgroup as Admin
  2. Click on the Admin icon
  3. Click on the General Preferences button
  4. Set the "Enable Submit via Email" option to Yes
  5. Click OK to save this change

Enter the Outgoing Mail Server Settings
Configure the "Set Mail Server Configuration" section of the Mail Server used by this Tracker workgroup. If you are using other features that generate email notifications, a mail server may already be set up for your workgroup. The same mail server can be used for all features that generate email notifications.

Configure the Global Incoming Mail Options
Make selections for the options related to handling the incoming messages in the Incoming Mail section of the Email Configuration page.

Configure the Incoming Email Settings for each Project
Make selections for the options related to handling the incoming messages for each project in the Incoming Email Settings section of the Manage Projects page.

Create a Scheduled Task for the Submit via Email Feature
Set up the Email Processor in the Scheduled Tasks section of the Control Panel on the machine where Tracker is installed using the steps below.

  1. Go to Start > Settings > Control Panel on the machine where Tracker is installed
  2. Double click on Scheduled Tasks
  3. Double click on "Add Scheduled Task", then click Next
  4. Click on the Browse button, then navigate to the location you selected to for the Tracker files during the installation. By default, this location is C:\Program Files\NetResults\Tracker
  5. Select the file called PTEmails.jse, then click on the Open button
  6. Enter a name for the scheduled task such as "Tracker Submit via Email", then for the option "Perform this task:" select the radio button next to "Daily". Click Next to proceed.

  7. The current time will be displayed as "Start Time". For the "Perform this task:" option, select "Every Day". The current date will be displayed as "Start Date". Click Next to continue.

  8. Enter the User ID of an Administrator user (it is recommended that you use the local Administrator user). Enter and confirm the password of this user. Click Next.
  9. The values you entered will be displayed. Check the box next to the option "Open advanced properties for this task when I click Finish", then click on the Finish button.

  10. The Advanced properties will be displayed. Click on the Task tab. In the "Run" field, enter the following:

    CScript.exe "<PTEmails.jse file path>" //B //H:CScript

    where <PTEmails.jse file path> is the path where the PTEmails.jse file resides. As mentioned above, by default, this path is C:\Program Files\NetResults\Tracker. Using the default path as an example, the Run field should have the following entered:

    CScript.exe "C:\Program Files\NetResults\Tracker\PTEmails.jse" //B //H:CScript

    Please note that the PTEmails.jse file path should be enclosed with double quotes.

  11. Click on the Schedule tab, then click on the Advanced button.

  12. Check the box next to "Repeat task", then for "Every" select a length of time. We recommend using a minimum of "10 minutes". This time dictates how frequently you wish to run the Email Processor to check for new emails. You can specify any repeat time you wish, but make sure that it is more than 10 minutes. For "Until" select the radio button next to "Duration". Enter "24 hours" for the "Duration". Click OK.

  13. Click on the Settings tab. Check the box for the option "Stop the task if it runs for:", then enter "0" for hours and "30" for minutes. Click Apply, then click OK to save these changes and dismiss the Properties for the Scheduled Task.

Submitting a Record via Email

After enabling this feature using the steps above, to add a record via email, send an email to the mail account specified in the Incoming Email Settings that corresponds to the project for which you want to add a new record.

Email Notification for Unregistered Users

Email notification messages can be sent to unregistered users reporting issues using the Submit via Email feature. Designate a Text type field to be the collect the reporter's email address when records are submitted via email using the Unregistered User Email attribute in the Managing Fields section.

You can set preferences for the Date and Time information, email content and actions that send an email notification to unregistered users by configuring the Unregistered User Options in the General Preferences section.

Required Fields on Add Page

The Submit via Email feature bypasses the "Required For Add" attribute for all field types. This is especially useful with respect to the Product field as it allows you add records via email for the default option menu item in the Product field while still requiring that a non-default value be selected on the Add page within Tracker.

Record Visibility for Records Submitted via Email

When Record Visibility is enabled in a workgroup, the visibility of each record added via email will be set based on the whether the email message is mapped or unmapped. The only exception is that all records are made visible to the Admins user group regardless of whether the email was mapped or unmapped.

When the option Set Reporter by Mapping "From" Address in the Incoming Email Settings is set to "Yes", this indicates that Tracker should attempt to match the From email address of the incoming message to the email address listed in the profile information for any user account. If the From email address in the incoming message matches an email address for a user in the workgroup, this user will be set as the Reporter of the record created by the incoming message. This is a Mapped email.

The new record resulting from a mapped email will be set such that it is visible to the user groups in which the Reporter is a member as well as the Admins user group.

When the option Set Reporter by Mapping "From" Address in the Incoming Mail Configuration is set to "No", Tracker will not attempt to map the From email address to a user in the workgroup. This is an Unmapped email. Or, if the Set Reporter by Mapping 'From' Address is set to "Yes" and a match is not found, this is also an Unmapped email.

The new record resulting from an unmapped email will be set such that it is visible to the user groups selected for the option Visibility for Records Submitted by Unregistered Users via Email in the Record Visibility section as well as the Admins user group.

Error Handling

Incoming messages with invalid formats (e.g. characters from an unsupported character set, incorrect multipart content, etc.) will be processed such that the field where the body of the incoming message is stored will note "Invalid Email Format. See Attachments." A copy of the raw email will be saved as an attachment called "rawemail.txt" in the record created for this incoming message. The raw email will be saved as an attachment irrespective of how the Save Raw Email as Attachment option is set.

If there are any control characters that are not supported by XML present, these will be converted into "blank" characters.