-
Notifications
You must be signed in to change notification settings - Fork 108
Basic Setup
Guy Hershenbaum edited this page Mar 18, 2015
·
14 revisions
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
- 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
- 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
- Follow the filename pattern Mail2BugConfigMyInstanceName**.xml**
- 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
- 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
- CollectionUri - The TFS collection URL for your TFS server. Examples:
- 'WorkItemSettings' element
- 'EmailSettings' element