Mail Processor 4.4. Installation and Configuration Guide. Date: June Page 1 of 37

Transcription

1 Mail Processor 4.4 Installation and Configuration Guide Date: June 2014 Page 1 of 37

2 All rights reserved. No part of this document may be reproduced or transmitted in any form or by any means, or stored in any retrieval system of any nature without the prior written permission of Sunrise Software Limited, except for permitted fair dealing under the Copyright, Designs and Patents Act Sunrise Software Limited, Sostenuto is a registered trade mark of Sunrise Software Limited. Sunrise Software Limited does not assume or accept any liability for any loss or damage of any kind to any person that may arise as a result of that person (or any other person) using this document or acting or refraining from action in reliance on any information (including expressions of opinion) contained in this document. This limitation/exclusion of liability does not apply in the case of death or personal injury caused by negligence on the part of Sunrise Software Limited, or to the extent (if any) that a limitations and/or exclusion in these terms is not permitted under applicable law. Sunrise 50 Barwell Business Park Leatherhead Road Chessington Surrey KT9 2NY United Kingdom Visit us at Enquiries e: welcome@sunrisesoftware.com t: +44(0) Page 2 of 37

3 C O N T E N T S Introduction 4 What is the Mail Processor? 4 Installation 5 Prerequisites 5 Limitations and Caveats 5 Upgrading to JDK Update 51 5 Installing Mail Processor Update the setenv.bat File 8 Amend the interfaces.properties File 8 Update the Sostenuto Database for the MP 9 Configuring Multiple Instances of the MP 9 MP 4.4 Icons and Shortcuts 10 Uninstalling Mail Processor Summary of MP Functionality 12 Data flow through MP 12 Mailboxes 12 Types of handled 12 Services and Operations 12 Security settings 13 Creating Associations 13 Responses 13 Attachments 13 Configuration 14 Windows Authentication at Runtime 14 Starting the Configurator 14 Connecting to your Sostenuto Database 15 Configurator Screen Layout 16 Configure a Mailbox 17 The Mailbox Screens 17 POP3 Mailbox Screen 19 IMAP Mailbox Screen 20 Configure Additional Options 21 Enabling a Mailbox 23 Disabling a Mailbox 23 Deleting a Mailbox 24 Configure an Operation 25 General Properties 25 Configure Operation to Perform 26 Sender Address Lookup Options 26 Information Capture and Storage 27 Configure Default Values 28 Notification Configuration 29 Managing Operations for Mailboxes 31 Configure a Notification 32 Handling Automated Message Formats 33 The File Menu 35 Hints and tips for Microsoft Exchange and IMAP/POP3 36 Enabling IMAP/POP3 connectivity 36 Considerations 36 Firewall Blocking 36 Secure Communication with SSL and TLS 36 Resources 37 Default IMAP and POP3 Port Numbers 37 SSL Configuration 37 SSL and TLS Configuration 37 Page 3 of 37

4 Introduction This document details the installation, configuration and use of the Mail Processor. The document is aimed at the Sunrise Administrator or installation consultant. What is the Mail Processor? The Mail Processor (MP) allows users to view and update information held within Sunrise via . The MP 4.4 is an optional component of Sunrise that communicates with Sunrise via the REST API. This version of the MP is not a direct upgrade from MP 3.5, but a new product with many enhancements requested of previous versions. As MP 3.5 and MP 4.4 are different applications with different code bases, they can be run in parallel. Page 4 of 37

5 Installation MP 4.4 acts as a service that sends messages to the Sostenuto REST API; it does not have to be installed on the same server as Sunrise, but must have access to the Sostenuto REST URL. MP 4.4 installs independently from MP 3.5 and the installer does not attempt to upgrade an existing MP 3.5 installation. Note: Do not use the installation instructions in this document to upgrade to MP 4.4. Instead, follow the upgrade instructions in the Mail Processor 4.4 Release Notes. Prerequisites Please ensure that the following software is installed and available for use before you install MP 4.4: Sostenuto and above. The MP 4.4 uses the REST API to pass information from connected mail boxes into Sunrise. Note: The application server will send a 404 error message if you try to configure when REST is not installed. The correct version of Java for your Sostenuto installation is Update 51. Finally, ensure that you back up the Sostenuto database before running the MP 4.4 Installer. Limitations and Caveats The Sunrise HTML5 interface only processes records from registered users. If you are running the MP with Sostenuto 4.5 or later releases, please ensure that the Sostenuto Account used for logging into the MP is registered as a user in the Sunrise HTML5 Interface and has logged into it at least once. This will ensure that, when the MP processes an with an attachment, the Sunrise HTML5 interface can open the new Incident record. The following REST API issues were fixed in Sostenuto 4.1.4: PRB002439: REST API fails to add record if message body is too long. PRB002461: REST API cannot add attachments with apostrophes in their filenames. They are supported in Sostenuto 4.6 and above, but not in Sostenuto 4.5. Upgrading to JDK Update 51 If your installation uses an earlier Java version than JDK Update 51, you must upgrade your Java version before installing Mail Processor. Open the Installation > Java folder in the Mail Processor 4.4 download. 1 In the Java folder, locate the appropriate JDK for your server: For a 32-bit server, this is x86 > jdk[update number]-windows-i586.exe. For a 64-bit server, this is x64 > jdk[update number]-windows-x64.exe. 2 Double-click on this executable to begin the installation. If a User Account Control screen is displayed, click Yes to proceed, then follow the instructions to upgrade the JDK. The configuration changes will take effect when you restart your machine. Page 5 of 37

6 Installing Mail Processor 4.4 Follow these steps to install MP. 3 From the Mail Processor installation media, locate the Install folder and run setup.exe. The following Welcome screen will be presented: Press Next. 4 The License Agreement screen is displayed: Click I accept the terms of the license agreement and click Next. Page 6 of 37

7 5 The Destination Location screen is displayed. This screen allows you to determine where the MP files will be installed. The examples used in this guide are for a 32-bit processor. The recommended location is: [root directory]\program Files (x86)\sostenuto Mail Processor for a 32-bit processor. If you install on a 64-bit processor, the recommended location will be [root directory]\program Files\Sostenuto Mail Processor. To change the default location, click Change and browse for the preferred location. When you have selected an installation location press Next. 6 The Ready to Install the Program screen is displayed. Click Install to continue with the installation. Page 7 of 37

8 1. 7 A progress screen is displayed while the MP is installed. When it has completed, the InstallShield Wizard Completed screen is displayed: Click Finish. The Mail Processor is now installed on your machine. Update the setenv.bat File Open to the setenv.bat file and update the JDK version to Update 51. The example below shows the pathway for a 32-bit Java installation: Save the file. Amend the interfaces.properties File During operation MP adds message text from incoming s into specified Sostenuto fields. You must define End of Message (EoM) markers in the interfaces.properties file so that the MP can identify the end of the message text when it reaches an EoM marker and stop adding message text to the Sostenuto field. To define the EoM markers: 1 Open the interfaces.properties file, in the C:\Program Files (x86)\sostenuto Mail Processor\config folder. 2 Go to the last paragraph of the interfaces.properties file, shown below, to specify a comma-separated list of end-of-message (EoM) markers. You should specify every expected marker. Figure1: The interfaces.properties file gives examples of EoM markers 3 Specify the text strings to be used as EoM markers, such as ***** or a phrase, to mark the point where the Mail Processor stops reading the contents of the for processing. 4 Save the file. Page 8 of 37

9 Update the Sostenuto Database for the MP 1 The MP stores the configuration of mailboxes and operations within the Sostenuto database. Execute the following SQL script against the Sostenuto database that stores the files: <Mail Processor installation root>\sql-scripts\smp-install.sql Once connected you will be able to launch the MP. 2 To launch the MP, use either the Launch Mail Processor 4.4 shortcut on the desktop, or the shortcut from the program menu under the folder Sunrise Software Ltd. Configuring Multiple Instances of the MP If you have multiple instances of Sostenuto in the same environment, each one may need its own MP. Only follow the procedure below if you are installing multiple instances of the MP in your environment. To create an additional instance of the MP you must copy the installed instance and give the copy a unique name and its own port number, then create a Windows Service for it and link the two together. The procedure is explained below. 1 After installing Mail Processor 4.4, create a copy of the Mail Processor 4.4 folder and paste it into C:\Program Files (x86). Give the new instance of the MP folder a unique name; for example, MP01. 2 No two mail processors can have same port number. Change the StatusConsolePort number in C:\Program Files (x86)\<sostenuto Mail Processor instance>\config\interfaces. where <Mail Processor instance> is the unique name of the MP service you are creating, for example MP01. # Status Console Server Connection Properties StatusConsoleHost=localhost StatusConsolePort= Create a Mail Processor Windows service to run this MP instance: Start a command prompt and type the following command: cmd <Mail Processor installation root>\instsrv.exe <Service Name> <Mail Processor installation root>\srvany.exe where path is the absolute path to the instsrv.exe and srvany.exe files and <Service Name> is the unique name of the MP service you are creating. For example: cmd C:\Program Files (x86)\mp01\ntservice\instsrv.exe MP01 C:\Program Files (x86)\smp01\ntservice\srvany.exe 4 Update the registry for this MP Windows service, to create a link to the new MP instance : Run Registry Editor and create the following subkey: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\<Service Name> For example: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\MP01 5 From the Edit menu, click New > Key then change the Key name to Parameters. 6 Select the Parameters key folder. 7 From the Edit menu, click New > String Value. Change the name of the new string value to Application. Right-click on the Application and select Modify. In Value data: enter the <path to executable>; that is, is the absolute path to the executable including the extension. For example, C:\Program Files (x86)\java\jdk <upgrade number>\bin\java.exe -DinstallPath=C:\Program Files (x86)\mp01\lib\smp-runtime.jar 8 Click OK. You have now linked the instance of the MP to the registry. 9 Close Registry Editor. Page 9 of 37

10 Repeat this procedure for each instance of MP. MP 4.4 Icons and Shortcuts When you use the MP 4.4 Installer to install MP 4.4, a shortcut is automatically added to your desktop and to the Start menu. However, when you create an instance by copying and pasting the MP 4.4 folder, no shortcuts are created. You must either add them manually or use Services on the Start menu to start and stop the instance of MP that you want to use. Page 10 of 37

11 Uninstalling Mail Processor 4.4 In order to fully uninstall the MP you should also remove the database tables. Ensure that the Sostenuto database associated with this MP instance is backed up before you uninstall, so that you do not lose your MP configuration. Follow the steps below to uninstall the MP from your Server or PC. 1 To delete the MP configuration and remove all its tables from the Sostenuto database, run the script below against the Sostenuto database. <Mail Processor installation root>\sql-scripts\smp-uninstall.sql 2 Open Add or Remove Programs from the Windows Control Panel then locate the Mail Processor program and select Remove. 3 You will be prompted to confirm the removal: Select Yes to continue. 4 Once completed, the Uninstall Complete screen is displayed: Click Finish. If an instance of the MP was created by copying the folder structure and creating the Service manually, you must manually delete the folder containing the instance of the MP and delete the Windows service. Use Windows Explorer to locate and delete the copied files. To delete the MP Windows Service, open a command prompt as an Administrator and type: sc delete <Service Name>. For example: sc delete MP01. Page 11 of 37

12 Summary of MP Functionality This chapter briefly outlines the functionality provided by the MP. Detailed explanations of the functions are provided later in the document Data flow through MP IMAP SMTP Mail Servers Mail Processor POP3 SMTP Mail Servers Sostenuto Web Service REST API The MP need not be installed on the same machine as the Sostenuto Application or database, but it must be in a location that can communicate with the database server via JDBC connection and with the Sostenuto Application server via the REST API. Mailboxes The MP monitors one or many mailboxes for new s from your customers. The MP can connect to mailboxes using the industry standard IMAP and POP3 protocols. Types of handled The MP can be configured to look for keywords in subject lines in order to carry out specific Add or Update operations within Sostenuto. Throughout this document and within the Configurator, these types of s are referred to as 'Automated' s. If no key word or recognisable format can be found, the MP can be configured to accept the as unformatted, at which point the MP can check to see if the contains a specific Service Request ID. If a Service Request ID is found, the will be treated as an Unformatted Update. If NO Service Request ID is found, the will be treated as an Unformatted Add. Services and Operations The MP can perform any operation in any service (with the exception of System Management Service). Each Sostenuto operation can be configured more than once against a specific mailbox, providing great flexibility. Page 12 of 37

13 Security settings The MP uses a Sostenuto Account and therefore any action or data that is not available to this Sostenuto Account is not available through the MP. Creating Associations The MP can create an association between the user and a newly created Service Request. Association requires user-address lookup to be enabled in order to identify the user from their address. This feature allows the information from the user record to be displayed, ensuring that when processing the record within Sostenuto, a head start on data logging is given. Responses The MP allows you to totally control responses to events that occur during the course of the retrieval and processing, be that a success or failure. The format of the s sent makes use of the Configurator, allowing access to fields from Sostenuto records, error codes and information from the incoming s. Alternatively, send no response s at all. Attachments As well as subject and body information, the MP can be configured to search for attachments to the , whether these are direct attachments or embedded images to the body. Page 13 of 37

14 Configuration This chapter describes how to configure mail box connectors and operations that will be performed on receipt of s in the specified formats. Note: Changes to the MP configuration are only activated when you stop and restart the service. When first connecting, you must define the connection from the MP to the Sostenuto database and also to the Sostenuto REST API. Windows Authentication at Runtime To use Windows authentication for the MP, you must ensure that you use a Windows Authentication account that has been created as a Login in SQL Server. Additionally the account must have DB Owner rights to the database. To configure the MP to use this account, follow the steps below. 1 Select Services on the Start menu to display Mail Processor. 2 Double-click on Mail Processor. (If there are multiple instances, ensure that you select the right one.) 3 Select the Log On tab: Figure 1: Only use this configuration if you have an NT account 4 Check This account and enter, or browse for, the name of the Windows Authentication account. 5 Enter the account s password and confirm it. 6 Click OK to save the configuration and close the Mail Processor window. Starting the Configurator To open the MP utility, go to the Start menu and select Programs > Sunrise Software Ltd> Launch Sostenuto Mail Processor 4.4. Alternatively, double-click on the shortcut by the same name on the desktop, or select the instance from Services on the Start menu. If there are multiple instances of the MP installed locate the shortcut previously created for the required instance. As it opens, MP will verify the connection settings for both the Database and Sostenuto REST API connections. If you are logging in for the first time, you will be taken to the Verify Interface Connections screen. You will also be taken to this screen if either of the connection settings has become invalid. Page 14 of 37

15 Connecting to your Sostenuto Database The Configurator presents a user-friendly interface. It combines access to the Sostenuto REST API and the Sostenuto Database in order to display all relevant information, therefore a direct connection to your Sostenuto database is required. 1 When you first open the Configurator this window is presented, showing the Database tab: Enter the following information: The name of the SQL Server hosting your Sostenuto database; if the server contains multiple SQL Server instances, include the port number of the SQL server instance as shown above. the name of the database. the SQL Server login used to attach to the server. that account s password. Check Windows Authentication if you require to log into the database with a domain account. See Windows Authentication (page 14) for more information about using Windows authentication. 2 Click Connect. The Sostenuto Connection Success popup will show whether or not the connection is successful: Note that you must make a successful connection before the MP allows you to continue. If the connection fails you can only close MP. 3 Select the Sostenuto tab. Page 15 of 37

16 Enter: the name of the Sostenuto REST API URL in the format of machine where Sostenuto is installed/]sostenuto/rest/ the Short Name of the Service for which the access point is configured; this will typically be Users the Sostenuto login to the Sostenuto REST URL the account s password. 4 Again, you must make a successful connection before the MP allows you to continue. 5 Finally, click OK to close the popup and display the Configurator screen. Configurator Screen Layout Figure 2: Example of Full message details The Configurator screen has two panels, the Configuration Panel and the Monitor Panel. The Configuration panel has two tabs: Connectors tab: add, edit and configure MP mailboxes. See Configure a Mailbox on page 17. Operations tab: add, edit and configure MP operations for each mailbox. See Configure an Operation on page 25. The Monitor panel has a separate tab for each mailbox you configure. When the MP starts polling, each tab in the monitor shows a continuous log of incoming s. The Simple and Full buttons enable you to select the amount of detail displayed in the log messages. The Full view provides more detailed information, which can be used to diagnose problems. By default both panels are displayed. Use the toggles to close a panel when you don t need to see it. Page 16 of 37

17 Configure a Mailbox The MP monitors a set of mailboxes for new from users. The MP can connect to mailboxes using the IMAP and POP3 protocols. The mail protocols supported by SMTP differ in the way they process downloaded s: POP3: Post Office Protocol (POP) is used by local clients to retrieve from a remote server over a TCP/IP connection. IMAP: Internet message access protocol (IMAP) is an internet protocol that allows an client to access on a remote mail server. IMAP supports both on-line and off-line modes of operation. To specify that all s are handled in the same way, regardless of the protocol, you must change the settings in your mail server. The Mailbox Screens Use the Connectors tab to manage and configure additional servers for the MP to monitor. Configured mailboxes are shown in the top panel of the screen. Note: When you add, edit or delete a mailbox, you clear the log messages displayed on the MP monitor. To edit an existing Mailbox, double-click on the mailbox required, or highlight it and click Edit Mailbox. To set up a new mailbox, 1 Click Add Mailbox to start the Mailbox Wizard. Use the General Properties screen below to add a unique name for the mailbox, together with a description of the mailbox, providing more information for fellow administrators. Figure 3: General properties of a mailbox Once completed, click Next to continue. Page 17 of 37

18 2 The next screen allows you to choose between POP3 or IMAP as the protocol to use to connect to your mail server. For more information on setting up POP3 and IMAP connections, see Appendix A. Choose the appropriate protocol on the Mailboxes screen: Figure 4: Select the mailbox protocol Click Next to continue. Page 18 of 37

19 POP3 Mailbox Screen If POP3 is chosen, the following screen tells the MP how to connect to a specific mailbox using the POP3 protocol. Enter the following information: Entry POP3 Host Port Requires SSL User name Password SMTP Server Description The URL to the server. You may enter a machine name, an alphanumeric URL or an IP address. The port used to connect to the server. POP3 servers typically use port 110. Check this to use SSL encryption whilst reading the mailbox. The name of the account used to log in to the mail server. The password for the above account. The URL of the SMTP server used to send replies to users. You may enter a machine name, an alphanumeric URL or an IP address. Port The port used to connect to the SMTP server, typically 25. Encryption User name Password From Address The type of encryption used for replies. May be TLS, SSL or None. The name of the account used to log in to the SMTP server. The password for the above account. Click Connect to check the values you have provided are correct. The address that replies will appear to come from, for example: MP@sunrisesw.com. After entering the information, click Connect to check the incoming and outgoing connections. You cannot continue until a connection is made. When the connection has been made, click Next to continue. Page 19 of 37

20 IMAP Mailbox Screen If IMAP has been selected as the required protocol, the following screen tells the MP how to connect to a specific mailbox using the IMAP protocol. The example below tells the MP to connect to the server smtp.gmail.com, using the account sunrisesoftware2012@gmail.com, and check the folder INBOX for incoming mail. Figure 5: You must specify a folder to store s Page 20 of 37

21 Enter the following information: Entry IMAP Host Port Requires SSL User Name Password Mailbox Folder SMTP Server Description The URL to the server. You may enter a machine name, an alphanumeric URL or an IP address, for example, MailServer or imap.mycompany.com. The port used to connect to the server. IMAP servers typically use port 993. Check this to use SSL-encryption Whilst reading the mailbox The name of the account used to log in to the mail server, for example: sunrisesoftware2012@gmail.com. The password for the above account. Once valid URL, port and account information has been entered and you select the Connect button you will get a list of valid folders on the server. This will default to Inbox. The URL of the SMTP server used to send replies to users. You may enter a machine name, an alphanumeric URL or an IP address, for example: MailServer or smtp.mycompany.com Port The port used to connect to the SMTP server, typically 587. Encryption User Name Password From Address The type of encryption used for replies. May be TLS, SSL or None. The name of the account used to log in to the SMTP server, for example: sunrisesoftware2012@gmail.com The password for the above account. The address that replies will appear to come from, for example: sunrisesoftware2012@gmail.com After entering the information, click Connect to check the incoming and outgoing connections. You cannot continue until a connection is made. When the connection has been made, click Next to continue. Configure Additional Options The next screen enables you to configure additional options. Enter the following information: Entry Separator character Poll frequency (minutes) Send if processing fails? Description The character expected to separate service, operation and service request ID values in the subject line of incoming , for example: #. The frequency in minutes at which the MP polls the mailbox for incoming s. Check this box in order to configure a notification . If you have checked the box you must configure an or processing will fail. Page 21 of 37

22 Figure 6: Remember to configure an to notify failure Click Configure to configure a notification (see page 32), or click Next to continue. A summary of the mailbox configuration is displayed. Figure 7: Page back to edit your settings Page 22 of 37

23 2. You can now: EITHER Check Launch mailbox operation configuration after finishing? to close the Connectors tab and open the Mailbox Operations screen (see page 31). OR Click Finish to save the mailbox and close this window. The new mailbox is displayed in the Connectors tab, with its status set to Enabled. A tab is displayed for it in the MP monitor. Note: The log messages displayed on the MP monitor are cleared when you save the mailbox. Figure 8:The protocol, poll frequency and status of the mailboxes are displayed Enabling a Mailbox If a mailbox has been disabled, for instance if it has been created for testing but now you want to place into production, you must enable it. 1 In the Connectors tab, select the mailbox you wish to enable. 2 Click Enable. 3 The status of the selected mailbox will change to Enabled in the summary grid and a tab for that mailbox will be displayed in the MP monitor. Disabling a Mailbox If a mailbox needs to be disabled but not deleted, for instance if you are moving from one protocol to another on the same server, we can disable it. 1 In the Connectors tab, select the mailbox you wish to disable. 2 Click Disable. 3 The status of the selected mailbox will change to Disabled in the summary grid and the tab for that mailbox will be removed from the MP monitor. Page 23 of 37

24 Deleting a Mailbox If a mailbox is not wanted in the MP, for instance if it was created in error, you can delete it. 1 In the Connectors tab, select the mailbox you wish to delete. 2 Click Delete. You will be prompted to confirm the deletion: 3 Click Yes to confirm the deletion. The mailbox will be removed from the system when you save this configuration. Note: When you delete a mailbox, you clear the log messages displayed on the MP monitor. Page 24 of 37

25 Configure an Operation The MP can perform any operation in any Service (with the exception of the System Management Service). You can configure each Sostenuto operation more than once, providing different settings to alter the MP s behaviour before allocating the operations to a mailbox. The MP divides Sostenuto operations into the following types: Operation Type Add operations Lifecycle operations Description These operations create a Service Request. (As in Sostenuto, multiple add-type operations are supported for each Service.) These operations update the history of a Service Request, possibly moving it into a different lifecycle state. To edit an existing operation, double-click on the operation required or highlight it and click Edit Operation. The procedure for adding an operation is explained below, using Add Incident as an example. Select the Operations tab and click Add Operation. General Properties 1 Enter the Name of the operation, which must be unique. For Automated s, the Name will be used as the Key Phrase to search for in the subject line. 2 Enter a useful Description for the new operation. Click Next to continue. Page 25 of 37

26 3. Configure Operation to Perform The MP can create an association between a user and a newly-created Service Request, by using the address to identify the user account in Sostenuto. When the MP performs update operations, -address look-up can be combined with other associationlookups to restrict access to Sostenuto. Use the drop-down lists to select the Sostenuto Service and Operation you wish to configure. Figure 9: An Add operation is specified. All s will be processed and an association will be created in Sostenuto when an address matches a Sostenuto account Sender Address Lookup Options In Sender Address Lookup Options, specify the s the MP should accept and the action to be taken for an add or an update request. 1 Select the Service and Field to be searched for the sender s address; for example, the field in the Contacts Service. 2 The way the MP processes incoming s depends on the operation to be performed and whether you configure it to map the address to a Sostenuto account. For an Add operation: Allow unknown s checked Allow unknown s unchecked Account mapped Process the . Process the . Account not mapped Process the . Reject the . Note: Check Create Association to associate the subject record to the mapped account. Page 26 of 37

27 For an Update operation: Allow unknown s checked Allow unknown s unchecked Check association checked Account mapped Process the . Process the . Only process the if the account is associated to the subject record. Account not mapped Process the . Reject the . Reject the . 3 Click Next to continue. Information Capture and Storage The information capture screen allows you to define where specific details of the will be placed in the Service record or history that is being created. This screen also allows you to define if attachments are to be retrieved from the and stored against the Service record. The drop-down fields on this screen list only the text and memo fields used in this operation. 1 Check each field from which you wish to capture data, then use the drop-down list to select the Sostenuto field which will store the data. Figure 10: Example of a fully-defined operation Note: If possible you should choose different fields to capture different types of information, to avoid any details being overwritten. When choosing to capture the To, From and Cc information into the same field in Sostenuto, these fields will be concatenated together, ensuring no information is over-written. If you choose the same field to capture the address information as well as the Priority, Subject or Body information, the address will be overwritten by the Priority, Subject or Body information respectively. If you choose the same field to capture the Priority Flag as well as the Subject or Body information, the Priority Flag will be overwritten by the Subject or Body information respectively. Page 27 of 37

28 If you choose the same field to capture the Subject information and the Body information, the Body information will be captured. 2 On selecting the Body check box for capture, by default the contents of the body will be added into the selected field. If the has been formatted to specify data capture fields in the body, these will be placed into the relevant fields. More information on automated messages can be found on page 32. To see more information on data capture within a message body, click on the button, shown in Figure 12 above. 3 Check Attachments to store the s attachments in Sostenuto. 4 Check Embedded Images to store images from the body as attachments in Sostenuto. Click Next to continue. Configure Default Values This screen allows you to set default values for any fields which are expected in an but are not found. Figure 11: When you select a list field, every level of sublist is displayed in Default Value 1 From the Fields drop-down list, select the parameters for the selected operation. If this is a Create operation all Service Request fields will be displayed, not just associations for the Service in which you are creating a record. 2 In the Default Value field: When the Fields selection is a text field, you can enter free text here. When the Fields selection is a List or Sublist field, such as Type or Category, you may select a default value from the field s subcategories. Default Value will display every level of sublist for the selected field, as shown in Figure Click Add to add the Field and its default value to the grid at the bottom of the screen. Repeat these steps for every field to which you are assigning a default value. To delete a row, select it and click Delete. To edit a Value, click on it in the grid. The Value is then displayed in the Default Value field, so that you can change it. When you select a Value for editing, the Add button changes to Update. When all the default values have been added, click Next to continue. Page 28 of 37

29 Notification Configuration This enables you to configure s to notify that processing has succeeded or failed. For each type of you want to send, click Configure and follow the procedure described in Configure a Notification on page 32. Click Next to continue. Figure 12: You must configure an if you check the Send boxes 1 A summary of the configuration is displayed. Page 29 of 37

30 2 Click Back to return to the wizard or, if all details are correct, click Finish. The configured operation is displayed in the Operations tab. Page 30 of 37

31 Managing Operations for Mailboxes For each mailbox, you can define a set of operations to be carried out depending on how the is formatted. 1 In the Connectors tab, select the mailbox for which you want to handle unformatted messages. 2 Click Configure Mailbox Operations. 3 The following screen is displayed: Figure 13: Select every operation you want the MP to detect 4 In Default Mailbox Operations, For an that has no Service Request ID and does not contain any operation keywords: select from the Add drop-down list the operation to be performed. For an that does have a Service Request ID in the Subject and does not contain any operation keywords: select from the Update drop-down list the operation to be performed against the specified Service Request ID. In the Automated Mailbox Operations panel, select every operation that will be checked for its key word in the Subject of the . This option allows you to perform specific operations. 5 Click OK when the configuration is complete. Page 31 of 37

32 Configure a Notification To configure a notification , complete the address fields and the body. You may enter free text and variables, as shown below. 1 To, From, Cc and Bcc fields for the notification . 2 As well as free text addresses you may right-click on the address fields to choose from: The Original Sender s Address who is the from Sent To Recipient(s) who was the sent to, typically used for the From address in the notification. Sent Cc Recipient(s) those in the original CC address. 3 Subject and Body details. You can concatenate free text together with field variables to pass a meaningful response to the user who has sent the . These variables are displayed for selection when you right-click on the Subject and body of the response . The following options are available. Sent s Subject: The original subject line from the incoming message. Sent s Body: The original body of the incoming message. Returned Record ID: The Service Request ID of the record created. Returned Error Message: In case of Error, the details of that error. Original Sender s Address: Who the is from Sent To Recipient(s): Who the was sent to, typically used for the From address in the notification. Sent Cc Recipient(s): The addressees in the original Cc address. Figure 14: Right-click in a field to select variables 4 Click OK to save the configuration and return to the screen where you clicked Configure. Page 32 of 37

33 Handling Automated Message Formats Automated messages are those that come into the Inbox in a formatted manner, typical of automated messages from system monitoring tools or other tracking systems. Automated s can be set against one or more mailboxes in the Configure Mailbox Operations screen, as displayed in Figure 13 on page 31. By selecting the operation to be checked for automation against the mail box, we are instructing the Mail Processor to look for the operation name keyword, prefixed by the separator recognised in the mailbox. This can be used for both Add and Update operations. Example: Add an Incident, where the mailbox delimiter is a # : Subject Line: #Add Incident Note that no Service Request ID is required, as this is a new record and has yet to be allocated its ID. Example: Update an Incident with an Add Note operation, where the mailbox delimiter is a # : Subject Line: #AddNote#INC Note that the Service Request ID is included after the operation key phrase, separated by the allocated delimiter. You can map information in the body of the directly to fields within Sostenuto, by formatting the inbound so that the Mail Processor can read the field tag names and allocate the data within them to the corresponding field in Sostenuto. 1 The body of the where formatted data resides should be enclosed with <data> </data> tags. Information outside of the tags will be ignored. 2 Inside the Data tags you can specify either fields of type Service Request or Service Request History or both. Tags to use are either <srrfields> </srrfields>, or <srhfields> </srhfields> respectively. 3 The Sostenuto field name should be used as the tag name for the actual field data tag as seen in the example below. Example: Formatted used to add a new Incident where the mailbox delimited is a # Subject Line: #Add Incident Body: <data> <srrfields> <name>printer Error 303</name> <priority>2. High</priority> <category1>incident</category1> <category2>hardware</category2> <category3>printer</category3> <description>when a large print job of over 100 sheets is sent, this error occurs each time.</description> </srrfields> <srhfields> <actiontext>added by the Mail Processor</actionText> </srhfields> </data> Page 33 of 37

34 Note: When performing a Create operation, any Service Request History fields detected in the automated will be placed into the first Service Request History record for the new Service Request; this is typically the Create operation. Page 34 of 37

35 The File Menu The File menu contains two options: Verify Interface Connections: Display the Verify Interface Connections popup (see page 15). Exit: Exit the MP. Page 35 of 37

36 Hints and tips for Microsoft Exchange and IMAP/POP3 Mail Processor does not support the MAPI protocol as this moves out of mainstream support for the latest versions of Exchange. Exchange Web Services are on the Mail Processor roadmap for future development. The latest versions of Exchange, however, do support IMAP and POP3 connections, and the details below assist in setting and securing these connections. Enabling IMAP/POP3 connectivity The same steps are required for enabling IMAP or POP3 on any of the Microsoft Exchange versions from 2003 to At the Microsoft Exchange server, you simply enable the Windows service and start it. Once logged onto the Microsoft Exchange server, follow the steps below: 1 Open the Services Management Console. 2 Locate the required service (either Microsoft Exchange IMAP or Microsoft Exchange POP3). 3 Double-click to view the Properties dialog. 4 Enable the service. 5 Start the service. 6 You should also switch the Startup Type to Automatic to ensure the service is started automatically after a server reboot. At this point you can connect to all default mailboxes via the chosen mail protocol, over the default port numbers. Considerations Firewall Blocking If the Microsoft Exchange server resides on a network outside the one where the Mail Processor resides, there will probably be a firewall between them. If a firewall exists, that may block communication. In this case a rule should be created in the firewall that allows communication from the Mail Processor to the Microsoft Exchange server, for the port number of the chosen protocol. See the table of Default IMAP and POP3 Port Numbers on page 37. Secure Communication with SSL and TLS If communication from the Mail Processor has to travel across a public network (for example over the Internet) it is recommended that you use SSL/TLS to secure communication. Typically, if Outlook Web Access is used and exposed to the internet, an SSL certificate is probably in place already. If this is the case, you can use the same certificate to secure communication from the Mail Processor. If a certificate is not already in place, you should acquire one and install it at the Microsoft Exchange Server. If the SSL certificate is not issued by a recognised Certification authority or is a self-signed certificate, follow the steps below to import the certificate to ensure that the certificate is recognised as coming from a trusted Certification authority. 1 Copy the certificate file to the <JAVA_HOME>\lib\security folder 2 Run the following command: <JAVA_HOME>\bin\keytool -import -alias <EXCHANGE_SERVER_NAME> -file <CERT_FILE_NAME> -keystore jssecacerts 3 It will prompt for a password. Enter any password that you prefer. Page 36 of 37

37 4 At the end of the execution, the user will be prompted with the question Trust this certificate? [no]: 5 Type yes and press the Enter key. 6 Restart the Mail Processor. The SSL and TLS Configuration tables below contain links to information on how to install and configure SSL and TLS. While it is recommended that you secure communication for public access, it is not mandatory. Resources Default IMAP and POP3 Port Numbers Protocol TCP Port Number IMAP 143 IMAP with SSL 993 POP3 110 POP3 with SSL 995 SSL Configuration Exchange SSL and TLS Configuration Exchange Exchange Page 37 of 37