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 can specify a search query that filters only recipients matching particular criteria. It is possible to use any field available in the table this mailing is intended for. Click on "view filter results" to get a listing of all selected records.

For example: income>=3000 AND education="high"
Only recipients will receive this mailing which have an income of more than 3000 currency units and a "high" education level.

Usage note: For more details about how to perform search operations, please refer to "Searching of databases (tables)" below.

Personalized mailings:

Personalized mailings contain an individual "To:" field for each recipient. In addition, you can include fields from the concerned table  (format: <!--$FIELDNAME-->) which are replaced by appropriate content.
 

Sample personalized mailing:
 

Dear <!--$first_name--> <!--$last_name-->, you recently added your website <!--$URL--> to our database. If you would like to increase the popularity of your <!--$BUSINESSTYPE--> company, you should take a closer look at our valuable offers ! With kind regards, John Smith (my sample company).

Technical note: If "Do not send duplicate e-mails" is marked, a recipient with multiple records receives mail for the first found record only (and so will just see content of table fields for this specific record).

Quick mailings:

Quick mailings are used to send identical messages to all recipients (faster processing). However the usage of personalized elements is not possible (included table tags are removed automatically).
 

Intelligent mail content delivery:

The most powerful feature is the delivery of intelligent message parts based on a record's content and "if/then/else" conditions. So a mailing can be written absolutely targeted, which leads to higher response rates and increased user convenience.

Important note: This works only with "Personalized" mailing method. "Quick" mailings will ignore intelligent message parts.

Each "intelligent message part" has the following structure:
 

<!--if <expression>--> Message delivered when <expression> is true. <!--else--> Message delivered when <expression> is false. <!--endif-->

Usage notes: "if" and "endif" tags are required, while the "else" part is optional. Recurrent tags may also be used.

<expression> can contain these operators:
 

Format of field values: $fieldname (field names are handled case-sensitive).

Sample applications (non-recurrent tags):
 

<!--if $gender eq "m"--> Ties for 5 Euro only. Just a limited time, buy now ! <!--else--> Parfums starting at 10 Euro. <!--endif--> <!--if $income < 20000 AND $intelligence_quotient <= 30--> Hi <$name>, participate in our "get rich fast" special offers ! This is your chance to live like the <rich & beautiful>. <b><i>So start acting now - start today.</b></i> <!--endif--> <!--if $index * 10 / $basetax + 0.03 == 2 AND $taxstatus eq "high"--> Save taxes by ordering our book "1001 (il)legal tax tricks". <!--else--> Increase your income by ordering our book "1001 ways to get wealthy". <!--endif-->

Usage notes: Second sample does not have an "else" tag, which means that a false result will lead into not displaying anything. Should a field value be unavailable (spelling error, non-existing field), then the argument is considered as being empty.

Technical note: It is also possible to use HTML and client-sided scripts (like JavaScript) within intelligent message parts.

Sample application (recurrent tags):
 

<!--if $gender eq "m"--> Special offer for <b>men</b> from our drug store: <!--if $age > 50--> Gray hair remover for just 9,99 Euro. <!--else--> Shaving foam - just 3,99 Euro. <!--endif--> <!--else--> Special offer for <b>women</b> from our drug store: <!--if $age > 50--> Wrinkle remover for just 9,99 Euro. <!--else--> Lavender bath salt - just 3,99 Euro. <!--endif--> <!--endif-->

Usage notes: Parts in green text belonging together. Do not forget to close all "if" tags avoiding malfunctions.

How to perform a test of personalized and intelligent mailings:

In order to let the system process a sample message, click on the button "Send test message to admin". The system then generates a mailing, which is sent to the administrator under real life conditions.

And these default values are used: Numerical = 0; date/time related fields = actual date/time; URLs = http://test.<fieldname>/; e-mail addresses = test@<fieldname>.test; fields in general = test-<fieldname>.

Smart tip: Have a look at MailingStar (plus) - professional mailing list management and e-mail marketing software.
 

The system tables contain system related data, like registered user and staff profiles, FAQ and KnowledgeBase articles as well as case databases. All system tables can be searched and modified according their specific applications.

You can access the system tables from the main admin menu. For each table, different selections are available.

Usage note: All modifications made to these tables takes immediately effect to the user lounge. Since most of these actions cannot be recovered, please be careful when altering data.

Restructure system tables, table parameters and layout:

Please refer to the next part of this chapter for general information about modifying table parameters or read below to find table specific information (e.g. managing records, permission handling).

Table of registered users:

This table holds all information about registered users. You can add users through the admin / staff panel and people can also subscribe via the user lounge:

When browsing this table, click on "Add" in the upper right corner of the screen to create a new user profile or select the desired profile to edit or delete and then click on the appropriate link (also available in the upper right corner).
 

Set table permissions / Moderation:

You can make this table moderated (MessageSuite asks for acknowledgement before adding new profiles or modifying existing ones) as well as set special permissions. In order to do so, go to the screen "Table parameters & layout", part "Permissions":
 

In addition, MessageSuite can send an e-mail notification as soon as there are records in moderation queue. This is done also on the screen "Table parameters and layout", part "Behavior" (refer to the next part of this chapter for details).

In order to moderate actions, click on "Moderate users actions" available on main admin menu.

Technical note: If you wish to modify records that are currently in moderation queue, mark the button "Remind to update" when approving these records. On the moderation result screen, you can edit them right away (new browser window opens).

Table of staff members:

This table contains all registered staff members allowed to access the staff panel (special kind of admin panel) working on cases, doing chat sessions and other tasks.

Staff member profiles are allowed to be created by the admin only (via admin panel).

Add / Update / Delete profiles:

When browsing this table, click on "Add" in the upper right corner of the screen to create a new staff profile or select the desired profile to edit or delete and then click on the appropriate link (also available in the upper right corner).
 

* These details may be visible on the user lounge.

Set table permissions / Moderation:

You can make this table moderated as well as set special permissions. In order to do so, go to the screen "Table parameters and layout", part "Permissions of logged in members":
 

In addition, MessageSuite can send an e-mail notification as soon as there are records in moderation queue. This is done also on the screen "Table parameters and layout", part "Behavior" (refer to the next part of this chapter for details).

In order to moderate actions, click on "Moderate member updates" available on main admin menu.

Table of cases:

This table contains all existing cases on the system. Messages belonging to a case are stored in a separate database.

Technical note: Although possible, the admin panel is not suited to work on cases; please use the staff panel instead of.

Add / Update / Delete cases:

Normally this table is managed by the software (new cases created when importing e-mails or web form submissions), but if you do also offline communication (e.g. via phone and fax), you can create a case also via the admin / staff panel.

When browsing this table, click on "Add" in the upper right corner of the screen to create a new message or select the desired message to edit or delete and then click on the appropriate link (also available in the upper right corner).
 

Table of messages:

This table contains all messages (e-mail, user lounge, chat and offline) connected to cases available on the system.

Technical note: Although possible, the admin panel is not suited to work on messages; please use the staff panel instead of.

Add / Update / Delete messages:

Normally this table is managed by the software, but if you do also offline communication (e.g. via phone and fax), you can create messages also by using the admin / staff panel.

When browsing this table, click on "Add" in the upper right corner of the screen to create a new message or select the desired message to edit or delete and then click on the appropriate link (also available in the upper right corner).

Technical note: Each message has to belong to an already created case.
 

FAQ and KnowledgeBase tables:

Please refer above within this chapter for information about these tables.
 

The following information contains details about how to modify the system tables. As an experienced user, you can modify MessageSuite's system behavior according your wishes.

However please note that once modifications were made, they cannot be recovered. In worst case, you have to re-install the software with the risk of losing existing user and staff member profiles as well as other data.

Important note: Before you touch the system tables, ensure that you are familiar with MessageSuite.

Restructure system table:

Click on "Restructure" of the desired system table. Alternatively you can use the "Restructure" link in the upper right corner of the screen appearing when you are inside of a system table (browse its content).

How to add a new or edit an existing field:

Go to "New field name", type in the desired name, select the data type and click on "Create new field". Otherwise look for the field you wish to modify and click either on "Edit" or the field name. Now the screen "Field properties" appears:
 

Important notes: If you edit a system field (all system fields starts with an underline character), some of the settings above may be not available for selection. Don't touch pre-filled settings for system fields; you may negatively affect their behavior.

How to change sorting of fields:

Look for the field you wish to move around and click on either "move up" or "move down" to change the its position. This action takes effect to the admin panel and to the dynamically generated user lounge templates (except mail templates).

How to delete a field (use with care only):

Look for the field you wish to remove from the table and click on "Delete". However, please note that once a field is removed, all related content will get lost and cannot be recovered.

By the way: All table parameters are automatically updated and the concerned field becomes removed from these settings.

Empty table:

Just select the desired options and click on the "Clear data" button in order to clear the concerned table. Please note that once a table (or part of it) is cleared, all related content will get lost and cannot be recovered.

Important note: Since all entries of concerned table may get lost, this option should be used with care (e.g. clearing table from test entries before starting to run the system officially).

Table layout parameters:

On the "Restructure" screen of concerned system table, there is a button named with "Edit table parameters" which leads you to the table layout parameters screen.

Usage note: The shown table parameters may not be available for all system tables.
 

* These are required (and important) fields; double-check them for containing correct values.

Search layout parameters:
 

* These are required (and important) fields; double-check them for correct values.

Behavior:
 

Permissions:

These parameters are specific to some system tables; please refer to the parts above within this chapter for more information.

Menu layout:
 

Database script pages headers / Login script page headers:

Customize the headlines of generated pages; also usage of images (IMG tags according HTML) is allowed.

Table modifications logging:

Check this button in order to log all table modifications (add, update and delete records) to TABLENAME.modif.log located in the "data" directory (TABLENAME is replaced with the name of the concerned table).

In this way, you are able to manually recover lost data or track IP addresses of users trying to cheat your system.

Technical notes: Content of memo / image / binary field types is not logged.

Table automatic maintenance:
 

Data file backing up:

What exactly is backup generation ?

MessageSuite is able to generate backups of its data files automatically to allow restoring them later. Generated backup files (extension .db.bak) are located within the "data" directory.

Pre-requisites for generating backups:

Maintenance interval: Ensure that a maintenance interval is specified. See screen "Table parameters", "Table automatic maintenance". Recommended range: 3600 to 43200 seconds (1 to 12 hours).

Important note: The backup update period must be longer than the specified maintenance interval.

Enable / disable backup generation:
 

Technical notes: In order to disable the backup feature, set "Number of backup files" to 0 or leave it empty. New backups are not generated for unchanged files (since backup already exists).

Recommended backup settings:

Maintenance interval = 3600; number of backup files = 4; backup file #1 update period = 6
Rename backup file #1 to #2 after this number of updates of backup file #1: 4
Rename backup file #2 to #3 after this number of updates of backup file #2: 5
Rename backup file #3 to #4 after this number of updates of backup file #3: 6

<TABLENAME>.db.bak1 holds 0 to 6 hours old database content.
<TABLENAME>.db.bak2 holds 6 to 24 hours old database content.
<TABLENAME>.db.bak3 holds 1 to 5 days old database content.
<TABLENAME>.db.bak4 holds 5 to 30 days old database content.

<TABLENAME>: Name of the table, concerned backup file belongs to.

Retrieve data from backup:

If you wish to roll-back a corrupted data file, just replace the original file with the latest error-free backup copy.

Before doing so, please ensure that the table definition did not change recently (e.g. by adding new fields). In this case, the table definition needs to be set to the configuration of the data file to restore.

Important note: Restoring data files should be managed by an experienced system administrator only. In case of emergency, SunnyScript can provide you with special assistance to professionally handle this task (optional fee-based service).

Helpful hint: In order to create a backup of an entire database, you may use the "Download/upload table package" feature.

"Password reminder" utility (system tables of "users" and "members"):

If a user or staff member forgot the password to access the user lounge or staff panel, it can be re-send automatically by the system at request.
 

Important note: Since the admin password is saved encrypted for higher security, it cannot be restored. See chapter "Helpful hints and technical reference" about information on how to reset the admin password.

Templates substitution:

If you wish to use your own templates instead of the pre-defined ones, please select your desired templates here (more details about templates are available in the next chapter). "--use default--" will activate the standard template for concerned output.

Helpful hint: If you're unable to find your recently created templates within the lists, hold CTRL or SHIFT key and click on the "Reload" button of your browser software to reload the browser window (to replace an old copy in cache).
 

Import data into database:

Click at the button "Start data import..." to begin reading in an existing 3rd-party database.
 

Click on the button "Import data" to start the importing process. After it is finished successfully, please check the read in data for consistency first. It is also recommended to keep a backup copy of all original database files for later references.

Technical note: Data formats "... with field names" requires that the first line of the importable file holds the names of the fields. Alternatively, default names are chosen you can rename later at any time.

Importing already uploaded source files:

This feature is useful especially when trying to import huge databases, because the file size allowed to read in through the admin panel may be limited by your server or webbrowsing software...

Just place the source file into the directory data/import.tmp. Now go to the admin panel, click on "Import / export data" and select the concerned file from the list (see parameter "Determine data file being uploaded").

Export data from database:

Select the appropriate source table and click on "Continue..." to go to the next screen.
 

Now click on "Export data" to start the exporting process. A "save file" dialog is shown by your web browsing software to store the exported data file on your computer.

Advantages of the "EasyData exchange format":

The "EasyData exchange format" is a tab-delimited text-based format also storing binary field content, like images or software files together with the textual data (URL-encoded).

Where possible, this format should be used for data import and export tasks to ensure best results when handling non-textual contents (all other supported formats cannot handle binary fields).

Technical note: If you are a programmer interested in implementing our exchange format into your own applications, please let us know. We are able to provide you with additional information upon request.

Helpful hint: Should you wish to manually back up an entire database or to carry an existing one over to an other MessageSuite installation, you may decide to create a "table package" as described more closer in the following.

Table packages - overview:

A table package contains an entire database (the table and all related elements) in one single file (TABLENAME.ede). So table packages are ideally suited for carrying an entire database to an other server or for generating manual backups.

Download table package:
 

Now click on "Download table" to save the table package. A "save file" dialog is shown by your web browsing software.

Upload table package:
 

Now click on "Upload table" to copy the table package to the server.

Technical note 1: Should there already exist a table with equal name, MessageSuite chooses a new name for the uploaded table (may be changed later at "Restructure table" screen).

Technical note 2: The choices "Use internal GZIP compression" respectively "Use internal GZIP decompression" for table package down- and uploads are only available, if there is the Perl module "Compress::Zlib" installed.
 

How to access the user lounge:
 

Usage note: Some actions may not be available depending upon the set system behavior.

How to search FAQ and KnowledgeBase:
 

Click on the button "Search" in order to send your request to the system.

How to post an inquiry:

Select the appropriate radiobutton or click on the link "Post inquiry" available in the top menu line of the screen.

The following procedure is spread over two screens and allows creation of a new case, searching the FAQ and KnowledgeBase or opening a topic specific chat session.
 

Click on the button "Continue" after all fields are filled in.

Depending upon user's selection, found search results in FAQ and KnowledgeBase databases appears first (done by using fuzzy logic search algorithms based upon inquiry details).

If the user's question could not be answered by the FAQ and KnowledgeBase search results, then the inquiry can be posted to the staff (a preferred staff member may be selected depending upon system settings).

If a staff member is available for chat (chat listener active), then the customer can start the chat session and may be also able to select the desired staff member to talk with (depending upon system settings).
 

By default, a standard template scheme is used. It's the ideal basis to create your own templates or modify the existing ones. More detailed information will follow later in this chapter. You have two choices of modifying the lounge templates:

1. Modify color and font schemes only:

You may adjust the color and font schemes to achieve a similar layout as the one of your business website...

Go to the admin menu, click on the button "Edit templates" and search for "main template" labelled entries. These contains various layout settings taking effect to all sub-templates connected with the concerned main template.

2. Full set of freely configurable templates:

Beside of just customizing color and font schemes with style sheet commands, you can create your own set of templates or re-write the standard ones (they are a good basis for your own templates).

Each template is written in HTML and contains special tags which will be replaced by appropriate content. There's nothing you cannot customize, however you should have a familiar understanding of MessageSuite and HTML programming.
 

There are three kinds of templates: Main templates contain the master layout; sub-templates hold the layout of output blocks appearing in these main templates; independent templates stand alone.

A detailed list with comprehensive descriptions of all template files is available from the admin panel (see "Templates editor" screen). Please contact our customer service for pre-sale inquiries asking for this list.

Helpful hints: If you create your own template sets, start creating the main templates first to have a better overview. After each single template is ready, run a test-drive to check correct functionality.

Important note: We strongly recommend to keep backup copies of the original template files for later referencing purposes.

Expert note: Some mail templates may be also modified using the screen "Edit MessageSuite parameters". Simply click on the link available near each template label to open a new pop-up browser window containing all required details.

Location of templates:

All template files are physically located in the templates directory you specified during installation of MessageSuite.

As long as you create or modify templates using the admin panel, you don't have to care about. However if you create templates manually, you must copy them to this location, because MessageSuite only recognizes files in this directory as templates.
 

For some advanced functions, Perl code is used on the templates together with internal script variables. You may just surround these codes with additional HTML tags or modify them as desired (suggested only if you are familiar with Perl).

Important notes: Some tags are specific for selected templates. If you add a tag to a template which cannot use it, concerned tag will be simply ignored. However a missing tag can cause that users are not able to get access to selected features.

If you wish to customize templates, go to the admin menu and click on the button "Edit templates".

List of tags and Perl script variables you can use on templates:

A detailed list with comprehensive descriptions of all valid variables and tags is available from the admin panel (see "Templates editor" screen). Please contact our customer service for pre-sale inquiries asking for this list.

Expert note: Common script variables available in all templates are $in{<form_var>}, which gives access to form variables submitted by the user (<form_var>) and $namespace->{'TAG'}, which offers access to special tag variables.

Custom software solutions:

Contact our sales department to request a free quote for our individual programming and customization services. Our team of experienced programmers and website designers looks forward to take over your project at affordable rates.
 

In order to manage this task with highest possible compatibility to different server systems, MessageSuite uses "fork" function to prevent killing of resource consuming processes by running clone processes with other PID (process identification).

So the allowed CPU time on your server isn't exceeded, but MessageSuite can manage all tasks without disruptions. In this way, you don't have to take care about deep technical details of your server configuration.

However sometimes "fork" function is not available (this is detected automatically when running the admin panel first time, see "System parameters" screen). In this case, please refer to the chapter "System implementation" ("Data maintenance" of "Edit MessageSuite parameters" screen) for more details about how to workaround this problem.
 

MessageSuite is a versatile mail management software which can not just handle support requests and any kind of pre-sale inquiries coming from (potential) customers, but also the following special tasks.

Project related communication:

All members participating in a project receive own user profiles. In order to prevent unauthorized people logging in, you should disable "User can post request without registration" (see "Edit MessageSuite parameters") and disallow anonymous users to create profiles (see "Table parameters and layout" of registered users table).

In this way, the user lounge is fully password protected to allow only certain users access to the information listed there.

Time-based support services:

By requiring people to register first, you can also provide time-based support. Each registered user profile gets a time stamp, so you (the admin) can easily remove expired profiles (let sort records in registered users table by this "lifetime" field).

Mail management:

Let MessageSuite handle all e-mail addresses belonging to your company or e-business: Create a topic category for each e-mail address and give only permitted persons (staff members) access to it (the same people normally receiving the mails).
 

MessageSuite provides a wide range of powerful search features to retrieve information from your stored data fast and accurate. In the following, we want to show how to built search operations in an effective way.

Let's first have a look at these two records used to explain the sample operations below:
 

id: 1 firstname: John lastname: Smith age: 27 postcode: 12345 city: Samplecity country: Somewhere

id: 2 firstname: Max lastname: Smith age: 12 postcode: 02345 city: Samplecity country: Somewhere

Usage note: All samples don't consider special features like searchable fields, whole word or case-sensitive search operations. They just refer exclusively to their concerned explained features.

Interpreting keyword searches:

In most cases, you can use any text string for query fields in order to start searching a table.

Sample query: smith
Delivered records: 1, 2

Multiple keywords should be separated by spaces. MessageSuite automatically adds the logical operator AND unless an other one is specified (read below for details and additional explanations).

Sample query: john blanche
Delivered records: none ("john" is found in record 1, but "blanche" is not existing)

If you are not sure about the spelling of a word (e.g. singular/plural or different spelling alternatives), then just type in a partial word.  MessageSuite will perform a sub-string search for the provided string.

Sample query: some
Delivered records: 1, 2 (finds string "some" in values of field "country")

Boolean operators: AND (&) OR (|) NOT (!)

The logical operators AND, OR, NOT are supported. Instead of the words AND, OR and NOT you can also use the operator characters ampersand (&), pipe (|) and exclamation mark (!).

Sample query: john AND smith
Delivered records: 1

Sample query: john OR max
Delivered records: 1, 2

Sample query: john ! max
Delivered records: 1 ("!" stands for "NOT")

Technical note: At advanced searches you can specify a default operator.

Parentheses: ( )

Operations put within parentheses are processed first; the result is then used for further operations within the search string.

Sample query: (john NOT max) AND samplecity
Delivered records: 1 ("john NOT max" delivers record 1; then looks there for "samplecity"; both statements are true (AND))

Phrases: " "

Strings put within phrases are searched exactly as they are (not case-sensitive).

Sample query: "sample"
Delivered records: 1, 2 (finds "samplecity")

Sample query: "JOHN"
Delivered records: 1

Wildcards: * ? \

Beside of the standard sub-string search, it is possible to use more specific wildcards for automatically expanding a search operation. Wildcards marking variable parts of a string; they are helpful when looking for word variations and different spellings.

The asterisk (*) is considered as placeholder for none, one or more characters; the question mark (?) is considered as placeholder for exactly one character.

Place an escape character (\) before any symbol to disable its special meaning (e.g. a search for the string "book\*" will look for "book*" as it is written and does not consider the special meaning of the asterisk character).

Sample query: sample*
Delivered records: 1, 2 (would also find "sampletown", "samplevillage" or just "sample")

Sample query: ?2345
Delivered records: 1, 2 (but would not find "012345", since only one character is allowed being there).

Comparison operators: = == < > <= >= <> ~ !~ ~~

Within a search query you may address a specific record field being searched for a given string or numerical value.

Available operators:
 

= wildcard match (wildcard symbols allowed)	== exact match (disabled wildcard search, "as is")
< less than	> greater than
<= less or equal than	>= greater or equal than
<> or != not equal	~ contains text (default operator)
!~ does not contain text	~~ whole word match

Sample query: age <= 12
Delivered records: 2 (looks exactly at the field "age" and disregards other fields)

Technical note: When just entering a string, MessageSuite converts it into <searchable field> ~ <search string>. In case of using "whole word" match, the search string is converted into <searchable field> ~~ <search string>.

Priority of used operators:

When processing a search request, MessageSuite first handles all parentheses, then comparisons and finally any boolean operator found (in this priority: NOT, AND, OR).

Search options at "Advanced search" screen:

By clicking at the "Search" link in the upper left corner of the screen you will come to the advanced search area for the concerned active table. Beside of a standard search mask, also the following options are available:

Case-sensitive: Mark this button to handle search operations case-sensitive (CAPITAL and lowercase chars are differed).

Whole words: Mark this button to search for entire words only (recognizes space characters).

Match method: Select whether all arguments must be found (AND) or just one is sufficient to list a record (OR).

Sort by / then sort by: Define sorting of search results over two levels.

Fuzzy logic search algorithm:

FAQ and KnowledgeBase search operations can be also done by simply asking a question (e.g. "Who is SunnyScript ?") or generally while sending an enquiry. In order to deliver matching results, a special fuzzy logic search algorithm is used:

This system will give "points" to each string found in databases depending upon a weight factor scheme. In easy words, records with most points are displayed first while "not so relevant" ones are shown later in search results.

Since FAQ records are normally smaller than KnowledgeBase articles (less substance to search), matching strings in FAQ records have higher weight factors as KnowledgeBase ones.

In addition, the question part of FAQ records also has a higher weight factor than the FAQ answer (because they are very likely the subject to search); so it is very important that records added to the FAQ table consists of clear, situation-matching terms.
 

Message goes from user to staff:

1. The user sends a message to an e-mail address belonging to a registered POP3 (gateway) account.

2. MessageSuite downloads the mail from the gateway account and creates a new case (case ID is assigned to the message). The case and message are added to the system, responsible staff member receives a copy of the message (requires admin to enable "Forward incoming messages" as well as concerned preference settings in staff member profile).

Messages marked with "Highest" priority will lead that concerned staff member receives also a notification to the emergency e-mail address. So it is recommend to keep "Highest" priority only for certain user groups.

Message goes from staff to user:

A. The staff member uses its own e-mail client to answer mails ("Forward incoming messages" set to "Yes"):

1. The staff member replies to a user message. The reply is not directly sent to the user, but to a gateway account's e-mail address (as set in staff member profile). Under normal conditions, this doesn't take any attention of the staff member.

2. Message Suite imports the e-mail from the gateway account, looks for the case number and redirects the message via e-mail to the user (recipient mail address as assigned to the concerned case).

B. The staff member uses staff panel to answer inquiries:

1. The staff member writes the reply to an inquiry and sends it to MessageSuite.

2. MessageSuite will redirect the message to the user (recipient mail address as assigned to the concerned case) and automatically set the "From:" address part in mail header pointing to the concerned staff member's gateway e-mail address.

In this way, replies send back to the user are automatically taken over by MessageSuite.

Technical note: Even if "Forward incoming messages" is set to "Yes", staff can also still use the staff panel to work on cases.
 

Technically there is no limitation in the number of staff members working at the same time. Each logged in member (as well as logged in user) does not require CPU resources until actively working with the software (e.g. doing chat or sending a form).

Each open chat listener needs only few system resources (amount of used memory space and CPU time varies basing upon operating system and hardware configuration). Starting a chat session just takes inappreciable more resources.

So on a common system environment, you may never notice a loss of performance or speed. But please contact our customer service, if you have specific questions regarding this topic.
 

In order to translate system messages into your desired language, download the files *.en (located in the software directory), which holds all pre-defined text parts and load them into a text editor.

Each language file uses the same structure:

<Meaning or default text> => <Translation>

Please change only the part <Translation> while keeping the left-sided ones. After you finished translation, please upload the files to your server and give them a try.

Important note: You should create a backup copy of all original *.en for later reference.
 

Before you contact our customer service department, please read this manual first. In most cases you find the answer here. However if you still experience problems, we will be more than happy to help you...

For all support inquiries, please contact support@sunnyscript.com and provide the following information:

* The license number of the concerned product.
* A close description of the problem or question you have (no file attachments, please).
* For technical inquiries: Used server environment, URL of admin panel & admin password.