This JBuddy Message Server Users Guide is intended primarily for two kinds of readers. The first group consists of IT staff who will be supporting and maintaining the JBuddy Message Server environment in a “system administration” capacity where central control of all IM activity is desired. The second group includes people who have been given authorization to administer their own accounts.

We provide a brief history of the Instant Messaging (IM) industry, describe IM concepts important to the use of features in the JBuddy Message Server. We conver installation of a new server, configuring accounts, and using the server in several common scenarios. We cover the new optional Instant Help system which uses JBuddy Message Server for a versatile web live help desk solution.

As far back as the dawn of computer networks, people have desired to communicate with each other. Back in the early 1980’s a unix program called talk was available on nearly all unix based computers. Talk allowed two users to exchange text messages with each other over the network (MESSAGING). In order to determine if another user was online, a second unix program was often used called rwho. Rwho would gather who else was logged into a unix computer on the LAN. After determining that the user you were interested to talk with was logged in to a remote computer (and presumably sitting at the computer) (PRESENCE), talk would be used to send an invitation to the remote user and invite them to chat. This invitation was often a short beep and a invitation message within the remote users’s terminal (this was before GUIs were available). If the remote user agreed to accept the invitation to talk, his terminal would be divided top and bottom with his text appearing in one half of the terminal and the remote user’s text in the other half of the terminal. Thus, instant messaging in it’s most primitive form was born. By 1988 a program called Internet Relay Chat (IRC) was available which allowed multiple users connected to the same IRC server to carry on a GROUP CHAT.

By the early 1990’s cell phones were growing in popularity in Europe and short text messages (aka SMS) were being passed between thousands of cell phone users. SMS still lacks presence, however in Europe, your cell phone is rarely off during the day and the SMS would be delivered to your cell phone as soon as it was turned on and an indication would appear on the phone’s display and possibly flash a light, vibrate, or emit a audible beep.

By the mid to late 1990’s, the land rush of the internet dot-com era was underway and several large internet service providers (ISPs) were running free public IM services each of which could not communicate with the other IM services. The four largest public IM services at that time were ICQ (I seek you), AOL Instant Messaging service  (AIM), MSN Messenger Service , and Yahoo Messenger .

AIM    ICQ    MSN    Yahoo

By 2003, worldwide adoption of IM continued to grow rapidly with over four hundred million users reportedly using at least one IM service. With corporate scandals and huge financial disasters like Enron and WorldCom surfacing,  the legislative branch of government in the United States passed regulatory laws mandating message retention, retrieval and in the case of health information, encryption - not only covering E-Mail, but IM! By 2004 SPIM was reported (unsolicated junk IM) and viruses and worms began to surface, largely using automated IM agents (BOTs) to deliver the message or an infected file. Enterprises realize that with regulatory compliance regulation deadlines looming and the aforementioned risk factors to business, that unmanaged IM is cause for great concern. By 2004, enterprises using IM have begun installing IM firewalls, and IM management software in an effort to lock down and bring IM under central control, security and compliance. Numbered are the days of unauthorized IM use within the enterprise. By 2005, IM is on the top 10 list of action-items within corporate IT departments. Some corporations have even attempted to shutdown any use of IM. By 2006 however, the inevitable trend toward embracing and adopting enterprise IM company-wide with carefully managed access to public IM is underway, which is one of the core features of JBuddy Message Server and described in this Users Guide.

It is always important to understand the basic concepts of any product that you will be using. Understanding the different components that make up the JBuddy Message Server will help you make the most of the platform.

We will start by discussing the versions prior to the latest release, version 3.0 which began shipping in June 2006. As you will discover, the new version offers significant improvements in management and user features over the prior, 2.0 version.

In releases prior to version 3.0, JBuddy Message Server shipped with only one IM gateway; the JBuddy Protocol Gateway, which provided secure, archived private enterprise IM. Connectivity to public IM and enterprise IM networks was available through the multi-network enterprise IM client, JBuddy Messenger Pro as shown in Figure 1-1 below.

JBuddy Message Server 3.0 represents a big leap forward in the JBuddy Message Server product evolution. It offers substantial benefits to organizations in many areas, including IM management and control, operations, user features, mobile uses, and development and system integration.

In Figure 1-2 below, you can see the current JBuddy Message Server 3.0 architecture. As in prior releases, it shows how all of the server components remain behind the corporate firewall while communicating with the outside world through the firewall. What’s new in version 3.0 is the ability to centrally manage and log all external communications, as well as route both public IM and enterprise IM to specific users including mobile E-Mail users. Version 3.0 supports an optional message gateway called Instant Help described in a subsequent chapter. By centrally managing external connectivity, the enterprise achieves greater control and reduces potential security threats and misuse while at the same time, bringing all users including mobile users under message archival for regulatory compliance.  Connectivity to public IM can still be achieved directly through the JBuddy Messenger Pro IM client if external file transfers are allowed at your organization.

Public IM is represented on the left side of Figure 1-2 by the MSN and AIM icons connected to their respective Public IM network clouds. A Blackberry icon represents an enterprise mobile user with an E-Mail enabled wireless device. This mobile user may or may not play a role in a JBuddy Message Server deployment depending on server configuration. On the right side of Figure 1-2 (inside the corporate firewall), several components which make up the JBuddy Message Server architecture are shown. The JBuddy Message Server consists of several components or services including an authorization / load balancing server, and multiple message gateways.

The Database server was omitted from Figure 1-2 but plays a critical role in the overall server architecture by persisting IM account data, routing rules, buddy lists, privacy settings, message archival for regulatory compliance purposes, and buddy presence. The presence stored in the database can form the foundation for other useful applications such as the display of presence information to a live web page or with email as a presence enabled URL as depicted in Figure 1-3 below. These applications are made possibly by leveraging the live presence updated in the database and using the new Presence Servlet new to this release.

External connectivity management and control is one of the major enhancements to the server in this release. To facilitate central management and mobile messaging, a message routing engine along with server-side public IM gateways, enterprise IM gateways, and other gateways including an SMTP message gateway are introduced to the server options. To facilitate web based live support, version 3.0 also introduces a sophisticated Instant Help message gateway.

During installation, if the Installer encounters more than one JVM, it will make a 'best guess' on which Java environment to use. It updates .conf files located in the conf directory. Near the top of these files it sets the property 'wrapper.java.command=$JAVA_HOME/bin/java' and then a little lower it updates the classpath wrapper.java.classpath.1=$JAVA_HOME/lib/tools.jar'. The $JAVA_HOME variable is replaced with the 'JAVA_HOME' that the Installer believes is the correct version. If you wish to use a different JVM, you will need to edit the values above. Also if you desire to use the -server flag for performance reasons, you will need to use a Java version that includes support for this feature. On Windows and OS X, the typical JRE 1.4.x does not, but on Linux it does. You can determine if your JVM environment supports this by typing the following in a command shell or terminal: java -server -version which should tell you the version of java used as well as if it is the server or client version of the virtual machine.

Initially you will need to run the installation on a computer with a graphical interface (see Launching the Graphical Installer below). At the end of the installation, you will be prompted if you wish to save the installation as an XML installation script which can be used later for an automated (non-graphical) installation such as on a remote Linux or Unix server. If this is your situation, you need to enter information applicable to the remote host when prompted during the Installer. To run the headless installation, copy the installer jar file and xml install script saved at the end of the GUI install to the remote host. Then login to the remote host and from a command shell or terminal, enter as follows:

java -jar JBuddyMessageServerInstaller-3.x.xxxx.jar JBuddyServerInstallScript.xml where the JBuddyServerInstallScript.xml is whatever name you saved at the end of the GUI install.

After JVM 1.4.x or 5.x is properly installed, double click on the JBuddyMessageServerInstaller-3.x.xxxx.jar file to launch the installation program. If you prefer, you can launch the Installer by simply entering the following from a command shell or terminal: java -jar JBuddyMessageServerInstaller-3.x.xxxx.jar. Once launched you should see a small Language Selection dialog appear similar to Figure 2-1 below:

After selecting eng (English) language and clicking OK, the Installation Welcome window appears similar to Figure 2-2:

After clicking Next, the Installation Information window appears similar to Figure 2-3:

After clicking Next, the License Agreement window appears similar to Figure 2-4. You must accept the terms of the license agreement before the Next button will permit proceeding to the next screen.

After accepting the license agreement terms and clicking Next, the installation path must be specified as in Figure 2-5 below. Once Next is chosen an Message dialog appears to inform you that the directory will be created (or if it already exists).

After clicking OK to the Message dialog, the Installation Registration window will appear where you should enter your organization name and paste in the license key you received from Zion as in Figure 2-6 below. If the license key is not entered properly, or has expired a Input Problem dialog will appear. The best way to avoid this error with a valid license key is to copy and paste since 1s and ls and Os and 0s are often difficult to distinguish.

After pasting a valid license key into the License String input field and clicking Next, the Installation Package Selection window will appear similar to Figure 2-7 below:

The Package Selection window shows mandatory and optional “packs” that can be installed. Clicking a individual pack changes the description shown. For example, if you don’t have plans to leverage Lotus Sametime or ICQ, you can uncheck the pack(s) and it will not get installed. Just because you install a particular pack doesn’t mean you have the proper license to enable that feature. An improvement of the Installer would only enable the products packs which you hold a valid license to use. Once you are satisfied with your packs selection, click Next to proceed.

After clicking Next, the Installation Configuration window will appear similar to Figure 2-8 below. Server Hostname is the IP address or fully qualified domain name of the machine where JBuddy Message Server will operate once installed. If it will ultimately live on a remote headless machine, enter that host name or IP here.

The Sys Admin UserId is a login userid for administering the JBuddy Message Server. It is not related to operating system authorization credentials. Confirm the chosen password by reentering it in the Confirm Password input field. The Database Secret field is also a password field of sorts. It is used to encrypt all user account passwords with 192 bit Triple DES encryption into the database. It should be noted that although the account passwords are very securely encrypted, the Database Secret must be accessible by the server at runtime to unencrypt the passwords on demand and therefore, utmost care should be taken to protect the JBuddy Message Server configuration files from unauthorized access or view.

After clicking Next, the second Installation Configuration window will appear similar to Figure 2-9 below. E-Mail From is the email address used for emails sent from the JBuddy Message Server such as for lost passwords. The Smtp Host is the fully qualified hostname of the SMTP mail server that JBuddy Message Server will use to deliver the email. If the SMTP mail server requires authorization to login before sending email, the Smtp User and Smtp Password should be entered. If not, leave them blank.

After clicking Next, any optional Installation Configuration windows will appear similar to Figure 2-10A-D if you selected the SMTP Gateway, Lotus Sametime, Microsoft LCS or Jabber packs respectively during the Installation Package Selection window (Figure 2-7).    

In Figure 2-10A, the current Installer prompts for an IMAP Host, IMAP User and Password, however the configuration file for the SmtpMsgGateway.properties file may be configured for POP email retrieval by changing the correct properties in the future.

If you selected any other enterprise IM packs to be installed such as Lotus Sametime or Microsoft LCS or Jabber, you will be prompted to provide the hostname of the EIM server similiar to Figure 2-10B, 2-10C, 2-10D) below.

After clicking Next, the Installation Process (Figure 2-11) will begin and you will see progress bars as the packs are written to the directory specified in the Installation Location window (see Figure 2-5). Once this process is complete, the Next button will become active.

After clicking Next, the Installation Post Install Processing window will appear similar to Figure 2-12 (Mac OS X) below. If the Installation is believed to be successful, the Next button will be enabled once more.

On Windows, the Installer will attempt to register the JBuddy Message Server and JBuddy Message Server Admin Console as services with the operating system and start them. The log output from Post Install Processing will appear in the window as well (Figure 2-13). If the Installation is believed to be successful, the Next button will be enabled once more.

After clicking Next, the final Installation window will appear as shown in Figure 2-14 below. You can save this GUI installation as an XML script for a repeatable non-gui installation, by clicking the “Generate an automatic installation script” button before finishing.

On Windows 2000, Windows 2000 Server, Windows 2003 Server and XP Pro, both services are installed and started automatically in the background as "windows services". Log output shown in the Installation Post Install Processing window (Figure 2-13) would typically indicate the success or failure of the services launch during installation. At any point after the installation, you can view the current running status of the JBuddy Message Server services on a Windows Machine by viewing the Windows Services Panel, (Extended) (Figure 3-1). If the Status is “Started” this indicates the service is running. To shutdown the server on Windows, select the JBuddy Message Server service and click stop the stop button. The JBuddy Message Server Admin Console will also be stopped as it depends on the JBuddy Message Server service. This may take a minute. To start the Server, select each of the JBuddy services and click the start button. After a few seconds the Services panel should refresh and update the services Status to “Started”. If one or both of the services fail to start the Windows Event Logger will show the failure.

 

Property Name	Property value	Default	Description
-server	N/A	N/A	uses the server JVM instead of  the client JVM for server side applications. No -D is prepended.
-XX:AggressiveHeap	N/A	N/A	enables the AggressiveHeap garbage collector in the JVM for high load servers. No -D is prepended.
jbuddy.use_external_db	true	false	Disable embedded HsqlDB engine
jbuddy.disable_message_archive	true	false	Disable message archiving
jbuddy.use_rich_text_in_message_archive	true	false	Archive message in native rich text format instead of plain text
jbuddy.auto_reply_seconds	900	900	Number of seconds of idle to resend auto_reply message
jbuddy.db_key	READ ONLY	DB Secret	This is READ ONLY after installer. Triple DES key used to encrypt passwords.
jbuddy.use_ssl	true	false	Enable SSL login and message encryption (applies to JBuddy Gateway and JBuddy Message Server)
jbuddy.logLevel	0-1023	3	default log level for JBuddy Message Server and all components
jbuddy.logThreaded	true	false	Spawn a logger thread to try to order the incoming log requests according to FIFO order

Log Level Name	Log level	Description
OFF	0	Logging Disabled
EXCEPTION	1	Log Exceptions
ERROR	2	Log Errors
WARNING	4	Log Warnings
DATABASE	8	Database related logs
RMI	16	RMI related logs
SOCKET	32	Socket related logs
TRACE	64	Method level logs
DEBUG	128	Full debug logs
LOG_BUDDY	256	Presence related logs
LOG_MESSAGE	512	IM related logs
ALL	1023	Always log

For more fine-grained control over logging, individual components can have their logLevel set by adding a System property to the MessageServer.properties file after the specified component. For example. To turn on EXCEPTION, ERROR, WARNING, and PRESENCE and MESSAGE logging for the AIM Gateway, we would enter the following using the values from the Log Level Table above:

Inside the installation directory is a hsqldb subdirectory where the HSQLDB database server is installed. This is a simple yet powerful open source relational database written in java. Using a .conf option, the JBuddy Message Server can be told to use an external database such as Oracle, Sql Server, My SQL, etc rather than HsqlDB if desired. Presently the JBuddy Message Server controls the start and stop of HsqlDB. JBuddy Message Server communications with the database through a properly configured JDBC driver.

Although we haven’t covered User level accounts up to this point, this section will detail how to correctly create User level accounts in the database such as for a bulk loading of users by directly updating the database with SQL.

For enterprise IM using the proprietary JBuddy protocol, the JBuddy Message Server load balancer process listens on port 1424 and the JBuddy Gateway listens on 1425 by default. These can be modified prior to startup by carefully editing the MessageServer.properties file within the lib subdirectory. The load balancer listening on port 1424 redirects connecting clients to connect to the JBuddy Gateway running on port 1425 on the same host or other hosts if JBuddy Message Server is configured for enterprise clustering. The JBuddy Message Server Admin Console runs as a web application within Jakarta-Tomcat and is available by default by pointing your browser to port 8080, although configuring Jakarta-Tomcat to run in parallel with the popular Apache web server on port 80 is very common but beyond the scope of this guide. Other network ports used by JBuddy Message Server may include additional ports opened by Jakarta-Tomcat, HsqlDB (see Jakarta-Tomcat and HsqlDB documentation for details), and Java’s RMI (port 1099 by default). Various other optional message gateways use additional ports and are documented in the section specific to the gateway.

Normally enterprise IM is configured for privacy and security with no external access permitted. However, if the JBuddy Message Server is used for an internet portal or online community, then external access is required. If the host that JBuddy Message Server is installed on is reachable from the internet with a fully qualified domain name or internet IP, there is no problem. However, if the host that JBuddy Message Server is installed on is only visible from the private network, an additional setting is required. The JBuddy Message Server may be configured to listen for connecting clients from the internet while running on a private IP network such as 192.168.x.x behind a NAT Router by adding the following System Property to MessageServer.properties located in the lib subdirectory:

Each user who will have the ability to configure Accounts within JBuddy should have their own User Profile. A User Profile consists of a user id and password and other contact information. The Sys Admin User Id is created during server installation. If central control of all accounts will be handled by the Sys Admin for the JBuddy Message Server, then no additional User Profiles need to be created. The default Central Account Management screen is shown in Figure 4-1A below.

If each user will be able to manage their own Accounts such as for a hosted service, then each user should to have their own User Profile. Please request the hosted-version of the JBuddy Message Server from Zion Software if this is your intended use. It differs slightly from the non-hosted version (see Figure 4-1B) and provides users with the ability to create their own User Profile. To create their own User Profile, users will click on the Sign Up Now link from the homepage and completing the User Registration form (Figure 4-2).

With a valid user ID and password (either the Sys Admin or one created using the User Registration form in Figure 4-2), a user can login to the JBuddy Message Server Admin console by entering their user ID and password in the User Name and Password fields shown in Figure 4-1, or may login via a WAP enabled mobile device but pointing the mobile device browser to:

Upon login the user will be presented with the Welcome page (Figure 4-3).

From here, the user can access various pages in the Admin Console by either clicking on the links in the Welcome page or clicking on the tabs across the top. Since this is a newly created User, we will begin with the Account Manager.

 

 

 

 

All connectivity in the JBuddy Message Server centers around Accounts. There are IM Accounts and there are other non-IM Message Accounts. A user may have more than one Account since JBuddy Message Server version 3.0 is capable of connecting to five (5) public IM networks and four (4) Enterprise IM servers in addition to the other messaging services. After clicking on the Account Manager link or top menu tab, the Account Manager Admin screen appears (Figure 4-4):

Since this is a brand new user profile, there are no accounts visible in the table. After clicking on the Add Account, the New Messaging Service Account screen appears (Figure 4-5):

The Message Service Provide drop down list offers a list of public IM, enterprise IM and several other messaging service types. Depending on the license(s) installed, this list may be different. After selecting the desired Messaging Service Provider, the default fields may change.

In Figure 4-7, we’ve selected AOL Instant Messenger Messaging Service Provider as indicated by the yellow triangle representing AIM.

After creating several message accounts, the Account Manager Admin screen would look similar to Figure 4-8 below:

Notice in Figure 4-8 how the status is blank for all the services. This is because the accounts are not yet active.

In order to active the message accounts creating in the IM Accounts screen, they must be associated with another message service. In the JBuddy Message Server Admin Console, this message account association or mapping or routing is termed, ‘IM Account Forwarding’ and it is available as a sub menu on the left side of the screen in the Account Manager below ‘IM Accounts’ (Figure 4-9 below).

IM Forwarding To Blackberry (e-mail enabled devices)

IM Forwarding To Instant Help

Forwarding IM accounts to an Instant Help account permits an IM account to be used as a proxy representative for a real person. As an example, the ZionRep AIM account could be forwarded to an Instant Help account named ‘Sales’. When a properly configured Instant Help web link was clicked by a web visitor, the Sales Instant Help proxy would be selected and an IM help invitation would be sent to one or more real IM users through the proxy representative (ZionRep). This scenario is very powerful for distributed live help desk support and will be covered in a chapter of its own.

 

Returning to the IM Account Forwarding screen, we notice the new online accounts status as indicated by the status column with green (online) bullets (Figure 4-14). If a route was not active, instead of a stop sign, you would see a green “Go” button to indicate that you need to press GO to activate it.

DeActivating IM Forwarding

IM Forwarding can be deactivated simply by clicking on the red stop sign or deleting the route altogether. In addition, a mobile users with a WAP enabled browser and authorization credentials can login (see WAP Login in the Logging In section above) to the Admin Console if it’s accessible and de-active any active routes.

In the next chapter, we will examine the Buddy Manager were the status of buddies is determined by the active, online status of accounts in this section.

Archiving messages serves no purpose without the ability to search and find specific messages quickly which is why the recent Sarbanes Oxley and HIPPA record retention legislation included time constraints on finding data on demand if a company was under court order or under an SEC audit. This is not a problem with the Search IM Archive screen within the JBuddy Message Server Admin Console (Figure 6-1):

Now that we’ve covered the core JBuddy Message Server features, we will describe an exciting new technology available as an add-in to the JBuddy Message Server. Clicking on the Instant Help Manager tab brings up the Instant Help Manager Admin screen (Figure 7-1).

    

they are prompted for their name and their initial question (Figure 7-3):

 

In this initial release of the Instant Help Server, the following Attributes are predefined (see Table 7-1). In the future additional Attributes may be defined. The Attribute name and value are specified along with the effect it has if associated with a Link or Buddy.

Property Name	Property value	Area	Description
dispatchAlgorithm	A whole number	LINK	The number of seconds between sending invitations to help to qualifying reps
dispatchTimeout	A whole numer	LINK	The number of seconds after the last invitation to help is sent before telling the visitor no helper are available
contactFormUrl	URL	LINK	URL to provide to visitor if no helpers are available
contactFormEmail	EMail	LINK	The E-Mail address to send default contact form submissions to
onlineButtonUrl	URL to graphic	LINK, BUDDY	LINK - URL to online button. BUDDY - URL to online button for Buddy Presence
offlineButtonUrl	URL to graphic	LINK, BUDDY	LINK - URL to offline button. BUDDY - URL to offline button for a Buddy Presence
offlineSchedule*	crontab formatted  offline schedule	LINK, BUDDY	LINK - governs when the link is offline/inactive. BUDDY - governs when the buddy is offline/inactive. This is used for PresenceServlet?buddyId=4 queries. Attribute name or Attribute name prefix (attribute name must start with 'offlineSchedule') for scheduled offline hours in unix crontab format. If no link attributes are equal to or begin with offlineSchedule, the presence of qualified reps will determine the use of offlineButtonUrl or onlineButtonUrl. Attribute Value Format consists of five fields. The fields are separated by spaces or tabs. They are integer patterns that specify the following: minute (0 -59 ), hour (0 -23 ), day of the month (1 -31 ), month of the year (1 -12 ), day of the week (1 -7 with 1 =Sunday). Each of these patterns may be either an asterisk (meaning all legal values) or an element. An element is either a number or two numbers separated by a minus sign (meaning an inclusive range). Note that the specification of days may be made by two fields (day of the month and day of the week). If both are specified, both are adhered to. For example, 0 0 25-31 * 2 would indicate a scheduled outage between the 25th and 31st of the month, as well as on every Monday. To specify days by only one field, the other field should be set to * (for example, 0 0 * * 2 would run a command only on Mondays). The parsable schedule format may be modified in the future to include an asterisk or list of elements separated by commas. For example, * 0-6 * * 7,1 would mean outage from midnight to 6am on Saturday and Sunday. For now, two records for the named resource would be necessary to specify this schedule.
displayName	name	BUDDY	Rep name to display to visitor if set as an attribute of Buddy (Rep)

Instant Help captures 'help session' data during each session including; how many messages are sent from the visitor, how many messages are sent by the rep, which rep(s) helped the visitor, the link ID the visitor clicked for help, the visitor’s given name and given question (initial submission to request help), the referer URL that brought the visitor into the Instant Help system, the type of web browser used by the visitor, the actual messages sent / received (if message logging is enabled), and several other elements - all recorded in the HELP_SESSION database table.

Once JBM is installed, you will be prompted to create a new IM account. This step doesn’t actually provision a new IM account on an IM server, but instead allows the user to specify the login credentials and server configuration necessary to sign on to the server. In order to login to the JBuddy Message Server, the JBM user must already have an account on the server created already (see Figure 4-6). The JBM user will click New Account (JBuddy Message Server) (Figure 8-1).

Next, the JBM user will specify the Username and Password (Figure 8-2):