Fogbugz Documentation

Licensed Version: 8.8.46

Hosted Version: 8.9.10

  1. Installing or Upgrading FogBugz
    1. What are the system requirements for FogBugz 7 and 8?
    2. How do I back up my FogBugz installation?
  2. FogBugz in Two Minutes
    1. Projects and Areas
    2. Filters: Controlling which cases you view
      1. Adding a Search to a Filter
    3. Milestones: Manage your release schedule and coordinate your team
      1. Setting Up and Managing Milestones
    4. Statuses and Workflow
    5. Searching In FogBugz: Syntax and the search axis
    6. Adding Screen Shots to Cases
    7. Case Hierarchy: Parent cases and subcases
      1. Outlining Projects
    8. Reporting: Charts, graphs, and a historical view
    9. User Administration and User Accounts
      1. Authentication: LDAP, Active Directory, FogBugz Authentication
      2. User Notifications: Get alerts about FogBugz cases via email
        1. Troubleshooting Email Notifications
        2. RSS Feeds: Keeping tabs on Fogbugz via a feed aggregator
    10. FogBugz Groups and Permissions
      1. How are Groups used to assign permissions in FogBugz?
    11. The Admin Dashboard
    12. Compiling Release Notes
    13. Troubleshooting FogBugz Slow Performance
    14. Keyboard Shortcuts
  3. Handling Incoming Customer Email
    1. Using FogBugz to check POP3 and IMAP mailboxes
      1. Automatic replies to incoming emails
    2. Snippets for Fast Responses and Templating
    3. Removing Spam from your Inbox with Autosort
      1. The Autosort Bayesian Filter
      2. Best Practices for Using Autosort
    4. Public Access to Email Cases
  4. The FogBugz Wiki
    1. New Wiki Features
    2. Exporting Wiki Articles
    3. Associating a Wiki with a Project
  5. Source Code Control System Integration
    1. Integrating with Subversion
      1. Entering case numbers in Subversion
      2. Troubleshooting Subversion Integration
    2. Setting up TortoiseSVN Source Control Integration
      1. How can we enter case numbers using TortoiseSVN?
    3. CVS Source Control Integration
      1. Entering case numbers in CVS
    4. Perforce Source Control Integration
      1. Entering case numbers in Perforce
    5. Visual SourceSafe Integration
      1. Entering case numbers in Visual SourceSafe
    6. SourceGear Vault Integration
    7. Mercurial Integration
      1. Entering case numbers using Kiln and/or Mercurial
    8. Team Foundation Server Integration
      1. Entering case numbers using Team Foundation Server
    9. Generic Integration Instructions for Other Source Code Control Systems
  6. BugzScout to Capture Errors
  7. Evidenced-Based Scheduling (EBS)
    1. How to Estimate Software Tasks
    2. Site Working Schedule and individual Working Schedules
  8. The FogBugz XML API
  9. The FogBugz Database Format (Schema)
  10. FogBugz Plugins
    1. Custom Fields: Track your own case attributes.
    2. Customizing your FogBugz install with BugMonkey
    3. Notify: Notify users of changes to cases
    4. URL Trigger: Integrate with virtually any outside system
    5. Subscribe to All Cases in a Project or Area
    6. Broadcast Email
    7. What is the Kanban plugin for, and how do I use it?
  11. Discussion Groups
  12. Starting on FogBugz On Demand and Moving to Your Server
    1. SQL Server: Importing data from FogBugz On Demand or trial into SQL Server
    2. MySQL: Importing data from On Demand or trial
    3. On Demand Billing FAQ

Installing or Upgrading FogBugz

Installing FogBugz is very simple, and there's not much difference between an install and an upgrade. In fact, if an upgrade goes wrong, you can just do a new install pointed at your old database:

  • Check out the FogBugz 8 System Requirements
  • Download the installer from https://shop.fogcreek.com/FogBugz/
  • If you have a current FogBugz database, back it up. Everything FogBugz needs to run is contained in the database. If you don't have a FogBugz database, it will be created for you in the install process.
  • Run the installer and go through the steps.

If you're upgrading and anything goes wrong, you can always unhook the FogBugz web site, delete the FogBugz directory, and do a completely new install of the product. During the new install, you'll be given the opportunity to select the FogBugz web site, and direct the installer to the FogBugz database.

If you are having trouble connecting to your FogBugz database through the installer, you can just have it create a new database and connect to your database by editing the connection string later.




What are the system requirements for FogBugz 7 and 8?

FogBugz System Requirements
Hardware/VM Requirements

2GB RAM minimum. 4GB RAM preferred.

We've never encountered an install that needed a beefier processor. It's very likely that, if you have enough RAM, whatever processor you have is fast enough. Naturally, if you've upgraded a horrendously old machine with a bunch of RAM, there's a limit.

Operating Systems
What we run:

For FogBugz On Demand, our web servers are all Windows Server 2003 64-bit.

Windows

Windows editions and versions we test on

  • Windows 2003 32 Bit Version 5.2.3790
  • Windows Server 2003 64 Bit Version 5.2.3790
  • Windows 2k8 R2 64 Bit Version 6.1.7600

Additional Windows versions and editions we support:

  • Windows Server 2003 Standard/Enterprise/Datacenter Edition

Unsupported but known to have worked:

  • Windows Small Business Server 2003/2008 (with caveats)
  • Windows XP 32 Bit Version 5.1.2600
  • Vista 32 Bit Version 6.0.6000
  • Vista 64 bit 6.0.6001
  • Windows XP 64 Bit 5.2.3790
  • Windows 7 64 Bit 6.1.7600

Unsupported Windows editions:

  • Windows Server 2003/2008 Web Edition
Linux

We test on the last two server releases of:

  • Ubuntu LTS (10.04 & 12.04, 32 Bit)
  • RHEL (5 & 6, 32 Bit)
  • Fedora (16 & 17, 32 Bit)
  • CentOS (5.8 & 6.2, 32 & 64 Bit)
  • Debian (5 & 6, 32 Bit)

Note: GDI+ must be installed in order for users to upload profile pictures. Please read Profile Pictures on Linux / Unix for additional details.

Additional versions and distros we support:

  • Many prior versions of the above distros will work, but we do not have a comprehensive list.
Web Server

On Windows servers, FogBugz requires IIS 6 or 7 with ASP.NET and .NET 2.0.

Databases

Please note that you should have a fair amount of experience in your chosen database system to run FogBugz. It can certainly run with no problems for years, but FogBugz has a way of becoming central to the work of a team, and a failed/corrupted database should be something you can handle, because it can happen.

What we run:

For FogBugz On Demand, our database servers run both Windows Server 2003 64-bit and Windows Server 2008 R2 64-bit. The servers run SQL Server 2005 if they're on Windows Server 2003, and they run SQL Server 2008 R2 if they're on Windows Server 2008 R2.

Microsoft SQL Server

Make sure you're shrinking your transaction logs.

Versions we test on:

  • Microsoft SQL Server 2005
  • Microsoft SQL Server 2008
  • Microsoft SQL Server 2008 R2
  • Microsoft SQL Server 2012

Minimum Version:

Microsoft SQL Server 2005 (Express versions are supported, but note that they have database size and memory usage limits)

Not supported:

Support for SQL Server 2000 only extends as far as FogBugz 7.1.16.

MySQL

Here's a list of gotchas you might want to review if running MySQL. We also have a sample my.cnf for MySQL 5.1 (with some restrictions).

Minimum version:

Community 5.0.45

FogBugz 7.3.9 can only be run on MySQL versions between 5.0.45-community and 5.1.59-community. You can find older MySQL versions than the current GA release (5.1.58 as of this writing) here.

Versions we test on:

  • 5.0.77
  • 5.0.41a
  • 5.0.95
  • 5.1.41
  • 5.1.61
  • 5.1.63
  • 5.5.24

Additional supported versions:

5.5 (FogBugz 8 only)

Access

Official support of Microsoft Access databases was discontinued as of FogBugz 7.3.6, and the option is entirely removed in later versions. Use of MS-SQL's database import tools is not encouraged as it can lead to unexpected results. The recommended conversion technique is to use Easy From's ESF Database Migration Toolkit to convert from Access to SQL Server, and is quite easy, so we strongly recommend doing so! MS has also released a general purpose server migration page to help you migrate data between databases, which should eventually point you to the Microsoft SQL Server Migration Assistant for Access. This has not been tested extensively, but it is an alternative to the ESF Migration tool.

Effective Limits
Disk Space

The bulk of the size of the FogBugz database is made up of email events and attachments (usually from incoming email, not from files attached from the FogBugz interface). If you are not corresponding with a user base that's likely to submit large attachments, it's very unlikely that you'll amass 1GB per year of usage.

Responsiveness

Our internal FogBugz installation has sub-second response times for page loads and wiki edits, with a 150GB SQL Server 2005 database. Searches currently take significantly longer, but we're working on search improvements.

We've seen intermittent issues with running MySQL databases in the 30-50GB range, but by the same token we have many clients running MySQL with larger databases than this. If you're going to run FogBugz against MySQL, especially with large attachments coming in via email, it's recommended that you have significant experience with MySQL administration and tuning.

Browsers

See "What web browsers does FogBugz support?".

Number of Users

There are still practical limits on the scale of an installation, particularly around user administration. We have plenty of happy customers at the 250+ user level, but they're happy because they've let us help them understand the trade-offs involved in using a team-focused solution at that scale.

See Also



How do I back up my FogBugz installation?

FogBugz stores all the data it needs to run in the FogBugz database. If you've backed up this database, you've backed up FogBugz. Here's instructions on how to back up that database depending on how you have FogBugz installed and what type of database you are using.

FogBugz On Demand

If you are using FogBugz On Demand, there is no need for you to back up your database. We are constantly taking snapshots of your database and shipping them to our other data centers in case of a catastrophe. We are also taking nightly backups. You can read more about our FogBugz On Demand Infrastructure on our website. If you still need to grab a backup for testing purposes, or reporting purposes, you can do so by going to Settings->Your FogBugz On Demand Account. You'll find a link there which allows you to download your database.

Microsoft SQL Server

Microsoft has a knowledge base article on how to back up your SQL Server database. You can find the physical server your database is on by looking under Admin->Site->Database tab in FogBugz. Make sure that every time you do a backup you are shrinking the transaction logs to keep them small.

MySQL

MySQL has a knowledge base article on how to back up your MySQL database. You can find the physical server your database is on by looking under Admin->Site->Database tab in FogBugz.




FogBugz in Two Minutes

Okay!

"FogBugz in Two Minutes"

FogBugz is a complete project management system optimized for software teams. It helps teams work together by tracking, prioritizing, and coordinating the thousands of small tasks a development team has to do. You access FogBugz through a web browser.

alt text

FogBugz includes:

  • A database of cases, to track bugs, features, and inquiries
  • A wiki, for all your technical documentation
  • Discussion groups

Out-of-the-box, FogBugz tracks four kinds of cases:

  • alt text Bugs: things which don't work right
  • alt text Features: new things being planned
  • alt text Inquiries: questions, including email from customers
  • alt text Schedule items: buffers, debugging, beta tests, meetings, etc.

(You can also use the Workflow Plugin to create your own custom categories.)

Every case is prioritized, sorted, and assigned to exactly one person on your team who must either resolve it or assign it to someone else. Developers work through their cases one by one, in order of priority.

alt text

Where do cases come from?

A case can be entered by someone on your team or by an outside customer. It can be submitted via the web or through email. Email inquiries can be automatically sorted into areas. A case can be entered automatically from running software in the field via a web service. For example, if your software crashes, it can upload details of the crash to FogBugz. A handy screenshot tool that runs on the desktop lets you submit a picture of a bug to FogBugz with just two clicks. FogBugz provides web-based discussion groups for your customers, so that when a customer finds a bug or brings up a feature request, you can create a new case for it with a single click.

Slicing and dicing

The FogBugz filter feature and advanced full-text search make it easy to sort and search. You can constantly re-prioritize and reassign cases, making it easy to track your project. You can even automatically generate release notes for cases included in one or more project milestones.

alt text

Schedules

Developers can enter estimates for their cases and then tell FogBugz what they're working on. FogBugz combines this information to show a detailed schedule of upcoming milestones including the probability of completing work on any given date.

Using a sophisticated statistical technique we developed called Evidence-Based Scheduling, FogBugz displays a probability curve of completion dates that considers developer estimation history, team work schedules, and project dependencies. It will also show you how the predicted completion date has changed over time, and it will show you each developer's ship dates graphically so you can find bottlenecks.

alt text

Users seeking the familiar Burn Down Chart will find it in FogBugz as well.

Documentation

FogBugz includes a wiki: an easy-to-use documentation system. You can edit any document right in your browser: the FogBugz wiki includes a web-based WYSIWYG editor. It includes rich formatting features, a built-in spell checker, and user-customizable style sheets. FogBugz doesn't require you to learn special markup or codes, so anyone can edit articles.

alt text

A complete record of every change is always maintained so that you can undo mistakes. You can review the history of any article and see what changes were made over time in a side-by-side comparison.

The wiki is fully integrated with FogBugz, allowing you to keep all your developer documentation, feature specifications, technical specifications, and end-user documentation in one place, for example, it's trivial to link features on the schedule to their specs.

Customer email

FogBugz lets your team collaboratively handle a public email address (like support@example.com). When an email message comes in, Bayesian filtering discards any spam, and the remaining messages are sorted into areas, based on your training. Anyone on the team can reply to email and instantly see the entire history of the email conversation with a given customer.

alt text

Customers get an automatic email reply with a URL they can click to check the status of their inquiry. When a customer asks a common question, you can reply with a canned snippet instantly. When a customer reports a bug, via email or on a discussion group, it can easily be assigned to a developer to fix and be tracked just like any other bug. You can assign due dates and receive escalation reports to make sure customers receive timely responses.

Source code integration

Source code integration makes it easy to see which check-ins were associated with which bugs or features, and allows you to set up an elegant online code review system.




Projects and Areas

Each installation of FogBugz can be used to keep track of multiple projects. On typical software teams, you might set up a project for every individual product that you develop.

Within each project, you can divide cases into areas. For example, you might have separate areas for the code and the documentation.

An administrator can create and edit projects and areas by clicking on Admin | Projects. Administrators can also determine which users can view, create and edit cases within a project with permissions

Each project has a primary contact. The primary contact is the person whom you've designated to look at cases and assign them to the appropriate person to fix. When someone enters a new case, they usually leave it assigned to the primary contact. (In FogBugz every case is always assigned to one person, so that no case can fall through the cracks.)

If desired, you can also set up different primary contacts for each area.

If you are working on a large project team, you may want to have several people who help sort through new cases. To do this, we suggest that you set up a virtual user account called "Up For Grabs" and make that the primary contact of the project. You can use as many email addresses as you want for Up For Grabs, separated by commas, so that a group of people receive an email notification whenever there's a new bug in a particular project. Anyone who wants to help sort through new bugs can create a saved filter on "all cases assigned to Up For Grabs" which they check occasionally, or you can create this filter as a shared filter so that all users can see it.

Choosing Good Areas

In general you'll find that the fewer areas you have, the more likely people are to categorize cases correctly into the right area. Think of it this way: if you have 100 areas, everybody who enters a case is going to have to consider each of those 100 areas to decide which area is the best fit. Inevitably, cases will be miscategorized, and the pain of choosing an area may even make people enter fewer cases. If it's easier to jot down a case than enter it into FogBugz, you're going to lose the benefit of bug tracking.

Our recommended approach is to start with just one area, called Miscellaneous, and use it for everything.

Then, add areas only after careful considerationand only if they are needed for a particular filter that you want to create. For example, if you have a team of technical writers and they want to be able to see all the bugs in the documentation, create an area called Documentation.

Don't create more areas than you absolutely need, because the more you have, the more likely cases will be misfiled. If you need finer categorization, use tags. You can also group cases into hierarchies with subcases.

Public Projects

You can set a project to allow public submissions.




Filters: Controlling which cases you view

When you click List in FogBugz, you don't see every single case in the system: you only see cases that match your current filter.

alt text

Your filter is remembered until you change it, even when you log on from another computer or browser.

To see fewer cases, you can refine a filter, adding a criterion, by clicking on the name of the filter:

alt text

You can also search within filters by expanding the "Search for" option.

To change or remove a criterion, click on the underlined term:

alt text

Five filter controls are always available.

  1. The Save Filter control lets you save a filter with a name. After you have saved it, it appears in the Filters menu at the top of the screen. FogBugz administrators can share their saved filters.
  2. The Select Columns control determines which columns appear in the current filter.
  3. The Outline View / Flat View control determines if subcases are displayed within a case heirarchy or alongside all other cases in a flat list.
  4. The View control switches back and forth between the default outline view, which displays cases and subcases in a hierarchical outline, and the familiar flat view, which displays cases and subcases in a flat list.
  5. The RSS Feed control (available in the More drop-down menu) provides a link to an RSS feed for the current filter which you can use in your RSS aggregator. RSS feeds are only available when you have saved the filter.
  6. The Permanent Link control (also available in the More drop-down menu) reloads the page with a URL that fully describes the current filter in the querystring. This allows you to provide another user with a link to the exact same filter.

alt text

When you are looking at a list of cases in grid view, you can:

  • Rearrange columns, by dragging the column header left and right.
  • Sort by a column by clicking on the column header; reverse sort by clicking it again. Tip: To sort by two or three terms, click the column headers in reverse order. For example, to sort by area first, and by priority within each area, click on the Priority header and then the Area header.
  • Change the width of a column by dragging the thin gray separator between two column headers.
  • Autosize a column to the minimum width necessary to show everything, by double-clicking on the thin gray separator to the right of the column header.

Saving a filter also saves which columns are selected, and the sort order.




Adding a Search to a Filter

For a given filter, just click on the Refine Further: menu to bring up the dropdown, then select the Search for item and add any search you want.

Search for




Milestones: Manage your release schedule and coordinate your team

Just looking for the basics? See this post (in progress as of this writing)


Like many FogBugz features, you can use this feature in several ways (likely ways we haven't even considered, yet). That being said, there are two main methods we see people using:

Like You're Building a House, but Digitially

Use milestones as markers for... well, milestones: Big, specific, achievable goals. Depending on your release cycle and style, you may have start and completion dates for these goals. I recommend setting a completion date at least to get the most advantage from EBS.

When you're creating these milestones, remember that you're grouping a set of cases that apply toward a common goal. It's a delicate balance that ties back to how you break down work in the first place. That discussion is far beyond the scope of this post, but suffice to say that if you have a case that fits into two milestones, then either your milestones are too small in scope, or the case is too large in scope.

One solution to this problem is to break that case into subcases that fall in different milestones. The parent case can then go into a milestone like "30,000 Foot View". These cases don't have any work, and only inherit summed estimates from the children. Once all the children are done, they get closed without ceremony... But it does keep everything organized! That milestone should never have a start or end date to it (because it isn't really a goal in and of itself).

By the end of this process, you end up with several milestones that probably have somewhat disparate completion dates. Each milestone has a unique collection of cases which, when completed, whatever the goal of this milestone was will also be completed. As you put estimates into cases and complete them, your EBS should give you an accurate picture of how these milestones are doing.

Now You're Thinking in Sprints

This is the sprint-based workflow, typically some form of Agile/Scrum. Now, milestones aren't (necessarily) specific goals or objectives in your product's creation. Instead, milestones reflect periods of time (typically two weeks long) which has a goal in itself: Complete all of the cases assigned to that sprint. Maybe those cases get you to a new plateau... but maybe not. It doesn't matter: You have two weeks of work to do, here's when you start, and here's when you end.

You start thinking about milestones in the middle of this process. You've already created the cases necessary to complete the project (or at least a few sprints worth), applied estimates, broken into subcases, and then thrown them into a backlog that roughly approximates the order you want them done in. Now all you need to do is decide how much work your team can actually do in two weeks. Let's say you have 5 devs who will always give you exactly 8 hours of work per day because they're robots or... magic? I guess? In any event, you can confidently complete 400 hours of work every two weeks.

You create a milestone for "Sprint 1", give it a start and end date, then put 400 hours worth of cases into that milestone. Your developers divide up the work, and have at it. While they do that, you line up the next few sprints. After a couple sprints, EBS should be accurately predicting how good or bad the situation will be based on how good or bad you're proving to be at estimating those hours in the first place.

But Wait, What's the Deal with Global Milestones?

First, if you find yourself in a position where you have a case that needs to be in two projects, think very carefully about whether you've gone wrong in how you structured your projects. This kind of thing happens, but it shouldn't happen often. Maybe a translation project is in order?

Now that you're sure you're doing the right thing: Global milestones are milestones which can take cases from all projects. A case can still be a member of only a single project and only a single milestone, but you can have a single milestone that encompasses cases from more than one project. How does this fit in with the above?

With a sprint-based workflow, this is incredibly easy: They are cases in a sprint. Just do them and everything will work out. No need to be fancy, here! Maybe you had to temporarily join two teams to work one sprint... no big deal, just do that. The beauty of the sprint-based workflow is that this just works. But I submit it should be rare you need these global milestones or they're going to be regular and predictable like "Build Week Sprint" to finish up several projects at once and get them out the door.

If you're building a house, this takes a little more thought. Why are two of your houses interacting? You have cases in two projects that need to be grouped as part of a single goal. It's one thing to have parallel constructions and releases, but for that you should have two regular milestones with the same completion date. A global milestone in this context means that you have a goal that spans two projects in such a way that one project completing their work would be meaningless without the other project doing the same.




Setting Up and Managing Milestones

For each feature in FogBugz, you have to decide when you want to implement it. Similarly, for each bug, you have to decide when it's going to be fixed.

In FogBugz this is done by assigning the case to a particular milestone.

alt text

For example, a milestone could represent each major version of your software, whatever numbering scheme you use: 1.0, 2.0, etc.

(Or, if you're insane, you can use a simple and obvious numbering system like 1.0, 2.0, 286, 386, 3.0, 3.1, 3.11, 95, 98, 98SE, Me, XP, ...)

You can also use milestones to track minor versions (Alpha, Beta 1, Beta 2, Release Candidate, Gold Release, Service Pack 1, etc.) or checkpoints in the code development process ( "Search feature code complete" or "Performance work and optimizations").

When a certain milestone is coming up, you can create a filter to see all the features and bugs that need to be fixed for that milestone.

To edit milestones in a particular project, you have to either be a site or project administrator. From the Admin menu, choose Projects. Click on the project name and scroll down where you'll see a section marked Milestones (this project).

alt text

Each milestone has a date; for example, the 2.0 alpha release might be planned for 6/4/2007. You can move the date at will (although your management may be less flexible than FogBugz about changing dates!)

Note that your "official" dates that you enter for a milestone are not the same as the dates that FogBugz will calculate later using Evidence-Based Scheduling. As far as EBS is concerned, the only thing that matters about official dates is their order. It will assume that you're going to do all the "search feature milestone" stuff before you do any of the "alpha" stuff because it comes first, officially. But EBS will have it's own opinions of when you're going to finish, based on your estimates, not based on the official date.

When you fix a bug or implement a new feature, before you resolve the case, double check that the milestone is correct; that way it can also be used as an historical record of which bugs were fixed in which milestone, and which new features were implemented for which milestone.

FogBugz also lets you maintain and create Release Notes automatically.

You can also create meaningful milestones without dates.

Although milestones are normally per-project, you can also create milestones that can be used for any project. FogBugz ships with "Undecided" as a useful default milestone. You may also want to add "ASAP" or "Never". To edit these global milestones, go to the Admin menu and choose Projects. Click on any project name and scroll down where you'll see a section marked "Milestones (all projects)."

After all work for a milestone has already been completed, it doesn't make any sense to assign new cases to it. You should set the "Assignable" field of the milestone to "No" to prevent new cases being assigned to a completed milestone, which also makes the "Milestone" dropdown shorter so it's easier to enter new cases. We make this a manual setting, rather than making milestones become unassignable automatically, because the last thing you need to worry about during crunch time is why a milestones has suddenly disappeared from your dropdowns.




Statuses and Workflow

Statuses

The basic statuses in FogBugz come in two flavors, Active and Resolved. By default, there is only one active status for each type of case, but if you need more active statuses, like Needing Replication to your instance, you can do so via Admin > Workflow

Resolved statuses differ per category. A bug will be marked Resolved (Won't Fix) whereas a feature will be resolved Resolved (Won't Implement). Again, you can customize this via the Workflow admin menu.

Workflow

The basic workflow of FogBugz is that cases are created in projects, assigned to the default assignee for that project, remain active until fixed, and then are resolved back to the person who created the bug, who is responsible for verifying its resolution and closing the case.

This doesn't always fit the workflow of software organizations, where you might want a QA person to test. For this, you can set the default assignee for, say, the Bug status of Resolved (Fixed) to QA, while the default assignee for Resolved (Won't Fix) should stay as the opener of the case.

The Force option in the Workflow plug-in simply means that the assignee cannot be changed in the same step as the resolution. In keeping with FogBugz's general design principles, the assignee can be changed immediately after the forced step.

Complex Workflows

FogBugz allows for basically two steps of automated workflow: Active and Resolved. For more complex organizations, it is possible to set up scripts and customizations to approximate a case moving through multiple steps (legal, accounting, executive review, PR). But it's really not what the tool was designed for. For such complex and changeable processes, it's generally the better choice to use something more geared toward complex workflow (and likely much, much more expensive) or something more flexible like Trello.




Searching In FogBugz: Syntax and the search axis

FogBugz Search works pretty much as you expect: you type your search terms in the box, and click Search.

You can go directly to any case number by typing just a number. If you're actually searching for a number within your case text, just put it in quotation marks (e.g., "456").

Any search can be saved as a filter, either by clicking on the disk icon in the Search Tools box in the upper right corner of the results page, or from the Filters menu.

FogBugz will initially return a maximum of 45 case results or 10 wiki or discussion group results, sorted by relevance, with a link to "List all" to see the rest of the results.

FogBugz also supports advanced search queries.

  • apple peach searches for items containing both apple and peach
  • apple OR peach searches for items containing either apple or peach
  • "apple peach" searches for items containing the phrase apple peach
  • apple -peach searches for items containing apple but not containing peach
  • pear* Searches for items containing words that start with pear. Can take a long time.

Note that FogBugz search uses stemming, not exact matches. For example: searching for hiking will find cases containing hike, hiking and hiker. If you see unexpected search results, take a look at this post.

When your search phrase contains quotation marks, you can deal with them in two ways:

  • Use single quotes around double quotes, e.g. openedby:'Joel "The Bossman" Spolsky'
  • Escape the quotation marks with backslashes, e.g. openedby:"Joel \"The Bossman\" Spolsky"
Searching specific fields with axes

Use axis:query to search specific fields. title:pear will find everything with the word pear in the title. You can negate an axis as well: -title:pear will find everything without the word pear in the title.

You can also combine axes with Boolean queries and parentheses. newfeature (assignedto:Tester1 OR assignedto:Tester2) (resolvedby:Developer1 OR resolvedby:Developer2) will return all cases that mention newfeature that have been resolved by either Developer1 or Developer2 that are currently assigned to Tester1 or Tester2.

Note that OR has a lower priority than the implied AND, so assignedto:Tester1 OR assignedto:Tester2 resolvedby:Developer1 will return all cases assigned to Tester1 as well as cases that are both assigned to Tester2 and resolved by Developer1. To get the result of cases resolved by Developer1 that are assigned to Tester1 or Tester2, use parentheses: (assignedto:Tester1 OR assignedto:Tester2) resolvedby:Developer1

Combining action: and actionby: axes (e.g. edited/editedby, or opened/openedby) has a special behavior, where the FogBugz searcher links the two searches. For instance, in the case of editedby:me edited:today, FogBugz will return only cases that I edited today, rather than the strict intersection which would be the cases I edited at some point which were also edited by somebody (not necessarily me) today. If you want to search for a case edited by more than one person, please use the syntax of editedby:me alsoeditedby:michael.

Use the type axis to specify what type of documents you wish to search. type:case will search for cases, type:wiki will search for wiki pages, and type:discuss will search for discussion topics. If you use a search axis such as edited that applies to all types of documents, FogBugz will return a summary of search results organized by document type.

Axis search does a sub-string match on the query, so if you have two projects, "Widget Factory" and "Widget Distributor" and you search for project:Widget, you will get results for both projects. A notable exception is the title: axis, which uses stemming, just like search. While searching for Project:Roc will find cases in the Rocketship project (sub-string match), a search for Title:asdf will NOT find a case with the title asdfasdf because asdf is not a stem of asdfasdf (neither are real words or parts of words).

To search for an exact match, use the field's "ix" (ID) by using := instead of : as the operator. For example project:=1 finds cases in Sample Project. The exception to this is the tag axis, which does an exact match, so tag:foo matches "foo" but not "foobar".

Most axes also support * as a wildcard. See this post for caveats.

Dates

You can search dates (or date + times) and date ranges (use .. to indicate date ranges -- ... also works). When you have a decimal number in a range, include a leading zero, e.g. "0.5" instead of ".5" Here are some date search examples:

  • edited:"March 2007" everything modified during the month of March 2007
  • edited:"3/26/2007" everything modified on March 26, 2007
  • edited:"March 2007..June 2007" everything modified during the months of March through June in 2007
  • edited:"3-26-2007..6-8-2007" everything modified between March 26, 2007 and June 8, 2007, inclusive
  • edited:"5/6/2012 5:00pm..5/7/2012 9:00am" everything modified between May 5th at 5pm and 9am the next day
  • edited:"today" everything modified today
  • edited:"last Thursday" everything modified on the Thursday of the previous week
  • resolved:"last month" everything resolved in the previous calendar month
  • resolved:"this week" everything resolved between Sunday of the current week and today
  • resolved:"yesterday" everything resolved yesterday
  • due:"tomorrow" everything due tomorrow
  • due:"next week" everything due from next Sunday through the following Saturday

Date ranges can also be open-ended to indicate anything before, or after a date or date and time. For examples:

  • opened:"1/14/2011.." everything opened January 14th 2011 and later
  • due:"..10/10/2012 4:30pm" everything due before October 10th 2012 at 4:30pm (including cases due in the past)

As of FogBugz 7.1.11, you can also search for dates and times relative to the current time, too, using a special syntax of + or - a certain number of minutes, hours, days, or weeks, (m, h, d, w, respectively). This is shorthand for a date and time relative to the current exact time (which can be expressed as now). If the current date and time is 12/25/2009 8am, then "-3w" will translate to 12/4/2009 8am.

  • opened:"-3w..-1w" everything opened between 1 and 3 weeks ago
  • closed:"-30m..now" everything closed in the last 30 minutes
  • viewed:"-1d.." everything I've looked at in the last 24 hours
  • due:"..+3h" everything due in the next three hours
  • opened:"3/21/2007..-5d" everything opened between 3/21/2007 and 5 days ago
  • due:"now..today" everything due between now and the end of the day

Note that relative search times are not rounded. For instance, opened:"yesterday.." will show you everything opened from the beginning of yesterday up to the current moment, whereas opened:"-1d.." will show you everything opened in the last 24 hours, exactly.

+'s are implied, so due:"now..+5m" is equivalent to due:"now..5m".

..'s are not implied, so while edited:"-20m.." means "edited within the last 20 minutes", edited:"-20m" means "edited exactly 20 minutes ago".

Axes for searching cases

In general, an axis can be formed from the title of any column in the grid view by removing the spaces e.g. the "Assigned To" column becomes the "assignedto:" axis. To find out what possible values are available for a given axis, add the corresponding column to the grid view of a filter and see what values are listed.

  • AlsoEditedBy cases edited by the specified user, to be used in combination with EditedBy
  • Area cases in the specified area
  • AssignedTo cases assigned to the specified user
  • Attachment cases with an attachment with the specified name
  • Category cases with the specified category
  • Closed (date) cases closed on the date specified
  • ClosedBy cases last closed by the specified user
  • CommunityUser cases that were submitted by the specified community user
  • Computer cases containing specific text in the second custom field. Note that this field may have been renamed in your installation.
  • Correspondent cases with the specified email correspondent
  • CreatedBy cases created by the specified user
  • Department cases belonging to the specified department
  • Due (date) cases due on the date specified
  • Edited (date) cases modified on the date specified
  • EditedBy cases with a bug event generated by the specified user
  • ElapsedTime cases with the specified (range of) elapsed time
  • EstimateCurrent cases with the specified (range of) current estimate e.g. EstimateCurrent:"..2h" would show all cases with less than 2 hours of estimated work remaining.
  • EstimateOriginal cases with the specified (range of) original estimate
  • From cases with emails from the specified email address
  • ixBug case matching the case number specified. Can be used with OR to search for multiple cases, e.g. ixBug:"123" OR ixBug:"55" will return cases 123 and 55.
  • LastEdited (date) cases that were modified on the date specified and have not been modified since then
  • LastEditedBy cases last edited by the specified user
  • LastViewed (date) cases that you last viewed on the date specified
  • Milestone cases assigned to the specified milestone
  • Occurrences Number of occurrences for a BugzScout case
  • Opened (date) cases opened on the date specified
  • OpenedBy cases last opened or reopened by the specified user
  • OrderBy This takes another axis as its argument and sorts the search results by that axis e.g. "OrderBy:Milestone OrderBy:Priority" will sort the search results first by Milestone, and then by Priority. You can also reverse the order by using a negative sign and wrapping the whole term in quotes: OrderBy:"-Milestone" OrderBy:Priority
  • Outline returns cases in the same subcase hierarchy as the specfied case.
  • Parent returns all subcases of the specified case.
  • Root all cases in the hierarchy underneath the specified case.
  • Priority cases with the specified priority
  • Project cases in the specified project
  • ProjectGroup cases in the specified Project Group (from the ProjectGroups Plugin)
  • RelatedTo cases that are linked to the specified case
  • Release same as milestone
  • ReleaseNotes search for "ReleaseNotes:*" to see all cases with release notes
  • RemainingTime cases with the specified (range of) original estimate
  • Resolved (date) cases resolved on the date specified
  • ResolvedBy cases last resolved by the specified user
  • Show cases with the specified attribute (Read, Unread, Subscribed or Spam)
  • StarredBy starredby:me shows cases you have starred.
  • Status cases with the specified status
  • Tag cases with the specified tag
  • Title cases containing the specified words in the title
  • To cases with email to the specified email address
  • Version cases containing specific text in the first custom field. Note that this field may have been renamed in your installation.
  • ViewedBy viewedby:me shows cases you have previously viewed.
Axes for searching wiki pages
  • Edited (date) wiki pages that were modified on the date specified
  • EditedBy wiki pages edited by the specified user
  • LastEdited (date) wiki pages that were modified on the date specified and have not been modified since then
  • LastEditedBy wiki pages last edited by the specified user
  • LastViewed (date) wiki pages that you last viewed on the date specified
  • Show wiki pages with the specified attribute (Read, Unread or Subscribed)
  • StarredBy starredby:me shows wiki pages you have starred.
  • Title Finds wiki pages containing the specified words in the title
  • ViewedBy viewedby:me shows wiki pages you have previously viewed.
  • Wiki wiki pages in the specified wiki
Axes for searching discussion topics
  • CreatedBy topics created by the specified user
  • DiscussionGroup topics in the specified discussion group
  • Edited (date) topics that were modified on the date specified
  • EditedBy topics edited by the specified user
  • LastEdited (date) topics modified on the date specified and which have not been modified since then
  • LastEditedBy topics last edited by the specified user
  • LastViewed (date) topics that you last viewed on the date specified
  • Opened (date) topics opened on the date specified
  • Show topics with the specified attribute (Read or Unread)
  • StarredBy starredby:me shows topics you have starred.
  • Title topics containing the specified words in the title
  • Type type:case for cases, type:wiki for wiki pages, type:discuss for discussion topics
  • ViewedBy viewedby:me shows topics you have previously viewed.
About the FogBugz Search Engine

For performance and search quality, FogBugz has its own full-text search engine, based on Apache's Lucene.NET.

FogBugz builds its index in the background, and updates it frequently. However:

  • Things entered into FogBugz very recently may not yet be indexed.
  • Building the index for the first time can take hours or days, depending on the size of your FogBugz database.

Go to Admin | Site and click on the Search tab to see the status of the index, and what percentage of your database is indexed.

On rare occasions when the index is not available or missing large amounts of data, FogBugz starts re-indexing with the most recently updated cases first, in an attempt to get the most relevant cases into the index as soon as possible.




Adding Screen Shots to Cases

Sometimes adding a screenshot showing a bug to your bug reports can save a lot of explanation. The FogBugz Screenshot tool runs on your Windows or Macintosh desktop. To install it, click on the Extras menu and choose Capture Screenshots. If it does not appear in your Extras menu, make sure you have at least one public project setup.

Note: Only logged-on FogBugz users are able to use the screenshot program. They need to be full users or community users.

When you download and install the FogBugz Screenshot program, a bug icon will appear on your screen.

Windows

alt text

When you click on the bug icon, it will capture the current screen.

Once you've captured a screenshot, you can crop it to make it smaller, or highlight a particular area with a red border to illustrate the exact part of the screen that represents the bug. Then you can send it to a new case or append the screenshot to an existing case.

Tip: By right clicking on the screenshot tool, a menu appears allowing you to enter a bug directly without capturing a screenshot. This is the fastest way to launch your browser and go to the New Case page.

To uninstall the FogBugz Screenshot tool: first quit the program by right clicking on the screenshot icon shown above and selecting Exit, then use the Add or Remove Programs feature in the Windows Control Panel.

Capturing a screenshot makes a camera shutter sound. To turn off this sound, click Sound:OFF in the bottom right corner of the Screenshot window.

To change the URL where screenshots are sent, click on the URL at the bottom of the screen. By default, this is set correctly, but if you use more than one bug tracking database, you'll have to adjust this. Use the basic URL of FogBugz, including http://, but without any file name. For example, http://www.example.com/FogBugz

Macintosh

alt text

When you click the bug icon, you will have a choice of capturing a window, a rectangle, or the whole screen. After capturing, you can highlight a particular area with a red border to illustrate the exact part of the screen that represents the bug. Then you can send it to a new case or append the screenshot to an existing case.

Capturing a screenshot makes a camera shutter sound. To turn off this sound, click Sound:OFF in the bottom right corner of the Screenshot window.

To change the URL where screenshots are sent, click on the URL at the bottom of the screen. By default, this is set correctly, but if you use more than one bug tracking database, you'll have to adjust this. Use the basic URL of FogBugz, including http:// or https://, but without any file name. For example, http://www.example.com/FogBugz




Case Hierarchy: Parent cases and subcases

Often, you want to break down a feature into a set of subfeatures, or, more generally, break down a task into smaller subtasks. FogBugz subcases allow you to do so quickly and easily.

Adding Subcases in the Grid View

While viewing a set of cases in the grid view, you can add a subcase to any case by selecting it and clicking the "Add Subcase" button at the bottom of the screen. (Alternatively, you can select the "Add Subcase" option in the context menu.)

alt text

Once the case is created, it appears indented below the parent case, in an "outline" format. You can make the outline as deep and detailed as you like by creating subcases of subcases, and so on. Cases matching the current filter are displayed in blue, while parents of cases matching the filter (but do not themselves match) are displayed in gray.

If you prefer not to see "outlines" in your case list, you can switch from "Outline View" to "Flat View" using the control on the upper right of the case list.

alt text

Adding Subcases in the Case View

You can also add subcases to a case in the case view by using the subcases field. You can find an existing case by title via auto-complete, or create a new case on the fly by entering a new title.

alt text

In the case view, you can also make the current case the subcase of another case by using the "parent" field.

Aggregating Estimates

It's usually best practice to create case outlines such that only cases without subcases (ie, the "bare tasks") require estimates. (You can, however, enter an estimate for a parent case.) The the grid view, the estimate of a parent case is displayed as a sum of its own estimate and all subcase estimates.

Resolving / Closing Subcases

When you resolve or close a case that contains subcases, FogBugz gives you the option to perform the same action on all subcases. To do so, simply click the checkbox below the "Resolve" or "Close" buttons.

alt text




Outlining Projects

You can use the case list's Outline View to quickly create a detailed work plan. Just start by clicking the Add Case link at the bottom of the list:

alt text

This reveals a control allowing you to select the case category (including any custom categories created using the Workflow Plugin) and enter a name for the new case.

alt text

The case you've just created can become the root of a complete case outline. Just use the context menu (or the Add Subcase button below the case list) to add a subcase:

alt text

alt text

alt text

alt text

You can add detail to your outline by adding subcases to subcases:

alt text

Once you've created your outline, you can assign cases to a new or existing project milestone:

alt text

...and assign cases to the developers on your team to spead the workload:

alt text

It's best if developers enter their own estimates. They can do so in the case view, or enter estimates right in the grid view by clicking on the case's entry in the Estimate column:

alt text

alt text

Once cases are estimated, you can check out FogBugz's Evidence-Based Scheduling (EBS) reports to make sure that the predicted completion date is sometime relatively soon:

alt text

As developers get started, they can use the Working On control to let FogBugz know they're getting started on a case, and can regularly check updated EBS estimates to make sure the project is on track.




Reporting: Charts, graphs, and a historical view

Reporting in FogBugz enables you to visualize the cases in any filter as a graphical chart or data table.

alt text

There are three types of reports: standard, time-based, and raw data summaries.

alt text

Standard Reports

Choose "Pie", "Bar" or "Column" from the Filter Type drop down on the left side of the filter bar. When viewing a Bar or Column report, you can change the report type between "Normal", "Stacked" and "100%" using the Chart Type drop down menu on the right side of the filter bar. Hovering your mouse over a section of a stacked report will show the section criteria and the number of cases within that section.

alt text

The reporting axis and breakdown can be changed using the drop down menus in the filter bar.

alt text

Time-Based Reports

Time-based reports are line graphs (either normal or stacked) that show changes to your data over time. Along with all of the features of standard reports, time-based reports include a menu to specify the time period that your report runs over.

alt text

Time based reports can show you the number of cases or the time estimated over time. If your filter includes cases without time estimates (and you're viewing a report by estimated time) you'll see an informational message letting you know that those cases are excluded from the report.

alt text

Raw Data Summaries

Sometimes you just want to see the numbers. You can do this by selecting "Table" from the Filter Type drop down on the left side of the filter bar. Summaries can be time-based as well.

alt text

Flexibility

The charts and tables have been designed with flexibility in mind. You can breakdown your reports by the count of cases, estimated time, time remaining or many other metrics. Through the use of plugins, reports can also be broken down by custom fields.




User Administration and User Accounts

There are four kinds of user account in FogBugz.

Normal

A normal FogBugz user. Normal users have access to cases, wikis, discussion groups and reports as determined by permissions.

Administrator

An administrator has permission to do anything in FogBugz:

  • Access the Admin menu and Admin Dashboard
  • Configure and add users, and change their passwords
  • Set up projects, areas, shared filters and snippets, and groups
  • Configure all FogBugz site settings and site working schedule
  • Customize each project's workflow
  • Add, remove and configure FogBugz plugins
  • Install new licenses

Administrators are notified of FogBugz errors as well as new versions available for download at the top of any page when they log in.

There is one built-in Administrator account that comes with the Licensed version of FogBugz (i.e., this paragraph does not apply to On Demand accounts). This account is free: for example, if you purchase licenses for 10 users, you can actually have 11 accounts. This account can be deleted if there is at least one other active administrator account. This account's properties (such as full name and email address) can be changed at any time. In addition, any other user can be promoted to administrator status.

Note: In addition to site-wide administrators, FogBugz also lets you designate any user as an administrator over a project. See Permissions.

Virtual

A virtual user can't log on and doesn't use up a license. Its pupose is to allow assigning of cases to a group of people instead of an individual. For example, you could create an "Up For Grabs" virtual user that serves as a sort of work queue and owns a case until someone assigns it to themselves. Give it all of the email addresses (comma separated) of the users you want notified when a case is assigned to create a notification list.

Community

Community users are free user accounts that allow you to partially open up your FogBugz install to the outside. Only wikis and discussion groups can be fully opened to community users. You can allow this type of user to submit cases on a project-by-project basis. This is not very different from submitting cases via email. They'll be able to see a list of their past cases and all email correspondence within the case. They will not be able to see internal edits or any case properties (other than open/closed) and the case title.

Community users can be added to groups, so you can restrict the visibility of a wiki or a discussion group to a subset of users.

Additionally, you can enable the Community Case List plugin, which will extend the access granted to a Community user and allow them to see a list and view all of the cases in a project which they have permissions on.

Administrators can configure users under Admin | Users. They can move a user between these four types, configure their settings and set their project, wiki and discussion group permissions (through the use of Groups).




Authentication: LDAP, Active Directory, FogBugz Authentication

Log On Method

FogBugz for your server allows you to choose two user authentication methods. FogBugz On Demand supports only FogBugz Authentication

FogBugz Authentication

FogBugz stores users' passwords in encrypted form, and checks them itself. You can have user names provided in a drop-down menu or require users to type them.

In low-security environments (a few users on a LAN, where FogBugz is not available on the Internet), you can set up FogBugz not to require passwords. This is provided for backwards compatibility and is not recommended.

LDAP / Active Directory Authentication

FogBugz checks users' passwords against an LDAP directory, such as Windows Active Directory or any other LDAP server. This allows users to use the same password to log on to FogBugz as they use for other purposes such as logging on to their workstation or email.

User accounts must still exist in FogBugz, identified by name and email address. When a user logs in, FogBugz checks that the user exists in the FogBugz database, and then checks the password against the matching name and email in the LDAP server. If you have existing accounts in FogBugz and you want to switch to LDAP, be sure that the names and email addresses in FogBugz exactly match the name and email info on the LDAP server.

Checking Allow LDAP to create new accounts automatically allows any user with a valid LDAP account to log on to FogBugz. The first time they log on, a FogBugz account is created for them. This is an easy way to get large teams setup with access to FogBugz. An administrator can later set individuals permissions via groups.

If you don't check Allow LDAP to create new accounts automatically, you must manually create new users in FogBugz. Make sure their full name and email address match exactly with the name and email info on the LDAP server. Those users will then be able to log on with their LDAP password.

LDAP Authentication is not available with FogBugz On Demand.

New User Control

Normally only administrators can create FogBugz accounts. This setting determines if anybody can create an account.

If set to "Anybody can create a community account", this will permit anyone who can access the FogBugz URL to create a community user. These users can only access designated wikis and discussion groups and do not use a license. New community users created in this way initially do not have read or write permissions in any groups. They will have access to any wiki or discussion group which is open to all community users. This option is only present if the Community Users feature is enabled (see blow).

Setting this to "Anybody can create a normal account" you will allow anyone who can access the FogBugz URL to make their own normal user account. Normal users do use licenses so generally this option is only used when your FogBugz server is secure inside a firewall and you have a large number of potential users in your organization. New normal users created in this way initially do not have read or write permissions in any groups and must be added explicitly by an administrator. If you are using LDAP Authentication, this option is not present. Instead, check the box Allow LDAP to create new accounts automatically.

Community Users

Allows community users to register to access wikis and discussion groups. Community users cannot use LDAP authentication. Even if normal users are set up for LDAP, community users will still use FogBugz Authentication.




User Notifications: Get alerts about FogBugz cases via email

Email notifications can be turned on or off by navigating to My Settings > Options.

Any time a case is assigned to you, or someone edits a case currently assigned to you, FogBugz generates an email notification. To keep from cluttering your inbox with redundant notifications, FogBugz does not notify you on actions you perform yourself.

You can also set up subscriptions to receive notifications for different types of cases, including cases that are not assigned to you. To learn more, check out this article.

Because filtering capability is so much more robust in email clients than it likely ever will be in FogBugz, we tend toward the more-is-more approach for notifications. These notifications are predictably structured, so they can be easily filtered by Outlook, Thunderbird, or Gmail. For instance, you can filter out all emails with A case which you opened has been resolved in the body and Inbox in the subject line.

If you're not getting email notifications, you can find a troubleshooting guide here.




Troubleshooting Email Notifications

If you are using FogBugz On Demand, do steps I-1, I-3 and III, then contact us.  This guide is meant for Licensed FogBugz.

You can use FogBugz to send email manually, and FogBugz will also send automatic email notifications when a bug is created or modified. This article will tell you how to troubleshoot this process in case email is not successfully being sent from FogBugz.

I. Specific to notification problems:
  1. Make sure you're assigning the bug to someone besides yourself.

    If you assign a bug to yourself you won't receive a notification of that (since you know what you just did). Look in the top right corner of the screen to see who you're logged on as.

  2. Check that the assignee has bug notification turned on.

    If you're logged on as the user in question, you can check this by clicking on Prefs in the menu.

  3. Alternately, any FogBugz administrator can control this setting for any user by clicking on Users in the menu and then clicking on the user's name.
II. Is the FogBugz Maintenance Service running? (Version 4.0 or greater)

Check the services control panel or your processes listing to make sure the FogBugz Maintenance service is running (on Windows this is a service, on Linux and Mac it's a daemon called fogbugzmaintd in FogBugz 6, a Mono process called heartbeat in FogBugz 7).  If it's running, restart it. If you have mail piled up in your MailQueue table in your database, it could be because this service just isn't running.

It connects to the "FogBugz URL" set in the site settings and hits heartbeat.asp.  This URL may no longer be set correctly because you moved the machine or changed its name.  For example, if your site settings say your FogBugz url is http://localhost, then the Maintenance service will connect to http://localhost/heartbeat.asp.  Double check that this URL is correct on your Site settings page and then make sure you hit OK to have FogBugz save that info (even if it looks correct already -- FogBugz may need to rewrite this to the registry and hitting OK will do this).  You can access that URL manually and refresh a few times to see if that sends a few messages.  If it returns "+", that means there are things left for the heartbeat to take care of.  If it returns "-", that means there is nothing left for the service to do.

III. Any spam filters?

Check that you don't have any spam filter programs on the recipient end that are trapping messages delivered by FogBugz. If you're only testing with email addresses at your company, try sending to an address at Gmail or Yahoo etc.

IV. Any antivirus or firewall programs interfering?

Check to see if you have Norton or McAfee or another antivirus or firewall or "Internet security" program running. These programs have email scanning features which will simply kill your emails from FogBugz. (This is true even if you have FogBugz set to simply use the default SMTP server in IIS.) Disable any such email scanning features. 

For example, in McAfee VirusScan it's called On-Delivery E-mail Scanner: 


In this screenshot you can also see Access Protection (highlighted). You will need to make sure this does not contain a policy preventing the sending of email, e.g. "Prevent mass mailing works from sending mail". These policies are intended to prevent spam from being sent, but you will need to make sure they do not prevent non-spam from being sent! Add FogBugzMaint.exe and DLLHOST.exe (a Windows process) to the "Excluded Processes" list.

V. Is the SMTP server set correctly within FogBugz?
  1. Log on as an administrator.
  2. Click on Site in the menu.
  3. Check the value for SMTP Server
  4. This should contain the Internet address of a standard mail server that is configured to accept mail from the FogBugz server.
  5. If your SMTP server uses SSL, make sure it is setup correctly according to this guide

Note: FogBugz does not provide its own SMTP server for delivering email. You can use any SMTP server that is set up for delivering email inside your company. If you do not already have one, Windows Internet Information Services (IIS) which is required for FogBugz has a built in SMTP server which you can turn on. Configuring and administering email servers is beyond the scope of this article.

VI. Is Relaying set correctly on the SMTP server?

If email sending only fails when you send to a domain that is not your domain, then relaying is probably not allowed on your SMTP server. This is often done as a security precaution so that spammers don't use your SMTP server to send out a million spam without you knowing.

Instructions for setting relaying in the IIS SMTP server: In the properties dialogue for the Default SMTP Server in IIS, go to the Access tab and click Relay. Make sure "Only the list below" is selected and make sure that the IP of your server appears in that list, i.e. that your web server (and FogBugz) is granted access to this SMTP server.

VII. Check that the SMTP server can be reached.
  1. From the computer where FogBugz is running, open a command prompt (choose Start, Run, type cmd, and click OK).
  2. Type ping followed by a space and the name of the SMTP server.
  3. If this works correctly, you will quickly see four lines that start with Reply from...
  4. If you see the message Unknown host, the SMTP server which you specified cannot be found. This could be because:
    • you typed the name incorrectly
    • the FogBugz computer does not have a reliable connection to a DNS (Internet domain name) server
    • the name is not listed with a DNS server.
  5. If you see the message Request timed out, the SMTP server which you specified cannot be reached. This could be because:
    • the SMTP server is off
    • the SMTP server refuses connections from the FogBugz server
    • there is no network route from the FogBugz server to the SMTP server.
VIII. Check that the FogBugz server is reverse-DNSable.

Most SMTP servers will try to reverse lookup the IP address of the FogBugz server when the FogBugz server connects to send email. Using DNS, they will try to lookup the numeric IP address of FogBugz (such as 192.168.0.1) to a name (such as FogBugzmachine.example.com). If this fails or takes too long, mail delivery will be impaired.

  1. From the computer where your SMTP server is running, open a command prompt.
    • If this is a Unix host, simply log on.
    • If this is a NT machine, choose Start, Run, type cmd, and click OK.
  2. Using the numeric IP address of the FogBugz machine, type

    nslookup 1.2.3.4

    This is asking the name resolution system to find out what computer has that numeric IP address.

  3. If you see the domain name of your FogBugz machine on the Name line, everything is OK. However, if you see an error message like "Non-existent host/domain," your FogBugz server is not reverse-DNSable. Contact the person who administers DNS on your network and make sure there is a reverse mapping for the FogBugz machine. (This is sometimes called "the in-addr.arpa" address.)

  4. Many SMTP servers will not accept mail from machines that are not reverse-DNSable.

  5. If the nslookup command takes more than a second to execute and then fails, it is likely that there is a connectivity problem between the SMTP machine and the DNS server such as a firewall. This will cause a delay every time you try to send mail with FogBugz. If you are experiencing 30 second - 1 minute delays every time you assign a bug in FogBugz, this is probably the cause.

IX. Check that you are not blocking ident traffic.

Some mail servers will attempt to connect to the ident port (113) of the mail sender to see who the mail is coming from. (More info) If the mail server is outside a firewall and the FogBugz server is inside a firewall, the mail server attempts to connect to port 113 on the FogBugz computer. If these packets are dropped by the firewall, the mail server will stall for a minute or so before it can deliver the mail.

X. Check that the SMTP server accepts email.

Follow these steps to simulate what FogBugz does when it tries to send mail. If you see an error at any point, it will likely give you some clues as to what's wrong with the SMTP server.

Secure SMTP (SSL)

If your SMTP server is using SSL, see this guide to debug.

Normal SMTP

  1. From the computer where FogBugz is running, open a command prompt (choose Start, Run, type cmd, and click OK).

  2. Type (replace 25 with your SMTP server's port number if it is non-standard)

    telnet smtpserver 25
  3. If you get a message saying that the command is not found, you're likely on Windows 7, which removed telnet from the default installation. You can search Google for "enable telnet windows 7" to get several options to re-enable. If you get a message that says something like Connect Failed, the SMTP server in question is not accepting any connections. This may be because:
  4. the SMTP server is not running
  5. the SMTP server is configured to reject email connections from the FogBugz machine
  6. If all is well, you will see a message that starts with the number 220 followed by a greeting.

  7. Type

    HELO smtpserver
  8. You should see a message starting with the number 250 followed by something glib like "pleased to meet you"

  9. Using the email address configured as "Notification Return Address" in the FogBugz Site configuration screen, type

    MAIL FROM:youremail@example.com
  10. You should see a message starting with the number 250 followed by something like Sender ok.

  11. Using the email address you want to send a notification to, type

    RCPT TO:email@example.com
  12. You should see a message starting with the number 250 followed by something like Recipient ok.

    If you see a message that says something like "Relay Access Denied" this means that the SMTP server is configured to refuse any email that is not intended for its own domain. For example if you are sending mail to joe@example.com using an SMTP server at mycompany.com and you see a message about relaying denied, this SMTP server probably thinks you are a spammer. You will need to find an SMTP server that is configured to accept email from the FogBugz machine to its recipients.

  13. Type

    DATA
  14. You should see a message starting with the number 354 followed by instructions to enter the email message.

  15. Type

    Test message
    .
    Note that the last line contains a period (dot) alone. This signals that you are done typing the message.

  16. You should see a message starting with the number 250 followed by something like Message Accepted for Delivery.

  17. Type

    QUIT
  18. Check that the email was received. If it was not received even though the message was accepted for delivery, there is something wrong with the SMTP mail server.
Still stuck?

This solves the issue in the vast majority of cases. If you need further help, contact us at http://contact.fogcreek.com




RSS Feeds: Keeping tabs on Fogbugz via a feed aggregator

FogBugz publishes RSS feeds, allowing you to use an RSS aggregator to receive notifications, so you can keep up to date on changes to your filter without opening your web browser. FogBugz supports RSS version 2.0.

Note: An RSS ("Really Simple Syndication") reader or aggregator is a program that checks with a bunch of websites to see if there's anything new there, and shows you a list of new items on all the sites in one central location. That way you don't have to visit sites that haven't added anything new since the last time you looked. Many websites, including popular news websites and most weblogs, publish RSS feeds so that RSS aggregators can find out if anything new has appeared.

Cases

FogBugz creates an RSS feed automatically whenever you save a filter. For the RSS link, go to the More menu at the top right of the case list page. The link also appears in the Manage Saved Filters screen. You will see a little orange RSS link next to every saved filter. Copy the link location into your favorite RSS aggregator.

Note: Some RSS readers may not support cookies, making it impossible for them to keep you logged on to FogBugz. To work around this problem, you will need to append your user name and password to the end of your feed link manually:

FogBugz generated URL&sEmail=email&sPassword=password

If FogBugz is set up to use LDAP authentication, the password to use will be the non-LDAP password set in FogBugz before LDAP authentication was enabled. You can also subscribe to a single bug using RSS, which will notify you as that bug changes, just as subscribing by email would. Simply enter the URL of the bug itself in your RSS aggregator, which will automatically discover the URL of the RSS link for that bug. The URL of bug number 1234 is http://fogbugz/?1234 where fogbugz is your main FogBugz URL.

Wikis

To subscribe to a wiki article, find the little orange RSS link on the page. Copy the link location into your favorite RSS aggregator. The RSS link must be included in the wiki's template using the template field $rsslink$.

Discussion Groups

You can subscribe to an RSS feed for a discussion group which will list all new topics posted to the group. To do so, view the group or any topic in it. Find the little orange RSS link at the top-right of the page. Copy the link location into your favorite RSS aggregator.




FogBugz Groups and Permissions

As of FogBugz 8, FogBugz allows you to set up groups of users who can be granted permissions to read or modify certain parts of FogBugz selectively. FogBugz users can be given permission directly on Projects, Wikis, and Discussion Groups, or they can get permission through a group.

Setting Up Permissions

Before setting up permissions, ensure that FogBugz is configured to require passwords (Admin | Site | Authentication | Log on Method).

Groups

Groups in FogBugz are lists of users that can be given permission on Projects, Wikis, and Discussion Groups. Before you setup permissions in FogBugz, you may want to organize your users into groups. In addition to any groups you create, there are 4 automatic groups on every FogBugz install that are considered when assigning permissions:

  1. Site Administrators (automatically have full permissions on everything)
  2. All Normal Users
  3. All Community Users (if community users are enabled on the install)
  4. Anonymous Users

These groups let you easily give all users access to a project, wiki, or discussion group. For more information, see this article.

Projects

Access to cases is controlled at the project level. Normal users can be given permission to view cases, submit cases, or to be a project administrator. Community users can only be given permission to submit cases and view cases they have already submitted.

To setup project permissions:

  1. Go to Admin | Projects.
  2. Click on the Edit button on the left for the Wiki or Discussion Group you want to edit.
  3. Click on Edit Permissions.
  4. Click on Add User or Group to give a new User or Group permission.
  5. Select the appropriate radio buttons for the permissions you want to grant.

alt text

Wikis and discussion groups

Both normal and community users can be given access to a Wiki or Discussion Group. Normal users can be given read, write, or administration privileges, while community users can be given permission to read or write only.

To setup wiki or discussion group permissions:

  1. Go to Wiki | Manage Wikis or Discuss | Manage Discussions.
  2. Click on the Configure button on the left for the Wiki or Discussion Group you want to edit.
  3. Click on Edit Permissions.
  4. Click on Add User or Group to give a new User or Group permission.
  5. Select the appropriate radio buttons for the permissions you want to grant.

alt text

Administrators

There are two types of administrators: Site Administrators, and administrators who have been given permission on a specific Project, Wiki, or Discussion Group. Site administrators are a special type of FogBugz user designated in Admin | Users. They have full control over all areas of FogBugz, and are the only users that can edit permissions or Create/Delete Projects, Wikis, and Discussion Groups. Non-Site Administrators get control over their respective areas, described below:

Projects

Project Administrators can't create or delete projects, or assign project admin permissions to other users, but otherwise have full control over their own projects, including the ability to:

  • create, edit, and delete areas
  • create, edit, and delete milestones
  • modify project settings
  • assign only modify or read permissions to users or groups within the project admin's visibility
  • create and assign workflows to the project
  • edit assigned workflows to the project created by other project admins

Wikis

Wiki administrators can't create or delete wikis, or assign wiki admin permissions to other users, but otherwise have full control over their own wikis, including the ability to:

  • create, edit, and delete templates
  • modify wiki settings
  • assign only modify or read permissions to users or groups within the wiki admin's visibility

Discussion groups

Discussion Group Administrators can't create or delete discussion groups, or assign discussion group admin permissions to other users, but otherwise have full control over their own discussion groups, including the ability to:

  • moderate discussions (deleting and undeleting posts)
  • see the email address and IP address of a poster
  • modify discussion group settings
  • modify discussion group layouts
  • assign only modify or read permissions to users or groups within the discussion group admin's visibility

Isolating users from one another

In various parts of the FogBugz user interface, you can see a list of users in a dropdown list. FogBugz will only show each user the names of people who have some project or group in common.

For example, Alice and Bob will not see each other's names in any dropdown lists with the following group setup:

  • Development group: Alice, Ted, Joan
  • Administration group: Bob, Emily

However, suppose we create a Project called Bob's Project and give the Development Group and Bob permission on it. Then Bob and Alice would be able to see each other. Also note that if we give All Normal Users permission on a project than everyone can see everyone in a FogBugz install.

Mailbox Usage Rules

In order for a user to send mail from a specific mailbox, they must have Modify access to a project and the mailbox they wish to use must be set to sort incoming messages into an area in that project. Only if these conditions are met will a user be able to send outgoing mail from a given mailbox.

Other Visibility Rules

There are a few other rules to keep in mind if you are concerned about user visibility in your FogBugz install:

  • Site Administrators can see everyone and everyone can see Site Administrators.
  • Community Users can only see Administrators and all other Community Users, and everyone can see all community users.
  • Virtual Users are visible to everyone

Our QA Process Regarding Permissions

We test to make sure permissions work with every single release that we do. The basic workflow that we walk through is:

  • Create a project that a particular user can't see.
  • Create a case for that project.
  • Log in as the user with limited permissions
  • If the user can see the case that was created, the test fails and we don't allow the build to go into production.



How are Groups used to assign permissions in FogBugz?

Permissions can be set on FogBugz Projects, Wikis, and Discussion Groups. Permissions can be assigned to individual users, to built-in groups (e.g. 'All Community Users'), or to user-defined groups. A group is simply a set of users to whom you want to assign the same set of permissions.

Built-in Groups

There are four built-in groups that are available in every FogBugz install.

  1. Site Administrators (automatically have full permissions on everything)
  2. All Normal Users
  3. All Community Users (if community users are enabled on the install)
  4. Anonymous Users

User-Defined Groups

When you want to set more restrictive permissions, but have several users who should have identical permissions on some project or set of projects, you can create a group to make assigning those permissions convenient. To create a new group, go to Admin | Groups, and select 'Create New Group'. There are two types of groups, Normal and Community User groups. This distinction exists because there are certain things Normal FogBugz Users can do that Community Users can't. For example, normal users can be Project Administrators while Community Users can't.

Normal User Groups

A Normal User Group can contain any non-community user. When editing a group, you can add users by clicking the Add A Member link at the bottom of the users table.

alt text

Community User Groups

You can add any community user to to a Community User Group individually, just as with Normal User Groups, or you can give permission to an entire domain of community users by adding a domain wildcard.

alt text

Assigning Permissions to Groups

Once you have created a group, you can assign permissions for the group directly on the configuration page for the Project, Wiki, or Discussion Group. For instance, here we are giving the 'Developers' group access to a project that already includes the user Robert Tarjan as an administrator.

alt text

Upgrading from FogBugz 7 and Earlier

Previous versions of FogBugz used an 'umbrella' permission model rather than giving permissions on each Project, Wiki, and Discussion Group individually. Projects, Wikis, and Discussion Groups were each assigned to a "Group", which was entirely different from a FogBugz 8 group. In FogBugz 7, users were granted permission on Groups which were passed onto any Projects, Wikis, or Discussion Groups which were assigned to that group. The concept of Groups in FogBugz 8 and later is entirely different from this notion, but to maintain continuity, FogBugz 8 user groups will be created from the old Fogbugz 7 groups when upgrading. These new groups ensure that permissions remain the same when upgrading, and you may continue to use the newly created groups or use an entirely different group setup after you upgrade.




The Admin Dashboard

The Admin Dashboard (accessible via the Admin menu on the upper right) provides site administrators with a complete snapshot of all the FogBugz functionality currently in use on the site. Each dashboard panel provides a brief summary of settings and links to the relevant configuration page.

alt text




Compiling Release Notes

  1. From any FogBugz page, click the Schedules menu at the top, then click the last item in this menu, "Release Notes".

  2. Select the project and milestone you are releasing.

  3. The page will update to show the cases you've resolved. This page also enables you to review the release notes and modify them as necessary.

  4. When you're happy with the release notes, click the HTML button at the bottom to generate an HTML page. It will open in a new tab. You can now save this file and publish it elsewhere.

  5. Optionally, you can generate XML instead and use it to generate your own HTML.




Troubleshooting FogBugz Slow Performance

These things can slow down FogBugz performance:
  1. Email Server Issues? Determine if this only happens when automatic email notifications get sent. Is it the case that assigning a bug to a person with email notification turned on causes a delay, but assigning a bug to a person with email notification turned off happens instantly?

    If this is the case, the problem is related to your SMTP mail server. It's possible that the mail server is remarkably slow. More commonly, it's caused by a firewall between the mail server and the FogBugz server. See Troubleshooting Email Notification Problems for more details, especially the section titled "Check that you are not blocking ident traffic" and the notes on nslookup right above that.

  2. Database Authentication? If it happens for all page loads, it may be an authentication issue. In Windows: If your connection string has this in it:

    Integrated Security=SSPI; 

    ...then switch to name and password in the connection string, using a SQL Server login that has db_owner rights and access to the FogBugz database. Example: 

    Server=myServer;Initial Catalog=myDatabase;User Id=myUserID;Password=myPassword;MultipleActiveResultSets=true;

  3. DNS Issues? If you are not using Windows Integrated Security, and are passing a username and password for a database login, and page loads are still slow, one thing to try is the following. In the connection string, shown above, note the server name part:

    Data Source=SERVER-NAME-HERE;

    Instead of using the server name, use the IP address. Or, if the database is on the same machine as the web server, use:

    Data Source=[localhost];

    This has been known to work in some cases.

    MySQL: if you're using FogBugz 7.0 or later, your connection string should start with DRIVER={mysql}; If it starts with Driver={MySQL ODBC 3.51 Driver}; change it.

  4. Slow SQL Server? If you use SQL Server with FogBugz, try restarting SQL Server. If after restarting SQL Server, an event in Event Viewer comes up as:

    supersocket info: connectionlisten(shared-memory LPC)) error 5

    Go to http://support.microsoft.com/kb/815249 and execute the workaround listed there...

  5. DB time-outs with MySQL? If you use MySQL with FogBugz and you see errors about database time-outs, see this post on debugging MySQL

  6. Virus Scanner?   McAfee Virus Scan may be monitoring all files. Other users found that this killed their performance (presumably because every time SQL Server hit the disk, McAfee was checking the DB files for viruses. Updating McAfee to the latest version and having it ignore the DB files completely solved the problem).




Keyboard Shortcuts

Yes! FogBugz has keyboard shortcuts!

To activate FogBugz keyboard shortcuts, press Ctrl+; (hold down Ctrl and press the semicolon key) on any page. Little yellow tags will appear over each action with its shortcut.

You can:

  • Press the key shown to perform the action,
  • Press Ctrl+; again to rotate through different sets of keyboard shortcuts,
  • Or press Esc to make the tags go away.

When you're looking at the list of cases, press Ctrl+; to go into keyboard mode and use the cursor keys (, , Home, End, Page Up, and Page Down) keys to select a case. Once you've selected a case press Enter ↵ to view it.

  • In some browsers, including Firefox and Internet Explorer, Alt+; can be used as an alternative to Ctrl+;.
  • On non-English keyboards, try Ctrl+, (comma) or Ctrl+` (backtick).
  • In certain browsers, including Opera, the arrow keys are not available. Use j and k to navigate up and down within a list.



Handling Incoming Customer Email

You can use FogBugz to handle customer interactions over email. If you're using FogBugz On Demand, your FogBugz comes with a free cases@xxx.fogbugz.com mailbox to get you started. If you have FogBugz on your server (or if you want to use an email address of your own with FogBugz On Demand), you'll just need to have a POP3 or IMAP mailbox hosted on a server that FogBugz can access.

Once you've set up your mailbox, FogBugz will check it regularly for new messages. When it finds messages in the mailbox, it'll download them (including attachments) and turn them into cases. Once the email is successfully turned into a case, it's deleted from your POP3 mailbox or marked as read and optionally deleted if the mailbox is IMAP.

By default, FogBugz will send a confirmation email automatically. This email will contain a link to a special public view of the case page.

By default, once a case is created in FogBugz, it's autosorted using FogBugz's sorter. This is not just a spam filter. It's a probabilistic sorting engine that can learn how to sort different kinds of emails into different areas within the Inbox project. It can save a lot of work if you have different teams working in the Inbox.

Once the message is in FogBugz, you can treat it like any other case: you can prioritize it, assign it, track it, slice it, dice it, deep fry it, etc. But probably you'll just want to reply to it. Your reply will come from the same email address the original message was sent to (or you can change it manually). If the customer replies, the email will reactivate the case if it's been resolved, and will re-open it if closed. To ensure timely replies to customer email, you can set the mailbox to assign a due date to the case that was created.

For several reasons, it's probably a good thing to keep all your incoming customer email case in your Inbox project. (FogBugz can be configured to sort into projects other than the Inbox on a per-mailbox basis.) If a given inbox case seems like it should be turned straight into a bug, we get the best results with spawning off a new case, and using FogBugz's automatic case relation feature to link back to the generating email. We do this for two reasons: First, the FogBugz autosorter uses historical data to decide where to sort an incoming email. If your email cases are moved out of the Inbox project, the sorter loses track of them and becomes less effective. Second, and more important, we find that Inquiries demand a different kind of attention than Bugs or Features. If you move a case out of the Inbox and into your feature backlog, it's just too easy to forget that you didn't respond to the customer... and customers like getting responses to every email. When the feature is implemented or the bug is fixed, you still have the case relation link back to the original email, so with two clicks you can reply to the customer to let them know.

When you do respond to the email, FogBugz has a lot of help for making it painless. You can use our keyboard shortcuts to burn through a list of cases quickly. You can use snippets to create friendly salutations and closings, as well as clear responses to frequently asked questions. FogBugz also helps prevent users from stepping on eachother's toes when responding to emails and relates any other cases with the same correspondent so you can quickly see the customer's history.

Customers can also submit new cases via public projects, and can post on public discussion groups (you can turn a discussion post into an internal case with one click).




Using FogBugz to check POP3 and IMAP mailboxes

To handle customer email through FogBugz, you set up Mailboxes.

Each FogBugz Mailbox corresponds to one incoming POP3 or IMAP mailbox where FogBugz receives mail. You can set up as many mailboxes as you want, for example, you could set up support@example.com as well as suggestions@example.com and bugs@example.com.

When using POP3, FogBugz deletes messages off the mail server after downloading them. With IMAP, FogBugz only downloads unread messages from the Inbox of the IMAP account (not other folders) and marks them read afterward. If you enable the option in FogBugz, it also deletes them from the IMAP account.

If you use FogBugz On Demand, hosted by Fog Creek Software, we've set up a single mailbox for you automatically on our own server. Incoming messages can be sent to cases@xxx.fogbugz.com, where xxx is your custom URL. You can also set up your own mailboxes.

To configure a mailbox, log on as a FogBugz administrator and choose Admin | Mailboxes.

Basically, you'll need to configure

  1. Where the email comes from
  2. What FogBugz should do with it

The following options are configured when you set up a mailbox:

Email address

The full email address of the mailbox, for example, support@example.com. This is the "from address" when FogBugz sends outgoing email.

Full name

The full name that will appear in the "from address" when replying to email from this mailbox, for example, Customer Service.

When you are replying to incoming email, you get a choice of using this name if you wish to remain anonymous, or you can use your own full name.

The next four settings are required unless you are configuring the FogBugz On Demand default mailbox:

Account name

The log-in account on the POP3/IMAP mail server.

Password

The login password on the POP3/IMAP mail server. FogBugz will use the account name and this password to log in and retrieve the email, just as any other mail client.

Mail Server

The DNS name or IP address of the POP3/IMAP mail server.

Port

The TCP port for the POP3 or IMAP service. For POP3, this is almost always 110 unless you're using secure POP3, which is almost always 995. For IMAP, this is typically 143 or 993 for secure IMAP.

Aliases

A comma separated list of any other email addresses which forward to this mailbox. This allows FogBugz to recognize these addresses as pointing back into FogBugz, and thus not send extraneous email to them.

Protocol

Select the type of mailbox. FogBugz supports POP3 and IMAP. For IMAP, choose whether you would like messages deleted from the server after they are downloaded or only marked as read. Note: FogBugz only downloads unread messages in the Inbox of the account when set to IMAP.

Reply Automatically

Allows you to decide if users should receive an immediate automatic reply when they send a request into this mailbox. FogBugz will not reply to follow-ups, or to messages categorized as spam. Learn about automatic replies. Note that this is the only email that FogBugz will ever send without explicit action from a FogBugz user. Some systems send emails automatically on resolution or closure of the case, but we find that these can often cause more confusion than they prevent.

Due

To insure that email is responded to promptly, FogBugz can set a due date for every mail message that comes in. Learn more about due dates.

Sort Messages

FogBugz can sort messages automatically, including spam removal. Learn more about FogBugz AutoSort.

Message Template

Set up a signature that will be automatically inserted at the bottom of every reply you send in this mailbox. In addition to the special variables provided by Automatic Replies, you can also include the current user's name with {username} and personal email with {useremail}.

Delete spam after

To avoid spam filling up your FogBugz database, any message which is either resolved as SPAM or moved into the Spam area will be permanently and irrevocably deleted after the number of days you set here (defaults to 7). If you don't want to delete spam leave this blank.

Deleting old spam is handled nightly by the FogBugz Maintenance Service.

Delete inquiries after

If you do not wish to keep a permanent record of incoming email, you can set up FogBugz to delete the complete case history of all closed inquiries after a certain number of days.

Deleting old inquiries is handled nightly by the FogBugz Maintenance Service.

Mailbox Problems

If FogBugz is not checking your mailboxes successfully, see this debugging guide.




Automatic replies to incoming emails

When you configure a mailbox, you can configure FogBugz to reply automatically to incoming email. This is the only instance in which FogBugz can be configured to send an automatic message to an outside party (a user without a FogBugz account). FogBugz will not send automated emails when a case is resolved or closed. We believe it should be your choice as to how to communicate this status to your customers, and that communicating automatically might cause more harm than good.

Automatic replies are plain-text and you can include the following variables in the message or subject line. The placeholder will be substituted with the appropriate value when the message is sent:

{case}      the case ID number
{sender}    the sender's email address
{subject}   the subject of the incoming message
{ticket}    the external customer reference number to this case; includes a random password for security
{url}       the URL of the FogBugz install
{ticketurl} a link the customer can use to check the status of their case
{fullname}  the full name associated with this mailbox
{email}     the email address associated with this mailbox

No matter what you do, the outgoing subject must include (Case {case}), because that will insure that if the customer replies to the autoreply, their reply will be appended to the same case instead of opening a new one. In this case, FogBugz will not send an auto-reply, as the correspondent has already had confirmation of this particular case reaching the system.

FogBugz will not send auto-reponses to messages categorized as spam.

Also, to prevent mail loops, FogBugz will not automatically reply if any of the following is true:
  • The From or Reply-to field contains postmaster, daemon, owner-, bounced, no-reply, do-not-reply, noreply or donotreply
  • The Precedence field is junk or bulk

FogBugz will not automatically reply to the same email address more than three times in one hour.




Snippets for Fast Responses and Templating

Snippets can be used in any text field in a case, but they're most useful for replies to emails.

The snippet activation key defaults to `. It is changeable on a per-user basis in My Settings > Options. If you have a non-English keyboard layout, you might find the regular snippet key doesn't work. If so, just change to one of the other keys.

Let's say you've got this snippet, which you call, upgrade:

Hi there,

Thanks for reporting this bug! Fortunately, we've already fixed it in the most recent version of the software, Frogger [[version]].

If there's anything else we can do for you, or if upgrading doesn't fix the issue, please just reply to this email and we'll figure out what's going on.

{username} - Frogger Software

To activate it, you can either type the snippet name and then the snippet key:

upgrade`

Or you can type the snippet key twice, which will bring up a snippet search box.

The text from the upgrade snippet will be inserted, plus you can include one a placeholder like [[version]] per snippet. That portion of the text will be immediately highlighted, so the next thing you type will replace that text.

There are also placeholders, surrounded by curly braces, which will be replaced with features from the case or the user. You can even add your own placeholders via BugMonkey. We have developed a customization we use to extract the user's first name from their email.

Snippet Placeholders

There are also many placeholders you can put in snippets that will be replaced automatically. All of these are available for mailbox autoreplies, too:

  • {case} for the case ID
  • {sender} for the sender's email address
  • {subject} for the subject of the message
  • {ticket} for the external ticket ID
  • {ticket_singlecase} for the external ticket ID that only has access to the current case (not other cases submitted by the same person)
  • {url} for the URL of the FogBugz install
  • {ticketurl} for a link to the external case (e.g. http://try.fogbugz.com/default.asp?[ticket])
  • {ticketurl_singlecase} for a link to the external case (e.g. http://try.fogbugz.com/default.asp?[ticket_singlecase])
  • {username} for the name of the logged on user
  • {useremail} for the email of the logged on user
Snippet Administration

Snippets can either be personal to the user or global, if added as such by an administrator. Users often run into the problem that global snippets proliferate and become hard to manage. The search box and the notes field come in handy here.

Rather than offering some sort of snippet group administration interface, which would further complicate the product, we recommend putting a code in the Notes field for the global snippets. The user can then type this code in to the search box and restrict their snippets to that subset. For instance, the code KLN could be added to all Kiln snippets, and the code FBZ to all FogBugz snippets.




Removing Spam from your Inbox with Autosort

FogBugz AutoSort automatically sorts incoming email into different areas. The simplest way to use FogBugz AutoSort is to separate spam from non-spam. But you can also set it up to divide incoming email into up to seven areas. For example, you could divide incoming mail into four areas: Customer Service, Tech Support, Job Applications, and Spam.

Initially, and when it is not completely sure about a message, the sorter will put messages into the Undecided area. Make sure to move messages out of this area and into other areas within the same project. If you move the cases out of the project, the sorter loses track of the case and can't learn from your sorting.

After a few dozen emails, FogBugz AutoSort will start doing a pretty good job. With a few days of training you should expect about 99% accuracy separating spam from non-spam. Note that 99% accuracy means that a portion of your spam messages will come through to Undecided or even another visible area. In our view, it's much more important to show you the messages we are not fully sure about. An unfiltered spam is no big deal. A missed purchase order from a customer is a big deal, so we err on the side of caution.

Setting Up the Email Sorter

To set up simple email sorting, separating Spam from Non-Spam:

  1. Set up a Mailbox in FogBugz, leaving the Autosort default intact. If you're on FogBugz On Demand, you can optionally skip this step, as you have a built-in mailbox. When you point the Autosorter at a project, it automatically creates three areas in that project: Spam, Not Spam, and Undecided. You can add as many as you want, but we strongly recommend no more than 4 additional areas (7 areas total).
  2. On the Filters menu, choose Inbox to see all your incoming email sorted neatly. (Create a new filter if the mail is in another project.)
  3. Start sorting messages into appropriate areas. After FogBugz has seen fifteen non-spam emails, it has enough data to start autosorting. For the initial period, you might want to keep an eye on the Spam folder for false positives. Every time you move an email, FogBugz will learn a bit more.

If you are trying to sort messages into different areas rather than just filtering spam, you will have the best luck if there are obvious clues in the message, like recurring words or a particular language. Included in these are so-called "bounce" messages and vacation auto-replies. Most heavy users of FogBugz's email functionality will want to have an "Undeliverable" area. As you sort vacation autoresponses and "message undeliverable" messages into this area, you'll find the predictable nature of these messages makes them ideal for autosorting.




The Autosort Bayesian Filter

Note: Make sure you also read the Best Practices for using Autosort.

FogBugz contains a sophisticated spam-blocking algorithm that learns how to recognize spam automatically as you train it.

Rather than using a fixed set of spam clues, for example, assuming that "mortgage" must mean spam, it learns from your own incoming email. If you work for a bank, "mortgage" probably doesn't mean spam.

In addition to using only positive clues (for example, "V1agra" probably means spam), FogBugz will learn from negative clues as well (for example, if the email contains the name of one of your products it's much less likely to be spam.) FogBugz examines many aspects of the incoming email for clues which could be considered positive signs of spam, negative signs of spam, or neutral. And since you train it, it will adapt itself to the particular stream of email that you receive.

When you first install FogBugz and turn on FogBugz AutoSort, FogBugz sets up a project named Inbox with three areas: Spam, Not Spam, and Undecided. At first, FogBugz AutoSort has no clues at all about what messages are spam and what messages are not spam. All incoming messages are put straight into the Undecided area.

To train FogBugz AutoSort, you need to teach it about every message in the Undecided area, either by flagging it as spam by clicking the Spam button, or by moving it to the Not Spam area if it's not spam.

Any time you see a message in the wrong area, take the time to move it to the right area. This will help train FogBugz AutoSort.

After a few days, you should notice that FogBugz AutoSort is correctly sorting most messages. In the first few days there is a small chance that a few messages will be mistakenly flagged as spam. Don't worry about this, but do move them into the Not Spam area to help train FogBugz AutoSort.

After you've received a bunch of spam and a bunch of nonspam, typically after a couple of days or about 100-200 messages, you'll find that FogBugz AutoSort is doing a really good job automatically sorting messages. But no matter how good it gets, it will always be undecided about some messages and you'll have to decide those cases yourself.

FogBugz AutoSort tries to be conservative to avoid accidentally flagging a message as spam when it's not really spam. In practice, we have found that even with an email address that receives hundreds of spam messages a day, it is extremely rare for FogBugz AutoSort to accidentally mark something as spam that is a legitimate email. In fact, our experience is that it's more common for humans to mistake a real email for spam than for FogBugz AutoSort to make this mistake! Unfortunately, there's always the possibility that a legitimate email from a customer will look so spammy that it gets deleted accidentally. If you are concerned about this, set aside some time to review the spam messages every few days just to be certain nothing legitimate is getting lost. On the whole, though, you'll find that FogBugz AutoSort does a great job with very few "false positives."

To save you time, FogBugz treats emails sorted as spam slightly differently.You will not receive notifications, auto-replies, or escalation reports regarding spam emails. Spam emails are also conveniently hidden from most views of your cases and summary reports, although they are still accessible with the click of a link.

Implementation details

FogBugz implements a modified version of the Bayesian filtering algorithm proposed by Paul Graham in the article A Plan for Spam and Better Bayesian Filtering, with modifications and improvements designed by Fog Creek technical staff.




Best Practices for Using Autosort

Here are a few things we commonly tell customers:

  1. Make sure you're moving cases out of Undecided, whether they're spam or not. The spam filter's decision process is trying to figure out not just whether something is spam or not, but where to put it other than Undecided. If you are closing cases in Undecided, then you're not training the filter that those cases are not spam. Autosort will only leave training mode and start sorting once you have moved 15 non-spam messages out of Undecided. We have a feature request in to warn you when you're closing cases in Undecided. The case number is 1675911.

  2. Close Autosorted cases in the project and area they're sorted into. If you move the case out of the project, FogBugz Autosorter loses track of it. This is not ideal operation, but is due to the need to support multiple Autosort projects. We have a case for this, too, though I can't find it right now. Ping me if you want the number to keep track of it.

  3. Limit the number of Autosort areas to five or six per project. This kind of sorting takes a lot of computational resources. Deciding between seven areas is about three times as intense as deciding between four areas. Fewer choices also give you better sorting.

  4. Have an "Undeliverable" area. Bounces from email servers and out-of-office auto-replies will create new cases. Because they're so predictably structured, though, it's easy to get the sorter trained to sort these out into their own area. We use "Undeliverable" because it sorts nicely to the bottom of the Inbox filter. I just resolve and close them periodically. We should have some sort of special operation here, to close these out easily. I've created case 1695675.

  5. Turning on Autosort will create "Spam", "Not Spam", and "Undecided" areas. If there are already areas with these names in the project, then Autosort may encounter errors. Be sure to rename any such areas before turning on Autosort for a project.

  6. Add areas slowly and organically. (This is taken from Spooky's answer.) Your first order of business should be to train spam vs. nonspam. Once you have mail reliably being sorted into Not Spam, you can add areas one by one to segment out certain types of mail. The more areas you have, the less accurate it will be. Also, it almost never works to send emails that you think will look like the emails you intend to receive. The signals that the sorter listens to go far beyond the actual text content of the email, so it's really not worth your while to send 100 messages with your product name into the Inbox and sort them to "pre-train" the filter. Rather, just open it up and train it naturally. It will respond very quickly to things like web form submissions and auto-generated emails.




Public Access to Email Cases

The "ticket" for a case is a generated 8-character value, that, when combined with the case number, allows outside users to see certain parts of, and attributes of, their case. It used to be generated only for cases emailed into the system, but is now generated for all cases.

The chance of a random outside user guessing this ticket value is 36 to the power of 8, about 2,821,109,907,456 to 1.

If someone was trying to "brute force" access to a case, you would almost certainly detect the millions of hits on the same case, and we certainly will detect it on our servers (for those folks on FogBugz On Demand).

You can send a customer the ticket url using a snippet or show it in a case using a plugin or bugmonkey script.




The FogBugz Wiki

FogBugz includes a wiki for creating and maintaining documentation.

In a wiki, every article can be edited by anybody, and a complete record of all edits is maintained forever. This allows anyone with a little bit more information to improve an article simply by clicking the Edit link and editing it in place.

You can use the wiki for any team documentation: specifications, requirements documents, knowledge base articles, status reports, internal technical documentation, and external end-user documentation. Because anyone can edit any article, the quality of each article will improve over time.

You can create as many wikis as you need in your FogBugz installation.

  • Each wiki has a home page accessible from the Wiki pull-down menu; it can link to an unlimited number of other articles.
  • You can create one or more templates, which specify the design of each wiki page. All pages from the same wiki must use the same template.
  • Each wiki has its own set of permissions. You can make some wikis open to the public, while others are more restricted.
Editing wiki articles

To create additional articles in a wiki, you simply edit an existing article, click where you want a hyperlink to the new article, and choose Insert | New Article. This makes a link to the new, initially-blank article right in the current document. The link is red to remind you that the new article has not been written yet. Save your changes and click on the red link to get to the new article.

Links

In general, when you want to insert a link:

  1. Type the text that the link should have, and select it
  2. Choose Insert | Link
  3. Enter the destination that the link should go to.

To follow a link while you're editing an article, hold down Ctrl while clicking the link.

The wiki is tightly integrated with FogBugz. You can create a link to any FogBugz case simply by typing the case number when you insert a link. This becomes a bidirectional link; the FogBugz case will link back to the wiki article automatically. Likewise, you can link from a case to a wiki page by typing 'w' and the article number when editing the case, for example W123.

You can also attach a file to a wiki article and create a link to it in one step by clicking Insert | Attachment...

Images and tables

Add images to your document by choosing Insert | Picture... The image will be stored in the wiki and embedded in the page. You can resize the image by clicking it and dragging the corners or edges. Set a title and formatting by right-clicking and choosing Picture Properties...

To create a table, choose Insert | Table... and set the options. You can add and remove columns and rows and split or merge cells by right-clicking the table.

Insert an automatically-updating tables of contents for an article with the Wiki Table of Contents plugin.

Removing articles

FogBugz does not automatically maintain a table of contents to all wiki articles. If you delete the last link to a given article, even though it still exists in FogBugz, you can only get to it by directly typing the URL. This is called an orphaned article; administrators can see a list of them in the wiki configuration page. To delete an article, remove all links to it (see the article's Info page for a list) and then delete it from the orphaned articles list.

Templates

An HTML and CSS template applies to all articles within each wiki. The WYSIWYG article editor built into FogBugz picks up on several things from the current template:

  • the list of available fonts
  • the list of available paragraph styles
  • the list of available font sizes
  • the palette of available colors

If you want to change the fonts, styles, and colors used in your articles, just select a new template. To do so, choose Wiki | Manage Wikis... to navigate to the Wikis page, then click the Configure icon next to your wiki's entry in the list. This will take you to the Edit Wiki page, where you can select a template.

To edit an existing template, click on the Customize Templates link at the bottom the Wikis page. On the Templates page, click the Configure icon next to a template's entry in the list. The Edit Template page will allow you to customize page layout HTML, view a set of template variables that you can embed in your wiki (for example, the "$incoming_links$" variable lists all pages that link to the current page), edit the wiki's CSS stylesheet, and specify a set of image (or other content type) attachments for use in your layout HTML.

Collaboration

The FogBugz wiki is completely multiuser; any number of users can edit each article simultaneously without clobbering each other. FogBugz will detect if two users' changes conflict, and ask the second user to decide how to resolve the conflict. If two users edit different parts of a document, their changes will not conflict and will both be saved.

FogBugz automatically saves drafts in the background as you are editing, in case you close your web browser or it crashes before you can save. When edit the article again, you'll be given a chance to recover your changes, even if you never clicked Save.

Permissions

Each wiki can have its own set of granular permissions. You can choose whether Anonymous and Community users can see and edit the wiki, and you can enable finer controls by setting assigning the wiki to a group.

Wiki article information

If the three Wiki Article Info plugins are enabled, you will see an Info link next to Edit at the top-right when viewing or editing an article. The wiki article info page contains article details, history and a list of all links to and from the article. If these are not enabled, the link will read History.

The wiki history browser shows a list of each change made to the article over time, who made it and how much of the content was changed. For each version, you can click a link to see a graphical display showing what changed relative to the previous version. You can compare any two versions by clicking Next and Previous for each side of the comparison until you see the two versions you want. From the article editor, you can go back to any old version by clicking the left arrow next to the date and time in the top-right, then click Restore Old Version in the top-left.

If somebody has made a change that you don't like, just restore the version before they made the change and save it as the current version. This has the effect of undoing their change in two clicks. In practice, this means that it's easier to clean up vandalism than to vandalize in the first place, and it has the effect of keeping the quality of a wiki article very high even when you allow anyone in the world to edit it.

Users can subscribe to a wiki article to receive notification when it changes. This is useful to track projects or interesting documents, and it also makes it difficult for a vandal to deface a page without anyone noticing. Vandals eventually give up when they realize that they're not getting anywhere and move on to something else, like throwing stones at rabbits.

Searching wiki articles

FogBugz search includes wiki articles. To search only wiki articles, add type:wiki to the search terms. To quickly search just the current wiki, use the search box on the article page (if included in the current template).

Tags

Tags make it easy to find what you are looking for in FogBugz. Add tags to wiki articles in the tags field at the bottom of the editor. Find your tagged articles later by searching for type:wiki tag:my_tag




New Wiki Features

The functionality and design of the Wiki have both been completely revamped for FogBugz 8.0. Major changes include an updated editor, a sidebar with useful page collections and attributes, inline wiki comments and a redesigned default template. Here's a brief overview of some of the new features:

Updated Editor

The FogBugz wiki editor has been replaced with a customized version of CKEditor (http://www.ckeditor.com). Here's what the new editor's toolbar looks like:

alt text

CKEditor provides excellent editing functionality right out of the box, and we've added a few cool things to make editing a wiki page a better experience. One example are bubble menus that provide contextual options, but don't obscure your browser's right-click menu.

alt text

Page Collections and Attributes

As a wiki gets bigger it can be challenging to keep track of all the pages and how they relate to each other. Wiki Page Collections and Attributes aim to help. The Wiki comes with a Title Index, a Recently Changed page listing, a Page Hierarchy, and a listing of Incomplete pages. Also included are a Tags page that lists all of your wiki's tags and a Hierarchy control that displays related pages and helps you keep track of where you are in the wiki.

alt text

Each of the navigation control pages also include a "filter-as-you-type" search bar to make finding the wiki page you're looking for as simple and fast as possible.

alt text

The wiki sidebar can be extended via plugins to add page collections and attributes for pretty much anything you can come up with.

Comments

As with the rest of FogBugz, the Wiki is extensible via plugins. One example is the Comments plugin, which allows for inline comments and responses on a wiki page without having to switch to edit mode. It's great for receiving feedback without cluttering up the content of your page. The comments plug comes with the Wiki by default.

alt text

Redesigned Template

The default wiki template has been completely redesigned in FogBugz 8.0 to be easier to use and better looking. The primary goal was to make a clear distinction between controls and links that are related to the wiki as a whole, and those that are related to the page of the wiki that you're currently viewing or editing. To do this, the search box, new page link, and other controls have all been placed in the sidebar. Metadata and other page specific controls have been consolidated into the page header. Of course, if you want your wiki to have a different style to it, wiki templates can still be customized.

Here's a screenshot of my wiki page for writing this response:

alt text

There are more details on what's new with the FogBugz 8 default template here.




Exporting Wiki Articles

Print to PDF We recommend viewing the wiki article in your browser and using print to pdf. You can adjust your template for the wiki to format it best for printing. On Mac, choose Save to PDF... from the print dialog box. On Windows, grab a free tool such as CutePDF.

Programmatic exports. If you need to export many pages or export programmatically, there are many options, all fairly complex. Here are some basics:

  • Wiki articles are stored in the database as raw html - good
  • Intra-wiki and case links are relative - tricky
  • Embedded images and attachments' URLs can be accessed programmatically by adding an XML API logon toke to the end - good
  • If you use plugins in your wiki such as the Table of Contents or other Wikiblock plugins, these only put a placeholder in the HTML which is dynamically replaced on render - tricky

Some things to try:

  • Have your live documentation site use the XML API to pull the article's HTML when the user requests a document on your site. The script on your site would then need to fix relative links. You would also need to make sure the wiki is publicly accessible so images and attachments work, or store an API logon token in the script on your site for fetching them.
  • Spider the wiki either as a user would, or better with the XML API. convert links, etc, apply styles and save the documents in your desired format. See this answer for an outline.

To those who can edit: feel free to add any accumulated knowledge from your own export efforts




Associating a Wiki with a Project

This functionality is added by the Wiki Article: Case Relationships plugin, which was developed by DevMental Software. I believe that this does two important things:

  1. It allows articles in that particular wiki to be cross-referenced from cases in the same project
  2. It associates the permissions for the project with the wiki



Source Code Control System Integration

FogBugz can be set up to work together tightly with most source control systems. When you commit a bug fix to source control, you simply type the case number that you're fixing. The integration scripts see this and create bidirectional links:

  1. From the FogBugz case to the source control history and diffs
  2. From the source control system to the FogBugz case.

The benefits:

  • You can implement a code-review process. Simply assign a case to the code reviewer. They click on the links to see the diffs in the source control system and review them.
  • It's easy to find out how a bug was fixed by jumping straight to the source code change.
  • When you're looking at the changes made in the source code and wondering why they were made, you can quickly jump to the bug they were intended to fix.

The exact mechanism for entering a case number when you commit changes depends on your source control system.

Before you can start using source control integration, you will need to make a few configuration changes to FogBugz and your source control system so they can talk to each other.

If you don't already have source control, we recommend Kiln.

Using Source Control Integration

When you have everything setup, source control integration in FogBugz allows you to associated changes you commit with a given case or cases. When you commit your changes in VCS, your hook script will look for something in your commit message that gives it a case number. For the scripts we distribute, the format is "BugzID: XYZ" where XYZ is a case number. The hook script then posts the info to FogBugz.

When you look at the case you referenced (number XYZ) in FogBugz, you will see a link on the left side of the case, "checkins".

alt text

When you click the link, a pop-up dialog appears, showing all of the files and revisions committed against the case.

alt text

Based on your configured URLs in Admin -> Source Control, the file paths and revision numbers will link to an external system to show you file and diff views.




Integrating with Subversion

There are two aspects to setting up FogBugz-Subversion integration:

  1. Getting Subversion to transmit changes to FogBugz
  2. Getting FogBugz to provide links to WebSVN, the web-based Subversion repository browser
Setting up the repository in FogBugz

The starting point for setting up source control integration is to create the repository in FogBugz. To do so, log into FogBugz as an administrator and go to Admin | Source Control. Click Create New Repository. In the resulting dialog, select Subversion as the type and give the repository a display name. Click Next.

alt text

The resulting dialog contains scripts and instructions for getting Subversion to transmit changes to FogBugz. Those instructions are provided in more detail below. Select the appropriate tab for the server Subversion runs on and download the scripts. Before you close the dialog, choose whether you want FogBugz to provide links to your check-ins. You can change this setting later by clicking the Edit icon next to the repository on the Admin | Source Control page.

Diff and log links

In order to have FogBugz link to checked-in files directly from cases, you need something that allows you to view file diffs and history logs from a web browser. We recommend WebSVN. You can also setup FogBugz to link to logs and diffs in Trac. Once you have WebSVN or Trac installed and working with your Subversion repository, set the path to it in the New Repository dialog and click OK to complete the setup.

Getting Subversion to transmit changes to FogBugz

If your Subversion server is Linux or Unix, make sure that Perl is installed. If your Subversion server is Windows, make sure it has Windows Scripting version 5.6 or later installed.

Put the logBugDataSVN and post-commit scripts you downloaded above into Hooks directory in your Subversion repository. If your SVN repository is on Unix, grant execute permissions on both files (chmod +x filename). If you already have a post-commit script, you will need to merge it with this one.

TortoiseSVN

If anyone on your team uses TortoiseSVN, a Subversion client for Windows, follow these steps to configure it to prompt for case numbers when you enter log messages.




Entering case numbers in Subversion

When you commit a change using Subversion, include a single line of the form BugzID: case number in the log after the other comments, for example:

alt text




Troubleshooting Subversion Integration

FogBugz Subversion Source Control integration consists of two parts:

  1. a trigger script run from the source control system to notify FogBugz of a checkin
  2. a link in FogBugz to a web front end of the source control system
If you check in a file and don't see any corresponding info appear in the FogBugz bug:
  • Make sure you are using the correct syntax when referring to the case. Try BugzID:1 (if you have a case number 1)

  • See if the trigger is running.

    1. The post-commit script for Subversion has a line at the end that says

      rm /var/tmp/$LOGSVNCHANGEFILE (unix)

      del %temp%\%logsvnfile% (windows)

    2. Add a # character to the beggining of this line so after the commit runs it does NOT delete the file in /var/tmp (or c:\temp, c:\windows\temp)

    3. Run a commit again and validate the file is there

    4. If the file is not there, try running the post-commit script directly (to make sure the problem is not svn failing to run it):

      1. Go to your svn hooks directory

      2. Run post-commit /path/to/svn/root/directory 1234 where the first argument is the root directory of your svn directory and "1234" is a revision number containing a fogbugz case id. If anythings goes wrong, you will see it on your console output.

  • See if the logBugDataSVN file is working. The easiest way to do this is to call it from the command line. (In the commands below, replace $REV with a valid revision number and $REPOS with the path to your repository.)

    Unix:

       svnlook changed -r $REV $REPOS > /var/tmp/svnfile

       svnlook log -r $REV $REPOS | perl /path/to/logBugDataSVN.pl $REV /var/tmp/svnfile $REPOS

    Windows:

    svnlook changed -r $REV $REPOS > /var/tmp/svnfile

    svnlook log -r $REV $REPOS | cscript /path/to/logBugDataSVN.vbs $REV /var/tmp/svnfile $REPOS

    1. If the above lines DID make an entry on your case, focus on the post-commit script. It's likely that svnlook is not in the scripts path and you need to rewrite those lines in the script to use the full path to svnlook. Or the user that subversion runs as may not have permission to run cscript.exe (on windows).

    2. If the above lines DID NOT make an entry on your case, logBugDataSVN is failing. If you are using On Demand, or have a SSL FogBugz install, one of the most common reasons for logBugDataSVN.pl failing is the script cannot find wget. At the top of the script it may say $wget_path = `which wget`; and you should change this to $wget_path = "/actual/path/to/wget";

      Also at the bottom of the script you should change the line that calls system to be system("$wget_path --no-check-certificate '$url' -q -O /dev/null");

If the info is actually getting into FogBugz but the link back to WebSVN is not working:
  • Outside of FogBugz navigate to your site and make sure WebSVN is working on its own. Note the URLs that it is using and make sure you have set the appropriate pointers to this install. You can edit the URLs by editing your repo settings in Admin -> Source Control

  • If you are using an older version of FogBugz and you see %2F in the URLs where you should see "/", change your Apache AllowEncodedSlashes configuration.

If none of that works...

These steps work for most people, but not all.

If you're still having trouble, go to http://contact.fogcreek.com and contact us. Friendly people are standing by to help!




Setting up TortoiseSVN Source Control Integration

If anyone on your team uses TortoiseSVN, a Subversion client for Windows, follow these steps to configure it to prompt for case numbers when you enter log messages.

First, make sure FogBugz and your Subversion server are both setup for integration by following these steps. Next, setup your TortoiseSVN clients:

  • Check out your repository
  • cd to the root directory of your checkout
  • Run the following commands from the command line. Notice the dots which are important.

    svn propset bugtraq:label "BugzID:" .

    svn propset bugtraq:url "http://Your FogBugz URL/default.asp?%BUGID%" .

    svn propset bugtraq:message "BugzID: %BUGID%" .

    svn propset bugtraq:number "true" .

    svn propset bugtraq:warnifnoissue "false" .

    svn commit -q -m "Added BugzID properties to the repository"

  • If you would prefer to run these commands from a batch file, you need to escape the % signs by doubling them to prevent the batch file from replacing them with nothing.

    svn propset bugtraq:label "BugzID:" .

    svn propset bugtraq:url "http://Your FogBugz URL/default.asp?%%BUGID%%" .

    svn propset bugtraq:message "BugzID: %%BUGID%%" .

    svn propset bugtraq:number "true" .

    svn propset bugtraq:warnifnoissue "false" .

    svn commit -q -m "Added BugzID properties to the repository"

  • Tortoise will search up your folder path on a checkout looking for this property, so if you checkout from other folders in your tree, be sure to do the same procedure for those folders also. We used to ask people to execute the above commands with the -R flag to do this recursively, but it has been reported that this can slow down Subversion. More details are available in this guide.




How can we enter case numbers using TortoiseSVN?

When you commit a change to a Subversion repository using Tortoise-SVN, enter the case number in the BugzID edit box at the top right corner of the Enter Log Message dialog:

alt text




CVS Source Control Integration

There are two aspects to FogBugz-CVS integration:

  • Getting CVS to transmit changes to FogBugz
  • Getting FogBugz to provide links to CVSweb, the web-based CVS repository browser
Setting up the repository in FogBugz

The starting point for setting up source control integration is to create the repository in FogBugz. To do so, log into FogBugz as an administrator and go to Admin | Source Control. Click Create New Repository. In the resulting dialog, select CVS as the type and give the repository a display name. Click Next.

alt text

The resulting dialog contains a script and instructions for getting CVS to transmit changes to FogBugz. Those instructions are provided in more detail below. Select the appropriate tab for the server CVS runs on and download the script. Before you close the dialog, choose whether you want FogBugz to provide links to your check-ins. You can change this setting later by clicking the Edit icon next to the repository on the Admin | Source Control page.

Diff and log links

In order to have FogBugz link to checked-in files directly from cases, you need something that allows you to view file diffs and history logs from a web browser. We recommend CVSweb (If you run CVSNT on Windows, you can use CVSWEB NT). Once you have CVSWeb installed and working with your CVS repository, set the path to it in the New Repository dialog and click OK to complete the setup.

Getting CVS to transmit changes to FogBugz

Check out the CVSROOT directory.

alt text

Find the logBugData script you downloaded above and copy it into your CVSROOT directory. Add it to the repository with cvs add.

alt text

If your CVS server is Linux or Unix, make sure that Perl is installed. If your CVS server is Windows, make sure it has Windows Scripting version 5.6 or later installed.

Edit the file loginfo, adding one line at the end as shown below. Change the file path shown here to point to the logBugData file in your CVS repository on your CVS server.

Using Perl on Unix:

ALL perl -s /path to cvs/logBugData.pl "%{sVv}"

Using Perl on Windows:

ALL perl -s C:\\path to cvs\\logBugData.pl "%{sVv}"

Using VBScript on Windows:

ALL cscript.exe C:\\path to cvs\\logBugData.vbs "%{sVv}"

alt text

Edit the file checkoutlist, adding the following line at the end as shown in these examples:

Using Perl:

logBugData.pl Error-logBugData.pl

Using VBScript:

logBugData.vbs Error-logBugData.vbs

alt text

Check in your changes.

alt text

If your CVS repository is on Unix make sure to set execute permissions on the logBugData.pl file (chmod +x logBugData.pl).

Here's a screenshot of a check-in that successfully connected to FogBugz (this screenshot is of CVSNT on Windows, utilizing logBugData.vbs, that's why you see "Windows Script Host" poking its face in):

alt text

Notice that it says "Adding bug info for Bug ID #1" -- this means that when you view bug number 1 in FogBugz you see the check-in in the left hand column.




Entering case numbers in CVS

When you commit a change using CVS, include a single line of the form BugzID: case number in the log after the other comments, for example:

alt text




Perforce Source Control Integration

There are two aspects to setting up FogBugz-Perforce integration:

.1 Installing either trigger scripts or the Perforce Defect Tracking Gateway so that Perforce transmits changes to FogBugz 2. Getting FogBugz to provide links to P4Web, the Perforce web client

Setting up the repository in FogBugz

The starting point for setting up source control integration is to create the repository in FogBugz. Start by logging into FogBugz as an administrator. If you will be using the Perforce Defect Tracking Gateway (DTG), install and enable the Perforce DTG Integration plugin.

To setup the repository in FogBugz, go to Admin | Source Control. Click Create New Repository. In the resulting dialog, select Perforce as the type and give the repository a display name. Click Next.

alt text

The resulting dialog contains a script for getting Perforce to transmit changes to FogBugz. Select the appropriate tab for the server Perforce runs on to use triggers, or DTG for the Perforce Defect Tracking Gateway (DTG). Download the script and follow the instructions below to set it up. Before you close the dialog, choose whether you want FogBugz to provide links to your check-ins. You can change this setting later by clicking the Edit icon next to the repository on the Admin | Source Control page.

Diff and log links

In order to have FogBugz link to checked-in files directly from cases, you need to have P4Web installed. Once it is installed and working with your Perfoce repository, set the path to it in the New Repository dialog and click OK to complete the setup.

Getting Perforce to transmit changes to FogBugz

We provide trigger scripts for Perforce in Perl or VBScript, depending on whether your Perforce server is running on Unix, where Perl is probably installed, or Windows, where VBScript is probably installed.

Instructions for Perl

Download and customize the trigger Perl script.

  1. Follow the instructions above to setup the Perforce repository in FogBugz. Download the logBugDataP4.pl script.
  2. Put it in the directory that contains your Perforce server executable (for example, c:\Program Files\Perforce).
  3. Edit the file. Look for the variables $P4USERNAME and $P4PASSWORD and set them to the Perforce username and password you want to use. Perforce passwords cannot be accessed from trigger scripts, so the good folks at Perforce will give you a free "background" or "automation" user for this purpose. Please contact them at support@perforce.com to pursue this option. If you do NOT have Perforce passwords enabled, leave $P4PASSWORD blank.
  4. By default, the Perforce script sends changelists, not individual files (so you will see only one line in FogBugz for a changelist containing 40 files, instead of 40 lines). If you want to change this, look for the variable $CHANGELIST_ONLY and set it to 0.

Perforce will let you call an executable every time files are submitted (actually, just before the submission occurs). This is called a trigger. We want to use a trigger to call the logBugDataP4.pl file every time any files are submitted in Perforce. To do this, do the following:

  1. Type p4 triggers on the command line (or cmd window). A text file appears in your editor. (If it doesn't, make sure the full path to p4 is in your path.)
  2. To add the FogBugz trigger you need to add a line to at the bottom of this file. The trigger looks slightly different depending on what version of Perforce you use: Perforce Version 2003.2 - all triggers are of type "submit", no need to specify type: FogBugzTrigger //... "C:\path\to\your\perl.exe C:\path\to\your\logBugDataP4.pl %changelist% %serverport% %client%" Perforce Version 2004.2 - you must specify the type of trigger as "submit": FogBugzTrigger submit //... "C:\path\to\your\perl.exe C:\path\to\your\logBugDataP4.pl %changelist% %serverport% %client%" Perforce Version 2005.2 - you must specify the type of trigger as "change-submit": FogBugzTrigger change-submit //... "C:\path\to\your\perl.exe C:\path\to\your\logBugDataP4.pl %changelist% %serverport% %client%" Note that this new line has a tab at the beginning. Adjust the path to the Perl interpreter and the path to the logBugDataP4.pl file to make sure it points to logBugDataP4.pl on your server (wherever you put it). IMPORTANT: The paths in the trigger cannot contain any spaces. A path with spaces in it will generate an error like the following: Input Error: There is no file extension in "C:\Program".
  3. Save this temporary file and exit the editor. The trigger is now added.

If you don't see the checkin entries in the FogBugz case, here is some troubleshooting help:

Instructions for VBScript

Download and customize the trigger VBScript.

  1. Follow the instructions above to setup the Perforce repository in FogBugz. Download the logBugDataP4.vbs script.
  2. Put it in the directory that contains your Perforce server executable (for example, c:\Program Files\Perforce).
  3. Edit the file. Look for the variables P4USERNAME and P4PASSWORD and set them to the Perforce username and password you want to use. Perforce passwords cannot be accessed from trigger scripts, so the good folks at Perforce will give you a free "background" or "automation" user for this purpose. Please contact them at support@perforce.com to pursue this option. If you do NOT have Perforce passwords enabled, leave P4PASSWORD blank.
  4. By default, the Perforce script sends changelists, not individual files (so you will see only one line in FogBugz for a changelist containing 40 files, instead of 40 lines). If you want to change this, look for the variable CHANGELIST_ONLY and set it to 0.

Perforce will let you call an executable every time files are submitted (actually, just before the submission occurs). This is called a trigger. We want to use a trigger to call the logBugDataP4.vbs file every time any files are submitted in Perforce. To do this, do the following:

  1. Type p4 triggers on the command line (cmd window). A text file appears in your editor. (If it doesn't, make sure the full path to p4 is in your path.)
  2. To add the FogBugz trigger you need to add a line to at the bottom of this file. The trigger looks slightly different depending on what version of Perforce you use: Perforce Version 2003.2 - all triggers are of type "submit", no need to specify type: FogBugzTrigger //... "cscript.exe C:\path\to\your\logBugDataP4.vbs %changelist% %serverport% %client%" Perforce Version 2004.2 - you must specify the type of trigger as "submit": FogBugzTrigger submit //... "cscript.exe C:\path\to\your\logBugDataP4.vbs %changelist% %serverport% %client%" Perforce Version 2005.2 - you must specify the type of trigger as "change-submit": FogBugzTrigger change-submit //... "cscript.exe C:\path\to\your\logBugDataP4.vbs %changelist% %serverport% %client%" Note that this new line has a tab at the beginning. Adjust the path to the logBugDataP4.vbs file to make sure it points to logBugDataP4.vbs on your server (wherever you put it). IMPORTANT: The paths in the trigger cannot contain any spaces. A path with spaces in it will generate an error like the following: Input Error: There is no file extension in "C:\Program".
  3. Save this temporary file and exit the editor. The trigger is now added.

Instruction for Perforce DTG Intergration

If you have a Windows server which can access your Perforce server, you can use the Perforce Defect Tracking Gateway (DTG) instead of setting up trigger scripts. If you do this, FogBugz cases will appear in Perforce as Perforce Jobs and you can apply changelists to them directly.

There are three essential components for setting up the DTG integration:

(1) The Perforce Defect Tracking Gateway (DTG) (installed on your server)

The Perforce DTG, created and supported by Perforce, provides a service that does the following:

  • Periodically query any configured defect tracking systems for case information, and then update or create an associated job in Perforce.
  • Periodically query Perforce for any new changesets, and send the information to the associated defect tracking system.

Note that by default, the Perforce DTG does not have any FogBugz integration.

Setup

  1. Download the DTG Setup program from the Perforce downloads page.
  2. Run the setup program and follow the instructions provided.

(2) The FogBugz DTG Integration Plugin (installed in FogBugz)

DTG integration in FogBugz requires that the FogBugz plugin be installed. The plugin configures FogBugz to accept changesets from the Perforce DTG, and allows downloading the FogBugz - Perforce DTG link for step 3.

Setup for Licensed FogBugz Users:

  1. Download the Perforce DTG Integration plugin .zip file from the FogBugz Plugin Gallery.
  2. In your FogBugz installation, navigate to Admin > Plugins
  3. Click "Upload Plugin", and select the .zip file

Setup for FogBugz On Demand Users:

  1. In your FogBugz installation, navigate to Admin > Plugins
  2. Click the link to the FogBugz Plugin Gallery
  3. Find the Perforce DTG Integration and click "Install"
  4. You should be redirected back to your FogBugz account, and asked to confirm if you want to install the plugin. Click "OK" to install.

(3) The FogBugz-P4DTG Link (installed on your server)

By default, the DTG does not have FogBugz support installed. To add FogBugz support, and configure the DTG to communicate with FogBugz, you must install the FogBugz-P4DTG Link.

Setup:

  1. Create a new Perforce repository
    1. In your FogBugz account, navigate to Admin > Source Control
    2. Click "Create New Repository"
    3. Select "Perforce" and select a name for the repository
    4. Click OK
  2. Install the FogBugz-P4DTG Link
    1. Click the edit link on the Perforce Repository
    2. Select the DTG tab
    3. Click the link to the Perforce DTG Integration Setup (Enter your Perforce server, user, and password, and FogBugz user and password; Select the fields you wish to copy to Perforce; Click OK)
    4. Download and run the setup program
    5. When prompted, enter the location of the Perforce DTG installed previously (typically C:\Program Files\Perforce\p4dtg)
    6. After installation is done, you'll need to update your Perforce jobspec and configure the plugin (If you're already logged in as a Perforce administrator, the setup program will launch the jobspec editor automatically. If not, you'll need to log in as a Perforce administrator and enter p4 jobspec on the command line (cmd window), or type p4 jobspec -u [admin user name] -P [admin password]; Copy the lines given by the setup page in FogBugz into your jobspec; Save and close the window)
    7. Setup should automatically open the configuration editor. You can also find this program in [Your Perforce DTG install]\p4dtg-config.exe.
    8. Check that each tab indicates that the configuration is correct, as described in the setup page
    9. On the final tab, click "Start Replication" to start the replication engine
Getting FogBugz to provide links to P4Web, the Perforce web client

In order to browse a Perforce repository, you need something that allows you to view file diffs and history logs from a web browser. With Perforce, you use P4Web, the Perforce Web Client.




Entering case numbers in Perforce

How you enter the case depends on how you've set up your Perforce - FogBugz integration.

Using Perforce Trigger Script

When you commit a change using Perforce, include a single line of the form BugzID: case number in the change specification after the other comments. For example:

alt text

Using Perforce DTG integration

To submit changes to a FogBugz case, simply apply a job fix to the changelist for the corresponding job.

You can do this from the command line by typing (where job000021 is the job that corresponds to your case)

p4 fix -c 324 job000021

Or from one of Perforce's graphical tools by finding the option to add a job fix to a changelist and simply selecting the job(s) from a list:

alt text

Note that you'll probably want to Filter the results to find the case that you want. Here are some useful filters for finding your cases:

  • Search for all cases with the word "Perforce" in them by filtering on: Perforce
  • Search for all cases assigned to you by filtering on: FB_Assigned_To=[Your Name]
  • Search for all active (not resolved or closed) cases assigned to you by filtering on: FB_Status=Active FB_Assigned_To=[Your Name]
  • Search for all active cases assigned to you with the word "Perforce" in them by filtering on: FB_Status=Active FB_Assigned_To=[Your Name] Perforce

You can use these filters from the command line or from the graphical tools.




Visual SourceSafe Integration

There are two aspects to setting up FogBugz-Visual SourceSafe integration:

  1. Getting VSS to transmit changes to FogBugz
  2. Getting FogBugz to display VSS diffs and logs
Setting up the repository in FogBugz

The starting point for setting up source control integration is to create the repository in FogBugz. To do so, log into FogBugz as an administrator and go to Admin | Source Control. Click Create New Repository. In the resulting dialog, select VSS as the type and give the repository a display name. Click Next.

alt text

In the resulting dialog, download the script necessary to get Visual Source Safe (VSS) to transmit changes to FogBugz. Instructions for setting it up are provided below. Before you close the dialog, choose whether you want FogBugz to provide links to your check-ins. You can change this setting later by clicking the Edit icon next to the repository on the Admin | Source Control page.

Diff and log links

There are two ways to have FogBugz link to checked-in files directly from cases.

The first is to set up VSS to run on the same machine as FogBugz so that you can use our internal tools. If this is not feasible for you, you can install a separate instance of FogBugz on IIS on the VSS machine, whose sole purpose is to read VSS files and show you the diffs and logs. Be sure the FogBugz user in that IIS has permissions on the VSS files on that server as specified above.

The second method, for FogBugz On-Demand users and those who do not wish to install FogBugz on the same machine that runs VSS, is to use VSS Remoting to display diffs and logs. For this method, set the path to VSS Remoting in the New Repository dialog and click OK to complete the setup.

Getting VSS to transmit changes to FogBugz

Edit the vss_fbupdate.wsf file you downloaded above as follows:

  • Set the FB_VSS_USER and FB_VSS_PASSWORD variables to the user name and password FogBugz will use to connect to VSS.
  • If you are using FogBugz in another language, you will need to update the strings FogBugz checks from the journal.txt file. In particular, the sItemVersion and sItemAction comparisons will need to be updated.

Find out the path to your VSS database directory. For example:

C:\Program Files\Microsoft Visual Studio\Common\VSS

You can identify the VSS database directory because it contains a file named SrcSafe.ini. (Read more at Microsoft's website).

In vss_fbupdate.wsf, look for the commented-out line

'Call ProcessVSSJournal("Project Name", "Path to VSS Database directory")

Uncomment this and make a copy of each VSS project you have. For example:

Call ProcessVSSJournal("Test", "C:\Program Files\Microsoft Visual Studio\Common\VSS")

Note: If you are using MySQL, you cannot have an underscore in the file path, since it will be replaced by MySQL with a dash, and you cannot use a backslash \ since MySQL will interpret that as an escape character, so use forward slashes (/)instead.

For each VSS Database you have, run the Admin Console and choose Tools | Options. Make sure it is set to create a file called journal.txt in the VSS Database directory.

Using the example above, the "Log all actions in journal file" would point to "C:\Program Files\Microsoft Visual Studio\Common\VSS\journal.txt".

alt text

If VSS says no such path exists, try using a UNC path (\server\share...). You will then have to use this in vss_fbupdate.wsf as well.

Set the vss_fbupdate.wsf file to run as a scheduled task every so often -- at least hourly, or even more often if you like. The task will complete very quickly so don't worry about running it too often.

Make sure this scheduled task runs as a user that has privileges to rename/delete files in the VSS directories (usually NOT the FogBugz user, but instead an admin on the machine). Use the //B option to wscript so the script does NOT run in interactive mode:

c:\winnt\system32\wscript.exe //B "C:\Program Files\fogbugz\accessories\SourceControl\vss\vss_fbupdate.wsf"

Make sure that the FogBugz user (or whomever you installed FogBugz to run as) has READ access on all your VSS folders and all subfolders. The user must also have FULL CONTROL on the names.dat and the rights.dat files, and the LoggedIn directory. Also it must have FULL CONTROL ON THE SSUS.DLL and SSAPI.DLL in order to create the SourceSafe COM object.




Entering case numbers in Visual SourceSafe

When you check in a file using Visual SourceSafe, include a single line of the form BugzID: case number in the log after the other comments, for example:

alt text




SourceGear Vault Integration

Integration

To enable bug tracking in SourceGear Vault, you must have Vault admin privileges and access to the Vault Admin Tool.

In Vault
  1. Log on to the Vault Admin Tool
  2. Click on the Admin tab
  3. Expand Source Control Repositories on the left side
  4. Click on the repository you are setting up
  5. Set the Bug Tracking Application drop-down to FogBugz
  6. In the Bug Tracking Integration URL box, type in the URL of your FogBugz site, something like:

    http://www.example.com/FogBugz

alt text

In FogBugz

When you go to Admin -> Source Control, click Create New Repository, select Vault and click ok, FogBugz will tell you that the repository is created in FogBugz automatically when you first checkin code in Vault and set a case number for it.

alt text

alt text

When you commit your first checkin, you will now see the repository in the list in Admin -> Source Control. At this point, you can click to edit that repository and setup the diff and log links. These links show up in FogBugz cases as shown here.

alt text

Entering Case Numbers

The Vault Check In/Commit dialog allows you to associate a Vault file with a FogBugz case during the check in process. Type the case number in the Update Bugs edit box.

Requirements

Vault <-> FogBugz integration is only supported by Vault Standard, not Vault Professional.




Mercurial Integration

Getting Mercurial to transmit changes to FogBugz

To setup Mercurial-FogBugz integration, start by logging into FogBugz as an administrator and going to Admin | Source Control. Click Create New Repository. In the resulting dialog, select Mercurial as the type and click Next.

In the resulting dialog, download the Python script and place it anywhere that's visible to the Mercurial server process. It should not be in your hgext directory.

To enable the script, edit the .hg/hgrc file in your repository by adding the following lines:

[hooks]
changegroup = python:/path/to/fogbugz.py:hook

You will then need to configure the FogBugz extension so that it knows where to locate your FogBugz install. Simply add the following lines, edited appropriately, into your .hg/hgrc file:

[fogbugz]
host=http://full/path/to/fogbugz

Finally, you should set your baseurl to make sure that the appropriate repository location is passed along to FogBugz. Baseurl is the web URL to where the "hg serve" web server is running for the provided repository.

[web]
baseurl=http://url/of/your/repo
Getting FogBugz to Provide Hyperlinks to Mercurial

Assuming you supplied the right value for baseurl in your hgrc file, FogBugz will automatically link to logs and diffs in Mercurial. If you do not have hg serve running, then although FogBugz will record changesets, the links back from FogBugz will not point anywhere meaningful.




Entering case numbers using Kiln and/or Mercurial

When you commit a change using Mercurial, include a single line of the form BugzID: case number in the log after the other comments.




Team Foundation Server Integration

There are two aspects to setting up FogBugz-Visual SourceSafe integration:

  1. Getting Team Foundation Server (TFS) to transmit changes to FogBugz
  2. Getting FogBugz to provide links to Team System Web Access 2008, the web-based repository browser
Setting up the repository in FogBugz

The starting point for setting up source control integration is to create the repository in FogBugz. To do so, log into FogBugz as an administrator and go to Admin | Source Control. Click Create New Repository. In the resulting dialog, select Team Foundation as the type and give the repository a display name. Click Next.

alt text

In the resulting dialog, download the script necessary to get TFS to transmit changes to FogBugz and choose whether you want FogBugz to provide links to your check-ins. You can change this setting later by clicking the Edit icon next to the repository on the Admin | Source Control page.

Diff and log links

FogBugz can provide links to a site that displays diffs and logs for changes connected to a case. In version 2008, Team Foundation Server itself does not include web-based diff and log viewing capabilities, but Microsoft provides a free application called Team System Web Access 2008 that can display diffs and logs from a web browser. TFS 2010 includes this by default. Once it is installed and working, set the path to it in the New Repository dialog and click OK to complete the setup. For TFS 2010, this should be www.example.org:8080/tfs/web

Note: Team System Web Access 2005 (and therefore Team Foundation Server 2005) will not work with web-based diffs and logs, since it doesn't allow direct links to logs and diffs.

Getting Team Foundation Server to transmit changes to FogBugz

On your application tier Team Foundation server, run the register-fogbugz.bat script you downloaded above. The script will prompt you to confirm the Team Foundation Server URL; it will then register FogBugz for notifications. After successfully completing this step, you can delete the batch file; it is no longer needed.




Entering case numbers using Team Foundation Server

When you commit a change using Team System, include a single line of the form BugzID: case number in the log after the other comments, for example:

alt text




Generic Integration Instructions for Other Source Code Control Systems

If your source control system is not listed elsewhere on this stie, you can still integrate it with FogBugz. There are two aspects to source control integration:

  1. Getting your source control system to transmit changes to FogBugz
  2. Getting FogBugz to provide links to a URL that shows diffs and history logs from your source control system
Getting your source control system to transmit changes to FogBugz

You need to install a "trigger" script in your source control system to notify FogBugz whenever a check-in occurs that is related to a particular bug.

The way these scripts work is they send the check-in information via HTTP to a FogBugz ASP page named cvsSubmit.asp, using a URL like:

http://your.fogbugz.server/cvsSubmit.asp?ixBug=bugID&sFile=file&sPrev=x&sNew=y&ixRepository=RepositoryID

Where:

  • bugID is the FogBugz bug number
  • file is the source file that is being checked in
  • x is the previous revision number
  • y is the new revision number
  • RepostioryID is the ID of the repository you create in FogBugz. You can get this value from the New Repository dialog (see below).

Alternately, you could write a script that notifies FogBugz by using a data access library such as ODBC or OLEDB to insert a new record directly in the table named CVS containing the above four values. You can view your FogBugz database schema at http://your.fogbugz.server/?pg=pgSchema

Getting FogBugz to Provide Hyperlinks to Your Source Control Viewer

Log into FogBugz as an administrator and go to Admin | Source Control. Click Create New Repository. In the resulting dialog, select Other (custom) as the type and give the repository a display name. Click Next.

alt text

Under Diff URL, enter the URL of your source control system diff viewer.

In this URL, ^FILE will be replaced with the file name, ^R1 will be replaced with the old version number, and ^R2 will be replaced with the new version number.

Under Log URL, enter the URL of your source control system history viewer.

In this URL, ^FILE will be replaced with a file name for which FogBugz wants to display the history.




BugzScout to Capture Errors

BugzScout is included with every licensed (for-your-server) FogBugz installation as well as FogBugz On Demand. The URL of this API is http://your.fogbugz.url/scoutSubmit.asp (for pre-FogBugz 7 on Linux/Mac, it's scoutSubmit.php). This URL is an entry point for automatic bug submissions. The way it works is that you create an HTTP post containing the values that it expects to receive, and post that directly to scoutSubmit on your web server. (If your web server is behind a firewall, remember to allow the scoutSubmit file to be seen by the public, but not the other ASP/PHP files on your FogBugz installation.)

How do I submit bugs to scoutSubmit?

For Licensed FogBugz, included in your FogBugz/accessories folder there is a zipped folder called ScoutSample.zip which contains examples for the two methods of sending this HTTP post. If you are using FogBugz On Demand, you can download the sample code here.

  • scoutsample.html
    An HTML form that posts to scoutSubmit. Just open this in your browser and follow the directions on the form, it's easy to use.
  • ScoutSample.vbp
    Included with Licensed FogBugz, this is a simple VB project that shows you how to interact programatically with our free BugzScout ActiveX control (BugzScout.dll in the Accessories folder), which packages up the values for you and posts them via HTTP to scoutSubmit.asp. If you do not have the tools to open a VB project, you can click here to view some of the source code for the form - we stripped out the UI stuff and left in the parts that interact with the BugzScout control.
    ScoutSample.exe is the compiled result of this VB project, just double click on it to run it. Click here to see the interface, with usage tips for the fields involved.
  • The XML API
    You can also submit cases using the XML API and specify that they are BugzScout cases. This allows you to take advantage of the many features of the API, while still getting the benefits of BugzScout (automatically appending to existing cases, occurance count, etc). The trade-off is that it requires a logon token.
How are these bugs handled within FogBugz?

Duplicate bug submissions: If the description field of a bug submitted via scoutSubmit matches exactly to any existing bug, this new submission will be APPENDED to the existing bug's history, and a new bug will NOT be created in FogBugz. (You can over-ride that behavior if you set ForceNewBug to 1 or "true".) The following two things will also happen:

  • The "occurrences" field for the existing bug will increase by 1. (The "occurrences" field of a bug, e.g. "3 occurrences", appears only when there are more than one occurences of that bug. In FogBugz 3.x it is present only in the List view, not the Grid view.)
  • FogBugz will return a status message to the person who submitted the bug. If there is already a case in FogBugz with the same description as this new bug, and that case has a "Scout Message" specified, that message will be returned to the customer. Otherwise, the "ScoutDefaultMessage" text will be returned to the customer. An example of a default message could be something general like "Thank you, your bug report has been received." 

When you Edit a bug submitted via scoutSubmit, you have these two new fields:

  • Scout Msg
    Type in a custom message to be returned to the next person who submits this same bug, i.e. if and when a bug with the same description is submitted again. You could use this to provide the user with instructions for a workaround for this bug, or tell the user that this bug has been fixed for the next release.
  • "Scout Will"...
    This controls whether or not future duplicates of this case will be appended to this case. If it is set to "Stop Reports", future submissions with the same description will not be added to FogBugz in any way. "Continue Reporting" simply means that future duplicates will continue to be appended to this case.

For more information on automatically collecting bugs from the field, see the 7.0 help doc for BugzScout (applies to FogBugz 8 as well).




Evidenced-Based Scheduling (EBS)

FogBugz uses a sophisticated statistical algorithm called Evidence-Based Scheduling (EBS) to produce ship date probability distributions. EBS was developed at Fog Creek Software, and is exclusive to FogBugz.

EBS uses a statistical method called bootstrapping that we have found does a very good job of predicting software schedules.

The first time you use EBS, it will probably come up with a ship date that seems much later than you were hoping for, and you might despair. But after a while, you'll understand why it's doing this, and you'll see that the schedule that EBS generated, pessimistic though it seemed, was actually right on the mark. EBS is an algorithm that understands why software projects come in late and actually incorporates that into its estimates, mathematically. EBS actually looks at the historical track records of every person who enters estimates, and assumes that the future will look a lot like the past.

How the algorithm works

EBS doesn't give you a single ship date. Instead, it produces a probability distribution curve. That means that for any given date, it tells you what the probability is that you will ship by that date.

alt text

To do this, EBS needs to keep track of the historical track record of each estimator. An estimator's track record is just a list of all the features that they estimated which were implemented and closed. In order to be considered a historical estimate for a user, a case must be estimated by that user, have time charged against it, and then be resolved and closed. The resolution must be "Completed", "Fixed", "Implemented", or "Responded." For each completed feature, EBS looks at the original estimate entered and the actual time elapsed. It divides estimate by elapsed to get the velocity of that feature's implementation. A feature that takes twice as long as expected has velocity 0.5.

EBS collects as many as 200 recent velocities from each estimator. If an estimator has no historical track record or has fewer than six completed features, EBS backfills that track record with six velocities that reflect a very poor estimator. This way, in the absence of historical data, EBS assumes the worst about the estimator.

alt text

Once EBS has a track record for each estimator, it can simulate the future. EBS does this simulation 60 times. In each round of the simulation, and for every feature that needs to be implemented, it uses a velocity randomly chosen from the estimator's track record.

When EBS calculates the schedule repeatedly, for 60 possible futures, it assumes that each possible future will occur with 1/60th probability. This gives it a probability distribution curve with 60 data points.

To make a schedule for one developer, EBS adds up all the estimates of that developer's features to get a total number of hours of work. But instead of actually taking the estimates at face value, it uses adjusted estimates, which reflect the estimator's historical track record.

To get an adjusted estimate, EBS starts with the estimates entered into FogBugz (minus elapsed time). Then it picks a pseudo-random number n between 1 and x, where x is the number of velocities in the estimator's track record. It then sorts the velocities in ascending order and picks out the nth velocity from the list. Since n is real, it actually picks the two closest velocities - the (floor(n))th and the (floor(n+1))th - and interpolates linearly between them to get a single velocity. In other words, EBS picks a random velocity with the same distribution as that estimator's historical velocities.

Next, EBS divides the entered estimate for the feature by the randomly chosen velocity and uses this as the adjusted estimate for this particular imagined future. Unless every estimator has a perfect track record, each of the 60 futures will be a little bit different.

EBS scales adjusted estimates if the developer does not work 100% on that project; for a developer who works 20% time on that project, a 1 hour feature will be scaled to 5 hours.

Once EBS has the sum of a developer's adjusted estimates, it spreads those hours out on the calendar, the developer's work schedule, vacations and holidays, and figures out the calendar date when they would be done. It also takes any project dependencies into account, and assumes that the developer will do all priority 1 features first, followed by all priority 2 features, etc.

In each iteration, EBS calculates the schedule for each individual developer, and then assumes that the project will ship on the date that the last developer finishes their last task.

alt text

Why the algorithm works

EBS is not affected by the details of how estimators come up with their estimates. For example, it doesn't really care if they include coffee breaks in their estimates or not, as long as they're consistent about it.

  • Example. Adam has a bunch of features estimated at 1 hour. He takes a three hour coffee break every day, so he gets 5 of these one hour features done every day. On his time sheet, one of these features actually takes 4 hours even though it was estimated at 1 hour, because he took the coffee break in the middle of working on that feature. Eventually, his track record shows that he has a 80% chance of working at velocity 1.0 and a 20% chance of working at velocity 0.25. When EBS runs, 20% of the time that it sees Adam estimating something at 1 hour, EBS will actually use a calculated estimate of 4 hours, which perfectly corrects for Adam's very predictable coffee breaks.

EBS degrades very gracefully in the absence of historical data.

  • Example. Bonnie is new to the team, so EBS has no track record for her. EBS uses a synthetic track record corresponding to a lousy estimator. Her calculated estimates are much more scattered than her entered estimates, which makes the probability curve much more gradual. The more people you have on a team without track records, the more gradual the probability curve is, reflecting the reality that your schedule is not very trustworthy.
  • Example. Over the next year, Bonnie proves herself to be a consistent estimator -- consistently underestimating each task by half. Even though she seems like a "bad" estimator, her track record fills up with velocities very near 0.5. When EBS runs, the calculated estimate is almost always 2 times the entered estimate. EBS actually gets the final date right, and in fact there is very little variation in this date because Bonnie is a reliable underestimator, so the probability curve is very steep, reflecting the reality that your schedule is quite trustworthy.

EBS handles rare outliers very well.

  • Example. Chauncey is a member of the company gardening committee. Twice a year, in the spring and fall, he takes off two weeks to plant annuals in the company garden, and leaves the clock running on whatever feature he left in progress. There is a certain small probability, reflected in his track record, that a particular short feature will actually take more than two weeks because he's off gardening. Even though this seems like an unusual outlier and you might be tempted to discard the data point, it actually gives EBS very useful information; with some probability, EBS will generate a schedule in which Chauncey takes a ridiculously long time to do something, and that probability is based on evidence. Over the course of a one year schedule EBS is very likely to correctly compensate for Chauncey's gardening excursions.

EBS handles estimators whose estimates improve.

  • Example. By her third year on the job, Dahlia is much better at estimating than she was when she started. Because EBS only looks at the last 200 completed features in constructing a track record, as time goes on, her calculated estimates get closer and closer to her entered estimates.

EBS correctly accounts for real-world estimating errors.

  • Example. It is far more likely for a feature to go over than to come in early, and when it does go over, it can go over by much more than other features could come in early. It's easy to imagine an 8 hour feature slipping to 16 hours, 24 hours, or 40 hours as things go wrong and new bugs and new work is discovered, but it's impossible to imagine an 8 hour feature taking much less than 2 hours. In realistic schedules, this means that features don't really balance themselves out: early features do not fully compensate for late features, and you can never make up for all that lost time by doing other features more quickly. EBS understands this, measures this, and accounts for this perfectly based on actual historical data.

EBS correctly accounts for vacations and holidays.

  • Example. Francine is the developer with the most work left -- she has about two weeks of work. Unfortunately, in two weeks, she's scheduled to go on a long overdue vacation that is three weeks long. There is a 50% chance that she will finish her work before the vacation. EBS will show a probability distribution curve that reflects the 50% chance that you'll ship in two weeks, with a big flat step: to get to 51% probability, you have to wait five weeks. When you see this unusual flat step in the probability distribution, you can move a feature or two from Francine to George, increasing the probability that you will ship three weeks earlier.

EBS correctly accounts for lazy developers.

  • Example. One member of the team, Hilda, is really lazy about entering estimates and never keeps her time sheets up to date. When she does enter estimates, they're wildly off the mark. EBS reflects this correctly, showing a very wide bar for her on the developer ship date chart, and it is reflected accurately in the project schedule, which becomes more gradual to correctly account for the poor data you're getting from Hilda. Her manager Ivan decides he's had enough and starts giving her paychecks with about the same consistency as she enters estimates and timesheet data. Soon, her track record gets better and the project schedule becomes steeper as the data become better.

EBS correctly accounts for team leaders who still like to meddle in the code.

  • Example. Joel has been the Big Boss for six years now, but he still makes the developers assign features to him which he works on maybe one day every two weeks. There are two ways to account for this in EBS, both of which work perfectly. One way is that Joel goes to his personal schedule and declares that he spends 10% of his time on features tracked in FogBugz. Now when he enters a one day estimate, EBS will treat this as taking two calendar weeks. Another way to account for it is that he leaves the clock running even when he's not working on features at all. His track record shows that he commonly works at a velocity of 0.10. Then the calculated estimate of a one day feature is likely to be ten working days. The cool thing is that EBS produces the same, correct results no matter how you choose to use it, as long as you're consistent.
See Also



How to Estimate Software Tasks

Let developers estimate their own work

Any system where management writes a schedule and hands it off to programmers is doomed to fail. Only the programmer who is going to do the work can figure out what steps they will need to take to implement that feature. And only the programmer can estimate how long each one will take.

Design first, and in detail

Attempting to estimate a feature before you've figured out how the feature is going to work, in detail, can't possibly work, even if you "multiply your best guess by three," because your "best guess" is based on very little in the way of facts. The nature of software development is that things which seem simple are often surprisingly complicated when you think about all the details. For example, when you think about creating a registration and logon system, you might forget that you're going to need a way to prevent passwords that are the same as the user name, and a way to deal with forgotten passwords, and a way for people to unregister, and so on. Until you try to figure out the design of all these things, you have no basis for an estimate at all.

Break things down to very small tasks

This is the most important part to making your schedule work. Your tasks should be measured in hours, not days. (When you see a schedule measured in days, or even weeks, it's probably not real). You might think that a schedule with fine grained tasks is merely more precise. Wrong! Very wrong! When you start with a schedule with rough tasks and then break it down into smaller tasks, you will find that you get a different result, not just a more precise one. It is a completely different number. Why does this happen?

When you have to pick fine grained tasks, you are forcing yourself to actually figure out what steps you are going to have to take. Write subroutine foo. Create dialog such and such. Read the wawa file. These steps are easy to estimate, because you've written subroutines, created dialogs, and read wawa files before.

If you are sloppy, and pick big "chunky" tasks ("implement grammar correction"), then you haven't really thought about what you are going to do. And when you haven't thought about what you're going to do, you just can't know how long it will take.

As a rule of thumb, each task should be from 1 to 16 hours. If you have a 40 hour (one week) task on your schedule, you're not breaking it down enough.

Here's another reason to pick fine grained tasks: it forces you to design the feature. If you have a hand-wavy feature called "Internet Integration" and you schedule three weeks for it, you are doomed, buddy. If you have to figure out what subroutines you're going to write, you are forced to pin down the feature. By being forced to plan ahead at this level, you eliminate a lot of the instability in a software project.

Track actual times and learn from your mistakes

Most programmers have no idea how to guess how long things will take. That's okay. As long as they are continuously learning and continuously updating their estimates as they learn, the schedule will work. (You may have to cut features or slip, but the schedule will still be working correctly, in the sense that it will constantly be telling you when you have to cut features or slip). Most programmers become very good estimators with about one year of experience.

Account for vacations, holidays, meetings, etc.

If your schedule is going to take about a year, each programmer will probably take quite a few days of vacation. In FogBugz, you can set up company-wide holidays, and each developer can enter their own planned vacations as well.

Add schedule items

You need to enter schedule items for:

  1. Integration time, that is, time spent getting code written by different developers to work together.
  2. Buffer time: extra time in each developers' schedule to account for unplanned features and tasks. This may need to be as much as 50% to 100% of the planned time, depending on how much confidence you have in the accuracy of your design.
  3. Competitive buffer time: time to allow for new features added at the last moment to match a competitor's features.
  4. Debugging time: time spent fixing bugs discovered during testing.
  5. Alpha and beta tests: time spent distributing test versions of the software, gathering and responding to feedback and bug reports, incorporating feedback into the product, and fixing bugs discovered by beta testers.

In FogBugz, a schedule item is a special kind of case. You should enter schedule items for each developer. If you have five developers on your team, you should have five "debugging" schedule items, one assigned to each developer, so that the calculated dates produced by EBS are correct.

Note, Schedule Items still take into account a developer's velocity when calculating dates are produced by EBS.

Ignore business needs (and your manager)

Many rookie software managers think that they can "motivate" their programmers to work faster by giving them nice, "tight" (unrealistically short) schedules. This kind of motivation is brain-dead. Most developers, when behind schedule, will feel doomed and depressed and unmotivated. When they're working ahead of schedule, they're cheerful and productive. As such, the schedule is not the place to play games of chicken.

Why do inept managers try to get programmers to reduce estimates?

When the project begins, the technical managers go off, meet with the business people, and come up with a list of features which they think would take about three months, but would really take nine. When you think of writing code without thinking about all the steps you have to take, it always seems like it will take n time, when in reality it will probably take more like 3n time. When you do a real schedule, you add up all the tasks and realize that the project is going to take much longer than originally thought. Reality sinks in.

Inept managers try to address this by figuring out how to get people to work faster. This never works. You might be able to get 10% more raw code out of people temporarily at the cost of having them burn out 100% in a year. Not a big gain, and it's a bit like eating your seed corn.

You might be able to get 20% more raw code out of people by begging everybody to work super hard, no matter how tired they get. This causes debugging time to double. An idiotic move that backfires in a splendidly karmic way.

The business is best served if estimates are as realistic as possible. While estimating, you must completely ignore the wishful thinking of the client and focus on what is really going to happen.

Learn more

The idea that software estimation is an "unsolved problem" is simply not true. True, a lot of software developers organizations have managed to remain ignorant of everything that has been learned over the last 40 years about how to estimate software and deliver it on time, but there are also plenty of development teams that reliably produce accurate software estimates and ship within 5% or 10% of estimate.

You can learn more about estimating software schedules from Steve McConnell's book Software Estimation: Demystifying the Black Art, published by Microsoft Press.

If you've never read it, The Mythical Man-Month by Frederick P. Brooks (Addison-Wesley) is a requirement.




Site Working Schedule and individual Working Schedules

FogBugz allows you to specify a site-wide working schedule, along with individual team members' working schedules when they differ.

Any administrator can set a site-wide working schedule. Go to the Admin menu and choose Site Working Schedule. The site-wide working schedule is used:

  • to convert between hours and days in the user interface (for example, when you enter "1 day")
  • to set due dates automatically on incoming mail

Each user can also set their own personal working schedule by going to the Admin menu and choosing Working Schedule. The personal working schedule is used:

  • in Evidence-Based Scheduling, to convert from adjusted estimates (in hours) to calendar dates
  • to start and stop time tracking automatically, so you don't have to tell FogBugz when you go home or come in every day

Adminstrators can access individual users' working schedules via the Users page. Choose Users from the Admin menu, find the user, and click on the small calendar icon next to their name.

% Time Spent per Project

FogBugz 7 assumes that you spend 100% of your work time on tasks that could be tracked in FogBugz. If you work on a few projects at once, you can break this down into a set of percentages per project. This allows FogBugz's Evidence-Based Scheduling algorithm to predict more accurate completion dates for project milestones.

Working Days

Determines which days of the week normally worked.

The value entered here on the site working schedule only determines the default for new FogBugz users. It does not affect existing users.

Daily Schedule

Determines the hours that you normally work, and if and when you have a lunch break.

On the site working schedule, this section determines the default daily schedule for new users. However, changing these values will not affect existing users.

The site daily schedule is also used to convert between hours and days when typing estimates, so, for example, if you work 8 hours a day, entering estimates of "8h" or "1d" are the same.

Holidays and Vacations

On the site working schedule, allows you to enter and edit holidays when nobody will be working. For accurate schedules, enter all the planned holidays for the next couple of years, and keep this up to date.

FogBugz does not allow you to enter recurring holidays, because the rules for calculating them are too complicated and vary widely. For individual users, this section shows both site holidays and personal vacations. Users can enter and edit their upcoming planned vacations. Site holidays are read-only.




The FogBugz XML API

The FogBugz XML API, now at version 8, is fully documented here:

http://fogbugz.stackexchange.com/fogbugz-xml-api




The FogBugz Database Format (Schema)

An online version of the schema (which may differ slightly from the DB Version on your FogBugz site) can be found here:

http://fogbugz.stackexchange.com/fogbugz-database-schema

If your FogBugz site is up and running, you can always see the exact schema in use by going here:

<YOUR FOGBUGZ SITE URL>/default.asp?pg=pgSchema




FogBugz Plugins

What are plugins?

Plugins are modules (.NET assemblies to be precise) which run inside of FogBugz to change or add to the look and feel and functionality of the application. The robust plugin architecture allows you to make changes to all areas of FogBugz: cases, wikis, discussion groups, email handling and time tracking. Plugins can add all new pages and tools to FogBugz or change existing interfaces such as the case view. Plugins can even create new APIs to allow connections to other applications.

Where do I get plugins and how do I install them?

If you're using FogBugz On Demand, you can install new plugins by going to Admin > Plugins and clicking "View All Available Plugins" at the button of the page. This will bring you to a page where you can see all of the plugins that you're able to install on your On Demand account.

If you're using FogBugz for your server, you can browse the Plugin Gallery, or install one locally from a different source. If you don't find the functionality you need, try writing your own in your favorite .NET language.

FogBugz comes many great plugins already installed (there are many more in the Plugin Gallery and still more to come both from Fog Creek and developers like you):

  • Custom Workflow Customize case categories, statuses and assignment
  • Project Backlog Use FogBugz in a Agile/Scrum development environment
  • URLTrigger Send custom HTTP requests triggered by FogBugz events
  • Custom Fields Add a new case field in minutes
  • Wiki Table of Contents Insert a dynamically-updating table of contents into wiki pages
Enabling and Disabling

Plugins can be enabled or disabled by FogBugz administrators by clicking the "yes" or "no" link in the Enabled column on the plugins admin page, accessible by clicking Plugins from the Admin menu. Disabling a plugin preserves its data in the FogBugz database in case you need to enable it again later.

Configuring Plugins

Once installed, plugins are configured via the "Configure" icon next to their names on the Plugin admin page. The icon only appears next to plugins that have configurable options.




Custom Fields: Track your own case attributes.

I'll add an extra point:

Once you've installed the plugin, it might not be obvious how to configure the extra field.

On the table of installed plugins, there is a Configure column, with a small icon. Click on the icon to start adding the custom fields.




Customizing your FogBugz install with BugMonkey

BugMonkey is a FogBugz plug-in that allows you to customize your own FogBugz to suit your needs. The name comes from the popular GreaseMonkey extension for FireFox.

You can add and manage BugMonkey scripts by going to My Settings > Customizations within FogBugz.

Initial view

Click "New Customization..." to create a new script. Give it a name and description and fill in the JS and CSS sections. Make sure you save it and also enable it for your user. You can also enable scripts that others have shared in your FogBugz instance in the "Your Available Customizations" list.

Site administrators can configure the plugin in Admin > Plugins to set who can create customizations and who can import customizations from this site.

Admin config

Site admins can edit any customization regardless of who created it, and can set whether it is on or off by default for certain users, or is required.

Edit and rules

You can find a bunch of BugMonkey scripts by visiting the bugmonkey tag here, or by looking at the BugMonkey Script Archive post.




Notify: Notify users of changes to cases

Once installed, the Notify plugin adds a "Notify More Users" input field to cases in edit mode. Enter the names of FogBugz users into this box to include e-mail notifications to them with the case edit information. The box even supports completion of partial name entry using a similar style to the "To" and "CC" fields in FogBugz e-mails.




URL Trigger: Integrate with virtually any outside system

The URLTrigger Plugin allows you to specify a request to be sent to a specific URL when events occur in FogBugz. To create a URLTrigger, select one or more events that your trigger will respond to, then add values to the URL querystring using a list of variables presented by the plugin.

Usage scenarios of this plugin are discussed at http://fogbugz.stackexchange.com/questions/36/what-would-be-a-typical-usage-scenario-for-the-urltrigger-plugin




Subscribe to All Cases in a Project or Area

The AutoSubscribe Plugin is a FogBugz plugin that allows you to subscribe to cases, wikis, and discussion groups.

You can add and manage subscriptions by navigating to My Settings > Subscriptions within FogBugz.

Initial view

Click "Add New Subscription," and you'll see a few broad auto-subscription options at the top of the list, allowing you to subscribe to any item you create, any item you edit, and all projects. Below, you can choose more specific subscriptions, like individual projects, areas, wikis, and even discussion groups.

Initial view

Once you are subscribed to a case, you can always unsubscribe by clicking "Unsubscribe" in the left sidebar of the case view.

Initial view




Broadcast Email

Install the Email Users plug-in from the FogBugz Plug-in Gallery. This will allow you to send out broadcast emails.

Once you install the plugin, you should see an "Email All Users" link in the Admin dropdown.

Initial view

Clicking it will bring you to an email form, where you can specify whether you'd like to email all users or only administrators, add a subject, and write your message.

Initial view

Users will then receive your message at the email addresses linked to their respective FogBugz accounts.




What is the Kanban plugin for, and how do I use it?

A Kanban board is useful for visualizing what cases are being worked on and where they are in your development process.

This plugin allows you to put cases in columns and assign them colors. This can be done via case editing or from the Kanban editor. While in the Kanban editor, cases can be dragged to change the order within a column or between columns. The editor's context menu allows easy adding or removing of cases and easy color changes.




Discussion Groups

FogBugz gives you full-fledged discussion groups built in.

Each discussion group shows a list of topics:

alt text

Discussion groups can be private or public.

Private discussion groups are a great way to communicate in your team. Unlike private email, once conversations are captured in a discussion group, they will always be visible and searchable, capturing valuable development knowledge for posterity.

Public discussion groups are a great way to communicate with your customers and provide tech support for customers. The biggest advantage of communicating with your customers over a discussion group instead of email is that you won't have to repeat yourself so much, and there's a good chance that your customers will help each other solve problems before you have a chance to get to them.

When a customer posts something to a discussion group that you want to follow up on, you can click on a "New Case" link to create a case in FogBugz out of that post. This also creates a bidirectional link between the discussion topic and the case used to track it. You can use this to:

  • create a case to track a bug reported by a customer in one step
  • assign the discussion topic to a member of your team and make sure they reply to it
  • gather interesting discussion topics in a project in FogBugz, for example, to track customer feature requests.



Starting on FogBugz On Demand and Moving to Your Server

Yes, you can. You can download your database at any time by going to Admin > Your On Demand Account and selecting a download format. After that, you can point a local install of FogBugz at this database and it'll run right away.

Note that Kiln On Demand can not currently be easily moved from our servers to other servers.




SQL Server: Importing data from FogBugz On Demand or trial into SQL Server

Step 1

Run FogBugz Setup. Choose SQL Server as the database option. When Setup has finished, it launches a web page and asks you to install licenses. Don't install the licenses yet - it's okay if you already did, but you just don't need to. Just minimize this browser, we'll come back to it later.

   

Don't install licenses yet! (it's ok if you already did)

Step 2

In another browser window, log into your FogBugz On Demand account as a Site Administrator. Click Admin at the top right, then "Your On Demand Account", and click the download link for "SQL Server 2005". FogBugz will warn you that during the database copy, the site will be down. Make sure nobody needs to use FogBugz and then click "Begin Copy"

The download may take many hours if you have a large database. If it takes too long or fails, please contact us for other options.

After the copy is complete, click the Download button that appears to download your MDF data file (it will be named something like fogbugz72040459_copy.MDF), and save it to the folder that MS SQL Server likes to keep data files, which is normally:

C:\Program Files\Microsoft SQL Server\MSSQL\Data

Make sure this file is not read-only and that the user SQL Server runs as has full control for it and the directory it is in.

At this point, your FogBugz On Demand account is still locked for the download. On the page you downloaded from, either enter a URL for a new site to link to, or click the link next to "Go back" to reactivate the site if you need to keep using it.

Step 3

Run SQL Server Management Studio and connect to your database server. Drill down to the empty database named FogBugz that was created by Setup. Select it and press the Delete key to delete it.

   

Step 4

Right click the Databases item and choose Attach...

   

In the dialog which appears, click the "Add..." button and select the MDF file you just downloaded. The dialog will now look like this. Click the second entry in the bottom pane, which has File Type "Log" and click the Remove button:

   

If the Data row has an incorrect path for "Current File Path", change it to the path of the mdf where you just moved it.

In the top pane, click on the Owner field, then click again to bring up the menu. Select the same user you told setup to run FogBugz as. If you told Setup to use Windows/Mixed Mode authentication to connect to the database, this user is the same one you see for Anonymous Authentication in the FogBugz virtual directory. If you told Setup to connect to the database using a SQL Server login (name and password), then specify that login here. Click OK.

   

Step 5

Bring up FogBugz in your web browser and refresh the page. If at this point you get an error message, please re-read the above steps and verify that you didn't do something ever so slightly differently.

  1. Install your licenses
  2. Set your options in Admin -> Site Configuration
    • The FogBugz Maintenance URL
    • Notification URL
    • Your outgoing SMTP server information

Users will lot in with the same credentials from your hosted account. Presto magicko, you should see all the data you created on our server like so many eggs in a basket!

Step 6

Re-install your plugins per this question.




MySQL: Importing data from On Demand or trial

NB: Before you go through any of this, you should make sure there are no FogBugz-unfriendly settings in your MySQL instance.

1. Email customer-service@fogcreek.com to request a MySQL export of your FogBugz account. It will be provided on an FTP site for you. Download and save the .sql file to your computer.

2. Install FogBugz fully and get it working (even add a test case).  Remember the FogBugz user and password that you set for the database. Before you go on, stop the FogBugz Maintenance Service.

3. Once its working, log into mysql. You should be able to log on using the fogbugz user and password at this point.  The instructions assume your FogBugz database is called 'fogbugz'.  If not, replace fogbugz with the name of your database.

mysql> drop database fogbugz;
mysql> create database fogbugz;
mysql> use fogbugz;
mysql> source /path/to/trial.sql.dat
mysql> grant all on fogbugz.* to fogbugzuser identified by 'fogbugzpassword';
mysql> grant all on fogbugz.* to fogbugzuser@'localhost' identified by 'fogbugzpassword';

Note the ' around the 'localhost' part.  You can replace localhost with the server name if your FogBugz server is on a different machine.  You should replace all italicized values above with values corresponding to your setup and environment.

Note the use of the "source" command above. Do not simply paste the contents of the .sql file into a MySQL GUI and run it. Tests have shown that this results in corrupted cases under certain circumstances.

4. Then go back into FogBugz through your web browser. You will have to enter your order info for licenses again.




On Demand Billing FAQ

How much does FogBugz On Demand cost?

At first, it's free. You get a 45-day free trial period, and you don't have to give us your credit card information if you don't want to.

Once the free trial ends, you will be billed based on the number of active users you have. The pricing is listed here.

Price adjustments are calculated automatically, so there's no need to worry about changing plans as you add users.

What if the number of users I have in a month changes?

You are billed according to the high-water mark of the number of active user accounts each month, that is, the maximum number of user logins that were simultaneously enabled at any one time during the calendar month. So, if you have three active users for part of the month and then add a new active user, you get charged $100 for that month ($25 times 4 users).

You can securely enter your credit card information at any time. If you give us your credit card info before the end of your trial period, we won't start charging you until that 45-day period ends; and we process charges on the first weekday of each calendar month. So, if your trial period ends on May 25th, the first charge to your credit card will be posted on the first weekday of June.

What if I am a student or creating a startup, and we don't have much money?

The FogBugz Student and Startup Edition allows teams of one or two people to use a complete, full-featured version of FogBugz, professionally hosted at our data center, at absolutely no cost. You don't have to provide a credit card, there's no advertising, and there's no catch. If you love FogBugz, tell your friends about it. If you make it big and your startup grows, you can hire more people and switch to the paid version. If you graduate from school and a get a job somewhere, you can convince your new company to start using FogBugz.

What if I start my account in the middle of a month?

We only start billing you after the end of your free trial. On the first weekday of the next month, we pro-rate your first monthly fee. To do that, we calculate the high-water mark of the number of active user accounts during that first partial month, multiply by $25 (or $30 for FogBugz + Kiln), and pro-rate that proportionally to how many days of the month you had the account. Then, by the next month, the charges should get to their normal level. You can keep track of this using the Usage Details link on the Your Account page.

What if I end my account in the middle of a month?

If you're past the free trial period, and you cancel your account in the middle of a month, the monthly fee for that month of service will be pro-rated in accordance with the number of complete days during that month when the account was active.

How do users work?

You can share your FogBugz On Demand account with other people by making them users. Each user corresponds to one individual human being who can log in and use FogBugz.  You can make a user an administrator for your site or a regular user, and you can limit his or her permissions in various ways.

Only active users can log in, and only active users count towards your billing. You can deactivate and reactivate users at any time. So, for example, if you have a tester working for you for a few months at a time, you can deactivate her account while she's away to save costs.

How can I stop from accidentally adding lots of active users and going bankrupt?

Any administrator can set an Active User Account Limit on the Your Account page. No one can activate users beyond this limit.

What type of payment do you accept?

Fog Creek Software accepts all major credit cards. If you prepay for a year in advance, you can also pay with a check or corporate purchase order.

How do prepayments work?

You can prepay for a year in advance based on the estimated number of users that you will have. This amount will be credited to your account. At the end of each month, we deduct your monthly charges from this account. If you add more users, this account may be depleted before 12 months are up. If you cancel at any time, any money left in the account is refunded to you.

How do I cancel my account?

You can click the Cancel link on the Your Account page. You can cancel at any time.

What is your refund policy?

If you're past the free trial, and your trial period ended less than 90 days ago, just let us know and we'll refund everything you've paid us. Otherwise, just hit the Cancel link on the Your Account page, and we'll pro-rate you for the used portion of the current month and close your account.

The Fog Creek Promise: If youre not satisfied, for any reason, within 90 days you get a full refund, period, no questions asked. We dont want your money if youre not amazingly happy.