Setup:Downloading real mail into your Helpdesk for the first time

From Cerb Wiki
Jump to: navigation, search

Written based on a 4.3.1 install. Concepts, links are the same, screens need to be updated.

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!” 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 Cerb that’s not quite production-ready. You may have noticed that none of your organization’s e-mail is downloaded to the Helpdesk.

Does Cerberus support Piping (a.k.a. Pushing)

In Short: No

For a longer version there was a blog post back in 2008 describing why.

http://www.cerb4.com/blog/2008/09/09/difference_between_piping_and_polling/

/* FIX ME */ Update and migrate the info in the wiki.

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 Cerb 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.

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.

Wait for the green success message.

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 the Helpdesk 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 Cerb) and only add that single mailbox to Cerb. 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.
  • Cerb 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 the Helpdesk checks, and one to keep a copy.

Actually downloading mail

That gets you half way to grabbing your mail, but there’s still one important step. Unfortunately, Cerb 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 the Helpdesk caught up on all the existing mail currently sitting on the server.

Click "automatically run jobs in a browser window".

(Unauthorized IP?) This should be a good test to see if everything is working and a good opportunity to gauge the Helpdesk's performance. At the end of this guide, I'll talk about the "Advanced" option and why you should use it from now on.

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 Cerb 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.
Click the job title to see the options.

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 Cerb 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.

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 the Helpdesk, 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 Advanced link: ping http://example.com/cerb5/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 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 Cerb, receiving new mail at regular intervals.

The tickets in the screenshot are "fake" (@cerberusdemo.com) but your REAL e-mail should start populating the 'Mail', 'Overview' tab as they enter the Helpdesk.

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.

Not having the appropriate IP address can block the cron.