Documentation "Avia Support Pro" Extension Plugin

Content:

Content
General Information
Multiple Moderator Features
- Topic assignment to moderators
- Topics currently open by moderators
Support Request Queue Table filters
Notes for topic and replies
Plugin Internal Data and Datatables
Activity Tracking and Sessions
Extended Statistics
- Response Time Statistics
- Online Time Statistics
Activation, Setup, Deactivation, Uninstall
Plugin options
Developer Section

General Information:

This plugin is an extension to the "Avia Support"-Plugin (and bbPress) and adds the following features:

Moderator – Backend:

Auto assign a topic to a moderator who answered this topic
Support for multiple moderators to be assigned to a topic
Extended information which moderators are currently working on a topic (= have the topic open)
Several filters for the support request queue table topics
Add notes individually to a topic or reply (private or visible to other moderators)
Activity tracking for moderators to get online time information
Extended statistics (response times for topics and replies, moderator online time)

Multiple Moderator Features

These features help to improve the work in a team of moderators.

Topic assignment to moderators

A topic can be assigned to one or more moderators to mark attention to that topic. The name of the assigned moderators are shown below the topic title. For a moderator it is possible to filter the support request queue table for topics, he has been assigned to.

Topics can be assigned by:

Auto assign topics: An option field allows to automatically assign a topic to:
- the first moderator who answers a topic
- to all moderators who answer a topic
Manual assign topics: There is a checkbox list of all moderators and keymasters in the sidebar of an open topic. Changing the selection immediatly updates the moderator assignment info in the support request queue table of the moderator changing the assignment, for the others it is updated time-delayed with the topic state icons update

Topics currently open by moderators

The base version offers an icon showing when a topic is currently open by another moderator. This is replaced by the gravatar of the moderator, who has the topic opened. If multiple moderators have opened the same topic, there is a "+" beside the gravatar.

Hovering over the gravatar shows a popup with the name(s) of the moderators who have the topic opened.

To reduce intensive server and database trafic there is a time-delay in updating this information.

Support Request Queue Table filters

The first tab in the support request queue page is extended with a dropdown menu and adds the following filter functions:

All open topics: default, shows all open topics
Unassigned open topics: Topics, that are not assigned to a moderator yet
Topics assigned to me: Returns a list of all "Open topics assigned to me" and "Replied topics assigned to me"
Open Topics I replied to: Topics, where I had answered already

Notes for topic and replies

Moderators may add one or more notes to a topic or reply.

Notes can be visible to (checkbox left of submit button):

all moderators
to creator only (= "Private note")

In the dropdown menu in the right corner of a topic or reply you find a menu "Add a new note".

This opens an editor similar to the topic or reply editor. Canned textblocks, pure HTML and codesnippets are supported.

Multiple notes to a topic or reply are possible and are ordered by date ascending.

The right corner of a note has a dropdown menu with several functions like edit, trash, …..

Currently notes are limited to the backend and to the support request queue (and therefore for moderators only). Future versions may extend it to the frontend.

Plugin Internal Data and Datatables

This plugin extends the base plugin "Avia Support" and must extend a datatable of the base plugin and needs additional SQL datatables.

These structures have to be indexed once when activating the plugin and are maintained by the plugin continuously. See base plugin for more information about manual update feature.

Warning: There is a limitation on rebuilding the sessions !

Activity Tracking and Sessions

General

This feature helps to get more information about user activity in the forum.

Currently it is limited to backend and moderator activity on the support request queue page. In future releases it can be extended to all users and both frontend and backend pages.

Options allow to configure the plugin depending on the amount of traffic in the forum.

Activity

A user is "active", when he makes predefined actions on a page that show, that he is online AND working in the forum. Only being online is NOT active.

Each activity is logged as an entry in the SQL datatable "{$wpdb_prefix} avia_activity_log" with a timestamp. These entries are the base for later evaluation of user activity in sessions. To speed up response time we only insert the records in the datatable and return immediately without any further actions.

Activity Tracking on Support Request Queue Page

On the support request queue page we monitor the following actions (comprehensive to give an idea – closer details about all defined events you can find in avia-support-proclassesclass-avia-support-events.php):

Open a Support Request Queue Page (new or with a single topic page)
Open a topicline (if not already preloaded)
Submit a reply to a topic
Actions like Edit, Reload, Trash, ….. topic/reply
Add/edit/delete a note to a topic/reply
Toggle topic moderation
Pagination (for topics, replies, search results)
Apply a topic filter
Search in forum with Support Request Queue Page search function
Assign/remove moderators to/from a topic

Keyboard tracking on Support Request Queue Page

The following events are monitored as keyboard activity events ("srq_page_user_activity_tracking") on the Support Request Queue Page:

KeyUp
Click
MouseMove

Keyboard activity events are sent with ajax calls to the server. To limit the number of ajax calls (and event entries in database) to a reasonable amount the following logic is applied (see options to cofigure to your needs):

Triggered events by js code are ignored (= no user activity)
Only mousemoves are ignored (= no user activity)
User activity = (keyup) or (keyup and click) or (keyup and click and mousemove)
There is a defined period of time to pass before sending the next ajax call to save a keyboard event
Typing long text WITHOUT mousemove (= KeyUp only) will send an ajax call to save a keyboard event after a given number of keyups regardless of time passed
There is a keyboard inactivity timeout (= time to pass without recieving a monitored event = user is not working but the window is open). When recieving the next monitored event (= user returns and starts working again) both the last timestamp and the current timestamp are sent as activity events

Sessions

A session is a continuous period of time, where a user (currently only a moderator) is working in the forum.

We use the datatable "{$wpdb_prefix} avia_activity_log" to build the sessions and save them in the datatable "{$wpdb_prefix} avia_sessions". Each session is an own record in the datatable. Sessions are built on a daily bases (00:00:00 – 23:59:59), a user can have several sessions per day.

There is an option "session expire time". When this period of time is passed without recieving a user activity, we assume the user has stopped working with the last activity time.

The following rules are applied to build the sessions for a user:

A new session starts with the first activity log entry and end time is set to start time (= length 0)
If the next activity log entry is within "session expire time"(= end time + session expire time > activity log time), the session is extended to that timestamp (= end time is changed to activity log time)
If the next activity log entry is after "session expire time"(= end time + session expire time < activity log time) we start a new session with activity log time (previous session was "closed" implicitly with the last set activity log time)
If a session passes midnight, we close the last session at 23:59:59 and start a new one at 00:00:00
Continue at step 2.)

Building the sessions is implemented as a background task. Whenever an admin page is open, an ajax call starts this background task in a loop (integrated logic avoids multiple processes running at a time if more users are working in backend). You have several options to configure the behaviour depending on forum size.

Limitation on rebuilding sessions

Activity tracking might produce a large amount of entries in the activity log table depending on the number of moderators and their activity.

Deleting old entries is the only way to keep the size of this table in a reasonable size (currently not implemented yet). But this makes it impossible to reconstruct the sessions.

There is a workaround implemeted to simulate missing activity log entries, which you can also use if you have an already existing forum and want to go back with the sessions in the past:

topics or replies with publish time in a session are assumed to be processed correctly and can be skipped
Option "Simulate User Activity Time" defines an average period of time you allow a moderator to answer a topic (e.g. 20 minutes)
For all not skipped topics or replies from 1.) you add 2 activity log entries (publish time and (publish time – Simulate User Activity Time) )

Extended Statistics

The forum statistics dashboard (opened with the submenulink "Statistics" in "Avia Support") is extended with 2 tabs and additional filters:

Response Time Statistics

Topics Response Times
Replies Response Times Overview
Detailed Report on Topics and Replies Response Times

Online Time Statistics

Total Online Time
Average Daily Online Time
Detailed Report on Online Times

Activation, Setup, Deactivation, Uninstall

This plugin is based on the plugin "Avia Support" (which depends on bbPress). Both plugins must be activated.
We recommend to avoid the bulk features of WP on the plugin page with these plugins. Use plugin specific operations instead and use the following order:

Activating the plugin and Setup:

We describe the steps for a complete new setup of all plugins (steps can be skipped if the base plugins are already running).

Install and activate bbPress
Setup the bbPress moderators
Install and activate plugin "Avia Support"
Install and activate this plugin "Avia Support Pro" (it is safe and recommended to activate this plugin before performing the setup process of "Avia Support" to speed up building plugin specific SQL datatables especially in large databases)
If you are using other extension plugins check, when it is safe to install and activate these plugins
Follow steps for activating base plugin (see documentation)
In the admin notice field area you find a message to setup plugin internal data and datatables for "Avia Support Pro" plugin. Click button "Start setup process now" and wait for the finished update message – do not reload the page as this will stop the process.
If interrupted (e.g. loss of internet connection) after page reload you get a message and can continue or restart. For more information see Manual Update Feature in base plugin.
Open the settings page for the base plugin, read section Plugin options and following sections to get familiar with the options of this plugin
Check all the options and and make your changes – do not forget to press "Save" when finished
Start "Activity Data Simulation" – you may do that later whenever you want
If you are using other extension plugins not already activated, activate them now and check for manual update in the admin notice field area

Deactivating the plugin:

Dectivate this plugins
Dectivate all other depending plugins, if you want to deactivate Avia Support
Dectivate Avia Support
Dectivate bbPress

Deleting the plugin:

Delete this plugins
Delete all other depending plugins, if you want to delete Avia Support
Delete Avia Support
Delete bbPress

Plugin options

Plugin options are added to the base plugin "Settings" page.

General Settings Tab

The following options are added to the base plugin on this tab below headline "Avia Support Pro Extension Plugin":

Auto assign moderator:

Do not assign:	Do not auto assign any moderator to a topic being answered
Assign only to first:	Assign the first moderator to a topic, who answers the topic or a reply
Assign to all:	Assign all moderator to a topic, that answers the topic or a reply

Calculate Statistics:

The statistics table of the base plugin is extended with additional columns for the reply time statistics.

At the moment you have to click this button after activating the plugin, will be replaced by a one click activation “Start setup process now”. Depending on the amount of topics and replies in an existing forum this can be a lengthly operation. So please be patient.
After that the table content is maintained by the plugin, when a new topic is inserted or a reply is added
You can click this button any time to rebuild the table manually, if you have the feeling, that the results are incorrect. Keep in mind: Depending on the amount of topics and replies this can be a lengthly operation. So please be patient

Clean Up Tab

The following options are added to the base plugin on this tab below headline "Avia Support Pro Extension Plugin":

Deactivation:	Leave unchecked in production environment !! When checked, all objects checked in section "Remove Objects" will be deleted permanently when deactivating the plugin. This is usefull for a testsite if you want to reset the database and do not want to uninstall the plugin.
Uninstall Clean Up:	When checked, all objects checked in section "Remove Objects" will be deleted permanently when uninstalling the plugin. This is usefull to keep objects in case you want to install the plugin later.
Remove Objects:	Select all objects to be removed permanently from database.

Activity Management Tab

These options configure the behaviour for activity and session handling. Depending on the size of the forum, the time you allow a moderator to answer a topic and how near to realtime you want to have your statistics you have to vary the values.

Activate Tracking:

This is a multiple select box (use Ctrl-key and Shift-key to select multile entries)

No Activity Tracking:	Stops tracking – keep in mind, that this will break the consistency of your activity log and lead to wrong results in statistics (currently only the session statistics)
Activity Tracking SRQ Page Backend:	Activate tracking on the support request queue page in backend (for moderators only)
–	…… more selections may follow in future releases

Log Session Processing:

This option is only intended to check the function of the ajax callbacks, as it produces entries in the event log of this plugin (which are added to the posts table).

Never:	This should be the standard setting for this option
Only information about processed entries:	Only information about processed entries are added to the plugin event log
Also log information when no entries found	All ajax calls (even when there are no unprocessed activity entries) are added to the plugin event log. This will produce many entries. Only use this for error tracking and as short as possible.

Activity Log Options

Clientside Activity Log Evaluation:	This is the interval in minutes, the client sends an ajax request to the server to start a check for evaluation of the activity log. Currently this updates and extends the sessions for a user. This is sent by every open page in the admin area. Default is 5 minutes (recommended for large forums). A smaller value leads to more realtime for the sessions but also to more server traffic.
Delay Clientside Activity Log Evaluation on pageload:	This is the delay for the first ajax call after a pageload in admin area. Default is 5 minutes (recommended for large forums). Select a smaller value in a small forum and if online time in admin area is not long enough to allow processing all open activity entries (keep an eye on the information in the admin notice area)

Session Log Options:

Session Log Calculation Interval:	When multiple moderators or other users are active in backend each page sends update requests for the activity log. This parameter is the time to ignore those requests for sessions since the last update. Only when this time is passed, a new complete scan of the activity log for new session concerned entries is done. Default is 5 minutes (recommended for large forums). Select a smaller value in small forums to be more realtime.
Session Expire Time:	When no activity for a user was found within that period since last activity entry, it is assumed that user is inactive and the previous session is regarded as closed and a new session is started. Default is 20 minutes. Adjust this value to how many minutes you allow a user to be inactive
Nr. of Session Activity Entries:	Number of activity log session entries to be processed in an ajax call. If topics remain unprocessed, the next ajax call is performed immediately after return. Default is 50. Keep in mind server timeout problems when enlarging this value.
Forced unlock of session lock:	Calculating sessions is limited to one task at a time – to avoid multiple tasks running there is a lock flag set which is cleared when the task is finished. This option is a fallback only, when this flag had not been cleared by normal workflow (maybe an error occured, ….). Default is 20 minutes.

Support Request Queue Page related Options:

Keyboard Activity Interval:

Time to pass before sending an ajax call about user keyboard activity for adding to activity log. User activity is defined by a combination of mousemoves, key actions and clicks. Default is 5 minutes.

This option has to be seen in relation to option "Session Expire Time": the larger "Session Expire Time", the larger this option can be.

Keyboard Inactive Timeout:

Time to pass since last keyboard activity to recognize user inactivity. Activity is a combination of mousemoves, key actions and clicks. When a timeout is recognised, an activity message with the time of the last key action or click is sent to the server, a new keyboard activity period starts and an activity message with the time of the new keyboard activity is also sent to the server. Default is 15 minutes.

This option has to be seen in relation to option "Session Expire Time": the larger "Session Expire Time", the larger this option can be.

Minimum Key Only Characters:

If user types a long text without any mousemove this might run into "Keyboard Inactive Timeout". To avoid this, typing this number of characters is recognised as an active sequence and we send an activity message to the server. Default is 300.

This option has to be seen in relation to option "Keyboard Inactive Timeout":

Activity Data Simulation Options:

Simulate User Activity Time:

Simulating user work on a topic or reply outside an existing session we create two activity log entries: Start time with (publish time – Simulate User Activity Time) and end time with publish time. Default is 20 minutes.

This option has to be seen in relation to option "Session Expire Time":

Session Simulation:

Button "Check for Simulation of User Activity" performs a check for moderator created topics and replies outside existing sessions and returns the number found.

Button "Start Simulation of User Activity" inserts the two simulated activity log entries using "Simulate User Activity Time" for each moderator topic/reply outside a session

Currently all topics and replies are checked – that means you rebuild the sessions for the complete forum.

Developer Section

This section contains useful inside code information.

Options:

Options for this plugin are stored in associative arrays. To avoid calls to isset, to ensure startup default values and to make customization easier loading the options are handled in functions, where it is possible to filter the option array and values on loading the options:

class Avia_Support_Pro::get_options_default

Most of the options are "hidden options", that cannot be accessed via the settings page. They are intended for future use when extending the functions of this plugin to frontend.

Documentation “Avia Support Pro” Extension Plugin