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 manual is for Jitbit Helpdesk version 10 and later. The manual for earlier versions can be found here.

This file will guide through the basics of installation and operation of Jitbit Helpdesk Ticketing System.

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 .NET 6 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: Chrome, Firefox, MS Edge, Safari, etc.

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 (on Windows) or Nginx web-server (on Linux). We strongly recommend going with our hosted version, please try the server-version 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. Windows: Microsoft .NET 6 Hosting Bundle (direct download)
  2. Linux: .NET 6 (installation instructions)
  3. Windows: 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".
  4. Microsoft SQL Server 2012 or later configured to accept both Windows and SQL authentication (the so called "Mixed Mode")
    • "SQL Server Express" edition and "SQL Server Developer" edition are free editions of MS SQL Server (developer edition has strict license terms, please check). 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).
  5. Full-Text Search for SQL Server (this is optional, but highly recommended)
  6. If you plan using Windows-integrated authentication - you will need "Windows authentication" role service installed in IIS. Installation instructions

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

3. INSTALLING HELPDESK

Technically speaking, Jitbit Helpdesk is a web-app plus a SQL Server database. That's it, only two main enitites. You unpack the web-app to a folder on the server, you install the database on the database server. On Windows you need "IIS" (inluded with Windows) to run the web-app, on linux you don't.

If you prefer a video, here is a step-by-step tutorial:

Full Linux installation and upgrade manual

Jitbit HelpDesk can be installed in TWO WAYS:

3.1. INSTALLING via the installer (Windows only)

3.2. MANUAL INSTALLATION (Windows and linux)

3.2.1. Web-application install
3.2.2. Database install

Choose one of the following options

3.2.3. Run the app

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 on Windows or http://localhost:5000/ on Linux).

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: Jitbit Helpdesk comes with an auto-update module. To upgrade your app to the latest version simply launch Setup.exe in the app's folder. 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.

Here is a step-by-step video:

To upgrade your helpdesk to the latest version:

4.1. Upgrading from versions 10.4 and earlier

With version 10.5 we've moved from .NET 5 to .NET 6. All you need to do is install .NET 6 Hosting Bundle on Windows or .NET 6 SDK on Linux: download. You do not need to uninstall .NET 5.

4.2. Upgrading from versions 9.36 and earlier

With version 10 we've moved from .NET Framework to .NET 6 (also known as ".NET Core"). Before upgrading, please make sure you install Microsoft .NET 6 Hosting Bundle (direct download). After that launch Setup.exe and it should take care of the upgrade.

If you want to upgrade manually you need to move your settings from web.config to appsettings.json. That includes the database connection string, windows auth and additional settings you might've had in the "appSettings" section.

We recommend using the Setup.exe instead of a manual update.

4. Jitbit Helpdesk on Linux

In this manual, we will describe the process of installing Jitbit Helpdesk on Linux systems.

Before you proceed keep in mind that you will need to know what you are doing to run Jitbit on your own Linux server. If you do not have a competent Linux admin on hand please consider using the hosted version or installing it on Windows.

This manual is for Ubuntu-20.04 LTS. The commands for your Linux distro may be different. Jitbit Helpdesk is an ASP.NET Core app. Microsoft has a detailed manual on how to host such apps on Linux: Host ASP.NET Core on Linux with Nginx.

Prerequisites

To run Jitbit Helpdesk you'll need:

Installation on Linux

SQL Server

We will install SQL Server on Linux in this example. Here is the link to official Microsoft installation guide.

Run the following commands:

  1. wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
  2. sudo add-apt-repository "$(wget -qO- https://packages.microsoft.com/config/ubuntu/20.04/mssql-server-2019.list)" This command is Ubuntu 20.04 specific. Look for commands for your distro in Microsoft's manuals.
  3. sudo apt-get update
  4. sudo apt-get install -y mssql-server
  5. sudo /opt/mssql/bin/mssql-conf setup
  6. You will be prompted to pick an edition. We will use Express in this example.
  7. Accept the license terms and set a password for the SQL admin user (sa). We will need this password soon.
  8. You should have SQL Server installed and running after that.
  9. Install command-line tools: curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list (this command is Ubuntu 20.04 specific).
  10. sudo apt-get update
  11. sudo apt-get install mssql-tools unixodbc-dev

Create the database

Download the latest Jitbit package from our site and unpack it somewhere. Go inside the unpacked directory and find sql folder. We will need to run two scripts from there: CreateEmptyDB.sql and CreateTables.sql.

  1. /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'YOUR PASSWORD' -i CreateEmptyDB.sql
  2. /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'YOUR PASSWORD' -i CreateTables.sql

NOTE: The scripts above create a default Jitbit SQL User with the default password. We recommend you change this password later and update the appsettings.json file accordingly.

Running Jitbit Helpdesk

  1. Install .NET Runtime 6 or later. Follow the manual for your Linux version.
  2. Check that everything is working by running dotnet --list-runtimes. You should see something like this:
    $ dotnet --list-runtimes
                Microsoft.AspNetCore.App 6.0.4 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
                Microsoft.NETCore.App 6.0.4 [/usr/share/dotnet/shared/Microsoft.NETCore.App]
  3. Open appsettings.json in an editor and update the connection string to look like this: "DBConnectionString": "user id=JitbitHelpDeskUser;data source=localhost;initial catalog=JitbitHelpDesk;password=HDPassword1". If your SQL Server runs somewhere else you will need to update the connection string accordingly.
  4. Run this command in the root directory of the unpacked folder: dotnet HelpDesk.dll. You should see Jitbit Helpdesk[2170]: HelpDesk app started.
  5. Open http://localhost:5000/ in your browser. That's it - Jitbit Helpdesk is now running.

You can run Jitbit on a different port by using dotnet HelpDesk.dll --urls http://0.0.0.0:8080.

Configuring Nginx Reverse Proxy

We will not get into detail on how to configure Nginx reverse proxy since it is out of the scope of this document. This step is optional, but it is a good idea to run a web app behind a reverse proxy. Here is the official manual from Microsoft: Configure a reverse proxy server. They have one for Apache as well.

Upgrading Jitbit on Linux

This applies to both: upgrading from trial to full version and upgrading to the latest version. The process is the same.

There are two steps to an upgrade: updating the application files and upgrading the DB.

Download the latest version from our site, unpack it and run the following:

  1. /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'YOUR PASSWORD' -i sql/UpgradeFromOlderVersions.sql. This upgrades the DB to the latest version. If your SQL Server runs somewhere else you will need to execute this script there manually.
  2. Replace your local Jitbit files with the new ones except the appsettings.json file.
  3. Restart the app.

5. ADVANCED FEATURES

Editing appsettings.json

Some of the advanced Jitbit Helpdesk features reside inside appsettings.json file in the root helpdesk directory. You can open this file with any plain text editor. You have to recyle IIS for the changes to take effect.

Appsettings.json is in JSON format. If you make a mistake the app will crash after the IIS recycle. Use this validator before saving.

5.1 Full-Text Search

By default Helpdesk searches only within tickets subject and text. 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'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. 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 appsettings.json. Open the appsettings.json file in the root directory of helpdesk and find "AppURL" setting and set it to the desired URL.

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 appsettings.json file, then open it in Notepad
  6. Find AttachmentsPath tag and set its value to the desired path.
  7. Recycle the app pool and you're done

6. Windows-integrated authentication

Jitbit HelpDesk supports Windows-integrated authentication and integrating with your existing Active Directory (AD) user's catalog. To enable Windows-integrated authentication edit the appsettings.json file and un-comment this line:

"Auth": "Windows"
. Also remember to check if Windows-integrated authentication is enabled in IIS directory where HelpDesk is installed. Recycle IIS after the change.

If you plan using Windows-authentication under IIS - 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 administrator

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 appsettings.json file: "WindowsAdminUsername": "DOMAIN\\User"

The username is case-sensitive. To see the exact casing of your own username execute whoami in the cmd.exe. Also note that every slash (\) should be escaped with another slash in the appsettings.json file.

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 appsettings.json settings

"WindowsAdminUsername": "DOMAIN\User" - if you're using helpdesk via Windows authentication and somehow unable to gain admin access to it - type your username into this setting

"LogErrors": true - Log helpdesk errors in the server event log

"EmailErrorTo": "admin-john@test.com, admin-pete@test.com" - Send error notifications to these addresses

"DisallowChangingAvatars": "false" - restrict users from changing their avatars (for example, if your avatars are being synched from AD)

"AttachmentsPath": "c:\hdfiles" - store helpdesk attachment in disk instead of the database. Advanced setting do not touch.

"DisableMailChecker": "true" - disable the mail-importing module for debugging purposes. Advanced, do no touch.

"AppURL" :"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.

"MailPswEncryptKey": "" - 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.