Extension Documentation

EMail Raising of Issues
Prev Cron tasks and the Issue Tracker component Next

EMail Raising of Issues

It is possible to use a cron task to fetch emails, from a specific address, and to use the contents to create or update an issue upon the site automatically.

It is recommended that a separate email account is established solely for the purpose of receiving issue emails, be they 'new' or 'replies' to existing issues. By using a separate email account, one can more easily monitor received emails and ensure that messages that have been 'detected' as SPAM are correct and that something important has not be missed. If component logging is enabled then the log will contain details of messages received and various processing statistics. Most hosting suppliers permit a number of different email accounts and they are generally easy to set up and use.

The component needs to be configured with the details of the mail server from which the emails are to be fetched. Once configured the task will make contact with the email server, and read all of the 'UNSEEN' messages present for the connection user.

Each message is then processed. The first step is to inspect the message to determine whether this is a 'new' issue being reported or an 'update' to an already existing issue. This is achieved by checking the received email to see if there are any 'hidden' header tags which are recognised by Issue Tracker.

[Note]Note

All email notifications sent out by Issue Tracker include two specific custom header tags that identify the issue (about which the email is concerned), by its database unique identifier and it issue number. If the sent messages are used to create a reply then these fields can be checked for when a reply is made. Unfortunately a lot of email clients strip out the headers when they reply so that means they are not present for us to check, and hence can not be relied upon.

If the 'hidden' header tags are not present then the message subject (title) is inspected for a specific issue string. Depending upon the strength of the checking specified in the component options, the specific string would be '[Issue: xxxxxxxxxx ]' or '[ xxxxxxxxxx ]' where xxxxxxxxxx represents the issue number. If neither of these pieces of information are present then the message is assumed to represent a new problem report.

[Note]Note

Consideration was given to implementing checks for other information in the email header for a response, but unfortunately different email clients may add "re" "RE" "Re" "Antwort" "AW" "?p" "?p??t?s?" or some other localised "reply" prefix OR SUFFIX in the message subject. It was considered virtually impossible to keep a track on all of the possibilities and would present a continual coding nightmare.

To complicate the problem there is always the situation where people change the subject of the email which would then result in a complex parsing exercise. For this reason no checks are performed to match the Email Subject title other than for the string mentioned above.

The message is also checked, using the currently implements spam checks. i.e. Are there any 'prohibited' words, the number of included web links etc. Optionally Akismet is also supported for checking of Spam.

[Note]Note

A lot of the commercial ticket/issue/problem reporting systems –e.g. GitHub– work based on a customised email address per problem. Unfortunately this is not an option for a Joomla! component. The other technique commonly used is the thread ID in the mail server which again is not an option.

This leaves one with possible hidden email header entries and a reply above line, both of which are implemented in the Issue Tracker email fetch feature.

New issue emails

When the message is determined to be a new 'problem report', some additional checks are made.

The email address of the sender is then analysed. If the email address is not currently known by the system, and we are accepting emails from 'guest' users then optionally a new 'unregistered' user is created in the component.

The message subject is stored as the 'issue summary' for the reported problem.

The contents of the message text are stored in plain (not HTML) format in the description field of the issue.

A confirmation email is sent to the sender and also to the (default) assignee for the issue when the issue has been saved in the database.

Updates for existing issues.

To be a (possible) reply to an existing issue,the header tags and/or the pseudo header tags are present.

Checks are then made to ensure that the 'extracted' issue details from the message subject or header tags, together with the email address of the sender match with the details recorded in the existing issue within the database, IF it exists. If the 'requested' issue does not exists, or is 'CLOSED' or is not identified as being originally identified as by the message sender, the message is rejected.

There are options to control the strength of the email reply detection. 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.

A lot of email clients (e.g. Thunderbird) by default *appends* replies to the original text, and it is not desirable that this information should be added to existing issues, since it will cause unnecessary duplication. For that reason the message should include a 'reply above this line' (the precise text is a configuration option) string. If a user makes a mistake and does not enter text in the correct manner an empty reply may be generated, and in this situation the message should be discarded.

Release 1.6.8 made a few small modifications in the area of update handling. The search for the 'reply above line' was modified such that any string can be specified in between the two 'reply identifiers'. Default '#-#-'. This string searched for is thus build up and looks for something like the following:

'#-#- Any thing you like -#-#'

There is also a new parameter that controls what to do with the email message IF the 'reply above string' is not found in the message. Two options are available:

  • Strict: The 'strict' setting will reject the email message IF the string is not found.

  • Relaxed: The 'relaxed' setting will accept the email message in its entirety and place it in the progress record. This last setting should be used with care, since there is a lot of potential for 'unrequired' information being saved in the database record. The reason is that a number of email clients will 'append' the contents of the current message to the end (or front depending on email client setting) of the outgoing reply message. These 'old' message history texts will be placed in the progress record of the issue, resulting in a lot of potentially unwanted text.

The message contents are appended to the issue progress field, immediately preceded by a line separator and the date and sender Name (extracted from the message) in HTML format.

[Note]Note

The script only fetches 'UNSEEN' messages from the mail server. In the event of an error being encountered upon processing the message, i.e. An issue may be in the state of being updated (edited), in which case the issue could not be updated, then the message would be left upon the mail server, even if it is configured to remove messages after processing.

[Tip]Tip

The act of retrieving the email message from the server will often cause the email server to mark the message as 'SEEN' or 'READ', which means that if the next 'cron script' run tries to retrieve the message it will not be 'fetched'. To reprocess a message it is necessary to enter the email server and mark the desired messages as 'UNSEEN' or 'UNREAD', in which case they will be picked up by the 'cron script' and re-processed upon its next run.

[Caution]Caution

If the option to delete processed emails is set, then all emails that have been successfully processed will be automatically removed from the email server and will be unavailable for re-processing.

Email that has not been processed for what ever reason will remain upon the email server, but not fetched again unless reset (on the mail server).

Prev Up Next
Cron tasks and the Issue Tracker component Home EMail sending of Issue Summary
Go To Top

Joomla! Debug Console

Session

Profile Information

Memory Usage

Database Queries