Installation

M-Files Email Processor is a standalone rule-based application designed for the most common scenarios – when integrating an email with M-Files. M-Files Email Processor allows a user to configure the rules and exceptions under which the email will be stored. You can create new or update existing M-Files object and map fields from an email into object properties.

1. Installation

The groundwork is easy, the installation is done on the same server where the M-Files server is installed.

After that, you need to configure an access to your mailbox and connect it to the desired vault. Voila!

1.1. Installation and preparation

Well, it’s not all that simple, there are some prerequisites for the installation of the product:

• Microsoft SQL Server
  • M-Files Email Processor uses SQL Server as an underlying database to store the configuration and runtime setup. To be able to install M-Files Email Processor, you need SQL Server, database, one account that installs schemas to the database and one account that is used in runtime (this can be one account in case you don’t have granular permissions configured on that database). SQL Server doesn’t have to be installed locally.
• M-Files server
  • M-Files Email Processor uses M-Files API to communicate to vaults and therefore needs M-Files Server to be installed locally. Without the local M-Files Server, M-Files Email Processor cannot be installed.

Installation is done in a few simple steps:

1. Get the installation file at our Product page. Register for a trial and download a free trial setup or request a full version.
2. Start the setup on a Windows based machine with M-Files server installed.
3. Click Next-Next-Finish if you need only the basic and default settings. Otherwise, check the list of installation steps and adjust certain settings if needed.

List of installation steps:

1. EULA: End User License Agreement, you should agree to, if you want to continue with the installation and use the product.
2. Start Menu Folder: Folder name in the start menu, which can be disabled.
3. Additional Tasks: Miscellaneous install options:
   1. Icons – Create desktop shortcut: Choose whether to create a desktop shortcut, or not.
   2. Configuration – Force configuration for Service and Configurator: choose whether the Configuration Setup (see below) should be run at the end of the setup, or not. This is recommended if you’re installing M-Files Email Processor for the first time. If M-Files Email Processor has already been configured on this machine, just skip this part.
4. Ready to Install: Summary page that shows all the selected options.
5. Installing… At this point, if it was checked, M-Files Email Processor Configuration Setup started.
6. Finished!

1.2. Email Processor Configuration Setup

Email Processor Configuration Setup is a small configuration/setup application that allows simple and quick initial configuration of M-Files Email Processor Service.

Steps of Email Processor Configuration Setup:

1. License: enter the license code that you got from us. Configuration Setup cannot continue if the license code is not entered. If you do not have a license, you can always request for a trial or full license at our Product page.
2. SQL Server – Schema installation: Set up a connection to SQL Server that will be used by M-Files Email Processor.
   1. Server name: name of the SQL Server. Enter “.”(dot) if SQL server is installed locally.
   2. Account type: this account is used only for the installation
      1. Integrated Security – uses the account that runs the setup, and that account must have all the database privileges to install the database (DB Owner)
      2. Specific Account – Enter username and password of the specific account that will be used to install the schema into the database (DB Owner)
   3. Database Name: name of database where you want to install all schema and tables and other artifacts needed by M-Files Email Processor.
   4. : At this point, you cannot create a new database, only add a schema information to the existing one. If you want a new database for M-Files Email Processor, create a new database manually and refresh the list of the databases on the server, either by going back and then clicking next, or re-enter the information on the page for a force refresh of the drop-down menu. Note
3. SQL Server – User configuration: Sets up an account for service to run under.
4. Account type: Type of account for service
5. Integrated Security: Uses LocalSystem account for the M-Files Email Processor Service ii. Specific Account: Enter username and password of the specific account for the M-Files Email Processor Service
6. Test connection button: test the connection with the chosen server/database with the provided account. Use this if you want to make sure that all the provided information on that page is correct.

Errors

If something went wrong while installing M-Files Email Processor, note that all the errors are written down to files in folder:

C:\Program Files (x86)\M-Files Email Processor\logs\setup or C:\Program Files\M-Files Email Processor\logs\setup depends on 32-bit or 64-bit systems.

2. Configuration

M-Files Email Processor Configuration is a small administrative application that is used to configure all parts of M-Files Email Processor. It is used to configure M-Files vaults connections, input mailboxes, output mailboxes, log types etc. But its main purpose is to configure M-Files Email Processor process, which connects email (Mailbox) using some Filters with M-Files Vaults using some Actions.

• Mailbox – email that is used as a source, all mails will come from this one specified mailbox
• Filters – determine which emails will be received from Mailbox
• M-Files Vault – no extra explanation 
• Action – what to do with the fetched email in vault

M-Files Email Processor Configuration main window displays a searchable list of all created processes with their statuses. From that window you can add new processes, Start/Stop entire service and open process details by clicking on desired process. Also, the window offers left side navigation with different parts of application.

Every Process has one Mailbox, one or more Filters, one Vault connection and one or more Actions. But before we can configure the process, we need to set at least one Mailbox and at least one M-Files Vault connection. Configurator will remind us of that if we click on Add New button, but don’t have all configured.

2.1. Email Accounts & M-Files Connections

First step is to prepare our M-Files Connection by clicking on the M-Files Connection button.

M-Files Connections

Description of the fields on the Document Vault Connection Properties window:

• Name: Friendly name of the vault that will be used by M-Files Email Processor. This name doesn’t depend on the Vault name
• Server: Information about the M-Files server. This could be, but doesn’t have to be, a local server.
  • Name: Name or Fully Qualified name of the server, e.g. MyComputer or MyComputer.MyCompany.com. If the server is a local server on which M-Files Email Processor is installed, enter “localhost”
    • Port number: Port that is used for the communication with the server. All M-Files servers are listening on port 2266 by default.
    • Protocol: Protocol used for communication with the M-Files server. At the moment, the only protocol that is enabled is the TCP/IP protocol.
• Test connection button: testing the connection only to M-Files server to see if it is available.
• Logon information: Account that is used to connect to M-Files server/vault. This account is used to load all vaults from server and to connect to the specified vault, so it needs to have proper permissions on M-Files server.
  • Authentication: type of an account: M-Files user or Windows user.
  • Username: account username.
  • Password: account password.
  • Domain: account domain, enabled only for windows user accounts.
• Vault on server: specifies to which M-Files vault you want to connect to. This is a dropdown menu which is populated only when a connection to the server is possible.
  • Load button: Loads all vaults from M-Files server if it is possible. If server is inaccessible, error popup is raised, and dropdown menu is not populated.

Note: Without specifying the vault, connection information cannot be saved, and OK button is greyed out. Only after specifying the vault, OK button will be enabled. That also means that all the previous information must be correct.

Note: All required, but empty fields have red rectangles around text box. Connection information cannot be saved if some of the required fields are empty, so make sure to enter all the needed information.

After saving the connection settings, a vault can be used in setting up a new process in M-Files Email Processor.

Mailbox Connections

On this screen, we can see and setup all the incoming and outgoing emails/mailboxes. They are used for monitoring emails from which you want to parse information that can be imported to M-Files vault. In case of outgoing connection, it is used by M-Files Email Processor to send emails. The configuration process is similar to the one shown for incoming mail accounts.

To add new mailbox information, open Email Accounts screen via the side menu. Then, you can click “Add new” button and enter your desired information.

When a new mailbox information is entered, popup window will look like this:

Additional information in the email account settings window:

• Email Address: Friendly name of an email that will be used by M-Files Email Processor. This name doesn’t depend on the email address that is used to log on to the account (it is not depended on real email address?)
• Server Information: Information about mail server to which M-Files Email Processor will connect to.
  • Load settings from template: choose a template to pre-populate Server Information fields. Currently existing templates are Hotmail, Gmail, G Suite, Office 365.
  • Account type: defines protocol type for getting emails from mailbox. Currently only the existing type is IMAP.
  • Incoming mail server: Name of the mail server to which the M-Files Email Processor will connect, to get the emails. It can be pre-populated with the template field or ask your system administrator to tell you the name of your mail server.
  • Port: Port used to connect to mail server.
  • Require secured connection: choose whether to use SSL when connecting to mail server or not.
• Logon Information: Account information that is used when authenticating on mail server, Also, defines an account from which we will get emails.
  • Username: login account username.
  • Password: login account password.

After saving mailbox information, incoming mailbox can be used when creating a new Process.

Account blocking

Some mail providers, like Hotmail/Outlook or Google/Gmail can mark M-Files Email Processor’s connection to mailbox as suspicious. Because of that, initially connection to your mailbox can be denied from the mail server and it has to be manually approved.

You can receive an email from your provider in which they state that you had a new connection on your mailbox, e.g., Microsoft email can look like the one below, stating that you have to confirm that it was you:

After clicking on that link, Microsoft shows you more details about the actual connection:

While IP address and location will vary depending on where the server with M-Files Email Processor is installed, Session Type will always be Automatic Sync and protocol will be IMAP. After clicking on That was me button, M-Files Email Processor will successfully connect to mailbox.

2.2. Process Configuration

After a successful configuration of the M-Files connections and Email accounts you can create processes that actually fulfil your needs.

After opening the Processes screen and clicking on “Add new process” you will see Process Settings window.

General

The first tab is “General” where you define general settings for wanted process. Here you can also define:

• Process Name: the name of your process which will be shown on the Home Screen.
• Email account to monitor: here you have to define which email account you want to monitor with this process. The list displays all the incoming email accounts configured in Settings.
• M-Files connection: here you have to define which M-Files connection you want to use for this process. The list displays all configured M-Files connections configured in Settings.
• Object class: based on your selected M-Files connection, here you will see the list of all the object classes fetched from your M-Files vault. You have to select object class with which you want to process work.
• Disable process checkbox: Check if you want to disable the process.
• Delete email after import checkbox: This option allows you to delete an email once it is imported and processed by M-Files Email processor
• Mark email as read after import: This option allows you to mark an email as read once it is imported and processed by M-Files Email processor
• Apply on newly received emails and Apply on old and new emails radio buttons: Here you can choose whether you want to apply this process settings on newly received emails or you want to process both newly received emails together with the old emails in the mailbox.

Next thing you may want to configure are Conditions and Exceptions. For that you can use Conditions and Exceptions tabs.

Conditions and Exceptions

On both Conditions and Exceptions, you see the list of available options for processing emails. You can specify as many conditions and exceptions as you need. After you select exception or condition you want to setup you will see the List Input pop-up window.

From that window you can define a word or a phrase to search for in the selected field (subject, To:, Body:, etc.). After you specify a word or a phrase you have to select Add and that specified word, or a phrase will be added to the List. List displays all specified words or phrases, and you can always remove some of them by selecting Remove.

Create or Update Object

Next available tab in the Process Settings window is Create or Update Object tab. Here you define main rules for creating and updating objects based on emails that satisfy defined objects and conditions.

The first thing you have to decide is whether you want to create a new M-Files object or you want to update the existing one. For that you have to select either Create new object or Update existing object radio button.

Create new object

After you select Create new object radio button you will see the list of properties for an object class you selected on the General tab.

Whether you select Add button or click on a specific property and select Edit, the Property Editor window will be displayed. The only difference between Add and Edit is that when you select Add you will be able to select the property from the list of available properties for a selected M-Files object class.

From this window you can define whether you want to use a fixed value for property or you want to read value from an email.

If you want to use a fixed value in a Value field you have to define the value you want to add for a selected property. This field recognizes property type and it will display an adequate input field. For example, if you select property of type Date you will see the date picker.

Read from email option allows you to compose a value from the different parts of an email. You can read values from:

• To:
• Subject:
• MessageId:
• From:
• Date:
• Cc:
• TextBody:

By simply clicking on the wanted field you compose your value. All the selected fields will be added to Compose value: field.

ou can remove some of the added fields with Backspace on your keyboard.

RegEx Placeholder Editor windows allows you to add Regular Expression and parse information from the selected email field. You can add and edit regular expression by clicking on added email field.

From that window you can enter the regular expression you want to use to parse the information. Additionally, you can test your regular expression with the test input. Once you input your test values you can click on the Test RegEx button which will display the result in RegEx Match Result field.

After you define properties and values you want to map to M-Files you can choose what you want to do with the email attachments.

Picture above displays available options for parsing email attachments.

Update Existing Object

If you decide to update existing object you will see Update existing object tab.

Here, you define which M-Files object will actually be updated. You can do that by clicking on a Map Value button which opens Property Editor window, the same one as for defining values when creating a new object. Once again you can choose if you want to use a fixed value, or you want to parse an Object ID from the email. Process of gathering value from the email is the same as described for Creating a new object.

Once you define the Object ID for the Object that you want to update, you can set the values for each property.

The last option to configure for the process is Send email.

Send email

By selecting Send email after processing checkbox, your process will send an email once the processing of the incoming email is done. In order to configure sending an email you have to select an email account that you want to use for sending emails. From the list, you have to select which email account you want to use. This list displays all the configured outgoing email accounts from the Settings.

After that, you need to define Recipients, Subject and Message.

Recipients tab allows you to define who will receive an email once the Email Processor is done with the processing of an email. Here you have two checkboxes:

• Include recipients of the original email
• Include sender of the original email

Besides that, you can define a list of additional recipients. By clicking on Edit additional addresses you will get a List Input window from where you can define a list of additional email addresses.

Subject tabs allow you to define the subject of an outgoing email.

Compose Subject field allows you to define any subject name but also to use some placeholders from M-Files objects. Clicking on Add Placeholder button will show you the list of available placeholders you can use for Subject line.

Finally, you need to define the content of the message that is going to be sent.