Jitbit Helpdesk

Jitbit Help Desk Software : on-premise installation manual

This is the installation manual for Jitbit Help Desk - a web based help desk software application.
Learn more about it

This file will guide through the basics of installation and operation of Jitbit's Helpdesk Ticketing System. Thank you for reading it.

1. OVERVIEW

Thank you for choosing Jitbit HelpDesk. Jitbit HelpDesk is a web based help desk software app, designed to assist help desk teams to deliver outstanding customer service. Jitbit HelpDesk is an ASP.NET 4.0 web-application with access from client computers via a web browser.

Jitbit offers both hosted and self-hosted versions of the software. This installation manual is for the "self-hosted" edition, "for your server".

1.1. Tickets and Categories

Tickets (aka "issues" aka "support requests" aka "support cases") 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 four user roles:

  • Regular User
  • Manager User
  • Technician
  • Administrator

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

Manager User - is a regular user with additional "manager" permissions. This user can view and "close" tickets from other users in the same company.

Technician (aka "help desk agent") - is a user who is permitted (by the 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 at least one category. This can be done through the category editing form in the admin section, or via the user profile editor page.

Administrator - most powerful user role. Helpdesk 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:

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:

2.2 SKILLS REQUIRED

Please be aware that installing a web-application on a server can be a complicated task. It requires basic knowledge of how to install and administer MS SQL Server, create databases and run SQL scripts. You may also need some experience how to configure basic IIS server settings. We strongly recommend going with our hosted version, please try the server only if you really know what you're doing.

2.3. PREREQUISITES

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

  1. Microsoft .NET Framework 4.5.2
  2. Internet Information Services (IIS) web-server with ASP.NET feature enabled.

    To enable the required features on Windows Server, do this:

    • Click "Start button"
    • in the search box, enter "Turn windows features on or off"
    • in the features window, Click: "Internet Information Services"
    • Click: "World Wide Web Services"
    • Click: "Application Development Features"
    • Check (enable) the features. Check all but CGI.
    • Under "Common HTTP features" enable everything except "WebDAV" and "Directory browsing".

  3. Microsoft SQL Server 2012 or later configured to accept both Windows and SQL authentication (the so called "Mixed Mode")

    MS SQL Server 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 SQL Server has to be installed with the "Mixed Mode" authentication mode (!), with an SA-password specified ("SA" is a built-in "system administrator" user, who's password must be specified explicitly during installation).

  4. Full-Text Search for SQL Server (this is optional, but highly recommended)
  5. If you plan using Windows-integrated authentication - you will need "Windows authentication" role service installed. Installation instructions

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.

3. INSTALLING HELPDESK read carefully

Jitbit HelpDesk can be installed in TWO WAYS:

To get you started you can follow along with this 5-minute video guide. It shows the most basic scenario of installing Jitbit along with SQL Server Express on the same server.

3.1. INSTALLING via HelpDeskSetup.exe

3.2. MANUAL INSTALLATION

3.2.1. Web-application install
3.2.2. Database install

Choose one of the following options

3.3. FIRST LOG IN

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.

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.

3.4. Fixing common problems

If you see errors when you open Helpdesk in a browser, please try these things before contacting our support:

4. UPGRADING FROM OLDER VERSIONS

NOTE: starting with version 9.29, the helpdesk app comes with an auto-update module. To upgrade your app to the latest version simply launch SetupTool.exe in the /bin subfolder. It will download the latest version (if you have a licensed version it will prompt you for your password first) and update all the files. And then update the database schema. Please note that if you made changes to the source codes, this might break your changes.

You can watch this short 4-minute video or follow the manual below.

To upgrade your helpdesk to the latest version:

Upgrading from 9.16 and lower - MVC 5.2.7

You also need to make one small change to the web.config file. If you are using our SetupTool.exe when upgrading this change should be made automatically. Otherwise you can do it yourself. Open the "web.config" file from the root directory of Helpdesk in a text editor. Look for this string:


<dependentAssembly>
    <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
    <bindingRedirect oldVersion="1.0.0.0-5.2.5.0" newVersion="5.2.5.0" />
</dependentAssembly>

Should look like this:


<dependentAssembly>
    <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35"/>
    <bindingRedirect oldVersion="1.0.0.0-5.2.7.0" newVersion="5.2.7.0" />
</dependentAssembly>

Upgrading from 9.15 and lower - .NET 4.7.2

Starting with version 9.16 we are switching to .NET 4.7.2. It is possible that you already have it installed on your server. Here is an article on how to check what .NET version do you currently have: How to: Determine Which .NET Framework Versions Are Installed.

If you don't have .NET 4.7.2 installed, you can download it here. A server reboot might be needed.

You also need to make one small change to the web.config file. If you are using our SetupTool.exe when upgrading this change should be made automatically. Otherwise you can do it yourself. Open the "web.config" file from the root directory of Helpdesk in a text editor. Look for this string:

<compilation batch="false" targetFramework="4.5" />

Change "4.5" to "4.7.2". The resulting string should look like this:

<compilation batch="false" targetFramework="4.7.2" />

You will also need to do another small change. Find the code below and replace "9" with "12".


<dependentAssembly>
    <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
    <bindingRedirect oldVersion="0.0.0.0-9.0.0.0" newVersion="9.0.0.0" />
</dependentAssembly>

Should look like this:


<dependentAssembly>
    <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
    <bindingRedirect oldVersion="0.0.0.0-12.0.0.0" newVersion="12.0.0.0" />
</dependentAssembly>

Upgrading from 9.4 and lower

You need to make one change to the web.config file. If you are using our SetupTool.exe when upgrading this change should be made automatically. Otherwise you can do it yourself. Open the "web.config" file from the root directory of Helpdesk in a text editor. Look for this string:

<runtime> ... </runtime>

Replace that entire section with the following:

<runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
        <dependentAssembly>
            <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-9.0.0.0" newVersion="9.0.0.0" />
        </dependentAssembly>
        <dependentAssembly>
            <assemblyIdentity name="Microsoft.Owin" publicKeyToken="31bf3856ad364e35" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-4.0.0.0" newVersion="4.0.0.0" />
        </dependentAssembly>
        <dependentAssembly>
            <assemblyIdentity name="System.Web.Cors" publicKeyToken="31bf3856ad364e35" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-5.2.5.0" newVersion="5.2.5.0" />
        </dependentAssembly>
        <dependentAssembly>
            <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
            <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
        </dependentAssembly>
        <dependentAssembly>
            <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
            <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
        </dependentAssembly>
        <dependentAssembly>
            <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
            <bindingRedirect oldVersion="1.0.0.0-5.2.5.0" newVersion="5.2.5.0" />
        </dependentAssembly>
    </assemblyBinding>
</runtime>

Upgrading from 8.9.20 and lower

You need to make one small change to the web.config file. If you are using our SetupTool.exe when upgrading this change should be made automatically. Otherwise you can do it yourself. Open the "web.config" file from the root directory of Helpdesk in a text editor. Look for this string:

</assemblyBinding>

Before this tag add the following:

<dependentAssembly>
  <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
  <bindingRedirect oldVersion = "0.0.0.0-9.0.0.0" newVersion = "9.0.0.0" />
</dependentAssembly>

Upgrading from 8.9.11 and lower - .NET 4.5

Starting with version 8.9.12 we've started using .NET 4.5. Most likely you already have .NET 4.5+ installed on your server. Here is an article on how to check what .NET version do you currently have: How to: Determine Which .NET Framework Versions Are Installed.

If you don't have .NET 4.5+ (4.6.* is also fine) installed, you can download it here. You will need to restart the server after that, so plan accordingly.

You also need to make one small change to the web.config file. If you are using our SetupTool.exe when upgrading this change should be made automatically. Otherwise you can do it yourself. Open the "web.config" file from the root directory of Helpdesk in a text editor. Look for this string:

<compilation batch="false" targetFramework="4.0" />

Change "4.0" to "4.5". The resulting string should look like this:

<compilation batch="false" targetFramework="4.5" />

That's it. You should be all set.

Upgrading from 8.6.1 and lower - ASP.NET MVC 4

As of version 8.6.2 we've migrated Jitbit Help Desk to ASP.NET MVC 4 to increase security and performance. So upgrading from earlier versions requires you to update your "web.config" file:

Upgrading from 7.0.8 and lower - ASP.NET MVC

As of version 7.1.0 Jitbit Help Desk uses ASP.NET MVC for some of it's operations. So upgrading from earlier versions requires you to update your "web.config" file with the new settings that were not there before (they're marked with "MVC" comment in the new web.config). And also removing all the "location" tags form the "web.config".

Upgrading from 5.4.10 and lower - .NET 4.0

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:

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

5.1 Full-Text Search

By default Helpdesk searches only within tickets subject and text. Since version 7.4.2 you can increase the search performance and enable searching within ticket replies (comments) as well by installing Full-Text Search components on your SQL Server.

If you had Full-Text Search installed from the start and you've upgraded to version 7.4.2 or above, you don't need to do anything, it just works.

If you're not sure whether or not you have it installed, run this query on your server:

SELECT FULLTEXTSERVICEPROPERTY('IsFullTextInstalled')

If it returns "1", you're all set up. If it returns "0", you need to install Full-Text components. Here are the steps you should take:

Full-Text Components are optional, nothing will break without them, but installing them will improve the search speed and quality dramatically.

5.2. Autologin-feature

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. No matter if a user is already present in the helpdesk database or not, use this link format: http://Helpdesk_Url/User/AutoLogin?username=xxx&email=yyy&userHash=HASH. The helpdesk will either create a new user account or use the existing one.
  2. In the URL above Helpdesk_Url is the full helpdesk URL, username is the user's username, email is email and HASH is calculated as follows: MD5(name + email + shared-secret + day + month). The "shared secret" is specified in the helpdesk's admin panel. Remember to specify a "strong" secret, at least 10 characters (the longer the better). The day and month values should be the current day of month, and current month formatted as TWO DIGITS, so "January 1st" should become "0101".

    You can optionally add FirstName=xxx and LastName=xxx parameters to the URL, so the newly-created helpdesk user will have the First/Last names pre-set. You can also pass CompanyName=xxx so the auto-created user will have a company assigned
When using the "autologin" feature you can optionally redirect users to the "new ticket" page. Just add "&new_ticket=1" to the link above.

Here's the up-to-date info on this feature.

5.3. Helpdesk URL

All outgoing email notifications about various ticket events contain a hyperlink to a ticket. The URL in those links is being initialised when Helpdesk starts and it is taken from the URL of the very first request to the app.

For example, if you recycle the application pool and make the first request to http://localhost/helpdesk, this URL will be used in all email notifications from Helpdesk until you recycle the app pool again.

There is a way to override this behaviour by setting a desired URL in the AppURL setting in web.config. Open the web.config file in the root directory of helpdesk and find or add "AppURL" setting inside the <appSettings> section. Like this:

<appSettings>
<add key="AppURL" value="http://support.yourcompany.com" />
</appSettings>

5.4. Storing files on disk

By default Helpdesk stores all attachments in the database. You can set it to store all attachments directly on disk:

  1. Create folder on your hard disk, for example C:\hdfiles
  2. Launch IIS Management Console (inetmgr.exe) and locate Helpdesk's application pool
  3. Right click it and select "Advanced properties", then look for "Identity" property
  4. You need to grant the "identity" user full access permissions to the folder you've just created. You can read how to do it in the official manual
  5. Go to Helpdesk root folder (C:\inetpub\wwwroot\helpdesk by default) and locate web.config file, then open it in Notepad
  6. Find <appSettings> tag and add this line right below it (don't forget to replace "value" with your folder path): <add key="AttachmentsPath" value="C:\hdfiles" />
  7. Recycle the app pool and you're done

6. 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 line: 

<authentication mode="Windows"></authentication>
and comment the above tag which enables "Forms" authentication. Also remember to check if Windows-integrated authentication is enabled in IIS directory where HelpDesk is installed.

If you plan using Windows-authentication under IIS 7 - you will need "Windows authentication" role service installed. Installation instructions.

PLEASE NOTE: that when Windows-authentication is enabled, Jitbit HelpDesk automatically adds a domain-user into the HelpDesk database when he logs 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.

Adding windows-user adminitrator

If you're installing via the "setup.exe" you'll be prompted for a Windows username to add to Helpdesk "administrators" role. If not - there's a setting in the web.config file: <add key="WindowsAdminUsername" value="DOMAIN\Username"/>

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

8. API & Email API

The helpdesk app includes a "RESTful" web-service for integrating with other apps. The service address is: http://servername/helpdesk/api/

API docs can be found here: http://www.jitbit.com/helpdesk/helpdesk-api/

Email API

Email API manual can be found here: Email API

Advanced web.config settings

<add key="WindowsAdminUsername" value="DOMAIN\Username"/> - if you're using helpdesk via Windows authentication and somehow unable to gain admin access to it - type your username into this setting

<add key="LogErrors" value="true"/> - Log helpdesk errors in the server event log

<add key="DisallowChangingAvatars" value="true" /> - restrict users from changing their avatars (for example, if your avatars are being synched from AD)

<add key="AttachmentsPath" value="" /> - store helpdesk attachment in disk instead of the database. Advanced setting do not touch.

<add key="DisableMailChecker" value="" /> - disable the mail-importing module for debugging purposes. Advanced, do no touch.

<add key="AppURL" value="http://support.yourcompany.com" /> - the helpdesk app will try to detect your app's URL automatically. But if you see it making mistakes from time to time - simply use this setting.

<add key="mailCheckerInterval" value="10" /> - allows you to set the interval for pulling emails from your mailboxes manually. The interval is in seconds. Changing this setting is not recommended - the absolute majority of systems will work fine with the default setting. You can try to increase the interval if you are constantly seeing a lot of ticket duplicates.

<add key="MailPswEncryptKey" value="" /> - email-server passwords will be encrypted in the database using this key (if not empty). Should be 8 characters, latin letters/numbers only. Example "18d6fg81". BACKUP THIS KEY AND NEVER CHANGE IT once you set it. Otherwise your mailbox-passwords in the DB will be lost and you will have to recreate the mailboxes in the app.