Whd Admin Guide 9

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

Table of Contents

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

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 Considerations 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 Chapter 2.

Database Setup

Select the host you’ll connect from, then click the “Schema Privileges” tab. Select the “whd” schema, and assign the Select, Insert, Update, Delete, Create, Drop, References, 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. Depending on what edition you’re using, you may need to enable Remote Connections over TCP/IP if your database is on a different machine from the WHD installation.

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.

Connect to the “Microsoft SQL Server Management Studio 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...”.

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 Create a new “whd” login using “SQL Server Authentication” – set the password to anything you like.

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 password to one of your choosing. Refer to the OpenBase documentation 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. Embedded FrontBase backups are located at <WebHelpDesk>/

CHAPTER 1

FrontBase4/Backups/whd.fb by default, or you can choose your own backup location. If not using FrontBase, the application can trigger the execution of your own backup script daily. The backup should always be moved to a separate hard disk or tape.

Database 3

4

Chapter 2: Installation Mac OS X

Windows Server

Pre-Install Requirements

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-.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 FrontBaseManager 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 embedded 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 connection 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.

• If not using the embedded FrontBase, your database of choice should be setup as described in Chapter 1.

Installation Launch the WebHelpDesk-.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 application 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 Integration 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 embedded 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 connection 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 Decompress and install and install the RPM: gunzip webhelpdesk-9.x.x-1.noarch.rpm.gz sudo rpm -ivh webhelpdesk-9.x.x-1.noarch.rpm

The RPM installs and starts the Web Help Desk at: /usr/local/webhelpdesk

The application is configured to restart automatically upon reboot. However, if you do need to manually stop and start the application, using a shell: cd /usr/local/webhelpdesk sudo ./whd stop 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: http://localhost:8081/helpdesk

Provide your settings to at the database configuration screen. 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 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.

star is needed because the tar utility included with Solaris (/usr/bin/tar) will not extract the long filenames in the webhelpdesk-.tgz package correctly, nor will the open-source GNU tar. (gtar version 1.13, currently the most popular build for Solaris, seems to have a bug that truncates the last character of paths having 103 characters.) You can use the following to install star (replace sol9 with sol8 if using Solaris 8): • Download the pre-compiled star package (star-1.5a40sol9-sparc-local.gz) from: http://ftp.sunfreeware.com/ftp/pub/freeware. • Uncompress the package (for Intel servers, replace sparc with intel): gunzip star-1.5a40-sol9-sparc-local.gz • Install the package: 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. To install the Web Help Desk once the above prerequisites are met: Extract the webhelpdesk folder into /usr/local/. Be sure to use star not tar! sudo star xfz webhelpdesk-.tgz -C /usr/local/

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 version. To login to the application, use the default account: E-Mail Address: admin Password: admin

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

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, perform 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

• 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 address you want IIS to listen) • To check your settings, type the following command: httpcfg query iplisten

7

Chapter 3: Getting Started Preferences

base and the max attachment size accepted by the application.

Log in as an Administrator and click on the Preferences tab.

Database

Tip: Pop-up help is available throughout the preferences. Mouse over any preference label for a detailed description of the setting.

Specify the database vendor, machine name or IP address and connection account. Specify a backup schedule for your database and set a custom backup path for the FrontBase database if desired.

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 automatic 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. 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 version, Java version and memory used.

Time & Place Business Zones 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-

The application creates a default business zone that should match the time zone specified by the server’s operating system. 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

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 preference values specified in their detail record. Important options include: • Editing options on assets, models, parts and purchase orders • Ticket related editing options

Tickets Calendars

Ticket Options

Enable/disable calendar links, determine which ticket types are included, specify the calendar time “window” and customize the format for event listings.

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

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 account. The default module displayed to the client after login can also be specified.

Create custom fields for your tickets and define viewing/editing 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 options should be either semicolon or new line delimited. Each option must be less than 150 characters in length.

Request Types

Client Custom Fields

Create custom fields for your clients and define viewing/ editing permissions for clients and techs. Custom fields are

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.

Getting Started 9

• The Lead Technician will receive any top level escalations 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. • In the sample above, the “Monitor” request type is defined as child of the “Mac” sub-type, which is a child of the “Hardware” parent, both of which were previously created. • Assign the request type to a Tech Group (optional at this point – can be assigned when tech groups are created). • Define the default priority that tickets of this type will be assigned. • Specify if a detailed description of the request is required 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.

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

Priority Types & Alerts

The application defines four priority types by default: Urgent, High, Medium and Low. Additional priority types can be created and the names and display order for each priority can be changed. Each priority type has its own set of Alert Conditions 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 triggering 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 and time can be overridden within each ticket if desired.

Specify if asset numbers should auto-increment, set view/ editing permissions for technicians and enable expiration e-mail messages to be sent to a specified Tech. Enable asset discovery integration (see Chapter 7: Asset Discovery for more information).

Custom Fields

Define custom fields and specify view/editing permissions for techs.

Asset Types

Tip: If the status type for the ticket has alerts disabled, no alert level changes will be observed regardless of the alert settings.

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 include: Desktop, Laptop, Printer, Software, etc. Each type can also be linked to one or more of your defined custom fields.

CHAPTER 3

Getting Started 11

Status Types

Location

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.

Location Custom Fields

Warranty Types

Tip: Client permissions cannot be set for location or department custom fields because they are never visible to clients.

Specify the warranty options available for your models. Warranties 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 defined 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.

Define custom fields for both Locations and Departments and specify view/editing permissions for techs.

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. Invoicing > 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 available. 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

E-Mail

Getting Started 12

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 notifications. In order to send e-mail, the you must provide the following 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 ordering 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. Greetings 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

Techs This module is used to create new Tech/Admin accounts and to link techs with specific request types by creating Tech Groups. Click on the Techs tab to work with this module.

Technician List The application installs a single Administrator account which 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.

Getting Started 13

Permissions

All new Tech (non Admin) accounts inherit the permissions defined in Preferences > Users > Default Tech Permissions. These values can be left as is for the new account, or they can be edited to customize the behavior for each Tech. Administrator accounts always have full access. Permissions are divided into five main sections: Location, Ticket, Client, Asset and Other.

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 unavailable 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 manager 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, email 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

Locations Click on the Locations tab — this module is used to define support locations and to organize locations into Location Groups. Departments and Department Groups are also configured under this tab if enabled at Preferences > General > Global Options > Use Departments. Locations can also be imported using the Location Importer.

Getting Started 15

Room Editor

If Preferences > General > Use Rooms is enabled, rooms can be linked to the Location by clicking on the Room Editor tab. Add rooms by clicking on the New button at the bottom of the list. Remove rooms by clicking the trash can icon on the room’s row.

Location List The application defines a single Sample Location at installation. 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

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 can be defined. Tech note work time can be displayed to clients at the location.

Link specific clients to each Location Approver Role defined at Approvals > Approver Types. For further information on using Approvals, see Chapter 8: Approvals Management.

Service Time Blocks

Define a service level agreement that is constructed around 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 edit.

Tip: If you wish to have jobs routed to a different Tech for every location, you must 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.

Departments

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 preference.

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

Assigned Techs

Use this tab to assign the technicians to the group. A technician 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.

Link specific clients to each Department Approver Role defined at Approvals > Approver Types. For further information on using Approvals, see Chapter 8: Approvals Management.

CHAPTER 3

Department Groups Use this sub-module to define groups of Departments and link them to the Techs that will handle their tickets.

Getting Started 17

Model Editor

Add models for the manufacturer under this tab. You must provide a model name and an asset type and default warranty 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 management 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 Management deals with this topic in detail.

Models Use this sub-module to define the models your help desk will support. Before adding specific models, you need to create Manufacturers to link the models to. The application defines 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 beyond the full and short names is optional.

Tip: Manufacturers and models are added automatically when using the Asset Importer. If you plan on importing assets, you may want to hold off creating your manufacturers and models and let the importer do it for you. You will still need to go back to each entry and fill out details using the web interface.

18

Chapter 4: Managing Clients Manual Web Entry

Assigned Assets

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” button on the lower right of the list.

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).

Client Info

Ticket History

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 client 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.

A complete history for the client is available under the Ticket History tab. Entries can be sorted by column header and details 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

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.

The importer adds a new client for each unique e-mail address 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

Managing Clients 19

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 complete, go to Clients > Search Clients to check your upload results.

Tip: For most directories anonymous access is all the Web Help Desk requires to import your client data. Active Directory, however, requires authentication to read the directory. The connection account should look like [email protected], 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 information 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.

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 Connections. 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 connection 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 connections and several authentication options are available.

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 synchronization 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 Tip: If your LDAP does not define separate first and last name attributes, but combines them into one, choose a Custom schema and the Full Name option in the Name Attribute. The last word in the name value is used for the client’s last name and the rest of the value is used for the first name.

The location, room, and department attributes have checkboxes indicating whether new corresponding entries should be added to the Web Help Desk database if they don’t already exist. In order for the LDAP location, room, and department data to map to existing Web Help Desk entities, the values of the LDAP attributes must exactly match the 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 locations 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 Department. The Location and Department used must already be created in order to map the fixed value. Some LDAP implementations do not allow the discovery of 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.

Once an LDAP connection has been defined, you must synchronize it with the Web Help Desk database. Although password authentication is initially performed directly against the directory using an LDAP bind, all other client data is referenced from cached copies contained within the Web Help Desk database. You can perform a manual synchronization of the LDAP data by clicking on the Sync Now icon in the list of LDAP connections. If more than one LDAP connection has been defined, an additional synchronization icon is provided in order to sync all connections at once. You may use the Auto-Sync Schedule setting of each LDAP connection to define when automatic synchronizations should take place.

Tip: You can combine LDAP sync with client import to populate values that are not available in your LDAP directory. For example, if your LDAP directory only stores client name and e-mail, you can still use it to create WHD client accounts for authentication. To populate values like Location, Room and Department, you can use an import template and sync to the client’s e-mail address or user name.

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 Preferences > Tickets > Client Required. Use the “Client Lookup” 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.

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 number, 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.

Tip: To search by partial name or e-mail, use an asterisk (*) as a wildcard.

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” button 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 the selected one. The history can be filtered by status. To remove the assigned client from the ticket, click the “Unassign Client” button.

Tip: A ticket is not required to have an assigned asset or model. If the issue you are reporting doesn’t need this information, the Asset Info tab can be skipped entirely.

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 billing 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 regardless of any auto-assign rules in effect. Recipients can be added at the bottom of the panel.

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 calculated 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 approvals are displayed, and can be listed by clicking Approvals button in the panel.

Ticket Notes

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 application will assign a technician to the ticket using load balancing. 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 highest level number, further escalation assigns it to the Tech Group Manager (or Location Group Manager if specified in

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.

Tickets 23

sent when the ticket is saved. Select the recipient checkboxes and add Cc: or Bcc: addresses (comma separated) if necessary, 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 clicking 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.

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: 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

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 automatically 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.

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.

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.

• Edit Problem Report and Client Notes allows the tech to update the text of the reported issue and in client 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 priority 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 created at Tickets > Task Manager. Additionally, access to tickets (as well as Assets and Clients) is controlled by the two “Location Access Permissions”: • 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 assigned Department Groups. Note that tickets, clients and assets that have no department assigned are also accessible.

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

CHAPTER 5

E-Mail Ticketing Reporting by E-Mail

Tickets 25

must have a default “E-Mail Request type” defined for tickets created from that mailbox.

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

The e-mail account may be either POP or IMAP (Exchange Server must enable IMAP), and can connect via SSL if 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 messages (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] > Enable 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

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 Preferences > 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 reply 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 ticket can update it via e-mail. If enabled, any files attached to the message are added to the ticket as attachments.

CHAPTER 5

Techs can also update tickets by e-mail. In addition to adding 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 create a reply e-mail with a pre-formatted subject line the application uses to carry out the action. For example: Ticket:1532 Action:TechUpdate Hidden:NO Status:Pending EmailClient:NO Reassign:[email protected] MinutesWorked:30 BillingRate:Standard

This subject tells the application to add the body of the message to ticket 1532 as a tech note visible to the client, change 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.

Tickets 26

Task Management Creating Tasks A Task is a container for one or more ticket templates called “Elements”. A task can be scheduled to repeat at daily, monthly or yearly intervals. A task may also have a Client associated with it — the Client would be assigned to all tickets created by the task. To create a new task, go to Tickets > Task Manager. Click the “New” button at the bottom of the Task list.

At a minimum, the Task must have a name in order to be saved. If tickets created by the task should have a client assigned, 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 additional 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 “Generate 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.

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.

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 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 option (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 headers 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 spreadsheet 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.

A bulk action template looks similar to the Ticket Details 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 any time in the future. Bulk actions can be private or shared, and can be edited and re-named.

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 cancel the action.

Tip: To select all the tickets in the search results list, click on the small checkbox in the column header for the selection column.

To edit an existing bulk action, select the action from the popup menu, then click the pencil button.

CHAPTER 5

Quick Tickets To save time creating tickets for common issues, the “Quick Ticket” popup menu is available for new tickets. Quick Tickets 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.

Tickets 29

CHAPTER 5

Tickets 30

Ticket Assignment Logic New Ticket

Is the Ticket's Requset Type in a Tech Group?

Web Help Desk Ticket Assignment Logic

Techs > Tech Groups > [Group] > Request Types Supported

Yes

Level 1 Auto-Assign Tickets

Preferences > Tickets > Request Types > [Request Type] > Lead Technician

Place in pool of tickets for Tech Group Level 1

No

Lead Tech

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

Techs > Tech Groups > [Group] > Tech Group Levels > Level 1 > Auto Assign Tickets to

Yes

Group Manager

Assign to Lead Tech for the Request Type* Preferences > Tickets > Request Types > [Request Type] > Lead Technician

Assign to Lead Tech for the Request Type*

No

Assign to Manager of the Tech Group*

Auto assign to?

Techs > Tech Groups > [Group] > Tech Group Info > Group Manager

Level Tech

May use Location Group Manager instead if specified at Techs > Tech Groups > [Group] > Tech Group Info

Get techs in Tech Group Level 1 Techs > Tech Groups > [Group] > Assigned Techs

Filter out any techs not currently scheduled or on vacation Techs > Technician List > [Technician] > On Vacation

Is the ticket's Location in a Location Group?

Techs > Technician List > [Technician] > Specify Work Schedule

No Locations > Location Groups > [Group] > Assigned Locations

Yes

Filter out any techs not in the Location Group

* If the assigned Tech is marked as "On Vacation" the ticket is assigned to the "Backup Tech" for the original assignee.

Locations > Location Groups > [Group] > Assigned Techs

To enable Departments, check Preferences > General > Global Options > Use Departments

Is the ticket's Department in a 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

Are any techs remaining?

No

Assign to Manager of the Tech Group*

Techs > Tech Groups > [Group] > Tech Group Info > Group Manager

Yes Assign to tech who has fewest load balance tickets*

Specify which status types are used in load balancing at Preferences > Tickets > Status Types > [Status Type] > Use for Load Balance

31

Chapter 6: Asset Management Adding Assets Asset management is an optional extension to the Web Help Desk. The asset management features can help keep track of what you own, where it is located and who is using it. In addition, the application can store purchase order information and link it to assets in your inventory. This combination makes it easy to know where you purchased your assets from and when warranties expire. Using the integrated asset management tools enhances the help request ticketing functionality of the application, but it is not required. There are three methods for adding asset information: • Manual Web Entry • Data Import • Asset Discovery Integration (chapter 7)

Manual Web Entry New assets are added by going to Assets > Search Assets and clicking on the “New Asset” button at the top of the search results list, or on the “New” button on the bottom right of the list.

Parent/Child Relationships

Once an asset has been inserted into the database, the option to create a Parent/Child relationship is available. Parent/Child relationships are a powerful way to group assets together. For example, you may issue several assets to an employee that you wish to group: computer, monitor, printer and scanner. You could treat the computer as the “parent” while the other assets act as “children.” After adding all four assets to the system, return to the “parent” computer, and add the other assets as children to it. Click “Edit” in the Child Assets tab and lookup assets by number, type, serial number location and room. Click the “link” hyperlink in the search results list to link the asset. Repeat the process for the other assets you wish to add as children. Children automatically inherit the Location, Room, and Deployed values from the parent. If the parent has only one assigned Client, the child will inherit that as well. To remove a child asset from the list, click on the trash can icon next to the child asset. Important concepts: • A child asset can have multiple parents. • You cannot make an asset that has children (a parent) into a child asset.

Asset Basics

Asset basics are the “what, where, and who” of the asset. If 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 Synchronization.

• Children will automatically update their location information if the parent changes provided there is only one client assigned to the asset.

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

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 manually entered purchase date, and the warranty type specified for the asset.

Asset Management 32

Models

For further information on using adding and editing “Models,” see Chapter. 3: Getting Started.

Import Assets Importing is an efficient way to populate your assets. The import 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.

Ticket History

Provides a list of all tickets created for the asset and provides a link to a ticket detail view for editing.

The importer adds a new asset for each unique asset number it encounters and synchronizes data for any existing asset matching a number in the import file. The importer adds new asset types, manufacturers, models, locations, rooms and

CHAPTER 6

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.

Asset Discovery Integration For further information on using the Asset Discovery feature of the WHD, see Chapter. 7: Asset Discovery.

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. Search results are sorted by clicking on a column header. Download the search results in PDF format by clicking on the Download PDF button, or download the results as a tab 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 Column 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.

Asset Management 33

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 option of defining shared queries, and only an administrator can delete a shared query.

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 round search button. To remove the selected query from the list, click on the round delete button.

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

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.

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 • Originator Name – lookup, by last name, the client who made the PO request. • Deliver To – lookup, by last name, the client the purchased items should be delivered to • Attachments - link any supporting documentation • Notes Only the PO Number and Vendor are required to save the purchase order.

The “Order Type” field has a toggle button that switches between “Purchase” and “Lease.” Toggling to lease exposes an additional option – the lease length drop down. After supplying 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. Create line items by clicking on the “New Line Item” button 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.

CHAPTER 6

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 Number and Vendor for the import to succeed. Line items may be added to the PO import by providing a line item number, asset 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.

Asset Management 35

36

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, download 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 identifier 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 identifier that matches that of the discovered asset, then a search is conducted for any un-deleted asset in the database (regardless 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

If no matching asset record can be found in the WHD database, 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 database 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 Connection 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.webhelpdesk.com/setup_ard_database.command.zip then double-click to execute it.

You will be prompted to enter your Mac OS X password. The script will configure the ARD database to enable 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 Overview 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.

Asset Discovery 37

Casper To enable Casper as the Asset Discovery tool, there is no additional configuration outside of the Web Help Desk Connection 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: 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 Connection 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).

http://www.lanrev.com/forum/viewtopic.php?t=223 Configuring the LANrev Admin Console

Close the LANrev admin console and add the following setting to the LANrev admin console preferences in one of the following locations. Mac OS X •

“~/Library/Preferences/com.poleposition-sw.lanrev_ admin.plist” file

5. Use the Attribute Mapping tab of the asset discovery connection to map any custom asset fields to ARD attributes (See Attribute Mapping later in this document).

Windows •

Edit “HKEY_CURRENT_USER\Software\Pole Position Software\LANrev Admin” registry key

6. Save the discovery connection and synchronize it. You should now see the synchronized assets when you search for them in Assets > Search Assets.

•

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 Command 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 connection that points to the LANrev MySQL database (See Connection Basics later in this document). The connection 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 attributes (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 operating system value for a particular asset via the WHD web interface, but the discovery tool does not have OS information for the particular asset, then checking this setting would prevent the asset synchronization from wiping out the value that was provided manually. The difference between this setting and Clear Unmapped Attributes is that it applies to ALL attributes, and clears the fields not based on whether they are mapped or not but on whether the corresponding values provided by the discovery tool are empty. (It only applies to mapped and built-in fields.) When Assets Are Removed

When applied, this setting will remove an asset that was previously found by the discovery tool yet in the current sync, is no longer found by it.

Casper Settings

When using the Casper asset discovery tool, the following Basic Connection settings will need to be set: • Casper MySQL Database Host • Port • Database Name • Username - For that database • Password - For that database • Client Relationships

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 • Username - For that database • Password - For that database

• LANrev MySQL Database Host • Port • 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 asset 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 tool. These values are taken directly from the values provided by the discovery tool’s database. 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 application itself). They get written into the database at the time the System Overview report is run. There is no way to customize the attributes that appear in this popup.

Then enable the link option for individual technicians at Techs > Techs > [Individual Tech] > Account Info or at Home > My Account in the “Asset Preferences” panel.

With this enabled, wherever assets are referenced in Web Help Desk, icons will appear allowing you to open the asset 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 Desk and set up approval processes, three things must be defined and assigned: • Approver Roles • Approver Processes • Approval Status Types

Add Department Approver Roles

To add a position that will be responsible for approvals for one or more departments, click on Approvals > Approver Types > Department Approver Roles. Then Click on the “New” button to bring up a panel that will allow for a new 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 > Approver 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 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.

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 “Minimum Approvers” drop down box.

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 existing 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” button. 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” button. 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

An approval process is triggered whenever a ticket is created with a specific Request Type. To define which specific request types will trigger a given Approval Process, click on the “Request Types Supported” tab.

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 appropriate fields. Use the drop down menus to select the desired “E-Mail Reminder Interval” for approvers. Click “Save” to create your new process.

Add Approval Steps Select the Approval Steps tab and click the “New” button. 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.

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.

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 in order to assign the new status types. Use the drop down menu for “Needs Approval Status Type” to select “Pending Approval”, or whatever you chose to name that status. Use the drop down menu for “Approved Status Type” to select “Approved”, or whatever you chose to name that status. Use the drop down menu for “Approval Denied Status Type” to select “Denied”, or whatever you chose to name that status. Click “Save” to save the settings.

Approval specific “Status Types” should be added and defined in order to use the approvals functionality of WHD effectively. These status types will be used by the WHD to automatically control the status of tickets that require an approval – they will not be selectable in non-approval tickets. Common naming conventions for these status types are: “Approved”, “Pending Approval” and “Denied”. When a ticket is created that requires approval, the WHD application will automatically set the status of the ticket to “Pending Approval”, 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 available for status changes by techs. Under Preferences > Tickets > Status Types, create a new status types by clicking the “New” button in the “Type Editor” panel.

Approval Status Types have now been configured to allow for the automated handling of ticket status by the WHD application. 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, utilizing 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 process triggered by the ticket’s request type.

CHAPTER 8

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 approval process.

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.

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 Approvals” 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 Requester” to share the denial explanation as a note in the ticket. Click “Save” to submit approvals.

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

CHAPTER 8

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.

Approvals Management 46

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. Attachments linked to each FAQ are downloaded by clicking on the file name link. A direct URL to a FAQ is available by rightclicking on the “External Link” arrow image.

The audience option controls who can see the FAQ — “Everyone” 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.

New FAQ 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. Answers can include HTML hyperlinks and formatting, or use BBCode tags. FAQs can be linked to specific models locations and departments and contain one or more file attachments. A FAQ must be “Approved” to be visible by Clients – only an Administrator can approve a FAQ.

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 a FAQ from the note also saves the tech note entry.

CHAPTER 9

Import FAQs 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.

Public FAQ Access Web Access FAQs that are available to “Everyone” and are approved can be accessed by anonymous users by connecting to the following 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.

FAQs 48

RSS Feed An RSS feed of public FAQs is also available at the following URL: http://myserver.com/helpdesk/WebObjects/Helpdesk.woa/wa/ FaqActions/rss?type=atom

Clicking on the subject of the RSS entry opens the corresponding FAQ in its own window.

49

Chapter 10: Parts and Billing The Web Help Desk can be used to track parts, inventory and billing on tickets. This functionality is enabled by default, but can be disabled by going to Preferences > General > Global Options > Parts & Billing Enabled. Disabling the feature will hide the main Parts tab, the ticket detail Parts & Billing tab, billing preferences and the billing reporting option.

Billing Preferences

down list, use the Display Order setting. If you offer support to your client locations based on pre-defined service time blocks, and have enabled this functionality at Preferences > Billing > Invoicing > Enable Location Service Time Blocks, you can select the check box “Subtracts from Time Blocks” that will cause the work time for tech notes using the rate to be deducted from the ticket location’s service time block balance.

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 are linked to.

Billing Terms Define terms options for your invoices. Create as many billing terms as you need for your requirements.

Tax

You can also decide which Client contact information is displayed 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

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 defined tax rates are applied to an invoice.

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 manufacturer.

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 message. 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

The part detail view also shows a history of when inventory was added for the part.

Importing Parts To import a list of parts, download the template at Parts > Import Parts. Every column must have a value for each row for the import to successfully complete. The columns are: • Part Number (alphanumeric) • Manufacturer Name • Part Description • Our Cost • Customer Cost 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.

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 using the web interface, go to Parts > Parts & Inventory, then search by part number, description or manufacturer for the parts you wish to add inventory. If no search criteria are provided, all parts are returned. Click on the “Inventory” tab above the search results. For each part you wish to add inventory, provide a storage Location and a count to be added. Any rows where the count is zero are ignored. Negative values are allowed for the part count if you need to make inventory adjustments. Click the “Save” button at the bottom of the inventory add list to complete the inventory update. Inventory can also be zeroed for all parts at a specific location using the “Zero Inventory For” popup.

CHAPTER 10

Parts and Billing 51

Tip: If there are no Locations available in the location popup, you must go to Locations > 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 Do not delete the first row of the template, or you will receive an error message. After adding data to the template, save as a 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 inventory.

Using Parts

Invoicing Generate a PDF invoice or quote directly from a ticket by clicking on the Download button at the top of the Parts & Billing view of a ticket. The default PDF type is “Invoice”, but you may select either “Quote” or “Ticket” from the drop down menu as the description for the PDF. The document is generated by the application and downloads directly to your machine. All relevant contact information, tech notes and 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 inventory 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. Additional fields available include Billing Terms, PO Number, Shipping, Discount and a Tax Free option. Tax Rates are defined at Preferences > Billing > Tax Rates. If you update your rates, tickets created prior to the update retain their original rate. To update an old ticket with the new rates, click the “Refresh Tax Rates” button.

Service Time Blocks If you offer support to your client locations based on pre-defined service time blocks, you can enable this functionality at Preferences > Billing > Invoicing > Enable Location Service Time Blocks. You must have the “Location” specified as your “Billing Entity” to see this option. To use time blocks at a location, go to Locations > Location List > [Edit Location] 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 time block list for a location shows the creation date, expiration date (if applicable), creator, block amount and 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 expired. 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 block will automatically deduct time used in the ticket’s tech notes. Tickets created before time blocks were first added will not count against the location service time. If you want to count an older ticket against a location’s service time, go to the “Parts & Billing” tab of the ticket and enable the “Count Against Location Service Time” checkbox in the Billing 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.

The amount of service time available for a location is displayed within the “Ticket Details” of a ticket under the location 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 trigger an alert message in the “Notes” section of the “Ticket Details” panel as a reminder of the time deficit.

Tip: Re-saving a tech note does not re-deduct the note time from the total service time available. The time used for a location is dynamically calculated based on the current tech note time values of all relevant tickets.

The service time available for all locations is shown at Locations > Location List.

53

Chapter 11: Reports Sample Reports

Creating 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.

Ticket Report

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.

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 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 additional 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 information available in previous versions of the Web Help Desk, but with the added power of being able to choose the categories used to define the report axes. It also allows specific items in report categories to be filtered so that the report focuses on a subset of category items—for instance, only those tickets assigned to Joe Admin and Sally Tech. New categories are available as well, including Ticket Creator, Alert Level, Alert Condition, and custom fields.

After selecting the report type, the Report Details and Report Filters tabs will appear, providing settings specific to Ticket Reports. Click the Report Details tab. Ticket reports are defined by four sets of options: categories, metrics, time range, and filters.

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 calculate the length of bars or size of pie slices, and determines which attribute will be included in the table. We want to 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 ago, instead of 0 months ago, the time would be determined by going back one month from the present and then going back to the beginning of that month—resulting in tickets for the current month plus the previous month).

Click Run Report to see how the report looks so far. Statistics depend upon the tickets in your help desk, but you should see something like this:

Adding a Filter

The report shows statistics for all tickets opened during the current calendar month, but we want to limit it to only those tickets assigned to the user generating the report. To do this, we will add an Assigned Tech filter that includes only the Report User. Click the Report Filters tab. Since no filters have been added yet, the list will be empty.

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.

Click New to add a filter. Set the Filter Attribute to Assigned 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 settings). Click Run Report again to see the report with the filter applied.

Click the Run Report button to generate the table.

Tip: Report tables include hyperlinked data that open a ticket list displaying the specific 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 the current user, and a text box appears at the bottom to show that the filter has been applied.

Click Cancel to return to the report list. Select the “Unassigned” Report Group filter to see your report.

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 reports also include the option of displaying detailed, multivalued table data. To generate the table, the report must use the “Table Only” option for the Chart Type. Go back to the “Report Details” tab and select the “Table Only” option.

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

Ticket Reports on Other Categories

Reports 56

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 Technician 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 Reports for further examples.

Tip: to group request sub-types together within a single entry for their parent type, 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 includes 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

At this point, we can click Run Report to see a side-by-side 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 Technician filter:

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 > Reports. Click New to create a Billing Report with the name Technician Billing Report. Leave the Report Group blank, then click Save.

Select the Report Details tab. Set the Category to Technician. (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 select Round back to beginning of time periods. We also will

Now the report includes an entry for only the selected technician, with a text box indicating the filter is in effect:

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 billing reports. Wherever we set a category or filter to Technician in the technician billing reports, we simply replace it with the desired category: Tech Group, Location, Location Group, Department, Department Group or Request Type.

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 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 Options window. In the upper portion of the pane, reports can be added to the group by selecting the check boxes. In the lower

Creating Report Schedules To further facilitate the distribution of reports, WHD has included 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 Schedule. 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” section – 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 distribution by adding e-mail addresses in the “Other Recipients’ E-Mails” field at the bottom of the panel. Click “Save” when done.

CHAPTER 11

Reports 58

History 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 distribution. Use the check boxes to select those technicians who should receive the report. Click “Save” when done.

Finally, the history of Scheduled Reports can be viewed by clicking on the “History” tab under Reports > Report Schedules. 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.

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.

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

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 than 1.

For the non-text options, possible answers are supplied in the “Answer Options” field, separated by a semicolon. Additionally, 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.

Sending a Survey 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

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.

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.

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 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.

One way to view the results of a ticket survey is from the detail 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

General Surveys

A survey does not need to be linked to a ticket. You can create a questionnaire for the purpose of collecting any information 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.

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.

Messages Messaging is a utility you can use to post information to technicians and clients. A message shows up as a “sticky” note in the web interface and can be targeted technicians, clients or both.

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 date and time. If no expiration date is provided, the message remains available indefinitely.

Viewing Tech Messages 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 window. 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 expiration. 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 message list.

63

Chapter 13: Client Interface Clients log into the application at the same login panel that 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.

hyperlinked number.

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 selected determines the following:

Selecting an asset adds it to the “Ticket Assets” box. Any 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 Type] > Request Detail Required and Use Models

Additionally, several options at Preferences > Tickets > Ticket Options affect a client’s ability to select an asset and location: • Lock Ticket to Client Location – Disables the location 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.

If the request type selected requires a model, additional options 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

• 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 number, serial number or network name. • Tickets Require Room – Client must select a room. • Include Room Assets in Client Asset List – Adds assets 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. Clicking 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

History

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 effectiveness of each FAQ by selecting a rating value from 1 to 5 stars in the “Vote” drop down menu. The average of all votes is dynamically re-displayed.

All help requests submitted by a client are visible in the History 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.

Tickets that are not Closed or Cancelled can have Client Notes added or additional files attached (if enabled). Closed 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 Tickets. Tickets can be cancelled using the “Cancel Ticket” button on the upper right corner of the ticket detail. An e-mail response is generated for all updated and cancelled tickets.

Users can also access FAQs anonymously. For more information on anonymous FAQ access, see Chapter 9: Public FAQ Access.

Profile Clients can update their user profile based on the permissions defined at Preferences > Users > Client Options > Client Permissions.

CHAPTER 13

Client Interface 65

Logout Administrative Contacts Locations and Departments can have one or more “Administrative 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.

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.

Clients exit the application by clicking on the Logout button. Upon logout, they have the option of re-entering the application 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.

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 concurrent users you expect your application to support. Tech sessions are much more memory intensive than Client sessions, so use the estimated number of concurrent Tech sessions to determine which type of deployment will work for your needs.

Another option available on Mac OS X Server is a multiple instance WebObjects deployment. WebObjects deployment is supported on Mac OS X 10.4 and 10.5 Server only. The following details how to configure the WHD to run under WebObjects using the Monitor tool:

Supporting up to 20 Techs On a 32 bit OS, the WHD must use a 32 bit Java Virtual Machine (JVM). The maximum memory a 32 bit JVM can address varies slightly by operating system, but 1600 MB is a good common max value. This max should be able to support 10-20 concurrent Techs without a problem. 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_MEMORY option. The default value is 512 MB.

1. Install the Web Help Desk, then run the following deployment script in the Terminal (as root or sudo): /Library/WebHelpDesk/bin/UpdateWebObjectsConfiguration

2. In Server Admin, start the Web and the WebObjects services. Enable the Monitor by checking “Turn Monitor On”. You can leave the default ports.

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_MEMORY option. Always make sure you have enough physical memory in your machine to support both the JVM size as well as the server OS and any other services you run on the machine. A 64 bit JVM is available by default on Mac OS X 10.5 for Intel. You can invoke it by adding the following argument 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.

3. With a web browser, connect to the Monitor tool at http://yourserver.com:56789. Click on the “Site” tab. Provide a valid “URL to Adaptor” (this is only used for links in the Monitor tool). We suggest using “Round Robin” as your load balance scheme and setting the “Receive Timeout” value to 300. Click the “Update Adaptor Settings” button to save.

13 CHAPTER 14

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.

Deployment Considerations 67

instance can handle up to 1600m, but in general, we find values of 256m to 384m are sufficient (you will be running 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 application name if you wish). Click the “Add Application” button.

6. Configure the new application. Use the “Path Wizard” button for the Mac OSX path field to lookup the following path to the application startup file:

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 configuration. 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.

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

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.

8. Provide “Additional Arguments” to specify the max JVM heap size for the application instances. Each

11. The instances should startup on their own -- you can 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.

CHAPTER 14

12. At this point you should be able to connect to your application by going to the following URL: http://myserver.com/cgi-bin/WebObjects/Helpdesk.woa

If you didn’t name your application “Helpdesk”, make sure to substitute the appropriate application name in the URL. 13. Click on the “Applications” tab and add a new application called “Daemon”. This application will have a similar configuration to Helpdesk, but the “Path” to the application startup file is: /Library/WebHelpDesk/bin/webapps/WHDReminderDaemon/WEB-INF/WHDReminderDaemon.woa/WHDRemind-

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 clear the heap memory is suggested. The procedure for doing 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:

erDaemon

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: 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 email generation. The Web Help Desk is now configured to run under WebObjects using the Monitor tool.

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 configure 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 you can choose the first in the list.

Check off the “open advanced” option when Finished.

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 following commands would need to be called: /usr/local/webhelpdesk/whd stop /usr/local/webhelpdesk/whd start

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.

Configuring WHD for HTTPS

Certificate configuration overview

Setting HTTPS_PORT and URL_HTTPS_PORT in whd.conf

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.

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, browsers 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 following URL: https://localhost:8443

After setting HTTPS_PORT, restarting Web Help Desk will create a new Java keystore at <WebHelpDesk>/conf/keystore.jks containing a self-signed 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 validity 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 opensource utility Porteclé (“POR-tuh-CLAY,” French for keychain), 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 consists 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 certificate with a certificate signed by a CA, a Certificate Signing 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).

Deployment Considerations 71

in the chain must imported into the keystore so that the complete 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 password 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 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 selfsigned certificate, signed by the trusted CA. Each certificate

This section explains how to create a new certificate, generate 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 created 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.)

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 distinguishedname attributes for your certificate: 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 automatically 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: 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 support.mycompany.com, not merely mycompany.com. (However, 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

distinguish this certificate from others for your organization. Organization Name (O) should be the legal name for your organization. Locality Name (L) and State Name (ST) 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.

Deployment Considerations 73

Generating a CSR

Now you can create the certificate signing request (CSR) by right-clicking on the keypair and selecting Generate CSR:

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 should see the new keypair aliased by tomcat:

Before importing your certificate into the keystore, you 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 Certificate:

CHAPTER 14

Deployment Considerations 74

Locate each of the certificates (if any) provided by your CA and import them into the keystore.

port the certificate using Porteclé’s Tools > Import Trusted Certificate… option, as it will not include the private key.

Importing the CA Reply certificate

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.)

After installing any required root certificates, right-click the tomcat keypair and select Import CA Reply:

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 Certificate

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.

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 private key and certificate: openssl pkcs12 -export \

-in <signed_cert_filename> \

-inkey <private_key_filename> \

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 certificate 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-

-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> \

[] ... \

> 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 Windows 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 > Export. 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 Keystore 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 establish 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, serverside 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 redirection 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

Deployment Considerations 76

<security-constraint>

<web-resource-collection>

<web-resource-name>Automatic SSL

Forwarding

/*



<user-data-constraint>

CONFIDENTIAL







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 listening 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 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 importing your own certificate as a CA Reply. You can determine the Issuer of your CA Reply by temporarily 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

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 certificate 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_export_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.) Defaults for WHD installations are below: Windows: \Program Files\WebHelpdesk\bin\jre\lib\security\ 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

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 command line: <WebHelpDesk>/whd stop <WebHelpDesk>/whd debug

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

Deployment Considerations 77