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

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' element - used for logging purposes. Pick a name of your liking.
• 'TfsServerConfig' element - 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). [TBD - steps for creating the query file]
  • SimulationMode - should be 'false'
  • NamesListFieldName - should be the name of the field that contains all the valid user names - usually points to the "Assigned To" field
• 'WorkItemSettings' element
• 'EmailSettings' element

Common errors