1 Sysadmin tracker for roundup

Author

John P. Rouillard

Date

2022-01-10

2 Using the sysadmin tracker

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

2.2 The Web Interface

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

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

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

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.

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

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.

[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

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

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

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.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

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.

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.

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.

5 Administering the tracker

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

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

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

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

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

NEW_ISSUE_ANNOUNCE_DEFAULT = "sysadmins"

DEFAULT_PRIORITY = 'routine'

COMMENT_TRACKER_EMAIL = 'tracker_comment@%s'%MAIL_DOMAIN

[jumpsearch]
search_by_email = no

[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.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.

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.

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.

15. 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.

16. 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.

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

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:

• log into the tracker as admin pw admin

• create issue with title issue1 and priority high

• create issue with title issue2 and priority low

• create issue with title issue3 and priority routine

• create issue via email by sending:

  From: "rouilj" <rouilj@example.org>
  Content-Type: text/plain
  Subject: test 4a
  To: issue_tracker@example.org
  MIME-Version: 1.0
  Message-Id: <1034901317.14.0.292086518234.issue@example.org>
  Content-Transfer-Encoding: quoted-printable
  
  New issue via email.

  to stdin of:

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

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.

• Add user admin to technical list and send the following email:

  From: "d1" <d1@example.org>
  Content-Type: text/plain
  Subject: [issue4] test 4a
  To: issue_tracker@example.org
  MIME-Version: 1.0
  Message-Id: <1034901317.14.0.292086518234.issue@example.org>
  Content-Transfer-Encoding: quoted-printable
  
  New issue via email.

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

• make issue4 depend on issue1. Change status to resolved issue4. Should result in an error that issue1 must be resolved. Change status of issue4 to stalled.

• goto issue1 resolve it. Then go to issue4.

• issue 4 should be open. Change status to resolved. should work.

• on issue 4, remove issue1 from depends on list. Add issue 1 and 2 to group relation.

• stall issue4. Goto issue1 and issue 2, they should also be stalled.

• add message to issue1. It should open issue1, issue2 and issue4.

• goto issue4, it should be open and have last message at the top of its message list. Goto message 2 it should not have the latest message.

• add message to issue4. It should be in issue1 and issue2.

• edit the queue class. Empty the email address field for support.

• Create a new issue with integration as the queue and a message. no email should be sent out.

• Create a new issue with support as the queue and a message. email should be sent out to sysadmin.

• Send the following email:

  From: "d1" <d1@example.org>
  Content-Type: text/plain
  Subject: test 4a [queue=Support]
  To: issue_tracker@example.org
  MIME-Version: 1.0
  Message-Id: <1034901317.14.0.292086518234.issue@example.org>
  Content-Transfer-Encoding: quoted-printable
  
  New issue via email.

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.

10 Todo

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

• Implement a very nosy keyword field for the user object to add the user object to the verynosy list if the listed keywords are added to the issue's topic. See the implementation of the same for the nosy_keyword in the user object described at Working With Users.

• Add a button/link called create dependson for a message (or issue) that will:

  1. create a new issue entry form with the change note filled with the current message, or empty if invoked at the issue level.

  2. when the issue is created, add the newly created issue to the dependson list of the original issue.

  This is great for splitting tickets into multiple tasks.

• A help desk person can't create a new caller easily. They need to get to the registration page and involve the caller in the creation process. This isn't good. There needs to be a way for a help desk worker using roundup to create a new user similar to the way the admin can do it. Maybe a finer grain permission for the user (say helpdesk) that includes the ability to create a new user. This isn't an issue for me since our "help desk" people are also admins, and most of our people submit tickets by email thus autocreating the user (still without organization/phone etc). As a workaround the Cc field in a message will create the user, but no info like phone number, company etc can be filled in.

• There is a filestatus that is meant to label files with obsolete, current etc. so older version of files can be labeled as obsolete and ignored. This is not currently in the templates.

• Support for setting timelog via the email mechanism. Something like [msg.timelog=2:10] at the end of an email subject line should set the timelog entry for the newly created message.

• The link to turn off auto refresh should not list the time in seconds. It should list it as the select box does, sec, min or hours.

• A configuration setting to allow comments to be visible to all people who can see the issue. Currently the msg_access() function in schema.py for the tracker must be changed to do this.

• Allow setting explicit ACL's to limit user access to issues and comments:

  • In addition to using nosy/verynosy consider explicit view and edit ACL's for issues that would allow access but not participate in the email flows.

  • It should be possible to enable people to see the comments even if they are not on the technical list at the time of viewing. Think about a per issue viewcomments multilink to the users. The viewcomments field will need to be protected by an auditor and limit changes to those who can already see the comments, or to admins.

• An announcement email should be sent when a ticket is re-opened because a previously resolved depended issue is unresolved.

• Users should be able to be assigned to monitor issues (or limited to seeing) issues in particular queues. Maybe add a multiselect called queuewatcher to the user object.

• Emulate the following from RT.

  "Goto ticket" has been replaced with a smart "Search" feature which does a pretty good job of guessing whether you're trying to go to a specific ticket, search for all tickets from a given email address, find all new/open tickets in a given queue or search for tickets whose subjects match a string.

  Current state, the jump to a ticket number works (see: https://wiki.roundup-tracker.org/JumpSearchIssueEntryBox ) but searching for tickets that are in a queue, or limiting search to subject field is missing.

  The feature is documented in the search goto reference.

• Implement other searches on the user detail page including including issues where the user is nosy etc. to get more info about the user.

• Implement crosstab reports via command line (in CSV and table output) and web interface (with CSV download). This should be a standard spreadsheet type display with the vertical column vs the horizontal row. So assignedto vs ticket status will provide the assignedto people down the left hand side of the table and status across the top row. Also if selectable is requested the user can select which statuses they want. Also if groupable is there, the selected items can be grouped into a single column, e.g. working group may be everything except resolved, dead, delete and this will be a valid column in the table. I have a command line program that will do some of this. The report types I have come up with:

  • count of tickets for assignedto vs (selectable, groupable) ticket status.

  • count of non-resolved tickets per assignedto person.

  • count of tickets assignedto vs (selectable, groupable) ticket priority.

  • count of tickets requestedby vs ticket status.

  • count of tickets requestedby vs ticket priority.

  • count of tickets non-resolved assignedto vs timeperiod

  • average time spent to resolve ticket per priority

  • average time to open ticket per priority

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.

• Mark Paschal - rsswriter

14 Revisions/Releases

15 Comments here