Helpdesk Setup

Installation

Please read this page carefully and follow any instructions given.

System Requirements

- A Windows or Linux web server with a PHP version 7.0 or higher. To view currently supported versions, see the system requirements.
- Mcrypt library enabled for data encryption (not required for white label licence). Required for PHP7.0* ONLY.
- OpenSSL library enabled for data encryption (not required for white label licence). PHP7.1 or higher ONLY.
- 1 MySQL/MariaDB database to hold the script tables. An existing database is fine.
- MySQL Improved Extension (mysqli) functions enabled on server for database connection.
- Password Hash API support enabled for secure password hashing.
- CURL support enabled for software version check.
- MultiByte String extension enabled for IMAP tickets.
- Imap functions enabled on server for tickets to be opened by standard email.
- Simple XML functions enabled on server for XML API.
- JSON functions enabled on server for JSON API & Ajax responses. MUST be installed.

The installer will check what functions are available.

Finally, a good VPS or Dedicated server is recommended. Processing power is slow and unreliable on shared servers. This could impact your business and support!

Step 1: Create Database

If you haven't already done so, create a database to hold the script tables. An existing database is fine. If you are unsure how to do this please contact your web hosting company. As many control panels differ, no one tutorial can cover all scenarios.

Step 2: Create Config File

Copy the 'control/_cfg-sample.php' file as 'control/_cfg.php'.

Step 3: Edit Connection File

Using a good quality text editor (NOT a word processor), open the following file:

control/_cfg.php

Perform the following operations:

1 - Edit database connection parameters to point to the database you created in step 1. Contact your host if you aren't sure. Prefix is required if you only have a single database. This might be something with an underscore. It's fine to leave the prefix as is, so don't change if you aren't sure. See notes in connection file.

Example:

define('DB_HOST', 'localhost');
define('DB_USER', 'joeblogs_admin');
define('DB_PASS', '12345XX');
define('DB_NAME', 'helpdesk');
define('DB_PREFIX', 'ms_');


2 - Specify character set for database. Can be left blank if preferred. Used for 'Set Character Set' and 'Set Names'. If you aren't sure, utf8 should be fine. See notes in connection file:

define('DB_CHAR_SET', 'utf8');

3 - Specify locale for your database. Only really required to be changed if your language isn't English. This will ensure text data in dates converted by MySQL is in your local language. For English, 'en_GB' should be fine for all. See notes in connection file:

define('DB_LOCALE', 'en_GB');

4 - Specify secret key (or salt). You can use the Maian Media secret key service to generate a unique key. See the connection file for more information.

define('SECRET_KEY', 'your unique string here');

5 - The option to display MySQL errors should only be enabled if you are having problems. This will display the possible problem. As it's a security risk to display MySQL errors because of server paths, this is disabled by default. Instead a simple message appears whenever a MySQL error occurs. Edit as required.

SAVE FILE!

NOTE! At this point you should make sure that the file didn't save with whitespace before the opening <?php tag or after the closing ?> tag. You should also make sure that your text editor does NOT save with the Bom Byte Order Mark. This can potentially fail PHP files and cause nothing to appear but a white screen. It is generally NOT recommended to edit files directly on the server via a control panel.

Step 4: Transfer Files to Server

Using a good FTP program such as FileZilla, WinSCP or CyberDuck, transfer the 'helpdesk' folder to your web server.

Most good FTP programs auto detect 'ascii' mode for PHP files. However, if you are presented with an option, you should specify 'ascii' and not 'binary'.

- 'helpdesk' may be renamed if you wish.
- Files can also be uploaded to root of web server if you prefer. Open 'helpdesk' folder and transfer files.

https://www.example.com/helpdesk/
https://www.example.com/

Step 5: Permissions

The following folders are required to have read/write permissions. On Linux 0777 or 0755 should be used:

admin/export/
content/attachments/
content/attachments-faq/
logs/


For help on how to change permissions on a linux server using Filezilla, click here. You can change permissions in most good FTP programs or directly on the server via the control panel. Attachment locations can be changed later if preferred.

Step 6: Accessing the Installer or Manual Install

Once the files have transferred successfully, access the 'install' folder in your browser. An example if your website was at 'example.com/helpdesk/':

https://www.example.com/helpdesk/install/

Follow the on screen instructions. Alternatively, if you are an advanced user and you are familiar with executing SQL files, run the following file in your MySQL database management program.

docs/schematic/database-schema.sql (MySQL 5 or higher ONLY)

The following FREE applications can be used to administer MySQL databases:

HeidiSQL (Lightning fast Windows based software)
Adminer (Recommended web based database management via a single .php file)
PHPMyAdmin (Installed on many servers as the default database software. PHP based.)
SQL Buddy (Lightweight PHP based software. Great alternative to PHPMyAdmin, but no longer developed)
MySQL Workbench (Alternative Windows based software from the MySQL creators. Also available for Mac.)
Sequel Pro (Mac)
Database Beaver (Windows/Mac/Linux. Java based.)

NOTE: If you manually run the 'docs/schematic/database-schema.sql' file you do NOT need to access the install folder! Just run the SQL file, then access your helpdesk index.php file in a browser. Values that are blank in the import file (such as paths), will be updated automatically on load.

Step 7: Update Settings / Check Paths

Log into your administration area (via the 'admin' folder) using the administrative user details you entered during install. If you ran the manual install option, log in with the following email and password:

Email: admin@example.com
Pass: admin

An example if your website was at 'example.com/helpdesk/':

https://www.example.com/helpdesk/admin/

From the left menu select the following:

Settings & Tools > Settings

Check the following paths to make sure they are correct. The installer will have attempted to calculate these. If they haven't or you ran the SQL file manually, these paths MUST be correct. Use the icon if you think a path is wrong and want the system to attempt to create it. Note that for attachment paths "FOLDER_NAME_HERE" should be changed to your actual folder name if renaming folders.

General > HTTP Installation Path
Attachments > Server Path to Attachments Folder
Attachments > HTTP Path to Attachments Folder
F.A.Q > Server Path to F.A.Q Attachments Folder
F.A.Q > HTTP Path to F.A.Q Attachments Folder


NOTE: A server path is NOT a http path. Examples of server paths would start:

/home/server/public_html/...
/server/www/...
c:\windows\helpdesk\..

You should also update any other settings to suit your requirements. Most options can remain as is for testing as the defaults should be fine.

Step 8: SMTP Settings

SMTP is recommended for ALL mail operations. Maian Support utilises the PHP Mailer system for SMTP. To enable SMTP in the system, access the SMTP settings via:

Settings & Tools > Settings > Other Options > Mail Settings

If you don't have SMTP available, there are a number of SMTP services around. Mailgun is a free SMTP service that allows 12,000 free emails a month.

Maian Support also supports the PHP mail function, but this may be less reliable and only supports plain text messages.

Step 9: Crontabs/Cronjobs

The following files should be set up to run as automated tasks:

control/cron/close-tickets.php - Auto closes tickets. More info here.
control/cron/db-backup.php - Database backup. More info here.
control/cron/email-digest.php - Email digest with ticket info. More info here.

More info on crons here.

Step 10: Update Administrative User for Manual Install

If you ran the manual install option, make sure you update the username, email & password for this user. To do this access 'Support Team > Manage Staff' in your admin area and click edit on the relevant link. Only a single user would exist at this point.

Step 11: Add Additional Support Team Members/Users

If required, add more support team members. For support staff help, click here.

Step 12: Rename administration folder

For additional security it is highly recommended you rename your 'admin' folder. To do this perform the following operations:

1 - Manually rename the 'admin' folder to something unique. Letters, numbers, underscores or hyphens should be used, no special characters.

2 - Access the following page in your administration area via the left menu: Settings & Tools > Settings

3 - Enter your new folder name in the option 'Admin Folder Name'.

Step 13: Getting Started

Now that the system is installed, you can start testing the system.

Departments are all that's required to get the system ready for testing, once you have added 1 or more departments give the system a run through. Visitor accounts can be added manually if you wish, or will be created automatically depending on settings.

Maian Support offers a powerful, yet simple set of features for a fast, reliable help desk system. You'll find links to relevant help pages via the 'Help' link in admin, which is found at the very top of the page.

Step 14: Templates/Colours/Images

Once you are getting familiar with the system, see the 'HTML Templates' section for help on adapting the layout into an existing website or changing colours.

Step 15: Language & Text

See the Language & Text section for further assistance.

Step 16: API

Accounts and tickets can be opened from many applications that support http posts. See the API for more info.

Comments/Feedback

If you have comments, problems or general feedback about this system, we would very much like to hear your comments. Use the contact option on the Maian Support website. If you would like to see new features, please let us know.