Inbound Email Integration via Plugin | Targetprocess - Visual management software

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.

How to set up Inbound Email Integration. Image 1

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+

How to set up Inbound Email Integration. Image 2

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

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 Helpdesk practice is listed below the Process name. Enable Helpdesk 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

  • What would be a single rule to setup an email integration for all emails which should be created as requests?
  • Setup only one default rule:
    then attach to project 283 and create request in project 283

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 Helpdesk practice is listed below the Process name. Enable Helpdesk 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.

Possible conditions
subject contains ‘keyword1, keyword2, …’Actions from “then” part will be performed if subject contains ANY of the listed keywords.

Keywords are case-insensitive.

Possible actions
create request in project 1234

create private request in project 1234

Private request will be created from email in this project #1234
create public request in project 1234Public request will be created from email in this project #1234
create request in project 1234 and attach request to team 567Private request will be created from email in this project #1234. Additionally, the request will be assigned to team #567.

The team should be assigned to the corresponding project in advance, otherwise the email processing error occurs.

create public request in project 1234 and attach request to team 567Public request will be created from email in this project #1234. Additionally, the request will be assigned to team #567.

The team should be assigned to the corresponding project in advance, otherwise the email processing error occurs.

 

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://www.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.

Possible conditions
company matched to project 1234actions from “then” part will be performed only if requester and project mentioned in “when” clause relate to the same company

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@targetprocess.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.

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.

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.

Still have a question?

We're here to help! Just contact our friendly support team

Find out more about our APIs, Plugins, Mashups and custom extensions. Join our community of passionate users and even discuss directly with our developers.