Smart tip: This handbook is also designed to be printed... set your printer's page orientation to landscape format, so there is enough space to place hand-written notes on the left and right margin easily.
 

In a common environment, we recommend to create a new sub-directory within the existing "cgi-bin" folder to separate the software from other already installed products.

Required "template.en" directory:

Inside the directory you desired for installation, please create a new sub-directory called "template.en". It's used to hold the content of "template.en" directory delivered with your software package.

Required "data" directory:

Inside the directory you desired for installation, please create a new sub-directory called "data". It's used to hold the content of "data" directory delivered with your software package.

Adjust path to Perl:

Open all program files (*.pl and *.cgi) in a text editor and change the first line "#!/usr/bin/perl" that it reflects the correct path to Perl 5 (or higher version) on your system. This is required to let your server know where the Perl interpreter is located.

Usage note: On most systems, /usr/bin/perl is already the default path to Perl and so no modifications are required.
 

Detailed file table: Scheme: [filename | suggested place to upload (short description); file permission]:
 

Filename...	Description...	Filename...	Description...
*	cgi-bin (program & data files); 755	template.en/*	template.en (templates); 666
		data/*	data (basic data files); 666

Important notes: Please double-check file permissions and transfer mode, otherwise the software may not work as intended. Depending upon the server configuration, different file permissions than the ones stated above may be necessary.

Smart tip: Our installation helper install.cgi makes it easier... just call it from your web browsing software (requires correct installation of this script) and it automatically checks your entire installation, adjusts permissions and fixes typical errors.
 

Before you proceed, it is highly recommended to set an administration password. After this is done, access to the admin panel is granted only by using "admin" as login together with the chosen password.

Now click on the button "Edit system parameters" and configure the shown parameters according your needs.

Usage note: Since all parameters are automatically filled with correct values, modifications on your side may not be required.

Directories and files:
 

Name of parameter to set...	Description...
CGI files directory Example: /usr/www/cgi-bin/msuite	Absolute path to the location of MessageSuite on your server.
"binarydata" directory * Example: /usr/www/cgi-bin/msuite/bindata	Absolute path to the location that holds binary database content.

* Technical note: The software tries to create this directory at a web-accessible place (certain cgi-bin locations doesn't allow to deliver multimedia content). If you experience problems in content delivery, please move it manually to a suited location.

Platform specific settings:
 

Name of parameter to set...	Description...
Mailing program (for Unix only) Example: /usr/bin/sendmail	Absolute path to Sendmail (or compatible) application on your server.
SMTP server Example: smtp.sunnyscript.com	SMTP server for handling mails; when left blank, default mail application is used. This setting is required for non-Unix systems, otherwise optional.
Don't use flock Example: Unchecked	"flock" is normally supported directly by the operating system; should it be unavailable for any reason (e.g. on Win9x, WinMe), mark this checkbox.
Don't use fork Example: Unchecked	"fork" is normally supported directly by the operating system; should it be unavailable for any reason, mark this checkbox.
Forked process respawn interval (seconds) Example: 60	Respawn interval for processes; recommended range: 30 to 60 seconds.
Max. life of chat process (seconds) * Example: 60	Respawn interval for chat processes; recommended range: 30 to 60 sec.
Webserver buffer size (bytes) * Example: 16	Size of the data buffer during chat; recommended range: 16 to 8192 bytes.
Admin e-mail address Example: admin@sunnycript.com	E-mail address of the system administrator (e.g. webmaster).

* Available on MessageSuite plus only.

URLs:
 

Name of parameter to set...	Description...
Binary directory URL Example: http://www.sunnyscript.com/cgi-bin/msuite/bindata	URL to the location that holds binary database content.
URL of CGI files directory Example: http://www.sunnyscript.com/cgi-bin/msuite	URL to the location of MessageSuite on your server.

Various parameters:
 

Name of parameter to set...	Description...
Authentication time (in seconds) Example: 36000	Time frame keeping user authentications active (after expiration, people must log in again); recommended range: 1 to 12 hours.

After you have verified all settings carefully, click on the button "Save parameters" to take over modifications to the system. It is also possible to bring back previous values with the "Let the script restore defaults" button.
 

How to access the staff panel:

The staff panel is a special web panel (but similar to the admin panel) intended for operators to work on cases.
 

Get access by using the concerned staff profile's login information; multiple profiles can be logged in at the same time and work simultaneously (see chapter "Helpful hints and technical reference" for some notes).

Usage note: Finally it does not matter wether calling admin.cgi or login.cgi. You can use both to get access either to the administration panel or the staff panel. The software automatically decides depending upon the login information.
 

The top menu line provides additional selections (depending on the current system status):
 

If you are interested in the setup of applications, implementation topics or advanced features, please refer to the next chapters for more comprehensive information. As a beginner, start with the chapter "Case management & advanced features".
 

General settings:
 

Security settings:
 

Reading notification:
 

User lounge layout:
 

Staff panel layout:
 

Chat (MessageSuite plus only):
 

Mailings:

The following settings are valid for using MessageSuite handling e-mail correspondence (explained later more detailed).
 

* Technical note: In order to avoid receiving too many alerts, you will only get one alert related to the same-typed error within 24 hours. However each single alert is logged for later referencing purposes.

Data maintenance:

Each time data maintenance runs, the following actions are performed:
 

* Manage cases and POP3 gateway accounts. * Remove expired activity log entries.

Important note: Executing data maintenance is required and needs "fork" function to be enabled (see "System parameters"). If it is disabled due to technical limitations of the server, please follow instructions below.
 

Data maintenance with disabled "fork" function:

Schedule the file cron_run.pl (file is located in the software directory of MessageSuite) to be ran regularly by your server (recommended scheduling: each ten minutes). You may use Cron or your server's scheduling tool in order to manage this task.

Technical note: Even when starting data maintenance in this way, ensure to fill in the parameters above.

By the way: If you are new at scheduling server actions, please contact your webhoster for details or refer to available literature. Alternatively you may use the Cron editor we provide (call cron_edt.pl from the command line, e.g. "perl5 cron_edt.pl").
 

Topic categories divide your message system into different fields of interests. Incoming user messages and inquiries are scanned for matching topic categories and automatically assigned to the correct one by using a complex filtering system.

Each staff member is assigned to specific topic categories (multiple staff members can work for a particular category). In this way, they answer only inquiries of their concerned field.

Some examples of possible topic categories:

Let's say you manage a hardware store providing online customer service: So topic categories like "Do-it-yourself", "Decoration and fabrics" and "wooden floors" would be useful; each one has experts assigned specialized in concerned field.

Your company distributes computer software: For each product range (like "Games", "Business applications" and "Networking products") you may create a topic category maintained by experienced support personnel.

As project manager you use topic categories to handle the daily flood of important (and not so important) messages.

Are topic categories absolutely required ?

As you have noticed, there is one topic category ("default") pre-defined. It is mandatory for the system, because the software must need to know how to handle incoming messages - and since this is set in topic categories, you need at least one of them.

How to create a new topic category ?

Type in the name of the new topic category (keep it short; use alphanumerical chars only) and click on the button "Create new".

How to edit / remove a topic category ?

Select the topic category from the list, click on "Delete" or "Edit" and follow the provided instructions.

How to change the sorting of topic categories ?

Select the one you wish to move around and click on either "Move up" or "Move down" button to change its position (this affects the category's position within the user lounge).
 

FAQ / KnowledgeBase search:
 

Incoming mail sorting:

Incoming e-mails are filtered and then directed to the matching topic category.
 

Topic specific incoming mail autoresponder:

For each incoming inquiry, MessageSuite can search the FAQ/KB databases for matching solutions; found results are then automatically mailed to the concerned user - this saves time answering recurring questions.
 

User groups gives you the ability to assign different rights to certain users (like "normal" and "preferred" customers).

By default, two user groups are pre-defined:

The group "?" refers to all unregistered users (people sending inquiries or accessing the user lounge without logging in).
The group "*" refers to all registered users (people accessing the user lounge with their username/password pair).

Technical note: Both groups are mandatory for MessageSuite, feel free to configure them according your requirements.

How to create a new user group ?

Type in the name of the new user group (keep it short; use alphanumerical chars only) and click on the button "Create new".

How to edit / remove a user group ?

Select the group from the list, click on "Delete" or "Edit" and follow the provided instructions.

How to change the sorting of user groups ?

Select the one you wish to move around and click on either "Move up" or "Move down" button to change its position (this affects the group's position within the admin and staff panels).
 

User group permissions:
 

Profile lifetime limitation:
 

MessageSuite is able to import messages from e-mail accounts compatible to the post office protocol (POP3). Such e-mail accounts are named "gateway accounts" in this manual.

Each time executing the data maintenance routines, MessageSuite downloads all mails from the gateway accounts, analyzes their content according your preferences and either creates new cases or assigns messages to existing ones.

Important note: Gateway accounts needs to be exclusively managed by MessageSuite; shared usage may lead to data loss.

How to create a new gateway account ?

Type in the name of the gateway account (keep it short; use alphanumerical chars only) and click on the button "Create new".

How to edit / remove a gateway account ?

Select the account from the list, click on "Delete" or "Edit" and follow the provided instructions.
 

Account settings:
 

Usage note: The mail account details are available from your ISP (Internet Service Provider) or webhosting provider.
 

E-mail gateways:

MessageSuite manages incoming messages from gateway accounts to handle mail communication efficiently. Customers and prospective clients can reach you simply by using their familiar mail clients.

Web-based services:

Via the built-in user lounge, people can access your support and communication areas instantly from everywhere. An online live chat (MessageSuite plus only) provides a convenient solution for pre-sale inquiries and fast support services.

Offline communication stream:

This refers to all kinds of communication not requiring a personal computer or access to the Internet: Starting from telephone and fax, over written correspondence and ending in smoke signals (last way is not directly supported by MessageSuite ;-)

All kinds of offline communication can be recorded by MessageSuite for later reference.
 

Open the staff panel:
 

Use your staff login and password pair to get access. Depending upon the permissions assigned to your profile, some of the features described in the following may not be available.

Overview:

On the main staff panel screen, the following selections are available on the top menu line:
 

Depending upon the screen currently shown, more top menu entries may be available. Since we have spent much time to make the staff panel self-explaining, you'll find it very easy to use.

Main staff panel screen:

The main staff panel screen shows all open cases assigned to your profile. Click on the linked subject or the case number in order to view the cases and all messages more detailed.

Use "Staff cases" to work on assigned cases and "Database tools" to search for specific records (cases, messages).

Case details screen:

Shows all case details as well as the messages connected to it. Starting from this screen, you can manage further actions, like replying to the user's inquiry or viewing more details about the concerned user who initialized the case.

Provided that the concerned staff member has sufficient permissions, more complex tasks are available on this screen, like merging or deleting cases and updating FAQ / KnowledgeBase instantly.

Replying to a user message within a case:

Click on "reply" near the user message you wish to reply. The following screen will appear:
 

Create a new case:

Click on "New case" in the upper right corner of the screen. For more details, please take a look at the part "Manage system tables - overview and applications", "Table of cases".

Usage note: As soon as the user inquiry is answered, ensure to close the case (set its status to "closed").

Handling offline communication streams:

As a staff member, you may also do telephone support, answering faxes or written correspondence. For each new user inquiry you receive, please create a new case within MessageSuite to keep the case database up to date.

Select the appropriate "Type" (e.g. "Phone call" or "Fax message") and the correct "Direction" (e.g. "Incoming"). In this way, other staff members have all necessary information also about cases managed offline.

While working on a case, you may add new messages (e.g. repeated faxes or phone calls) to the case and set its flag to the appropriate status (e.g. "Replied, awaiting user response").

Printing messages or entire cases:

Click on "print" near a particular message or case to see it in a printer-friendly layout or click on "FAXable" to see an outgoing message ready formatted for being sent via telefax (including a customizable fax header).

In both cases, a new browser window opens to show the content - in order to go back to the original screen, simply close this window again. You can modify the default templates by using the "Templates editor".

By the way: All graphical attachments (e.g. screenshots) are shown for being printed or faxed directly (requires support of the concerned file formats by your web browsing software).

Usage note: This feature is suited well for handling offline communication streams efficiently or creating paper-based archives.
 

Chat sessions - overview:

Topic specific chat sessions:

When people sending an inquiry via the user lounge, they have the ability to open a chat session with a staff member of their choice (if more than one suited staff member is available and selection allowed by the admin).

In this way, MessageSuite looks for the most experienced chat partner. Before starting the chat session, the selected staff member will see all inquiry details.

Direct chat sessions:

You can also add a link to your website providing chat sessions, suited for pre-sale inquiries or questions concerning your website (e.g. provide personal advice while people go shopping online).

An auto-adjusting "availability banner" can be placed on your website indicating whether staff members are available for chat or asking the visitor to leave a message via the user lounge.

Pre-requisites for chat sessions:

In order to allow chat sessions, one or more staff members must be logged in and having the chat listener active (click on "Open chat" when you are on the staff panel (the pop-up window must be kept open, but can be minimized).

For enabling direct chat sessions, ensure that the "Direct chat" parameters on screen "Edit MessageSuite parameters" are set correctly. Please refer to the chapter "System implementation" for more details.

In some cases, you may need to modify the "System parameters" screen, part "Platform specific settings":
 

Name of parameter to set...	Description...
Max. life of chat process (seconds) Example: 60	If the chat session is interrupted, then decrease the value carefully until it is kept stable (should not go below 10 seconds to avoid an unnecessary high server load).
Webserver buffer size (bytes) Example: 16	If the data transmission is too slow during chat sessions, increase the buffer size until the performance is suited (however a delay of up to five seconds is okay). Technical note: Should your server support unbuffered content delivery, then set this value to "0" to achieve best results (ask your system administrator before).

Important note: When closing a chat session, please click on the appropriate link appearing in the chat window (do NOT simply close the window, this causes an activity timeout error and leaves the chat session incomplete).

How to start a topic specific chat session:

The entire procedure is handled by the staff panel / user lounge automatically. Please refer to the chapter "User lounge and template management" for more details.

Chat sessions - technical and usage notes:

If user requests a chat, the FAQ search results are shown in any case (even if "Skip FAQ" checkbox is enabled).

At a beginning chat session, the referring URL is shown allowing to determine the user's location on your website (intended to answer product specific questions with reference to the current open webpage).

Chat sessions can be printed and even sent by e-mail; this is useful when needing to clarify open issues by a third person.

If staff member sends an e-mail address or Internet location (e.g. website URL) during the chat, it will be automatically send with embedded HTML to make it clickable by the user (content opens in a new browser window to keep running chat session).

How staff members are chosen by the software:

MessageSuite looks for the "best-suited" staff member for a topic specific chat (depending upon members' priority settings).

In order to achieve a balanced workload, staff members already involved in chat sessions will be ignored unless no other staff member is available for concerned topic. Then one already chatting member will receive also the new chat session.

In the case that there are two or more staff members available with same priority on the concerned topic, MessageSuite randomly selects the chat partner.

Direct chat session - availability banner & implementation of chat link:

The "availability banner" is suited to notify people visiting your website about staff members available for chat (should nobody be able to talk to them right away, then people can leave a message via the user lounge).

You need to create two graphics of equal size and upload them to the location of your website: The first image should say "Talk with us personally now !" and the second one "Leave a message !".

Now implement the "availability banner" (isonline.cgi) to your website according this scheme:
 

<a href = "<URL>/user.cgi?action=direct_chat&topic=<Topic>"> <img src = "<URL>/isonline.cgi?topic=<topic>&yes_url=<YesURL>&no_url=<NoURL>"> </a>

A filled-in sample may look like this (please ignore any line breaks):
 

<a href = "http://www.sunnyscript.com/cgi-bin/msuite/user.cgi?action=direct_chat& topic=*"><img src = "http://www.sunnyscript.com/cgi-bin/msuite/isonline.cgi?topic= *&yes_url=http://www.sunnyscript.com/chatnow.gif&no_url= http://www.sunnyscript.com/leavemsg.gif"></a>

Usage note: Use additional HTML tags to achieve a custom layout (e.g. banner dimensions, borders, ...).

Expert note: It is possible to display the chat link and "availability banner" separately from each other by using the concerned URL from the above scheme.
 

FAQ and KnowledgeBase are accessible at the main menu of admin / staff panel as well as through the user lounge (depending upon the permissions of the staff member profile you are logged in with).

More information about system tables is available at "Manage system tables - ..." parts below.

Important note: Since MessageSuite uses special fuzzy logic algorithm for search operations, it is essential to understand the difference between FAQ and KnowledgeBase to achieve best-matching results.

Frequently asked questions (FAQ):

This table contains all frequently asked questions (FAQ) entered via the admin panel or staff panel.

Guidelines for adding FAQ entries:

A FAQ entry should answer often asked questions (e.g. "How to turn power on ?") in a short and precise way (e.g. "Push the red button."). It is not the place for specific in-depth questions (see KnowledgeBase instead of).

New entries should be written in a short language using many technical terms related to the specific theme by experienced staff members having sufficient knowledge.

Original sentence: "You should try to measure the temperature: If it goes over 50°, this is okay. But should it ever exceed 75°, then turn the blue device off immediately and control the pressure shown on the yellow liquid crystal display."

Shortened FAQ sentence: "If temperature goes over 75°, turn off the blue device and control pressure on the yellow LCD."

Usage note: The more time you spend on the FAQ, the more you are able to reduce incoming "dummy" questions.

KnowledgeBase:

This table contains all KnowledgeBase ("knowledge database") articles entered via the admin panel or staff panel.

Guidelines for adding KnowledgeBase articles:

While FAQs are short text parts answering most important questions, KnowledgeBase articles are normally longer and more comprehensive. It is suited for detailed step-by-step instructions, background details and special experts-only information.

Usage note: The more time you spend on the KnowledgeBase, the more you are able to reduce complex inquiries.
 

Here you can select the desired time period (date range, months or years) as well as the following report types:
 

Technical note: Depending upon your system settings, the available time period of statistics may be limited.

The system statistics is an essential tool to track your staff members' activities and to prevent particular staff members getting overtaxed by workload while others have free capacities (in such a case, change staff members' topic priorities).
 

You can send out mailings either to all record owners of a selected table (recipients filter set to "Send to all") or just mail such people who have allowed you to do so (recipients filter set to "Send to subscribed users only").

Mark "Do not send duplicate e-mails" in order to send only one single mail, even a particular address is found multiple times.

Custom recipients filter:

You