LIBERUM HELP DESK ----------------- Version: 0.98 Date: TBD Please view CHANGELOG.TXT for changes in this version. Liberum Help Desk, Copyright (C) 2001 Doug Luxem Liberum Help Desk comes with ABSOLUTELY NO WARRANTY Please view the license.txt file for the full GNU General Public License WEB: http://www.liberum.org SUPPORT: http://www.liberum.org/support.html |--------------------------------------------------------------| CONTENTS I. ABOUT II. REQUIREMENTS III. INSTALLATION IV. UPGRADING V. DATABASES VI. EMAIL VII. AUTHENTICATION VIII. SQL FULL TEXT SEARCHING IX. IIS CONFIGURATION |--------------------------------------------------------------| I. ABOUT Liberum Help Desk is a "free", web-based help desk solution. By "free", not only does the software cost $0 to use, but it is also open software. You are free to change and redistribute Liberum Help Desk as put forth in the license. Features: * Web-based, requires no proprietary clients * Works with most web browsers * Can utilize NT authentication or a separate database of user accounts for granting access * Easily customized to fit your needs * Users can submit and update problems * Email support for user and rep notification * Problems classified by CATEGORY, DEPARTMENT, PRIORITY, and STATUS * Problems can automatically be assigned to reps based on category * Automatically page support reps about high priority problems * View reports on problem categories, work done by support reps, and departments submitting problems |--------------------------------------------------------------| II. REQUIREMENTS The requirements for installing and using Liberum Help Desk are: * Windows NT 4.0 or greater * IIS 4.0 or greater with ASP support * MS SQL Server (not required, but provides better performance) * For email support: IIS SMTP or Exchange server installed locally, or JMail or ASPEmail installed (see section on email) * CPU and MEMORY to run IIS and SQL * 1 MB of hard drive space for web pages * 5+ MB for SQL database * Web browser |--------------------------------------------------------------| III. INSTALLATION ** If you are upgrading from a previous version, please read section IV. ** 1. Extrack the zip file to a temporary directory. Copy the files in the "www" directory to a location on your web server. For example, "C:\inetpub\wwwroot\helpdesk". 2. Edit SETTINGS.ASP in the root of the help desk with Notepad or other text editor. In this file you will need to configure the database settings. Set "DBType" to the type of database you wish to use. (See the section V on databases to configure them.) For SQL, set the server name and database along with username and password if needed. If you are using Access, enter the full physical path to the Access database in AccessPath. The Access database in located in the /db directory and should be copied to a location on your server that is not accessible by the web service (i.e. "C:\inetpub\databases") 3. Using your web browser, browse to the setup.asp page in the root of the help desk. (http://your.webserver.com/helpdesk/setup.asp) Click on the button to install the translated language strings into the database. Even if you are only using English, you must still do this step to install the English strings. 4. Browse to the admin directory of the help desk. (http://your.webserver.com/helpdesk/admin) The default administrative password is: admin After logging in, go to 'Configure Site'. Read the help available on the page for information on the settings. 5. Start using the help desk!! A few thing you will want to look at are setting up support reps (after they have logged in once), configuring the categories, departments, statuses and priorities. If you are using email, you can also configure the messages sent to users and reps. All of this can be done from the admin pages. Also, don't forget to change the admin password! |--------------------------------------------------------------| IV. UPGRADING ** Upgrading to this version is only support if your previous version is 0.95 or higher. ** 1. Create a temporary directory called oldhelpdesk and move the contents of your current help desk directory to it. 2. Extract the new Liberum Help Desk to a temporary location then copy the contents of the www directory to the help desk directory on your web server, which should now be empty. 3. ACCESS USERS ONLY: Copy your old database back to the web server placing it in its previous location. Make sure the anonymous internet user still has CHANGE permissions to the database. See section V for more information. 4. Edit your settings.asp file (as in section III, step 2) to point to your database. 5. Point your web browser to setup.asp in the root of the helpdesk and follow the instructions to update your database. This step will add tables to your database, so you may be required to update your security settings if you are using SQL Server. 6. Test the help desk and delete the oldhelpdesk directory if everything is working. |--------------------------------------------------------------| V. DATABASES There are two choices as to what types of databases you can use as a back end to Liberum Help Desk: MS SQL Server and Access. The Access database will be easier to setup; however, it will not provide the same performance as using MS SQL Server. Access: To use the Access database, open SETTINGS.ASP in the root of the help desk set the DBType equal to 3 and enter the path to the database in AccessPath (the database is located in the db directory). This path should be the physical path to the database and will usually include a drive letter (i.e. C:\databases\helpdesk2000.mdb). WARNING. You should move the Access database to a location outside of your web server. If your web site is located at C:\Inetpub\wwwroot, you should create a directory called C:\Inetpub\databases and place the Liberum database there. You will need to give the IUSR_MACHINE account CHANGE (or MODIFY) rights to the db directory and the helpdesk.mdb file. If you are using NT Authentication (see Sect. VI), then you will need to give all user accounts those rights. The database was designed in Access 2000, and you will only be able to edit it with Access 2000 (however, there should be no need to edit it). SQL: To use MS SQL Server as the database for Liberum Help Desk, do the following: 1. Open Query Analyzer (a tool shipped with SQL Server) and open the helpdesk.sql file located in the db directory. 2. Edit the FILENAME properties of the data and log files to suit your server and then execute the script. 3. Open SETTINGS.ASP and set DBType equal to 1 and then set the SQLServer, SQLDBase, SQLUser and SQLPass variables. (You can use integrated security instead of SQL security. To do this, set DBType equal to 2 and you don't need to set SQLUser or SQLPass. You should also consider using NT Authentication for the site then--see Sect. VII) |--------------------------------------------------------------| VI. EMAIL There is no direct way to send email from ASP pages in IIS without some intermediary. Liberum Help Desk support three different types of "intermediaries" to send mail: CDONTS, ASPEmail, JMail, and ASPMail. Collaborative Data Objects for NT Server (CDONTS) is Microsoft's method for sending email from ASP applications and it can only use the IIS SMTP Service (or Exchange) that is installed on the web server. ASPEmail, ASPMail and JMail are third party components that will allow sending mail to any remote SMTP server. To use CDONTS, you must install the IIS SMTP service. If you with to use Exchange Server, then the IIS SMTP service must be installed before the Exchange IMS so CDONTS is installed. (CDONTS is only installed with the IIS SMTP service). If you don't want to run an SMTP server on the local web server, then use ASPEmail, ASPMail or JMail. To use ASPEmail, ASPMail, or JMail, download the components from the web and install on it on your web server. ASPEmail is available at http://www.aspemail.com and JMail is available at http://www.dimac.net. Both have versions that are freely available. You may also download ASPMail at http://www.serverobjects.com After setting up an email component, make sure to set the help desk to use that component from the administrative menu. For ASPEmail, ASPMail or JMail, you will also have to set an SMTP server address (CDONTS doesn't need one because it will only use the local server). Pager Support: Liberum Help Desk does support alpha-numeric pagers; however, they must be addressable via an email address (most pager services provide this). To use pagers, set a pager priority level from the site configuration page. Any problems created at this priority level or higher will page the rep to which it is assigned. Transferring a problem will also page the new rep if the priority is at the pager level or higher. Reps can add or change their pager address by selecting Edit Information from their main menu after you have set a Pager Priority level. Email Messages: You can configure the email messages sent to users or support reps. Select Configure Email Messages from the administrative menu. The email messages are: User - New: Sent to the user when a new problem is entered in their name. User - Update: Sent to the user whenever a rep updates the problem. User - Closed: Sent to the user when the problem is closed. Rep - New: Sent to the support rep when a problem is assigned to them. Rep - Update: Sent to the support rep when a user adds more information about the problem. Rep - Close: Currently not used. Rep - Pager: Sent to the rep's pager address if paging is enabled. The message support various variables that can be used in the message. These variables have information about the problem, user, support rep or the help desk. All variables are enclosed in square brackets [ ]. See the help available on the Edit Message page for information on what variables are available. |--------------------------------------------------------------| VII. AUTHENTICATION Three types of authentication methods are supported by Liberum Help Desk: Database, NT Authentication, and External Authentication. The most common type of authentication used is Database. This will hold the username and password in the help desk database and users log in via a web page created by Liberum. They will also be allowed to create their own accounts. NT Authentication work in an NT domain environment where you already have accounts set up. You must configure IIS for NT Authentication. To do this, open the Internet Service Manager and browse to the helpdesk directory in the web site. Right-click on the directory and select properties. Select Edit from the directory security tab and then deselect anonymous logon and select basic and/or integrated authentication. External Authentication can be used if you have some other method already programmed for authenticating users. After authenticating users with your other method, there are three ways to get the authenticated username to the help desk: by form data, a query string, or a session variable. The name of the form field, query string or session variable must be 'lhd_ext_uid' and submitted to logon.asp. Here is an example using the form method: <form method="post" action="http://webserver/helpdesk/logon.asp"> <input type="hidden" name="lhd_ext_uid" value="username"> <input type="submit" value="Logon to the help desk"> </form> A query string example would be: <a href="http://webserver/helpdesk/logon.asp?lhd_ext_uid=username"> Please note, using external authentication is fairly insecure as anyone could create a url or form to logon to the help desk and bypass your authentication. After choosing an authentication method, you need to set the correct option in the site configuration off of the administrative menu. |--------------------------------------------------------------| VIII. SQL FULL TEXT SEARCHING Liberum Help Desk supports using SQL full text searching in the knowledge base and support rep problem search. Full text searches allow for more accurate results, the use of logical and proximity keywords, and inflectional words. The logical and proximity keywords allowed are AND, OR, NOT and NEAR. By searching for inflectional words, when searching for "drive" for example, SQL will also use "drives", "drove", "driven", and "driving." Before enabling full text searching in Liberum, you must first configure the full text catalogues in SQL. THE SQL FULL TEXT SEARCH ENGINE MUST BE INSTALLED BEFORE CONTINUING. First, in SQL Enterprise Manager, browse the the Full-Text Catalog under the help desk database. Right-click on Full-Text Catalog and select New. Type in a name for the catalog (i.e. "FT_HelpDesk") and a location for the data. Next go to the Schedules tab and schedule a full text cataloging to reoccur nightly. You may want to adjust this schedule to better suit your environment. Click OK. Now you must add the tables and columns that will be indexed into the catalog. The columns that will be indexed are in the PROBLEMS table. The columns are TITLE, DESCRIPTION, and SOLUTION. To add the columns, browse to the Tables object under the help desk database. Right-click on the PROBLEMS table and select Define Full-Text Indexing on Table. Run through the wizard and add the TITLE, DESCRIPTION, and SOLUTION fields to the catalog created in the previous step. After adding the fields to the catalog, you must do an initial population of the catalog. In SQL Enterprise Manager, browse to the catalog created above. Right-click on it and select Start Population- Full Population. You have now created the full text catalog for Liberum Help Desk. Now, from your web browser, edit your Liberum Help Desk configuration from the administrative menu. You will need to set the SQL full text searching option to enabled. |--------------------------------------------------------------| IX. IIS CONFIGURATION - For Windows 2008 and later, you will need to install the ASP feature for the IIS role. - When configuring IIS, it is recommended to run Liberum under its own application pool. - Configure ASP to allow Parent Paths. This is disabled by default, but the feature is required by Liberum. - For further troubleshoot information on Windows 2008 and later, please see this website: http://www.iis.net/learn/application-frameworks/running-classic-asp-applications-on-iis-7-and-iis-8