We have knowledge base articles about how to fix things in FogBugz when they go wrong. Many of these articles also have troubleshooting steps to help you navigate a tricky problem. These guides have been tested here many times, and they work. But people occasionally complain that although they worked, they were a bit confusing.
This confusion is due, at least in part, to the issue that they don't know, and we don't always tell them, about the circumstances that are responsible for the trouble. This is the right approach for a knowledge base article whose purpose is to identify and solve your problem as quickly as possible, but for those analytical minds out there (like mine) a little context goes a long way to helping you solve and prevent problems. In that spirit, I am going to do a series of articles showing what's "Under the Hood" of FogBugz so that our more technically inclined customers can see what is going on.
In this post, I'll talk about exactly how FogBugz email works, and, in particular, what the mysterious FogBugz Maintenance Service (FBMS) does.
First, let's review how email works in FogBugz. FogBugz does not send or receive mail as a result of any direct user action. Because we want FogBugz to continue receiving mail even if nobody is around, we have a service, the FogBugz Maintenance Service on Windows and the fogbugzmaintd daemon on Unix/Mac, that regularly runs and makes sure that mail is sent and received (as well as doing a couple other routine tasks).
After its first start, the FBMS waits 15 seconds and then it hits heartbeat.asp (or php). It does this by creating an HTTP connection to the maintenance URL that you have configured in your Site administration tool inside of FogBugz.
Note: This is why we ask you to check this URL in our KB article on troubleshooting Mailbox/Notification problems.
Heartbeat calls singleHeartbeat which is essentially a checklist of activities. The first one that is mail related is retrieving email from the POP3 accounts that you have configured in the Mailboxes administration tool.
To do this, the FBMS creates an instance of CMailboxList (.asp/php). It then loops through all of the mailboxes that you have configured. From each mailbox, it retrieves the oldest message by creating a POP3 connection to the mail server and requesting the message. Take note, that it only retrieves one mail message from each mailbox on every pass. You can simulate this communication by going to step 7 of our built-in diagnostics which is linked at the bottom of the Site page.
Note: Diagnostics are our solution for giving you an easy way to validate your mail settings are correct.
If it encounters any errors, it will display them in FogBugz just beneath the navigation bar (Warning: Some errors have occurred in your FogBugz installation.). If no errors are encountered, it moves on to its next task.
Next, the FBMS deals with mail in the FogBugz mail queue. Mail in the mail queue consists of both notifications and email responses to inquiries in FogBugz. To accomplish this, the FBMS creates an instance of CMailQueue. This will load into memory all of the records that appear in the MailQueue table of the FogBugz database. The FBMS then takes N records from that queue and creates an SMTP connection to the server you configured in the Site administration tool and sends them out. In this case, N is controlled by the value of cMaxMailMessages which is set in heartbeat.asp. By default, cMaxMailMessages is set to 1. This communication can be simulated in step 6 of the included diagnostics. Just like with your POP mailboxes, if there is an error here, it will display as a warning inside of FogBugz.
After the FBMS finishes its checklist, it records the amount of time it took to do its work. Then, to prevent it from becoming a resource hog, it uses a set of rules to decide how long to wait before its next pass. The rules are as follows:
- If there is still more work to do (e.g. more messages waiting to be sent or received)
- Wait the lesser of two minutes or the amount of time it took to complete the work of the last pass
- If there is no more work to do
Once one of these rules is satisfied, the process starts all over again.
I hope that this first look under the hood has been helpful. If you have any questions, or suggestions for future "Under the Hood" topics, please contact us.
