1

E-Mail Processing Guide

1 Overview

The Email option of SupportDesk has two key areas:

The automatic sending of emails at different points and actions along the lifecycle of a Call

The creation of Calls from emails read from one or more mailboxes.

The E-Mail Option can be used in conjunction with MAPI-enabled email clients such as Outlook or you can connect to an email server to send and receive messages. The mail server must be either POP or IMAP enabled. If you have the E-Mail option as part of your SupportDesk package, it will automatically be included in your installation when you set up SupportDesk.

To enable the E-Mail feature, the SupportDesk Logins must have the E-Mail Enabled box ticked at the Login Details form on the Options tab. If the person is to be allowed to send attachments, make sure the Attachments tick box is also selected:

You must use Mail> Setup & Templates… in the Windows user interface, or Settings > E-Mail Setup in the Web interface, to configure the settings.

You can also use the Setup & Templates… form to create templates for mail in various situations, either on an automatic or ad hoc basis. Some examples are in place to assist you. You can disable messages and request that a message be paused before sending.

2

2 The Setup & Templates Form

You must use Mail | Setup & Templates… to declare the servers to be used for sending and receiving mails.

The Windows client can use either MAPI settings or SMTP/POP3 settings. (Use the tick box at the bottom of the E-Mail Configuration form to select MAPI. This setting is applied to all windows client users. In some systems, this will already be ticked for you.)

The WebServer can only send mail directly via the specified SMTP server; it cannot send via a MAPI interface. SMTP/POP3 are the recommended options for email integration.

Figure 1: Email Configuration

1. MAPI In the MAPI Settings, you need to supply the Outlook Profile name (otherwise, the Outlook default will be used). Mail will be sent from the mailbox associated with this Profile. The inbox associated with this Profile will be used when scanning for incoming mail to be converted into a Call. Use the Programs tab on the Properties of Microsoft Internet Explorer to specify the e-mail client in operation. If you supply an Outlook profile, the Windows client will use this in preference to any POP3/SMTP settings if the Enable MAPI on Windows Clients box is ticked.

Tick box to use MAPI in the windows client.

Enable matching of domain on mail read.

MAPI Interface Profile

POP3 settings for receiving mail

SMTP Server to send mail. If authenticated SMTP, account and password can also be entered.

This message will go at the end of all your outgoing emails.

Tick to receive automatic mails that would be sent to you as a result of your own actions.

To select the Folder to which the mail templates refer.

Send a copy email of all outgoing emails to the manager of the Login recipient.

3

2. SMTP/POP3 To send mail, you must specify the SMTP Server Name. Please check with your IT Manager if the SMTP server is authenticated and needs a password. The WebServer can only send mails using SMTP; a separate SMTP server may be specified for the WebServer interface. To set this, logon to the Web UI with supervisor rights and go to Settings, WebServer, where you will see the option:

Figure 2: WebServer SMTP Settings Enter the SMTP details that the WebServer is going to use. You are not required to enter an SMTP server here, you only need to complete these details if the WebServer is going to use a different SMTP server to the Windows client. If the WebServer is going to use the same SMTP server as the Windows client, leave these fields blank. The shared SMTP server details can be entered via the Windows client, as in Figure 1 above. To receive mail, you need to specify the POP3/IMAP Server Name and Account Name (and any associated Password) in the SupportDesk windows client software.

3 Receiving Mail

3. Which Mail Box is used?

➢ If you are using a MAPI interface, the in-box associated with the Profile on the Setup & Templates dialog is the one used for receiving mail. If the Profile is left blank, SupportDesk will use the in-box of the Outlook default Profile.

➢ If you are reading mail directly from a POP3 or IMAP server, you must provide the correct POP3 server name.

➢ There is also the functionality to specify a specific POP3/IMAP mailbox per Folder.

Figure 3: POP3/IMAP Settings In this case, the POP3/IMAP account settings are maintained on the Folder Management - System Management menu, Folder, Open (Windows client). This would be the preferred place for entering POP3/IMAP server and mailbox credentials. When the mail read process is running, each account specified will be visited.

4

SupportDesk will also write a simple text file into the installation directory each time it checks for emails. This file is called mailread.txt and can be useful in diagnosing issues.

4. Which Mails are converted to Calls?

➢ Mail with subjects that match the subjects on the E-Mail Forms in Mail – Setup & Templates will be converted to Calls.

➢ If there is an E-Mail Form with a blank subject, all incoming messages will be treated as a new Call (with an exception as described in the next point).

➢ Mail with a recognised subject (or the text SupportDesk) that contains a forward slash (/) will be treated as an addition (i.e. a new Note to an existing Call.) The Call Reference in the email subject must immediately follow the forward slash for the Mail to be added as a Note. You can change this delimiter in the suppdesk.ini file located on the PC where the mail is being read in; amend the entry "RefSeparator=/" to be what is required.

➢ You can specify a mail form with the subject IGNORE **** and have all mails with that subject ignored by the mail read process; where **** is present in the email subject. You might use this to IGNORE undeliverable messages.

➢ The IGNORE must be in upper case and SupportDesk will apply a case sensitive search to the text after the IGNORE, so:- IGNORE Undeliverable will match to, and skip mail with the subject “Your mail is Undeliverable” but not match, and let through mail with the subject “Your mail is undeliverable “

➢ The text after the IGNORE may be more than one word but will be treated as a single string for the search, so:- IGNORE Out of office will match to, and skip mail with the subject “Sorry I am Out of office for the next week” but will let through mails with the subject “Sorry I am Out of the office for the next week”. (N.B. ‘The’ is highlighted here in order to show the difference in subject.

➢ To cater for these slight variations SupportDesk allows the creation and addition of multiple IGNORE forms.

5. How do I log the new Call into the correct Folder

Start your incoming message with the phrase

➢ Folder=Folder Name or you can use

➢ Folder: Folder Name

And the e-mail will be loaded as a new Call in the designated Folder.

6. Should I use Mail - Read, or Mail - Read Background, or Mail – Read Selected?

➢ You should choose one method or the other; SupportDesk will not like the two used in conjunction. Mail | Read will read the in-box or server mailbox when you request the read. The Call screen is presented for you to check the details and you can opt to delete the originating e-mail message.

➢ Mail | Read Background will check for new mail at regular intervals. The interval, in seconds, is determined by the entry "Synchronise=" in the suppdesk.ini file. The Calls will be created and the originating e-mail message deleted automatically. If you perform any other operations while Mail | Read Background is in use then the process will stop. You can set the Mail | Read Background

5

task as a service. There is more information about adding Mail - Read Background as a service at the end of this document.

➢ Mail | Read Selected. SupportDesk allows viewing and selected mail read whilst viewing emails in the Mailroom (accessible via the Explorer in the Windows client). On selecting the mails to read, SupportDesk executes a normal mail read and generates a new Call. If the email is identified as a possible note to an existing call, you will be asked to choose between adding the mail as a note or as a new Call. Selective Mail Read is described in more detail in a separate section later in this document.

7. If I have a PC dedicated to reading mail, will it use up one of my SupportDesk logins?

If you create a login with supervisor rights and tick the box on the options tab (“Server E-mail login”) this doesn't take up one of your user licenses. You can also set the Mail | Read Background task as a service (see later sections of this document).

8. How does SupportDesk reconcile who has sent the e-mail?

The e-mail will be received with a 'from' address. SupportDesk will try to match this address with the e-mail addresses on Contact and Customer records. If a record is found, the Customer, and possibly the Contact, details will be populated in the Call. If no direct match can be made and if the option ‘Match on customers Domain’ is ticked, SupportDesk will look for the first Customer/Contact that has a matching email domain and assign the Call based on this information. This feature can be useful when SupportDesk is being used to support external customers and ‘unknown’ contacts from one of the customers may send in emails. If the address cannot be reconciled, it will be saved in a Note. If the Customer/Contact information is sent in the body of the message, prefixed by the expected prompts, they will be inserted into the relevant Call fields. If you are reading internal e-mails, using X400 protocol on Exchange, SupportDesk will search e-mail fields for a match on the Common Name (cn=). That is, the e-mail address of an internal Contact should contain the Common Name of the sender.

9. Can I force data from the email into set fields in SupportDesk.?

You can only do this if the inbound mail has some content of fixed format that obeys preset rules. An example would be if you had an automatic mail from a machine that was sent as a warning and the mail could be pre-formatted. If the mail contained a line that read Machine: Server A You could rename a call field in the Data Dictionary to match the literal in the mail – so Call:Text1 could be set with a prompt of “Machine”. On the Mail Form you could identify this field using the syntax <Prompt:Call:Text1>: Which SupportDesk would resolve to “Machine” and would then parse the mail for that string (Machine) and update the field value after the colon into Call:Text1 An alternative way to achieve the same result is for the Mail Form to contain the line Machine:<Field:Call:Text1> which may be useful if the mail contains long literals that cannot be directly matched to field names.

6

4 Selective Mail Read

Current E-mail read functionality within SupportDesk allows either a manual read of mail from a designated mailbox or a background read. Both functions attempt to read emails in accordance with the templates that have been set in the E-Mail forms. The manual mail read gives the user the option to reject the mail before it is translated into a Call.

Selective Mail Read extends this functionality and allows the viewing of the designated ‘inbox’, whether IMAP, MAPI or POP3:

Figures 4 & 5: Email Actions

Use the View Mailbox option to view the contents of the mailbox associated with this SupportDesk client. It has to be remembered that when using MAPI, most SupportDesk clients will not make use of the mail read – this functionality will be customised on one designated client that has a profile associated to the mailbox used for Support mails. If a POP/IMAP mailbox is being used for incoming Support mails, all SupportDesk clients can be associated with the same mailbox.

On selecting the View Mailbox option, SupportDesk will read the appropriate inbox and then display the contents:

Figure 6: Email Message List

Some of the mail items are already highlighted. This is determined by the subject containing a match with one of the Mail Form templates that exist, or there being a mail reference delimiter — default ‘/’ in the mail subject.

You can individually select or deselect messages or use CTRL + click to select multiple messages that are to be read by SupportDesk.

Mail menu - Read Selected. When you select this option, SupportDesk reads the selected mails and displays the Call form. This shows the details created automatically and allows extra maintenance of the Call in the same way as for any mail read.

7

Figure 7: Call Form

After each mail has been read, you can choose to delete it from the inbox.

5 Sending Mail

10. How do you use Templates?

➢ Mail can be sent for various circumstances. The situations are identified on the tabs of the Setup & Templates form. For each situation, you can select a Template style to use and so be consistent with the contents of the mail for different circumstances. In the web Interface the maintenance is controlled under the menu – Settings – E-Mail Setup. The templates are grouped into several areas: Automatic Call – shows key trigger points in the lifecycle of a call with options as to who can get the mail. Specific – mails that are enabled to complement other functions such as scheduled quick reports or mailed knowledge base items. Escalation-a list of mails that are associated with actions of the Escalator/Workflow engine, such as mail to assignee on breach of warning date. Activity – mails related to the use of Activities. E-Mail Forms – used in conjunction with the Mail Read function. Campaign management-mails used with marketing campaigns. User Defined- Mails that have been created with category codes during the configuration of the system.

➢ Use the Folder selection to have different mail styles for different Folders.

➢ To amend a template or select a template style for a situation, double click the entry. Select a template from the pull down list.

➢ Select <New> to create a new template; a reference number will be allocated.

➢ If creating templates for alternative folders to the default we advise to always create <New> templates.

➢ If you amend the layout of a template, the style will be used for all situations where the template has been selected.

8

➢ To prevent the sending of a mail in a certain circumstance, select <Disabled> from the pull down list of templates. <Disabled> will appear in the template column.

➢ Variable fields are entered in angled brackets, when using plain text. Use the Data Dictionary to ascertain the record and field names. The variables are entered in the format <Record:Field>; for example, <Call:Subject>. If you want to precede the variable value with the prompt for this field in the Data Dictionary, use <Prompt:Call:Subject>. So, if the Subject field on the Call record has been customised and given the prompt of ‘Problem’, using <Prompt:Call:Subject> will substitute the text Problem.

These are some variable fields worth noting: — <Notes:Details> - includes the text for a particular Call note — <Call:NotesText> - includes the textual part of all the notes — <Call:Notes> - includes all the detail for all the Call notes — <Call:External Notes> - includes all the detail for all the Call notes marked as external — <Call:Assignee Name> - includes the Assignee’s Name — <Login:Name> - includes the Login’s User Name — <Login:Tag> - includes the Login’s Tag — <Call:Attachments> - add the Call attachments to the mail — <Activity:Attachments> - Attachments on Activities will be automatically included in activity emails.

➢ When using HTML formatting (SMTP only) the variable fields are entered in square brackets and spaces in field names are replaced by underscore (_).

➢ When you create an e-mail that uses a particular template, the variables from the current database record will be substituted into the message. If you select Pause for the template, you can review the message before it is sent.

➢ You can include your own fixed text in the template.

11. Who does the mail go from?

➢ Using SMTP, the email option takes the e-mail address from one of these fields in this order… 1. ‘SMTP From’ Address in email template 2. Mail | Setup & Templates - Email Address or Login Name (if e-mail address is blank) 3. Company Configuration E-Mail address

➢ Mail sent using the MAPI interface will have the From address associated with this profile.

12. I have some special Customers that I don't want to send automatic e-mails to. What can I do?

➢ There is a tick box on the Customer form, 'No Automatic E-Mails'. Tick this box and this customer will be excluded from the automatic mailing.

13. I would like to add a secondary email address onto a Customer Record.

➢ The field ‘E-mail2’ on the Customer record if specified will also receive mails sent to the primary address of the customer.

17a. Can I associate a Specific Email template with an Individual Customer?

➢ It is possible to associate a Customer with their own specific email template in SupportDesk. A new template can be created or existing template selected via the Customer record in SupportDesk.

9

17b. In addition the ‘E-Template2’ if set on the User Record (see screen shot above) will be used by the ‘New call note to owner’ Email scenario.

18. Can I automate a CSV attachment to be included on my Automatic Emails?

➢ Yes, an e-mail template can be flagged to have a CSV attachment. This CSV attachment can consist

of fields from the call that the mail is pertaining to and can be configured from a new "CSV

Attachment Fields" option on the Mail Setup and Templates screen. See below…

Following this SupportDesk will prompt you to select which call fields you wish to include on the CSV

attachment…

10

Once you have done this, check the ‘CSV Attachment’ check box on the particular Email template

you wish to include your attachment on.

➢ This feature can be used to update third parties with information about a call. If the same CSV file is

read in on a reply mail then SupportDesk can be configured to automatically update the call based

on the contents of the CSV file.

Common Errors/Queries The Mail menu is greyed out Check the Login’s details – is e-mail enabled on the Options tab?

Check the properties of the SupportDesk short cut icon – are the settings the same as other users?

Attachments are not being sent with emails

Make sure somewhere in the body of the email template there is the line <Call:Attachments>. This will attach the attachments associated with the Call to the mail

Mail not being sent by SupportDesk Clients

As a simple diagnostic, test the client using Outlook Express - configured with the same parameters as SupportDesk. If this cannot send mail then the problem is most likely down to architecture or security settings, not SupportDesk.

SMTP sending email failed unable to relay for ... Reported by hhsmtp32.dll error 161

The error is an SMTP server configuration issue. It's saying that the SMTP server that's configured in SupportDesk is denying access for sending to the designated address. The SMTP server needs setting up to allow relaying of email for this user (or his IP address, or subnet).You'll need to configure the email (SMTP) server to allow relaying (sending onward of external email) for all of the client machines, or open it up to a range.

11

SMTP Email Failing Error Number 10053

Both McAfee VirusScan 8 and Norton Antivirus 2004 have been found to give these errors sometimes, but other virus scanners or versions may also cause these errors. Firewalls and Internet Security applications must be configured to allow SupportDesk to send SMTP email over TCP/IP port 25. What we have found in the past is that anti-virus software blocks certain applications from sending email. They usually have an exclusion list, to which the SupportDesk binaries need adding, rather than simply opening a port.

Customer wants to use a different port for sending mail using SMTP

All you need to do is in the "SMTP Server" box, place the port number after the server name, separated by a colon. Like this: servername:123

Where does the SMTP email option look to determine what to put in the FROM address.

The order is as follows:

1) 'SMTP From' Address in email template (takes precedence)

2) Mail -> Setup & Templates - Email Address

3) Mail -> Setup & Templates - Login Name (if above is blank)

SMTP authentication on the SMTP Server

If your SMTP server is set to operate with SMTP authentication mail will not be sent by logins that do not have the appropriate authentication information in the database. This may throw up Relay errors which can be misleading. There are two fields towards the end of the User table (SUPUSERS) which are intended to hold SMTP authentication information. There is also code to actually use the data in these fields in SupportDesk. However, there isn't an interface to the fields through the SupportDesk screens as yet! The two fields are called: szsmtpaccount szsmtppassword You need to use SQL Enterprise Manager to add the necessary data in SUPUSERS. i.e. 'Return All Rows' on the SUPUSERS table in Enterprise Manager, locate your user record, move along this row until you find the two fields mentioned above. Enter the necessary details, save and close. You will need to put the information in every record at some time

SMTP 550 5.7.1 errors Have a look at Microsoft Knowledge Base article 895853, How to troubleshoot mail relay issues in Exchange Server 2003 and in Exchange 2000 Server.

Email sent via SMTP on Windows or Web is very slow. Windows version shows a dialog while waiting for the SMTP server. Send succeeds eventually.

If Exchange/Microsoft SMTP server. Check that SMTP server isn't configured to do maximum logging in the ExchangeIMC (Internet Mail Connector) Service (via Exchange Administrator) as this can cause the SMTP server to do a reverse DNS lookup for every connection request. This can slow connection requests down. Try sending via Outlook Express to measure send speed independent of SupportDesk. 'Telnet servername 25' - should respond immediately with an SMTP welcome string. http://support.microsoft.com/kb/286375

Mails from the WebServer are not getting sent

Check:

1) Have you got copies of ipworks*.dll and hhsmtp32.dll in your SupportDesk WebServer installation directory?

2) Is Mail=1 set in the [WebServer] section of the WebServer's suppdesk.ini file (in the WebServer's installation directory)?

3) Check the SMTP server setting in Mail Setup.

12

4) If you change any of the above, you may need to recycle your WebServer Application Pool in order to activate the changes.

5) Can you actually see the SMTP server from the WebServer machine (e.g., can you ping to the SMTP server from WebServer machine)?

MAPI 3 No default sign in This error message indicates that SupportDesk hasn't been told which profile to look at in order to use a mail client.

Go to Mail | Setup & Templates and ensure that the Profile Name in MAPI settings is correct.

To find your profile, right click on your Outlook icon and check the Profile Name on the properties icon.

MAPI 25 Invalid Recipients You can get this error when SupportDesk is trying to resolve the login name (or contact name) with the names in Outlook contacts. You may get this message if the customer/contact is marked as internal.

MAPI 26: Not Supported Use POP3/SMTP rather than the MAPI interface

“A program is trying to automatically send an email on your behalf. Do you want it to allow this?"

This is a message from Outlook and not SupportDesk. Unfortunately, Microsoft has not provided the functionality to switch this security feature off.

There is a third party solution: Express Click Yes is a small program that sits in the taskbar and clicks the Yes button for you when Outlook's Security Guard opens prompt form saying that a program is trying to send an email with Outlook or access its address book. You can suspend and resume it by double-clicking its taskbar icon. Developers can automate its behavior by sending special messages.

We do not support Express click-yes but have been using it with no problems.

http://www.express-soft.com/mailmate/clickyes.html

Mail read stops The security settings on some systems required all access to the mail system by other programs to be authorised and a dialog box is shown prompting for this. If using the utility ClickYes to automatically do this then ensure that this has not stopped and access to mail is being denied. Simply stop the background read and start a manual main read. If this works then it may be ClickYes has stopped.

One machine cannot use e-mail, but all others are OK.

On the rogue machine check the following:-

1. On the SupportDesk icon properties, ensure that the Start In directory matches the settings on a machine with no problems.

2. While out of SupportDesk, open the suppdesk.ini file (found in the Windows directory) and ensure that the setting under [DLL32] is EMail=HhsMap32.dll. Change and save suppdesk.ini if necessary.

6 Installing Email Monitoring as a Service

Email as a service should only be added on one machine, usually the SupportDesk installation Server. Depending on whether you are reading using MAPI or POP3, the setup required is different and usually much simpler if POP3.

Prerequisites if reading from POP/IMAP

13

If reading from a POP3/IMAP-enabled mailbox, there are no specific requirements beyond the setup details already discussed in this document.

Prerequisites if reading from MAPI mailbox

The machine on which the mail read is to be used must have a copy of Outlook.

The machine must have a local account called email that should be used to run the service.

This email account must have a default mail profile that is linked to the mail box to be read.

If the Outlook E-mail guard is activated on your version of Outlook, a third party tool needs to be installed to prevent the Outlook pop-ups from appearing. House on the Hill can assist with this.

Adding Support Desk as a Service

On the machine on which the Email service is to be run:

Close SupportDesk.

In the appropriate suppdesk*.ini file used by the Email Read process, add or modify the following entries, which are the SupportDesk login and password that the service should login as.

[SuppDesk] Login=<supportdesk_login> Password=<supportdesk_password>

Alternatively – login into SupportDesk with the email login and click on the menu option File – Automatic Logon. This will write the login details to the Suppdesk.ini file.

Restart SupportDesk. It should now automatically login rather than showing the login form. This is required for the service to operate correctly.

Make sure that SupportDesk Email - Read Background is working as expected before installing it as a service.

Make sure that the file nssm.exe is located in the same Folder as the Windows SupportDesk executable (supdskcs.exe), normally \suppdesk.

In SupportDesk, press Ctrl-Alt-Q and tick the 'Run as a service' box. When you press the OK button, the service component will be installed. If this does not happen you may have to run SupportDesk “As Administrator” to give yourself rights to add a service.

Ensure that the Mail/Read Background menu is still ticked and then close SupportDesk.

In the Services window (Control Panel, Administrative Tools, Services), right click the SupportDesk Email Monitor entry and choose Properties.

In the Log On tab, choose the account that you want the service to run as. By default, this is the local system account if reading a POP3 account. Alternatively, if Windows Authentication is enabled, you’ll need to enter the local or domain user credentials for the Email Read login here. If reading from MAPI, specify the email account that should have been created on this machine.

You may want to tick the ‘Allow service to interact with the desktop’ box during initial testing. This will cause the SupportDesk service window to appear on the desktop when the service is started.

You can now start the service.

If you encounter any problems, stop the service and add or modify the following lines in the appropriate supdesk*.ini file.

[Database] Trace=2

14

This will cause a suppdesk*.trc file to be generated in the SupportDesk Temp directory at run time, which will contain diagnostic information and any error messages.

Checking that mail read is running.

On the machine on which the Email service is running the application will create a simple text file called mailread.txt after each mail read cycle (every 1 minute). This will contain confirmation of connection and a summary of the last mail read cycle. This file should be the first check if it appears mail read has stopped.

Keeping mail read running. Experience has shown that external factors on a system such as Database backups, network glitches or can impact the mail read and halt the function. For this reason we always advise the addition on a windows scheduled task that runs a command file which stops and restarts the mail read service. The command file should contain the lines :-

net stop "SupportDesk Email Monitor"

net start "SupportDesk Email Monitor"

and to improve the chances of continued service we recommend that this be scheduled to run every 4 hours.