Flicket Documentation

Flicket is a simple web based ticketing system written in Python using the flask web framework which supports English and French locales.

Why Flicket?

I could not find a simple open source ticketing system that I really liked. So, decided to have a crack at creating something written in Python.

Requirements

Operating System

This will run on either Linux or Windows. Mac is untested.

Python

Python =>3.6 - I have not tested earlier versions of Python 3.

SQL Database Server

Out of the box Flicket is configured to work with MySQL. But there should be no reason other SQLAlchemy supported databases won’t work just as well.

Note

When I last tried SQLite I had problems configuring the email settings within the administration settings. You may have to change them manually within SQLite.

Web Server

For a production environment a webserver such as Apache or nginx should be used to serve the application.

Installation

First read Requirements.

It is good practise to create a virtual environment before installing the python package requirements. Virtual environments can be considered a sand boxed python installation for a specific application. They are used since one application may require a different version of a python module than another.

Getting Flicket

The source code for Flicket is hosted at GitHub. You can either get the latest frozen zip file or use the latest master branch.

Warning

If you are upgrading from a previous version please read the CHANGELOG.

Master Branch

Get the latest master branch from github using git:

git clone https://github.com/evereux/flicket.git

Alternatively, download and unzip the master branch zip file.

Installing Python Requirements

Install the requirements using pip::

(env) C:\<folder_path>\flicket> pip install -r requirements.txt

Set Up

If using PostgreSQL or MySQL create your database and a database user that will access the flicket database. If using SQLite you can skip this step.

See SQLAlchemy_documentation for options.

Create the configuration json file:
```
python -m scripts.create_json
```
If you aren’t using SQLite edit config.json and change “db_driver”. “null” should be replaced by the driver you are using. See the documentation above regarding engines, dialects and drivers. For example, if you are using a MySQL database and want to use the pymysql driver.
```
"db_driver: "pymysql"
```
Install the driver you are using if not using SQLite. For example if you are using a MySQL database and want to use the pymysql driver.
```
pip install pymysql
```
Upgrade the database using manage.py from the command line:
```
flask db upgrade
```
Run the set-up script:. This is required to create the Admin user and site url defaults. These can be changed again via the admin panel once you log in:
```
flask run-set-up
```
Running development server for testing:
```
flask runserver
```

Log into the server using the username admin and the password defined during the setup process.

Administration

Command Line Options

From the command line the following options are available.

python manage.py

usage: manage.py [-?]
                 {db,run_set_up,export_users,import_users,update_user_posts,update_user_assigned,email_outstanding_tickets,runserver,shell}
                 ...

positional arguments:
  {db,run_set_up,export_users,import_users,update_user_posts,update_user_assigned,email_outstanding_tickets,runserver,shell}
    db                  Perform database migrations
    run_set_up
    export_users        Command used by manage.py to export all the users from
                        the database to a json file. Useful if we need a list
                        of users to import into other applications.
    import_users        Command used by manage.py to import users from a json
                        file formatted such: [ { username, name, email,
                        password. ]
    update_user_posts   Command used by manage.py to update the users total
                        post count. Use when upgrading from 0.1.4.
    update_user_assigned
                        Command used by manage.py to update the users total
                        post count. Use if upgrading to 0.1.7.
    email_outstanding_tickets
                        Script to be run independently of the webserver.
                        Script emails users a list of outstanding tickets that
                        they have created or been assigned. To be run on a
                        regular basis using a cron job or similar. Email
                        functionality has to be enabled.
    runserver           Runs the Flask development server i.e. app.run()
    shell               Runs a Python shell inside Flask application context.

optional arguments:
  -?, --help            show this help message and exit

Administration Config Panel

Options

For email configuration the following options are available. At a minimum you should configure mail_server, mail_port, mail_username and mail_password.

For more information regarding these settings see the documentation for Flask-Mail.

class flicket_admin.models.flicket_config.FlicketConfig(*args: Any, **kwargs: Any)

Server configuration settings editable by administrators only via the administration page /flicket_admin/config/.

For email configuration settings see https://flask-mail.readthedocs.io/en/latest/ for more information.

Parameters

mail_server (str) – example: smtp.yourcompany.com.
mail_port (int) – example: 567
mail_use_tls (bool) – example: true
mail_use_ssl (bool) – example: false
mail_debug (bool) – example: false
mail_username (str) – example: flicket.admin
mail_password (str) –
mail_default_sender (str) – example: flicket.admin@yourcompany.com
mail_max_emails (int) –
mail_suppress_send (bool) –
mail_ascii_attachments (bool) –
application_title (str) – Changes the default banner text from Flicket. Can typically be your company name.
posts_per_page (str) – Maximum number of posts / topics displayed per page.
allowed_extensions (str) – A comma delimited list of file extensions users are allowed to upload. DO NOT include the . before the extension letter.
ticket_upload_folder (str) – The folder used for file uploads.
base_url (str) – The sites base url. This is used to resolve urls for emails and links. Broken links are probably a result of not setting this value.
csv_dump_limit (str) – The maximum number of rows exported to csv.
change_category (bool) – Enable/disable change category.
change_category_only_admin_or_super_user (bool) – Only admins or super users can change category.

static extension_allowed(filename): Validates extension of a given filename and returns True if valid. Otherwise False. :param filename: :return:

static valid_extensions(): Returns a list of valid extensions. :return: list()

Exporting / Importing Flicket Users

Exporting

If you need to export the users from the Flicket database you can run the following command:

python manage.py export_users

This will output a json file formatted thus:

[
    {
        'username': 'jblogs',
        'name': 'Joe Blogs',
        'email':'jblogs@email.com',
        'password': 'bcrypt_encoded_string'
    }
]

Importing

If you need to import users run the following command:

python manage.py import_users

The file has to formatted as shown in the Exporting example.

Installing A Webserver

Currently the documentation will only describe how to install and configure the Apache webserver on Windows since this can be a bit trickier than on Linux. However, some of the steps here can also be used in Linux.

The instructions provided are for use with Python and Apache. You must ensure both Python and Apache have been compiled with the same version of Visual Studio. Also, Python and Apache must both be compiled for the same CPU architecture (x86 x64).

Also, the paths defined in this guide can be changed. You can by all means use different paths but you should try and and get the webserver running with the settings defined herein first.

Apache - Windows

Prior to installing a webserver you should confirm that flicket is working correctly by running the developement webserver as described in the Installation instructions.

Install mod_wsgi

Download the applicable mod_wsgi whl for your flavour of Apache and Python from the Unofficial Windows Binaries for Python Extension Packages page. For example, if you have Python 3.6 x64 and Apache 2.4 x64 you would get the whl mod_wsgi-4.6.5+ap24vc14-cp36-cp36m-win_amd64.whl.

Whilst active in your flicket virtual environment install mod_wsgi:

pip install <path_to_download>mod_wsgi-4.6.5+ap24vc14-cp36-cp36m-win_amd64.whl

Installing Apache

Download Apache compiled with VC14 from the apache lounge.

Unzip the apache folder to your c:\ directory. You should end up with a folder structure like this:

C:\Apache24
    C:\Apache24\bin
    C:\Apache24\cgi-bin
    ...

Open the file C:\Apache24\conf\httpd.conf in a text editor like notepad++.

Ensure SRVROOT is pointing to the correct folder:

SRVROOT "C:\Apache24"

Uncomment mod_version line:

LoadModule version_module modules/mod_version.so

Add the following lines (put these after the other LoadModule declarations):

LoadModule wsgi_module "<path_to_your_virtualenv>/lib/site-packages/mod_wsgi/server/mod_wsgi.cp36-win_amd64.pyd"
WSGIPythonHome "<path_to_your_virtualenv>"

Uncomment the vhosts line:

Include conf/extra/httpd-vhosts.conf

Edit the file C:\Apache24\conf\extra\httpd-vhosts.conf.

Comment out the existing configurations lines by prefixing with a # (good reference for future troubleshooting).

Add the following:

<VirtualHost *:8000>

    ServerName <ip_address or hostname>
    ServerAlias <ip_address or hostname>
    ServerAdmin <your_email@there.com>

    DocumentRoot C:\Apache24\htdocs

    <Directory C:\Apache24\htdocs>
    <IfVersion < 2.4>
        Order allow,deny
        Allow from all
    </IfVersion>
    <IfVersion >= 2.4>
        Require all granted
    </IfVersion>
    </Directory>

    WSGIScriptAlias / <path_to_flicket>run.wsgi
    # Make sure to enable so that the API requests will work.
    WSGIPassAuthorization On

    <Directory <path_to_flicket>>
    <IfVersion < 2.4>
        Order allow,deny
        Allow from all
    </IfVersion>
    <IfVersion >= 2.4>
        Require all granted
    </IfVersion>
    </Directory>

</VirtualHost>

Edit the file run.wsgi so that the path points to your Flicket virtual environment.

Register Apache As A Service

Navigate to the Apache folder and register the service with name Apache HTTP Server:

cd "C:\Apache24\bin"
httpd.exe -k install -n "Apache HTTP Server"

Start Apache

To start the service use either Windows Serivce Manage and start the service Apache HTTP Server or from the command prompt whilst in the folder c:\Apache24\bin:

httpd -k start -n "Apache HTTP Server"

Flicket should now be available in your browser by accessing http:\<ip_address or hostname>:8000

Troubleshooting

To troubleshoot problems starting the apache service or accessing the webpage you should start by reading your Apache installations log files normally located in c:Apache24logs.

Adding Additional Languages

Flicket now supports additional languages through the use of Flask Babel. To add an additional local:

Edit SUPPORTED_LANGUAGES in config.py and add an additional entry to the dictionary. For example: {‘en’: ‘English’, ‘fr’: ‘Francais’, ‘de’: ‘German’}
Whilst in the project root directory you now need to initialise the new language to generate a template file for it.

pybabel init -i messages.pot -d application/translations -l de

In the folder application/translations there should now be a new folder de.
Edit the file messages.po in that folder. For example:

msgid "403 Error - Forbidden"
msgstr "403 Error - Verboten"

Compile the translations for use:

pybabel compile -d application/translations

If any python or html text strings have been newly tagged for translation run:

pybabel extract -F babel.cfg -o messages.pot .

To get the new translations added to the .po files:

pybabel update -i messages.pot -d application/translations

Flicket - FAQ

What is Flicket?

Flicket is a simple open source ticketing system driven by the python flask web micro framework.

Flicket also uses the following python packages:

alembic, bcrypt, flask-admin, flask-babel, flask-login, flask-migrate, flask-principal, flask-sqlalchemy, flask-script, flask-wtf, jinja2, Markdown, WTForms

See README.rst for full requirements.

## Licensing

For licensing see LICENSE.md

Tickets

General

How do I create a ticket?

Select ‘create ticket’ from the Flicket pull down menu.
How do I assign a ticket?

Scenario: You have raised a ticket and you know to whom the ticket should be assigned.

Navigate to [flicket home page](/flicket/) and select the ticket you wish to assign. Within the ticket page is a button to assign ticket.
How do I release a ticket?

Scenario: You have been assigned a ticket but the ticket isn’t your responsibility to complete or you are unable to for another reason.

Navigate to [flicket home page](/flicket/) and select the ticket to which you have been assigned. Within the ticket page is a button to release the ticket from your ticket list.
How do I close a ticket?

Scenario: The ticket has been resolved to your satisfaction and you want to close the ticket.

Navigate to [flicket home page](/flicket/) and select the ticket which you would like to close. Within the ticket page is a button to replay and close the ticket.

Only the following persons can close a ticket: * Administrators. * The user which has been assigned the ticket. * The original creator of the ticket.

You may claim the ticket so that you may close it.
What is markdown?

Markdown is a lightweight markup language with plain text formatting syntax.

The text contents of a ticket can be made easier to read by employing markdown syntax.

Searching

The ticket main page can be filtered to show only results of a specific interest to you. Tickets can be filtered by department, category, user and a text string.

Departments

Note

Only administrators or super users can add / edit or delete departments.

How do I add new departments?

Navigate to Departments via the menu bar and use the add departments form.
How do I edit departments?

Navigate to [departments](/flicket/departments/) and select the edit link against the department name.
How do I delete departments?

Navigate to [departments](/flicket/departments/) and select the remove link against the department name. This is represented with a cross.

Categories

Note

Only administrators or super users can add / edit or delete categories.

How do I add categories?

Navigate to [departments](/flicket/departments/) and select the link to add categories against the appropriate department name.

How do I edit categories?

Navigate to [departments](/flicket/departments/) and select the link to add categories against the appropriate department name.

Screenshots

Home Page

Tickets

All tickets.

View Ticket

Create Ticket

Users

Admin Panel

Admin Panel - Add User

_images/2019-01-22_18_40_46-Add_User.png

Admin Panel - Configuration

_images/2019-01-22_18_43_25-Flicket_Configuration.png

Flicket Documentation

Why Flicket?

Requirements

Operating System

Python

SQL Database Server

Web Server

Installation

Getting Flicket

Master Branch

Installing Python Requirements

Set Up

Administration

Command Line Options

Administration Config Panel

Options

Exporting / Importing Flicket Users

Exporting

Importing

Installing A Webserver

Apache - Windows

Install mod_wsgi

Installing Apache

Register Apache As A Service

Start Apache

Troubleshooting

Adding Additional Languages

Flicket - FAQ

What is Flicket?

Tickets

General

Searching

Departments

Categories

Screenshots

Home Page

Tickets

View Ticket

Create Ticket

Users

Admin Panel

Admin Panel - Add User

Admin Panel - Configuration

API