Extension Documentation

Chapter 3. Configuration
Prev Part I. Macrotone Issue Tracker Next

Chapter 3. Configuration

Table of Contents

Component Options
General Options
Spam Security Options
Issue Option Rules
Message Options
Cron Control Options
List Control Options
Front End Options
Attachment Options
Log Control Options
Advanced Audit Options
Permission Options

This chapter describes the Macrotone Consulting Issue Tracker component options.

Component Options

This section describes the various component options available.

There are a number of options available to configure the component. These are all accessed from the ‘Option’ icon in the top right hand side of most of the Administrator screens. Hovering over the option title will display took tips explaining what the action that the selected option setting performs.

General Options

Figure 3.1. General Option Settings

General Option Settings

Figure 3.2. Issue Defaults

Issue Defaults

The general options specify the delete mode. In order to retain information and build up a knowledge base it may not be desirable to delete, issues, projects or people from the component. For that reason the default is that the delete mode is ‘disabled’. The other options are for a ‘Hard’ or a ‘Soft’ delete. Depending upon what is being deleted will determine the action taken when these options are picked.

A hard delete will remove the record from the database.

  1. If a project is being deleted then not only will the project be deleted, but al the issues associated with the project will also be deleted. In addition if the project is defined as the ‘default project’ for any user, then this will be modified for those users.

  2. If an issue is being deleted then the issue will be deleted from the database.

  3. If a user is hard deleted then all issues associated with the user will also be deleted along with the user.

    [Note]Note

    The Joomla registered entry is not affected.

A soft delete causes a re-assignment of associated record.

a A soft delete is really only relevant with user deletion, where all associated issues for that user will be change to refer to the specified default.

b For projects and issues a soft deleted is treated as a hard delete described above.

The deleted issue user is the user to whom all issues associated with ‘soft deleted’ users will be re-assigned.

The remaining options refer to the default values to be used for projects, project assignee and publishing state.

  • For issues the default publishing state, default project and default assignee will all apply.

  • For a user the default project will be used.

  • For a project the default publishing state will apply.

Not show in the figure above but present in release 1.2.0 are the options to enable front end editing for issue administrators and registered users. Also available is an option to use a site defined WYSIWYG editor installed upon your site such as JCE. (Others are available.)

The default assignee was changed in release 1.2.0. The person defined as the default assignee must be a registered user (otherwise how could they ever update an issue) and they must be a staff member. The drop down list is configured to only show people who meet this criteria. Release 1.2.2 added a default of ‘None’ for the default assignee in the options. When an issue is created and a project allocated, the assignee for the project is determined initially based upon whether the assigned project has an assignee. It the project does not have a configured assignee the 'default assignee' is used instead.

Introduced in release 1.3.0 is a public/private flag. If the option is enabled then when an issue is created on the front end, the raiser has the option of making the issue 'private'. If defined as private the issue is classed as containing information that under no conditions should be made available for display on the front end. Information in these issues should only be visible to the person raising the issue and the support staff. Information that might fall into this category includes passwords etc. If the option is enabled then the back end issue list will show an additional flag indicating private or public, and the additional field will be displayed on the front end create an issue form..

[Important]Important

An issue marked are private cannot be made public by design, not even by the issue administrator, even if the sensitive information is removed from the issue details itself. Private issue are not published by design, and it is not possible to change their state to published.

Release 1.6.8 introduced some additional default settings for the 'progress' record records such that it is now possible to specify the default state (published/unpublished), access level, and privacy (public/private) fields on each individual progress record. Formally the defaults were hard coded and the user had to 'opt' for the settings required from the droop down lists.

Spam Security Options

Figure 3.3. Spam Security Options

Spam Security Options

It is recognised that it is fact of life that there will always be someone who wished to create SPAM comments and the issue tracker if configured to allow to unregistered users to raise issues, it may also fall prey to this type of action. For that reason there is incorporated within the component the ability to filter out such entries.

The first line of defence is to make use of the Captcha facility provided in Joomla 2.5 and above. The component uses the inbuilt Joomla captcha thus automatically uses which ever version of Captcha is configured. This in itself is possibly not sufficient and there is therefore the ability to specify a limit upon the number of embedded links in the issue description an title. Experience indicates that more than 3 links is almost always SPAM. Finally we can check the issue summary and issue description entered for any specific words that we might deem contrary to what is acceptable.

The Site address and the Akismet API key are both required if the site wants to make use of the Akismet integration. An incorrect API key will prevent the saving of the options until the correct key, is entered or if the field is left blank.

[Important]Important

The default value for the link count of 3 is more than suitable for most normal usage. However if the site is making use of scheduled email fetches to collect issues (and updates) via email, then it may well be required to increase this value. Doubling it is often sufficient. This is to allow for the situation where the user has 'replied' to an earlier notification email which will itself contain embedded links, to the raised (or updated) issue and to our website, plus any links incorprated by the email server itself.

Issue Option Rules

Figure 3.4. Issue Option rules

Issue Option rules

The issue rules further define what may or may not be acceptable. We have the ability to prohibit input from any set of URLs, or any of a list of specific email addresses and or any of a list of specific IP addresses.

In this way be have minimised the chances of recording ‘funny’ or otherwise undesirable issues raised by an unregistered user.

Message Options

Figure 3.5. Message Option settings (1)

This section was prior to release 1.6.5 named 'Email Options', now with the possibility to send SMS messages it is renamed 'Message Options'. The Message settings are used by the system to generate email and/or SMS messages. Release 1.2.0 introduced the ability to control emails send to users, assignees and administrators based and to easily configure them separately. Issue administrators are controlled by the settings in If enabled a message is set to all staff marked as ‘Issue Administrators’ in the People table. [See People Display above - People Manager]. The message contents are controlled by the templates provided in the main email type tabs described section Message Tab .

Message Option settings (1)

Figure 3.6. Message Options (2)

Message Options (2)

When an issue is raised on the front end, one of the required details is the users email address. If the user raising the issue is ‘registered’ to Joomla then the email address stored in the ‘People’ table is used as the address. If the issue raiser is a guest then the user is required to enter a valid email address, which is then used to send to the raiser a message providing a link to the issue and the issue number, and is either stored in the progress field of the raised issue, or it configured an entry is created in the it_people table creating what is known as an ‘unregistered user’.

The Front End issue raising form also asks whether the user wishes to be updates when the issue is changed. If the affirmative is given then an email address may or may not be sent depending upon the notifications settings above. For example it is possible to only send the user a closure email and/or update messages.

[Note]Note

If an issue is ‘Closed’ and then updated again, a second email will be send. Every time an issue that is closed, is edited an email message will be generated so care should be taken to ensure that a ‘Closed’ issue is seldom if ever re-edited.

The 'Notification' switch takes priority over all of the following options. If it is set to 'No' then notifications, of any kind, will NOT be send from the component. If set to one of the other settings then the individual options will tend take effect. Whether a specific message is sent to a recipient will then be determined buy the specific settings for the user themselves. i.e. 'Email Notifications' and/or 'SMS Notify'.

[Important]Important

SMS notifications rely upon the presence on the site of the AcySMS component. If this is not installed upon the site then SMS notifications will not be possible independent of any SMS settings defined in the options. The implantation details of SMS messaging is described in the Issue Tracker Design Documentation.

There are some additional in-built rules that are used to prevent the sending of messages in specific circumstances. These are described below:

New Issues:

  • Notify user and assignee if the issue is new except where it is closed immediately.

  • Notify issue administrator unless an issue administrator actually opened the issue.

  • Notify the assignee except if the assignee opened the issue and assigned it to themselves.

  • Notify all issue administrators.

Closed Issues:

  • If an issue administrator is closing the issue do not notify them.

  • If user has requested it notify them of closure.

  • If the assignee is closing the issue then do not notify them.

Updated Issues:

  • Notify all issue administrators, except if an issue administrator updated it.

  • Notify the user if requested.

  • Notify the issue assignee of updates and closure except if the assignee made the change.

[Important]Important

To be able to receive email notifications the user has to have the email notifications flag enabled in the people table. If not enabled emails will not be sent to the individual.

Cron Control Options

Release 1.5 introduced the ability to use Cron based tasks primarily to enable the sending of scheduled emails containing typically summary reports , or overdue reports to staff members, but also to permit the receiving of emails to either raise new issues or update existing issues. If this facility is not required then most of the settings in this section can be ignored.

Figure 3.7. Cron Control options

Cron Control options

The CRON options control the running of scheduled task if invoked from the front end and also provide the default connection details for the scheduled fetching of 'issue' emails from a mail server.

The secret key is used by the front end scheduled cron tasks and has to be provided. It provides security to ensure that the tasks are only run when the parameter is provided on the invoking command line. It is not used by the scheduled PHP CLI tasks, as these cannot be invoked by a user.

The mail server details are required to obtain mail specifically addressed to a specifically named user account which is configured to be used for issues that are emailed in.

Figure 3.8. Cron Control options (2)

Cron Control options (2)

When processing email replies to issues there are options to control the strength of the email reply detection. There are checks to detect whether 'issue tracker bespoke' header entries are present in the email reply and these are used if present. Since a number of email servers strip these out of the reply message, we also perform checks upon the specification of the issue within the mail subject header. Three options are available:

  • Strict: Accepts only the exact format that email notification uses. Which means "anything [Issue: xxxxxxxxxx] anything here". The full text is required, and the issue id has to be the exact length (def 10 chars). In addition the custom header fields have to be present in the reply. Spaces before and after the issue identifier are optional.

  • Balanced: As Strict only the custom header fields may or may not be present. Spaces before and after the issue identifier are optional.

  • Relaxed: Accepts email notification formatted subjects but also [xxxxxxxxxx] in the subject line. Custom header fields may or may not be present. Spaces before and after the issue identifier are optional.

The ability to process email attachments is optional and if enabled used the settings for the number of files and the file sizes from the component Attachments options (see below).

In order to extract replies to Issues from new issues several mechanisms are used. One of these is the use of a 'reply above this line' string in the reply text. The specific string used is specified in the options.

The site base field is usually populated by the component installed and it should not be necessary to change this field.

[Note]Note

The subject of setting up the email fetch routine is not trivial and often involves much trial and error to enable the correct parameters to be supplied. For that reason the following may prove useful.

The Joomla system itself does not understand the receipt of email, so it is necessary to set up a scheduled task (covered in this manual) using something like 'cron' on Unix systems to connect to a mail server and fetch the emails, Basically this is a simple shell script consisting of a few lines. The scheduled tasks either calls a specific web page on the front end (pseudo cron), or better yet calls a PHP CLI script (supplied and installed as standard) which does the mail fetch. Not all web hosts allow the use of PHP CLI binaries. There are examples of both are provided in this manual.

It is often desirable to have a separate specific email account/address on a mail server that is accessed so that only emails concerned with 'Issues' are retrieved. This avoids the complexity of sorting out 'real' issue/problem reports from generic emails from colleagues or other systems.

Once retrieved the email is inspected (by the issue tracker component code) and depending upon specific component settings and the message contents, it is accepted and entered into the database as a 'new' issue, where it does the usual things like assigning people, triggering emails etc. There are also entries made in the Issue Tracker log (accessible from the back end control panel), IF the component logging is turned on, which is recommended especially while you are testing, and probably as standard.

The email fetch also informs the mail server that it has fetched the email so that further attempts do not fetch the self same email over and over again. In the event of an email being fetched and failing to be entered into the system, it is usually possible to access the Mail server to indicate the email message that it is desirable to be fetched 'again' upon in a forthcoming scheduled.

Release 1,6,8 removed the 'reply line' text field so that it is possible to specify any text that one desires, since the code now only searched for the start and end 'Reply line prefix'. The release also introduced a new parameter 'Update handling' which controls how an update email is handled if the 'reply above' line is missing in the retrieved email.

The Issue Tracker log is very useful in assisting the resolution of problems encountered with the setting up and ongoing monitoring of the synchronised email fetch mechanism. The Issue Tracker log is accessed from the back end Control Panel Issue Tracker Log icon. If logging is turned on from the from the component options it should/will display messages that will assist in pinning down connection problems. The most common error is the settings for the Mail server and its connections. i.e. the connect name, password etc. The logging is ideal for resolving that type of error.

The table below lists known settings for Mail providers. It may/will be extended as more information is supplied. The entries are known to work and have been provided by current users. If your mail provider is not listed below, then the information can usually be supplier by the vendor upon request, if it isn't available on their web site already.

Table 3.1. Sample Email setups.

Mail Host

IMAP Port

POP Port

Requires Novalidate

imap.1and1.co.uk

143

110

Y

See the section below about Cron/Scheduled tasks for more details.

List Control Options

Introduced in release 1.2.1 the list control options allow for optional display of fields in the administrator issue list display. The field that is expected to be most displayed is the ‘identifier’ field, and it is expected that for small organisations they may not want to display the ‘Assignee’ field, especially if there is only ever one or perhaps two assignees.

Figure 3.9. List Control options

List Control options

Release 1.3.0 introduced the identification date and the Actual resolution date (close date) to the above list of options field displayed. (Not shown on above figure.)

Front End Options

Introduced in release 1.3.0 the front end options provide parameter values for the front end displays. These defaults are used in the situations where the screen is reached via a link rather than from a menu item. If the front end screen is reached via a menu then the menu parameters take preference.

The front end options are split into several sections and these are displayed in the figures below.

Figure 3.10. Front End options - 1

Front End options - 1

Figure 3.11. Front End options - 2

Front End options - 2

Figure 3.12. Front End options - 3

Front End options - 3

Figure 3.13. Front End options - 4a

Front End options - 4a

Figure 3.14. Front End options - 4b

Front End options - 4b

All of the above screens are within the same tab and it is necessary to scroll down the list to find the appropriate section.

[Note]Note

The options above that relate to the display of the progress and resolution fields for an issue are also used to control whether these fields are included in the Finder (Smart search) index. After all if they are not displayed why index them.

Attachment Options

Release 1.3 introduced the ability to attach 'files' to an issue. This particular tab provides general settings to control the ability to attach files and also the criteria for the attachment.

The field 'maximum files' is not enforced in the initial 1.3.0 release. It is used in the scheduled task processing for email attachment since release 1.5. The back end can add as many file attachments as they desire to an issue at one time. Release 1.6.0 removed the restriction which limited the number of files that could be attached via the front end. Prior to this release the limit was a single file.

Figure 3.15. Attachment Options

Attachment Options

Log Control Options

Release 1.3 also introduced a log facility. In this release it is used solely to provide details of the email notification messages sent as a result of the email configuration parameters.

Figure 3.16. Log Control Options

Log Control Options

The logging option is used extensively by the front end scheduled task for the fetch of emailed issues. Future releases will expand upon the usage of the logging feature. Release 1.6.8 introduced a 'debug logging' option which is useful in tracking down some particularly difficult problems involved with the setting up and handling of email based issues handling. This specific setting is generally best left turned off.

Advanced Audit Options

This tab controls whether advanced auditing is to be used upon the site. Marking the audit as not enabled will restrict some of the fields displayed in the various list and item displays. See the section ion Advanced Audit for more specific details.

Figure 3.17. Advanced Audit Options

Advanced Audit Options

The advance audit feature requires certain database privileges to work, which may not be possible upon your site.

Permission Options

The final option enables the permissions to be specifically set for the user groups. See below for more information upon permitting public raising of issues on the front end.

Figure 3.18. Permissions Options

Permissions Options

Prev Up Next
Chapter 2. Installation Home Chapter 4. Usage
Go To Top

Joomla! Debug Console

Session

Profile Information

Memory Usage

Database Queries