1   Prerequisites

To function properly, Whups requires the following:

1. A working Horde installation.

   Whups runs within the Horde Application Framework, a set of common tools for web applications written in PHP. You must install Horde before installing Whups.

   Important

   Whups H5 requires version 5.0+ of the Horde Framework - earlier versions of Horde will not work.

   Important

   Be sure to have completed all of the steps in the horde/docs/INSTALL file for the Horde Framework before installing Whups. Many of Whups's prerequisites are also Horde prerequisites. Additionally, many of Whups's optional features are configured via the Horde install.

2. The following PHP capabilities:

   1. SQL support

      Whups stores its data in an SQL database. Build PHP with whichever SQL driver you require; see the`horde/docs/INSTALL`_ file for details.

2   Installing Whups

The RECOMMENDED way to install Whups is using the PEAR installer. Alternatively, if you want to run the latest development code or get the latest not yet released fixes, you can install Whups from Git.

pear install -a -B horde/whups

pear install horde/whups

pear install -a horde/whups

3   Configuring Whups

1. Configuring Whups

   You must login to Horde as a Horde Administrator to finish the configuration of Whups. Use the Horde Administration menu item to get to the administration page, and then click on the Configuration icon to get the configuration page. Select Tickets from the selection list of applications. Fill in or change any configuration values as needed. When done click on Generate Tickets Configuration to generate the conf.php file. If your web server doesn't have write permissions to the Whups configuration directory or file, it will not be able to write the file. In this case, go back to Configuration and choose one of the other methods to create the configuration file whups/config/conf.php.

   Documentation on the format and purpose of the other configuration files and templates in the config/ directory can be found in each file. You may create *.local.php versions of these files if you wish to customize Whups' appearance and behavior. See the header of the configuration files for details and examples. With one exception (reminders.php, in case you want to automatically sent out reminders about open tickets) the defaults will be correct for most sites.

   The *_email.plain.php files define how outgoing email notifications about ticket changes look like. See the comments in these files for details.

   If you would like the ability to create and update tickets via email, you will need to set up whups-mail-filter to receive email from the appropriate addresses. This script takes a number of arguments; see the script for more details. A typical setup might be:

   bugs |/usr/bin/whups-mail-filter --queue-id=1
   

   For Postfix:

   bugs: |"/usr/bin/whups-mail-filter --queue-id=1"
   

   This will take in mail to the bugs address at your domain, and create new tickets in the queue 1, with the default type, state and priority of this queue. If an email references an existing ticket (ticket numbers are recognized in the subject line) it will be updated instead.

   If not installing Whups through PEAR of if PEAR's bin_dir configuration doesn't point to /usr/bin/, replace /usr/bin/whups-mail-filter with the path to the whups-mail-filter script in your Horde installation.

   See also Creating tickets from email messages below.

2. Creating the database table

   Once you finished the configuration in the previous step, you can create all database tables by clicking the DB schema is out of date. link in the Whups row of the configuration screen.

   Alternatively creating the Whups database tables can be accomplished with horde's horde-db-migrate utility. If your database is properly setup in the Horde configuration, just run the following:

   horde-db-migrate whups
   

3. Testing Whups

   Use Whups to create your base data, create tickets, and modify tickets. Test at least the following:

   • Creating a new project (queue)
   • Creating ticket types, states, priorities for a project
   • Adding a ticket
   • Assigning a ticket
   • Closing a ticket

4. Creating tickets from email messages

   Whups provides functionality that can be used to create and update tickets from email messages. One part of this functionality is the whups-mail-filter script. It can either be installed inside the mail chain, or run as a standalone script against an IMAP or POP3 server. It provides a list of all available command line arguments if called with the --help argument: whups-mail-filter --help.

   If you use the arguments starting with --mail, the script will login to the provided IMAP or POP3 server and process all messages in the specified folder. Any successfully processed messages will be deleted. An error message will be displayed for any failed messages. Using the script in this mode makes most sense when run regularly, e.g. by a cron job or the Windows task planner.

   You can also install the script inside the mail chain. In this mode, the script expects a single email message from standard input. A common scenario would be to pipe all messages to a certain email address through this script, e.g. through the forwarding or alias mechanism. An example entry in /etc/alias could look like this:

   bugs:"|/usr/bin/whups-mail-filter -q 'Test Queue'"
   

   Even though this example uses a queue "name" for the argument, it's preferred to use IDs, because those doesn't cause any problems with spaces, or non-ascii characters.

   The script tries to determine the ticket number from the message, if a ticket number hasn't been specified with the --ticket argument. Currently it searches for strings looking like "[Bug #1]" in the message subject. If a ticket number cannot be determined by any means, or if a ticket with that number doesn't exist, a new ticket is created.

   The (Horde) user that will be used to create or update the ticket, will also be determined by investigating the message. The email address used in the From: header of the message will be looked up by searching all identities of all users in the authentication backend. This only works if the authentication backend is capable of listing users. If a user cannot be determined this way, the user provided by the --default--auth argument, if any, is used. Finally, if none has been provided, the user specified in Whups' configuration ($conf[mail][username]) will be used. If there still hasn't been a user determined at this point, the ticket will be updated or created by the "guest" user, using the email address of the From: header. This only works if guest access has been granted to both Whups, and the queue specified with the --queue-name or --queue-id parameters.

   Finally, you might want to to enable the setting in Whups' configuration, below the "Email Settings" tab, that allows users to reply to ticket emails. This setting removes the warning from the generated ticket emails to not reply to those emails. And you should of course make sure that you specify the correct email address here for the generated messages. It should be the address that you use for the mail pipe, or the IMAP/POP3 account when calling whups-mail-filter.

   Any attachments that have been sent with the message will be added to the ticket as attachments too. This is done via the virtual file system (VFS) of Horde. If you use the local file system as the VFS backend, you need to take care of permissions and umasks, i.e. both the user running the whups-mail-filter script and the user running the web server need to have read-write permissions to the VFS storage directory.

4   Obtaining Support

If you encounter problems with Whups, help is available!

The Horde Frequently Asked Questions List (FAQ), available on the Web at

http://wiki.horde.org/FAQ

The Horde Project runs a number of mailing lists, for individual applications and for issues relating to the project as a whole. Information, archives, and subscription information can be found at

http://www.horde.org/community/mail

Lastly, Horde developers, contributors and users may also be found on IRC, on the channel #horde on the Freenode Network (irc.freenode.net).

Please keep in mind that Whups is free software written by volunteers. For information on reasonable support expectations, please read

http://www.horde.org/community/support

Thanks for using Whups!

The Whups team