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.5 - 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.
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.
Zip Package¶
Download Flicket Dist.zip and unzip.
Installing Python Requirements¶
Install the requirements using pip::
(env) C:\<folder_path>\flicket> pip install -r requirements.txt
Set Up¶
Create your database and a database user that will access the flicket database.
If you are using a database server other than MySQL you should change the db_type value within config.py. See SQLAlchemy_documentation for options.
Create the configuration json file:
python -m scripts.create_json
Initialise the database using manage.py from the command line:
python manage.py db init python manage.py db migrate python manage.py 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:
python manage.py run_set_up
Running development server for testing:
python manage.py 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(**kwargs)¶ Server configuration settings editable by administrators only via the adminstration 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.
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:Apache24confhttpd.conf in a text editor like notepad++.
Modify the following line to read the following:
SRVROOT "C:\Apache24"
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
Uncomment mod_version line
LoadModule version_module modules/mod_version.so
Edit the file C:Apache24confextrahttpd-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
<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:Apache24bin:
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 repsonsibility to complete or you are unable to for another reason.
Navgiate 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.
Navgiate 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.
