Jitbit HelpDesk README

PLEASE READ this readme-file, which will guide through the basics of installation and operation of Jitbit HelpDesk software. Thank you.

Contents:
1. OVERVIEW
2. SYSTEM REQUIREMENTS
3. INSTALLING HELPDESK
4. UPDRADING HELPDESK
5. QUICKSTART
6. Autologin-feature (authentication API)
7. Windows-integrated authentication
8. UNINSTALLING HELPDESK

1. OVERVIEW

Thank you for choosing Jitbit HelpDesk - customer support and knowledge-base software from Jitbit Software. Jitbit HelpDesk is a web based help desk solution ("ticket system"), designed to assist help desks to deliver outstanding customer service. Jitbit HelpDesk is an ASP.NET 4.0 web-application with access from client computers via a web browser.

1.1. Tickets and Categories

Tickets (aka "issues") are the main entities in the help-desk system. Tickets are submitted by users and organized into categories for convenience.

1.2. User roles

Jitbit Help-Desk has three user roles:

User - is a regular user who submits support tickets to the system.

Technician - is a user who is permitted (by an administrator) to handle tickets in one or more categories. A technician receives email notifications about every new ticket in a category. NOTE: To make a user a technician you have to "grant" him permissions to handle tickets in some category. This is done through the category editing form in the admin section.

Administrator - changes system settings, assigns users to categories (thus making them technicians), creates categories, adds/deletes users etc. NOTE: By default an administrator does not get notified of new issues in the helpdesk system, unless he is assigned as a "technician" to some category.

2. JITBIT HELPDESK SYSTEM REQUIREMENTS

2.1. PLATFORMS

Jitbit HelpDesk requires a server running one of the following operating systems:

• Microsoft Windows XP Professional SP2 or later (Vista, Windows 7 etc)
• Microsoft Windows Server 2008 or later
• Microsoft Windows Server 2003 SP1 or later
• Microsoft Windows Server 2000 SP4 or later

Since Jitbit HelpDesk is browser based, there is no particular requirement for the client operating system. A variety of popular browsers can be used for client access to Jitbit HelpDesk including:

• Microsoft Internet Explorer 7.0 or later.
• Google Chrome (any version)
• Mozilla Firefox 1.0 or later.
• Opera 8.0 or later.
• etc

2.2. PREREQUISITES

The following components are required to be installed on the server hosting Jitbit HelpDesk:

• Microsoft .NET Framework 4.0
• Internet Information Services (IIS) web-server
• Microsoft SQL Server 2005/2008 configured to accept both Windows and SQL authentication (the so called "Mixed Mode")

Microsoft .NET Framework, Internet Information Services (IIS) and SQL Server 2005/2008 "Express Edition" are all available at no charge from Microsoft if you do not already have the required components installed.

How to setup SQL SQL 2005/2008:
MS SQL Server 2005/2008 "Express edition" is a free edition of MS SQL Server. It is available for download from the Microsoft web site. Jitbit HelpDesk uses SQL-authentication, so MS SQL 2005/2008 has to be installed with the "Mixed Mode" authentication mode (!), with an SA-password specified ("SA" is a built-in "system administrator" user, whos password must be specified explicitly during installation).

3. INSTALLING HELPDESK read carefully

Jitbit HelpDesk can be installed in TWO WAYS:

• automatically by launching the installer file "setup.exe" (recommended, if you are installing on a local server, you have terminal or physical access to)
• manually (for administrator professionals or, for example, if you want to upload Jitbit HelpDesk to a hosting environment)

3.1. INSTALLING via "setup.exe"

• unzip
• launch "setup.exe"
• If you get "the installer was interrupted" error message, then follow these steps:
  • For Windows 7/Vista go to "Control Panel -> Programs -> Turn Windows features on and off -> Internet Information Services -> Web Management Tools -> IIS 6.0 Management Capability Feature"
  • For Windows 2008 go to "Server Manager -> Roles -> Web Server (IIS) -> Add Role Services -> IIS 6 Management Compatibility"
• proceed with the wizard until you see a "Jitbit HelpDesk setup" dialog
• choose the authentication model - "windows" or "forms" (default, recommended to evaluate the app). See Section 6 for more info.
• If you select "Create a new database from scratch on the local computer" setup will:
  1. setup will prompt you for the SQL-Server name. If you are using SQL Server Express Edition, please note that by default, the SQL Server Express edition is installed as a named instance (SQLEXPRESS). This means that you need to specify "(local)\SQLEXPRESS" as a server name.
  2. setup will create the "JitbitHelpDesk" database on the specified server
  3. setup will create the "JitbitHelpDeskUser" SQL-user with a randomly generated password (this password will be saved to the web.config file).
  4. Note that the above steps require SQL-administrator privileges for your windows account.
• If you select "Upgrade an existing database from an older version" setup will:
  1. setup will prompt you for the SQL-Server name. If you are using SQL Server Express Edition, please note that by default, the SQL Server Express edition is installed as a named instance (SQLEXPRESS). This means that you need to specify "(local)\SQLEXPRESS" as a server name.
  2. setup will find a database named "JitbitHelpDesk" and try to upgrade it to the latest version (preserving the existing data)
  3. setup will generate a new password for the "JitbitHelpDeskUser" user, update it and save it to the web.config file.
  4. Note that the above steps require SQL-administrator privileges for your windows account.
• If you click "Manual setup or already installed" setup will skip the database creation. Proceed to section 3.2.2 of this manual to manually set up a database.
• that's it. Start using Jitbit HelpDesk. Default login is "admin/admin" (CHANGE THAT)

3.2. MANUAL INSTALLATION

3.2.1. Web-application install

• unzip
• copy the contents of the "ManualSetup" folder to your web-server virtual directory (e.g. "c:\inetpub\wwwroot\mywebsite\HelpDesk"), or upload it to your hosting environment
• configure this virtual directory as an application in IIS
• by using IIS Manager, ensure this virtual directory uses ASP.NET 2.0

3.2.2. Database install

Choose one of the following options

• Run the "HDCustomAction.exe" file from the app's "bin" folder (e.g. "c:\inetpub\wwwroot\HelpDesk\bin") .
• OR follow these steps to create the the DB manually.
  • create a new database on your SQL-server, OR choose an existing database
  • locate the "sql" folder within the installation folder (e.g. "c:\inetpub\wwwroot\HelpDesk\sql") and find the script file "CreateTables.sql" (or "UpgradeFromOlderVersions.sql" if you are upgrading).
  • run the script against the database using SQL Query Analyser of SQL Server Management Studio
  • edit the web.config with any plain-text editor to change the connection string to the appropriate value

4. UPGRADING FROM OLDER VERSIONS

To upgrade your helpdesk to the latest version:

• Backup the folder where you have your Helpdesk software installed
• Download the latest trial version OR the latest full version using your password you got after purchase
• Replace all the files in the Helpdesk application directory with the new versions except web.config
• If you have modified any of the files (or the source codes), use a great free tool called WinMerge to compare and merge your changes with our changes. Replacing the "web.config" file is also recommended.
• Upgrade your database to the new format - run the "HDCustomAction.exe" file from the Helpdesk application "bin" subfolder - or run the "UpgradeFromOlderVersions.sql" script manually. The script can be found in the "sql" subfolder.

UPGRADING FROM 5.4.10 AND LOWER

Please note, that starting from version 5.5 the helpdesk is using .NET Framework 4.0 (previous versions were using 3.5). Upgrading requires two more extra steps:

• In the IIS management console, change the application-pool ASP.NET version from "v2.0.50727" to "v4.0.30319" (might not be these exact numbers but something very similar)
• Edit your web.config and remove all sections that have a comment "reserved .NET stuff" next to it (the whole "configsections" element, "compilation" element, "httphandlers", "httpmodules", "system.webserver", "system.codedom", "runtime")
• If you're getting validation errors when trying to close/takeover (etc) old tickets, created in the old version of helpdesk, edit your web.config and add this line into the "system.web" section:
  <httpRuntime requestValidationMode="2.0" />

Also please note that NET Framework 4.0 uses a different method of sending emails via SMTP protocol. If you use an SMTP server via SSL, you may have to change your SMTP port from 465 to 587.

5. QUICKSTART

5.1. Quickstart

After Jitbit HelpDesk has been successfully installed, open your web-browser and navigate to the location where Jitbit HelpDesk is installed (e.g. "http://myserver/HelpDesk").

Unless you changed the installation scripts, Jitbit Help Desk installs with two predefined users: admin (password "admin") and client (password "client"). CHANGE THESE DEFAULT PASSWORDS BEFORE USING HelpDesk. Use these default users only to login for the first time and start using it.

5.2. Getting help

Most pages in Jitbit HelpDesk web application have a link "get help for this page" at the bottom of the page. Clicking this link provides the most relevant in-depth information about the current page.

6. Autologin-feature

AutoLogin (configuring single sign-on with your existing Web-apps and websites)

Jitbit HelpDesk supports "autologin" feature which allows users to be pre-authenticated automatically (by your parent website for example) without entering their username and password. The "autologin" feature is targeted at developers and administrators, who integrate the HelpDesk software into their existing SQL-powered websites and applications. If the user is already authenticated on your parent website (for instance) there are two options:

1. If a user is already present in the helpdesk's database and you know his password - redirect the user to the link of this kind: "AutoLogin.aspx?username=XXXXXX&pswHash=XXXXX". Where "username" is the user's login name, and "pswHash" is a MD5-hash of the user's HelpDesk-password.
2. If a user is not already present in the helpdesk database or you don't want to pass his password, use this link format: http://MyHelpdeskUrl/AutoLogin.aspx?username=xxx&email=yyy&userHash=HASH where "username" is the user's username, "email" is is email and HASH is calculated as follows: MD5(username + email + shared-secret). The "shared secret" is specified in the admin panel. Remember to specify a "strong" secret, at least 10 characters (the longer the better).

7. Windows-integrated authentication

Starting from version 1.9 Jitbit HelpDesk supports Windows-integrated authentication and integrating with your existing Active Directory (AD) user's catalog. To enable Windows-integrated authentication edit the web.config file and un-comment this two lines:

<authentication mode="Windows"></authentication>
<identity impersonate="true"/>

PLEASE NOTE: that when Windows-authentication is enabled, Jitbit HelpDesk automatically adds a domain-user into HelpDesk database when logged in for the first time, if he is properly authenticated with his Windows-account. Also HelpDesk will try to connect to your domain-controller and populate the user's email from Active Directory.

8. UNINSTALLING HELPDESK

Automatic uninstallation is available only if you have installed Jitbit HelpDesk using the automated "setup.exe" installer. If you have installed the application manually - you have to manually uninstall it.

To uninstall Jitbit HelpDesk select "Start - All Programs - Jitbit HelpDesk - Uninstall Jitbit HelpDesk". The application will be removed from your system.

PLEASE NOTE: the database is NOT uninstalled during the automated uninstallation procedure.