Downloading real mail into your Helpdesk for the first time
From Cerberus Helpdesk Wiki
I finished the installer, logged in, and read the Welcome page. Now what?
The first thing you’ll want to do is probably read the “Welcome to Cerberus Helpdesk 4.0!” ticket, which will at least give you an idea of what groups are and explain how to change the defaults. More importantly it’s a good way to get customer support from us right away, simply reply to the message.
Unfortunately the hand-holding from us stops there. And at this point you’re left with a copy of Cerb4 that’s not quite production-ready. You may have noticed that none of your organization’s e-mail is downloaded to the Helpdesk.
Contents |
[edit] Why we don't set this up for you
In the past we had a more thorough installer that forced you to configure everything up front, including POP3/IMAP accounts. Needless to say there’s a number of reasons why this didn’t work out, one being, the installer expected our customers to immediately understand how Cerb4 works. Imagine downloading a trial copy but before you get to see it in action you’re forced to create mail accounts, workers, groups, passwords and permissions. Definitely not the ideal way to present our software for new users. Instead we opted for a quick install and the Simulator plugin that lets you see how the mail functionality works before bothering with the Helpdesk configuration.
[edit] Adding a POP3 or IMAP account
With that history lesson out of the way, what you really need to know is that until you configure at least one mail server, you are not going to be getting e-mail. To add a POP3 or IMAP account to download mail from, go to ‘helpdesk setup’ and click ‘Mail Setup’. Fill in the details, click "Test Mailbox", and wait for a success message.
[edit] Two recommendations
Or maybe more like warnings before you put this into production.
- While theoretically you can add as many mail accounts as you need, it’s better to use as few mailboxes as possible since each account requires Cerb4 to open and close a new connection. For better performance and to limit the potential for complications, it’s recommended you forward all your POP mail to one “dropbox” account at the mail server level (outside the scope of Cerb4) and only add that single mailbox to Cerb4. For those paranoid about losing the unique account information from each mailbox, this move will have no effect on the account-specific e-mail headers.
- Cerb4 will download and delete all emails from your mail server, with both the POP3 and IMAP protocols. So don't set up an account unless you are comfortable with that OR have a way to archive that e-mail first. One way is to duplicate it at the mail server level and send it to two mailboxes; one that Cerb4 checks, and one to keep a copy.
[edit] Actually downloading mail
That gets you half way to grabbing your mail, but there’s still one important step. Unfortunately, Cerb4 will not download e-mail on its own without a little help. For now click the Simple option "automatically run jobs in a browser window" to get Cerb4 caught up on all the existing mail currently sitting on the server.
(Unauthorized IP?) This should be a good test to see if everything is working and a good opportunity to gauge the Helpdesk performance. At the end of this guide, I'll talk about the "Advanced" option and why you should use it from now on.
[edit] Quickly get all your old mail
Since this is your first time importing mail, you might want to speed up the system by lowering the minutes and raising the max messages of the ‘Scheduled Jobs’.
- POP3/IMAP E-Mail Importing: changes how often Cerb4 downloads new messages and how many at a time.
- Inbound E-Mail Processing: changes how many and how often it converts them into tickets the Helpdesk understands.
Note that it’s not necessary to do this, your mail will eventually get to the Helpdesk anyway but if you have a lot of mail it may take longer than necessary. In the background, the new window will automatically refresh over and over, continuously grabbing mail. Eventually it will stop giving you a log of successful parses. After the first big import is done change the max messages and minutes back up to the more reasonable default levels (5 minutes, 20 messages and 1 minute, 500 messages respectively). Over time if you find Cerb4 is not checking mail frequently enough for your workload, try throttling up or down these values for better performance. The actual values can be influenced by your server hardware so if the e-mail processing is reporting it's locked, disable and re-enable it, then reduce the numbers. Why waste server cycles checking for mail faster than you actually get it.
[edit] Automating mail parsing for the future
You chose "Simple" for the first time download, now you want to go with the Advanced option the rest of the way. It’s not the easiest concept to explain in layman’s terms, but basically you need to create a scheduled task that runs on your server every couple of minutes to “ping” a web page.
Why go this route? If you don't use Advanced and stick with Simple, you have to always remember to keep that page open in your browser whenever somebody is using Cerb4, otherwise you will not get any new e-mail. This way mail is fetched automatically in the background and you won’t have to worry about it.
Copy whatever that URL is in your Helpdesk from the (ping http://example.com/cerb4/index.php/cron?loglevel=3 with wget/lynx in an external cron/scheduled task). And use it to create a scheduled task on your server. There are very detailed directions for doing this on both a Linux and Windows machine.
And you're done! If you added a mail server AND configured a scheduled task, you should now have a live production-ready Cerb4, receiving new mail at regular intervals.
[edit] Troubleshooting
If the Simple cron cannot run because "your IP address is not authorized", add the reported IP to the 'helpdesk setup', 'System' tab, 'IP Security' section.
Adapted from a Cerb4 blog post.
