Web Help Desk ™

Administrator’s Guide
Version 9.1.10

© 2008 MacsDesign Studio

Table of Contents
Chapter 1: Database
Select a Database     1
Database Setup     1
MySQL      1
SQL Server 2005     2
Oracle     2
PostgreSQL 8     2
OpenBase     2
Backup Strategies     2
Chapter 2: Installation
Mac OS X     4
Pre-Install Requirements     4
Installation     4
Windows Server     4
Pre-Install Requirements     4
Installation     4
Linux     5
Pre-Install Requirements     5
Installation     5
Solaris     5
Pre-Install Requirements     5
Installation     5
Apache Integration     6
Existing Tomcat Integration     6
Microsoft IIS Integration     6
Chapter 3: Getting Started
Preferences     7
General     7
Time & Place     7
Users     8
Tickets     8
Location     11
Billing     11
E-Mail     12
Techs     13
Technician List     13
Tech Groups     14
Locations     15
Location List     15
Location Groups     16
Departments     16
Assets     17
Models     17
Chapter 4: Managing Clients
Manual Web Entry     18
Client Info     18
Assigned Assets     18
Ticket History     18
Data Import     18
LDAP Synchronization     19
Mapping Attributes     19
Synchronizing LDAP Connections     20
Chapter 5: Tickets
Web-Based Ticketing     21
Client Info     21
Asset Info     21
Ticket Details     22
Other Ticket Options     23
E-Mail Ticketing     25
Reporting by E-Mail     25
Updating by E-Mail     25
Creating Tasks     26
Task Elements     26
Triggering Tasks     27
Search Tickets     27
Refining Search Results     27
Saved Queries     28
Ticket Bulk Actions     28
Quick Tickets     29
Ticket Assignment Logic     30
Chapter 6: Asset Management
Adding Assets     31
Manual Web Entry     31
Import Assets      32
Asset Discovery Integration     33
Refining Search Results     33
Saved Queries     33
Purchase Orders     34
Define Vendors     34
Create a New Purchase Order     34
Add Line Items     34

Purchase Order Import     35
Chapter 7: Asset Discovery
Asset Discovery Components     36
Supported Components:     36
Asset Discovery Mechanics     36
Discovery Tool Configuration     36
Apple Remote Desktop 3     36
Casper     37
LANrev     37
Web Help Desk Configuration      38
Connection Basics     38
Attribute Mapping     40
WHD Hyperlink to Discovery Tool      40
Chapter 8: Approvals Management
Approver Roles     41
Add Approver Roles      41
Assign Approver Roles     42
Approval Processes     43
Add Approval Processes     43
Add Approval Steps     43
Define Request Types Supported     43
Approval Status Types     44
Add Approval Status Types     44
Assign Approval Status Types     44
Using Approvals     44
Ticket Creation     44
Approver Action     45
Requester Action     46
Chapter 9: FAQs
FAQ View     47
New FAQ     47
Public FAQ Access     48
Web Access     48
RSS Feed     48
Chapter 10: Parts and Billing
Billing Preferences     49
Invoicing     49
Custom Logo     49
Table of Contents
Billing Rates     49
Billing Terms     49
Tax     49
Managing Parts     50
Parts List     50
Importing Parts     50
Adding Inventory     50
Importing Inventory     51
Using Parts     51
Invoicing     51
Service Time Blocks     51
Chapter 11: Reports
Sample Reports     53
Creating Reports     53
Ticket Report     53
Billing Report     56
Creating Report Groups     57
Group Options     57
Included Reports     57
Creating Report Schedules     57
Schedule Details     57
Tech Recipients     58
Included Reports     58
History     58
Creating Survey Reports     58
Chapter 12: Surveys and Messages
Managing Surveys     59
Survey Manager     59
Sending a Survey     59
Viewing Survey Results     60
Ticket Detail View     60
Survey Reports     60
Messages     61
Creating Messages     61
Viewing Tech Messages     61
Viewing Client Messages     62
License Key Expiration Message     62
Chapter 13: Client Interface
Help Request     63
History     64
 Table of Contents

FAQs     64
Profile     64
Administrative Contacts     65
Logout     65

Chapter 14: Deployment Consider-

ations
Memory Sizing and JVM Options     66
Supporting up to 20 Techs     66
Supporting over 20 Techs     66
WebObjects on Mac OS X Server     66
Clearing JVM Heap Memory     68
Mac OS X     68
Windows     68
Linux/Solaris     70
Configuring WHD for HTTPS     70
Setting HTTPS_PORT and URL_HTTPS_PORT in
whd.conf     70
Certificate configuration overview     70
Generating a new certificate     71
Importing an existing certificate     74
Enabling HTTP-to-HTTPS redirection     75
Troubleshooting     76
 1

Chapter 1: Database
Select a Database
Before installing the Web Help Desk, you should decide on
which database the application will use. JDBC drivers for all
supported databases are installed by default.

Supported Databases:
• FrontBase (included on Mac OS X and Windows)
• MySQL 5
• SQL Server 2005 or later
• Oracle 8i/9i/10g
• PostgreSQL 8
• OpenBase
If installing on Mac OS X or Windows and you wish to
use the embedded FrontBase database, skip ahead to Select the host you’ll connect from, then click the “Schema
Chapter 2. Privileges” tab. Select the “whd” schema, and assign the
Select, Insert, Update, Delete, Create, Drop, References,

Database Setup Index, Alter and Lock_Tables privileges.

MySQL
Using the MySQL Administrator Tool, create a new database
schema named “whd” using the Catalogs option.

Save changes and the database is ready for the Web Help
Desk to connect.

Add a “whd” account, and attach an appropriate host to the

account. If you’re running MySQL on the same server as the
WHD is installed, “localhost” is fine, otherwise attach a host
with the IP address or DNS name of the WHD server that
will connect to the database.
CHAPTER 1
SQL Server 2005
Use the “SQL Server 2005 Surface Area Configuration” tool
to ensure that the server is listening over TCP/IP. Depend-
ing on what edition you’re using, you may need to enable
Remote Connections over TCP/IP if your database is on a dif-
ferent machine from the WHD installation.
Connect to the “Microsoft SQL Server Management Stu-
dio Express” application. Make sure you’ve enabled “SQL
Server Authentication” by right-clicking on the database
server in the Object Explorer pane and selecting “Properties”.
Select the “Security” Page, and check off “SQL Server and
Windows Authentication mode”.
Expand the “Security” folder under the database server in the
Object Explorer pane, then right-click on the “Logins” folder
and select “New Login...”.
Create a new “whd” login using “SQL Server Authentica-
tion” – set the password to anything you like.
Database 2
Right-click on the “Databases” folder in the Object Explorer
pane and choose “New Database...”. Name the new database
“whd” and assign the “whd” user as the Owner.
The database is now ready for connection with the Web Help
Desk.
Oracle
Create a new table space and user account having select,
insert, update, delete, create, drop, index, and alter
privileges. The user account should be named “whd” and the
password can be set to one of your choice. You will need the
SID value for the table space to make a connection from the
Web Help Desk.
PostgreSQL 8
As the postgres admin user, create a new “whd” user and
a new database called “whd”. Grant all permissions to the
whd database for the whd user.
OpenBase
Create a new database called “whd” and enable automatic
start on reboot. For the default “Admin” user, set the pass-
word to one of your choosing. Refer to the OpenBase docu-
mentation if you more explicit instructions.
Backup Strategies
Having a regular backup schedule is very important to protect
your data in the event of a catastrophic hardware failure.
The Web Help Desk can automatically make scheduled
backups on the embedded FrontBase database. Embed-
ded FrontBase backups are located at <WebHelpDesk>/
CHAPTER 1 Database 3

FrontBase4/Backups/whd.fb by default, or you can choose

your own backup location. If not using FrontBase, the applica-
tion can trigger the execution of your own backup script daily.
The backup should always be moved to a separate hard disk or
tape.

Chapter 2: Installation
Mac OS X
Pre-Install Requirements
• Mac OS X 10.4 or later with Java 5 installed.
• If not using the embedded FrontBase, your database of
choice should be setup as described in Chapter 1.
Installation
Mount the WebHelpDesk-<version>.dmg disk image in the
Finder and double click on the WebHelpDesk.pkg installer.
The application will be installed into:
/Library/WebHelpDesk
Utilities to start and stop the Web Help Desk and the Front-
BaseManager application are installed into:
/Applications/WebHelpDesk
The application is configured to start automatically after
installation and on reboot. However, if you do need to stop
or restart the application for any reason, you can use the start
and stop options in /Applications/WebHelpDesk.
By default, the Web Help Desk serves web pages on port
8081. If you would like to configure the Web Help Desk
to work with Apache, or run on port 80 directly, follow the
instructions described in the Apache Integration section.
Connect to the Web Help Desk by going to the URL:
http://localhost:8081/helpdesk
The application will attempt to connect to the FrontBase em-
bedded database by default. You will be prompted to update
the database to the latest version. Login to the application,
using the default account:
E-Mail Address: admin
Password: admin
Tip: In a new installation, the application will not prompt you for a database connec-
tion or license name and key. It will automatically use the embedded database and
start up in demo mode. If you don’t want to use the embedded database, you will
need to go to Preferences > General > Database to update your settings. You must
restart the application to use the new database connection. To enter your license
name and key, go to Preferences > General > Server Settings.
4
Windows Server
Pre-Install Requirements
• If not using the embedded FrontBase, your database of
choice should be setup as described in Chapter 1.
Installation
Launch the WebHelpDesk-<version>.exe application and
follow the on screen instructions. By default, the application
will be installed into:
C:\Program Files\WebHelpDesk
The Web Help Desk is configured to start automatically on
reboot. However, if you do need to stop or restart the applica-
tion for any reason, go to Start > All Programs > Web Help
Desk and use the stop/start options.
By default, the Web Help Desk serves web pages on port
8081. The application can be configured to run on port 80,
but IIS must be stopped. Refer to the Microsoft IIS Integra-
tion section at the end of this chapter for more information.
Connect to the Web Help Desk by going to the URL:
http://localhost:8081/helpdesk
The application will attempt to connect to the FrontBase em-
bedded database by default. You will be prompted to update
the database to the latest version. To login to the application,
use the default account:
E-Mail Address: admin
Password: admin
Tip: In a new installation, the application will not prompt you for a database connec-
tion or license name and key. It will automatically use the embedded database and
start up in demo mode. If you don’t want to use the embedded database, you will
need to go to Preferences > General > Database to update your settings. You must
restart the application to use the new database connection. To enter your license
name and key, go to Preferences > General > Server Settings.
CHAPTER 2 Installation 5

Linux Solaris
Pre-Install Requirements Pre-Install Requirements
• RPM Package manager • Database setup as described in Chapter 1.
• The application has only been tested on RedHat Linux,
but should work on other distributions. Installation
• Database setup as described in Chapter 1. NOTE: You will need the open-source utilities sudo and star
(a tar replacement).
Installation
star is needed because the tar utility included with Solaris
Decompress and install and install the RPM:
(/usr/bin/tar) will not extract the long filenames in the
webhelpdesk-<version>.tgz package correctly, nor will the
gunzip webhelpdesk-9.x.x-1.noarch.rpm.gz
open-source GNU tar. (gtar version 1.13, currently the most
sudo rpm -ivh webhelpdesk-9.x.x-1.noarch.rpm popular build for Solaris, seems to have a bug that truncates
the last character of paths having 103 characters.) You can
The RPM installs and starts the Web Help Desk at: use the following to install star (replace sol9 with sol8 if us-
ing Solaris 8):
/usr/local/webhelpdesk
• Download the pre-compiled star package (star-1.5a40-
The application is configured to restart automatically upon sol9-sparc-local.gz) from:
reboot. However, if you do need to manually stop and start http://ftp.sunfreeware.com/ftp/pub/freeware.
the application, using a shell: • Uncompress the package (for Intel servers, replace
sparc with intel):
cd /usr/local/webhelpdesk
gunzip star-1.5a40-sol9-sparc-local.gz

sudo ./whd stop • Install the package:

sudo ./whd start
By default, the Web Help Desk serves web pages on port
8081. If you would like to configure the Web Help Desk
to work with Apache, or run on port 80 directly, follow the
instructions described in the Apache Integration section.
If no Apache integration is required, connect to the Web Help
Desk by going to the URL:
pkgadd -d star-1.5a40-sol9-sparc-local
The Web Help Desk startup script depends on finding the
bash shell at /bin/bash. Unfortunately, before Solaris 9, bash
was not included in the default installation. If you do not
have bash installed, you can download it as a package from
http://sunfreeware.com. After installing the package, check
that there is a link to the bash executable from /bin/bash. If
not, you can create it with the command ln -s <path_to_bash_
executable> /bin/bash.

http://localhost:8081/helpdesk To install the Web Help Desk once the above prerequisites
are met:
Provide your settings to at the database configuration screen.
You will be prompted to update the database to the latest ver- Extract the webhelpdesk folder into /usr/local/. Be sure to use
sion. To login to the application, use the default account: star not tar!

E-Mail Address: admin sudo star xfz webhelpdesk-<version>.tgz -C /usr/local/

Password: admin

Tip: In a new installation, the application will not prompt you for a license name and
key. It will automatically start up in demo mode. To enter your license name and key,
go to Preferences > General > Server Settings.
CHAPTER 2
Execute the following to make the Web Help Desk start up
automatically after a reboot:
sudo /usr/local/webhelpdesk/bin/install_autostart
Start the Web Help Desk:
/usr/local/webhelpdesk/whd start
By default, the Web Help Desk serves web pages on port
8081. If you would like to configure the Web Help Desk
to work with Apache, or run on port 80 directly, follow the
instructions described in the Apache Integration section.
If no Apache integration is required, connect to the Web Help
Desk by going to the URL:
http://localhost:8081
Provide your settings to at the database configuration screen.
You will be prompted to update the database to the latest ver-
sion. To login to the application, use the default account:
E-Mail Address: admin
Password: admin
Tip: In a new installation, the application will not prompt you for a license name and
key. It will automatically start up in demo mode. To enter your license name and key,
go to Preferences > General > Server Settings.
Apache Integration
By default, the Web Help Desk runs on port 8081. If you
don’t need Apache, and would prefer to run the application
on port 80, do the following:
• Stop Apache
• Set the DEFAULT_PORT variable in webhelpdesk/
conf/whd.conf to 80
• Restart the Web Help Desk
To configure the Web Help Desk to work with Apache, per-
form the following steps:
• In your Apache configuration file (httpd.conf ), enable
the mod_proxy module by making sure the following
lines are uncommented:
LoadModule proxy_module
AddModule mod_proxy.c
• Add the following lines at the end of your Apache
Installation 6
configuration file (httpd.conf):
ProxyPass /helpdesk http://localhost:8081/helpdesk
ProxyPassReverse /helpdesk http://localhost:8081/helpdesk
• Restart Apache
Existing Tomcat Integration
To simplify installation, the Web Help Desk comes bundled
with its own copy of the Apache Tomcat application server.
However, if your deployment server already has Tomcat
installed and you wish to use it in place of the included copy,
move the following two directories to your existing Tomcat/
webapps directory:
webhelpdesk/bin/webapps/helpdesk
webhelpdesk/bin/webapps/WHDReminderDaemon
If you are running Tomcat and Apache, you will need to add
the ProxyPass entry described in the previous section.
Microsoft IIS Integration
By default, the Web Help Desk runs on port 8081. If you
don’t need IIS, and would prefer to run the application on
port 80, do the following:
• Stop IIS
• Set the DEFAULT_PORT variable in C:\Program
Files\webhelpdesk\conf\whd.conf to 80
• Restart the Web Help Desk
If there are multiple IP addresses on the machine, you can
run the Web Help Desk on port 80 along with IIS on port 80
provided you bind IIS and Web Help Desk to separate IPs.
To specify the IP address for Web Help Desk, edit the C:\
Program Files\WebHelpDesk\conf\whd.conf file and
set the IP_ADDRESS option to the IP you want to bind.
To bind IIS to a specific port:
• At a command prompt, switch to the “C:\Program
Files\Support Tools” folder.
• Type the following command: httpcfg set iplisten -i
xxx.xxx.xxx.xxx (where xxx.xxx.xxx.xxx is the IP ad-
dress you want IIS to listen)
• To check your settings, type the following command:
httpcfg query iplisten

Chapter 3: Getting Started
Preferences
Log in as an Administrator and click on the Preferences tab.
Tip: Pop-up help is available throughout the preferences. Mouse over any prefer-
ence label for a detailed description of the setting.
General
Server Settings
Specify your server DNS name and, if enabled, when to use
the HTTPS protocol. Define an optional login message and
edit the forgot password message to your liking. Enable au-
tomatic login and define the session timeout values for both
Techs and Clients. If you have license key to enter, click the
lock icon and apply the name and key.
Custom Logo
Upload a customized logo used in the web application and
client e-mail. Logo should be 259 x 61 pixels in size.
Global Options
Specify settings that affect the entire application, like the use
of Departments and Assets or enabling Parts and Billing. You
can also set the max number of items fetched from the data-
7
base and the max attachment size accepted by the application.
Database
Specify the database vendor, machine name or IP address and
connection account. Specify a backup schedule for your data-
base and set a custom backup path for the FrontBase database
if desired.
Logs
Specify the logging level of the application (default is Error).
Enable sending the log to a remote server for monitoring with
the Chainsaw log tool. Logs are stored in WebHelpDesk/log/
helpdesk.log.
System
Displays system environment information: application ver-
sion, Java version and memory used.
Time & Place
Business Zones
The application creates a default business zone that should
match the time zone specified by the server’s operating sys-
tem. You can create additional business zones for other time
zones your Techs or Locations may use. All Techs use the
default zone unless overridden in their profile. Clients inherit
their business zone from their assigned Location, using the
default if the Location has no override. Business zones define
the date, time and number formats as well as the business
hours used in calculating ticket open times.
CHAPTER 3
Calendars
Enable/disable calendar links, determine which ticket types
are included, specify the calendar time “window” and cus-
tomize the format for event listings.
Users
Client Options
Specify the client login attribute (e-mail or user name), define
which client fields are editable and required, and list which
domains the client e-mail must match to create a new ac-
count. The default module displayed to the client after login
can also be specified.
Client Custom Fields
Create custom fields for your clients and define viewing/
editing permissions for clients and techs. Custom fields are
Getting Started 8
always visible to administrators.
Default Tech Permissions
These options serve as default values for any new Technician
account. Each technician can have his/her own unique prefer-
ence values specified in their detail record. Important options
include:
• Editing options on assets, models, parts and purchase
orders
• Ticket related editing options
Tickets
Ticket Options
Set the default priority for tickets and enable file attachments.
Other important options include:
• Enable clients to set ticket priority
• Lock the ticket to the client’s assigned location so that
service locations remain private
• Field style for rooms (text or popup menu)
See the online help pop-ups for more information.
Custom Fields
Create custom fields for your tickets and define viewing/edit-
ing permissions for clients and techs. Custom fields can be
defined as one of the following types: Text, Multiple Choice
(checkboxes), Single Choice (radio buttons), or Popup Menu.
If the custom field must have more options than will fit in the
Options text field, they can be uploaded in a text file. The op-
tions should be either semicolon or new line delimited. Each
option must be less than 150 characters in length.
Request Types
Define what request categories your Web Help Desk will
support. By default, the application has two request types
defined: Sample Problem and E-Mail Report. The Sample
Problem can be renamed or deleted. Any new e-mail based
ticket is assigned to the E-Mail Report request type, which
cannot be deleted. Click on the New button to define another
request type. A request type can be defined at the top level,
CHAPTER 3
or as a child beneath any other level.
• In the sample above, the “Monitor” request type is de-
fined as child of the “Mac” sub-type, which is a child
of the “Hardware” parent, both of which were previ-
ously created.
• Assign the request type to a Tech Group (optional at
this point – can be assigned when tech groups are cre-
ated).
• Define the default priority that tickets of this type will
be assigned.
• Specify if a detailed description of the request is re-
quired in the ticket when the request type is selected
• Provide any detailed instructions you want to appear
for clients to follow when submitting the request.
• Create internal request types that are not visible to
clients by unchecking the Visible to Client option.
• By checking Model Required, a ticket with this
request type must have a hardware model or asset
selected by the client.
• Specify which Locations and Departments the request
type is visible from (default is “All”).
• Custom fields can be linked to the request type. The
default option is to display “None” – additional options
include “Specific” and “All”.
• Specify if attachments are allowed to clients for the
request type.
• Define if the request type should be used as a category
for FAQs.
Getting Started 9
• The Lead Technician will receive any top level escala-
tions for tickets of this type. If the request type isn’t
assigned to any Tech Group, the Lead Technician will
be assigned to tickets of this type automatically.
• Assign the survey to be linked to tickets using this
request type.
In the Request Type list view, you can expand a Parent/Child
grouping by clicking on the triangle icon next to the Parent
type name. Parents with no children will not have a triangle.
Status Types
Ticket status falls into two main states: Special and Other.
By default, the Web Help Desk defines the special states as
Open, Closed, Resolved and Cancelled. These types cannot
be deleted, but they can be re-named. The application creates
one “other” type by default: Pending.
The pending state can be deleted or re-named. You can also
add as many additional “other” states as you wish. There are
general settings to allow clients to re-open closed tickets and
to automatically close tickets that have been in Resolved state
for a particular time period.
Approval status types will be covered in more detail in
Chapter 8: Approvals Management. By default, all approval
status types use Open.
The status type detail editor includes options to use the status
in calendars, load balancing during ticket auto-assignment
(see Chapter 5: Tickets > Ticket Assignment Logic), enabling
client reminders, counting “open” time, enabling alerts, and
to determine if the type is shown by default in the Home >
My Tickets and Group Tickets view.
CHAPTER 3 Getting Started 10

Assets
Asset Options
Specify if asset numbers should auto-increment, set view/
editing permissions for technicians and enable expiration
Priority Types & Alerts e-mail messages to be sent to a specified Tech. Enable asset
The application defines four priority types by default: Urgent, discovery integration (see Chapter 7: Asset Discovery for
High, Medium and Low. Additional priority types can be cre- more information).
ated and the names and display order for each priority can be
changed. Each priority type has its own set of Alert Condi-
tions that are used in conjunction with a ticket’s status to
determine what the current alert status is. When a condition
in each alert level is reached, you have the option of trigger-
ing e-mail events, sending a message to the assigned tech, the
tech’s supervisor or the group manager for the ticket’s request
type. The alert repeat interval can also specified for each
priority type.

Each priority has a “Due Time” value that is used by a ticket

to automatically calculate the due date and time. The due date
Custom Fields
and time can be overridden within each ticket if desired.
Define custom fields and specify view/editing permissions for
techs.

Tip: If the status type for the ticket has alerts disabled, no alert level changes will be
observed regardless of the alert settings.
Asset Types
The application defines a single Sample Type asset type by
default. To add additional types, click on the New button at
the bottom of the list, or click on an existing type to edit. Use
Asset Types to categorize your assets — common types in-
clude: Desktop, Laptop, Printer, Software, etc. Each type can
also be linked to one or more of your defined custom fields.
CHAPTER 3
Status Types
Define the various states that an asset can be categorized
with. Common types include: Deployed, Storage, Donated,
etc. Any status type can be additionally flagged as “Retired”
which means that assets using this status won’t be available
for use in new tickets.
Warranty Types
Specify the warranty options available for your models. War-
ranties can be named whatever you like, and the expiration
can be defined in days, weeks, months or years.
Lease Types
Leases are only used in purchase orders (POs) for orders de-
fined as “Lease” (vs. “Purchase”). The lease periods defined
in this tab are available in the PO, and the period is used by
any assets linked to the PO to calculate their lease expiration
date.
PO Custom Fields
Define custom fields and specify view/editing permissions
for techs. These fields may be of text, multiple choice, single
choice or popup in nature. If the type is text, the height and
width of he line may be specified as well as the maximum
number of characters allowed.
Getting Started 11
Location
Location Custom Fields
Define custom fields for both Locations and Departments and
specify view/editing permissions for techs.
Tip: Client permissions cannot be set for location or department custom fields
because they are never visible to clients.
Billing
Options for Billing are available only if Parts and Billing
is enabled in Preferences > General > Global Options. There
are five sub-tabs available: Invoicing, Custom Logo, Billing
Rates, Billing Terms and Tax Rates. Billing preference values
are used in calculating ticket cost and for invoicing. Invoic-
ing > Preferred Client Contact Info controls which address
will be used on the invoice: “Help Desk” uses the Client’s
assigned Location address, while “Personal Address” will
use the address defined in the client’s profile. Tabs to upload
a logo, define billing rates and billing terms are also avail-
able. Define any tax rates to be applied on invoices. Taxes
can be applied to either labor, parts or both.
Tip: Your logo will be automatically scaled to a width of 3 inches in the PDF file. A
medium to high resolution file is suggested.
CHAPTER 3 Getting Started 12

E-Mail should be a dedicated account for use by the Web Help Desk.
Sending E-Mail
The Web Help Desk can send and receive e-mail notifica-
tions. In order to send e-mail, the you must provide the fol-
lowing settings:
• SMTP server address
• Helpdesk e-mail address (the “from” address for all
mail)

Other options include a setting to send mail in either plain

text or HTML format. You can also specify if clients can see
an estimated due date for the ticket, and show or hide action
links which allow clients to update or cancel a ticket via
e-mail. Additional options include the ability to set the order-
ing of information in the mail message (Client info, Ticket
info, Notes), and specify how many notes should be included
in the mail message. See the help pop-up items for a more
detailed description of each option.
WARNING: DO NOT use your personal mail account as the receiving e-mail box.
Once the application connects, all mail in the account inbox will be processed and
DELETED.
Custom Greetings
Create customized greetings for your mail messages. Greet-
ings are linked to specific ticket status types. SMS mail text
can also be customized. Greetings may contain application
specific “tags” for personalization and customization. The
full list of supported tags is listed at the bottom of the panel.

Tip: Outlook 2007 users should select “No Images” for the Image Format option if
using HTML formatted e-mail. The HTML renderer in Outlook 2007 is no longer web
standards compliant which causes rendering problems.

Receiving E-Mail
In order to receive and update tickets via e-mail you must
provide:
• E-Mail address for submitting tickets (POP or IMAP)
• Mail server address
• Account user name and password

The account is checked for new mail every minute and

CHAPTER 3 Getting Started 13

Techs Permissions
All new Tech (non Admin) accounts inherit the permissions
This module is used to create new Tech/Admin accounts and
defined in Preferences > Users > Default Tech Permis-
to link techs with specific request types by creating Tech
sions. These values can be left as is for the new account, or
Groups. Click on the Techs tab to work with this module.
they can be edited to customize the behavior for each Tech.
Administrator accounts always have full access. Permissions
Technician List
are divided into five main sections: Location, Ticket, Client,
The application installs a single Administrator account which Asset and Other.
can be edited but not deleted. Click the New button to create
a new Tech or Admin account, or click on an existing name
to edit the account.

Account Info
Provide name and contact information for the account and
define the account type. If creating a Tech account, you
must provide a Supervisor, which can be either an Admin
or another Tech. When a ticket is overdue or escalated, the
assigned Tech’s Supervisor may receive an e-mail. You may
optionally specify a weekly work schedule. The schedule is
used when determining if a technician is available for the
auto-assignment of tickets. A backup tech can be specified to
receive any auto-assigned tickets when the tech is unavail-
able due to schedule or vacation. Tech Groups
Assign the Tech to one or more Tech Group Levels. You
must have already defined your Tech Groups and Tech Group
Levels to use this tab.

Location Groups
Assign the Tech to one or more Location Groups. You must
have Locations and Location Groups setup before you can
use this option.

Department Groups
Assign the Tech to one or more Department Groups. You
must have Departments and Department Groups setup before
you can use this option.
CHAPTER 3 Getting Started 14

Tech Groups
The main purpose of creating Tech Groups is to match a
group of related Request Types with one or more Techs who
are qualified to handle the requests in the group. Tech Groups
must have at least one Level. Tickets always enter a group at
Level 1, and can be auto-assigned to a tech, the group man-
ager the request type lead. Ticket assignment can also be set
to “none” so that group members can self-assign tickets from
a queue of tickets.

Tech Group List

Selecting the Tech Group sub-menu option presents a list
of your groups. By default, the application has one group:
E-Mail Reports. This group contains only the E-Mail Report
request type and cannot be deleted. To create an additional
group, click on the New button, or click on an existing group
name to edit.
Tech Group Levels
To function, a Tech Group must have at least one level
defined. In the level editor, specify auto-assignment rules, e-
mail recipients for client updates, default e-mail recipients for
tech updates and select which techs are members of the level.

Tech Group Info

Provide a group name and specify a Group Manager. This
can be either a technician or administrator account. The
group manager receives escalations above the highest Tech
Group Level. Optionally, manager level escalation can be
sent to the ticket’s Location Group Manager by selecting
the precedence checkbox.
Request Types Supported
Specify the request types for the group. A request type can
only be assigned to one Tech Group. As request types are
assigned, they disappear from the list of available types.

E-Mail ticketing can also be enabled at the tech group level.

This feature allows you to define a unique mailbox for the
tech group. Any new messages delivered to this mailbox will
have tickets created based on the assignment rules defined at
Level 1 for the tech group and will use the default “E-Mail
Request Type” set for the group.
CHAPTER 3 Getting Started 15

Locations Room Editor

If Preferences > General > Use Rooms is enabled, rooms
Click on the Locations tab — this module is used to define
can be linked to the Location by clicking on the Room Edi-
support locations and to organize locations into Location
tor tab. Add rooms by clicking on the New button at the bot-
Groups. Departments and Department Groups are also
tom of the list. Remove rooms by clicking the trash can icon
configured under this tab if enabled at Preferences > Gen-
on the room’s row.
eral > Global Options > Use Departments. Locations can
also be imported using the Location Importer.

Location List
The application defines a single Sample Location at instal-
lation. To add an additional location, click on the New button
at the bottom of the list, or select the name of an existing
location to edit.

Approver Roles
Link specific clients to each Location Approver Role de-
fined at Approvals > Approver Types. For further informa-
tion on using Approvals, see Chapter 8: Approvals Manage-
ment.
Location Info
Provide a name and optional address for the location and
specify a Business Zone (time zone). Each location can be
assigned one or more Administrative Contacts — a Client
account that can view all tickets for the location, as well as
create tickets for themselves or other clients at the location (if
enabled). Admin Contacts may be given editing permission
on all tickets for the location and can also be sent a copy of
all e-mail updates sent to clients at the location. If billing is
enabled, the location can be designated for parts storage, and
a default billing rate can be specified. To facilitate service
level agreements (SLAs), a default priority for the location Service Time Blocks
can be defined. Tech note work time can be displayed to Define a service level agreement that is constructed around
clients at the location. blocks of time under (Service Time Blocks must be enabled
under Location Info for each specific Location). Assign a
fixed block of time to a location and an expiration date for
that block. As techs book time to the location, the balance of
available time is displayed. For further information on using
Approvals, see Chapter. 10: Parts and Billing.
CHAPTER 3 Getting Started 16

Location Groups
This sub-module is used to define groups of Locations and
link them to the Techs that will handle their tickets. The
application defines a single Sample Location Group at
installation, to which the Sample Location was added. To add
an additional location group, click on the New button at the
bottom of the list, or select the name of an existing group to
Tip: If you wish to have jobs routed to a different Tech for every location, you must
edit.
create a separate Location Group for every location. Only group locations together if
you want the Techs in the group to handle jobs from multiple locations.

Group Name
Name the location group and assign a Group Manager. The
group manager can be any a tech or an administrator, and
will receive “Manager” level escalations if the ticket’s Tech
Group specifies Location Group Manager escalation prefer-
ence.
Departments
This module is only available if Preferences > General >
Global Options > Use Departments is selected. Using the
Department List add new departments.
Department Info
Define the department name and optionally assign one or
more “Administrative Contacts”. Specify editing permissions
and e-mail settings for the Admin Contacts.

Assigned Locations
Define the locations for the group. Each location can only
be assigned to one group. As locations are assigned, they
disappear from the list of available locations. To remove a
location from the group, click the small trash can icon on the
location’s row.

Approver Roles

Link specific clients to each Department Approver Role de-

fined at Approvals > Approver Types. For further informa-
tion on using Approvals, see Chapter 8: Approvals Manage-
Assigned Techs ment.
Use this tab to assign the technicians to the group. A techni-
cian can be in any number of location groups. To remove a
tech from the group, click on the small trash can icon in the
tech’s row.
CHAPTER 3 Getting Started 17

Department Groups Model Editor

Add models for the manufacturer under this tab. You must
Use this sub-module to define groups of Departments and
provide a model name and an asset type and default war-
link them to the Techs that will handle their tickets.
ranty period. If you need to add additional asset and warranty
types, go to Preferences > Assets and edit the appropriate
type tab. You can also upload file attachments that relate
to the model. These attachments will show up in any asset
records that utilize the model.

Assets
The Web Help Desk can be used as a complete asset manage-
ment solution, however if you want to include basic asset
information in tickets, you must at minimum define Asset
Types, Manufacturers, and Models. Chapter 6: Asset Man-
agement deals with this topic in detail.

Models
Tip: Manufacturers and models are added automatically when using the Asset
Use this sub-module to define the models your help desk will Importer. If you plan on importing assets, you may want to hold off creating your
support. Before adding specific models, you need to create manufacturers and models and let the importer do it for you. You will still need to go
Manufacturers to link the models to. The application defines back to each entry and fill out details using the web interface.
a single Sample Manufacturer by default. To add a new
manufacturer, click on the New button at the bottom of the
list, or click on the name of an existing manufacturer to edit.

Manufacturer Info
Provide a manufacturer full name and short name — the
short name is used in all drop down menus for any models
linked to the manufacturer. Any additional information be-
yond the full and short names is optional.

Chapter 4: Managing Clients
Manual Web Entry
Individual clients are added to the application by going to the
Clients > Search Clients and clicking on the “New Client”
button at the top of the search results list, or the “New” but-
ton on the lower right of the list.
Client Info
All clients must have at least a last name and an e-mail
address to be saved successfully. A client can be assigned
to a primary location, room and department. Once the cli-
ent record is saved, the client can be assigned to additional
rooms. Personal address information can be stored in the
client record – expose the fields by clicking on the triangle
in the label row. By default, clients log in using their e-mail
address, but clients may instead log in with a user name if
enabled at Preferences > Users > Client Options > Client
Login Attribute. New account confirmation is mailed to the
client if enabled at Preferences > Users > Client Options >
E-Mail Client When Account is Created.
Tip: Passwords for web entry clients are created automatically using the value set at
Preferences > Users > Client Options > Password Reset Value, or the value can
be set manually.
18
Assigned Assets
View client assets under the Assigned Assets tab. Click the
hyperlinked asset number to edit the asset details, or use the
asset discovery buttons (enabled at Preferences > Assets >
Asset Options).
Ticket History
A complete history for the client is available under the Ticket
History tab. Entries can be sorted by column header and de-
tails are viewed by clicking on the hyperlinked ticket number
or request detail.
Data Import
Importing is an efficient way to populate your client list.
The import is facilitated by a template available at Clients >
Import Clients. Click on the Download Template link and
open the client_import_template.txt file in Excel. When
adding client rows to the spreadsheet, it is very import to
leave the column header and all columns in order and intact.
If you do not wish to import data for a particular column, it
is fine to leave the cells empty for the column. If you delete
the headers, columns, or change the column order, the import
will receive an error message. When e-mail is the client
login attribute, there are two required columns for any client
import:
• Last Name
• E-Mail Address
The importer adds a new client for each unique e-mail ad-
dress it encounters and synchronizes data based on the sync
key you select. The sync attribute is client e-mail address
by default, but you can also choose user name or one of your
custom fields. If you have Location, Room or Department in-
CHAPTER 4
formation contained in the data file, the importer creates new
Locations, Rooms and Departments for any uniquely named
values if the “Add New Entities” option is selected.
Once your template is prepared, make sure to save as the file
as tab or comma delimited, then use the Choose File button
to navigate to your file. Click the Import button to upload
the template and import the clients. When the upload is com-
plete, go to Clients > Search Clients to check your upload
results.
LDAP Synchronization
The Web Help Desk can be configured to use multiple
LDAP directories as a source for client data. To optimize
performance, the Web Help Desk downloads client data
from the LDAP directory to the Web Help Desk database;
consequently, changes to LDAP data require the Web Help
Desk database to be re-synchronized. Synchronization can be
performed manually or at scheduled intervals.
Creating an LDAP Connection
LDAP connections are specified at Clients > LDAP Connec-
tions. To create a new LDAP connection click on the New
button or click on an existing LDAP connection name to
edit. In the Connection Basics, provide an optional connec-
tion name and the required host and Base DN parameters for
the LDAP connection. If the LDAP directory is a Microsoft
Active Directory, be sure to select the Microsoft Active
Directory checkbox. You can also select SSL for secure con-
nections and several authentication options are available.
Managing Clients 19
Tip: For most directories anonymous access is all the Web Help Desk requires to im-
port your client data. Active Directory, however, requires authentication to read the
directory. The connection account should look like admin@yourdomain.com, where
the domain name matches the dc values in your Base DN. You must also provide a
password for the account.
LDAP synchronization does not import any passwords into
the database, so your directory must store password infor-
mation if you want to use it with the Web Help Desk. To
authenticate your clients, the application performs an LDAP
bind with your directory passing the user supplied password
as part of the bind.
Tip: There is an option to ignore all client passwords, which is helpful if your directory
doesn’t store passwords and client privacy isn’t an issue. See this FAQ for more
information: http://support.webhelpdesk.com/cgi-bin/WebObjects/Support.woa/wa/
FaqActions/view?action=70050002baa94921&id=1.
Mapping Attributes
Besides importing basic client information, LDAP synchroni-
zation can also be used to map values stored in your directory
to Web Help Desk entities like Location and Department or
to custom fields. To map these attributes, select an LDAP
connection, then click on the Attribute Mappings tab.
You may select to use either the default schema (user for
Active Directory, inetOrgPerson for others), or a custom
schema. If a custom schema is selected, a popup menu will
appear containing schemas provided by the LDAP directory.
The LDAP attributes to which the Web Help Desk entities
may be mapped are determined by the selected schema.
Clients can log into the Web Help Desk using either e-mail
address or a user name as defined in Preferences > Users
> Client Options > Client Login Attribute. If a custom
schema is selected, name, e-mail, and phone attributes may
CHAPTER 4 Managing Clients 20

be mapped; otherwise, these attributes are automatically

mapped to the givenName, sn, mail, and telephoneNumber
attributes of the default schema.

Synchronizing LDAP Connections

Once an LDAP connection has been defined, you must
Tip: If your LDAP does not define separate first and last name attributes, but synchronize it with the Web Help Desk database. Although
combines them into one, choose a Custom schema and the Full Name option in the password authentication is initially performed directly against
Name Attribute. The last word in the name value is used for the client’s last name and the directory using an LDAP bind, all other client data is ref-
the rest of the value is used for the first name. erenced from cached copies contained within the Web Help
Desk database. You can perform a manual synchronization of
The location, room, and department attributes have
the LDAP data by clicking on the Sync Now icon in the list
checkboxes indicating whether new corresponding entries
of LDAP connections. If more than one LDAP connection
should be added to the Web Help Desk database if they don’t
has been defined, an additional synchronization icon is pro-
already exist. In order for the LDAP location, room, and
vided in order to sync all connections at once. You may use
department data to map to existing Web Help Desk entities,
the Auto-Sync Schedule setting of each LDAP connection to
the values of the LDAP attributes must exactly match the
define when automatic synchronizations should take place.
names of the mapped Web Help Desk entity. For example,
if mapping the LDAP “l” attribute to the Web Help Desk
Location entity, you must be sure that you created your loca-
tions with the exact same names as the “l” entries in LDAP.
Note that once new location, room, and department entries
have been added, they will not be modified by subsequent
LDAP synchronizations. Optionally, you can specify that
clients are assigned a “Fixed Value” for Location and Depart-
Tip: You can combine LDAP sync with client import to populate values that are not
ment. The Location and Department used must already be available in your LDAP directory. For example, if your LDAP directory only stores
created in order to map the fixed value. client name and e-mail, you can still use it to create WHD client accounts for authen-
tication. To populate values like Location, Room and Department, you can use an
Some LDAP implementations do not allow the discovery of import template and sync to the client’s e-mail address or user name.
Schemas and Attributes. In that case, the “Detect Schemas
& Attributes” button will not be shaded, and the drop down
menus will be replaced with text fields where mappings can
be entered manually.
 21

Chapter 5: Tickets
Web-Based Ticketing
New tickets are created at Home > My Tickets or Group
Tickets and Tickets > Ticket Search. Click on the “New
Ticket” button at the top-left of the list or the “New” button
on the bottom-right of the list.

Client Info
By default, new web-based tickets open to the Client Info
tab. Tickets do not require a client, unless specified at Prefer-
ences > Tickets > Client Required. Use the “Client Look-
up” search panel to find clients by name, user name, e-mail,
phone, location or department. Search results are displayed
below. To assign the client, click on the hyper-linked name.
If only one match is found for the search criteria, that client is
automatically assigned to the ticket without having to select it
from the list.
Tip: To search by partial name or e-mail, use an asterisk (*) as a wildcard.
Asset Info
Click on the Asset Info tab to link an asset to the ticket, or
supply a model if a defined asset is not available. An asset
or model is not required in a ticket. If assets are disabled at
Preferences > General > Global Settings > Use Assets the
Asset Info tab will not be visible.
Any assets assigned to the ticket’s client are displayed in the
middle of the panel. Assets can be looked up by asset num-
ber, serial number, model, location, room or custom field. To
assign an asset, click on the hyperlinked asset number. The
assigned asset can be edited by clicking the edit button to the
far right of the “Ticket Assets” row. To remove an assigned
asset from the ticket, click the trash can icon at the right side
of the asset row. The blue “info” icon displays additional
information about the asset when rolled over by the cursor.
Multiple assets can be assigned to the ticket.

Once a client is selected, his/her contact information is

displayed in full on the upper left section of the Client Info
panel. If a mistake was made, you can click the “Clear” but-
ton to remove the client assignment. The client record can be
edited in a popup window by clicking the “Edit” button next
to the client name.

In addition to client info, a ticket history for the assigned

client is displayed on the right side of the panel. If an issue
has already been reported in a previous ticket, clicking on the
ticket number or problem report replaces the new ticket with Tip: A ticket is not required to have an assigned asset or model. If the issue you are
the selected one. The history can be filtered by status. reporting doesn’t need this information, the Asset Info tab can be skipped entirely.

To remove the assigned client from the ticket, click the “Un-
assign Client” button.
CHAPTER 5
Ticket Details
Saving a New Ticket
The Ticket Details panel is where you define the ticket’s
request type and provide a subject and request detail. The
ticket’s Location and Room can be specified here as well —
if the assigned client or asset had location information, that
will already be reflected in this panel. A request type and
description are required before the ticket can be successfully
submitted. You may also create a tech note with time and bill-
ing info for the ticket, and set the job status. By default, the
Level 1 assignment rules for the ticket’s Tech Group will be
used, but the tech can use the “Myself” option to override the
assignment. However, if the ticket status is set to “Closed”
the ticket is automatically assigned to the current tech regard-
less of any auto-assign rules in effect. Recipients can be
added at the bottom of the panel.
Assigned Tech and Escalation
If the ticket’s request type belongs to a Tech Group, and
auto-assign is enabled for Level 1 of the group, the applica-
tion will assign a technician to the ticket using load balanc-
ing. The ticket can be escalated to the next level by clicking
on the escalation widget which displays the current Tech
Group Level. If the ticket is already escalated to the high-
est level number, further escalation assigns it to the Tech
Group Manager (or Location Group Manager if specified in
Tickets 22
the Tech Group settings). If the manager is already assigned
to the ticket, it will be escalated to the Lead Technician for
the ticket’s request type. If auto-assign is disabled for Level
1, the ticket will not be assigned to a specific tech, but will
belong to the tech group level’s pool of tickets. For more
information on ticket workflow, see Ticket Assignment Logic
at the end of this chapter.
Status & Schedule
All new tickets are assigned with the “Open” status type, and
the ticket’s priority is set according to the value specified in
Preferences > Tickets > Ticket Options. The priority may
also be set based on the ticket’s request type or location. If
both location and request type have a default priority setting,
the location priority takes precedence. The due date is calcu-
lated based on priority, but can be manually overridden. If the
priority is changed, the due date is re-calculated on the fly.
The ticket can also be scheduled for work at a specific date
and time range – due dates and scheduled dates are displayed
in the calendar view (web and iCalendar). Required approv-
als are displayed, and can be listed by clicking Approvals
button in the panel.
Ticket Notes
Technicians add information to a ticket using a tech note. A
ticket can have any number of notes, and notes can be added
by any technician. Notes can contain basic HTML tags or
BBCode tags for formatting. Notes are date and time stamped
when saved and the tech who entered the information is
automatically associated with the note. The amount of time
that was spent on the work can be added to the note using the
“Work Time” fields. By default, notes are visible to clients
and are colored blue. Notes can be hidden from clients, and
appear gray in color. A note defined by the tech as a “Solu-
CHAPTER 5
tion” is colored green. Clients can also add notes, which
appear yellow.
If Preferences > General > Global Options > Parts &
Billing Enabled is checked, a billing rate for the work can
be specified. If the ticket’s location has a billing rate set,
new tech notes will use it by default. A tech note can also be
used to create a new FAQ — the request detail is used as the
question and the tech note is used as the answer. New FAQs
created from tech notes are set to “Unapproved” status by
default and use the ticket’s request type as the FAQ category.
Tip: Clicking the “Save” button at the bottom of the ticket will save any open tech
note as well as any changes made to other ticket fields. A tech note can be saved
independently from the rest of the ticket fields by clicking the note’s “Save” button.
Using FAQs in Notes
A link to an existing FAQ can be embedded into a tech note
using the “Insert FAQ Link” button when editing the note.
Clicking this button opens a FAQ search popup window.
Once the FAQ you wish to link is found, click the “Link”
button on the right side of the FAQ row. This copies a link
tag into the current tech note. If you happen to know the FAQ
number by memory, you can skip the lookup and enter the
tag yourself. The format is: <faq id=x> where x is the FAQ
number.
Ticket E-Mail Recipients
E-mail to the client, assigned technician, level techs, group
manager or other addresses via the Cc: and Bcc: fields can be
Tickets 23
sent when the ticket is saved. Select the recipient checkboxes
and add Cc: or Bcc: addresses (comma separated) if neces-
sary, then click the “Save & E-Mail” button. No mail is sent
when clicking the “Save” button. Clicking the padlock icon
makes the FAQ private and not able to be viewed publicly.
Other Ticket Options
Problem Tickets
A ticket can be designated as a “Problem Ticket” by click-
ing on the “Ticket Type” widget in the Details section of the
Ticket Details panel and selecting “Problem.” Once a ticket
has been designated as a problem, other tickets related to the
problem ticket can be linked. When the problem is resolved,
closing the problem ticket will automatically close all linked
child tickets.
To view the current problem tickets, click on the “Problems”
tab on the right side of the ticket detail. Clicking on “Link”
will make the current ticket a child of the selected problem
ticket, while the “View” hyperlink replaces the detail view
with the selected ticket. The linked child ticket is auto-
matically changed to an “Incident” type in the Ticket Type
widget.
CHAPTER 5
A ticket with a linked parent problem ticket adds a row in the
Ticket Details to display the parent ticket number. The link
can be broken by clicking on the trash can icon. Clicking on
the ticket number switches you to the parent problem ticket.
Print View
To display the ticket information in a printer-friendly view,
use the “Print” button at the top of the ticket. Clicking the
button opens the ticket in a window suitable for printing.
Additionally, access to tickets (as well as Assets and Clients)
is controlled by the two “Location Access Permissions”:
Editing Permissions
Administrators are free to re-assign technicians, change
ticket status and delete tickets. Technicians can have various
levels of access depending on their individual preferences set
by an Administrator. Any newly created technician inherits
the permissions defined in Preferences > Users > Default
Tech Permissions. These defaults may be overridden by an
Administrator by editing the permissions of an individual
technician record. The ticket related preferences are:
• Limit to Assigned Tech Groups allows the tech to
Tickets 24
create, view and edit tickets belonging only to Tech
Groups to which the tech is assigned.
• Change Others’ Ticket Status allows the tech to
change the status of tickets not assigned to themselves.
• Edit Ticket Dates enables the changing of the report
and close dates on a ticket.
• Edit Problem Report and Client Notes allows the
tech to update the text of the reported issue and in cli-
ent created notes.
• Allow Re-Assignment enables the tech to re-assign the
ticket to any other tech. Disabling this option allows
the tech to only re-assign jobs to themselves.
• Change Priority allows the tech to change the prior-
ity of tickets assigned to themselves or, if Edit Other’s
Tickets is enabled, the priority of any ticket.
• Close Tickets enables the tech to set tickets to the
“Closed” status type.
• Delete Tickets exposes the ticket “Delete” button to
the tech.
• Import Tickets allows the tech to access the Tickets >
Import Tickets module.
• Edit Tasks allows the tech to create and edit tasks cre-
ated at Tickets > Task Manager.
• Limit by Location Group allows the tech access only
to those tickets, clients and assets that are in assigned
Location Groups. Note that tickets, clients and assets
that have no location assigned are also accessible.
• Limit by Department Group allows the tech access
only to those tickets, clients and assets that are in as-
signed Department Groups. Note that tickets, clients
and assets that have no department assigned are also
accessible.
CHAPTER 5 Tickets 25

E-Mail Ticketing must have a default “E-Mail Request type” defined for tickets
created from that mailbox.
Reporting by E-Mail
Tickets can be created by sending an e-mail message to the
dedicated help desk e-mail address. A ticket is created for
each new message sent to the address provided the sender’s
e-mail address exists in your Client list. If the sender is not
a registered user of the application, the sender can be added
to your client list along with a new ticket, or an error e-mail
can be sent in reply. Preferences for handling e-mail tickets
are located at Preferences > E-Mail > Receiving E-Mail.
All settings in this panel are ignored unless “Enable E-Mail
Tickets” is checked. All tickets created from this mailbox are
designated as an E-Mail Report request type and therefore
belong to the E-Mail Reports tech group.

Updating by E-Mail
Clients receive an e-mail confirmation on e-mail tickets
based on the preference set at Preferences > Tickets >
Ticket Options > Auto-Reply to Client. “Action links” can
be enabled in the e-mail reply which allow the client to add
notes or cancel the ticket. Action links are enabled at Prefer-
ences > E-Mail > Sending E-Mail > Include Action Links
and appear as buttons in an HTML e-mail or as hyperlinks in
plain text e-mail messages. It is important that an e-mail re-
ply has its subject line left intact, as the Web Help Desk uses
the subject to determine if the e-mail triggers a new ticket or
an update to an existing ticket. Only the client that created
the ticket or a client that has been carbon copied (Cc:) on the
The e-mail account may be either POP or IMAP (Exchange
ticket can update it via e-mail. If enabled, any files attached
Server must enable IMAP), and can connect via SSL if
to the message are added to the ticket as attachments.
required. The receiving preferences can be configured to
ignore requests coming from a list of accounts – several are
created by default at installation. E-mail may also limited to
particular domains. Both the subject and body of the message
can be filtered by regular expression to reject unwanted mes-
sages (out of office replies, for example). When “Create New
Tickets From Replies” is enabled, the application will parse
the subject of the e-mail to determine if the message is in
response to an existing ticket, and if so, append the message
body as a note. Please pay special attention to the popup
help related to this setting.

E-mail tickets can be targeted to a specific tech group by

enabling a separate mailbox for each tech group. Select the
checkbox at Techs > Tech Groups > [select a group] > En-
able E-Mail Tickets to expose e-mail receiving preferences
for that group. The e-mail address must be different from the
one specified in the general e-mail receiving preference, and
CHAPTER 5 Tickets 26

Techs can also update tickets by e-mail. In addition to adding

Task Management
notes, techs can change the status of the ticket by clicking on
one of the status links at the bottom of the message. This will Creating Tasks
create a reply e-mail with a pre-formatted subject line the ap-
A Task is a container for one or more ticket templates called
plication uses to carry out the action. For example:
“Elements”. A task can be scheduled to repeat at daily,
Ticket:1532 Action:TechUpdate Hidden:NO Status:Pending EmailClient:NO monthly or yearly intervals. A task may also have a Client as-
Reassign:sally@mycompany.com MinutesWorked:30 BillingRate:Standard sociated with it — the Client would be assigned to all tickets
created by the task. To create a new task, go to Tickets >
This subject tells the application to add the body of the mes- Task Manager. Click the “New” button at the bottom of the
sage to ticket 1532 as a tech note visible to the client, change Task list.
the status of the ticket to “Pending”, don’t send the client
an e-mail confirmation, reassign the ticket to another tech
(Sally), set the work time for the note to 30 minutes and the
billing rate to “Standard”. To use the “reassign” option in the
subject, you must supply the full e-mail address of the tech.
The specified billing rate must match an existing rate name.
If the tech is an administrator, a “Delete Ticket” button is also
available in the e-mail message.

At a minimum, the Task must have a name in order to be

saved. If tickets created by the task should have a client as-
signed, use the search feature to find and select the assigned
client. Selecting “Yes” for the Scheduled option exposes a
Start Date field and a frequency selector. A scheduled task
can be made repeating or can be run once and deleted.

Task Elements
To add an Element to the Task, click the “New” button at the
bottom of the Element list. To save the Element, you must
provide a request type, subject and detail for the ticket to be
created. Optionally, location, room, department, technician,
priority and asset number can be added. If the Task needs to
create multiple tickets when triggered, continue adding ad-
ditional Elements as needed. The tickets generated from task
elements can be created all at once, or after the ticket for the
previous element reaches some status type. Use the “Gener-
ate Next Element” option to specify when the next element’s
ticket should be created.
CHAPTER 5 Tickets 27

To edit a ticket, click on the hyperlinked ticket number or

request detail text in the search results list. After saving any
changes to the ticket, clicking the back arrow button on the
save confirmation dialog returns you to your previous search
results list. You can also return to the search results by using
the back arrow button on the top left of the ticket detail or by
clicking the “Cancel” button at the bottom of the ticket.

Triggering Tasks
Tasks run automatically on their scheduled date or they can
be triggered manually using the green “Play” button next to
the task name. Running a scheduled task manually will set
the last run date to the current date, and set the next run date
based on the schedule interval.
Tip: Shift-clicking on the save button in a ticket will both save and return you to the
ticket list view. Alt-clicking will save the ticket and create a new one.
Refining Search Results
The search results list can display a large amount of ticket
data. To control what information is displayed use the
Column Set widget to control column visibility. The widget

Search Tickets
Tickets > Search Tickets provides two search options: Basic
or Advanced mode. Basic searching is a simplified sub-set
of the search criteria available in the advanced search mode.
is located at the upper right corner of the search results list.
Click the “+” button to add a new set, or the pencil button to
edit the selected set.

Column sets are saved individually for each Tech by name.

Each column set can specify a different PDF download op-
tion (Invoice or Ticket format) and full text option.
Search results are sorted by clicking on a column header. The
sort order of a column is reversed by clicking on the header
again. Sorting is performed using the last 3 column head-
ers selected. Download the search results in PDF format by
clicking on the Tickets PDF button, or download the results
as a tab separated text file suitable for viewing in a spread-
sheet by clicking on the Download TSV button. The buttons
will act on a subset of the search results checked off in the
left column.
CHAPTER 5 Tickets 28

Saved Queries
Search criteria that you plan to re-use can be saved as a
named query using the Advanced Search tab. To save a query,
define your search criteria, then provide a name in the “Save
Query as:” field. By default, a query can only be seen by
technician who creates it. Selecting the “Shared” checkbox
allows all techs to use the query. Shared queries have an *
after their name.

To run a query, select the query name from the Query drop
down list at the top of the search results display. The query
will be run automatically upon selection.

To re-run the same query, use the “play” triangle. To remove

the selected query from the list, click on the “-” button. To
subscribe to an iCalendar made up of tickets captured by the
query, click on the calendar button.

Tip: In Advanced Search mode, you can use the Technician, Status and Priority
select list options to search for multiple criteria in your search or query.

Ticket Bulk Actions

Bulk actions allow you to run a saved set of ticket changes
against one or more tickets in a search results list. To create
an action, click the “+” button. To run a saved action, select the left column checkbox for
one or more tickets from the search results list, then choose
the appropriate action from the popup menu. Click the “Play”
triangle — you will receive an alert that summarizes what
changes will be made to the selected tickets with a chance to
A bulk action template looks similar to the Ticket Details cancel the action.
tab of a normal ticket. The template allows you to assign a
client, create a tech note, change status, etc. — any set of
values you can change in a normal ticket can be specified
in the bulk action template. Once changes have been made,
you have the option of running the action against any tickets
you’ve selected from the search results list without saving the
template, or you can save the template by name to be run at Tip: To select all the tickets in the search results list, click on the small checkbox in
the column header for the selection column.
any time in the future. Bulk actions can be private or shared,
and can be edited and re-named.
To edit an existing bulk action, select the action from the
popup menu, then click the pencil button.
CHAPTER 5 Tickets 29

Quick Tickets
To save time creating tickets for common issues, the “Quick
Ticket” popup menu is available for new tickets. Quick Tick-
ets are defined using a template very similar to a bulk action,
with a few added options appropriate for new tickets like
the ability to specify a subject and request detail. On a new
ticket, Quick Tickets are created and run using the widget at
the lower left of the new ticket detail panel.

Typically the technician would lookup a client to assign to

the ticket, then run the Quick Ticket action.

To add a new quick ticket action, click the “+” button. Edit
the selected option by clicking the pencil icon, or run the
selection by clicking the “play” triangle.
CHAPTER 5 Tickets 30

Ticket Assignment Logic

New Ticket

Is the Ticket's Assign to Lead

Requset Type in a Tech for the
Tech Group? No Request Type*
Techs > Tech Groups Preferences > Tickets > Request Types
> [Group] > Request Types
Web Help Desk Supported
> [Request Type] > Lead Technician
Yes
Ticket Assignment Logic

Level 1 Place in pool of

Auto-Assign tickets for Tech Techs > Tech Groups > [Group] > Level 1
Tickets No Group Level 1 > Assigned Techs
To set whether all level techs, the group manager
Techs > Tech Groups
only, or no one gets an e-mail, see Techs > Tech
> [Group] > Tech Group Levels >
Yes Groups > [Group] > Tech Group Levels > Level 1 >
Level 1 > Auto Assign Tickets to
E-Mail Recipients of Client Updates

Lead Tech Group Manager

Assign to Lead
Assign to Manager
Tech for the Auto assign to?
of the Tech Group*
Request Type*

Preferences > Tickets > Request Types Techs > Tech Groups
> [Request Type] > Lead Technician > [Group] > Tech Group Info
Level Tech > Group Manager

May use Location Group Manager

instead if specified at Techs > Tech Groups
Get techs in
> [Group] > Tech Group Info
Tech Group Level 1

Techs > Tech Groups

> [Group] > Assigned Techs

Filter out any techs not

currently scheduled or on
vacation
Techs > Technician List Techs > Technician List
> [Technician] > On Vacation > [Technician] > Specify Work Schedule

Is the ticket's
Location in a
Location No
Group?
Locations > Location Groups
Yes > [Group] > Assigned Locations

Filter out any techs not in

the Location Group
* If the assigned Tech is
marked as "On Vacation"
Locations > Location Groups
> [Group] > Assigned Techs
the ticket is assigned to
the "Backup Tech"
for the original assignee.

To enable Departments, check

Preferences > General Is the ticket's
> Global Options Department in a
> Use Departments Department Group? No
Locations > Department Groups
> [Group] > Assigned Departments
Yes

Filter out any techs not in

the Department Group

Locations > Department Groups

> [Group] > Assigned Techs

Techs > Tech Groups

Are any techs Assign to Manager
> [Group] > Tech Group Info
remaining? of the Tech Group*
No > Group Manager

Yes

Assign to tech who has Specify which status types are used in load balancing
fewest load balance at Preferences > Tickets > Status Types > [Status Type]
tickets* > Use for Load Balance
 31

Chapter 6: Asset Management

Adding Assets Parent/Child Relationships
Once an asset has been inserted into the database, the option
Asset management is an optional extension to the Web Help
to create a Parent/Child relationship is available. Parent/Child
Desk. The asset management features can help keep track
relationships are a powerful way to group assets together. For
of what you own, where it is located and who is using it. In
example, you may issue several assets to an employee that
addition, the application can store purchase order informa-
you wish to group: computer, monitor, printer and scanner.
tion and link it to assets in your inventory. This combination
You could treat the computer as the “parent” while the other
makes it easy to know where you purchased your assets from
assets act as “children.” After adding all four assets to the
and when warranties expire. Using the integrated asset man-
system, return to the “parent” computer, and add the other
agement tools enhances the help request ticketing functional-
assets as children to it. Click “Edit” in the Child Assets tab
ity of the application, but it is not required. There are three
and lookup assets by number, type, serial number location
methods for adding asset information:
and room. Click the “link” hyperlink in the search results list
• Manual Web Entry to link the asset. Repeat the process for the other assets you
• Data Import wish to add as children. Children automatically inherit the
• Asset Discovery Integration (chapter 7) Location, Room, and Deployed values from the parent. If the
parent has only one assigned Client, the child will inherit that
Manual Web Entry as well. To remove a child asset from the list, click on the
trash can icon next to the child asset.
New assets are added by going to Assets > Search Assets
and clicking on the “New Asset” button at the top of the
Important concepts:
search results list, or on the “New” button on the bottom right
• A child asset can have multiple parents.
of the list.
• You cannot make an asset that has children (a parent)
into a child asset.
• Children will automatically update their location infor-
Asset Basics mation if the parent changes provided there is only
Asset basics are the “what, where, and who” of the asset. If one client assigned to the asset.
enabled at Preferences > Assets > Asset Options > Auto
Increment Asset No., the application will auto-enter an asset
number that increments your highest number by one. You
are free to change this number to match the actual value on
the asset you wish to add. Besides the asset number, the only
other required information is the model. An asset can have
one or more clients assigned. There is a check box to disable
the asset from being effected by Asset Discovery Synchroni-
zation.

Asset Details
Additional asset information can be added by clicking on the
Asset Details tab on the asset editor, then on the edit mode
button to display fields. There are several pre-defined fields
to store information, including serial number and version as
well as any custom fields defined in Preferences > Assets >
CHAPTER 6 Asset Management 32

Custom Fields. There is also the option to relate the asset

with a specific purchase order, or to enter the purchase date
manually. The warranty expiration date is calculated based on
the PO date (if a valid PO number is entered), or the manu-
ally entered purchase date, and the warranty type specified
for the asset. Models
For further information on using adding and editing “Mod-
els,” see Chapter. 3: Getting Started.

Import Assets
Importing is an efficient way to populate your assets. The im-
port is facilitated by a template you download from the Web
Help Desk. To download the template, go to Assets > Import
Assets. Click on the Download Template link and open the
asset_import_template.txt file in Excel. When adding asset
rows to the spreadsheet, it is very import to leave all columns
in order and intact. If you do not wish to import data for a
particular column, it is fine to leave the cells empty for the
column. If you delete columns, or change the column order,
your import will be stopped with an error message.
There are four required columns for any asset import:
• Asset Number (alphanumeric)
• Asset Type
• Manufacturer
• Model

Asset History
Lists the change history of the asset including: creation date,
location/room change, client add/remove, status change, sync
date. The history includes the date and the tech that made the
change.

The importer adds a new asset for each unique asset number
Ticket History it encounters and synchronizes data for any existing asset
Provides a list of all tickets created for the asset and provides matching a number in the import file. The importer adds new
a link to a ticket detail view for editing. asset types, manufacturers, models, locations, rooms and
CHAPTER 6 Asset Management 33

departments for any uniquely named values when the “Add
New Entities” option is selected. Otherwise, the importer
links the asset to the existing entities that match the names
provided in the file.
Once your template is prepared, save the file as tab or comma
delimited text, then use the Choose File button to navigate
to your file. Click the Import button to upload the template
and import the assets. When the upload is complete, go to the
Search Assets screen to verify your import.
Saved Queries
Search criteria that you plan to re-use can be saved as a
named query using the Advanced Search tab. To save a
query, define your search criteria, then provide a name in the
“Save Query as:” field. By default, a query can only be seen
by the technician who creates it. Administrators have the op-
tion of defining shared queries, and only an administrator can
delete a shared query.

Asset Discovery Integration

To run a query, select the query name from the Query drop
For further information on using the Asset Discovery feature down list at the top of the search results display. The query
of the WHD, see Chapter. 7: Asset Discovery. will be run automatically upon selection.

Search Assets
Searching can be done in either Basic or Advanced mode.
Basic searching provides a simplified sub-set of the search
criteria available in the advanced search mode.
To re-run the same query, use the round search button. To
remove the selected query from the list, click on the round
delete button.

Search results are sorted by clicking on a column header.

Download the search results in PDF format by clicking on Tip: In Advanced Search mode, you can use the Status and Priority select list op-
the Download PDF button, or download the results as a tab tions to search for multiple criteria in your search or query.
separated text file suitable for viewing in a spreadsheet by
clicking on the Download TSV button.

To edit an asset, click on the hyperlinked asset number. After

saving any changes to the asset, clicking the “OK” button
on the save confirmation dialog returns you to your previous
search results list. You can also return to the search results by
using the “Cancel” button at the bottom of the asset detail.

Refining Search Results

The search results list can display a large amount of asset
data. To control what information is displayed, use the Col-
umn Set widget on the upper right of the search results list
to enable/disable specific columns. Click the “+” icon to add
a new column set, or edit the selected column set by clicking
on the pencil icon.

Tip: Most text search fields can use the * wildcard to find results when you don’t
know the exact matching value.
CHAPTER 6 Asset Management 34

Purchase Orders
Using the purchase orders feature of the Web Help Desk can
simplify the tracking of where and when you purchased or
leased your assets. The feature is not meant to replace your
company’s current accounting system. It is designed to make
linking a specific PO number (and its associated vendor and
date information) to your assets a simple matter.

Define Vendors
Before adding a new PO, one or more vendors must be
entered into the database. Vendors are managed by going to
Assets > Vendors. To add a new vendor, click on the “New”
button at the bottom of the list. To edit an existing vendor,
click on the hyperlinked vendor name.

The “Order Type” field has a toggle button that switches

Create a New Purchase Order
Once vendors are in the database, a new purchase order can
be created. Click on Assets > Purchase Orders and click on
the “New” button at the bottom of the search display list.
Fields in a purchase order include:
• PO Number (must be unique in the database)
• Request Date – the date the purchase order was entered
• Invoice Date – the date the vendor shipped the product
(used to help calculate warranty / lease expiration date)
• Vendor
between “Purchase” and “Lease.” Toggling to lease exposes
an additional option – the lease length drop down. After sup-
plying purchase order information, click “Save” to enter it in
the database.
Add Line Items
Once a purchase order is saved, the line item editor becomes
visible. Line items must define a model, and may contain
part number and price information. Line items can also be
associated with a specific asset by providing a valid asset
number. If you attempt to link a line item to an asset number
that doesn’t exist, or is already linked to another PO, you will
receive an error message.

• Originator Name – lookup, by last name, the client who
made the PO request.
• Deliver To – lookup, by last name, the client the pur-
chased items should be delivered to
• Attachments - link any supporting documentation
• Notes
Create line items by clicking on the “New Line Item” but-
ton on the editor. To edit existing line items, click on the
hyperlinked model name. Remove line items by clicking on
the trash can icon. Duplicate a line item by clicking on the
“+” button. The line item editor also allows you to specify the
Tax and Shipping amounts for the PO.

Only the PO Number and Vendor are required to save the

purchase order.
CHAPTER 6 Asset Management 35

Tip: An asset can also be associated to a PO from within the asset detail view. You
must have a “free” line item defined in the PO in order to link the asset. If you were
to add a new iMac G5 asset, you could associate it with the PO in the example
above, because the iMac G5 line item is free (not linked) to any asset number.

Purchase Order Import

Purchase orders can be imported at Assets > Import POs. At
a minimum, the import template must provide the PO Num-
ber and Vendor for the import to succeed. Line items may be
added to the PO import by providing a line item number, as-
set type, manufacturer and model. If the model/type doesn’t
already exist in the database, it will be added. Line items can
also be linked to specific asset numbers. If the asset number
doesn’t exist, a new asset is created with the number.

Chapter 7: Asset Discovery
Asset Discovery Components
Web Help Desk supports several methods of automated asset
discovery. For the supported components listed below, WHD
can be configured to sync with the native tools and populate
the assets in the WHD.
Supported Components:
• Apple Remote Desktop version 3 or later
• Casper Suite 6 (or just the Recon Suite 6, which is the
asset discovery component of the Recon suite)
• LANrev 4.6.4 or later
In order for native tool links to work with ARD, down-
load and run the WHD/Remote Desktop Bridge on the
local machine from http://downloads.webhelpdesk.com/
WHDRemoteDesktopBridge.dmg.
Asset Discovery Mechanics
For each discovered asset encountered during a sync, WHD
does the following:
First WHD compares the discovered asset against all assets
currently associated with the Asset Discovery Connection.
Typically, the asset discovery tool provides a unique identi-
fier for each asset, and this is recorded internally by WHD
for each synchronized asset and used to determine whether
a discovered asset matches an asset that was previously
synchronized. For example, Casper assigns each asset a “JSS
ID.” This is recorded by WHD as the asset’s synchronization
identifier. During subsequent synchronizations, WHD will
find each discovered asset’s corresponding WHD record by
matching the JSS IDs provided by the discovery database
against the synchronization identifiers stored in the WHD
database.
If no WHD asset can be found having a synchronization iden-
tifier that matches that of the discovered asset, then a search
is conducted for any un-deleted asset in the database (re-
gardless of whether it is associated with an Asset Discovery
Connection) that matches any of the following values of the
discovered asset, in this order of priority:
• Asset Number
• Serial Number
• MAC Address
36
If no matching asset record can be found in the WHD data-
base, a new asset record is created and stamped with the new
asset’s synchronization identifier.
After matching all assets that have been discovered by the
synchronization tool and creating any new ones, any existing
attributes associated with the connection that were no longer
discovered are handled as specified by the “When Assets Are
Removed” option at Assets > Discover Assets > Connection
Basics.
Discovery Tool Configuration
Apple Remote Desktop 3
In order to use Apple Remote Desktop, the PostgreSQL da-
tabase needs to be enabled and configured to allow network
connections. WHD has provided a setup script to make the
configurations for you. In addition to setting up the Remote
Desktop database, within the Remote Desktop tool you will
need to scan all the assets that must be included in WHD and
then run a System Overview report (The System Overview
Report option in ARD is what exports the asset data to the
ARD PostgreSQL database). In order for the native tool links
to work with ARD, the WHD/Remote Desktop Bridge must
be downloaded and run on the WHD application server (a
download link is provided under “Supported Components”
above).
Tip: For more information, Apple has a knowledge document for setting up the
database at: http://developer.apple.com/appleapplications/ardsql.html. The Apple
document explains in more detail what the WHD script does, and gives instructions
on how to manually access the database from the terminal.
1. Install Apple Remote Desktop on the machine that will
serve as the database server upon which asset data will
be stored. Start Apple Remote Desktop and be sure it is
scanning computers successfully.
CHAPTER 7
Tip: Because the ARD database files are put in place when ARD is first launched,
Remote Desktop must have been started at least once before continuing on to
configure the database for TCP/IP access.
2. Follow the steps outlined in the Apple Developer Con-
nection article referenced above to enable the ARD
PostgreSQL database with TCP/IP support.
Tip: To simplify this process, WHD has provided a script that will do these steps
automatically. As a Mac OS X administrative user (but not as root), download and
uncompress the setup_ard_database.command script from: http://downloads.web-
helpdesk.com/setup_ard_database.command.zip then double-click to execute it.
You will be prompted to enter your Mac OS X pass-
word. The script will configure the ARD database to en-
able TCP/IP access and will then display your database
connection information. Take note of these connection
settings. You will need to enter them into Web Help
Desk.
3. After setting up the ARD database, run a System Over-
view report of all the computers that you want included
in the Web Help Desk asset sync. Open Remote Desktop,
select the computers to be included, and then choose
Report > System Overview and run the report.
Tip: ARD does not remove computers from the database when they are no longer
included in a System Overview report. Since Web Help Desk will synchronize with all
computers found in the ARD database, you must remove any old computers from the
ARD database manually if you want them to be removed from Web Help Desk.
4. In Web Help Desk, go to Assets > Discover Assets and
create a new Asset Discovery Connection (See Connec-
tion Basics later in this document). Select Apple Remote
Desktop as the discovery type and enter the database
connection parameters provided by the database setup
script (Step 2 above).
5. Use the Attribute Mapping tab of the asset discovery
connection to map any custom asset fields to ARD attri-
butes (See Attribute Mapping later in this document).
6. Save the discovery connection and synchronize it. You
should now see the synchronized assets when you search
for them in Assets > Search Assets.
Asset Discovery 37
Casper
To enable Casper as the Asset Discovery tool, there is no ad-
ditional configuration outside of the Web Help Desk Connec-
tion Basics and Attribute Mapping settings discussed later in
this document. There is no need to set up the database or the
native tool links.
LANrev
Web Help Desk features an integration with LANrev 4.6.4.
There are 2 components to this integration.
• The import of LANrev inventory data into Web Help
Desk via the LANrev MySQL ODBC export.
• The ability to view inventory details about a client
in the LANrev admin console and initiate a remote
control session through LANrev via a web link in Web
Help Desk.
For the integration to work you must:
• Configure LANrev’s MySQL ODBC export.
• Configure the LANrev admin console to respond to
HTML requests from Web Help Desk.
• Configure Web Help Desk to import client inventory
data from the LANrev MySQL database and enable the
LANrev inventory and remote control links.
Configuring LANrev’s MySQL ODBC Export
To configure LANrev’s MySQL ODBC export please consult
the following LANrev support forum tip at:
http://www.lanrev.com/forum/viewtopic.php?t=223
Configuring the LANrev Admin Console
Close the LANrev admin console and add the following set-
ting to the LANrev admin console preferences in one of the
following locations.
Mac OS X
• “~/Library/Preferences/com.poleposition-sw.lanrev_
admin.plist” file
Windows
• Edit “HKEY_CURRENT_USER\Software\Pole
Position Software\LANrev Admin” registry key
• Set HTTPServerEnabled - Boolean/DWORD - Yes/1
These changes can be made with either Property List Editor
CHAPTER 7 Asset Discovery 38

or Regedit. They can also be made at the Terminal or Com-

mand window with the following.

Mac OS X
• defaults write com.poleposition-sw.lanrev_admin
HTTPServerEnabled -bool true
Windows
• REG ADD “HKCU\Software\Pole Position Software\
LANrev Admin” /v HTTPServerEnabled /t REG_
DWORD /d 1 /f

Configuring Web Help Desk

1. In the Web Help Desk Admin interface select Assets >
Discover Assets, and create a new Asset Discovery con-
nection that points to the LANrev MySQL database (See
Connection Basics later in this document). The con-
nection will read the LANrev asset data into Web Help
Desk’s asset tables.
It can be set up to re-sync automatically at a specified
interval. You can also trigger a manual sync.
2. Use the Attribute Mapping tab of the asset discovery
connection to map any custom asset fields to LANrev at-
tributes (See Attribute Mapping later in this document).
3. In addition to syncing up with the LANrev database, you
need to go into Preferences > Assets > Asset Options
and enable links to the LANrev admin console.
Web Help Desk Configuration
Connection Basics
Database connection information is provided via the Assets
> Discover Assets > Connection Basics tab. In this panel,
create a new Asset Discovery connection that points to the
asset discovery tool’s database. You will be prompted to enter
the database name, username, and password. The connection
will read the asset discovery tool’s data into Web Help Desk’s
asset tables.
Click on “New” and create a new “Connection Name.”
Specify the “Discovery Tool” (ARD, Casper or LANrev) and
specify an “Auto-Sync Schedule.”

Go into each Tech’s account and turn the links on/off for each
of them (See WHD Hyperlink to Discovery Tool later in
this document)

With this enabled, wherever assets are referenced in Web

Help Desk, icons will appear allowing you to open the asset
in the LANrev admin console, or to control it via LANrev.
Note that the LANrev admin console must already be open
for these icons to work.

Clear Unmapped Attribute Values

For Asset Discovery, WHD allows only custom fields to
be mapped. If the checkbox “Clear Unmapped Attribute
Values” is checked, then any custom fields that have not been
mapped will be cleared when the assets are synchronized.
CHAPTER 7 Asset Discovery 39

This setting is useful if you already have some data in the

custom fields of existing assets and want to clear it all out in
order to make the assets strictly reflect the data provided by
the asset discovery tool.

Ignore Blank Discovered Values

This option indicates whether blank values provided by the
discovery tool should wipe out corresponding fields in WHD
asset records. For instance, if there is a manually entered op-
erating system value for a particular asset via the WHD web
interface, but the discovery tool does not have OS informa-
tion for the particular asset, then checking this setting would
prevent the asset synchronization from wiping out the value Casper Settings
that was provided manually. When using the Casper asset discovery tool, the following
Basic Connection settings will need to be set:
The difference between this setting and Clear Unmapped
• Casper MySQL Database Host
Attributes is that it applies to ALL attributes, and clears the
fields not based on whether they are mapped or not but on • Port
whether the corresponding values provided by the discovery • Database Name
tool are empty. (It only applies to mapped and built-in fields.) • Username - For that database

When Assets Are Removed • Password - For that database

When applied, this setting will remove an asset that was pre- • Client Relationships
viously found by the discovery tool yet in the current sync, is
no longer found by it.
Tip: When syncing with Apple Remote Desktop, ARD never deletes records from its
database. This means if a computer is removed from the network after it has already
been scanned with an ARD System Overview Report, it will not be removed from the
ARD database when the next System Overview Report is run. As a consequence, if a
fresh view of the synchronized assets that excludes any that have been taken offline
is desired, you will have to manually clear the ARD database and then re-run an ARD
System Overview Report.

ARD Settings
When using the ARD asset discovery tool, the following
Basic Connection settings will need to be set:
• Remote Desktop PostgreSQL Database Host LANrev Settings

• Port When using the LANrev asset discovery tool, the following
Basic Connection settings will need to be set:
• Database Name
• LANrev MySQL Database Host
• Username - For that database
• Port
• Password - For that database
• Database Name
• Username - For that database
• Password - For that database
• Include Virtual Machines
• Client Relationships
CHAPTER 7 Asset Discovery 40

WHD Hyperlink to Discovery Tool

In addition to synchronizing data, WHD provides the option
of displaying hyperlinks for opening asset information in the
discovery products’ native tools. These options are enabled in
Preferences > Assets > Asset Options.

Attribute Mapping
The “Attribute Mapping” tab allows for the mapping of as-
set custom fields to the discovery tool’s attributes. Attribute
Mapping applies only to asset custom fields (Preferences >
Assets > Custom Fields). The asset attributes available to be
mapped to custom fields depends on the particular discovery
Then enable the link option for individual technicians at
tool. These values are taken directly from the values provided
Techs > Techs > [Individual Tech] > Account Info or at
by the discovery tool’s database.
Home > My Account in the “Asset Preferences” panel.
The specific set of options in the popup menu is hard coded
in the WHD ARD plugin, based on the values Apple provides
in the database. The set of attributes written to the database is
fixed (i.e., they are coded into the Remote Desktop applica-
tion itself). They get written into the database at the time the With this enabled, wherever assets are referenced in Web
System Overview report is run. There is no way to customize Help Desk, icons will appear allowing you to open the asset
the attributes that appear in this popup. in the asset discovery tool’s admin console, or to control it
via the tool.
Tip: The LANrev admin console must already be open for these icons to work.
 41

Chapter 8: Approvals Management

The use of approvals is an optional extension to the Web
Help Desk. The ability to manage requests by approval,
where appropriate, can help maintain managerial control over
important company assets and processes. Using the integrated
approvals management tools enhances the functionality of the
application, but it is not required.

In order to utilize the approvals extension of the Web Help Add Department Approver Roles
Desk and set up approval processes, three things must be
To add a position that will be responsible for approvals for
defined and assigned:
one or more departments, click on Approvals > Approver
• Approver Roles Types > Department Approver Roles. Then Click on the
• Approver Processes “New” button to bring up a panel that will allow for a new
• Approval Status Types department approver to be added inside the “Approver Role
Name” cell.

Approver Roles
Add Approver Roles
Before approval processes can be set up, “Approver Roles”
must first be created under the Approvals tab.

New approver roles are added by going to Approvals > Ap-

prover Types. In the resulting panel, there are three types of
Approver Roles that can be added:
• Location Approver Roles allows for the assignment of
Approver Roles by location.
• Department Approver Roles allows for the assignment
of Approver Roles by department.
• Change Advisory Boards allows for the creation of a
change advisory board (or CAB) with the ability to set
how many of the board are required for approval.
Select the type of approver role that is appropriate, click on
the tab of that type, and then click on the “New” button on
the bottom right of the panel.
Add Change Advisory Board Roles
To add a Change Advisory Board (CAB), click on Approvals
> Approver Types > Change Advisory Boards. Then Click
on the “New” button to bring up a panel that will allow for a
new location approver to be added inside the “CAB Name”
cell. In addition, CAB membership can be assigned in the
“CAB Members” section. Use the “Client Lookup” search
function to select and add members by clicking on client
names from the queried list to add them to the CAB. Upon
completion of the CAB membership, select the minimum
number of approvals from the CAB required in the “Mini-
mum Approvers” drop down box.

Add Location Approver Roles

To add a position that will be responsible for approvals for
one or more locations, click on Approvals > Approver
Types > Location Approver Roles. Then Click on the
“New” button to bring up a panel that will allow for a new
location approver to be added inside the “Approver Role
Name” cell.
CHAPTER 8 Approvals Management 42

Assign Approver Roles

Before approval processes can be set up, “Approver Roles”
must be assigned to clients under the Approver Roles tab for
each Location and Department.

Assign Location Approver Roles

Go to Locations > Locations and then click on an existing
location or the “New” button on the bottom right of the panel.
Add “Location Info” as needed. Click “Save” when done.

Assign Department Approver Roles

Go to Locations > Departments and then click on an exist-
ing location or the “New” button on the bottom right of the
panel. Add “Department Info” as needed. Click “Save” when
done.

Select the Approver Roles tab, then click on the “New” but-
ton. Use the drop down menu at “Approver Role” to select
the correct role for the current Department. Use the “Client
Lookup” function in the “Approver Name” field to select the
proper client to link to the role. Click “Save” to record the
approver role.

Select the Approver Roles tab, then click on the “New” but-
ton. Use the drop down menu at “Approver Role” to select
the correct role for the current Location. Use the “Client
Lookup” function in the “Approver Name” field to select the
proper client to link to the role. Click “Save” to record the
approver role.
CHAPTER 8 Approvals Management 43

Approval Processes Define Request Types Supported

Add Approval Processes
Now that Approval Roles have been added and assigned,
the next step is to create an approval process. First go to
Approvals > Approval Processes and click on an existing
“Approver Process” or click the “New” button. These actions
will open an “Approval Basics” window. In this window,
enter a new “Process Name” and “Description” in the appro-
priate fields. Use the drop down menus to select the desired
“E-Mail Reminder Interval” for approvers. Click “Save” to
create your new process.
An approval process is triggered whenever a ticket is cre-
ated with a specific Request Type. To define which specific
request types will trigger a given Approval Process, click on
the “Request Types Supported” tab.
Click the “Edit” button to expose a list of all request types
that are not yet linked to an Approval Process. Check off the
request types to link to the current process, then click “Save”.
Remove linked request types by either unchecking them from
the list in edit mode, or by using the trash can icon in the
linked request types list.

Add Approval Steps

Select the Approval Steps tab and click the “New” but-
ton. Use the “Step No.” drop down menu to select the step
number of this approval step. An approval process may have
an unlimited number of steps. In the “Step Name” field give
the process a descriptive name. In the “Approver Type” field,
use the radio buttons to select which type of approval to set
up. Selecting CAB, Location or Department approver types
results in a drop down menu for the selection of the specific
approver role or CAB to link to the step. Selecting “Client”
as the approver type requires the lookup of a specific Client
to assign to the step.

Tip: While an approval process may have an unlimited number of steps, ALL steps
must be approved for the overall process to be approved. A single unapproved step
halts the process and leaves the process unapproved.
CHAPTER 8 Approvals Management 44

Approval Status Types Assign Approval Status Types

Add Approval Status Types Next, in the “General Settings” panel of the Preferences >
Tickets > Status Types screen several settings must be made
Approval specific “Status Types” should be added and
in order to assign the new status types. Use the drop down
defined in order to use the approvals functionality of WHD
menu for “Needs Approval Status Type” to select “Pending
effectively. These status types will be used by the WHD to
Approval”, or whatever you chose to name that status. Use
automatically control the status of tickets that require an ap-
the drop down menu for “Approved Status Type” to select
proval – they will not be selectable in non-approval tickets.
“Approved”, or whatever you chose to name that status. Use
Common naming conventions for these status types are: “Ap-
the drop down menu for “Approval Denied Status Type” to
proved”, “Pending Approval” and “Denied”. When a ticket
select “Denied”, or whatever you chose to name that status.
is created that requires approval, the WHD application will
Click “Save” to save the settings.
automatically set the status of the ticket to “Pending Approv-
al”, if we assume the common naming conventions above are
used, and lock the ability to change that status until the ticket
goes through the approval process and is either “Approved”
or “Denied”. After the approval decision has been made, no
matter the outcome, the status will unlock and become avail-
able for status changes by techs.

Under Preferences > Tickets > Status Types, create a new

status types by clicking the “New” button in the “Type Edi-
tor” panel.

Approval Status Types have now been configured to allow

for the automated handling of ticket status by the WHD ap-
plication.

Enter “Approved”, or another appropriate entry, into the text
box that says “New Status Type” at the top of the panel. Enter
a description in the field provided and use the checkboxes to
enable any variables desired and click “Save”. Repeat for the
“Pending Approval” and “Denied” statuses.
Using Approvals
Ticket Creation
Now that approval processes have been correctly set up, uti-
lizing this powerful tool is simple. When a client logs in and
creates a new ticket and selects a request type that has been
assigned to an approval process, a notification in a large blue
field denotes that “This Request Type requires approval.”
This is the only difference between opening a ticket that
requires approval and one that does not.

Upon saving the ticket, an e-mail is sent out to the approver

assigned to the Step 1 Approver Role for the approval pro-
cess triggered by the ticket’s request type.
CHAPTER 8
Approver Action
Now that the ticket has been created there are two ways in
which an approver may view and respond to the approval
request:
• Via E-Mail
• Via the Client web interface
E-Mail Approvals
When a ticket has been created that has an approval process
assigned to it, an e-mail will be sent to the approver’s e-mail
and will contain the option of responding “Yes” or “No” to
the request.
Clicking either option will send them to a WHD web page
that will ask to confirm their vote. If a yes vote, the ticket
status will be changed to “Approved.” If a no vote, the ticket
status will be changed to “Declined.” Also, if a no vote is
cast, the approver is given an “Explanation” text box where
they may provide any reasons for declining the request.
There is a “Visible to Requestor” check box below that will
Approvals Management 45
allow the explanation to be viewable by the requestor. Once
the vote has been cast, and any desired explanation has been
entered, click “Save” to submit the approval process.
A window will appear asking for confirmation of the vote
from the approver. Clicking “Confirm” will complete the ap-
proval process.
Client Web Interface Approvals
Another way in which the approver may view and approve
or decline approval requests is through their own client web
interface. When an client who has been set up as an approver
logs in, they will have an “Approvals” button at the top of
their interface. Here they will be able to view “New Ap-
provals” and vote on each new request, as well as view “Old
Approvals” listed when that button is clicked.
In the New Approvals window, the approver can select, vote
and enter explanation values just as with the e-mail process
of approving requests. You may also select “Visible to Re-
quester” to share the denial explanation as a note in the ticket.
Click “Save” to submit approvals.
CHAPTER 8 Approvals Management 46

In the Old Approvals window, the approver can review past

approval requests. The ticket request details can be seen in
the “Details” column. The buttons “More” or “Less” can be
used to adjust the amount of the detail visible. The “Show
Notes” button may also be selected to make the request
denial explanation visible. “Approval Step” information may
be viewed by mousing over the red buttons in the Approval
Step column.

Requester Action
In order to know if the request has been approved or denied
by the approver, the requester must log back in and click on
the “History” icon to view the ticket history and look to see if
there has been a status change to approved or denied for that
ticket.
 47

Chapter 9: FAQs
FAQ View
Search existing FAQs or create a new FAQ by going to FAQs
> Search FAQs. Complete a FAQ search or click “New” in
the Search FAQs box at the top of the screen.

FAQs can be filtered by number, category, location, model,

approval, expiration, and question/answer text. A FAQ is
edited by clicking on its hyperlinked number, and the search
results list is sorted by clicking on a column name. Attach-
ments linked to each FAQ are downloaded by clicking on the
file name link. A direct URL to a FAQ is available by right-
clicking on the “External Link” arrow image.

The audience option controls who can see the FAQ — “Ev-
eryone” means the FAQ is visible to Clients and Techs, while
“Techs Only” makes the FAQ private, and can be further
limited to specific Tech Groups, Locations and Departments.
A link to another FAQ can be added by using the “Insert FAQ
Link” button.

It is also possible to create new FAQ directly from a tech note

within a ticket. The “Create FAQ” button uses the ticket’s
request type and request detail for the FAQ category and
question, and uses the tech note as the FAQ answer. FAQs
added this way are always created as “unapproved”. Creating
New FAQ a FAQ from the note also saves the tech note entry.
Create a new FAQ entry by clicking on the “New” button at
the bottom right of the search results list. A FAQ must have
a category and contain both a question and answer. An-
swers can include HTML hyperlinks and formatting, or use
BBCode tags. FAQs can be linked to specific models loca-
tions and departments and contain one or more file attach-
ments. A FAQ must be “Approved” to be visible by Clients
– only an Administrator can approve a FAQ.
CHAPTER 9 FAQs 48

Import FAQs RSS Feed

FAQs can be imported using the template available at FAQs
> Import FAQs. The template can be saved as either tab or
comma delimited text, and must supply the three required
values for each FAQ.
An RSS feed of public FAQs is also available at the follow-
ing URL:
http://myserver.com/helpdesk/WebObjects/Helpdesk.woa/wa/
FaqActions/rss?type=atom

Clicking on the subject of the RSS entry opens the corre-

Public FAQ Access sponding FAQ in its own window.
Web Access
FAQs that are available to “Everyone” and are approved can
be accessed by anonymous users by connecting to the follow-
ing URL:

http://myserver.com/helpdesk/WebObjects/Helpdesk.woa/wa/

FaqActions/viewAll

FAQs that are linked to specific Locations or Departments are

not accessible using the public URL.
 49

Chapter 10: Parts and Billing

The Web Help Desk can be used to track parts, inventory and down list, use the Display Order setting. If you offer support
billing on tickets. This functionality is enabled by default, to your client locations based on pre-defined service time
but can be disabled by going to Preferences > General > blocks, and have enabled this functionality at Preferences
Global Options > Parts & Billing Enabled. Disabling the > Billing > Invoicing > Enable Location Service Time
feature will hide the main Parts tab, the ticket detail Parts Blocks, you can select the check box “Subtracts from Time
& Billing tab, billing preferences and the billing reporting Blocks” that will cause the work time for tech notes using
option. the rate to be deducted from the ticket location’s service time
block balance.
Billing Preferences
Invoicing
Specify company contact information and tax rates for
labor and parts. Define what the main Billing Entity will
be – Department or Location. The contact information of the
Administrative Contact for the ticket’s billing entity will
be displayed on any PDF invoices generated for a ticket. In
addition, the Administrative Contact for the billing entity is
able to view all tickets for the location or department they Billing Terms
are linked to.
Define terms options for your invoices. Create as many bill-
ing terms as you need for your requirements.

Tax
Define tax rates to be applied to invoices. A tax rate can be
applied to parts, labor and shipping. There is a global option
to apply discounts before taxes are calculated. Note that all
You can also decide which Client contact information is dis-
defined tax rates are applied to an invoice.
played on the invoice – the client’s Location address, or the
client’s personal address.

Custom Logo
Upload your company logo for display on invoices. The logo
is scaled to 3 inches in width by the PDF generator, but the
file should be high resolution for best results.

Billing Rates
Define billing rates to use in your tickets. You can define as
many billing rates as required. For invoicing purposes, a rate
can be defined as a “travel” rate by enabling the Travel Rate
checkbox. To control where the rate shows up in the drop
CHAPTER 10 Parts and Billing 50

Managing Parts
Parts List
Parts are added to the Web Help Desk one by one or as an
imported TSV (tab separated values) file. To view parts in
the system or add new parts, click on the Parts tab. You are
placed at the Parts & Inventory sub-menu option by default.
Parts may be searched by number, description or manufac-
turer.

To add a new part, click on the “New” button at the bottom of
the parts search results list. A part must have an alphanumeric
Part Number, a Manufacturer (defined in Assets > Models),
Description and both cost types. Click “Save” to add the new
part.
Tip: Do not delete the header row of the template, or you will receive an error mes-
sage. Also, make sure that your costs do not contain any commas (i.e. 1,999.00) or
currency symbols. Do not use Excel’s currency number formatter on your prices.
When importing parts, the application synchronizes values
for any existing parts. This makes importing an easy way to
quickly update pricing information. Any part number that
doesn’t exist in the database will be added during the import
if “Add New Entities” is checked.

Adding Inventory
Inventory is added directly via the web interface, or can be
imported from a file. Before adding inventory, make sure
the corresponding parts are already added. To add inventory
The part detail view also shows a history of when inventory using the web interface, go to Parts > Parts & Inventory,
was added for the part. then search by part number, description or manufacturer for
the parts you wish to add inventory. If no search criteria are
Importing Parts provided, all parts are returned.
To import a list of parts, download the template at Parts >
Click on the “Inventory” tab above the search results. For
Import Parts. Every column must have a value for each row
each part you wish to add inventory, provide a storage Loca-
for the import to successfully complete. The columns are:
tion and a count to be added. Any rows where the count is
• Part Number (alphanumeric)
zero are ignored. Negative values are allowed for the part
• Manufacturer Name count if you need to make inventory adjustments. Click
• Part Description the “Save” button at the bottom of the inventory add list to
• Our Cost complete the inventory update. Inventory can also be zeroed
for all parts at a specific location using the “Zero Inventory
• Customer Cost
For” popup.
After adding data to the template, be sure to save as tab
delimited text, then use the “Choose File” button to select the
file on your computer. Click the “Save” button to upload the
file and import the parts list.
CHAPTER 10 Parts and Billing 51

Tip: If there are no Locations available in the location popup, you must go to Loca-
tions > Location List. Select a location from the list, then enable the “Store Parts”
checkbox.

Importing Inventory
Inventory may also be added using a delimited text file at
Parts > Import Inventory. Download the import template,
then supply the following required values:
• Part Number (alphanumeric)
• Location Name
• Count Invoicing
Generate a PDF invoice or quote directly from a ticket by
Do not delete the first row of the template, or you will receive
clicking on the Download button at the top of the Parts &
an error message. After adding data to the template, save as a
Billing view of a ticket. The default PDF type is “Invoice”,
tab delimited text, then use the “Choose File” button to select
but you may select either “Quote” or “Ticket” from the drop
the file on your computer. Click the “Save” button to upload
down menu as the description for the PDF. The document is
the file and import the inventory.
generated by the application and downloads directly to your
machine. All relevant contact information, tech notes and
Using Parts billing line items are included.
Use parts in a ticket by clicking on the Parts & Billing tab
of a ticket detail. Search for a part to add to the ticket by
number, description, manufacturer or model. Selecting the
part from the search results adds a new line item to the part
list for the ticket with a default quantity of one. You can
select a larger quantity and override the default price listed if
required.

If one or more line item parts is defective, you can mark

down the number of DOA parts for the line item. The cost
of the DOA parts is removed from the ticket, and will show
up in a separate area in your billing reports. You can remove
an entire parts line item and return the parts back to inven-
tory by clicking on the trash can icon on the right. Changes
in the Parts & Billing tab are not finalized until you click the
“Save” button. Service Time Blocks
Additional fields available include Billing Terms, PO Num- If you offer support to your client locations based on pre-de-
ber, Shipping, Discount and a Tax Free option. Tax Rates are fined service time blocks, you can enable this functionality at
defined at Preferences > Billing > Tax Rates. If you update Preferences > Billing > Invoicing > Enable Location Ser-
your rates, tickets created prior to the update retain their vice Time Blocks. You must have the “Location” specified as
original rate. To update an old ticket with the new rates, click your “Billing Entity” to see this option. To use time blocks at
the “Refresh Tax Rates” button. a location, go to Locations > Location List > [Edit Loca-
tion] and check the box “Service Time Blocks Enabled.”
CHAPTER 10 Parts and Billing 52

Once enabled, blocks of service time can be allocated to each

location at Locations > Location List > [Edit Location] >
Service Time Blocks.

Create a new time block by clicking on the “New” button.

Time blocks are created in days, hours or minutes. A time
block can be set to expire at a specific date and time. The amount of service time available for a location is dis-
played within the “Ticket Details” of a ticket under the loca-
tion popup. If the value is negative, it will display in red.

If a tech note with time is added for a ticket who’s location

has negative service time available, saving the note will
The time block list for a location shows the creation date,
trigger an alert message in the “Notes” section of the “Ticket
expiration date (if applicable), creator, block amount and
Details” panel as a reminder of the time deficit.
usable time. For non-expiring time blocks, the “Time Block”
and “Usable Time” values should be the same. For an expired
block, the usable value may be lower than the block value
depending on how much time was used before the block ex-
pired. The location total is the sum of the usable time values
for all blocks.

Tickets created for a location with at least one service time Tip: Re-saving a tech note does not re-deduct the note time from the total service
block will automatically deduct time used in the ticket’s tech time available. The time used for a location is dynamically calculated based on the
notes. Tickets created before time blocks were first added current tech note time values of all relevant tickets.
will not count against the location service time. If you
want to count an older ticket against a location’s service time, The service time available for all locations is shown at Loca-
go to the “Parts & Billing” tab of the ticket and enable the tions > Location List.
“Count Against Location Service Time” checkbox in the Bill-
ing Details tab. Likewise, tickets created after time blocks
were added for a location can be excluded from counting
against the location by unchecking the option.
 53

Chapter 11: Reports

Sample Reports
The Web Help Desk includes a set of eight sample reports
you can use right away. The sample reports are also useful as
examples for learning how to build your own.
Creating Reports
Ticket Report
Tutorial
We will use the Ticket Report plugin to generate the report.
We’ll set its Chart Type to Pie Chart, its Category to Status
and its time range to the current month, and we’ll include a
table that displays the chart data in text format. We’ll also set
a Technician filter to limit the tickets included in the report to
those assigned to the current user.

To begin, log in to the Web Help Desk as an administrator

A report can be run directly from the list view by clicking
the “play” triangle. To generate a printable web view in a
popup window, use the “print view” button. To create a PDF
suitable for download and printing, use the PDF button in the
report row.
or as a tech with permission to view reports, and navigate to
Reports > Reports. Click the New button to define a new
report.
In the Report Basics tab, enter the Report Name “Individual
Technician Report – Current User” and set the Report Type
to Ticket Report. Leave the Report Group blank for now.

The reporting module uses a plugin architecture with ad-

ditional plugins planned for future releases. Currently, three
report plugins are available: Ticket Report, Billing Report
(visible only if Parts and Billing is enabled), and Composite
Report.

The Ticket Report plugin facilitates reports that have all the After selecting the report type, the Report Details and Report
information available in previous versions of the Web Help Filters tabs will appear, providing settings specific to Ticket
Desk, but with the added power of being able to choose the Reports. Click the Report Details tab.
categories used to define the report axes. It also allows spe-
Ticket reports are defined by four sets of options: categories,
cific items in report categories to be filtered so that the report
metrics, time range, and filters.
focuses on a subset of category items—for instance, only
those tickets assigned to Joe Admin and Sally Tech. New cat-
egories are available as well, including Ticket Creator, Alert
Level, Alert Condition, and custom fields.

If Parts and Billing is enabled, the new Billing Report plugin

can be used to generate billing reports like those of earlier
Web Help Desk versions, but with more categories to choose
from and with the ability to apply filters.

The Composite Report plugin enables you to group several

sub-reports into a single report that can be generated with a
single click.
Categories determine which values various dimensions of
the report will represent. We want to display a pie chart with
slices representing the number of tickets in each status type,
so we will set the Pie Slice Category to Status.
CHAPTER 11 Reports 54

We now have defined a report that includes a pie chart with

slices representing the number of tickets in each status type,
for all tickets opened during the current calendar month. It
also includes a table that displays the status count.
Metrics determine which ticket attribute will be used to cal-
Click Run Report to see how the report looks so far. Statis-
culate the length of bars or size of pie slices, and determines
tics depend upon the tickets in your help desk, but you should
which attribute will be included in the table. We want to
see something like this:
display a pie chart that shows the ticket count for each status
type, along with a table showing the status counts:

The Time Range filters the tickets included in the report

to those that occur within a given time period. Limiting the
report with a time range can significantly increase the report’s
performance. Time ranges can be Relative or Specific.
Relative time ranges are given as amounts of time prior to
the present. Specific time ranges are given as fixed dates
and times. We want our report to include only those tickets
that were opened during the current month, so we will use a
Relative date range. If we wanted to include tickets opened
within the past 30 days, we could set the From time to 1
Month ago and select Use exact date and time. However, we
want to include only those tickets opened during the current
calendar month. To do this, we will set the From time to 0
Months ago and select Round back to beginning of time
periods. (If we were to have set the From time to 1 Months Adding a Filter
ago, instead of 0 months ago, the time would be determined The report shows statistics for all tickets opened during the
by going back one month from the present and then going current calendar month, but we want to limit it to only those
back to the beginning of that month—resulting in tickets for tickets assigned to the user generating the report. To do this,
the current month plus the previous month). we will add an Assigned Tech filter that includes only the
Report User.

Click the Report Filters tab. Since no filters have been

Tip: “Date Worked On” is a unique date attribute as it looks specifically at Tech
Notes created during the specified date range and not ticket dates. Ticket reports
using this date attribute will include data based on all tech notes in the date range
regardless of who created them, however all “work time” is attributed to the assigned
tech on the ticket.
In addition to specifying the time range, we need to specify
the date attribute that it will apply to. We could use the date
the ticket was opened, the date it was last worked on, the date
it is scheduled for work, or the date it was closed. We will
select Date Opened.
added yet, the list will be empty.
Click New to add a filter. Set the Filter Attribute to As-
signed Tech. When the Filter Attribute is selected, a list of
possible values for the attribute will appear in the Values cell.
Select Report user. This is a special value that represents the
current user of the Web Help Desk who is running the report.
Keep the Filter Type set to Inclusive; otherwise, the filter
will allow all values except those that are selected.
CHAPTER 11 Reports 55

Select the table data options to include in the report:

Click Save to save the filter settings (and the other report Click the Run Report button to generate the table.
settings). Click Run Report again to see the report with the
filter applied.

Tip: Report tables include hyperlinked data that open a ticket list displaying the spe-
cific tickets used in calculating the value. This is a good way to verify that the report
is generated using the expected tickets.

This time the report includes only those tickets assigned to Click Cancel to return to the report list. Select the “Unas-
the current user, and a text box appears at the bottom to show signed” Report Group filter to see your report.
that the filter has been applied.

Displaying Detailed Table Data

In our example report we’ve generated a pie chart and a
simple table that displays the values in the chart. Ticket The report can be edited by clicking the report name, or the
reports also include the option of displaying detailed, multi- report can be run by clicking the Play, Print View or PDF
valued table data. To generate the table, the report must use buttons.
the “Table Only” option for the Chart Type. Go back to the
“Report Details” tab and select the “Table Only” option.
CHAPTER 11 Reports 56

Ticket Reports on Other Categories set the Date Attribute for Time Range to Date Worked On:
Creating ticket reports for tech groups, locations, location
groups, departments, department groups and request types
is nearly identical to the procedure for creating a technician
ticket report. Wherever we set a category or filter to Techni-
cian in the technician ticket reports, we simply replace it
with the desired category: Tech Group, Location, Location
Group, Department, Department Group or Request Type.

Look at the construction of some of the Sample Ticket Re-

At this point, we can click Run Report to see a side-by-side
ports for further examples.
comparison of the billing totals for each technician.

If we wish to focus the report on a single technician, we can

select the Report Filters tab and create an inclusive Techni-
Tip: to group request sub-types together within a single entry for their parent type, cian filter:
create a filter that includes the parent request type. For example, if there are request
types for Hardware and Software, and each have subtypes that you do not wish to
appear as separate lines in the report, create an inclusive Request Type filter that in-
cludes the Hardware and Software request types. The report will then show a single
line for Hardware that includes all tickets with subtypes of Hardware, and a single line
for Software that includes all tickets with subtypes of Software.

Billing Report
Tutorial
Log into the Web Help Desk an administrative user or a tech
with permission to view reports and go to Reports > Re-
Now the report includes an entry for only the selected techni-
ports. Click New to create a Billing Report with the name
cian, with a text box indicating the filter is in effect:
Technician Billing Report. Leave the Report Group blank,
then click Save.

Select the Report Details tab. Set the Category to Techni-
cian. (Note that Billing Reports have only one category
setting and do not have any metrics settings.) To make this
report calculate work time billed during the current calendar
month, we will set the From: period to 0 Months ago and se-
lect Round back to beginning of time periods. We also will
Save the report and return to the ticket list view. Select the
“Unassigned” Report Group filter to see your report. The
report can be edited by clicking the report name, or the report
can be run by clicking the Play, Print View or PDF buttons.
CHAPTER 11
Billing Reports on Other Categories
Creating billing reports for tech groups, locations, location
groups, departments, department groups and request types is
nearly identical to the procedure for creating technician bill-
ing reports. Wherever we set a category or filter to Techni-
cian in the technician billing reports, we simply replace it
with the desired category: Tech Group, Location, Location
Group, Department, Department Group or Request Type.
Creating Report Groups
To facilitate organization and help control access, WHD
has included the “Report Groups” function. Report Groups
control access to created reports by Tech and Location Group
which ensures that each Tech is only presented with the
reports concerning their scope of work.
Group Options
First, set up the “Group Options” of the new Report Group.
Click on any Report Group listed at Reports > Report
Groups under “Group Name” or, in the case of adding a new
group, click “New.” In the Group Options panel, select either
the “All” or “Specific” radio button in the Tech Groups and
Location Groups sections. If Specific is selected, a list of all
the Tech and/or Location Groups available to assign to the
Report Group is provided. Use the check boxes to determine
which groups and which locations are to receive the report(s)
and click “Save.”
Included Reports
Next, choose which reports should be visible in the Report
Group. Go to Reports > Report Groups > Group Options.
A report can only be assigned to one Report Group. Click on
the “Edit” button to get to the edit pane of the Group Op-
tions window. In the upper portion of the pane, reports can be
added to the group by selecting the check boxes. In the lower
Reports 57
portion of the pane, reports can be deleted from the group
by clicking on the small trash can icon. When all reports are
selected as needed, click “Save” to complete the process of
setting up the Report Group.
Creating Report Schedules
To further facilitate the distribution of reports, WHD has in-
cluded the “Report Schedules” function. Using this function
allows for reports to be automated and scheduled to fit your
needs.
Schedule Details
First, set up the “Schedule Details” of the new Report Sched-
ule. Go to Reports > Report Schedules and click “New.”
This will bring up the Schedule Details panel in edit mode.
Enter a descriptive name in the “Schedule Name” field and
click the check box “Enabled” to turn on the scheduled report
function. Set up the scheduled interval in the “Interval” sec-
tion – in the case below the report will be generated weekly,
every week, on Monday at 12:00am. Enter a message to be
included in the report e-mail if desired – dynamic tags for
report list and timestamp are available. Next, use the Client
Lookup function to assign the Client Recipients that should
receive the report – non-clients may be added to the distribu-
tion by adding e-mail addresses in the “Other Recipients’
E-Mails” field at the bottom of the panel. Click “Save” when
done.
CHAPTER 11
Tech Recipients
To define the technicians to include in the report distribution,
click on the “Tech Recipients” tab. Click the “Edit” button to
bring up the list of technicians that can be added to the distri-
bution. Use the check boxes to select those technicians who
should receive the report. Click “Save” when done.
Included Reports
Next, define the reports to include in the distribution. To
do this first click on the “Included Reports” tab, then click
“Edit” to bring up the list of reports that can be added to the
distribution. Use the check boxes to select the reports that
should be included in the distribution. Click “Save” when
done.
Reports 58
History
Finally, the history of Scheduled Reports can be viewed by
clicking on the “History” tab under Reports > Report Sched-
ules. This will bring up a list of when the scheduled report
was run. Dates of the report’s creation and transmission are
listed in the “Dates” field. A description of what transpired
is noted in the “Action” field and more information can be
obtained by mousing over the envelope icon on the right side
of the row.
Creating Survey Reports
Surveys are a useful feedback tool from client users. For
more information on the creation and reporting of surveys,
see the Survey Reports section in Chapter 12: Surveys and
Messages.
 59

Chapter 12: Surveys and Messages

Managing Surveys
Surveys are used as a feedback tool from your client users.
A survey can be linked to a specific ticket for a single client,
or can be used as a general questionnaire sent to a number of
clients.

Survey Manager
Surveys are created and managed at Tickets > Survey
Manager. The “Default Survey” drop down menu defines
which, if any, survey will be used by default for tickets who’s
request type has “Default Survey” for the survey option.

To add a question to a survey, click on the “New Question”

button. Enter the question in the specified text area, then
select the answer type. The options are:
• Text (text field)
• Multiple Choice (check boxes)
• Single Choice (radio buttons)
• Popup menu

For the non-text options, possible answers are supplied in the

“Answer Options” field, separated by a semicolon. Addition-
ally, an “explanation” field can be added to each question
so the client can add further information. Questions can be
reordered by changing the “Display Order” value.
Tip: The diagram above shows the relationship between the “Default Survey” defined
in the Survey Manager settings and the “Survey” selection in a request type. If the
Survey Manager default is set to “None”, no survey will be offered for tickets with a
request type using the “Default Survey” selection.

To create a new survey or edit an existing one, click on the

“Surveys” tab. Click on the “New” button or on the name
of an existing survey to edit the survey details. Each survey
must have a title, and may also have a description for techs,
client greeting, “thank you” message and e-mail invitation
message. If you don’t want the survey sent on every closed
ticket, set the Survey Frequency value to something higher
Sending a Survey
than 1.
Ticket Survey
Recall that a specific survey is linked to a ticket based on the
request type of the ticket. If a ticket has a survey linked, an
invitation to take the survey is sent to the client when the
ticket is closed as part of the closed ticket e-mail. Of course,
a client cannot be required to take a survey, but incomplete
surveys always remain available.
CHAPTER 12
Tip: The image above is an example of a survey invitation in a closed ticket. Note
how the invitation text uses replacement tags from the survey’s “E-Mail Invitation
Message” to personalize the feedback text.
In addition to receiving an e-mail invitation with a direct link
to the survey, a client can access a ticket’s survey via the web
interface. In the client’s “History” view, any closed tickets
with an incomplete linked survey will have a “Take” button
on the right side of the row, while completed surveys will
have a “View” button.
When the client clicks on either the e-mail invitation link or
the “Take” button, the survey will open in their web browser.
The survey cannot be saved unless all questions requiring a
response are answered.
General Surveys
A survey does not need to be linked to a ticket. You can cre-
ate a questionnaire for the purpose of collecting any informa-
tion you wish. Once created, an e-mail invitation with a link
to the survey can be sent to any number of clients. To send
a general survey, create the survey just as you would one to
be used for tickets. Next, go to Clients > Search Clients and
search for one or more clients you wish to send the survey.
Surveys and Messages 60
After searching, check off the clients you wish to include,
then click on the “Send Survey” button at the top of the
search results list.
A “Survey Selector” window will popup with survey settings
which allow you to select which of your saved surveys to
send. In addition, you can set the subject for the e-mail to be
sent. The settings also tell you how many client recipients
will be included in the mailing.
Viewing Survey Results
Ticket Detail View
One way to view the results of a ticket survey is from the de-
tail view of a closed ticket. If a closed ticket has a completed
survey, a survey results button will be available at the top
of the ticket. Clicking on this button opens a popup window
displaying the client’s answers.
Survey Reports
To view summary data regarding both ticket and general
surveys, go to Reports > Surveys. Survey reports can be
generated by name, date, technician, client and request type.
Each survey question is displayed graphically with a pie
chart showing answers by percentage. To view the individual
responses to any question, click on the “Responses” link
following each question. All surveys found by the report are
listed in a table below the graphs. To view all the answers
given by a client on the survey, click on the date/time in the
survey search results list. If the survey is linked to a ticket,
CHAPTER 12 Surveys and Messages 61

you can view the ticket by clicking on the hyperlinked ticket

number. Using a survey report is the only way to view the
results of a general (non-ticket) survey.

Message text can include HTML tags for formatting or

creating links as well as inserted FAQ links. If the message
is targeted to techs, the audience can be further refined to
include only certain tech groups. A message can be “Locked”
which means it cannot be removed from the read messages
list. Messages can be scheduled to start and stop at a specific
Messages date and time. If no expiration date is provided, the message
remains available indefinitely.
Messaging is a utility you can use to post information to tech-
nicians and clients. A message shows up as a “sticky” note in
Viewing Tech Messages
the web interface and can be targeted technicians, clients or
both. When a new tech message is available, an alert is shown
when viewing any option under Home.
Creating Messages
A list of all messages is available to administrators by going
to Home > Messages. The list shows the message, target
audience, which techs have read the message (if applicable),
and the scheduled start/stop dates if any.

Clicking on the alert link will open a message viewer win-

dow. New messages appear under the “New Messages” tab,
while read messages that have not been deleted appear under
the “All Messages” tab.

Administrators can create messages targeted to any group,

while technicians must have permission to access the editor
and can only create messages targeted to techs. To create a
new message, click either “New” button located at the top or
bottom of the message list.
CHAPTER 12 Surveys and Messages 62

All “new” messages are automatically moved to the “All

Messages” tab after viewing. To delete a message, click the
small “x” at the upper left. Messages with a lock cannot be
deleted.

Viewing Client Messages

Messages targeted to clients may be viewed by taking the
alert link on the login page.

License Key Expiration Message

The Web Help Desk uses a message to alert Administrators
when support on your license key is due to expire. A message
is created once a week for the month preceding the key expi-
ration. License keys always expire at the end of the month.

The alert link opens a “Public Message View” window.

If the client doesn’t click the public message link at the login
screen, all messages will be shown to the client after they
login. The client will not be allowed to create a new ticket
until they click the “Done” button at the bottom of the mes-
sage list.
 63

Chapter 13: Client Interface

Clients log into the application at the same login panel that hyperlinked number.
technicians use. The Web Help Desk creates a sample client
account at installation. To access the account, login as client/
client for the e-mail address/password. By default, clients are
sent to the Request module.

Help Request

Tip: If you don’t want your clients to see the Location and Room fields because they
aren’t applicable to your implementation, make sure all of your Locations are deleted
at Locations > Location List.
Clients create new tickets at the Help Request module. A
ticket must have a Request Type. The specific request type Selecting an asset adds it to the “Ticket Assets” box. Any
selected determines the following: number of assets can be added to the ticket.
• Is a Request Detail required?
• Is the client required to select an assigned asset or
choose a model.

To change these options for a specific request type, go to

Preferences > Tickets > Request Types > [Edit Request
Additionally, several options at Preferences > Tickets >
Type] > Request Detail Required and Use Models
Ticket Options affect a client’s ability to select an asset and
location:

• Lock Ticket to Client Location – Disables the loca-

If the request type selected requires a model, additional op-
tions will display below the Location and Room row. “Select
Asset” if the Client has assigned assets, or “Select Model” if
no assets are assigned.
If assets are assigned to the client and the selected request
type requires a model, a list of the client’s assets is displayed
in the My Assets box. An asset is selected by clicking on its
tion popup so that only the client’s profile location can
be used for a ticket.
• Ticket Must Use Assigned Asset – Client must specify
an asset on the My Assets list.
• Asset Number Lookup for Client – Enables an asset
search field so that clients can lookup an asset to use in
the ticket by number. Assets can be searched by num-
ber, serial number or network name.
• Tickets Require Room – Client must select a room.
• Include Room Assets in Client Asset List – Adds as-
sets for rooms in which the client is assigned to the My
Assets list.
CHAPTER 13 Client Interface 64

If the asset in question is not listed, or you are not using asset
management, the model can be entered manually in the form.
If the model is not listed in the system, or the request does
not apply to a specific model, the client may choose the “Not
Applicable/found” option from the model drop down. Click-
ing the Save button submits the request.

If all required information was provided, the ticket is added

to the database and the client receives a “Thank You” for
submitting. The application will attempt to send an e-mail
confirmation to the client’s account if enabled at Preferences
> Tickets > Ticket Options > Auto-Reply to Client.

FAQs
Clients can search your FAQ library, filtering their search by
model, category, and question/answer text. Any attachments
are displayed under the answer text. Clients can rate the ef-
fectiveness of each FAQ by selecting a rating value from 1
to 5 stars in the “Vote” drop down menu. The average of all

History votes is dynamically re-displayed.

All help requests submitted by a client are visible in the His-

tory module of the client interface. History can be searched
by ticket number, status or request detail. To view the details
of a help request, click on its hyperlinked ticket number.

Users can also access FAQs anonymously. For more informa-

Tickets that are not Closed or Cancelled can have Client
tion on anonymous FAQ access, see Chapter 9: Public FAQ
Notes added or additional files attached (if enabled). Closed
Access.
and cancelled tickets are view-only by default, but the
reopening of closed tickets can be enabled at Preferences
> Tickets >Status Types > Clients Can Reopen Closed Profile
Tickets. Tickets can be cancelled using the “Cancel Ticket” Clients can update their user profile based on the permissions
button on the upper right corner of the ticket detail. An e-mail defined at Preferences > Users > Client Options > Client
response is generated for all updated and cancelled tickets. Permissions.
CHAPTER 13 Client Interface 65

Administrative Contacts
Locations and Departments can have one or more “Admin-
istrative Contact” clients defined. At minimum, the Admin
Contact can view all tickets for clients at the Location or
Department assigned. A client can be assigned as Admin
Contact to multiple Locations and Departments. In addition,
the Admin Contact may also be able to edit other client’s
tickets and create tickets for other clients depending on the
options specified at the Location/Department level.
Logout
Clients exit the application by clicking on the Logout button.
Upon logout, they have the option of re-entering the applica-
tion by selecting the “Return to Login” button.
Tip: If “Allow Automatic Login” is enabled at Preferences > General > Server
Settings, and the client has enabled this option on the login screen, they will still
be prompted for their password on their next login attempt if they use the “Logout”
option. To avoid the password prompt, the client should close the browser window
instead of using the logout button.

Admin Contacts are also able to see the costs associated with
a ticket (if Parts & Billing is enabled) and to download PDF
invoices for closed tickets.
 66

Chapter 14: Deployment Considerations

Memory Sizing and JVM Options WebObjects on Mac OS X Server
The main deployment factor to consider is the number of Another option available on Mac OS X Server is a multiple
concurrent users you expect your application to support. instance WebObjects deployment. WebObjects deployment
Tech sessions are much more memory intensive than Client is supported on Mac OS X 10.4 and 10.5 Server only. The
sessions, so use the estimated number of concurrent Tech following details how to configure the WHD to run under
sessions to determine which type of deployment will work WebObjects using the Monitor tool:
for your needs.
1. Install the Web Help Desk, then run the following de-
Supporting up to 20 Techs ployment script in the Terminal (as root or sudo):
On a 32 bit OS, the WHD must use a 32 bit Java Virtual
/Library/WebHelpDesk/bin/UpdateWebObjectsConfiguration
Machine (JVM). The maximum memory a 32 bit JVM
can address varies slightly by operating system, but 1600 2. In Server Admin, start the Web and the WebObjects
MB is a good common max value. This max should be services. Enable the Monitor by checking “Turn Moni-
able to support 10-20 concurrent Techs without a problem.
tor On”. You can leave the default ports.
Always make sure you have enough physical memory in
your machine to support both the 1600 MB for the JVM as
well as the server OS and any other services you run on the
machine. You set the memory for the JVM by editing the
<WebHelpDesk>/conf/whd.conf file’s MAXIMUM_MEM-
ORY option. The default value is 512 MB.

Supporting over 20 Techs

If you need to support more that 20 simultaneous Tech
sessions, we suggest moving to a 64 bit OS and a 64 bit
JVM. On a 64 bit JVM you are free to increase the max
heap memory to multiple gigabytes in size by editing the
<WebHelpDesk>/conf/whd.conf file’s MAXIMUM_MEM-
ORY option. Always make sure you have enough physical 3. With a web browser, connect to the Monitor tool at
memory in your machine to support both the JVM size as http://yourserver.com:56789. Click on the “Site” tab.
well as the server OS and any other services you run on the Provide a valid “URL to Adaptor” (this is only used
machine. for links in the Monitor tool). We suggest using “Round
Robin” as your load balance scheme and setting the
A 64 bit JVM is available by default on Mac OS X 10.5 for “Receive Timeout” value to 300. Click the “Update
Intel. You can invoke it by adding the following argument Adaptor Settings” button to save.
to the /Library/WebHelpDesk/conf/whd.conf file’s JAVA_
OPTS option:

JAVA_OPTS=“-d64”

For other operating systems, you must install your own 64 bit
JVM (Java 5 or Java 6), then update the JAVA_HOME option
in the <WebHelpDesk>/conf/whd.conf file to point to your
Java installation.
 13
CHAPTER 14 Deployment Considerations 67

4. Click on the “Hosts” tab. Provide the DNS name or IP
address of the server using Mac OSX as the “of type”
option. Click the “Add Host” button. If this is the only
host that will be running the application, you can use
127.0.0.1 as the host address.
instance can handle up to 1600m, but in general, we find
values of 256m to 384m are sufficient (you will be run-
ning multiple instances). The format is: -Xmx256m

9. Click the “Push All” button to save all settings, then

click on the “Applications” tab again. You should see
your application listed.

5. Click on the “Applications” tab. Add an application

called “Helpdesk” (Note: you can use another applica-
tion name if you wish). Click the “Add Application”
button.

10. Click the “Detail View” button. Add the optimal number
of instances for your server based on the max JVM
memory setting you specified in the application configu-
ration. Remember to leave enough free memory for your
System and any other services you are running on the
machine. You’ll also need to leave an additional 64 MB
free for the Daemon application which we’ll add in a
moment. Click the “Add” button create the instances.
6. Configure the new application. Use the “Path Wizard”
button for the Mac OSX path field to lookup the follow-
ing path to the application startup file:

/Library/WebHelpDesk/bin/webapps/helpdesk/
WEB-INF/Helpdesk.woa/Helpdesk

11. The instances should startup on their own -- you can

7. If you want to capture log files, provide an “Output
Path.” Note that the directory you designate must be
writable by the appserver user.
speed up the process by clicking the green start button in
the “ALL INSTANCES” row for the Start/Stop column.
You can force the page to refresh by clicking the blue
hyperlink “Refresh Now” text below the application
name.

8. Provide “Additional Arguments” to specify the max

JVM heap size for the application instances. Each
CHAPTER 14
12. At this point you should be able to connect to your ap-
plication by going to the following URL:
http://myserver.com/cgi-bin/WebObjects/Helpdesk.woa
If you didn’t name your application “Helpdesk”, make clear the heap memory is suggested. The procedure for doing
sure to substitute the appropriate application name in the
URL.
13. Click on the “Applications” tab and add a new appli-
cation called “Daemon”. This application will have a
similar configuration to Helpdesk, but the “Path” to the
application startup file is:
/Library/WebHelpDesk/bin/webapps/WHDReminder-
Daemon/WEB-INF/WHDReminderDaemon.woa/WHDRemind-
erDaemon
14. Provide an “Output Path” if you are capturing log files.
You can use an additional argument of -Xmx64m for the
memory setting. If for some reason you find you need a
higher setting, feel free to increase the value and restart
the instance. Push all to save.
15. Go to the “Detail View” for the Daemon application and
add 1 (ONE) instance of the Daemon. It’s important that
you have only a single instance, as multiple instances
will cause problems with e-mail ticketing and alert e-
mail generation.
The Web Help Desk is now configured to run under WebOb-
jects using the Monitor tool.
Deployment Considerations 68
Clearing JVM Heap Memory
Most WHD deployments will eventually fill up the JVM
Heap Memory which may result in degraded performance.
To solve this problem, periodically restarting the WHD to
this will vary by the platform that WHD is hosted on.
Mac OS X
First, you must install WHD version 8.4.6.8 or later.
1. As the root user, Copy the /Library/WebHelpDesk/bin/
com.macsdesign.RestartWebHelpDesk.plist file into
your /Library/LaunchDaemons folder.
2. Then execute this command:
launchctl load com.macsdesign.RestartWebHelpDesk.plist
3. You can verify that the plist was loaded successfully
with this command:
launchctl list
To unload the LaunchDaemon, use this command:
launchctl unload com.macsdesign.RestartWebHelpDesk.plist
The plist file provided is configured to restart Web Help Desk
each night at 1AM. You can change the schedule by editing
the StartCalendarInterval property in the plist. See the Mac
OS X documentation for details.
Tip: This launch daemon works only with the standard Tomcat deployment of Web
Help Desk. WebObjects Monitor deployments should use the Monitor tool to config-
ure automatic restarts. When scheduling with the Monitor, make sure to uncheck “Is
Graceful” to force the instances to restart.
Windows
In order to schedule the WHD application for a nightly restart
on Windows to clear the JVM heap memory, you will need to
create two “Scheduled Tasks” in Control Panels.
Stop Scheduled Task
Choose Start > Control Panel > Scheduled Tasks > Add
Scheduled Task to start the Scheduled Task Wizard.
CHAPTER 14 Deployment Considerations 69

Choose a Daily time to run the task.

Choose an application to run -- the choice does not matter, so Check off the “open advanced” option when Finished.
you can choose the first in the list.

Change the “Run” command to be “net stop webhelpdesk.”

Give the task a name.
CHAPTER 14
Start Scheduled Task
Next, create a second Scheduled Task to restart the WHD
application. Follow the same steps above, but use the Run
command “net start webhelpdesk” as the final step.
Schedule the start at least one minute later than the stop
command to ensure that the service has completely stopped
before attempting to restart.
Linux/Solaris
For Linux and Solaris installations, create a nightly cron job
that calls the stop/start scripts as root or using sudo. The fol-
lowing commands would need to be called:
/usr/local/webhelpdesk/whd stop
/usr/local/webhelpdesk/whd start
Configuring WHD for HTTPS
Setting HTTPS_PORT and URL_HTTPS_PORT
in whd.conf
In order to enable HTTPS with Web Help Desk, you must
first configure the port it will listen to for HTTPS requests
and the port it will use in URLs it generates that point back
to itself.
Enabling HTTPS and initializing the Java keystore
To enable Web Help Desk to listen to HTTPS requests,
you must un-comment the HTTPS_PORT setting in
<WebHelpDesk>/conf/whd.conf by removing the pound
character (#) at the beginning of the line. By default, brows-
ers use port 443 for SSL connections. If you use a different
port, you will need to include it in URLs to Web Help Desk.
For example, if your whd.conf file contains the line
HTTPS_PORT=8443
then you would connect to Web Help Desk with the follow-
ing URL:
https://localhost:8443
After setting HTTPS_PORT, restarting Web Help Desk will
create a new Java keystore at <WebHelpDesk>/conf/key-
store.jks containing a self-signed certificate.
Deployment Considerations 70
Tip: If you leave the DEFAULT_PORT setting enabled, Web Help Desk will allow
HTTP as well as HTTPS connections. Most likely, you will want to disable HTTP
requests, by inserting a pound sign (#) in front of the DEFAULT_PORT setting, or
you will want to enable HTTP to HTTPS redirection. (See Enabling HTTP-to-HTTPS
Redirection.)
Generating Web Help Desk URLs to a different port (Optional)
If you have configured your Web Help Desk application
to be accessed through a port other than the web service
port configured by HTTPS_PORT (e.g., if you are using
an Apache rewrite directive to forward requests for port 80
on to the Web Help Desk port), you should uncomment the
URL_HTTPS_PORT setting in whd.conf and set it to the port
you wish Web Help Desk to use in any URLs that point back
to itself.
If you do not uncomment URL_HTTPS_PORT, then
HTTPS_PORT will be used for all links generated by Web
Help Desk that point to itself.
Certificate configuration overview
By default, Web Help Desk uses a self-signed certificate,
causing web browsers to prompt the user whether to trust the
certificate. This section explains how to configure Web Help
Desk to use a signed certificate that will be recognized by
browsers automatically as a valid certificate.
When a browser submits an HTTPS request to Web Help
Desk, the SSL protocol requires Web Help Desk to respond
with a certificate to prove the authenticity of the server. The
certificate contains a public key used for encryption and a
digital signature by a Certification Authority (CA) that tells
the browser who verified the authenticity of the server. Web
browsers are pre configured to trust several CAs whose valid-
ity has been established by the browser manufacturer, such as
VeriSign, Thawte, GeoTrust, and GoDaddy. If a browser does
not recognize the certificate’s CA, it asks the user whether
to trust the certificate. Once trust has been established, the
browser uses the public key to encrypt information it sends
to Web Help Desk, and Web Help Desk decrypts it using its
private key. Similarly, Web Help Desk uses its private key to
encrypt information sent to the browser, and the browser uses
the public key received in the certificate to decrypt it.
Web Help Desk keeps its keys and certificates in a Java
keystore at <WebHelpDesk>/conf/keystore.jks. The open-
source utility Porteclé (“POR-tuh-CLAY,” French for key-
chain), which comes bundled with Web Help Desk, provides
a graphical user interface for administering the keystore.
CHAPTER 14
The keystore holds one or more keypairs. A keypair con-
sists of a private key and a certificate. Each keypair is given
a unique name, or alias, and an optional password. The
embedded Tomcat server used by Web Help Desk requires
its keypair to be given the alias tomcat and, by default, the
password changeit. If a different password is used, the new
password must be given to Tomcat via the KEYSTORE_
PASSWORD setting in whd.conf. The keystore itself also
has a password, which Tomcat requires to be identical to the
keypair password.
When a new keypair is created using Porteclé, it is given
a self-signed certificate. To replace the self-signed certifi-
cate with a certificate signed by a CA, a Certificate Sign-
ing Request (CSR) must be generated for the keypair and
submitted to the CA. The CSR contains the public key and
the name of the server, in a format defined by the PKCS#10
standard (typically given the filename extension .p10 or .csr).
After verifying the applicant’s identity, the CA replies with a
certificate that can be used to replace the selfsigned certificate
in the keypair. This CA Reply (or CSR Reply) is typically
given as an X.509 Certificate file (.cer, .crt, .pem, or .der) or
as a PKCS#7 file (.p7b).
It is possible for a trusted CA to delegate to another CA. In
this case, the certificate returned by the delegated CA will
itself be signed by the trusted CA, resulting in a certificate
chain. Certificate chains may be of any length. The highest
certificate in the chain, the root certificate, should be a self-
signed certificate, signed by the trusted CA. Each certificate
Deployment Considerations 71
in the chain must imported into the keystore so that the com-
plete chain can be sent to the browser. If the CA Reply does
not include the chain certificates, they must be added to the
keystore manually before the CA reply. The certificates must
be imported in order of dependency—i.e., the root certificate
must be added first, then the next chained certificate that
was signed by the root certificate, and so on, down to the CA
reply.
If you have not yet obtained a certificate for your server, you
should use Porteclé to generate both a keypair and a CSR to
send to the CA, and then to import the CA Reply certificate.
If you do already have a certificate, you will need to import it
and the primary key into the keystore. Since Porteclé does
not allow you to import a primary key by itself, you will need
to combine it with its certificate in a PKCS#12 file (*.p12 or
*.pfx). In each case, the keypair must be aliased as “tomcat,”
and both it and the keystore must be protected by the pass-
word specified with the KEYSTORE_PASSWORD setting in
whd.conf.
The following sections explain both ways of getting a
certificate into the keystore: using Porteclé to generate a
new certificate (below), and in the “Importing an Existing
Certificate” section later in this chapter.
Generating a new certificate
This section explains how to create a new certificate, gener-
ate a certificate signing request (CSR), and import the CA
reply. If you already have a certificate, skip to Importing an
Existing Certificate later in this chapter.
CHAPTER 14
Creating a new Keypair
After launching Porteclé, select File > Open KeyStore… and
open <WebHelpDesk>/conf/keystore.jks. (This file is cre-
ated automatically when Web Help Desk is started with the
HTTPS_PORT setting uncommented in <WebHelpDesk>/
conf/whd.conf. If it does not yet exist, simply uncomment
the HTTPS_PORT setting and restart Web Help Desk.)
Upon selecting the keystore, you will be prompted to provide
the keystore password. The default password is changeit.
After opening the keystore, you should see a keypair entry
with the alias tomcat. This keypair was created automati-
cally by Web Help Desk. You will need to replace it with a
new keypair that is configured for your domain. First, delete
the existing tomcat keypair by right-clicking and selecting
Delete:
Deployment Considerations 72
Next, create a new keypair by selecting Tools > Generate
Key Pair. You will be prompted to choose an algorithm and
key size. Choose 1024-bit RSA. Configuring Web Help Desk
for HTTPS 6
Tip: Many browsers, including Internet Explorer, are known to have problems with
DSA certificates. RSA is more widely and consistently supported.
You will now be prompted to provide the x509 distinguished-
name attributes for your certificate:
The Validity attribute specifies the number of days you want
your certificate to be valid. Typical validation periods are 6,
12, or 24 months. (See your CA for options and pricing.)
The most critical attribute is Common Name (CN). This
must match exactly the full domain name for the site to be
used with the certificate. For example, if your help desk will
be hosted at support.mycompany.com, your CN must be sup-
port.mycompany.com, not merely mycompany.com. (Howev-
er, some CAs support wildcard certificates, where *.company.
com matches any subdomain of company.com.)
The Organization Unit (OU) may be anything that helps
CHAPTER 14 Deployment Considerations 73

distinguish this certificate from others for your organiza- Generating a CSR
tion. Organization Name (O) should be the legal name for Now you can create the certificate signing request (CSR) by
your organization. Locality Name (L) and State Name (ST) right-clicking on the keypair and selecting Generate CSR:
should be the unabbreviated city and state/province/region/
territory of your organization. Country (C) should be the
two letter ISO 3166 country code for your country. Email
(E) is generally optional, but may be used by your CA as the
address to which the certificate will be mailed. See your CA
vendor for further information.

After clicking OK, you will be asked to provide an alias for

the new keypair.

IMPORTANT: Web Help Desk expects your keypair or certificate to use the alias
tomcat: Give a name for the CSR that will help you remember the
domain it will validate:

Finally, you are asked to provide a password for the keypair.

IMPORTANT: Web Help Desk requires this password, and the password used
for the entire keystore, to match the KEYSTORE_PASSWORD parameter in
<WebHelpDesk>/conf/whd.conf. By default, this password is changeit. If you use a
different password, you must update the KEYSTORE_PASSWORD setting.
This will be the file you will send to your CA to request your
certificate. The CA should return an x.509 certificate in DER
(*.cer, *.crt), PEM (*.pem, *.cer, *.crt) or PKCS#7 (*.p7b,
*.p7c) encoding.

Importing CA Chain & Root Certificates

After successfully providing the keypair password, you Before importing your certificate into the keystore, you
should see the new keypair aliased by tomcat: should check whether the certificate vendor requires you
to include any other certificates to complete the certificate
chain.

To import a certificate, select Tools > Import Trusted Cer-

tificate:
CHAPTER 14
Locate each of the certificates (if any) provided by your CA
and import them into the keystore.
Importing the CA Reply certificate
After installing any required root certificates, right-click the
tomcat keypair and select Import CA Reply:
Locate the certificate returned by your CA and import it into
the keystore.
IMPORTANT: If your certificate is in Base64-encoded format (*.pem and sometimes
*.cer), you may get an error when importing the certificate if it contains anything
besides the certificate itself. If this is the case, make a copy of the certificate that
includes only the lines starting with -----BEGIN CERTIFICATE----- and ending with
-----END CERTIFICATE-----.
After importing your certificate reply, Porteclé should report
that the certificate was imported successfully.
If when attempting to import the CA Reply, Porteclé gives
you an error that the certificate cannot be trusted, you are
likely missing a root certificate. To determine which cer-
tificate you need, temporarily import your CA Reply as a
Trusted Certificate, rather than a CA Reply certificate, and
examine the Certificate Details. Locate the Issuer property.
You will need to obtain a certificate from your CA that
matches this property and then import it into Porteclé as a
Trusted Certificate. Once you have imported this Configuring
Web Help Desk for HTTPS 9 certificate into Porteclé, as well
as any other certificates needed by its Issuer, you can delete
your own trusted certificate and re-import it as a CA Reply to
your keypair.
Importing an existing certificate
If you have an existing certificate that you would like to use
with Web Help Desk, you will need to import your private
key as well as your certificate chain. It will not work to im-
Deployment Considerations 74
port the certificate using Porteclé’s Tools > Import Trusted
Certificate… option, as it will not include the private key.
The PKCS#12 standard specifies a keystore format that is
used for transferring private keys and certificates. PKCS#12
files typically use the extension .p12 or .pfx. If you already
have your private key and certificate bundled in this format,
you can import it directly into Porteclé. (See Importing a
PKCS#12 , below.)
If you do not have a PKCS#12 (.p12 or .pfx) file, you can
use the OpenSSL pkcs12 command to generate one from
a private key and a certificate; or, if your certificate is on a
Windows server, you can export a PKCS#12 file from the
Microsoft Management Console.
Creating a PKCS#12 Keystore from a Private Key and a Certifi-
cate
OpenSSL provides the pkcs12 command for generating
PKCS#12 files from a private key and a certificate. OpenSSL
is open source and can be downloaded from http://openssl.
org. The private key and certificate must be in PEM format
(i.e., base64-encoded, with ----BEGIN CERTIFICATE----
and ----END CERTIFICATE---- headers and footers).
Use this command to create a PKCS#12 file from your pri-
vate key and certificate:
openssl pkcs12 -export \
-in <signed_cert_filename> \
-inkey <private_key_filename> \
-name ‘tomcat’ \
-out keystore.p12
If you have a chain of certificates, you should first combine
the certificates into a single file and use it for the input file, as
shown below. The order of certificates must be from server
certificate to the CA root certificate (see RFC2246 section
7.4.2).
cat <signed_cert_filename> \
<intermediate.cert> [<intermediate2.cert>]
... \
> cert-chain.txt
openssl pkcs12 -export \
-in cert-chain.txt \
-inkey <private_key_filename> \
-name ‘tomcat’ \
-out keystore.p12
CHAPTER 14
You will be prompted to provide a password for the new
keystore, which you will need to provide when importing the
keystore into the Web Help Desk Java keystore.
Exporting a PKCS#12 Keystore from Microsoft Management
Console
If you wish to use an existing certificate located on a Win-
dows server, you can export it to a PKCS#12 file using the
Microsoft Management Console (MMC):
1. Click Start > Run… and execute the command mmc. A
Microsoft Management Console window will open.
2. Select Console > Add/Remove Snap-In.
3. Select Add > Certificates > Add > Computer Account
> Local Computer > Finish.
4. Expand Console Root > Certificates > Personal. You
should see your certificate listed.
5. Right-click your certificate and select All Tasks > Ex-
port.
6. Follow the Certificate Export Wizard prompts to export
a Personal Information Exchange – PKCS #12 (.PFX)
file. Check the option to Include all certificates in the
certification path if possible, and do NOT check the
options to Enable strong protection and to Delete the
private key if the export is successful. Take note of the
location in which you save the .pfx file. You will import
it into Porteclé using the instructions below.
Importing a PKCS#12 file into the Web Help Desk keystore
Porteclé provides two ways to import contents of a PKCS#12
file into the Web Help Desk Java keystore. The first method
is to open the PKCS#12 keystore (File > Open Keystore
File…), convert it to a Java keystore (Tools > Change Key-
store Type > JKS), and overwrite the existing keystore by
saving it as <WebHelpDesk>/conf/keystore.jks. The second
method is to open the Web Help Desk keystore file and then
import the keypair containing your certificate, using Tools
> Import Keypair…. You will be prompted to select which
keypair in your PKCS#12 keystore to import.
If your keystore already contains a default, unsigned ‘tomcat’
certificate, delete it before importing your PKCS#12 file.
Be sure that your certificate chain is intact in the Web
Help Desk keystore. You can inspect the certificate chain by
Deployment Considerations 75
double-clicking the certificate to view the certificate details.
Use the left and right arrows at the top of the details panel to
navigate through each certificate in the chain. If you do not
see the full certificate chain, try importing the CA certificates
first (Tools > Import Trusted Certificate…), and then import
your keypair again. For some reason, Porteclé does not estab-
lish trust when a certificate is imported before the certificate
that was used to sign it. Sequence is important. Import the
root certificate first, then the next certificate in the chain, and
so on, until you get to your own certificate.
IMPORTANT: Your certificate must be aliased as tomcat. The password for your
certificate and for the keystore itself must be the same, and must match the
KEYSTORE_PASSWORD setting in <WebHelpDesk>/conf/whd.conf (changeit by
default).
Enabling HTTP-to-HTTPS redirection
HTTP requests to Web Help Desk can be redirected use
HTTPS. This is useful if you want your clients to be able to
use a regular HTTP URL to connect to your help desk, but
also require their connections to be secure. Redirection can
be performed by the server or the browser. Generally, server-
side redirection is the preferred method.
Tip: If you want the security of passing login credentials through HTTPS, but wish
to avoid the performance penalty of SSL once authentication is complete, you can
configure Web Help Desk to use SSL for the login page only. (See Preferences >
General > Server Settings > Use HTTPS.)
Server-Side Redirection
The Tomcat application server bundled with Web Help Desk
supports HTTP to HTTPS redirection. With HTTPS redirec-
tion enabled, the Tomcat server will automatically switch any
HTTP connection attempts to an HTTPS connection. The
redirection is performed server-side, so it is inconspicuous to
the user.
To enable HTTP to HTTPS redirection, remove the
comments around the following lines at the bottom of
<WebHelpDesk>/bin/webapps/helpdesk/WEB-INF/web.
xml.
CHAPTER 14
<security-constraint>
<web-resource-collection>
<web-resource-name>Automatic SSL
Forwarding</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>
CONFIDENTIAL
</transport-guarantee>
</user-data-constraint>
</security-constraint>
NOTE: There should not be a line break between SSL
and Forwarding.
Be sure that both the DEFAULT_PORT and HTTPS_PORT
settings in whd.conf are provided.
You will need to restart Web Help Desk for any changes to
take effect.
Client-Side (Browser) Redirection
An alternative is to disable HTTP connections to the help
desk (by commenting out the DEFAULT_PORT setting in
<WebHelpDesk>/conf/whd.conf, and provide an HTTPS
URL to the help desk in a page served by a web server listen-
ing to HTTP requests on port 80.
You can make a web page initiate a client-side redirect to the
help desk by including the following meta tag in its <head>
element:
<meta http-equiv=”refresh”
content=”0;URL=https://mycompany.com:8443/
helpdesk/WebObjects/Helpdesk”>
NOTE: There should not be a line break in the URL.
Troubleshooting
Porteclé Says My CA Reply Certificate Cannot Be Trusted
Your certificate has been signed by an Issuer that Porteclé
does not trust. You must obtain a root certificate (or chain of
certificates) from your CA that match the Issuer identity of
your certificate, and import them into Porteclé before import-
ing your own certificate as a CA Reply.
You can determine the Issuer of your CA Reply by tempo-
rarily importing your certificate into Porteclé as a Trusted
Certificate rather than a CA Reply, and then examining its
Certificate Details. Look at the Certificate Details of other
Deployment Considerations 76
certificates in your keystore to see if any of them match your
certificate’s Issuer attribute. If not, you will need to obtain
from your CA a certificate that does match.
Once you have imported a certificate that matches your own
certificate’s issuer, as well as any other certificates needed to
trust those certificates, delete your temporarily trusted certifi-
cate and re-import it as a CA Reply to your keypair.
Porteclé Gives an Error About My Certificate Having an Illegal
Key Size, or About Needing Unlimited-Strength Jurisdiction
Policy Files
To add support for large SSL key sizes, you will need to
download the unlimited-strength local_policy.jar and US_ex-
port_policy.jar files from Sun:
http://java.sun.com/javase/downloads/index_jdk5.jsp
For your convenience they are also attached to FAQ 59 at:
http://support.webhelpdesk.com/cgi-bin/WebObjects/
Support.woa/wa/FaqActions/view?action=fc0500094aa9
410b&id=1
Copy these files into your JAVA_HOME/lib/security folder.
(They should replace existing files of the same names.) De-
faults for WHD installations are below:
Windows: \Program Files\WebHelpdesk\bin\jre\lib\secu-
rity\
Mac OS X: /Library/Java/Home/lib/security/
Linux: /usr/local/webhelpdesk/bin/jre/lib/security/
After copying these files into your Java security folder, you
will need to restart Porteclé.
After importing My Certificate, Web Help Desk Won’t Start
Check your <WebHelpDesk>/conf/whd.conf file to be sure
you have uncommented the SSL_PORT setting, and that
your DEFAULT_PORT and HTTPS_PORT settings are not
conflicting with any other processes on the server.
Also be sure that your KEYSTORE_PASSWORD setting
in whd.conf matches BOTH the password of your keystore
AND the password of your keypair (by default, this password
is changeit).
Finally, be sure that your keypair is aliased as tomcat.
CHAPTER 14 Deployment Considerations 77

After Importing My Certificate, Web Help Desk Starts Okay

But My Browser Shows a Self-Signed Certificate
Check that you are saving your Porteclé keystore to
<WebHelpDesk>/conf/keystore.jks.

Web Help Desk starts okay, but when I connect I get blank
pages or page-not-found error
Check whether your private key was generated using the
DSA algorithm. DSA keys are known to fail with many
browsers, including Internet Explorer. Try using RSA instead.

Running in debug mode

You may be able to get additional information about the error
by running Web Help Desk in debug mode from the com-
mand line:

<WebHelpDesk>/whd stop

<WebHelpDesk>/whd debug

Where <WebHelpDesk> is the path to your Web Help Desk

program folder.