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). [TBD - steps for creating the query file]
  • 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