Extension Documentation

Chapter 4. Usage
Prev Part I. Macrotone Issue Tracker Next

Chapter 4. Usage

Table of Contents

Back End Screens
Help Icon
Control Panel
Control Panel Screens
Issues
People
Projects
Attachments
Priorities
Roles
Statuses
Issue Types
Message Templates
Custom Fields and Custom Fields Group Tabs
Support Tab
Documentation Tab
Front End Screens
Create an Issue - Guest User
Registered Users Create an Issue
Front End Issue List Screen
Front End Issue Detail Screen
Front End Issue Edit Screens
Front End Project List.
Other screens
Scheduled Tasks
Pseudo-cron
Front-end access
UNIX System
Command Line Alternative
Securing the script
Cron Basics
Trouble shooting cron
Joomla Warning Messages
Cron tasks and the Issue Tracker component
Auto Close of Issues waiting for user or customer
EMail Raising of Issues
New issue emails
Updates for existing issues.
EMail sending of Issue Summary
EMail sending of overdue notifications

Most of the maintenance work of the component is performed in the back end. Creation of projects, control of users and the maintenance of issues are all performed (currently) in the back end. Creation, and updates of issues can be performed in both the front end and within the back end.

A person defined as an issue administrator also has the full ability in the front end to be able to change and manage issues.

This section displays some of the screens available. From the Joomla back end the Components heading will reveal the Issue Tracker component. Either select the main title or any of the individually selectable sections.

Back End Screens

There are a number of screens available within the Administration part of the site. These may be presented as tabs within the Control Panel, or accessed directory from the Components drop down menu.

This section looks at each of these in turn and explains their structure and usage.

Help Icon

A number of the back end screens have a ‘help’ icon displayed in the top right hand corner of the screen. Clicking on the icon will invoke a small pop up window as shown below.

Clicking on each of the links will redirect the browser to the appropriate pages on the support website.

Figure 4.1. Help Screen

Help Screen

Control Panel

The main Control Panel is illustrated in Figure 4.2, “Control Panel (Joomla 2.5)”. There are a number of separate sections.

  1. The main tabbed headings – Control Panel, Issues, People etc.

  2. The icons separated into three specific types:

    1. Tools – The first three icons provide an alternative entry point to the three tabbed actions. The fourth the ‘Synchronise Users` enables the currently registered Joomla users to be easily brought into the Issue Tracker People table. More details of this are provided later.

    2. Updates – This provides an easy check to show that the latest version of the component is installed.

    3. Sample Data – When installed there is one default project created and one Anonymous user, which can is used to provide system defaults. The existing registered Joomla users are also entered in the People table. These icons enable some ‘sample data’ to be populated into the various issues, people and project tables to demonstrate how the system works. This is explained in more detail later in this document.

  3. The panel which provides the most common type of reports required and provides an immediate overview of the status of the various issues.

    1. Issue Summary

    2. Latest Issues

    3. Overdue Issues

    4. Unassigned Issues

    5. About

    6. Credits

[Important]Important

The sample data icons will not be shown if the database connection user has not been granted the privilege to create database procedures.

Control Panel Screens

Figure 4.2. Control Panel (Joomla 2.5)

Control Panel

The figure below shows the same display as above for Joomla 3.x

Figure 4.3. Control Panel (Joomla 3.x)

Control Panel

The following figure displays the icons more clearly. Clicking on the icon will either initiate the associated action, i.e. Loading sample data; or redirect the user to the named tab display.

Figure 4.4. Control Panel Icons

Control Panel Icons

The following displays shows the sample data installed in the system soon after the system is installed. This illustrates the contents of the various tab (report)displays which would normally be populated by the details of the issues raised upon your site.

Depending upon the specific system upon which the component is running some of the icons may not be present. This reflects the privileges and configuration of the underlying system, more than the component itself.

See section Loading Demonstration Data for any known problems with the loading of sample data.

Figure 4.5. Control Panel Issue Summary Tab.

Control Panel Issue Summary Tab.

The Issue Summary provides an immediate view of the overall status of all of the current projects, along with the total number of issues currently reported and their various statuses. The above figure shows the sample data installed.

[Tip]Tip

The Issue Summary tab display is controlled from an option in the Options Panel.

Figure 4.6. Latest Issues Control Panel Tab.

Latest Issues Control Panel Tab.

This specific report provides details of the ten most recently raised issues.

Figure 4.7. Overdue Issues Control Panel Tab.

Overdue Issues Control Panel Tab.

The most overdue issues are shown in the ‘Overdue Issues’ panel above. They are ordered with the earliest reported issue shown first in the list.

Figure 4.8. Unassigned Issues Control Panel Tab

Unassigned Issues Control Panel Tab

The unassigned issues tab displays what it is expected to display, the issues that have not been assigned to anyone to investigate and work.

Figure 4.9. About Control Panel Tab.

About Control Panel Tab.

The 'About’ panel provides company information. As mentioned the component is provided free, and the user is requested to make a donation if they find it useful upon their site. Users who make a donation will obtain preference if they request any enhancements to the product, over those who choose not to do so.

Support is also currently provided free within the Forum upon the web site. This may change in the future and there is no guarantee for free support..

Clicking on the 'PayPal' icon will open a new browser window on the Paypal site so that users may donate to the support of the component.

Clicking on the 'Changelog' icon within the 'About' panel will cause a popup window to be displayed with details of the changes applied to Issue Tracker for the various releases, with the latest release displayed first.

Figure 4.10. Changelog

Changelog

The 'Credit’ panel provides details of some of the people who have assisted the Issue Tracker project by submitting translations via Transifex. The panel will be as up to date as that of the version of Issue Tracker currently installed. Please refer to the web site for information upon any other translations that may have been submitted after the release.

The panel also credits some of the sources that we have used to enable us to create the component and acknowledges that our work is built upon their previous efforts.

The Credits panel was added in Issue Tracker version 1.5.1. Prior to that release the credits were present upon the 'About' panel. Release 1.6.8 modified this and the details are now retrieved from our system for display in the panel. This means that the information is always as up to date as that upon our server.

Figure 4.11. Credits

Credits

Issues

The back end Issue list display for a Joomla 2.5 installation is illustrated below:

Figure 4.12. Issues Display (Joomla 2.5)

Issues Display (Joomla 2.5)

The same display as shown in a Joomla 3.3 installation is illustrated below:

Figure 4.13. Issues Display (Joomla 3.3)

Issues Display (Joomla 3.3)

The Issue tab is the main display of the current issues recorded with the system. They are shown above ordered by id but clicking on any of the column headings will cause the display to re-order itself. The Issue Summary is shown highlighted and indicates that there is a ‘link’, which if clicked will enable the issue to be edited.

The icons on the top right hand side perform the expected actions enabling the editing, creation, deletion and publishing of issues.

[Caution]Caution

Deleting an issue with attached files will also delete the associated attachments for that issue. There is no confirmation request!

[Note]Note

  • Generally only ‘published issues’ are ever visible in the front end of the site.

  • If a front end registered user is viewing their own raised issues [menu option only], the published flag is ignored.

  • Issue administrators have the ability to view all issues in the front end of the site.

  • The 'public' field is visible depending upon whether 'private' issues are acceptable upon the site.

There are a few configurable options to permit the hiding or showing of other fields such as the identifier, identification date, actual resolution date and the audit fields in the above display. See the list options for more details. The edit screen is shown below.

Figure 4.14. Issue Editor (header)

Issue Editor (header)

Figure 4.15. Issue Editor (part 1)

Issue Editor (part 1)

The edit screen is only one screen but is shown in this document in multiple parts for convenience. The top part illustrated above provides the information to report an issue. It consists, as can be seen of a title (or summary), along with a description of the issue or problem. The Identified by field is the person who has reported the problem, IF they are a registered Joomla user. If not then a configured default is used, often the ‘Anonymous’ user. Any issue raised by a front end user who is not logged in, or who chooses not to will have the configured default (often the ‘Anonymous user’) entered in this field.

The Identification date is the data the issue was first identified, or when first entered into the system, if not specifically provided.

The related project id is the project to which the issue is associated. If not explicitly provided, certain defaults are applied. If the issue is opened by a logged in user and they do not provide the project detail, then the ‘default project associated with that user’ is used. If there is no default for that user, then the ‘Unknown Project’ detail is entered. [If the issue was raised in the front end then the same logic applies with the exception of a issue created from the front end 'Projects List', in which case the project selected will be used.]

Figure 4.16. Issue Editor (part 2)

Issue Editor (part 2)

If there are any associated Custom Fields associated with the specific project (or sub-project) to which this issue is defined as being connected with, then there will be another panel displayed with the custom fields to be completed. This is discussed in more detail in the section Custom Fields on 'Custom Fields' later in this document.

If there are any attachments for the specified issue, an additional panel will be displayed immediately before the 'progress' panel. Absence of the panel indicates that there are no associated attachments.

Attachments are added to issues either via the front end when the issue is created or edited, which is the most common case, or via the back end 'attachments' screen. The illustration below shows a single attachment is associated with the issue being edited.

Figure 4.17. Issue Editor (attachments)

Issue Editor (attachments)

The next part of the issue edit screen contains details of the progress of the issue.

  1. The person is assigned to investigate the issue or problem.

  2. The type of issue relates to whether the issue is a ‘Defect’, ‘Documentation’ etc type.

  3. The status of the issue. i.e. Open, Closed, On-Hold or In-Progress. If a status is not defined by the person raising the issue then the default status as defined in the configuration is used.

  4. The publishing state of the issue. If published then the issue may be made visible in the front end of the site. If a published state is not explicitly set when the issue is opened then a default as specified in the configuration is applied.

  5. The assigned priority of the issue. i.e. Low, High, or Medium. If the priority is not explicitly stated when the issue is raised, then the default value as defined in the configuration is used.

  6. The target resolution date is the date that the issue is expected to be resolved. This field is not currently mandatory although there is some logic built in. If the target resolution date is not specified or if the value greater than that for the associated project, the target resolution date is set to the target date of the associated project. However if the current date (when the issue is saved) is greater than the project target date then wt leave the field alone. The underlying assumption is that it is an issue defect that is being reported.

  7. The details of the progress on the issue are recorded next. If the issue has been raised in the front end and the option to record additional details such as the Joomla version, database version etc (See options below), then these details will have been entered in the progress field.

There are two parts of the progress information. The first is the history of previously entered progress information, which is displayed as a record grid.

Figure 4.18. Progress History Grid

Progress History Grid

The information in the progress history grid is usually considered to be 'unchangeable' as it records the previous actions performed, and as such is part of the 'Knowledge Base'. It is possible for an issue administrator to change these records however, and even delete them, although this very act will destroy the historic information about the issue.

Figure 4.19. Progress History Editor

Progress History Editor

As can be seen in the above, it is possible to change the access criteria and the publishing state of an individual progress record. Not all sites desire or wish the progress history to be displayed publicly upon the front end of the site. With this ability it is possible to be selective as to which progress records may or may not be displayed and also to whom.

The next part of the progress history is the current progress information to be entered for the issue. Upon saving of the issue, this information would henceforth be considered as historic and would be subsequently displayed in the earlier 'progress history' grid.

Figure 4.20. Issues Editor (part 3)

Issues Editor (part 3)

The next part of the editor screen records the resolution of the issue and the audit data recorded by the system.

The main pieces of information are the actual resolution data and the actual resolution itself. The resolution should describe the solution to the problem, preferably in as much detail as possible, so that it may act as source of information should the same problem/issue be reported by another individual.

Figure 4.21. Issues Editor (Part 4)

Issues Editor (Part 4)

The audit information is not editable in the component. It is automatically updated as and when the issue (together with people and project) data is created and updated during its lifetime. It is limited to displaying the creation data and the date of the last update, along with the username of the person involved in the change. This is generally sufficient in most cases for audit purposes.

Figure 4.22. Issues Editor (Part 5)

Issues Editor (Part 5)

Release 1.2.0 introduced the ability to assign specific permissions to individual issues. This was introduced to control front end editing.

[Note]Note

Release 1.4 being based upon Joomla 3.1 introduced the ability to apply 'Tags' to specific projects (and issues). The implementation is the standard use of the supplied Tags API. If running upon Joomla 2.5 then the Tags feature is not available.

People

The people list display for a Joomla 2.5 installation is illustrated below:

Figure 4.23. People Manager *Joomla 2.5)

People Manager (Joomla 2.5)

In a Joomla 3.3 installation the screen would look similar to that shown below:

Figure 4.24. People Manager (Joomla 3.3)

People Manager (Joomla 3.3)

The people manager list display is shown above. Most of the details are extracted from the Joomla user table. This may seem like a duplication of information but is necessary to ensure that records of issues/problems are complete. Users are added to the table automatically (via a plug-in) when they are added to the system. It should be noted that there is no ‘New’ icon in the top right hand corner. The edit is described below, but it is worth mentioning that it is possible to remove users from this table. One of the configurable options is to decide what action to take if a user is deleted, and what should happen to any associated issues. This is described in more detail below, but basically associated issues may be re-assigned or removed. Deleting a user from this table does not remove them from the Joomla users table.

Figure 4.25. People Editor

People Editor

The People editor provides the ability to change the name of the user, their email address and their username. These values are used by the Issue Manager and are effectively independent of the main Joomla registration values. What is not editable is the identifier which will always associate the user entry with the Joomla user registration. It is not expected that these specific values will be changed very often but the ability was requested and is thus provided.

The main uses of the screen are to assign a default project for the user, which is used when they omit the project when a new issue is created.

The other useful attribute is the ‘role’ of the user, which can be used to assist in defining issue priorities.

In release 1.2.0 the ability was added to create and edit non-registered users. i.e. Uses that are known only to the Issue Tracker component. These users may be created automatically (if configured) if the guest user creates an issue in the front end. This then enables the issues to have the correct user identification information entered. If this option is not configured the guest user details are stored in the progress field of the issue record. Users known only to the Issue Tracker have the additional information such as email address, username and name as editable fields.

The registered flag is not shown in the editor view, only the list view. This is because there registration is handled by the standard Joomla user manager and the registered flag is merely an indicator for reference avoiding the need to change screens to obtain the information.

The 'staff' flag was introduced in release 1.3.3 and enabled support staff to be assigned without the full ability of an Issue administrator.

Projects

The projects list display for a Joomla 2.5 installation is illustrated below:

Figure 4.26. Projects Manager (Joomla 2.5)

Projects Manager (Joomla 2.5)

A similar display on a Joomla 3.3. Installation is shown below:

Figure 4.27. Projects Manager (Joomla 3.3)

Projects Manager (Joomla 3.3)

The project manager is the third of the main tabbed items, and is used to display the projects known to the system. Illustrated above is the provided default project ‘Unspecified Project’ and the sample data projects.

The projects display changes slightly in release 1.3.0 (shown above) due to a change in the underlying projects table structure.

Each of the entries may be edited in the usual manner and this is shown in the displays below.

It is expected that one of the first actions of an administrator will be to edit the default project to provide more appropriate details for their specific organisation.

Figure 4.28. Project Editor

Project Editor

The project edit screen is shown above. Each project has a specific name and an associated description.

The published field indicates whether the project details should be visible to the front end. If not visible then it would not be available to a front end user to raise an issue against.

Release 1.5.2 introduced the ability to define a specific assignee to newly raised issue, if not explicitly specified based upon the unique value defined for the project. If not specified or left empty the defined component default assignee is used instead.

The start data, target end date and actual end dates are as one would expect when the project was created, expected to be complete, and when it was actually completed.

[Note]Note

Release 1.3.0 changed the structure of the projects table to become a fully nested table. It introduced a new 'Root' project, which is not displayed since it is filtered out, which is the 'base/root' project for all defined projects. To accommodate this change the 'Undefined Project' has had its identifier changed from a value of 1 to 10. This change should be made as part of the installation and is performed automatically with no changes required by the site administrator.

[Note]Note

Release 1.4 being based upon Joomla 3.1 introduced the ability to apply 'Tags' to specific projects (and issues). The implementation is the standard use of the supplied Tags API.

Attachments

The Attachments display illustrates in one screen all of the attachments that have been placed with raised issues.

Attachments are usually loaded with a specific issue's details from the front end of the site. It is however possible in the Back end to add an attachment to an existing issue, although it is not quite so common. It will also be noted that there is a 'download' button that enables the specific attachment to be downloaded onto the viewers PC for saving and further investigation, or for viewing Image files are not incorporated into any of the descriptive text fields of an issue.

[Caution]Caution

Deleting an issue with attached files will also delete the associated attachments for that issue.

[Important]Please Note:

The attachments feature is not intended to be a fully blown file uploader/downloader. There are a number of existing Joomla extensions for this purpose. Instead it is intended to be a feature for the easy control of files that are regarded as providing additional information for raised issues.

Figure 4.29. Attachments Display

Attachment Display

The attachment editor enables the administrator to add a new attachment to an issue or to add additional information to an existing issue. For this reason the editor screen is slightly different depending upon which task is being performed.

The screen display when a new attachment is added from the back end is shown below. A number of the fields are disabled since they are populated with the details of the field selected for uploading/attaching to the chosen issue.

Figure 4.30. Add New Attachment Screen

Add new attachment Screen

The editing of an attachment screen is very similar to that displayed above for adding a new attachment. In this case the fields are populated with the details of the attached file. It is possible to change the assignment, and change the title and/or description of the attachment.

[Note]Note

In release 1.3.0 the published flag is largely redundant and will be fully implemented in a later version update.

Attachments may be deleted from the list display and this will not impact the associated issue.

The title of the attachment is set to be the 'title' of the associated issue IF the attachment is added from the front end. If added in the back end the title may be changed or set to any desired text.

Release 1.3.1 removed the ability to create a copy of the attachment as this option really served no useful purpose. The 'create new' serves the more useful feature.

Figure 4.31. Edit Attachment Screen

Edit attachment Screen

Priorities

Figure 4.32. Priorities Display

Priorities Display

The Priorities display shows all the defined priorities known to the system. These are installed when the component is installed on the system. They may be edited and additional priorities may be added if desired. It is suggested that they are not deleted as there is some business logic that may/will be impacted if they are deleted or replaced. Attempts to delete a priority that is currently is use will be rejected. It is necessary to assign different priorities for the issues using the ‘priority’ it is desired to delete, before you may delete the desired priority.

[Note]Note

There is a default priority defined in the configuration and that it is not recommended to try and delete the ‘priority’ if it is defined default. The recommended usage is to modify the naming and description as required, possibly to represent a different language retaining the current meaning.

Figure 4.33. Priority Editor

Priority Editor

The Priority Editor is where the description and name are changed.

[Note]Note

The colour associated with a specific 'priority' is defined in the CSS style sheet and is assigned automatically based upon the priority value assigned. i.e. 1 -> 100. There are 20 possible colours defined. See the section later in this guide for details of the colours themselves used as default.

Roles

Figure 4.34. Roles Display

Roles Display

The Roles display is shown above. There are the six displayed roles supplied when the system is installed. Of the supplied roles the ‘CEO’ and ‘Manager’ roles are treated such that people assigned these roles do not accept a default project assignment. The application will reset the person's assigned project to NULL if they are ever assigned a default project. As such they are the only roles that have any ‘special’ business logic.

Roles may be deleted providing they are not currently in use. It is necessary to re-assign users using the desire role that is to be deleted to another defined role, before you may delete the given role.

Figure 4.35. Roles Editor

Roles Editor

The Roles editor, shown above enables the changing of the role name and description.

Statuses

Figure 4.36. Status Display

Status Display

The Status displays illustrated above shows the known statuses supplied with the component.

[Note]Note

When an issue is specifically set to ‘Closed’ (using the unique status identifier of ‘1’) the issue ‘actual resolution date’ is set to the current date. In addition when an issue is created it is assigned the default status of ‘Open’, again using Status Id (4) defined above.

Statuses may be deleted but like other issue criteria, the ‘status’ to be deleted must not be assigned to any given issue. The issues must have that status re-assigned, before you may delete the required status.

Figure 4.37. Status Editor

Status Editor

The status editor is shown above and follows the same logic as that of the Priorities and Role editor described earlier.

Issue Types

Figure 4.38. Issue Types display

Issue Types display

The Types display illustrated above shows the known types supplied with the component. The default issue type is set to 1; i.e. ‘Defect’, unless the configuration option is set to some other value. The Issue type is always set when an issue is opened if not explicitly net by the issue raiser. Issue Types may be deleted however the ‘type’ may not be assigned to any recorded issue otherwise the delete will be rejected. Those issues must have their type changed to another value before you can proceed and delete the ‘type’.

Figure 4.39. Issue Type editor

Issue Type editor

It is possible to change the defined issue types using the editor. The screen above shows the specific entry for a ‘Defect’.

[Note]Note

Issue types may not be deleted if the issue type is associated with any issues. It is necessary to reassign those issues to another type before it is possible to delete the unwanted issue type.

Message Templates

This was formally named Email, but has been renamed to more accurately reflects the information that it is the templates that are used by the Email message or SMS messages sent from the site.

Figure 4.40. Message Templates Listing

Message Templates Listing

Email and SMS generation is controlled via the configuration options, and makes use of the message types as show in the figure above. The ‘email type’ (message_type) name is hard coded into the component, but all other settings are configurable by the administrator. The description field as suggested by its name provides a descriptive explanation of the purpose of the email type.

The message type name is important since it has to be unique and is used within the code to initiate the sending of the specific email type. Additional message types are likely to be introduced in latest releases.

Figure 4.41. Message Template Edit (1)

Message Template Edit (1)

The figure above illustrates the top of the ‘message template edit’ screen. The subject field reflects message subject field that is presented in the generated messages. Of more importance is the actual body of the message which is shown in the figure below. The body makes use of HTML codes, as the generated message is in HTML format. Consequently it is possible to make the text as attractive and detailed as is required.

The details of the issue are inserted into the message body by the use of ‘tags’. These tags are substituted into the message body prior to sending.

Figure 4.42. Message Template Edit (2)

Message Template Edit (2)

Tags are entered by using the words identified in the Message Template Tags table below surrounded by braces. The tags must be entered in lowercase letters otherwise they will not be recognised. Tags can be used in the subject field or in the body of the email. There is no limit to the number of tags that can be used and a tag may be used more than once, although this is often not required.

Despite the current name, this also includes the templates used for SMS notifications. The SMS templates are much shorter due to the restrictions usually due to the limitations imposed by the SMS providers. A message size of 160 characters is common for a lot of the SMS message providers. A component parameter permits a size limit to be specified (default 160), beyond which the message is truncated.

[Note]Note

An SMS message is built up by prefixing the message subject in front of the message body, so there is nothing to be gained by specifying the same 'tag' in both. The reasoning is that unlike with an email message there is no specific 'subject' for a SMS message, so it becomes part of the message itself.

One change that might be made by a site administrator is to add the Assignee details to the administrator message upon the opening of an issue. This has not been included as a default due to prior expressed preferences.

[Note]Note

It is not expected that the progress tag will be used in the email subject header.

It is also extremely unlikely that a progress tag would be included in a SMS message body either, since this is one easy way to exceed the SMS message length limitation. When a SMS message exceeds the specified length it is truncated and a message inserted in the component log, if logging is enabled.

[Important]Important

It is expected that some sites will wish to change the text of the messages into their own language. This is perfectly acceptable, only DO NOT change the message type since this would result in the message template not being found and hence no message of that type would be sent.

Custom Fields and Custom Fields Group Tabs

This is discussed and covered in more details in the separate section Custom Fields later in this document., and also in more detail in the Issue Tracker Customisation Guide.

Support Tab

Figure 4.43. Support Tab Control Panel

Support Tab Control Panel

The ‘Support’ tab provides details of how additional information and/or assistance may be obtained on the product. As can be seen Macrotone provide a Frequently Asked Question (FAQ) on the company website, and additionally provide a Forum where users may raise questions.

There is also the ability on the company web site to raise an Issue, using this actual component itself.

Finally there is the ability to send an email which will be answered as and when circumstances permit. Preference is usually given to forum entries.

Documentation Tab

Figure 4.44. Documentation Tab Control Panel

Documentation Tab Control Panel

There is some basic information about the component provided in the ‘Documentation’ tab, but the user is referred to the Macrotone site for the latest details since the installation of the product upon the user's website.

Prev Up Next
Chapter 3. Configuration Home Front End Screens
Go To Top

Joomla! Debug Console

Session

Profile Information

Memory Usage

Database Queries