========== JTracker ========== .. contents:: This product is an issue tracker for Zope. If you use virtual hosting ========================== If virtual hosting is used the auto-generated (or manually filled in) path to the MailHost can be incorrect. If you see errors adding or following up to issues where the traceback shows references to "unrestrictedTraverse" at the end the "mailhost" property is set incorrectly. If you do know the true physical path to the MailHost you want to use and it differs from the value shown then correct it. If you do not know the path you can also just fill in the ID of your MailHost object without any leading slashes and the first object with that ID that can be acquired by the JTracker will be used. How to upgrade ============== JTracker now comes with an updater script that can be invoked as an External Method. To update an existing JTracker instance follow the following steps: - Log into the Zope Management Interface (ZMI) and go to the folder where your JTracker(s) are located. - From the "Add" dropdown select "External Method". - Fill in the following fields: - Id: Any ID that is not yet taken - Title: (optional) title - Module Name: JTracker.updater - Function Name: update - Hit the "Add" button to instantiate the External Method - Click on your new external method in the ZMI - Click on the "Test" tab in the External Method to update. Depending on the number of JTrackers in the folder and the number of issues in each this update may take a while. Once it is done you will see a small log of the changes that were applied. In some cases the upgrade process actually requires restarting your Zope server. A symptom that signals the need to restart is the appearance of error messages when clicking through the JTracker and some of the issues. Talking to the JTracker via Email ================================= The JTracker allows you to perform certain tasks via email. This requires cooperation from several components, namely a dedicated email address (must be the same as the address set as "jtracker_emailaddress" in the JTracker properties) and a mail server that allows you to pipe mail for the dedicated email address into a script instead of delivering it to a mail spool. The script gets the raw email text and issues a POST request to a method on the JTracker. One important consideration that must be kept in mind is that if someone talks to the JTracker via email it is not possible to determine what user they really are. Email addresses can be spoofed easily. For that reason the email interaction is limited to the following: - creating new issues - commenting on existing issues This is basically what everyone with the permission "Submit JTracker Issues" can do. All other administrative requests must go through the normal web interface. This is what you need to do to set it up: - Edit the configuration parameters in the "emailAccepter.py" script. This script is in the Extensions directory of the JTracker package. It allows you to specify the full URL where your JTracker resides, the email address that it receives mail under (this is just for verification purposes to make sure only legitimate mail is piped into Zope), and an optional login and password in case your JTracker is not reachable for anonymous users or you have not enabled the "Submit JTracker issues" permission for Anonymous in the JTracker "Security" ZMI view. - Make your mail server invoke the "emailAccepter.py" script. How this is done varies from one mail server software package to another. I have set it up with Postfix (easiest) and Sendmail (a little more complicated). I used the /etc/aliases file to specify the email handling, like so:: # JTracker email account is jtracker jtracker: "|python2.x /path/to/JTracker/Extensions/emailAccepter.py" You must ensure that the emailAccepter script can be found/read by the user account your mail server runs under (you may copy the script anywhere, there are no dependencies with the JTracker package itself) and that your mail server can execute the python binary. This is the added snag with sendmail, it wants all "approved" binaries to be in (or linked into) a specific folder (/etc/smrsh on RedHat). The script invocation can be done using other methods as well, such as procmail. If you used the /etc/aliases route do not forget to run "newaliases" when you are done. At this point you should be OK, if not your email will bounce back. It is hard to debug the real reason for bouncing emails to the JTracker, I suggest you read up on your mail server package to get debugging help. Once you are set up on the receiving end here are the rules for sending email to the JTracker: - Email that does not have a issue ID ("issue_23") in the subject line but one of the items defined as "components" in the JTracker properties will create a new issue. The subject line should also contain one of the request types defined under "request_types" in the JTrackeer properties. The full subject will end up being the issue title. Parsing for component and request type is case-insensitive. It must be spelled correctly, though. Faulty email will be discarded silently and will not lead to malformed issues being created. A subject line that will create a "Bug Report"-type issue for component "Widget" could look like this:: widget bug report: I cannot log in anymore - Email that has a issue ID in the subject line is assumed to be a comment on the issue. Since issue followups do not use titles the rest of the subject is not important and it will be discarded. An example subject line can be as simple as this:: issue_123 For convenience purposes it is possible to take the email sent out by the JTracker about a new issue or an issue followup and simply hit "Reply" and adding your comment in the body. This will do "the right thing" and create an issue followup. To improve readability you should make sure to trim unnecessarily quoted text from your reply.