Basic Setup

This page walks through setting up a basic mail2bug instance
The focus is on getting you up and running quickly, skipping over advanced features. For full config file reference, see the Config file reference

Prerequisites

• An exchange mailbox to be used as the end-point for receiving emails
  • Requires Exchange 2010 SP1 or later
  • EWS access must be enabled
  • Credentials for accessing the mailbox
• A user with permissions to read, create, and update work items in the target TFS project
• A windows machine to run the service on
  • Needs .NET framework 4.5 or later installed
• The project binaries - see the project ReadMe.md (on the project home page) for instructions on how to build it

Setting up the new service

• Create a folder for the Service
• Copy all the files from <project root>\Tolls\DpapiTool\Bin\<Debug|Release>\* to the service folder
• Copy all the files from <project root>\Mail2Bug\Bin\<Debug|Release>\* to the service folder (override any existing files)
• Create a sub-folder called Resources under the service folder - this folder will hold all the configuration files for the mail2bug instances
  • Of course, you can use any other folder name
• Create a config file for your instance in the Resources folder
  • Follow the filename pattern Mail2BugConfigMyInstanceName**.xml**
    • This pattern is configurable, but we'll use it for simplicity, since it aligns with the default values in the app.config
  • See more details on creating the config below
• Create the protected password file under the Resources directory, and use it in your config file as needed
  • To create the protected password file, use DpapiTool.exe
  • Make sure to run it under the same credentials that mail2bug.exe will run with
  • The commandline is DpapiTool.exe write /Data=<password> /Out=password.bin
• Set up some basic rules in Exchange
  • IMPORTANT: This rules need to be server side rules, since you don't want to rely on Outlook running on some machines to apply them
  • Rule 1: Delete all incoming emails from "self" (i.e. from the email address used as the end-point)
    • Since mail2bug will be replying to emails for which it creates a new work item, you want to avoid processing those emails
  • Rules 2: Set a retention policy of 1 week for every incoming email
    • This will delete emails automatically after a week, even if they were not processed, so that you don't have to constantly clean up the mailbox
    • This should be done for standard set-ups, but if for some reason you need to retain items for longer, you may want to skip this rule or set the retention policy to be longer

Configuration

• Use the configuration example given in the Documentation folder of the project as a basis - Mail2BugConfigExample.xml
• The 'InstanceConfig' node is the one that defines the configuration for your service instance
  • The 'Instances' node can contain multiple 'InstanceConfig' elements inside it, and all these instances would run in the same process. This allows mail2bug to scale to serving many instances on a single server (it's been tested with 50+ active instances processing hundreds of emails on a daily basis, with a very minor memory footprint and negligible CPU usage). For more details and advice on setting up multiple instances, see Setting up multiple instances on a single server
• Instance Name - used for logging purposes. Pick a name of your liking.
• TfsServerConfig node - contains the details required for connecting to your TFS server and creating items:
  • CollectionUri - The TFS collection URL for your TFS server. Examples:
    • http://server:8080/tfs/YourColllection/ (on-prem)
    • https://name.visualstudio.com/DefaultCollection/ (VS Online)
  • Project - Your TFS project name
  • WorkItemTemplate - The type of work item that you would like to create from email threads
    • Most commonly this is set to 'Bug'
  • CacheQueryFile - The path to a file containing the query to be used for populating the work-item cache. If a work item is not captured by the query, new messages on the thread that created the item would create a new item instead of appending to the existing one. The standard set up is to provide a query that pulls all the items created by the mail2bug service account (regardless of state).
    • To create the query file, just create the query in a visual studio and save it locally to a file. Place the file where the other configuration files are and put the path to that file in the CacheQueryFile setting.
  • SimulationMode - set to 'false'
  • NamesListFieldName - set this value to "Assigned To"
    • Should be the name of a field that contains all the valid user names - if for some reason "Assigned To" is not the right field for your instance, replace this value with the correct one
• 'WorkItemSettings' node - This is where you set the rules governing how work items are created
  • 'ConversationIndexFieldName' - contains the name of the field that will contain the email conversation index.
    • The conversation ID is how mail2bug correlates email threads and work items
    • Text field - with capacity for 200 characters or more (conversation IDs can get pretty long for long email threads)
      • You can use lower capacity fields, but if the conversation ID is longer than the capacity, it won't be properly saved and you'll likely get duplicate work items for replies, instead of getting them to add a comment on an existing work item.
  • DefaultFieldValues - this is where you set the default values to be assigned for fields when a new work item is created
    • It's a list of DefaultValueDefinition elements
    • Each such element has a Field attribute and a Value attributes - you set the Field attribute to the name of the field, and the Value attribute to the desired default value
    • It's important to set defaults for all mandatory fields, otherwise work-item creation would fail
  • For this basic setup, ignore the 'Mnemonics' and 'DateBasedOverrides' nodes and remove them from the config file. More details on these nodes and how to use them in the Config file reference page
• EmailSettings node - contains settings related to accessing the email account and processing individual emails
  • ServiceType - set to EWSByRecipient
  • Recipients - leave the value blank
    • If you want to process only incoming messages with a specific email address (or display name) in the To or CC lines, put that address as the value of recipients (multiple addresses can be used, separated by ';').
  • EWSMailboxAddress - the email address to monitor for incoming emails, e.g. abc@def.com
  • EWSUsername - the username to use for logging into the email address. Set it to be the same as EWSMailboxAddress
    • If you get failures to log in to EWS, try replacing it with a username of the form 'DOMAIN\username'
  • EWSPasswordFile - Path to the DPAPI encrypted file that contains the password that should be used for logging in - you've created this file in an earlier step
  • SendAckEmails - Should mail2bug send a reply when creating a new item. Recommended value: 'true'
  • AckEmailsRecipientsAll - Should the reply email be send to all recipients of the original message, or just the sender? 'true' means "Reply All", 'false' mans "Reply". Recommended value: 'true'
  • ReplyTemplate - HTML file containing a template for the reply email. [BUGID] and [TFSCollectionUri] in the template will be replaced with the ID of the work item that was created, and the URI to the TFS collection (useful for adding a link to the bug) respectively
  • AppendOnlyEmailTitleRegex, AppendOnlyEmailBodyRegex, and ExplicitOverridesRegex - for these elements, use the values from the sample config file

First run

Start a command prompt (cmd.exe/powershell) under the same user credentials as the ones with which the tool will be running. Change to the directory of mail2bug and run mail2bug.exe - monitor logs and results and troubleshoot accordingly (see also common errors with initial setup below).

Scheduled task

Create a scheduled task to run the tool (in windows task scheduler). Since the tool exits every X iterations (where X is configurable in the app.config), you'll need to make this task recurring. Recommended settings:

• Set it to run under the credentials of a user that has access to the TFS server (for on-prem TFS servers)
• Set the directory where Mail2Bug.exe is as the “start in” parameter
• Set it as a daily task starting at midnight and set it to repeat every 5 minutes
  • Set it such that if the previous instance has not finished running yet, it would wait for it to finish first, before starting a new instance (supported by windows task scheduler)
• Set the task to run even when no user is logged in

First run

Run the task manually (right click->run) and monitor the logs and results to ensure that all is working correctly. Use the logs to detect

Common errors/Troubleshooting

Common errors that happen upon the first setup:

• Can't connect to Exchange/EWS
  • This usually indicates a bad username or password - verify that both are correct
  • Is there an exception thrown when trying to read the password from the file - that means the file was created when running with user credentials different from the one use to run mail2bug
• Error when creating a new work item - usually the log would indicate that a specific field was invalid. Make sure the field has a valid default value.
• Error connecting to TFS
  • Verify that the collection URI is correct
  • Verify the login credentials are correct