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.10.
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 run
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.
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
Admin Panel - Configuration
