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 - This is where you set the rules governing how work items are created
  • 'ConversationIndexFieldName' element - 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 element - 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' element

Common errors