Difference between revisions of "Helpdesk"

From Contao Community Documentation

m (wiki syntax)
m
 
(32 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{stub}}
 
 
[[de:Helpdesk]]
 
[[de:Helpdesk]]
 +
[[Category:Extensions]]
 
= Forum and Helpdesk =
 
= Forum and Helpdesk =
 
{{Note|Parts of this documentation were created by Peter Koch / IBK Software AG. Peter Koch has licensed this content for use on contoawiki.org. Content in this page must not be copied, reproduced, republished, uploaded, posted, transmitted, distributed, or used for the creation of derivative works without IBK's prior written consent.}}
 
{{Note|Parts of this documentation were created by Peter Koch / IBK Software AG. Peter Koch has licensed this content for use on contoawiki.org. Content in this page must not be copied, reproduced, republished, uploaded, posted, transmitted, distributed, or used for the creation of derivative works without IBK's prior written consent.}}
{{Hint|http://web.archive.org/web/20101121033235/http://contifex.com/wiki/extensions:helpdesk}}
+
{{Hint|Copied from http://web.archive.org/web/20101121033235/http://contifex.com/wiki/extensions:helpdesk}}
{{Note|feel free to bring the content from the page above to our contaowiki!}}  
+
  
 
== Features ==
 
== Features ==
 
[[File:Extensions-helpdesk-Hd130.png]]
 
[[File:Extensions-helpdesk-Hd130.png]]
  * Native TYPOlight application; fully integrated into TYPOlight user/member system.
+
* Native Contao application; fully integrated into Contao user/member system.
  * Can be used as forum, as helpdesk ticketing system, or both at same time.
+
* Can be used as forum, as helpdesk ticketing system, or both at same time.
  * Both, frontend members and backend users, can be members/clients or moderators/supporters.
+
* Both, frontend members and backend users, can be members/clients or moderators/supporters.
  * Multiple frontend modules with selected categories are possible; to be displayed on one or several pages, or embedded within articles.
+
* Multiple frontend modules with selected categories are possible; to be displayed on one or several pages, or embedded within articles.
  * Backend modules for configuration and forum participation.
+
* Backend modules for configuration and forum participation.
  * Comprehensive and fast BBCode engine including tables, lists, several box types, syntax highlighting and more.
+
* Comprehensive and fast BBCode engine including tables, lists, several box types, syntax highlighting and more.
  * Popup windows for BBCode help and editor preview.
+
* Popup windows for BBCode help and editor preview.
  * Email notification to subscribing users.
+
* Email notification to subscribing users.
  * Email import to create new topics/tickets, as well as to reply to notifications.
+
* Email import to create new topics/tickets, as well as to reply to notifications.
  * Fully customizable layout and appearence by templates and themes.
+
* Fully customizable layout and appearence by templates and themes.
  * Powerful search engine.
+
* Powerful search engine.
  * RSS feeds for any selection of categories.
+
* RSS feeds for any selection of categories.
  * Convenient moderator functions including cut/paste operations to move messages and topics
+
* Convenient moderator functions including cut/paste operations to move messages and topics
 
+
  
 
== Abstract ==
 
== Abstract ==
  
TYPOlight Forum/Helpdesk is a message board (forum) application designed to be as well used as a helpdesk ticketing system, for example to provide formal and informal support to customers or clients. The terminology and functions of the forum categories is slightly different than the support ticketing categories, but when you know the mapping you will immediately be familiar with the application:
+
Contao Forum/Helpdesk is a message board (forum) application designed to be as well used as a helpdesk ticketing system, for example to provide formal and informal support to customers or clients. The terminology and functions of the forum categories is slightly different than the support ticketing categories, but when you know the mapping you will immediately be familiar with the application:
  
 
{| border="0" cellspacing="1" cellpadding="2"
 
{| border="0" cellspacing="1" cellpadding="2"
Line 44: Line 42:
  
  
  * [[File:Extensions-helpdesk-Category416.png]] '''Public Forum''': Everybody can read the forum, even non-logged in users. Only authorized members can however open topics or reply.
+
*[[File:Extensions-helpdesk-Category416.png]] '''Public Forum''': Everybody can read the forum, even non-logged in users. Only authorized members can however open topics or reply.
 
+
*[[File:Extensions-helpdesk-Category316.png]] '''Restricted Forum''': The forum is visible only for authorized members.
  * [[File:Extensions-helpdesk-Category316.png]] '''Restricted Forum''': The forum is visible only for authorized members.
+
*[[File:Extensions-helpdesk-Category216.png]] '''Public Support''': Everybody can see all tickets, even non-logged in users. Only authorized clients can however open tickets or reply.
 
+
*[[File:Extensions-helpdesk-Category116.png]] '''Shared Support''': All authorized clients can see and reply each others tickets, however only the owner has priviledge to close or delete his tickets. Create such a category for example for each company with a SLA((Service level agreement)) where multiple staff members shall have access to the tickets.
  * [[File:Extensions-helpdesk-Category216.png]] '''Public Support''': Everybody can see all tickets, even non-logged in users. Only authorized clients can however open tickets or reply.
+
*[[File:Extensions-helpdesk-Category016.png]] '''Private Support''': Only the ticket owner can see his tickets, but nobody else (admins and supporters authorized for the category can of course also see and reply to the tickets). Used for example for formal support of individuals.
 
+
  * [[File:Extensions-helpdesk-Category116.png]] '''Shared Support''': All authorized clients can see and reply each others tickets, however only the owner has priviledge to close or delete his tickets. Create such a category for example for each company with a SLA((Service level agreement)) where multiple staff members shall have access to the tickets.
+
 
+
  * [[File:Extensions-helpdesk-Category016.png]] '''Private Support''': Only the ticket owner can see his tickets, but nobody else (admins and supporters authorized for the category can of course also see and reply to the tickets). Used for example for formal support of individuals.
+
  
 
=== Topic vs. ticket status ===
 
=== Topic vs. ticket status ===
Line 58: Line 52:
 
==== Topic status ====
 
==== Topic status ====
  
  * {{extensions:helpdesk:ticket0116.png}}**Pinned up**: Open topic that is listed on the top.  
+
*[[File:Extensions-helpdesk-Ticket0116.png]] '''Pinned up:''' Open topic that is listed on the top.  
  * {{extensions:helpdesk:ticket1116.png}}**Normal**: A normal open topic.   
+
*[[File:Extensions-helpdesk-Ticket1116.png]] '''Normal:''' A normal open topic.   
  * {{extensions:helpdesk:ticket2116.png}}**Closed**: No further edits or replies are possible, listed at the end.  
+
*[[File:Extensions-helpdesk-Ticket2116.png]] '''Closed:''' No further edits or replies are possible, listed at the end.  
  
 
==== Ticket status ====
 
==== Ticket status ====
  
  * {{extensions:helpdesk:ticket0016.png}}**Unanswered**: The ticked is open and the latest post is from a client. Listed on the top.  
+
*[[File:Extensions-helpdesk-Ticket0016.png]] '''Unanswered:''' The ticked is open and the latest post is from a client. Listed on the top.  
  * {{extensions:helpdesk:ticket1016.png}}**Answered**: The ticket is open and the latest post is from a supporter.  
+
*[[File:Extensions-helpdesk-Ticket1016.png]] '''Answered:''' The ticket is open and the latest post is from a supporter.  
  * {{extensions:helpdesk:ticket2016.png}}**Closed**: Issue solved. No further edits or replies are possible, the owner may reopen it however in case. Listed at the end.   
+
*[[File:Extensions-helpdesk-Ticket2016.png]] '''Closed:''' Issue solved. No further edits or replies are possible, the owner may reopen it however in case. Listed at the end.   
  
 
=== Members and Clients ===
 
=== Members and Clients ===
Line 74: Line 68:
 
=== Admin, Moderators and Supporters ===
 
=== Admin, Moderators and Supporters ===
  
Moderators and supporters are either TYPOlight backend users or frontend members, and belong to a user group authorized as moderator/supporter for the respective category. They have special rights to see unpublished, to pinup, edit, unpublish or delete any topic, ticket or message.
+
Moderators and supporters are either Contao backend users or frontend members, and belong to a user group authorized as moderator/supporter for the respective category. They have special rights to see unpublished, to pinup, edit, unpublish or delete any topic, ticket or message.
 +
 
 +
Contao admins are special backend users and appear as moderator or supporter, he/she is automaticly authorized for all categories. Additionally the admins have authorization to administrative operations, e.g. create or delete categories or change category settings. Also admins are the only ones who can see unpublished categories.
  
TYPOlight admins are special backend users and appear as moderator or supporter, he/she is automaticly authorized for all categories. Additionally the admins have authorization to administrative operations, e.g. create or delete categories or change category settings. Also admins are the only ones who can see unpublished categories.
 
 
 
=== Deletion levels ===
 
=== Deletion levels ===
  
 
Tickets and messages are not permanently deleted, but only unpublished from frontend when a ticket owner or member/client "deletes" them. They are still available for moderators and supporters however, mainly to serve as a knowledge resource. Tickets and messages can be permanently deleted only by admins, moderators and supporters.
 
Tickets and messages are not permanently deleted, but only unpublished from frontend when a ticket owner or member/client "deletes" them. They are still available for moderators and supporters however, mainly to serve as a knowledge resource. Tickets and messages can be permanently deleted only by admins, moderators and supporters.
 
  
 
== Installation and Setup ==
 
== Installation and Setup ==
Line 88: Line 81:
  
 
*PHP from version 5.2.0
 
*PHP from version 5.2.0
*Other requirements like [[http://www.contao.org/system-requirements.html|TYPOlight]]
+
*Other requirements like [http://www.contao.org/system-requirements.html]
  
 
=== Manual Installation ===
 
=== Manual Installation ===
  
*Install these required extensions in advance: [[extensions:avatar]], [[extensions:cron]], [[http://www.typolight.org/extension-list/view/geshi.en.html|geshi]]
+
*Install these required extensions in advance: [[extensions:avatar]], [[extensions:cron]], [http://www.contao.org/extension-list/view/geshi.en.html]
*Download the install package from [[http://www.typolight.org/extension-list/view/helpdesk.en.html|here]].
+
*Download the install package from [http://www.contao.org/extension-list/view/helpdesk.en.html].
*Unzip the content of TL_ROOT to the TYPOlight base directory on your webserver.
+
*Unzip the content of TL_ROOT to the Contao base directory on your webserver.
 
*Unzip the content of TL_FILES to the tl_files directory on your webserver.
 
*Unzip the content of TL_FILES to the tl_files directory on your webserver.
*Point your browser to <nowiki>http://www.yourdomain.com/typolight/install.php</nowiki>
+
*Point your browser to <nowiki>http://www.yourdomain.com/contao/install.php</nowiki>
 
*Enter the installation password and click '''Login'''
 
*Enter the installation password and click '''Login'''
 
*Scroll down to '''Update database tables''' and click on '''Update database'''
 
*Scroll down to '''Update database tables''' and click on '''Update database'''
Line 104: Line 97:
 
The page where the forum/helpdesk is located should have caching disabled, e.g:
 
The page where the forum/helpdesk is located should have caching disabled, e.g:
  
{{ :extensions:helpdesk:hd200.png |Cache Settings}}
+
[[File:Extensions-helpdesk-Hd200.png |Cache Settings]]
  
 
=== Page layout adjustment ===
 
=== Page layout adjustment ===
Line 130: Line 123:
 
=== Backend themes ===
 
=== Backend themes ===
  
To create the theme //mysite// you would first of cause create a new TYPOlight backend theme folder /system/themes/mysite and activate it in in the //Settings//.  
+
To create the theme ''mysite'' you would first of cause create a new Contao backend theme folder /system/themes/mysite and activate it in in the ''Settings''.  
  
Then likewise you would create a folder system/modules/helpdesk/themes/mysite, copy the CSS files from the adjaccent //default// folder and make your adjustments to them. Please note that because of the automatic fallback it is //not// necessary to copy all the images from the //default// theme. In case you want your own icons, just create a subfolder //images// and put them in there; any icons not found there will be taken from the //default// theme.
+
Then likewise you would create a folder system/modules/helpdesk/themes/mysite, copy the CSS files from the adjaccent ''default'' folder and make your adjustments to them. Please note that because of the automatic fallback it is '''not''' necessary to copy all the images from the ''default'' theme. In case you want your own icons, just create a subfolder ''images'' and put them in there; any icons not found there will be taken from the ''default'' theme.
  
 
=== Frontend themes ===
 
=== Frontend themes ===
  
Copy the CSS files from system/modules/helpdesk/themes/default to your custom frontend theme folder and make the desired adjustments. Don't forget to adjust the //Page layout// as explained before to use your custom stylesheet instead of the default one.
+
Copy the CSS files from system/modules/helpdesk/themes/default to your custom frontend theme folder and make the desired adjustments. Don't forget to adjust the ''Page layout'' as explained before to use your custom stylesheet instead of the default one.
  
You may want to replace some or all of the default forum/helpdesk icons too. Just put your custom icons into an //images// folder below your custom theme. Then enter the path of your images folder in the helpdesk settings. Again there is a fallback built in, so any icon not found in your custom images folder will be taken from the //default// backend theme.
+
You may want to replace some or all of the default forum/helpdesk icons too. Just put your custom icons into an ''images'' folder below your custom theme. Then enter the path of your images folder in the helpdesk settings. Again there is a fallback built in, so any icon not found in your custom images folder will be taken from the ''default'' backend theme.
  
Instead of PNG you may use GIF icons. In case both, a GIF //and// a PNG icon is found, the PNG has precedence.
+
Instead of PNG you may use GIF icons. In case both, a GIF ''and'' a PNG icon is found, the PNG has precedence.
  
 
=== Templates ===
 
=== Templates ===
Line 156: Line 149:
 
You may want to give your frontend members the option to subscribe themself for email noification with the ''Personal data'' module. This will work right out of the box when you are using the template ''member_default''.
 
You may want to give your frontend members the option to subscribe themself for email noification with the ''Personal data'' module. This will work right out of the box when you are using the template ''member_default''.
  
However when using the template ''member_grouped' you won't see the Forum/Helpdesk settings with the TYPOlight releases before 2.5.0. There is a workaround to use the grouped member display right now, which requires a small hack:
+
However when using the template ''member_grouped'' you won't see the Forum/Helpdesk settings with the TYPOlight releases before 2.5.0. There is a workaround to use the grouped member display right now, which requires a small hack:
  
 
Edit the file /system/modules/frontend/ModulePersonalData.php and find this code:
 
Edit the file /system/modules/frontend/ModulePersonalData.php and find this code:
Line 198: Line 191:
  
 
*Make settings in each category that you want feeds for
 
*Make settings in each category that you want feeds for
*Make global settings in the TYPOlight settings
+
*Make global settings in the Contao settings
 
*Add a rewrite rule to your .htaccess file
 
*Add a rewrite rule to your .htaccess file
 
*Optional: Add a link to the page header in case you want to display a feed icon in the browsers address field
 
*Optional: Add a link to the page header in case you want to display a feed icon in the browsers address field
Line 206: Line 199:
 
In the category settings you need to enter the url of the page holding this category, plus check that RSS feeds are enabled. Repeat this for all categories where you want to have RSS feeds for:
 
In the category settings you need to enter the url of the page holding this category, plus check that RSS feeds are enabled. Repeat this for all categories where you want to have RSS feeds for:
  
{{extensions:helpdesk:hd100.jpg|Category Settings}}
+
[[File:Extensions-helpdesk-Hd100.jpg|Category Settings]]
  
=== TYPOlight settings ===
+
=== Contao settings ===
  
In the TYPOlight settings enable the forum/helpdesk feeds, and then make settings for the maximum number of messages to display, the base name of the xml file (same as in the .htaccess below), the title and description of the feed. Please note that this title and description only comes into play for feeds of multiple categories, for single category feeds the title and description of the category is used:
+
In the Contao settings enable the forum/helpdesk feeds, and then make settings for the maximum number of messages to display, the base name of the xml file (same as in the .htaccess below), the title and description of the feed. Please note that this title and description only comes into play for feeds of multiple categories, for single category feeds the title and description of the category is used:
  
{{extensions:helpdesk:hd101.jpg|TYPOlight Settings}}
+
[[File:Extensions-helpdesk-Hd101.jpg|Contao Settings]]
  
 
=== .htaccess Modification ===
 
=== .htaccess Modification ===
  
Add a rewrite rule such as below to your .htaccess file. Replace //helpdesk// by the term you defined as base name in the TYPOlight settings:
+
Add a rewrite rule such as below to your .htaccess file. Replace ''helpdesk'' by the term you defined as base name in the Contao settings:
  
<code>RewriteRule ^helpdesk([0-9,]+).xml$ system/modules/helpdesk/HelpdeskFeed.php?id=$1 [L]</code>
+
<source lang="php">>RewriteRule ^helpdesk([0-9,]+).xml$ system/modules/helpdesk/HelpdeskFeed.php?id=$1 [L]</source>
  
 
A typical complete .htaccess for TYPOlight 2.6.0 might be:
 
A typical complete .htaccess for TYPOlight 2.6.0 might be:
  
<code>
+
<source lang="php">
 
# Enable mod_rewrite
 
# Enable mod_rewrite
 
RewriteEngine On
 
RewriteEngine On
Line 241: Line 234:
  
 
# Dynamic RSS feeds for forum/helpdesk  
 
# Dynamic RSS feeds for forum/helpdesk  
RewriteRule ^helpdesk([0-9,]+).xml$ system/modules/helpdesk/HelpdeskFeed.php?id=$1 [L]</code>
+
RewriteRule ^helpdesk([0-9,]+).xml$ system/modules/helpdesk/HelpdeskFeed.php?id=$1 [L]</source>
  
 
=== Add RSS icon link to page layout ===
 
=== Add RSS icon link to page layout ===
  
This is optional but very convenient for your users. In case you not yet have a distinct page layout for the forum/helpdesk, make a copy of the default page layout. Edit the layout and enter the following link to the //Additional head tags// input:
+
This is optional but very convenient for your users. In case you not yet have a distinct page layout for the forum/helpdesk, make a copy of the default page layout. Edit the layout and enter the following link to the ''Additional head tags input:
  
<code><link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.example.com/helpdesk0.xml" /></code>
+
<source lang="php"><link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.example.com/helpdesk0.xml" /></source>
  
 
Replace %%www.example.com%% by your site's url. The 0 tells to provide a feed over all categories the user has  read access to. If you want to make a feed over the categories 4, 5 and 7 instead, the link would be helpdesk4,5,7.xml
 
Replace %%www.example.com%% by your site's url. The 0 tells to provide a feed over all categories the user has  read access to. If you want to make a feed over the categories 4, 5 and 7 instead, the link would be helpdesk4,5,7.xml
 
 
 
 
  
 
=== Email Import and Notification ===
 
=== Email Import and Notification ===
Line 261: Line 250:
 
To send out notifications and import email a batch program must run on a regular base. You need to install the [[extensions:cron|cron utility]] for this purpose. Below you find suggested settings for the two Forum/Helpdesk jobs. Use a time schedule that matches your needs; the samples below will execute once every minute.
 
To send out notifications and import email a batch program must run on a regular base. You need to install the [[extensions:cron|cron utility]] for this purpose. Below you find suggested settings for the two Forum/Helpdesk jobs. Use a time schedule that matches your needs; the samples below will execute once every minute.
  
{{extensions:helpdesk:hd024.jpg|CRON Scheduler}}
+
[[File:Extensions-helpdesk-Hd024.jpg|CRON Scheduler]]<br />
{{extensions:helpdesk:hd025.jpg|Import Job Settings}}
+
 
{{extensions:helpdesk:hd026.jpg|Notification Job Settings}}
+
[[File:Extensions-helpdesk-Hd025.jpg|Import Job Settings]]<br />
 +
 
 +
[[File:Extensions-helpdesk-Hd026.jpg|Notification Job Settings]]
  
 
==== Troubleshooting E-Mail Issues ====
 
==== Troubleshooting E-Mail Issues ====
Line 269: Line 260:
 
*Check if your servers are properly configured to send out mails by creating a test-newsletter and sending it to one of your mail accounts. Send it to another server than the one used for sending out the mail to make sure the mail is not getting caught in some spamfilters or lost in any black hole.
 
*Check if your servers are properly configured to send out mails by creating a test-newsletter and sending it to one of your mail accounts. Send it to another server than the one used for sending out the mail to make sure the mail is not getting caught in some spamfilters or lost in any black hole.
 
*Using PHP Mail may work on well configured servers (which is not selve-evident these days, cheepo hosters are greeting). Use SMTP in case, that will work 100%.
 
*Using PHP Mail may work on well configured servers (which is not selve-evident these days, cheepo hosters are greeting). Use SMTP in case, that will work 100%.
 
 
*A common mistake is to use a different domain in the notification sender address than in the mail account in the system settings. For example when your SMTP account in the system settings is <nowiki>admin@example.com</nowiki>, a notification sender address such as <nowiki>forum@banana.net</nowiki> is likely to fail because that would be "relaying" which is forbidden in well configured mail servers. Of cause there are exceptions from this rule, for example when the mail server is configured to handle both of those domains. Leave the notification sender address empty until notification works in case.
 
*A common mistake is to use a different domain in the notification sender address than in the mail account in the system settings. For example when your SMTP account in the system settings is <nowiki>admin@example.com</nowiki>, a notification sender address such as <nowiki>forum@banana.net</nowiki> is likely to fail because that would be "relaying" which is forbidden in well configured mail servers. Of cause there are exceptions from this rule, for example when the mail server is configured to handle both of those domains. Leave the notification sender address empty until notification works in case.
 
*Switch the helpdesk logging to <nowiki>"debug"</nowiki> in the Contao system settings. You will find the log files at <nowiki>/system/logs/Helpdesk*.log</nowiki>. In case no log file gets created during the batch run, your directory permissions of /system/logs does not allow write access for the web server. In that case you can manually create the two files /system/logs/HelpdeskImport.log and /system/logs/HelpdeskNotify.log and give them read/write permissions for the web server (for example as chmod of 666).
 
*Switch the helpdesk logging to <nowiki>"debug"</nowiki> in the Contao system settings. You will find the log files at <nowiki>/system/logs/Helpdesk*.log</nowiki>. In case no log file gets created during the batch run, your directory permissions of /system/logs does not allow write access for the web server. In that case you can manually create the two files /system/logs/HelpdeskImport.log and /system/logs/HelpdeskNotify.log and give them read/write permissions for the web server (for example as chmod of 666).
Line 279: Line 269:
 
=== Manual upgrade from a previous version ===
 
=== Manual upgrade from a previous version ===
  
**It is recommended to make backups of your files and your database before starting any upgrade.**
+
{{Caution|It is recommended to make backups of your files and your database before starting any upgrade.}}
  
You can upgrade directly from any previous release, it is //not// necessary to install every version that was released between your old and new version of the application.
+
You can upgrade directly from any previous release, it is '''not''' necessary to install every version that was released between your old and new version of the application.
  
 
It is optional to delete the files of the old version before installing a new release; you can choose to just overwrite the old files. However there might be obsolete files which will stay in your installation that way. So for a clean update I recommend to manually delete these files and folders in advance:
 
It is optional to delete the files of the old version before installing a new release; you can choose to just overwrite the old files. However there might be obsolete files which will stay in your installation that way. So for a clean update I recommend to manually delete these files and folders in advance:
 
   
 
   
  * system/drivers/DC_HelpdeskTable.php
+
*system/drivers/DC_HelpdeskTable.php
  * system/modules/helpdesk
+
*system/modules/helpdesk
  
<note warning>Do **NOT** delete the mysql tables and settings of the helpdesk application after removing the old files, neither with phpmyadmin nor by using the TYPOlight install tool. Otherwise you will loose all your data and settings.</note>
+
{{Caution|Do '''NOT''' delete the mysql tables and settings of the helpdesk application after removing the old files, neither with phpmyadmin nor by using the Contao install tool. Otherwise you will loose all your data and settings.}}
  
 
Next the procedure is basicly the same as with a new installation from scratch:
 
Next the procedure is basicly the same as with a new installation from scratch:
  
  * Download the install package.
+
*Download the install package.
  * Unzip/upload to your TYPOlight base directory on your webserver.
+
*Unzip/upload to your Contao base directory on your webserver.
  * Point your browser to <nowiki>http://www.yourdomain.com/typolight/install.php</nowiki>  
+
*Point your browser to <nowiki>http://www.yourdomain.com/typolight/install.php</nowiki>  
  * Enter the installation password and click //Login//
+
*Enter the installation password and click ''Login''
  * Scroll down to //Update database tables//
+
*Scroll down to ''Update database tables''
  * If any drops of obsolete table columns are due, they are by default unchecked. It is safe to check them now in order to have clean database.  
+
*If any drops of obsolete table columns are due, they are by default unchecked. It is safe to check them now in order to have clean database.  
  * Click on //Update database// to have the necessary database updates applied.
+
*Click on ''Update database'' to have the necessary database updates applied.
  
<note>**After upgrading, you should read the change log to see what has changed and might need your attention.**</note>
+
{{note|After upgrading, you should read the change log to see what has changed and might need your attention.}}
  
 
=== Optimizing full text search ===
 
=== Optimizing full text search ===
Line 306: Line 296:
 
Full text search of mysql will by default not find any words shorter than 4 characters, or in the stopword list.  
 
Full text search of mysql will by default not find any words shorter than 4 characters, or in the stopword list.  
  
To improve search I recommend to lower the minimum word length to 2, or even down to 1. In case your site is not english only, you might also want to disable the default stopword list (or apply [[http://members.unine.ch/jacques.savoy/clef/index.html|a customized one in your language]]).
+
To improve search I recommend to lower the minimum word length to 2, or even down to 1. In case your site is not english only, you might also want to disable the default stopword list (or apply [[http://members.unine.ch/jacques.savoy/clef/index.html]]).
  
**Brief procedure:**
+
'''Brief procedure:''
 +
* Edit the mysql configuration file
 +
* Restart the mysql server
 +
* Drop the fulltext indexes
 +
* Recreate the fulltext indexes
  
  * Edit the mysql configuration file
 
  * Restart the mysql server
 
  * Drop the fulltext indexes
 
  * Recreate the fulltext indexes
 
  
 
+
'''More detailed description (debian example):'''
**More detailed description (debian example):**
+
  
 
Edit /etc/mysql/my.cnf\\
 
Edit /etc/mysql/my.cnf\\
Within the section **[mysqld]** edit or add the following lines:
+
Within the section <nowiki>**[mysqld]**</nowiki> edit or add the following lines:
  
     <code>#
+
     <source lang="php">#
 
     # Fulltext config
 
     # Fulltext config
 
     #
 
     #
 
     ft_min_word_len = 2
 
     ft_min_word_len = 2
     ft_stopword_file = ""</code>
+
     ft_stopword_file = ""</source>
  
 
Restart mysql:
 
Restart mysql:
Line 333: Line 322:
 
Check system vars in phpMyAdmin to make sure it worked:
 
Check system vars in phpMyAdmin to make sure it worked:
  
{{ :extensions:helpdesk:myvars1.png }}
+
[[File:Extensions-helpdesk-Myvars1.png]]<br /><br />
{{ :extensions:helpdesk:myvars2.png }}
+
[[File:Extensions-helpdesk-Myvars2.png]]
  
 
Drop the fulltext indexes from the tables tl_search, tl_helpdesk_tickets and tl_helpdesk_messages. Check also the tables of other installed extensions for fulltext indexes, and drop them as well:
 
Drop the fulltext indexes from the tables tl_search, tl_helpdesk_tickets and tl_helpdesk_messages. Check also the tables of other installed extensions for fulltext indexes, and drop them as well:
  
{{ :extensions:helpdesk:dropft3.png }}
+
[[File:Extensions-helpdesk-Dropft3.png]]<br /><br />
 +
[[File:Extensions-helpdesk-Dropft1.png]]<br /><br />
 +
[[File:Extensions-helpdesk-Dropft2.png]]
  
{{ :extensions:helpdesk:dropft1.png }}
+
Use the contao installation or extension manager to recreate the indexes based on the new settings:
 
+
{{ :extensions:helpdesk:dropft2.png }}
+
 
+
Use the TYPOlight installation or extension manager to recreate the indexes based on the new settings:
+
 
+
{{ :extensions:helpdesk:makeft.png }}
+
  
 +
[[File:Extensions-helpdesk-Makeft.png]]
  
 
== Getting started ==
 
== Getting started ==
  
Well this section is currently very brief. Only a few screenschots so far, but I guess you will figure out usage yourself with some TYPOlight experience.  
+
Well this section is currently very brief. Only a few screenschots so far, but I guess you will figure out usage yourself with some Contao experience.  
  
=== Create a new category ====
+
=== Create a new category ===
  
{{extensions:helpdesk:hd111.png|Goto helpdesk structure}}
+
[[File:Extensions-helpdesk-Hd110.png|Category overview]]<br /><br />
 
+
[[File:Extensions-helpdesk-Hd113.png|Category editor]]<br /><br />
{{extensions:helpdesk:hd110.png|Category overview}}
+
[[File:Extensions-helpdesk-Hd114.png|Category editor]]<br /><br />
 
+
[[File:Extensions-helpdesk-Hd115.png|Category editor]]<br /><br />
{{extensions:helpdesk:hd113.png|Category editor}}
+
[[File:Extensions-helpdesk-Hd116.png|Category editor]]<br /><br />
{{extensions:helpdesk:hd114.png|Category editor}}
+
[[File:Extensions-helpdesk-Hd117.png|Category editor]]
{{extensions:helpdesk:hd115.png|Category editor}}
+
{{extensions:helpdesk:hd116.png|Category editor}}
+
{{extensions:helpdesk:hd117.png|Category editor}}
+
  
 
=== Create a title module for the frontend ===
 
=== Create a title module for the frontend ===
Line 369: Line 352:
 
Basicly a title module is not required, however it helps you structure your forums and helpdesks when you want to group the categories into blocks.
 
Basicly a title module is not required, however it helps you structure your forums and helpdesks when you want to group the categories into blocks.
  
{{extensions:helpdesk:hd118.png|Goto modules}}
+
[[File:Extensions-helpdesk-Hd118.png|Goto modules]]<br />
{{extensions:helpdesk:hd119.png|Add a module}}
+
[[File:Extensions-helpdesk-Hd119.png|Add a module]]<br />
 
+
[[File:Extensions-helpdesk-Hd120.png|Title module settings]]<br />
{{extensions:helpdesk:hd120.png|Title module settings}}
+
[[File:Extensions-helpdesk-Hd121.png|Title module settings]]
{{extensions:helpdesk:hd121.png|Title module settings}}
+
  
 
=== Create block modules for the frontend ===
 
=== Create block modules for the frontend ===
Line 379: Line 361:
 
A forum/helpdesk block module displays a selection of categories in a block on the frontend. So the minimum to get started on frontend is one module of this type. In case you want to structure your categories you will make several of these modules:
 
A forum/helpdesk block module displays a selection of categories in a block on the frontend. So the minimum to get started on frontend is one module of this type. In case you want to structure your categories you will make several of these modules:
  
{{:extensions:helpdesk:hdblock.png|Block module settings}}
+
[[File:Extensions-helpdesk-Hdblock.png|Block module settings]]

Latest revision as of 00:14, 8 March 2012

Forum and Helpdesk

Note.png Note: Parts of this documentation were created by Peter Koch / IBK Software AG. Peter Koch has licensed this content for use on contoawiki.org. Content in this page must not be copied, reproduced, republished, uploaded, posted, transmitted, distributed, or used for the creation of derivative works without IBK's prior written consent.



Features

Extensions-helpdesk-Hd130.png

  • Native Contao application; fully integrated into Contao user/member system.
  • Can be used as forum, as helpdesk ticketing system, or both at same time.
  • Both, frontend members and backend users, can be members/clients or moderators/supporters.
  • Multiple frontend modules with selected categories are possible; to be displayed on one or several pages, or embedded within articles.
  • Backend modules for configuration and forum participation.
  • Comprehensive and fast BBCode engine including tables, lists, several box types, syntax highlighting and more.
  • Popup windows for BBCode help and editor preview.
  • Email notification to subscribing users.
  • Email import to create new topics/tickets, as well as to reply to notifications.
  • Fully customizable layout and appearence by templates and themes.
  • Powerful search engine.
  • RSS feeds for any selection of categories.
  • Convenient moderator functions including cut/paste operations to move messages and topics

Abstract

Contao Forum/Helpdesk is a message board (forum) application designed to be as well used as a helpdesk ticketing system, for example to provide formal and informal support to customers or clients. The terminology and functions of the forum categories is slightly different than the support ticketing categories, but when you know the mapping you will immediately be familiar with the application:

Forum Helpdesk
Category types (1) Restricted or public Private, shared or public
Thread naming (2) Topics Tickets
Frontend users (3) Members Clients
Backend users (4) Moderators Supporters

Categories

  • Extensions-helpdesk-Category416.png Public Forum: Everybody can read the forum, even non-logged in users. Only authorized members can however open topics or reply.
  • Extensions-helpdesk-Category316.png Restricted Forum: The forum is visible only for authorized members.
  • Extensions-helpdesk-Category216.png Public Support: Everybody can see all tickets, even non-logged in users. Only authorized clients can however open tickets or reply.
  • Extensions-helpdesk-Category116.png Shared Support: All authorized clients can see and reply each others tickets, however only the owner has priviledge to close or delete his tickets. Create such a category for example for each company with a SLA((Service level agreement)) where multiple staff members shall have access to the tickets.
  • Extensions-helpdesk-Category016.png Private Support: Only the ticket owner can see his tickets, but nobody else (admins and supporters authorized for the category can of course also see and reply to the tickets). Used for example for formal support of individuals.

Topic vs. ticket status

Topic status

  • Extensions-helpdesk-Ticket0116.png Pinned up: Open topic that is listed on the top.
  • Extensions-helpdesk-Ticket1116.png Normal: A normal open topic.
  • Extensions-helpdesk-Ticket2116.png Closed: No further edits or replies are possible, listed at the end.

Ticket status

  • Extensions-helpdesk-Ticket0016.png Unanswered: The ticked is open and the latest post is from a client. Listed on the top.
  • Extensions-helpdesk-Ticket1016.png Answered: The ticket is open and the latest post is from a supporter.
  • Extensions-helpdesk-Ticket2016.png Closed: Issue solved. No further edits or replies are possible, the owner may reopen it however in case. Listed at the end.

Members and Clients

Forum members and support clients are either "frontend members" or "backend users" in terms of TYPOlight, and belong to a member/user group authorized for the respective category. The client opening a ticket has special "owner" rights in the support type categories: He has authorization to close or delete (5) his tickets.

Admin, Moderators and Supporters

Moderators and supporters are either Contao backend users or frontend members, and belong to a user group authorized as moderator/supporter for the respective category. They have special rights to see unpublished, to pinup, edit, unpublish or delete any topic, ticket or message.

Contao admins are special backend users and appear as moderator or supporter, he/she is automaticly authorized for all categories. Additionally the admins have authorization to administrative operations, e.g. create or delete categories or change category settings. Also admins are the only ones who can see unpublished categories.

Deletion levels

Tickets and messages are not permanently deleted, but only unpublished from frontend when a ticket owner or member/client "deletes" them. They are still available for moderators and supporters however, mainly to serve as a knowledge resource. Tickets and messages can be permanently deleted only by admins, moderators and supporters.

Installation and Setup

Requirements

  • PHP from version 5.2.0
  • Other requirements like [1]

Manual Installation

  • Install these required extensions in advance: extensions:avatar, extensions:cron, [2]
  • Download the install package from [3].
  • Unzip the content of TL_ROOT to the Contao base directory on your webserver.
  • Unzip the content of TL_FILES to the tl_files directory on your webserver.
  • Point your browser to http://www.yourdomain.com/contao/install.php
  • Enter the installation password and click Login
  • Scroll down to Update database tables and click on Update database

Site structure settings

The page where the forum/helpdesk is located should have caching disabled, e.g:

Cache Settings

Page layout adjustment

The module will also work without this, however it will look poor in the frontend.

Go to Page layouts and change the layout for the pages that will display the forum/helpdesk. This might be a special layout you make for the forum/helpdesk pages, or the Default layout.

Scroll down to Additional ‹head› tags and append the following lines to whatever might allready be in there:

<link rel="stylesheet" 
      href="system/modules/helpdesk/themes/default/frontend.css" 
      type="text/css" 
      media="screen,projection,print" />
<!--[if lte IE 6]>
  <style type="text/css">
    .pngfix { behavior:url("system/modules/helpdesk/themes/default/pngfix.htc") }
  </style>
<![endif]-->

Custom themes and templates

Backend themes

To create the theme mysite you would first of cause create a new Contao backend theme folder /system/themes/mysite and activate it in in the Settings.

Then likewise you would create a folder system/modules/helpdesk/themes/mysite, copy the CSS files from the adjaccent default folder and make your adjustments to them. Please note that because of the automatic fallback it is not necessary to copy all the images from the default theme. In case you want your own icons, just create a subfolder images and put them in there; any icons not found there will be taken from the default theme.

Frontend themes

Copy the CSS files from system/modules/helpdesk/themes/default to your custom frontend theme folder and make the desired adjustments. Don't forget to adjust the Page layout as explained before to use your custom stylesheet instead of the default one.

You may want to replace some or all of the default forum/helpdesk icons too. Just put your custom icons into an images folder below your custom theme. Then enter the path of your images folder in the helpdesk settings. Again there is a fallback built in, so any icon not found in your custom images folder will be taken from the default backend theme.

Instead of PNG you may use GIF icons. In case both, a GIF and a PNG icon is found, the PNG has precedence.

Templates

In case you need to customize the default templates, just copy the files of interest from /system/modules/helpdesk/templates to /templates and make your adjustments.

Please note that the template files are used for both, frontend //and// backend.


"Personal data" Module

Note.png Note: As of TYPOlight 2.5.0 it is no longer required to edit the file ModulePersonalData.php; the hook is now included in the core file. However you still need to select the template member_grouped_helpdesk up to 2.5.9. Since TYPOlight 2.6.0 you also no longer need member_grouped_helpdesk because all necessary changes got included in member_grouped.


You may want to give your frontend members the option to subscribe themself for email noification with the Personal data module. This will work right out of the box when you are using the template member_default.

However when using the template member_grouped you won't see the Forum/Helpdesk settings with the TYPOlight releases before 2.5.0. There is a workaround to use the grouped member display right now, which requires a small hack:

Edit the file /system/modules/frontend/ModulePersonalData.php and find this code:

// HOOK: add newsletter fields
		if (in_array('newsletter', $this->Config->getActiveModules()))
		{
			$this->Template->newsletter = $arrFields['newsletter'];
			$this->Template->newsletterDetails = $GLOBALS['TL_LANG']['tl_member']['newsletterDetails'];
		}

Now add the following code immediately below:

// HOOK: add helpdesk fields
		if (in_array('helpdesk', $this->Config->getActiveModules()))
		{
			$this->Template->helpdesk = $arrFields['helpdesk'];
			$this->Template->helpdeskDetails = $GLOBALS['TL_LANG']['tl_member']['helpdeskDetails'];
		}

Finally, go to the Personal data module and select the template member_grouped_helpdesk.

The layout may look somewhat messy by default, here is a suggestion to add to your CSS of the respective page:

.mod_personalData .checkbox_container span
{
    display:block;
    white-space:nowrap;
}
 
.mod_personalData .checkbox_container span *
{
    vertical-align:middle;
}

Enabling RSS Feeds

To enable RSS feeds you need to:

  • Make settings in each category that you want feeds for
  • Make global settings in the Contao settings
  • Add a rewrite rule to your .htaccess file
  • Optional: Add a link to the page header in case you want to display a feed icon in the browsers address field

Category Settings

In the category settings you need to enter the url of the page holding this category, plus check that RSS feeds are enabled. Repeat this for all categories where you want to have RSS feeds for:

Category Settings

Contao settings

In the Contao settings enable the forum/helpdesk feeds, and then make settings for the maximum number of messages to display, the base name of the xml file (same as in the .htaccess below), the title and description of the feed. Please note that this title and description only comes into play for feeds of multiple categories, for single category feeds the title and description of the category is used:

Contao Settings

.htaccess Modification

Add a rewrite rule such as below to your .htaccess file. Replace helpdesk by the term you defined as base name in the Contao settings:

>RewriteRule ^helpdesk([0-9,]+).xml$ system/modules/helpdesk/HelpdeskFeed.php?id=$1 [L]

A typical complete .htaccess for TYPOlight 2.6.0 might be:

# Enable mod_rewrite
RewriteEngine On
RewriteBase /
 
# Block any URI protocol in the query string
RewriteCond %{QUERY_STRING} (ftp|https?):|/etc/ [NC]
RewriteRule .* - [F,L]
 
# Block any URI protocol in the request
RewriteCond %{REQUEST_URI} (ftp|https?):|/etc/ [NC]
RewriteRule .* - [F,L]
 
# Rewrite TYPOlight URLs
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule .*\.html$ index.php [L]
 
# Dynamic RSS feeds for forum/helpdesk 
RewriteRule ^helpdesk([0-9,]+).xml$ system/modules/helpdesk/HelpdeskFeed.php?id=$1 [L]

Add RSS icon link to page layout

This is optional but very convenient for your users. In case you not yet have a distinct page layout for the forum/helpdesk, make a copy of the default page layout. Edit the layout and enter the following link to the Additional head tags input:

<link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.example.com/helpdesk0.xml" />

Replace %%www.example.com%% by your site's url. The 0 tells to provide a feed over all categories the user has read access to. If you want to make a feed over the categories 4, 5 and 7 instead, the link would be helpdesk4,5,7.xml

Email Import and Notification

Email Settings

To send out notifications and import email a batch program must run on a regular base. You need to install the cron utility for this purpose. Below you find suggested settings for the two Forum/Helpdesk jobs. Use a time schedule that matches your needs; the samples below will execute once every minute.

CRON Scheduler

Import Job Settings

Notification Job Settings

Troubleshooting E-Mail Issues

  • Check if your servers are properly configured to send out mails by creating a test-newsletter and sending it to one of your mail accounts. Send it to another server than the one used for sending out the mail to make sure the mail is not getting caught in some spamfilters or lost in any black hole.
  • Using PHP Mail may work on well configured servers (which is not selve-evident these days, cheepo hosters are greeting). Use SMTP in case, that will work 100%.
  • A common mistake is to use a different domain in the notification sender address than in the mail account in the system settings. For example when your SMTP account in the system settings is admin@example.com, a notification sender address such as forum@banana.net is likely to fail because that would be "relaying" which is forbidden in well configured mail servers. Of cause there are exceptions from this rule, for example when the mail server is configured to handle both of those domains. Leave the notification sender address empty until notification works in case.
  • Switch the helpdesk logging to "debug" in the Contao system settings. You will find the log files at /system/logs/Helpdesk*.log. In case no log file gets created during the batch run, your directory permissions of /system/logs does not allow write access for the web server. In that case you can manually create the two files /system/logs/HelpdeskImport.log and /system/logs/HelpdeskNotify.log and give them read/write permissions for the web server (for example as chmod of 666).
  • For debugging it is time-consuming to always have to wait for the scheduler to run. You can disable the scheduler jobs and manually trigger the batch by calling these url's (replace %%www.example.com%% by your own url of cause):
%%http://www.example.com/system/modules/helpdesk/HelpdeskNotifyExec.php%%
%%http://www.example.com/system/modules/helpdesk/HelpdeskImportExec.php%%

You will most likely just see a blank page when executing, but then check the log files after execution to see the results.

Manual upgrade from a previous version

Caution.png Caution: It is recommended to make backups of your files and your database before starting any upgrade.


You can upgrade directly from any previous release, it is not necessary to install every version that was released between your old and new version of the application.

It is optional to delete the files of the old version before installing a new release; you can choose to just overwrite the old files. However there might be obsolete files which will stay in your installation that way. So for a clean update I recommend to manually delete these files and folders in advance:

  • system/drivers/DC_HelpdeskTable.php
  • system/modules/helpdesk


Caution.png Caution: Do NOT delete the mysql tables and settings of the helpdesk application after removing the old files, neither with phpmyadmin nor by using the Contao install tool. Otherwise you will loose all your data and settings.


Next the procedure is basicly the same as with a new installation from scratch:

  • Download the install package.
  • Unzip/upload to your Contao base directory on your webserver.
  • Point your browser to http://www.yourdomain.com/typolight/install.php
  • Enter the installation password and click Login
  • Scroll down to Update database tables
  • If any drops of obsolete table columns are due, they are by default unchecked. It is safe to check them now in order to have clean database.
  • Click on Update database to have the necessary database updates applied.


Note.png Note: After upgrading, you should read the change log to see what has changed and might need your attention.


Optimizing full text search

Full text search of mysql will by default not find any words shorter than 4 characters, or in the stopword list.

To improve search I recommend to lower the minimum word length to 2, or even down to 1. In case your site is not english only, you might also want to disable the default stopword list (or apply [[4]]).

'Brief procedure:

  • Edit the mysql configuration file
  • Restart the mysql server
  • Drop the fulltext indexes
  • Recreate the fulltext indexes


More detailed description (debian example):

Edit /etc/mysql/my.cnf\\ Within the section **[mysqld]** edit or add the following lines:

#
    # Fulltext config
    #
    ft_min_word_len = 2
    ft_stopword_file = ""

Restart mysql:

   /etc/init.d/mysql restart
   

Check system vars in phpMyAdmin to make sure it worked:

Extensions-helpdesk-Myvars1.png

Extensions-helpdesk-Myvars2.png

Drop the fulltext indexes from the tables tl_search, tl_helpdesk_tickets and tl_helpdesk_messages. Check also the tables of other installed extensions for fulltext indexes, and drop them as well:

Extensions-helpdesk-Dropft3.png

Extensions-helpdesk-Dropft1.png

Extensions-helpdesk-Dropft2.png

Use the contao installation or extension manager to recreate the indexes based on the new settings:

Extensions-helpdesk-Makeft.png

Getting started

Well this section is currently very brief. Only a few screenschots so far, but I guess you will figure out usage yourself with some Contao experience.

Create a new category

Category overview

Category editor

Category editor

Category editor

Category editor

Category editor

Create a title module for the frontend

Basicly a title module is not required, however it helps you structure your forums and helpdesks when you want to group the categories into blocks.

Goto modules
Add a module
Title module settings
Title module settings

Create block modules for the frontend

A forum/helpdesk block module displays a selection of categories in a block on the frontend. So the minimum to get started on frontend is one module of this type. In case you want to structure your categories you will make several of these modules:

Block module settings

Views
Personal tools

Contao Community Documentation

In other languages
Navigation
Discover
Understand
Enhance
Miscellaneous
Tools