1 Sysadmin tracker for roundup

Author

John P. Rouillard

Date

2022-01-10

Welcome to the sysadmin tracker for Roundup. This tracker is designed to handle issues generated in a system administration or help desk environment. It is released under the GPL license. See Tracker License section for details.

It is based on the classic tracker, but is enhanced with features I have wanted in my trackers. Some of the features were inspired by equivalent functionality in rt while other features were driven by missing functionality in other tracker/help-desk software (req, reqng, queuemh, rt1 and 2, Clearquest, Remedy, Cherwell) I have used through the years.

This project started in the early 2000's to replace a classic tracker that I was using at work. It started as a hobby at home and did not make it into production. You will see vestiges of the classic tracker in the naming of classes and fields to make the conversion easier.

I spent about 80 hours or so learning Python and implementing the basic features from Request Tracker:

  • two levels of notification lists and two types of update messages

  • dependencies/issue relations

plus a few more features (prototype automatic action feature) were added.

Extensive development on the tracker stopped with release 0.7 of roundup in 2005 after a job switch. I started working on it again at the end of 2012 to update it with responsive support and to bring it up to date with changes in the roundup framework.

The sysadmin tracker adds to the basic functions of the classic Tracker: status, keywords, owner, and nosy list support. A summary of the features:

  • Relationships between issues

    • Dependencies - closing all dependencies of an issue open the issue, issue can't be resolved until all its dependencies are resolved.

    • Grouping - arrange issues in a hierarchy that allows batch operation and distributes notifications across the hierarchy

    • See also - generic relationships between issues

  • Private mode restricting access to tickets

  • Notification/collaboration

    • The previously mentioned two levels of notification/messages (Watchers and Technical users)

    • Highlighting tickets in the web interface that need a response (works with auto-refresh mode)

    • Adding a particular topic/keyword to an issue will add users to the Watcher mailing list for that issue.

    • Public and custom RSS feeds

  • Scheduling/Workflow

    • Support for start date, due date, lead time

    • Support for a working order field to provide fine grained prioritization of issues

    • Six predefined priorities (with ability to adding more)

    • Support for queues which can email groups automatically when an issue is created/assigned

    • Implement a workflow by defining valid transitions in ticket status

  • Automatic/scheduled actions e.g. can auto-close a ticket in three days if there is no response.

  • Usability:

    • Web interface provides basic responsive design support for use on a tablet or phone

    • Batch-update mode that allows adding an update message and setting fields and apply it to multiple issues.

    • Multi-edit mode that allows applying different changes to different issues all from one screen.

    • When replying to a message in the web interface, it can quote the original message.

    • Fields for recording billing and reference information (e.g record a vendor ticket ID for reference without having to scan all updates).

    • Enhanced search box that provides full text issue search, the ability to jump to an issue by id or other object (e.g. user) an optionally find issues created using an email address.

    • Works with text based browsers so basic functionality can be used from remote servers (E.G. uploading a local file or quickly updating a ticket over a serial terminal/kvm in a data center.)

2 Using the sysadmin tracker

This section describes general usage of the tracker and explains the properties and related entries.

Note

This details the differences from the classc tracker. It assumes that you have read, or will read the roundup user guide.

2.1 Example use case

A requester sends email to the sysadmin tracker email address. The people responsible for watching the tracker and its queues are automatically sent a new issue email.

Then the queue manager for the week uses the web interface to set the issue priority and to assign somebody to the issue. This 'assigned to' person is called the owner. The owner automatically receives a "this issue is assigned to you email", and the issue will be displayed on the owner's issues list. The owner then replies to the assignment email and asks the requester for some additional information. The issue is automatically moved to the open status.

The owner then uses the web interface to add a few other technical people to the Technical (verynosy) list and creates a "comment" message asking for ideas on the best way to solve the problem. The technical people receiving this comment respond to it with more comments. Then somebody realizes that they need input from the issue creator. The owner sends a "reply" message using the web interface and asks the creator (who is automatically put on the Watcher list) for the information. All of the people on the Technical list see the email and its response. One of the technical people replies to this email and solicits further info from the creator.

Some more conversations occur using "comment" messages until a solution is reached. The owner realizes that she needs help from another group and creates a new dependson issue to assign part of the work to another person. The owner then stalls the issue.

Once the other work is done, and the depended issue is resolved, the issue is automatically moved from stalled to open. The owner completes the issue, adds a comment detailing how the issue was solved. Then passes it off to another (QA) person in the group by reassigning the issue owner. This moves it off her list of open issues and puts it on the new owner's open issue list.

The new (QA) owner creates a reply to the issue creator telling him that the problem is solved, and asks him to verify the fix. He also moves the issue to the testing status. The requester sends email saying that the issue is resolved, the owner changes the status to resolved and it is automatically removed from his list of open issues.

In this example we see there are two ways to interact with the issue:

  • web interface

  • email interface

with a few exceptions, all of the features of the tracker can be accessed via either interface. We will discuss the web interface first then the email interface.

2.2 The Web Interface

Screenshot showing the menu on the left and the top of the main content area for editing information on a ticket.

Display showing left menu and main content area.

We will discuss using the web interface. The interface is made up of two main parts:

  1. the left hand menu

  2. the main content area

the left hand menu is always present (except when viewing in print mode).

The main content area will have lists of issues, users or display individual issues etc. to work on.

2.2.1 The left hand menu

Screenshot of left hand menu showing the main sections: search issue/goto, query management/selection, issue operations, Creation/editing of keywords, administrative function (e.g. see info on other users), user's logout, issue display and preferences editing, links to manuals, actions section for triggering printing display, autorefresh form.

The left hand menu of the tracker.

The left hand menu has a number of items in it including:

  • Search Issue/Goto Box - this has multiple modes

    • Enter a word or words in the box (a word can include _ but no other punctuation). A list of issues will be shown where one of the messages in the issue includes all the words you typed into the box.

    • If you type a number in the box, the issue with that number will be shown. If you want to search for a number, surround it by quotes. E.G. entering "456" will search for an issue that has 456 in a text field or any message associated with the issue. Entering 456 will jump to issue 456.

    • You can also enter a designator (e.g. msg2 or user23) and jump directly to the item. If you want to search for something that could be interpreted as a designator, enclose it in double quotes "msg2" or add additional terms to the search.

    • If you enter a list of numbers (comma and/or space separated), an index view with just those issues will be shown. This is useful if you want to see more info about related issues. An issue's depends on relation is shows as a comma separated list e.g. 1,2,3. Copying this list into the jump box will display the index page of these issues.

    • If enabled by the administrator, a logged in user can enter an email address (e.g. user@example.com) to find all issues requested by a user with that address. Both primary and additional addresses are searched for a match. If no match is found, a regular full text search is done for the address. The anonymous user always gets a full text search and never the user address search. This can be enabled/disabled by modifying the entry in the extensions/config.ini config file.

  • User's Saved Searches - If you have saved any searches (by using the search page and naming the search), it will be listed here for quick reference.

  • Issues menu - Links for seeing unassigned issues, creating a new issue, showing all issues and searching for issues using specific criteria are located here.

  • Keywords Menu - You can add new keywords for use in the Topics field from the link in this box. If you created the keyword you can also edit it. If you are a tracker agent or administrator you can edit all keywords.

  • Admin box - If you are a regular user you can display a list of all users of the system. If you are an admin, you can pull up edit menus for all classes in the tracker and add users.

  • User Box - This box identifies who is logged in, allows you to see your details, your issue list and allows you to logout.

  • Help Box - this box provides links to roundup documentation on the roundup web site, and a link to this documentation on the tracker you are using.

  • Actions box - this box allows you to select a printable copy of your page. If you are viewing an issue, you can also eliminate the issue history which helps save on paper. Use your browser's back button to get out of printable mode.

  • Auto Refresh box - this box lets you automatically refresh the current screen with a user configurable time. It is useful for watching updates to a particular issue, or monitoring a selected list of issues. You can select from 10 sec, 20 sec, 30 sec, 1 min (Default), 1.5 min, 2 min, 5 min, 10 min, 20 min, 30 min, 1 hour and 2 hour intervals. Then press the AutoRefresh button. If you are already automatically refreshing the page, it will display the refresh interval and a link to turn off auto refresh.

2.2.2 Issue Index Views

Screenshot showing a list of 4 issues. Each row has a checkbox allowing it to be selected.  Shows actions: display selected (only checked items), edit the query that produced the list, download the list as a csv file, multiedit all of the items using a spreadsheet like interface, batch edit all the items using a form similar to the standard edit form, use the result of the list as an rss feed. Also shows sorting and grouping controls for the list/search.

A standard tabular display for multiple issues (index).

When you log in, you will see a list of open issues. You can click on the "My Issues" link in the User box to see all issues assigned to you. You can view an issue by clicking on its title or entering its ID number using the goto box.

Using either of these methods will bring up the default issue view. There is also a view for advanced administration of the issue including assigning a scheduled action, storing billing info etc. This advanced administration view is called the edit fields view. These two views are discussed below.

If you have the ability to edit the issue, you will see a form that lets you change the basic fields. If you have javascript enabled, the label for each field you change will have its background changed to indicate the change. Also the page title displayed in the browser and the issue title on the page will be changed (and highlighted) to indicate there are pending changes.

2.2.3 The Default Issue View

Screenshot of the default update pane in the view interface. Showing widgets to edit each piece of info. E.g. Title, Priority, Owner, notification lists, etc. Also shows change note field, file upload control.

Basic issue fields. (Note: Change Note textarea was shrunk for the picture.)

The issue view shows an update pane including:

  • basic fields,

  • new message entry field (change note),

  • file upload control

  • Submit Change or Silent Change buttons. The Silent Change button updates the issue like the Submit Change button, but it suppresses notification emails.

2.2.3.1 Basic Fields

The basic fields include:

  • Title

  • Priority

  • Assigned to (Owner)

  • Status

  • Queue

  • Watcher List

  • Technical list

  • FYI

  • Depends on

  • Groups

  • See also

  • Due Date

  • Lead time

  • Private

  • Topics

See the Issue Property Reference section for full information on these fields. The message entry fields are:

  • Message type

  • Time spent

  • Cc

  • Change note

  • File control (one or more)

You can paste text from the clipboard into the Change note. If javascript is enabled, you can also drag and drop files or text and paste images into the Change note area. When this is active the Change note will change color when you drag items over it.

  • Dropped files will be attached to the first empty add file control. Then a clear button for the current control and a new empty file control will be added for attaching another file.

  • You can paste an image (e.g. a screenshot) from the clipboard into the Change note. The image will be attached as image.png (assuming it's a png). Then a new file control is created as above.

  • When text is dropped, it is inserted in the Change note after the cursor.

The file upload control button can be used to browse to a file as usual with or without javascript enabled. All attached files will be uploaded when the form is submitted.

Note that only the first file control allows dropping/selecting multiple files. If there is more than one upload control displayed, you can only drop one file at a time. When a file is loaded in the upload control, a clear button is created. If you decide you don't want to upload a file (or files for the first control), clicking the clear button will empty the previous file control. You can submit a form with empty file controls.

These fields will be editable if the user has the ability to edit the issue/field. A number of the fields are grouped into sets of fields (fieldsets). If javascript is turned on you can collapse fieldsets. If you click the [×] at the end of the fieldset, the fieldset will collapse, clicking the [+] will expand the fieldset.

If you collapse a fieldset that has a changed field in it, the changed field will be updated when you submit the form.

The state of fieldsets is sticky. When you submit form with a collapsed fieldset, the fieldset will remain collapsed when viewing other issues. You can reset the fieldset to an expanded state by viewing an issue, opening the fieldset and submitting the form without any other changes to the form.

2.2.3.2 Time Log and Attached File Display

Below the update pane, the default issue view shows the time log (if times have been entered for the issue) including totals, the files list (if files have been attached), the message list, and history list.

Screenshot of the timelog and file attachment tables. The timelog table also includes a sum of all the timelog entries.

Display of timelog and files attached to an issue.

The Time Log Total section is shown only if one of the messages was entered with time information. The display consists of three columns:

  • Date - the date the time log entry was created

  • Period - amount of time spent

  • Logged by - user who logged the time

If you can edit the timelog (you created it, or you are an admin), you can click on the period and open a page where you can change the value. The bottom row of the timelog table provides a total of all periods.

If a file has been uploaded to the issue, there will be a file table below the timelog table. The columns are:

  • File name - the name of the file

  • Uploaded - the user and date of upload

  • Type - the mime type of the file

  • Edit - if you own the file or are an admin you can edit metadata by clicking this link.

  • Remove - if you are an admin, you can remove the file from the issue.

2.2.3.3 Messages Display
Screenshot of the header for a message showing message type, message id, author and date and actions including reply-to link that quotes the message in the change note box for reply.

The message header.

The messages section displays the full text of any messages that are linked to this issue. Each message has a header. The header consists of:

  • a short message type designator

    • "rep" for reply type messages

    • "com" for comment type messages

    • "dat" for data type messages

  • a link to the full message entry (this includes message history, attached files, message type, time spent, recipient list etc.)

  • if there was a timelog associated with the message, the time spent will be displayed.

  • the author's name

  • the creation date for the entry (in local time of the user if the user has the proper timezone set)

  • if you are an admin, you will see a remove link that will remove the message from the issue

  • the reply to link that will reload the page with the quoted message in the change note field. This makes it easy to reply to a message in the web interface using in-line comments to the message.

Next is the list of files that are associated with the message in the issue. It is displayed only if there are files associated with the message. If inline display of images is enabled for the user, attached images are also displayed. This makes it easier to associate a specific file with the message that describes it. Any attached files will also be displayed in the issue's file attachment table.

Screenshot of the file atachment section of a message including inline image.

List of file(s) attached to a message.

[Admins take note: earlier versions of roundup had a bug where file attachments sent via the email interface were linked into the messages, but were not linked into the issue. You can create a shell script using the roundup-admin command to fix this. See the admin chapter below.]

2.2.3.4 History Display

Then at the very bottom of the page is the history of the last 10 changes made to the issue.

  • Date - date and time of the change

  • User - the user who made the change

  • Action - there are a number of values including

    • set - set an property value

    • link/unlink - add/remove an item to a link or multilink type property

    • create - create the entry

  • Args - the argument that were actually changed. For most arguments you will see propertyname: *oldvalue* -> *newvalue* where newvalue is the replacement value. For properties that are multilinks, linking and unlinking are indicated by preceding the identifier with a + (added to property) or - (removed from property). It looks like: nosy: -rouilj, +admin.

Since you can change multiple items in a single modification of the issue, only one Date/user line is shown for each modification. There can be multiple action/args entries that were done with only a single modification transaction.

You can click the link at the end of the history section to reload the page and display all the issues history.

Caution!

To prevent loss of pending changes to the issue, open the history link in a new tab/window.

Roundup provides a mechanism to prevent you from submitting your changes if another user updated the ticket before you. A link is provided to view the ticket with the updated values. Open the link and go to the end of the page. Look at the history, you should be able to easily determine what has changed.

2.2.4 The Edit Fields Issue View

A form to edit all properties of an issue. The normal issue view form displays only a subset of the available properties. In this form we have all the basic fields plus action fields, start date, working order etc. Also a brief index of issues that relate to this issue is shown.

Form to edit all fields.

In this view, you have access to more fields, and also some embedded searches to provide a better feel for how the issue relates to other issues. It does not provide a message entry box, nor does is show the messages associated with the issue or a history of changes to the issue.

The fields shown are the basic fields shown in the main issue view:

  • Title

  • Priority

  • Due Date

  • Status

  • Lead time

  • Assigned to

  • Watcher List

  • Queue

  • Technical list

  • FYI

  • Depends on

  • Groups

  • See also

  • Topics

Below that is the "Additional Fields" section including:

  • Requested By

  • Start Date

  • Billing Info

  • Working Order

  • Needs Reply

Below that is the "Action Fields" section that implements some basic actions that can be scheduled for a future time. This section consists of the fields:

  • Action Date

  • Action Status

  • Action Comment

See the section Issue Property Reference for full details on these fields.

Below this section is the Issue Relationships section that provides a five column summary of related issues. The columns are:

  • ID (issue ID)

  • Title

  • Status

  • Priority

  • Activity (date of last activity on issue)

Also a graph of relationships is available under each summary table. This is useful for seeing the scope of the relationships starting from the current issue. It is also useful for troubleshooting loops between dependencies and grouping issues.

2.2.5 Multiple Issue Edit Form

Screenshot of one of the modes for editing multiple issues. This provides a spreadsheet like environment for setting different values on each issue. Useful for reviewing and setting status on multiple issues. The screenshot displays the id, activity, title, status creator and assigned to user.

Edit multiple issues form.

To edit multiple issues with different changes, you can use the "Multi Edit" form. This form presents a table (created from an index view) where you can edit each writable property of an issue. Some properties including id, activity, and creator are read only and can't be changed.

To remove all entries from a multilink box, replace the items with a blank space. If you leave the box empty, the change will not be recorded.

You access this form by selecting your issues using a search. Then click on the "Multi Edit" button at the bottom of the issue list. If you don't change any of the values for the issue, the issue won't have its properties changed.

If you are making the same change to multiple issues, you may want to use the batch update edit form instead.

2.2.6 Batch update edit form

Screenshot of a second mode for editing multiple issues. This allows the user to make the same change to all of the selected issues. The top of the display is an edit form just like you would have at the top of an issue when it is being edited. The body of the mode allows the user to select the issues for which the edit will occur. This can be used to close out a number of issues with a single edit.

Update multiple issues form.

Sometimes you need to make the same changes to multiple issues. Rather than editing the properties of each issue as with the multiple issue edit form you can change the properties of multiple issues by making a change to a form that looks like the standard fields form and selecting which issues the changes should apply to.

If you are editing a multilink you can prefix the entry with + or - to add or remove the value. So to remove the user '''admin''' from the Watcher (nosy) list, you would enter '''-admin''' and all of the issues that are checked will have the admin user removed. (This is similar to how you update properties via email.)

You access this form by selecting your issues using a search. Then click on the "Batch Update" button at the bottom of the issue list. You can then refine the list of issues. Remove issues from the update by unchecking the check box for the issue. By default all issues start checked. Toggling the check box in the table header will toggle the check box for all issues.

2.3 Logging in, or submitting your first issue by email

If you send email to the tracker email address, an entry in the user database is made for your email address. If the administrator has set the MESSAGES_TO_AUTHOR to include new, or yes, you will receive a return email that verifies the creation of the issue and will provide you an easy way to add information to this issue by replying to the return email.

You can also register for the web interface if you wish by using the register link. If you have forgotten your password, a new randomly generated one will be sent to you by following the process from the "Forgotten your password?" link. Both of these mechanisms send email to the registered address and use a web link in the email to verify the account creation or resetting of the password.

2.4 Email interface

The email interface uses specially formatted tags on the subject line to link a given email to a message. This tag occurs first on the subject line (words like Re:, Fwd: preceding the tag are ignored) and looks like '[issue345]'. The tag consists of an open left square bracket, the word 'issue' the issue number (with no space between the word issue and the number) and a closing right square bracket.

When you reply to an email, it preserves the subject line. Your reply email will be addressed to one of the tracker's email addresses. There are two addresses associated with a sysadmin tracker. They correspond to the two types of messages: reply and comment. (Optionally the administrator can set up a third "data" email that corresponds to the data type of message to make recording data via email possible.)

The comment address usually has the phrase '_comment' just before the at '@' sign in the email address. When your email reply goes to this address, only people on the Technical List will see it. By default, the requester is not on this list. If you want to send an email that the requester will see, just remove the '_comment' from the to address and it will go the the reply address that includes the people on the Watcher list (where the requester is) and the Technical List.

You can also set the properties of the issue by including a tag of the form [propertyname1=value;propertyname2=value2] at the end of the subject line. If you are using Microsoft Outlook, this may not work because of a significant bug in that product. See the roundup setting properties documentation for more information on setting properties via the email interface.

Any text you type in the body of the message will be saved as a message in the issue. The message type is determined from the address you send the email to as described above. Attached files will be recorded as attachments in the issue and will be forwarded to the Watcher or Technical lists depending on the message type.

You can send your email to real people by adding them on the Cc or To or Bcc lines of your mail program. These people will not receive an email message from the tracker. For their replies to be recorded, they will have to include the tracker email address in their replies. Usually this can be done by selecting the "reply to all" functionality of their mailer.

2.5 The RSS announcement interfaces

There are two ways to get rss feeds from roundup.

Thanks to http://markpasc.org/code/rsswriter (seen at wayback 1) the sysadmin tracker has an XML rss 2.0 feed at TRACKER_WEB/_file/rss.xml. You can point RSSOwl, Bottomfeeder, Feedreader, Liferea, Feedly or any other RSS reader including those available for TWiki as a plugin to get up to the minute info on the top 30 newly changed issues.

This is a publicly available list that is updated when something changes, hence it is efficiently generated. However because it is public, updates to private issues are not shown in this rss feed.

If you want to see updates to private issues, log into roundup and create a query. Get the rss url by clicking on the rss icon at the bottom of the query results table. When your rss reader logs into roundup and accesses the rss url, private issues that you are able to view will also be included in the rss feed.

Every rss update generates the results of the query and formats it as an rss feed. This work has to occur even if nothing has changed since the prior rss query request so it increases the load on the roundup server, but because you are logged in a custom rss feed can be generated using your permissions.

2.6 Working with Issues

This section discusses how to work with issues and the properties of those issues.

2.6.1 Issue Priority

There are 6 issue priorities predefined in the shipped tracker. Some of the ideas below are taken from the rt user's guide.

critical:

This needs to be fixed immediately, stop whatever else you are doing and fix it. It has a high severity and high impact with no workaround. Lots of people are affected, or a critical person can't do their job. E.G. the main file server is down and nobody can work till it is functioning again.

urgent:

High severity and moderate impact with no workaround. E.G. the only mail server is down, no email can be sent/received.

high:

moderate severity, and moderate impact there may or may not be a workaround. e.g. the source code control system is down. People can still compile, test they just can't check the code in, the next scheduled check-in/release to test is still 4 days away.

routine:

priority of the routine day to day issues. Low severity, moderate impact, there may or may not be a workaround for these issues.

low:

Low severity, low impact, should have a workaround, or no workaround is needed.

minimum:

Low severity, no impact, no workaround is needed.

The priorities above are defined in terms of severity and impact. I tried (and may have failed 8-)) to create a relatively simple single entry priority rating. Severity is a measure of how bad the problem is, and how difficult it will be to solve. Impact is a measure of how it interferes with people getting their jobs done.

The total failure of a mail server is pretty severe, but it may not be an urgent priority if you have three redundant mail server, and email is still flowing. So that one mail server being down is moderate impact, and there is a workaround in place (i.e. mail is still flowing). So this would be a high priority.

Also you may want to look at the workingorder property to further order the outstanding issues.

2.6.2 Issue Status

There are 9 predefined statuses in the default sysadmin tracker they are:

New:

the default status for a newly created issue. It also means that no work has been done on the issue yet.

Open:

The issue has (usually) been assigned to somebody and work (even if it is just gathering information) has started on the issue. The issue is set to this status automatically by the detectors when an entry is in the New, Stalled, Resolved, Dead or Delete status, and a message is added from somebody other than the original creator.

Stalled:

Work cannot progress on this issue because the worker is waiting for information from some other party.

Hold:

Work is not progressing on this issue because of a decision to hold off working on the issue. Another decision to continue working the issue is needed before the issue is reopened. Automatic reopening can be done by setting an action.

Testing:

A fix is in place for the issue, but we are waiting for the customer to agree that the fix is sufficient to resolve this issue.

Resolved:

The issue has been resolved. This resolution may be that the issue is fixed, is unfounded etc.

Duplicate:

This issue is closed (no work will be performed on it) because it's a duplicate of another issue. To be a duplicate, it should have been submitted by the same person for the same originating incident.

Dead:

the issue has been closed because we choose not to work on it.

Delete:

the issue should never have been opened. Delete issues are candidates for being retired from the system.

2.6.2.1 Issue Status Indicators

When looking at related issues, it is very useful to know what status the related issues are in. To do this compactly, the issue numbers are displayed with a final letter that indicates the status of the issue. These letters can be set by the administrator, but by default are:

Status

Letter

Status

Letter

new

N

resolved

R

open

O

duplicate (copy)

C

stalled

S

dead

D

hold

H

delete

d

testing

T

2.6.3 Taking automatic actions

The four action properties:

  • actiondate

  • actionstatus

  • actioncomment

  • actionclearonmessage

provide a limited mechanism for scheduling an action on an issue. It allows setting an actiondate, actionstatus and actioncomment that are cleared after the actiondate has occurred. The actionclearonmessage property will cause the actiondate to be cleared if a message is submitted to the issue. This is useful for resolving a message after say three days if there is no activity. If there is activity, the automatic resolution is disabled. Actions will not be performed for resolved, duplicate, or deleted issues.

If an action is pending, you will see an "action pending" link next to the issue number at the top of the default issue view screen. Clicking on that link will take to you to the edit fields view at the action fields section.

For this to work, your roundup administrator must run the roundup-action script daily to actually perform the actions.

2.6.3.1 Example actions
Screenshot used to set an action on an issue. The interface allows you to set the date of the action, the new state of the issue, a comment to be added when the action takes effect and if the action should be disabled if the issue is updated.

Configuring an action on an issue.

To automatically resolve an issue on a given date, set the actionstatus to resolved and the actiondate to the date you wish to resolve the ticket on. This is useful if you state that you will resolve a ticket in N days if there is no response. Note that you are still responsible for clearing the action if there is a response and you don't want the ticket to resolve. It may also be a good idea to set the actioncomment to "issue 345 automatically closed after N days without a response." This way you will get the email and can reopen the ticket by replying, or by manually setting its status in the web interface.

To remind you about a ticket on its start date, set the actiondate property to the start date, and add an actioncomment of "Start issue 345 today", and leave the actionstatus as '- no selection -'. On the given day, the actioncomment will be added to the issue, and an email will be sent to everybody on the Technical List (which includes you, the issue owner, by default).

These fields can also be assigned in the subject line of an email to the issue if you don't have access to the web interface.

2.6.4 Using comment and reply messages

The sysadmin tracker uses three types of change notes/messages. These types are replies, comments and data. The reason for this is to reduce the amount of email that people get on an issue. On a given issue, only one or two messages may have to go to the requester, but there may be dozens of messages recording how the work was done and intermediate steps taken in finishing it. By recording this intermediate info, the issue can be referred to later if a similar problem crops up. Then the issue can be used as the standard way of solving (or not solving) the problem. The two primary message types are used as follows:

  • reply messages - are used to interact with the requester and are forwarded to both the the Watcher and Technical lists. They are visible to all users in the web interface.

  • comment messages - are used to interact with other technical people, and are forwarded to only the Technical list. They are visible in the web interface to users:

    • on the Technical List for the issue

    • that authored or received the message (i.e. they were on the technical list at the time the message was sent)

    • that have the Agent role or another role with the SeeComment permission.

Associated with a message of any type are the following properties:

  • Time spent - records an interval of how long it took to do what is described in the message. This interval is associated with the message as well as being associated with the issue that the message is sent to.

  • Cc - Sends a copy of the message to parties not on the Watcher or Technical lists. This is useful if you have a manager should be notified about a particular issue (need to purchase a replacement disk drive), but doesn't need to be on the regular lists. This field accepts a comma separated list of email addresses. The message that the people on the Cc field receive is processed by the tracker before being sent, so the from address is the tracker address.

  • Change note - the actual text of your message. If the change note is empty, no change notification email is sent.

  • File - upload one or more files with your message. They are linked to the message and to the issue. It is also sent as an attachment to all the people who receive the change notification email. Note multiple file attachment needs support in the browser and often works only if the files are in the same directory.

By default there is a third type of message: "data" that does not automatically generate email. It is used to record information for historic or other purposes where people do not need to be notified about it. It has the same properties as comments and replies, so if you are generating a data message in the web interface you can manually enter a Cc address if you want to forward the data message to somebody.

2.6.5 Issue relations

This tracker defines three different relationships between issues:

  • dependson

  • groups

  • seealso

Either the dependson or groups relation replaces the classic tracker "superseder" property whose meaning seems to be incompletely defined. The sections below define each type.

FIXME: document "reverse links". (30), (-30), (+30) supported in multilinks to the same class.

2.6.5.1 Dependson Relationship

If issue A has issue B listed in issue A's dependson multilink property, issue A can't be resolved until B is resolved.

When the last unresolved issue in A's dependson property is resolved, issue A will have its status changed to open. In this case a comment is added to the issue that it is being opened so verynosy (technical list) notifications are sent out since assigned to people are on the technical list.

If one of issue A's dependson issues is unresolved, issue A will be reopened if issue A is resolved.

2.6.5.2 Groups Relationship

If issue A has issue B and issue C listed in issue A's group it means that updates (messages, status changes etc) to issue A should be applied to issues B and C. You would use it when you have multiple issues that are all solved by the same solution. Think of it as a merging of issues that preserves the individuality of the issues and permits un-merging if issue C turns out to not be solved by the solution to issue B.

It implements forwards and backwards (downward and upward) message propagation. This will make sure that the grouping issues will get the message so that their nosy people can be notified of changes.

In a group hierarchy like:

A -----+--------- B --------+------- C --------+------- D
       |                    |                  +------- E
       |                    +-------- F
       |                    +-------- G --------+--------- H
       |                                        +--------- I
       +--------- J ---+-- K
                       +-- L

update/email for H goes up the grouping chain to G, B, A. Update/email sent to G will go down to H, I and up to B, A. Update/email sent to A will go down to all issues A-L. This means that an issue that groups another issue will see all the messages made to its groupees. Also all the groupees will see the messages sent to the grouping issue.

2.6.5.3 Seealso Relationship

A general linking field without any special meaning. Since issues can be hyperlinked in the message bodies, this is somewhat redundant, but it is useful so that programs can easily find the links without having to grovel through all of the messages.

2.6.6 Making an Issue Private

Some issues contain sensitive information. For example security issues, requests that involve firing people etc. By setting the Private option, access to the issue, all its messages, and all its files is restricted to users associated with the issue. See the Security Model section for further details.

2.7 Working with Users

On the left hand pane in the Administration section, you can access an index page of users with the "User List" link. Then use your browser's search capability to find the right user. When you click on the username link, you will transfer to the user's page. If you click on the tickets link in the username column, you will see a list of open tickets grouped by status. This is a standard issue index page so you can sort and group then differently. This is useful to find out what the caller is submitting, what is currently open etc.

If you chose to go the user's page, you will be able to view the following fields:

  • Name - the user's real name.

  • Login Name - the login name listed as the user in all fields.

  • Phone - phone number of person.

  • Organisation - the organisation/department etc of the user.

  • Timezone - times in roundup are stored in GMT. If this is a number, the value is added (or subtracted if negative) from the time when they are listed in the web interface. If your installation of python includes the pytz library, you can choose timezones like "US/New York" or "America/Panama" that support fractional hour offsets and timezone changes such as daylight savings time. See the timezone section below for further discussion.

  • Nosy Topics - If an issue is created or modified to have the topic listed here, the user on this page will be added to the nosy list automatically.

Displayed at the top of the page is a link to the same view as the tickets link in the user index page so that you can quickly see prior ticket by this user.

In the future other searches including issues where the user is nosy on the ticket will also be supported.

2.7.1 The fields

Even though you may not be able to view all of the fields on another user's page, you can view your own by selecting the "My Details" link in the left hand column. The fields are:

  • Name - the user's real name.

  • Login Name - the login name. It is used to label all references to the user. It can consist of alphanumerics and the symbols: . @ _ - % !.

  • Login/Confirm password - type in your password for the web interface and type it in a second time to confirm the entry.

  • Phone - phone number of person.

  • Organisation - the organisation/department etc of the user.

  • Timezone - times in roundup are stored in GMT. If your installation of python includes the pytz library, you are shown a select control. You can choose timezones like "US/New York" or "America/Panama" that support fractional hour offsets and timezone changes such as daylight savings time. If you are presented with a field that you can type in, then timezone is a number. The value is added (or subtracted if negative) from the time when they are listed in the web interface. See the timezone section below for further discussion.

  • E-mail address - email is sent to this address. It is the primary email address of the user.

  • Alternate email addresses - often people have multiple addresses that they can send email from. E.G. on the machine foo, I may be foo@example.org, but I receive my email at rouilj@example.org. The email addresses listed here will allow the proper user to be assigned to the inbound email even if it is sent from a different system.

Below these fields a table of your available/assigned queries is displayed. This table provides the ability to edit, display or remove the query from your list of queries. At the bottom of the page is shown a history of changes to the user.

2.7.1.1 Timezone

Symbolic timezones (UTC, America/New York) are supported only when the python pytz package is installed. The about page will report if pytz is installed and used.

If it is not installed, the timezone is a positive or negative integer. It is edited using a standard text entry box. It is not a timezone such as US/Eastern or America/New_York. If you have a daylight savings time change you will have to change the offset to make times be displayed properly.

In this mode the timezone is added to all times regardless of the date. E.G. If I look at an issue with messages from December, which should be -4 hours from GMT in July when its -5 hours from GMT, the time will be modified by -5 hours (my current timezone setting) rather then the -4 hours that it should be modified by.

If the pytz package is installed, then you can use a timezone like America/New_York. You change it using a drop down menu in the user page. When using this mode, the timezone changes (standard vs daylight savings) will be properly applied to the date.

The default timezone for a user is UTC or 0 hour offset.

2.7.2 Finding issues requested by the user

Clicking on the link at the top of a user's page, or on the (tickets) link next to the user's name in the user list will provide a list of tickets that the user has requested.

3 Security Model

As mentioned above you can hide/make private issues. When you do this the messages and files attached to the issue are also hidden. This section describes the access rules for private issues and the access rights of users with the various roles.

All security for issues, msgs and files is based on the access setting (private set to true (checked) or false (unchecked)) of the issue and the contents of the nosy, verynosy, requestedby and assignedto field.

3.1 Private Issue Access Rules

A user can view (and edit unless otherwise noted) a private issue if one of the following is true:

  • The user is the Requested by user. Any user who requested an issue can edit the issue. This includes Provisional Users since they need to be able to respond to the issue. This access right does not allow the ability to make an issue public or change the technical list.

  • The user is on the Watcher List. These users can not change the technical list or make an issue public. (Note, the user requesting the issue is usually on the Watcher List, but they have access even when removed from the list. The Requested by user can be changed if needed.)

  • The user is on the Technical List. These users are allowed to change the technical list and make the issue public.

  • The user is assigned to the issue. This user is allowed to change the technical list and make the issue public.

  • Any user with the Agent role if there is no assigned to user. These users are allowed to change the technical list and make the issue public. (See Agent role access rights.)

3.2 Files and Messages linked to a Private Issue

A user can see a file or message attached to a private issue if:

  1. The user is the creator of the msg or file.

  2. The user was already a recipient of the message.

  3. The user is allowed access to a private issue where the file or msg is linked.

  4. The file or message is linked to a public issue. There is no web based way to do this manually. You need to use the roundup-admin, xmlrpc, email, or programmatic interface.

    However Issue Relationships Groups trade their messages. As a result an issue can not be made private if it is a member of a group or groups any issues. An attempt to make an issue private will result in an error. Also private issues can not be added to a group. This may be relaxed in the future.

    Also before a msg or file can be linked to another (possibly public) issue, the user making the link must be able to view the file or msg. This allows only authorized people to make a file or msg public.

3.3 Access Rights for Primary and Supplementary Roles

These are the default rights assigned to users with particular roles. A user must have one of these primary roles in the tracker in order to be able to use it.

User:

users with this role are allowed to:

  • create public and private issues.

  • view and edit all public issues.

  • view reply messages on public issues.

  • view comment/data messages they create.

  • view/download all files on public issues.

  • update the Watcher and Technical lists of public issues.

  • view and edit private issues subject to the access rules in Private Access Rules.

  • have SeeAbout rights.

Provisional User:

users with this role are allowed to:

  • create public and private issues.

  • view all public issues.

  • view reply messages on public issues

  • view comment/data messages they create.

  • view/download all files on public issues.

  • edit issues they created (technically they have to be the Requested by user, which starts as the creator).

  • view and edit private issues subject to the access rules in Private Access Rules.

  • have SeeAbout rights.

Anonymous:

users with this role are allowed to:

  • view all public issues.

  • view reply messages.

  • have SeeAbout rights.

they can not:

  • edit or create issues.

  • view a private issue even if Private Access Rules would usually allow them to access it.

  • view comment/data messages

Admin:

users with this role:

  • have full control over the tracker.

  • bypass all access checks so can read/edit/create/search/retire/restore all items in the system.

  • can edit the roles of users.

  • can be assigned to issues.

  • have SetAnyStatus, SeeAbout, and SeeAboutPrivDetails rights.

Access to comment and data messages can be changed by changing the schema. Adding the SeeComments right to the role allows users with that role to see data and comment messages on issues that they can access.

The roles below are supplementary roles adding additional rights for the user in the tracker. They can be added to the user's list of Roles separated by existing roles with a comma.

Agent:

users with this role:

  • can be assigned to an issue as the owner.

  • have edit rights to private issues if there is nobody assigned to the issue.

  • has SeeComment rights that allow viewing of all comments and data messages if the issue is viewable by the user. See the reply and comment section for details on the message types.

SeeComment:

users with this role are allowed to view comment and data messages for any issue the user can view. This permits users who are regular Users or Provisional Users to also see the background comments using the web interface. It does not notify them of comments. They need to be on the Technical (verynosy) list for the issue to receive comment notifications.

SetAnyStatus:

users with this role are allowed to assign any status to a ticket bypassing any transition workflow.

SeeAbout:

users with this role are allowed to see the about page for the tracker. This displays configuration and other info about how the tracker is deployed.

SeeAboutPrivDetails:

users with this role can see information about the environment the tracker is run in. This includes Python search paths, cookies for the user and other internal details.

4 Issue Property Reference

The properties shown in issue and message views are listed in alphabetic order below. For each property, the display title is given first, and the internal property name is given in parenthesis after the display name. The internal property name is what is displayed in pull down lists. After that is the type of property for which you should look at the standard roundup documentation on entering values to find out how to interact with that property type.

4.1 Action Clear on Message (actionclearonmessage)

  • Type: Boolean

The actionclearonmessage property is a boolean value that if set will cause the actiondate to be cleared if a message is submitted to the issue.

4.2 Action Comment (actioncomment)

  • Type: String

The comment to be sent when the action occurs. It will be added to the issue. Note that there is no actionreply, so the text entered here will not be sent to people on the Watcher list.

4.3 Action Date (actiondate)

  • Type: Date

A date whose time is ignored, only the date portion is used. On that day the action will occur. The action is triggered by a cron job, so the time when the action is triggered is controlled by the cron job.

4.4 Action Status (actionstatus)

  • Type: Constrained (Link to Status)

The issue will be changed to this status when the action triggers.

4.5 Assigned To (assignedto) (aka Owner)

  • Type: Constrained (Link to User)

The name of the person currently working or responsible for this issue. If you want to have multiple people responsible, you can create additional tickets and group issues together, or use the dependson relation to divide the issue into multiple parts. This is also referred to as the owner of a ticket.

If you change this value, you should remove the original user from the Technical list if they should not get future updates on the ticket.

4.6 Billing info (billinginfo)

  • Type: String

Store billing info for this issue. This could be a department name or other free form text.

4.7 Cc (cc)

  • Type: String, comma separated list of email addresses

This provides a way to send a message to people not on a nosy list for the issue. It is equivalent to sending email to the tracker with other recipients on the To or Cc lines of the email (except the email that is sent will come from the tracker). Enter a comma separated list of valid email addresses. It will not accept user names, you must use email addresses. This is also a fast way of creating a new user at the given email address as all addresses create new users.

4.8 Depends On (dependson)

  • Type: Constrained (Multilink to Issues)

The list of issues that this issue depends on. The issues will be listed with a letter after their names. See Issue Status Indicators for information on the letters. Also see Issue Relationships Dependson for further details.

4.9 Due Date (duedate)

  • Type: Date

The date the issue should be completed on.

4.10 FYI (fyi)

  • Type: String

Used to record summary notes and details that get buried in the issue trail. Useful for noting ticket Id's for phone calls, serial numbers of equipment etc.

4.11 Groups (group)

  • Type: Constrained (Multilink to Issues)

The list of issues that this issue groups. The issues will be listed with a letter after their names. See Issue Status Indicators for information on the letters. Also see Issue Relationships Groups for further details.

4.12 Lead Time (leadtime)

  • Type: Interval

The estimated amount of time that solving this issue will take. In theory, the due date - the lead time is the theoretical start date for the issue.

So in theory this is the same as the difference between the Start Date and the Due Date. However, it may be advantageous to have an issue done before the due date. In this case, the math won't work out, but the actual completion date will be the start date plus the lead time.

With a suitable escalation program, (not yet written), this can be used with the due date to escalate the priority of the issue.

4.13 Message Type (messagetype)

  • Type: Constrained (Link to Messagetype)

When creating a new note/message you need to select the message type. If you select 'reply - to all', it will be emailed to all the users on the Technical and Watchers lists. If you select 'comment - to technical', the new message will be emailed only to the people on the technical list. If you select 'data - to nobody' it will be emailed only to the addresses listed in the Cc (Carbon copy) field.

The first three characters of the message type name are used to identify the message type when the message is displayed as part of an issue.

Currently only "reply" type messages are visible to all users who can view the issue. "Comment" and "data" type messages are visible only to users on the technical list.

4.14 Needs Reply (needsreply)

  • Type: Boolean

Set to true if issue is not new and the last person to add a message is not the assignedto person. If there is no assignedto person, then set to true if last message addition was not done by person on the technical (verynosy) list. This is set to false only if the last message added was done by the assignedto person or a person on the verynosy list if the ticket is not assigned.

This causes issues that need a response to have ** prepended to the title in index displays and a '(reply requested)' note to be added to the page header in issue display mode. It is useful if you are working in the field, and have a browser, but no email access to be notified of responses to issues.

4.15 Priority (priority)

  • Type: Constrained (Link to Priority)

Used to set the priority of the issue. The defined priorities are defined in Issue Priority.

4.16 Private (private)

  • Type: Boolean

If set to true, it restricts who may see the issue. Details on the security policy are detailed at Private Access Rules.

4.17 Queue (queue)

  • Type: Constrained (Link to Queue)

Categorizing an issue to be handled by a particular group of people. Associated with each queue is a default announcement list that is independent of the Watcher or Technical lists. This default list is used to announce the issue if nobody is assigned to the issue.

4.18 Requested by (requestedby)

  • Type: Constrained (Link to User)

Used to record the person who requested this issue. An auditor sets it to the creator of issue by default. It is useful for help desk purposes, where the person creating the issue is not the person requesting the issue.

If you change the requested by field, you should remove the original person from the nosy list manually if the original person should no longer get updates.

Unlike the creator property associated with an issue, this can be changed to reflect the person actually requesting the issue rather than the person who physically created the issue.

4.19 See Also (seealso)

  • Type: Constrained (Multilink to Issues)

Used to link issues that are related in some way. E.G. an issue is created because the printing subsystem, is backed up. The first line support person can't clear the problem because he doesn't know how. So he passes it to the second line person. The second line person finds an issue that describes how to solve this problem and put the ID of this issue into the See Also property, and reassigns it to the first line support person.

It can also be used to link related issues for justifying purchase of a new disk. Every problem that comes in that can be solved by purchasing a new disk can be put into the seealso property so that a report can be generated of all the additional work caused by the lack of disk space. Also see Issue Relationships See Also for further details.

4.20 Start Date (startdate)

  • Type: Date

Enter the day the task should be started. If you wish the issue to be automatically opened on this date, see the Taking automatic actions section.

4.21 Status (status)

  • Type: Constrained (Link to Status)

Set the status of the issue. The defined statuses and their meanings are defined in the Issue Status section.

4.22 Superseder (superseder)

  • Type: Constrained (Multilink to Issues)

This is only visible on the edit fields or default issue view if it is not empty. It is left in place for compatibility with the classic trackers, but should not be used in the sysadmin tracker. Use the dependson, groups and seealso properties/fields instead.

4.23 Technical List (verynosy)

  • Type: Constrained (Multilink to User)

People in this list receive forwarded email for both comment AND reply messages.

4.24 Time Spent (timelog)

  • Type: Constrained (Multilink to Timelog)

Enter the amount of time worked on the issue here. This is actually linked to both the issue and any message that is created with it. Thus you can look at a message (that documents a particular phase of solving the issue) and find out how much time it took to perform the phase.

This is useful for future planning.

This can not be accessed using the email interface at this time.

4.25 Title (title)

  • Type: String

The title for the issue. It should be descriptive and easily distinguishable from others. For example use: "Build computer system for Joan Jetty" rather then just "Build computer system". This line will be shown in issue lists under the Title field.

4.26 Topics (topic)

  • Type: Constrained (Multilink to Keywords)

This is used to categorize the issue. E.G. keywords like hardware, software user_error can be assigned to the issue. This allows categorizing issues along multiple dimensions to allow statistics gathering. It can also be used to identify issues for followup (e.g. a First Time Failure keyword tat triggers further analysis). Note that keyword names should not contain a comma ','.

4.27 Watcher List (nosy)

  • Type: Constrained (Multilink to User)

People in this list receive forwarded email for ONLY reply messages.

4.28 Working Order (workingorder)

  • Type: Integer

Used to assign a working order to items. Useful when you have lots of things at the same priority.

5 Administering the tracker

This section assumes that you have read the roundup documentation on installing a tracker.

5.1 System level tasks

These tasks need to be done by somebody with access to a user or administrator interface on the computer hosting the tracker. They can't be done through the web interface.

5.1.1 Setting up the email interface

If you are using the email interface, you will need to set up (at least) two mail aliases for each tracker. The first alias is used for issue creation and replies to the issues. The second is used for comments. The two sendmail aliases you need look like:

tracker: |/tools/roundup/bin/roundup-mailgw -C msg
           -S "messagetype=reply - to all" /var/roundup/sysadmin

(the lines are split for readability. In the alias file they will be on the same line). Replace /tools/roundup/bin/roundup-mailgw by your path to the roundup-mailgw. This creates the email alias "tracker". All messages sent to it have their messagetype property set to "reply - to all". The roundup tracker instance is located at /var/roundup/sysadmin.

Then the comment alias is created and looks like:

tracker_comment: |/tools/roundup/bin/roundup-mailgw -C msg
           -S "messagetype=comment - to technical" /var/roundup/sysadmin

(the lines are split for readability. In the alias file they will be on the same line). Replace /tools/roundup/bin/roundup-mailgw by your path to the roundup-mailgw. This creates the alias tracker_comment. All messages sent to it have their messagetype property set to "comment - to technical". The roundup tracker instance is still located at /var/roundup/sysadmin.

If you wish you can add a similar entry for the messagetype data (tracker_data) to make entering data to a ticket easier.

If you are not using queues, or do not wish to have queue specific addresses, then you are done with the email setup for the sysadmin tracker. You still have to handle the email setup specified in the roundup documentation.

If you want to use queues (see Queue Use), you can have an email alias for each queue.

You may want to name your queues by department so all requests from a department are in the same queue:

department

queue

alias

sales

sales

sales_help@....

development

development

development_help@...

Alternatively you can arrange your queues according to the group that will work on the problem

group

queue

alias

networking

networking

network-help@...

web

web

web-help@...

email

sysadmin

email-help@...

To set up the queue specific addresses use the following aliases:

sales_help: |/tools/roundup/bin/roundup-mailgw
           -C msg -S "messagetype=reply - to all"
           -C issue -S queue=sales
           /var/roundup/sysadmin

The difference between these aliases and the ones above are setting the queue property on the issue.

Create one alias for each queue that should be able to create issues by email. Once the issue is created with default values, the normal tracker and comment aliases will be used for ongoing correspondence.

5.1.2 Modifying detectors/config.ini

There are some settings in detectors/config.ini that are unique to the sysadmin tracker.

Set the NEW_ISSUE_ANNOUNCE_DEFAULT variable to an email address where you want all new issues without an assigned queue or assignedto person to be announced. If it is set to None (the default) no email will be sent if queue is unassigned. If queue is assigned the email address(es) associated with the queue will be used.

Multiple email addresses can be specified using a , between them. No space is allowed in the string. A couple of examples are:

NEW_ISSUE_ANNOUNCE_DEFAULT = "sysadmin@example.com,sysadmin2@example.com"

NEW_ISSUE_ANNOUNCE_DEFAULT = "sysadmins"

Set the DEFAULT_PRIORITY variable to assign the priority to issues arriving via email that don't have a priority. This is the way to force a priority on emailed issues. For the web, setting a priority is enforced by the web interface. You can create a "Needs priority" priority and use it as the default. Then somebody can triage the issues with a "Needs priority" priority and assign a real priority. This is used in the default_priority.py detector/auditor. The default priority is routine:

DEFAULT_PRIORITY = 'routine'

Set COMMENT_TRACKER_EMAIL to the alias used for handling comment emails. This is usually the same as TRACKER_EMAIL except for comment messages rather then reply messages. If you choose the default with the _comment suffix, then there is no need to set this value, it is calculated automatically:

COMMENT_TRACKER_EMAIL = 'tracker_comment@%s'%MAIL_DOMAIN

5.1.3 Modifying extensions/config.ini

There are some settings in extensions/config.ini that are unique to the sysadmin tracker.

Using an email address to search for issues requested by a user can be enabled/disabled. This feature is described by the search goto box documentation. The entry looks like:

[jumpsearch]
search_by_email = no

By default the lookup is done using both primary and additional addresses. A simple edit of extensions/jumpSearch.py can change that to the primary addresses only.

If you are using the reCaptchaLogin extension, the keys, scores and supported version can be configured. The entry looks like:

[recaptcha]
# Configure the reCAPTCHAlogin extension module
# Adds a reCAPTCHA as part of the login form.
# See: https://developers.google.com/recaptcha/

# reCAPTCHA version: v2 (default) or v3
# version=v2

# secret key - if setting is commented out/missing or
# value is empty or value is set to none, module is disabled.
# secret = none

# Must set to the site key matching the secret key above.
# sitekey =

# If using google's reCAPTCHA v3, use this to set the passing score
# above/below 0.5 which is the default.
# score = 0.5

5.1.4 Setting up cron jobs

There are some functions that are carried out on a scheduled basis. On Unix, you can use cron, or self submitting at jobs to do this. On windows you may be able to use the at command or other scheduler. The two jobs done on a scheduled basis are to send daily (weekly) reminders to all assigned people about the issues they have open. Also the automatic action feature is carried out by a daily cron job.

5.1.4.1 Issue status reminders

Edit the cronjobs/roundup-reminder script to set the path to the roundup install directory.

Add the script cronjobs/roundup-reminder to the crontab of the user your cgi and mail gateways run as. Run the script daily (or weekly or any other schedule you want) in the early morning. It is called with the path to the roundup tracker home directory just like the roundup-admin command.

5.1.4.2 Automatic actions

Edit the cronjobs/roundup-action script to set the path to the roundup install directory.

Add the script cronjobs/roundup-action to the crontab of the user your cgi and mail gateways run as. Run the script daily in the early morning. It is called with the path to the roundup tracker home directory just like the roundup-admin command.

5.2 Tracker administrator tasks

You can customize the tracker classes as well. However some detectors may need to be modified since they will often embed the names of priorities and statuses in them. So you can change it in the web interface, but you may also need to get access to the system command line to fully implement the change.

5.2.1 Setting up supplementary classes in the HyperDB

There are a number of supplementary classes in the hyperdb.

5.2.1.1 Priority

See the description of the default priorities at Issue Priority.

The properties of this class are:

  • name - the name of the priority

  • order - the sort/display order

  • threshold - a property intended for automatic escalation of status using an external script. For example as the due date approaches, the new priority could be defined as: (threshold of current priority - threshold of max priority) divided by (number of days) - 1 till issue is due. This way issue would spend one day at highest priority. More complex escalation can be calculated using the lead time, Base priority determined from journal entries etc. To be implemented.

  • help - currently unused, but meant to be a brief description of the purpose of the priority to be used in on-line help.

5.2.1.2 Queue

This defines a queue for the issue. The queue is a flexible mechanism that can be used to group issues by:

  • functional area - network, unix admin, Windows admin, email specialist

  • administrative groups - test, training, integration, development, customer support. Admins that work for each group watch their own queue

  • service level: level 1 support, level 2 support, level 3 support so second and third level support personnel only watch their queues.

The properties of the queue object are:

  • name - the name of the queue

  • order - the sort/display order

  • email - the email property is used by newissuecopy to send notification emails. When a new issue is created or assigned to a given queue and nobody is assigned to the issue, the email is sent to the value of this property. The email property will also be used by the queue reactor (not yet written) to send email when an issue is moved from one queue to another if nobody is assigned to the issue. Multiple email addresses can be specified using "," between them. E.G. sysadmin1@example.com,sysadmin2@example.com

  • help - currently unused, but meant to be a brief description of the purpose of the queue to be used in on-line help.

This class is edited using the csv module, so the email string MUST be enclosed in quotes.

5.2.1.3 Status

Status items have 6 properties by default:

  • name - the name of the status (e.g. new, open etc.)

  • abbreviation - a one character abbreviation for the status. Used when displaying linked issues.

  • order - number indicating the sorting and display order for the status.

  • help - currently unused, but meant to be a brief description of the purpose of the status to be used in on-line help.

  • requiredpermissions - list of permissions required by the user to set an issue to this status.

  • transitions - list of valid statuses that this status can be changed to.

The name, order and help properties are self explanatory.

The abbreviation property is used to indicate the issue status. See Issue Status Indicators for more information.

The requiredpermissions property lists the permissions the user must have to select this status. E.G. you may only want managers to be able to resolve an issue, or you may want to stop regular users (i.e. people who generate the issues rather then the people who solve the issues.) from selecting any status except new and resolved. This property takes a colon separated list of required permissions. E.G. "manager:admin". If this property is empty, anybody is able to select this status.

The transitions property specifies what the next valid statuses are for a given status. E.G. if the testing status has its transitions property set to:

open:hold:stalled

(note this is translated into status id's when submitted) then an issue that was in the testing status couldn't be changed to the new status. The issue would have to be moved from testing to one of the open, hold or stalled status before it could be moved to the new status (assuming those states allowed a transition to the new status). The value for this is a colon separated list of statuses. If this field is empty, any status can be selected.

The names of the statuses are hard coded in detectors and extensions. So changing the names of the statuses will require changing the names in the detectors/extensions.

5.2.2 Druids for guided issue creation

Druids provide a way to guide your users to supply information required for a particular task. It helps eliminate the "20 questions" problem caused when users forget to supply critical data needed to fix the issue.

Each field in a standard roundup form is backed by a property in the database. However for many tasks it makes no sense to clutter the database with fields that will be used for only a few special purpose tasks. Druids can be constructed to get around this problem.

The user can access the druids by using the "Create with Druid" link under the "Create New" link in the Issues section of the left hand menu.

5.2.2.1 Druid anatomy

Druids consist of three parts:

  1. A web form in the html/druids directory of the tracker home.

  2. An action extension that is used to turn the druid form into an issue.

  3. An instance in the druid class to make the druid available to users.

There is a default GuidedMessage druid action defined in extensions/druid_actions.py. This action processes the submitted form. For each field that matches a property of the issue, it will set the the value for the issue. It also accepts tilde fields. These are fields whose name starts with a tilde ~. The fields do not correspond to any (database) properties of the issue, but will be incorporated as labeled data in the first message submitted to the issue.

For example the following form snippet (see html/druids/issue.guidedmessage.html):

<form method="POST" name="GuidedMessage" id="Guided_Message"
   enctype="multipart/form-data"
   tal:attributes="action context/designator">

<!-- set titles for tickets -->
<label for="title" class="ontop"><b>One Line Summary:</b></label><br>
  <span tal:omit-tag="" tal:content="structure
                  python:context.title.field(id='title',
                  required='true', style='width: 100%')">title</span>
<label for="~sysname" class="ontop"><b>System Name:</b></label><br>
  <input name="~sysname" id="~sysname" tal:attributes="value
            request/form/~sysname/value | string:System Name"><br>
<label for="~line1" class="ontop"><b>Line 1:</b></label><br>
  <input name="~line1" tal:attributes="value
             request/form/~line1/value | string:line1"><br>
 ...
<input type="hidden" name="@action" value="druid_guidedmessage" />
<input name="@csrf" type="hidden" tal:attributes="value
                     python:utils.anti_csrf_nonce()">
<input name="~druidis" type="hidden" value="guidedmessage">
<input name="submit_button" value="Submit New Entry" type="submit" />

will invoke the @action druid_guidedmessage. It will trigger the druid type guidedmessage set by the ~druidis hidden input. The guidedmessage subtype is configured in extensions/druid_actions.py using the following dictionary entry:

'guidedmessage': [ '~sysname', '~line1', '~line2', '~line3' ],

The title field is declared just as in any other template (e.g. issue.edit.html). The fields ~sysname and ~line1 will be prepended to the contents of any @note field and submitted as the first note in the issue. The order of the fields in the list is the same order they will be prepended to the message. The label for the fields is the name of the field without the leading tilde. An example note:

sysname: druid
line1: Filled in using the step by step driver for the guided issue druid.

Note is:
Free form text here is not guided.
5.2.2.2 Deploying a druid

To make the druid available to users, you install the template, add the action and configure a druid object using the admin interface to edit the druid class. The druid class consists of 6 fields:

id:

the id for the druid.

description:

the description shown in the druid index page. This can be multiline by embedding html line breaks in the value.

name:

a name for the druid.

order:

an integer that is used to order the druids on the index page.

tag:

a string (tag) that could be used for filtering druids.

url:

the url relative to the tracker web that accesses the form.

Values for the example above would be:

  • id: 4

  • description: Create a new issue with a message<br>filled in using a form,

  • name: Example guided issue creation

  • order: 1

  • tag: Example

  • url: issue?@template=druids/guidedmessage

In the generic class csv editor, you would paste all the values together with commas between them on a single line.

Generic editing screen for a class. Shown editing the druid class. Consists of directions above a textedit area that contains comma separated value (csv) text. The text has 6 columns and 3 rows. The first row is a header: id, description, name, order, tag, url.

Using the generic class editor to edit a druid configuration.

The figure shows the editing interface which is available to a user with admin rights. In this case the admin user with a red theme is used to display the edit form.

5.2.2.3 Javascript enhancement, driver.js

The tracker includes driver.js 2 a javascript library for guiding the user through the form by highlighting fields and displaying popups to inform the user about how to fill in the field. Describing the details on how to configure this is beyond the scope of this document. See the home page for the package and look at html/druids/guidedmessage.js for the configuration used for the Example Guided Issue druid.

5.3 The about page

This page provides information on the tracker.

Screenshot of a page showing details on the tracker and the environment in which it runs.

The about page showing tracker details available to all users.

This includes info about the operating environment, database configuration options, modules found by the running tracker (e.g pytz as mentioned in the timezone section). This info can be useful when troubleshooting a user's problems.

If you are an admin, you also get:

  • the Python module path (restricted to admins since it can show directories on the host)

  • cgi environment variables including cookies

  • runtime state of cookies and whether javascript is enabled on the client.

The admin restriction is controlled by the AboutPage extension in the extension/templating.py. You can change this and restart the tracker if you want to display additional information for a normal user.

6 Transitioning from the classic tracker

If you are starting with a fresh tracker, you can skip this section. If you want to import data from a classic tracker into a sysadmin tracker, you should read this section.

Many items (topics, nosy etc) will translate without a problem. The superseder relation will be displayed as needed.

  1. create a new initialized sysadmin tracker with the same database type as your classic tracker.

  2. shutdown classic tracker.

  3. backup classic tracker.

  4. copy the detectors and html directories from the newly initialized sysadmin tracker to the classic tracker's directory.

  5. copy the database files for new objects into the db directory. don't overwrite any of the class .db files that already exist. I don't know how to do this with anything other then the dbm or db databases. (e.g. mysql, or sqllite)

  6. merge settings in classic config.py into sysadmin tracker config.py and use the sysadmin config.py.

  7. Copy the dbinit.py and interfaces.py file from the sysadmin tracker into the classic tracker.

  8. Copy roundup/roundup/history.py to the site-packages/roundup directory in your python installation. The file needs to be in the same directory with the admin.py and security.py modules.

  9. Bring up the classic tracker.

  10. Add the 3 searches (Note: they are wrapped for readability, leading spaces on following lines should be removed.)

    klass="issue" name="WatcherTechnical"
        url=":columns=title,id,status,queue,topic,duedate,
        creator,assignedto,activity,nosy,verynosy&
        :pagesize=50&:startwith=0"
    
      klass="issue" name="Relationships"
        url=":columns=title,id,status,queue,duedate,assignedto,
        activity,dependson,group,seealso&:filter=status&
        status=-1,1,2,3,4,5&:pagesize=50&:startwith=0"
    
      klass="issue" name="Schedule"
        url=":columns=title,id,status,queue,duedate,leadtime,startdate,
        creator,assignedto,activity&:sort=-duedate&:pagesize=50&
        :startwith=0&filter=status&status=-1,1,2,3,4,5&
        @sort=-leadtime&@group=duedate"

    using the CSV interface.

  11. remove the leading ?'s from the url fields in the tracker queries using the CSV interface.

  12. set status class abbreviation property otherwise you don't get abbrevs on issue links. Change description/names of statuses so that resolved, new (unread) and open (chatting) exist.

  13. set default announce email for new issues. Change from sysadmin.

  14. set email addresses for per queue announcements if needed.

  1. run scripts to link files associated with issues to the issue so they are displayed in the gui interface. A Bourne shell script like:

    #! /bin/sh
    PATH=/tools/roundup:$PATH
    
    roundup_home=/data/roundup/admin
    
    for i in "$@"
    do
      case $i in
        [0-9]*) issues="$issues $i"
            ;;
        /*) roundup_home=$i
      esac
    done
    
    for issue in ${issues:-`roundup-admin -s -i ${roundup_home} list issue`}
    do
      echo "Running over issue $issue"
      files=""
      for msg in `roundup-admin -s -i ${roundup_home} get messages issue$issue`
      do
        echo "Scanning message $msg"
        files="$files,`roundup-admin -c -i ${roundup_home} get files msg$msg`"
      done
      if echo "$files" | grep "[0-9]" > /dev/null; then
        files=`echo $files | sed -e 's/[,],*/,/g' -e 's/^,//' -e 's/,$//'`
        echo "Files are $files"
        roundup-admin -s -i ${roundup_home} set issue$issue files=$files
      fi
    done

    This will take a while, but it runs over all issues making sure to set the files property of the issue to the union of the files properties for all the issues messages.

  2. You will be able to see your superseder field unless it is empty. At which point you can forget it exists.

7 Customizing the tracker

See the roundup customization document for technical issues.

Enhance the tracker to include asset tracking by creating a new hyperdb issue like object called asset. This asset can be linked to messages to record repairs, changes of ownership, etc. Also these assets can be linked into a hardware field of an issue to record the issues caused by this hardware.

7.1 Css changes for priority and status

Each issue row in the issue index page has classes added to it that you can use to customize the display of the issue. You can display different priority messages in different background colors or fonts or set the row color based on the current status of the ticket.

There is a commented out example to change the display settings based on status at the end of tracker_home/html/css/sysadmin.css. It basically involves setting the data cells located in a row with the class status-<status>. For example:

table.list tr.status-open td {
    background-color: #FFA07A;
    font-weight: bold;
}

will set the background of the row to light salmon for tickets that are open. Similarly using the class prio-<priority> allows you to control the color based on priorities. There used to be a color property that was never implemented in the priority class. This mechanism has replaced that idea.

8 Testing the tracker

(Note: I use a Bourne like shell, so where you see SENDMAILDEBUG=... before a command invocation, you should set the environment variable SENDMAILDEBUG before running the command, and remove the SENDMAILDEBUG=...[space] stuff from the command line if you use a csh like shell.)

Create new tracker:

/tools/roundup/bin/roundup-admin -i /var/roundup/testing \
   install sysadmin anydbm admin

edit config.ini setting required variables. Set the url to point to testing rather than sysadmin:

/tools/roundup/bin/roundup-admin -i /var/roundup/testing \
     initialise admin

run:

roundup-server -p 8080 -n 127.0.0.1 testing=/var/roundup/testing

test the following:

msg should be created with an email to rouilj@example.org. The created issue should have:

nosy: rouilj@example.org
priority: routine
status: new
title: test 4a

An email should be sent out to rouilj@example.org with a reply address of: issue_tracker@example.org. The subject line of the email should include the proper issue tag. An identical message should be sent to sysadmins.

Also the created message should have type reply.

where issue4 is REPLACED by the issue just created in the last step. Send this email to:

SENDMAILDEBUG=/tmp/smd.email roundup-mailgw -C msg \
  -S "messagetype=comment - to technical" /var/roundup/testing

An email should be sent out to roundup-admin@example.org with a reply address of: issue_tracker_comment@example.org. The subject line of the email should include the proper issue tag.

This finishes basic test of mailgw setting message type (or any prop) verynosy and nosy message processing as well as default_priority.py

to:

SENDMAILDEBUG=/tmp/smd.email roundup-mailgw -C msg \
  -S "messagetype=reply - to all" /var/roundup/testing

testing automatic actions:

  1. Create new issue on the web interface.

  2. Edit the issue and add today's date to the actiondate field, set a status of hold.

  3. from the tracker directory, run the roundup-action script with the path to the tracker like:

    SENDMAILDEBUG=/tmp/mail crontabs/roundup-action $PWD
  4. the issue should have its status changed to hold, and the action fields (actiondate, actionstatus, actioncomment) should be empty.

  5. edit the issue and add today's date to the actiondate field, set an actioncomment.

  6. run the roundup-action script as above.

  7. the issue should have its status unchanged, (even if a nosy reactor or something triggers) and should have a new message and the action fields should be empty.

  8. edit the issue and add today's date to the actiondate field. Don't set any other action fields.

  9. run the roundup-action script as above.

  10. the issue should have its status unchanged, but there should be a history entry showing the unchanged status. Also the last changed time for the issue will be updated.

9 Gotchas, bugs and warnings

As with all new software there are some gotchas or bugs that can't be worked around.

9.2 Ticket won't resolve when status is resolved and a message is entered

You set resolved on an issue, and enter a message. You submit the change and see that the message has been entered, but the ticket is not resolved.

This occurs when the issue is groupedby another issue. What happens is that the message you enter is propagated to the parent issue (the grouper). Then the parent issue has been changed and it tries to propagate its status to its child issues. This overrides the status set in the web interface.

This could be considered a bug. I am not really sure how it should work. To solve the problem, enter a message, then set the status without a message. This should stop the upward propagation that occurs for messages and clobbers the set status.

Now is the fact that you can set the status of a grouped issue independently of its grouper a bug??

9.3 Ticket won't resolve because of depends and group issues

It is possible to create a loop of issues such that a depends on issue is also a group issue of some parent issue. In this case, you will not be able to resolve the issue because:

  • Resolving the group issue will change change it resulting in its being reopened, which reopens any issues the have it on the dependson list.

The detectors do detect using the same issue on an issues dependson and groups property, or assigning the issue to its own dependson or groups properties. They just don't walk the entire tree looking for loops.

The solution is to get rid of the group or depends link that is causing the loop.

9.4 "Make a copy" uses default multiselect text interface

The "Make a copy" link produces a new issue that uses the default text entry based interface with (list) assistant for multiple item properties.

A normal option multiselect (with select2 support) will be used when the new issue is saved and the issue is displayed.

9.5 Setting fields via email fails when using Microsoft Outlook.

Microsoft Outlook does not follow the standard for creating continuation header lines in email. Outlook will fold the subject line in the middle of a word rather than folding only at whitespace as specified by RFC822 and later RFC2822. When the line is rejoined, whitespace is inserted at the point of the fold as specified by the RFC's. This can cause unintended white space to be added to the subject line which prevents the subject line parser from recognizing the [] enclosed property settings. E.G. it can turn "[status=resolved]" into "[statu s=resolved]". Because of this, it can be difficult to set properties using []'d commands at the end of the subject line. Until Microsoft manages to fix their software, this problem will continue to exist, but by judicious padding of the subject line with spaces the issue can be worked around although it's a major pain in the a**.

10 Todo

There are many areas for enhancement. A few open ideas include:

10.1 Enhancements to roundup

Here are some roundup core enhancements that this tracker would benefit from.

  • Email gateway arguments to -S (set) should do lookup by key field or id number, so messagetype=2 works.

  • Support setting fields in the message body by starting the message with lines like:

    [status=resolved]

    roundup should strip these lines from the recorded and sent message. This helps when you use a broken mailer like Microsoft Outlook, or when you have a lot of status info to insert. Consider proposal at: https://sourceforge.net/p/roundup/mailman/message/30536183/ Also debian bts supports:

    header: value

    also consider geek syntax in the form of a roundup command line for escapes.

10.1.1 MULTIPLE DATE FORMATS

  • Create dictionary of date formats. Select with us, uk etc country code. E.G:

    local_date_re={
        'us': ( re.compile(r'''
        ((?P<m>\d\d?)/(?P<d>\d\d?)(/(?P<y>\d\d\d\d))?)? # mm/dd/yyyy
        (?P<n>[. ])?                                    # . space
        (((?P<H>\d?\d):(?P<M>\d\d))?(:(?P<S>\d\d))?)?   # hh:mm:ss
        (?P<o>.+)?                                      # offset
    ''', re.VERBOSE), _("format mm/dd/yyyy not found") ),
        'uk': (re.compile(r'''
        ((?P<m>\d\d?)\.(?P<d>\d\d?)(\.(?P<y>\d\d))?)?   # mm.dd.yyyy
        (?P<n>[. ])?                                    # . space
        (((?P<H>\d?\d):(?P<M>\d\d))?(:(?P<S>\d\d))?)?  # hh:mm:ss
        (?P<o>.+)?                                     # offset
    ''', re.VERBOSE), _("format mm/dd/yy not found") )
    }

    then loop using something like:

    if config != None :
         date_match_error = ''
         for country in config.COUNTRY_DATE_FORMATS:
             m=local_date_re[country][0].match(spec)
             if m is not None:
                 break
             date_match_error = date_match_error + local_date_re[country][1]

    where COUNTRY_DATE_FORMATS is in config.py and looks like:

    COUNTRY_DATE_FORMATS = ['us', 'uk' ...]

    The first tried format is always serial format and the last format is roundup standard format. sourceforge feature tracker 2/22/2003

  • Need ability to show formatted view of messages, line wrapped etc. Along with this should be the ability to view a raw view so that explicit formatting, long lines etc can be viewed as it was received.

11 Glossary

assignedto:

an attribute of an issue indicating the person assigned to perform work to resolve the issue. This person is also known as the owner of the issue.

attribute:

a property of a roundup HyperDB item such as title, priority, email address etc.

blocker:

An depended issue that is not resolved and is preventing a depending issue from being worked on. A manual implementation of this can be found in the roundup customization document.

change notification email:

email that is sent out in response to a new message being received by an issue. Depending on the type of email (comment, or reply) it is sent to different lists of people.

comment messages:

these messages are used to interact with other technical people, and are forwarded only to the Technical list. Usually people on the Watcher list can not see these messages. However this can be changed by the roundup admin by modifying the msg_access() function in schema.py.

depended:

The target of the dependson relationship. I.E. a depended issue is one that is listed in another issues dependson property. Also known as a the required (to be closed) issue.

depending:

an issue that has a non empty dependson property.

dependson:

A relationship between issues. If issue A depends on issue B then issue A can not be resolved until issue B is resolved. Issue A is the depending issue and issue B is the depended issues (target of the depends on relationship) issue. If A depends on B, the B is required to be closed by A.

druid:

A form to guide users in properly filling out a request. Druids are customized/provided by the admin and geared toward specific workflows (e.g. new user creation, vlan creation). See Druids for guided issue creation for details on creating a druid.

field:

the entry mechanism for an property in the web interface. Also has the same meaning as property or value of the property.

grouped:

The target of the groups relationship. I.E. a grouped issue is one that is listed in another issues groups property.

groups:

A relationship between issues. If issue A groups issue B, then issue B appears in issue A's groups property. Issue a is the grouping issue and issue B is the grouped issue.

grouping:

an issue that has a non empty groups property.

integer:

a whole number positive or negative. E.G. -1, 7, 30. But not a real number like 2.34 or 1.0.

link:

a property that records a reference to one other object in roundup.

multilink:

a property that records references to other objects in roundup.

number:

A real number or integer positive or negative. E.G. 1.5, 2, 2.0.

owner:

the person assigned to work on an issue. This is stored in the assignedto attribute of the ticket. So the person can also be called the "assigned to" person.

property:

data associated with a roundup HyperDB item such as title, priority, email address etc. Properties have one of 7 types: string, numeric/number, integer, boolean, link, multilink, date, interval. See: https://www.roundup-tracker.org/docs/user_guide.html#entering-values-in-your-tracker for more information about these types.

reply messages:

these messages are used to interact with the requester via the Watcher list and are forwarded to both the the Watcher and Technical lists.

requester:

A user who is requesting an issue to be solved. Usually the same as the issue creator if the requester has access to the tracker via email or web.

roundup administrator:

the person who sets up the sysadmin tracker, and establishes the web interface, email addresses and automatic tasks (cron jobs) required for the tracker to work.

seealso:

a relationship between issues with no defined requirements.

staff:

A person with the Agent user role. This person is expected to resolve jobs in the tracker.

tracker:

An instance of a roundup database, rules for handling issues and associated web and email interfaces.

tracker administrator:

the person who is responsible for adding user to the tracker, establishing the priorities, statuses, edits keywords and handles day to day operation of the tracker. Most of these tasks can be done via the web interface with no other system access.

user:

Anybody who uses the system. This includes: requester: person asking that something be done staff: person solving the requester's problem manager: person managing the staff

12 License

This tracker is released under GPL version 2:

                    GNU GENERAL PUBLIC LICENSE
                       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                          675 Mass Ave, Cambridge, MA 02139, USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

                    GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

                            NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

                     END OF TERMS AND CONDITIONS

        Appendix: How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) 19yy  <name of author>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19yy name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  <signature of Ty Coon>, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

13 Thanks

I have used ideas from many others and implemented some thing with their code.

14 Revisions/Releases

15 Comments here

15.1 Working with queries

FIXME: document editing anon queries, existing queries from index page. Editing and controlling entries in left hand menu.

15.2 Long Features

FIXME: what to do here, some goes to thanks.

Compared to the classic tracker, this tracker has:

  • Well defined relationships between issues including:

    • dependson - shows dependencies and prevents issues from being resolved if they have any unresolved issues that they depend on.

    • grouping (merging) - used to update multiple similar issues as a group.

    • seealso - used to link issues that are related in some way.

  • Two notification (nosy) lists for issues:

    • Watcher list (aka nosy) - This list receives replies to the issue and is intended for non-implementation level conversations with the requester. It is also used to notify the requester of milestone achievements. Email to these people are generated by reply messages.

    • Technical List (aka verynosy) - This list is meant for technical discussion of how to implement solutions, and coordination of implementation as well as detailed implementation notes. Email to these people are generated by reply and comment messages.

  • Three types of messages: replies, comments and data.

    • reply messages - are used to interact with the requester and are sent to both the the Watcher and Technical lists.

    • comment messages - are used to interact with other technical people, and are sent to only the Technical list. They can only be viewed in the web interface by people on the technical list (but this can be changed by your roundup admin).

    • data messages - are not sent to anybody. They are useful for recording data on a ticket where no notification is needed.

  • The agent role has been defined and is used to restrict which users are visible in the assignedto list box, or which users can be assigned to an issue via email. Also there is an auditor (that is not installed by default) that will assign the first person, with the agent role, to respond to an issue to that issue. See unused/autotake.py.

  • Issues can be assigned to queues. Each queue can have its own list of email address for announcing a new unassigned item in the queue.

  • Users assigned an issue by a third party (like a manager or first line support person) are sent email with the initial message and the last three messages to get them to come up to speed as quickly as possible.

  • Issues support tracking the amount of time spent solving the issue. (Not available via email yet)

  • Issue has the extra properties for:

    • scheduling:

      • startdate - date on which work should start

      • leadtime - amount of time the work should take

      • duedate - date on which work needs to be done

      • workingorder - set a numeric order to issue. Useful to determine which issue gets worked on first when you have multiple issues at the same priority. Must be an integer > 0. The system doesn't care if you use 1000 for the first item to be worked, or 1 for the first item. That is up to local policy.

    • summary info:

      • fyi - string used to keep critical info (e.g. server serial numbers, external call ticket numbers) quickly available without having to search through the messages for the issue.

    • billing:

      • billinfo - text property for storing billing information

    • notification:

      • needsreply - for indicating on the index when a new message that needs to be replied to has been received on an issue. There are some times when you just can't monitor email to get change notification. This is a quick and dirty way of being notified via the web interface.

    • automatic actions:

      • actiondate - date on which action will occur

      • actionstatus - the [optional] new status for the issue after the action triggers.

      • actioncomment - the [optional] comment message that will be added to the issue when the action triggers.

    • can change user who opened/requested issue:

      • requestedby - set the user who requested this issue. It has a matching detector that by default will set it to the creator of an issue. Also it adds the requestedby person to the nosy list.

        By default this property will have the same value as the creator property, but this property can be changed unlike the creator. This means it can be set to a different user if you have a help desk that takes calls and enters issues on behalf of another person.

  • In the web interface, each message displayed has a replyto link that will reload the issue with the change note text area filled with a quoted attributed version of the message you are replying to.

  • In the web interface each message that is sent can be carbon copied to arbitrary email addresses.

  • Wherever issue numbers show up, they also display an indication of the status of the issue. This is settable in the status class.

  • The tracker administrator can configure what status transitions are allowed. E.G. you can force new to transition to only open, stalled or hold. Then those statuses can transition to resolved to enforce a particular status path.

  • The tracker administrator can limit setting a status to particular users. (Note is shown in the web interface, but an error is produced when it is set. This is considered a bug.)

  • It comes preloaded with searches for displaying (in a limited way) relations between issues, scheduling showing due dates, showing watcher and technical lists.

  • It has a printable link that makes it easier to print out issues for review.

  • It has an auto refresh mode that automatically refreshes the screen at a user selectable interval. Great for keeping up to date on new and changed issues.

  • All pages have a combined full text search and goto item form to ease navigation and locating particular issues.

  • The user's item page has a fixed format list of non-resolved issues requested by this user as well as a link to the index page of all issues requested by the user to allow interactive sorting and grouping capability.

  • On the index pages, all columns that are links to users are now hyperlinked to the user.

  • The ability to do the functions requested below. Used implementation from K Schutte from the roundup list.

    On Mon, 18 Aug 2003 09:50 pm, K Schutte wrote:
      How should I set up Roundup such that for any new issue
      with topic <foo> I am put on the nosy list?
    
      Does this also work when with an existing issue the topic
      <foo> is added? How can this be arranged such that any user
      (that is, including those who can't edit Python) can specify
      on  which topics they will be added on the nosy list?
  • Publishing an rss newsfeed keeping you up to date on changes in the tracker.

1

https://web.archive.org/web/20081113134259/http://www.markpasc.org/code/rsswriter/

2

https://github.com/kamranahmedse/driver.js