Boru Email Linker User Guide

Patrick O'Brien
on July 26, 2018

This is a summary flow chart to help you understand how the email linker works:

Enhanced Email linker is a tool which will help you to track and link the emails which are not linked to any vTiger entity.
- Basic functions:

1) You can filter the emails based on the user who sent/received emails.
2) You can filter the emails based on the From/To date.
3) You can filter the emails based on the type(Incoming/Outgoing) of the email.
4) With a click on the “Link To” drop down you will be able to link the email to the listed contacts.

4.1) The drop down values will contain the “Company, Contact Name”. Select the Company/Contact and the email will be linked automatically (Please see below for “Link & Add/Link”). Note, if you have multiple emails from the email sender/recipient and you link one of the emails, it will automatically link all of them, but you will need to refresh the filter in order to see the changes. We are using fuzzy logic (based on first name, last name, email domain, etc..) to find the closest match to link the email.
4.2) If you can’t find the right contact in the drop down list, use “Link To Other Contact” to find the contact.

4.2.1) Hit “Link & Add” and the contact search window will open. When you choose a contact it will link the email to the contact and add the new email address to the contact’s record.
4.2.2) Hit “Link” and the contact search window will open. When you choose a contact it will just link the email to the contact.
4.2.3) Hit “Cancel” and the popup will close.
4.3) If you can’t find the right contact in the drop down list, use “Create New” to create a new contact. The new contact window will open with the email address already filled in. When you save the contact the email will be linked automatically.
5) When you check the check box in the “Delete” column, you will be prompted to confirm that you want to delete it and the email(1) will be deleted.
6) “Block” check box, is used to block the unwanted emails from showing up in the Enhanced Email Panel.
6.1) If you block the Incoming email, it will add the “FROM” email address to the exclusion list. Please see “Exclusion List” for more details.
6.2) If you block the Outbound email, it will add the “TO” email address to the exclusion list. Please see “Exclusion List” for more details.
- Note: when you block the email, it will not show up in the panel anymore, unless you remove it from the Exclusion list.
7) The “Refresh Filter” button is used to refresh the email list after you update the filter(#1,#2,#3) and/or blocked/deleted emails.
8) Exclusion List is used to store blocked emails addresses.

8.1) When the email is blocked, the email address will show up in the Exclusion list. If condition starts with “To Email” = ‘abc@zyx.com’, then the outgoing email was blocked, if the condition starts with “From Email”, then the incoming email was blocked.
8.2) When the condition is selected, it can be edited, you change it from “From Email” to “To Email” and vice versa.
8.3) You can also change the condition, there are 3 options: “Equal”, “Not Equal” and “Contains”. For example, if you want to block all incoming emails from @delfi.com domain, you would add the rule “From Emails” Contains ‘@delfi.com’.
8.4) You can also adjust the email address that is being blocked.
8.5) This drop down contains “Or” and “And”, it is used for more complex blocking conditions.
8.6) After adjusting/adding new condition be sure to hit “Save”.
8.7) To remove the condition, select the condition first, then hit “Remove”.
8.8) Use “Add New” to add new conditions.
8.9) You can also search for conditions that have been added. Select the “From Email” or “To Email”
8.10) Select the condition “Equal”, “Not Equal” or “Contains”
8.11) Enter the email address you are looking for.
8.12) Hit “Search” to find the condition.
8.13) Use “Close” to close out the Exclusion list window.

[/accordion]
[accordion title=”Daily Email Report”]

This report will notify the user of the emails which were not linked during the day. You can access the configuration for the report by going to “Settings > Modules > Custom Modules > Boru Email Linker” and hit the “Daily Email Report” button.

From Email: – Enter the email address from which the report will be sent
Email Subject: – Enter the subject of the report.
Email Body: – The body of the report. You have the option of using the variables $count and $LINK_here in the body of the email (you can replace here with any other word and it will be hyperlinked), which will display the following information:
- $Count – is for the count of emails that are not linked for the selected user.
  $LINK_here – will be the direct link to user’s unlinked emails interface.
Use Add/Remove to add or remove user from receiving the report. Note: the report will be sent to user’s primary email address.
Note that the mail server which will be used is entered in Settings > Outgoing Server, so make sure you have that one working.
To find more information on how to setup the emails please submit your email address for more information.

This report will include the count of all received/sent emails during the specified time period. You can access the configuration for the report by going to “Settings > Modules > Custom Modules > Boru Email Linker” and hit the “Incoming/Outgoing Report” button.

From Email: – Enter the email address from which the report will be sent
Email Subject: – Enter the subject of the report.
Email Body: – Enter additional body text, and the report will be included below the text you entered.
Use Add/Remove to add or remove user from receiving the report. Note, the report will be sent to user’s primary email address.
Note that the mail server which will be used is entered in Settings > Outgoing Server, so make sure you have that one working.
Please reach out to us to find more information on how to setup the emails to go out daily.

Boru Email Linker has an ability to link emails based on a field in the email subject/body. For example, if you are sending an email to a client regarding Trouble Tickets and include the Trouble Ticket number/id in the email subject/body, that email can be automatically linked to that Trouble Ticket as well as the contact.

Instructions below are for vTiger 5.4, if you need instructions for 5.3 – please reach out to us.

Open vTiger
Mouse over the “Settings” icon
Hit “CRM Settings”
Click on “Module Manager”

Select “Custom Modules” Tab
Click on the Hammer next to the installed module name

Click on “Configure Module Linking”

Select Trouble Tickets module
Click “Add Email Related List View to HelpDesk”. Note, by default vTiger does NOT have an Email section included in the Trouble Ticket details (i.e., below the Trouble Tickets), so this step is necessary to display Emails below Trouble Tickets. You will be prompted to confirm the addition, since it will modify your vTiger core files.
Options:
- Add to Unlinked Emails Panel – If set to “Yes”, then the module will show up in the Unlinked Email Panel and you will be able to link emails to Trouble Tickets manually.
- Auto Link Emails – If set to “Yes”, then emails will be linked automatically based on the option(s) chosen in Linking Method. (See below for details)
- How to Link The Email – You can specify where you want to link the email to. You can link it to Trouble Ticket as well as the Contact/Account which is linked to the Trouble Ticket.
- How to handle Attachments – Email Attachments can be linked to the email, linked as a vTiger Document, or ignored.

Linking Method

“Default” will link email messages if it finds a matching email address in the record (note: “Default” linking can only be used for modules which contain an “email” field, such as Contacts, Leads, and Organizations. If you wish to link to a module which does not have an “email” field associated with it, such as Trouble Tickets or Opportunities, you need to select the “Custom” linking method, which is described below). Note: the email linker will look in all email type fields.
Custom
- Once we set Linking Method to “Custom”, we have an option to select which vTiger field value we will be looking for in the email and which part of the email (i.e., Subject, Body, To:, or CC:) the linker will be looking in for that value.
- After selecting your desired combination of “What Field to look for in the Email” and “Where to look in the email,” click the “Add” button below “Field Mapping/Searching” to enable those search options and display a text input box which shows the format of how the information will be searched for in emails. (Note: you can change the [[<i>field_name</i>]] to whatever you like, but if you use the default option of [[<i>field_name</i>]], the text in the email must also contain the surrounding square brackets–not just the field data between them–in order for the linker to link the email.)
- In this example I chose to look for “Ticket No” in the email Subject. For example, if there’s a Trouble Ticket with number of 1122, and an email comes in with a subject line of “ANY TEXT [[1122]] ANY TEXT”, the email message will be linked to that Trouble Ticket.

Installation Instructions

Configure Cron Job/Scheduled Task

Cron Job (Linux Servers)

Email Scraper

Linux distributions vary, but this is one way:

Enter the cron file
```
$ crontab -e
```
or
```
 pico /etc/crontab
```

The example below will update every hour, at 5 minutes past the hour.

5   *    *     *     * root php -f YOURVTIGERCRMDIR/modules/BoruEmailLinker/emailscraper.php

Email Reports

To Set a cron for Daily Email/Incoming Outgoing Report please add the following lines:

Enter the cron file
```
$ crontab -e
```
or
```
 pico /etc/crontab
```

The example below will run once a day at 4:16PM

16   16    *     *     * root php -f YOURVTIGERCRMDIR/modules/BoruEmailLinker/UnlinkedEmailsSend.php
16   16    *     *     * root php -f YOURVTIGERCRMDIR/modules/BoruEmailLinker/in_out_report.php

Scheduled Task (Windows Server 2008)

Email Scraper

Open “Task Scheduler”
Select “Create a Task”
Enter the name/description
Go to Triggers tab
1. Hit New and set it up to run every 30 minutes.
1. Create 2 additional scheduled tasks, but the argument should be different:
  1. ```
  1. -f "C:/Path/to/YOURVTIGERCRMDIR/modules/BoruEmailLinker/UnlinkedEmailsSend.php"
```
  1. Actions: “Start a program”
  2. Program/Script: C:\Path\to\php.exe
  3. ```
  Add arguments (optional): -f "C:/Path/to/YOURVTIGERCRMDIR/modules/BoruEmailLinker/emailscraper.php">
```
  4. Hit “OK”2. -f “C:/Path/to/YOURVTIGERCRMDIR/modules/BoruEmailLinker/in_out_report.php”Go to Actions Tab, and hit “New”

Patrick O'Brien

Interested in learning more? Let us send you an email.