How to set up Inbound Email Integration

Email Integration Plugin for Targetprocess connects to your inbox and retrieves email messages, binding them as comments to user stories (bugs, tasks, etc.) or creating Requests.

The Plugin uses POP3 or IMAP protocol for downloading emails. POP3 or IMAP incoming connections needs to be enabled in the internal settings of your mailbox.

IMAP protocol support requires Targetprocess v3.8.7+

Targetprocess doesn't provide you with any default mailbox for incoming mails, so you are welcome to sign up with any third-party email service.

Both POP and IMAP integrations support only individual mailboxes. IMAP integration in Targetprocess cannot connect to the whole Exchange server and download messages from all inboxes in a bulk.

Troubleshooting connection issues with Gmail

Gmail service is supported. However sometimes Check Connection action rejects provided credentials. There are two possible causes.

A. Two-step verification is not enabled

Please try to enable two-step verification and register Targetprocess as an application in your Gmail account settings. How to register it. When Targetprocess is registered, take obtained 16-digit passcode and put it into Password field in plugin profile settings form instead of your regular email account password.

B. Captcha should be passed in web browser

When you receive the following error:

Cannot login: Wrong account name and/or password. The server responded: MBN00000003 NO [ALERT] Please log in via your web browser: https://support.google.com/mail/accounts/answer/78754 (Failure).; Connection settings: Protocol=imap, MailServer='imap.gmail.com', Port=993, Ssl=Yes

that means you need to open your web browser and navigate to https://accounts.google.com/b/0/DisplayUnlockCaptcha, then click 'Continue'.

Set up incoming emails

To set up the Plugin please go to Settings > Plugins and add Project Email Integration profile.

Connection settings

Click Check Connection to make sure the settings are correct.

The Plugin checks for new messages every 5 minutes. This interval cannot be customized so far.

By default POP integration checks all incoming emails since the beginning of time. However, some smart email servers in POP settings allow to specify starting from what time moment messages will be available for download and whether any inner folders are visible for POP connections.

IMAP integration checks all emails in primary folder only. Messages from inner folders are not retrieved.

IMAP integration checks all incoming emails since the beginning of time. In order to let the plugin to download only messages starting from some specific moment and prevent creation of duplicated requests for older messages you have to move all old emails to a Archive folder in your IMAP inbox in advance.

Set up processing rules

At least one Rule should be added to let the Plugin process your incoming email and create Requests or Comments in Targetprocess.

Creating Comments only

It is good to add only one basic rule to let the Plugin accept your messages and add Comments to the related Targetprocess entities. Here is how you can set it up:

• Choose or create the primary Project for your emails. This Project should always be active. Having the primary Project is a requirement for Email Integration plugin. In the meantime, the Plugin will attach Comments to other Projects as well, regardless if they are primary or not.
• Go to the Details page for this Project and check if Requests practice is listed below the Process name. Enable Requests practice in the Process settings if it is missing there.
• Check the Project ID number on the Project Details page. Say, it is #283.
• Add a rule with the following syntax to the list of Plugin Profile rules:

  then attach to project 283

Creating Requests with Rules: create all Requests in the single Project

Here 283 is a numeric ID of the project that will serve as a container for all new requests.

This basic rule allows the Plugin accept your emails and either create new Request within selected Project if a message is not related to any existing entity or add Comment to the related Targetprocess entity.

• Choose or create the primary Project for your emails. This Project should always be active. Having the primary Project is a requirement for Email Integration plugin.
• Go to the Details page for this Project and check if Requests practice is listed below the Process name. Enable Requests practice in the Process settings if it is missing there.
• Check the Project ID number on the Project Details page. Say, it is #283.
• Add a rule with the following syntax to the list of Plugin Profile rules:

  then attach to project 283 and create request in project 283

Creating Requests with Rules: distribute Requests by multiple Projects using processing Rules

Rules have the following format:

when [conditions] then [actions]

Each rule should start with a new line. Rules specify the criteria that a message should match and the resulting action that is taken when the match is found. The rules are evaluated in sequential order, first to last. The first rule to match is the "winner" - after the first match the given message is no further evaluated against all subsequent rules.

For the final rule (i.e. applied by default when all the previous rules are not matched) the “conditions” part is not needed. The rule can start with "then" part.

Rejecting rule

It is not possible to specify a rule to reject a message so far. However, it is possible to create a dummy project for unintended messages and add an intercepting rule as a workaround.

Private and Public requests

Public and private requests are equally visible in Targetprocess tool. However, there is a difference in visibility in Help Desk portal. Public Requests are shown for all requesters that have access to some product. Private Requests are shown only to requesters specified in From: and CC: fields.

More details can be found here: https://targetprocess.com/guide/helpdesk-portal/helpdesk-faq/

Recipients in CC field

When request is created, the Plugin adds all users from CC: field as Requesters to the Request. This helps to keep all email participants notified about Requests.

Distribute incoming emails by client Companies

There is a "when" condition that helps to check to which company the sender user belongs to.

Let’s say, we have 2 projects. Project1 with id=1 and Project2 with id=2. Project2 is assigned to Gmail company.

We can set the following rules in the profile:

when company matched to project 2 then create request in project 2
then create request in project 1

Rules are checked from top to bottom. Let’s see how these rules are applied to messages.

If an email is sent by the requester from Gmail company, that is from a @gmail.com address, this message will be attached to Project2 with ID 2 with the Request created in this Project (match by the 1st rule).

All the other messages matching neither of the first two rules will be moved to Project1, with requests created for Project 1.

Set up outgoing emails

To allow your users to communicate with Targetprocess using emails, please specify the address of your mailbox in two locations:

1. On the Email Notifications settings page. The default address notifier@apptio.com is good for sending notifications, but the replies of your users to this address will never be processed, so you need to change it to your custom address for two-way communication.
2. On the Project details page. This setting influences only communication with Requesters. Please check and modify Reply Email property if you would like to have different mailboxes for different Projects. Otherwise you can leave the field Reply Email blank - the default address from Email Notifications settings will be used. There are also few other conditions that should be satisfied in this case (process notifications should be disabled for requesters in this project's Process and checkbox "Notify Requesters" should be ticked while adding a new comment)

Every outgoing email generated by Targetprocess has the line

--- Please do not remove this line! CompanyName Ticket#123 ---

in the bottom. It is important to keep the line when you post a reply back to Targetprocess. The Plugin searches for this line and adds a comment to the relevant Targetprocess entity when the line and the entity are found.

Troubleshooting

You should set up a unique profile for every mailbox. In the meantime it is non-recommended to set up two profiles connected to the same inbox because otherwise concurrent access issues can be observed and no requests and comments will be created.

• Why do I get “Not creating request” message in the Email Plugin log?

IMAP email integration is downloading all emails from root Inbox folder. Other folders are not checked by plugin.

If your Inbox has many emails inside, then initial IMAP synchronization may take up to several hours to download all of them. Further regular checks should work fast.