====== Installation ======
===== Requirements =====
The following is required for Mail Gateway to work:
  * **Microsoft .NET Framework 4.0** (full edition)   
  * **Microsoft Exchange 2007 or later** with Exchange Web Services (EWS) enabled. Older versions of Exchange are //not// supported. Exchange Online (i.e. Office 365) is also supported but take notice that you may have to enable basic authentication/EWS support for your tenant, alternatively use [[addons:mail-gateway:oauth2|Oauth autentication]] (//[[https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth|only]]// supported with Exchange Online).
  * **Lime CRM Web Service 10.6 or later** enabled and configured for the database(s) that Mail Gateway should import messages into.
During installation you will also need the following:
  * **Administrator privileges** on the machine where Mail Gateway is to be installed.   
  * **Account details** for the mailboxes (shared or personal) that are to be monitored:    
     * Mailbox name (email address)
     * User name for a user that has full permissions on the mailbox (if not using impersonation)
     * Password for that user
  * **Connection details** for Lime CRM Web Service (perhaps to be found in LISA):
    * Endpoint address (e.g. //<nowiki>http://limeserver.local:1337/lime/</nowiki>//)
    * Binding type (e.g. //basic http//)

===== Step-by-step guide =====
Follow these simple steps to get Mail Gateway up and running:

  - If you are going to use Mail Gateway with Office 365/Azure AD and Oauth2 authentication, first follow [[addons:mail-gateway:oauth2|this instruction]] to configure required Azure AD settings.
  - Run the Mail Gateway Windows Installer package (.msi file).
  - After the installation has completed, launch the //Mail Gateway Configurator// utility to configure and test Mail Gateway (refer to the Configuration section for details). Please note that the utility reads and processes messages from the inbox just as the Mail Gateway service does, which means the messages will be imported to Lime and deleted from the inbox.
  - When satisfied, start the Lundalogik Lime CRM Mail Gateway service through **Administrative Tools** | **Services**.

<WRAP round important>
=== Warning! ===
There have been problems installing the Mail Gateway service if the Services management window is open. Therefore, close Services control panel window before beginning the installation.
</WRAP>

<WRAP round info>
=== Note! ===
The installation requires true administrator privileges. If nothing seems to happen when you try to install the .msi file, open an elevated command prompt and install using the following command: 
<code>msiexec /i [path to .msi file]</code>
If you are upgrading an existing Mail Gateway installation and it won't complete despite administrator privileges (with an error message asking you to verify that you have sufficient privileges), please check if there are other users logged in to the server. It may be that they are locking the old installation, preventing the upgrade to complete.
</WRAP>

===== Upgrading =====
If upgrading from Mail Gateway version 1.x the configuration file will be automatically updated to a new format. Some manual changes regarding how sub tables are handled are however necessary and will be automatically marked in the configuration file (the service will not start until fixed).

Breaking changes to be aware of when going from version 1.x to 2.x:

  * Exchange public folders are no longer supported. Migrate to shared mailboxes.
  * Using MAPI for connecting to Exchange is strongly discouraged. Use Exchange Web Services instead.

Other things worth thinking about when upgrading:

  * .msg file templates are loaded differently in the new version which may lead to formatting problems. Always test everything after the upgrade!
  * The ''<nowiki>%%</nowiki>RECEIVEDATE<nowiki>%%</nowiki>'' field code now only sets the date while ''<nowiki>%%</nowiki>RECEIVEDATETIME<nowiki>%%</nowiki>'' sets both date and time.