Getting started

HelpIM version 2

The most recent documentation on installing and configuring HelpIM v. 2 can be found here: http://www.helpim.org/browser/stable/setup/README

HelpIM version 3

The most recent documentation on installing and configuring HelpIM v. 3 can be found here: http://www.helpim.org/browser/HelpIM3/README.txt

Additional hints for configuring and administrating HelpIM 2

Status and Logging

HelpIM keeps track of the statuses of the clients and the staff-members in two tables of the database: staffstatus and clientstatus. Depending on the log level, changes to these statuses are also logged to the log file. The statuses can be changed by configuration (except for 'new'), but these statuses are commonly used:

Note: statuses marked with 'hash' are used fir clients, marked with 'jid' are used for staff.

  • new going to check closed, blocked and full (hash)
  • entry intake form is served (hash)
  • pending intake form is returned correctly, client is in waiting queue (hash)
  • start client has left waiting queue, chat is going to be initiated (hash, jid, bot)

Note: while assigning a jid / hash / bot combo, the status table is locked, to avoid double assignments. All housekeeping to be done for starting a chat up, (like sending a subscription request to bot.) should be done while in the state start and before the state is set to active. Recieved messages from the webchat are passed through to the staff member, messages from the staff member are discarded with an error-reply. The webchat finally sets the status to active.

  • active chat is initiated, client is connected to chat (hash, jid, bot)

Messages are passed through to the other, messages from staff are logged by the bot, messages from the client by the webchat.

  • lost_pending connection is lost while in waiting queue (hash)

On reconnect status is set to 'pending' again (only when inchat queue)

  • lost_short connection is lost shorter then the time-out period (hash, jid, bot)

Messages from staff are logged, so they can show up in the backlog. On reconnect status is set to 'active' again.

  • lost connection is lost longer then time-out period (hash, jid, bot)

The bot checks regularly if lost_short has been timed-out. If so, a status message is send to staffmember and logged. Messages to the client are logged, so they can show up in the backlog. The staff member has to wait or terminate the chat. On reconnect of the client, a message is send to the staff-member and the status is set to 'active' again.

  • stop client or staff member has terminated the chat (hash, jid, bot)

Both webchat and bot must regularly check if status is raised by the other. If raised, a message indicating who has stopped the chat is logged. Webchat proceeds to questions (if any), bot to configured state.

  • questions clients questionaire form is served (hash)
  • end answers are returned, clients hash is timed out, no actions anymore (hash)
  • inactive staff-member is online, but not available (jid)
  • available staff-member is available for chat (jid)
  • offline staff member is off-line (jid)
  • eval[n] staff member has been asked question #n (jid)

Configuration & Database

HelpIM makes a distinction between 'static configurations' and 'dynamic settings'. Beside these, there are also templates for the intranet.

static configurations

These are te following configuration files:

  • baseconfig
  • settings_webchat.py
  • settings_all.py
  • settings_chatbot.py
  • settings_intranet.py
  • settings_util.py
  • templates_chatbot.py
  • templates_webchat.py

Baseconfig always has to be on disk. The environment variable "HELPIMCONFIG" must point HelpIM to the right file. The other static configurations are read from the same directory as the baseconfig. Only if HelpIM can not find the file there, it tries to read them from the database. These configurations are cached for each apache2/mod_python process. A reload (or restart) of apache2 is needed to reread them.

dynamic settings

These settings are dynamic and stored in the databsase:

  • rooms_groupchat.py
  • blocked_webchat.py
  • shifts_webchat.py
  • questions_registration_example.py
  • questions_registration.py
  • queue_webchat.py
  • retention_webchat.py

These settings can be changed on the intranet and are reread everytime they are needed. These settings can be stored to disk and loaded from to the database with python [path-to-HelpIM]\settings.py.

templates for the intranet

These templates are stored in a location pointed at by 'settings_intranet.py', usually: /usr/local/share/HelpIM/templates. These templates are precompiled in a set of code specific for one site, and stored on a location pointed at by by 'settings_intranet.py', usually: /var/cache/HelpIM/[site]/templates/.

red screens & questionmarks in Psi

The nightly cron-job updates the rosters (contact lists) of the staff-memebers who are allowed to chat. Unfortunately this cron-job sometimes fails. This leaves the users with incomplete rosters, they won't see other staff-members while they are online, get 'red screens' with messages about authorisation in their rosters or see them with questionmarks before their names. Best is to rewrite all rosters of that site, although that is a bit of time-consuming an cumbersome procedure. This procedure can take up to several hours (depending on the amount of users) and disturbs other chats on the same machine. So do it only if you have a good moment for maintenance.

Step for step:

  • stop all HelpIM chatbots:
    /etc/init.d/HelpIM stop
  • stop jabberd:
    /etc/init.d/jabber stop
  • copy the spool-directory of the offending site to a backup:
    cp -pr /var/lib/jabber/chat.somesite.org /var/lib/jabber/chat.somesite.org_bak
  • empty the spool-directory:
    rm /var/lib/jabber/chat.somesite.org/*
  • start jabberd again:
    /etc/init.d/jabber start
  • open a seperate terminal and do in that terminal:
    • export HELPIMCONFIG=/path/to/site/baseconfig
    • python
    • >>> import HelpIM.users
    • >>> HelpIM.users.register_users()
  • When this command is finished, start the HelpIM bots again. Do this from the first terminal, otherwise the set HELPIMCONFIG might disturb the bots:
    /etc/init.d/HelpIM start
  • Now return to the terminal with the python prompt:
    • >>> HelpIM.users.write_rosters()
    • The step above is the most time consuming and opens for every user a jabber sessions at the same time. When you have too much users for so many sessions, then you might try:
      >>> HelpIM.users.write_rosters2()
      This one is slightly slower, but opens only a few sessions at the same time.
    • When finished, exit the python shell with:
      ctrl-D
      and close the terminal (to avoid accidents with the set HELPIMCONFIG)
  • The rosters are fresh an complete again!