docs: 📝 hamronize all docs files (fix indent, code blocks, links, and some wording)

This commit is contained in:
Benbb96 2024-03-12 12:40:51 +01:00
parent 4b096a3010
commit ed1fd8c1f1
No known key found for this signature in database
12 changed files with 246 additions and 202 deletions

View File

@ -13,7 +13,7 @@ Before django-helpdesk will be much use, you need to do some basic configuration
Don't forget to set the relevant Django environment variables in your crontab::
*/5 * * * * /path/to/helpdesksite/manage.py get_email
*/5 * * * * /path/to/helpdesksite/manage.py get_email
This will run the e-mail import every 5 minutes
@ -32,13 +32,13 @@ Before django-helpdesk will be much use, you need to do some basic configuration
4. If you wish to automatically escalate tickets based on their age, set up a cronjob to run the escalation command on a regular basis::
0 * * * * /path/to/helpdesksite/manage.py escalate_tickets
0 * * * * /path/to/helpdesksite/manage.py escalate_tickets
This will run the escalation process hourly, using the 'Escalation Days' setting for each queue to determine which tickets to escalate.
5. If you wish to exclude some days (eg, weekends) from escalation calculations, enter the dates manually via the Admin, or setup a cronjob to run a management command on a regular basis::
0 0 * * 0 /path/to/helpdesksite/manage.py create_escalation_exclusions --days saturday,sunday --escalate-verbosely
0 0 * * 0 /path/to/helpdesksite/manage.py create_escalation_exclusions --days saturday,sunday --escalate-verbosely
This will, on a weekly basis, create exclusions for the coming weekend.
@ -46,9 +46,9 @@ Before django-helpdesk will be much use, you need to do some basic configuration
7. If you do not send mail directly from your web server (eg, you need to use an SMTP server) then edit your ``settings.py`` file so it contains your mail server details::
EMAIL_HOST = 'XXXXX'
EMAIL_HOST_USER = 'YYYYYY@ZZZZ.PPP'
EMAIL_HOST_PASSWORD = '123456'
EMAIL_HOST = 'XXXXX'
EMAIL_HOST_USER = 'YYYYYY@ZZZZ.PPP'
EMAIL_HOST_PASSWORD = '123456'
8. If you wish to use SOCKS4/5 proxy with Helpdesk Queue email operations, install PySocks manually. Please note that mixing both SOCKS and non-SOCKS email sources for different queues is only supported under Python 2; on Python 3, SOCKS proxy support is all-or-nothing: either all queue email sources must use SOCKS or none may use it. If you need this functionality on Python 3 please `let us know <https://github.com/django-helpdesk/django-helpdesk/issues/new>`_.
@ -88,6 +88,6 @@ You may add your own site specific navigation header to be included inside the <
1. Create an override template in your project's templates directory::
helpdesk/custom_navigation_header.html
helpdesk/custom_navigation_header.html
2. Update the contents to display your custom navigation.

View File

@ -3,6 +3,4 @@ Custom Fields
django-helpdesk supports custom fields on the ``Ticket`` model. These fields are created by using the Django administration tool, and are shown on both the public and staff submission forms. You can use most Django field types including text, integer, boolean, and list.
The demo at http://django-helpdesk-demo.herokuapp.com contains an example of each type of custom field, including a mix of mandatory and optional fields.
Custom fields are relatively inefficient; you can search them, but this might degrade performance of your installation if you make use of custom fields. They can be useful for tracking extra information that your organisation needs but that isn't supported out of the box.

View File

@ -6,4 +6,3 @@ django-helpdesk supports custom HTML templates that can be styled with CSS.
In particular, users can include a file named `helpdesk-customize.css` in their django project directory to provide CSS overrides easily.
In general, entire HTML and CSS templates may be overriden by including a file of the same name in the project directory. Django automatically searches the project directory before searching for default templates included with django-helpdesk.

View File

@ -1,5 +1,5 @@
Ticket submission with embeded iframe
-------------------------------------
=====================================
Django-helpdesk associates an email address with each submitted ticket. If you integrate django-helpdesk directly into your django application, logged in users will automatically have their email address set when they visit the `/tickets/submit/` form. If you wish to pre-fill fields in this form, you can do so simply by setting the following query parameters:

View File

@ -16,18 +16,13 @@ Contents
settings
spam
custom_fields
custom_templates
api
webhooks
iframe_submission
teams
license
How Does It Look?
-----------------
You can see a demo installation at http://django-helpdesk-demo.herokuapp.com/
Quick Start
-----------
@ -72,5 +67,3 @@ Optionally, their access to view tickets, both on the dashboard and through sear
Licensing
---------
django-helpdesk is released under the BSD license, however it packages 3rd party applications which may be using a different license. More details can be found in the :doc:`license` documentation.

View File

@ -1,12 +1,12 @@
.. _installation:
Installation
============
.. note::
For standalone installation, refer to the :doc:`standalone installation docs <standalone>`.
For standalone installation, refer to the :doc:`standalone installation docs <standalone>`.
``django-helpdesk`` installation isn't difficult, but it requires you have a bit of existing know-how about Django.
``django-helpdesk`` installation isn't difficult, but it requires you have a bit
of existing know-how about Django.
Prerequisites
@ -33,9 +33,12 @@ Installing using PIP
Try using ``pip install django-helpdesk``. Go and have a beer to celebrate Python packaging.
Checkout ``main`` branch from git (Cutting Edge)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you're planning on editing the code or just want to get whatever is the latest and greatest, you can clone the official Git repository with ``git clone git://github.com/django-helpdesk/django-helpdesk.git``. Each official release of ``django-helpdesk`` is tagged.
If you're planning on editing the code or just want to get whatever is the latest
and greatest, you can clone the official Git repository with
``git clone git://github.com/django-helpdesk/django-helpdesk.git``. Each official
release of ``django-helpdesk`` is tagged.
Copy the ``helpdesk`` folder into your ``PYTHONPATH`` or add it to your ``PYTHONPATH``.
@ -54,100 +57,134 @@ If you're on a brand new Django installation, make sure you do a ``migrate``
errors with trying to create User settings.
1. Edit your ``settings.py`` file add the following entries:
- add ``helpdesk`` to the ``INSTALLED_APPS`` along with some other required entries in the ``django.contrib`` package.
- Add ``helpdesk`` to the ``INSTALLED_APPS`` along with some other required
entries in the ``django.contrib`` package.
An example of the core ``INSTALLED_APPS`` requirements for this app are shown below::
An example of the core ``INSTALLED_APPS`` requirements for this app
are shown below::
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites', # Required for determining domain url for use in emails
'django.contrib.admin', # Required for helpdesk admin/maintenance
'django.contrib.humanize', # Required for elapsed time formatting
'bootstrap4form', # Required for nicer formatting of forms with the default templates
'rest_framework', # required for the API
'django_cleanup.apps.CleanupConfig', # Remove this if you do NOT want to delete files on the file system when the associated record is deleted in the database
'helpdesk', # This is us!
)
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites', # Required for determining domain url for use in emails
'django.contrib.admin', # Required for helpdesk admin/maintenance
'django.contrib.humanize', # Required for elapsed time formatting
'bootstrap4form', # Required for nicer formatting of forms with the default templates
'rest_framework', # required for the API
'django_cleanup.apps.CleanupConfig', # Remove this if you do NOT want to delete files on the file system when the associated record is deleted in the database
'helpdesk', # This is us!
)
- Enable or disable Teams based ticket assignment by setting the boolean flag named ``HELPDESK_TEAMS_MODE_ENABLED`` to True or False.
- Enable or disable Teams based ticket assignment by setting the boolean flag named
``HELPDESK_TEAMS_MODE_ENABLED`` to ``True`` or ``False``.
IMPORTANT NOTE: It is ENABLED by default if you do not set this flag to False
See the :doc::ref:`teams`. section for a detailed explanation of how to use teams mode.
See the :doc:`Working with teams<teams>` section for a detailed explanation of how to
use teams mode.
Below is an example for disabling teams::
HELPDESK_TEAMS_MODE_ENABLED=False
HELPDESK_TEAMS_MODE_ENABLED=False
- Your ``settings.py`` file should also define a ``SITE_ID``
This will allow multiple projects to share a single database, and is required by ``django.contrib.sites`` in Django 1.9+.
If you aren't running multiple sites, you can simply add a default ``SITE_ID`` to ``settings.py``
This will allow multiple projects to share a single database, and is
required by ``django.contrib.sites`` in Django 1.9+.
If you aren't running multiple sites, you can simply add a default
``SITE_ID`` to ``settings.py``
Below is an example for setting a default::
SITE_ID = 1
SITE_ID = 1
2. Make sure django-helpdesk is accessible via ``urls.py``. Add the
following lines to ``urls.py``::
2. Make sure django-helpdesk is accessible via ``urls.py``. Add the following lines to ``urls.py``::
from django.conf.urls import include
path('helpdesk/', include('helpdesk.urls')),
from django.conf.urls import include
path('helpdesk/', include('helpdesk.urls')),
Note that you can change 'helpdesk/' to anything you like, such as
'support/' or 'help/'. If you want django-helpdesk to be available at
the root of your site (for example at http://support.mysite.tld/) then
the path line will be as follows::
Note that you can change 'helpdesk/' to anything you like, such as 'support/' or 'help/'. If you want django-helpdesk to be available at the root of your site (for example at http://support.mysite.tld/) then the path line will be as follows::
path('', include('helpdesk.urls', namespace='helpdesk')),
path('', include('helpdesk.urls', namespace='helpdesk')),
This line will have to come *after* any other lines in your urls.py such
as those used by the Django admin.
This line will have to come *after* any other lines in your urls.py such as those used by the Django admin.
Note that the `helpdesk` namespace is no longer required for Django 1.9+ and you can use a different namespace.
Note that the `helpdesk` namespace is no longer required for Django 1.9+
and you can use a different namespace.
However, it is recommended to use the default namespace name for clarity.
3. Create the required database tables.
Migrate using Django migrations::
python manage.py migrate helpdesk
python manage.py migrate helpdesk
4. Include your static files in your public web path::
python manage.py collectstatic
python manage.py collectstatic
5. Inside your ``MEDIA_ROOT`` folder, inside the ``helpdesk`` folder, is a folder called ``attachments``. Ensure your web server software can write to this folder - something like this should do the trick::
5. Inside your ``MEDIA_ROOT`` folder, inside the ``helpdesk`` folder, is a
folder called ``attachments``. Ensure your web server software can write
to this folder - something like this should do the trick::
chown www-data:www-data attachments/
chmod 700 attachments
chown www-data:www-data attachments/
chmod 700 attachments
(substitute www-data for the user / group that your web server runs as, eg 'apache' or 'httpd')
(substitute www-data for the user / group that your web server runs as, eg
'apache' or 'httpd')
If all else fails, you could ensure all users can write to it::
chmod 777 attachments/
chmod 777 attachments/
But this is NOT recommended, especially if you're on a shared server.
6. Ensure that your ``attachments`` folder has directory listings turned off, to ensure users don't download files that they are not specifically linked to from their tickets.
6. Ensure that your ``attachments`` folder has directory listings turned off,
to ensure users don't download files that they are not specifically linked
to from their tickets.
If you are using Apache, put a ``.htaccess`` file in the ``attachments`` folder with the following content::
If you are using Apache, put a ``.htaccess`` file in the ``attachments``
folder with the following content::
Options -Indexes
Options -Indexes
You will also have to make sure that ``.htaccess`` files aren't being ignored.
Ideally, accessing http://MEDIA_URL/helpdesk/attachments/ will give you a 403 access denied error.
Ideally, accessing http://MEDIA_URL/helpdesk/attachments/ will give you a 403
access denied error.
7. If you already have a view handling your logins, then great! If not, add the following to ``settings.py`` to get your Django installation to use the login view included in ``django-helpdesk``::
7. If you already have a view handling your logins, then great! If not, add the
following to ``settings.py`` to get your Django installation to use the login
view included in ``django-helpdesk``::
LOGIN_URL = '/helpdesk/login/'
LOGIN_URL = '/helpdesk/login/'
Alter the URL to suit your installation path.
8. Load initial e-mail templates, otherwise you will not be able to send e-mail::
python manage.py loaddata emailtemplate.json
python manage.py loaddata emailtemplate.json
9. If you intend on using local mail directories for processing email into tickets, be sure to create the mail directory before adding it to the queue in the Django administrator interface. The default mail directory is ``/var/lib/mail/helpdesk/``. Ensure that the directory has appropriate permissions so that your Django/web server instance may read and write files from this directory.
9. If you intend on using local mail directories for processing email into tickets,
be sure to create the mail directory before adding it to the queue in the
Django administrator interface. The default mail directory is
``/var/lib/mail/helpdesk/``. Ensure that the directory has appropriate
permissions so that your Django/web server instance may read and write
files from this directory.
Note that by default, any mail files placed in your local directory will be permanently deleted after being successfully processed. It is strongly recommended that you take further steps to save emails if you wish to retain backups.
Note that by default, any mail files placed in your local directory will be
permanently deleted after being successfully processed. It is strongly recommended
that you take further steps to save emails if you wish to retain backups.
Also, be aware that if a disk error occurs and the local file is not deleted, the mail may be processed multiple times and generate duplicate tickets until the file is removed. It is recommended to monitor log files for ERRORS when a file is unable to be deleted.
Also, be aware that if a disk error occurs and the local file is not deleted,
the mail may be processed multiple times and generate duplicate tickets until
the file is removed. It is recommended to monitor log files for ERRORS when a
file is unable to be deleted.
Upgrading from previous versions
--------------------------------

View File

@ -1,7 +1,7 @@
License
=======
django-helpdesk is released under the terms of the BSD license. You must agree to these terms before installing or using django-helpdesk.::
django-helpdesk is released under the terms of the BSD license. You must agree to these terms before installing or using django-helpdesk. ::
Copyright (c) 2008, Ross Poulton (Trading as Jutda)
Copyright (c) 2008-2021, django-helpdesk contributors
@ -42,6 +42,7 @@ applications are included below.
License for jQuery & jQuery UI
------------------------------
::
Copyright (c) 2007 John Resig, http://jquery.com/
Permission is hereby granted, free of charge, to any person obtaining
@ -66,6 +67,7 @@ License for jQuery & jQuery UI
License for jQuery UI 'Smoothness' theme
----------------------------------------
::
/*
* jQuery UI screen structure and presentation
* This CSS file was generated by ThemeRoller, a Filament Group Project for jQuery UI
@ -76,6 +78,7 @@ License for jQuery UI 'Smoothness' theme
License for akismet.py
----------------------
::
Copyright (c) 2003-2009, Michael Foord
All rights reserved.
E-mail : fuzzyman AT voidspace DOT org DOT uk
@ -112,6 +115,7 @@ License for akismet.py
License for jqPlot
------------------
::
Copyright (c) 2009 - 2010 Chris Leonello
Permission is hereby granted, free of charge, to any person obtaining a copy

View File

@ -22,6 +22,7 @@ First, django-helpdesk needs ``django.core.context_processors.request`` activat
The following settings can be changed in your ``settings.py`` file to help change the way django-helpdesk operates. There are quite a few settings available to toggle functionality within django-helpdesk.
HELPDESK_DEFAULT_SETTINGS
-------------------------
@ -30,12 +31,13 @@ django-helpdesk has a built in ``UserSettings`` entity with per-user options tha
If you want to override the default settings for your users, create ``HELPDESK_DEFAULT_SETTINGS`` as a dictionary in ``settings.py``. The default is below::
HELPDESK_DEFAULT_SETTINGS = {
'use_email_as_submitter': True,
'email_on_ticket_assign': True,
'email_on_ticket_change': True,
'login_view_ticketlist': True,
'tickets_per_page': 25
}
'use_email_as_submitter': True,
'email_on_ticket_assign': True,
'email_on_ticket_change': True,
'login_view_ticketlist': True,
'tickets_per_page': 25
}
Generic Options
---------------
@ -87,7 +89,7 @@ These changes are visible throughout django-helpdesk
- **VALID_EXTENSIONS** Valid extensions for file types that can be attached to tickets
**Default:** ``VALID_EXTENSIONS = ['.txt', '.asc', '.htm', '.html', '.pdf', '.doc', '.docx', '.odt', '.jpg', '.png', '.eml']
**Default:** ``VALID_EXTENSIONS = ['.txt', '.asc', '.htm', '.html', '.pdf', '.doc', '.docx', '.odt', '.jpg', '.png', '.eml']``
- **QUEUE_EMAIL_BOX_UPDATE_ONLY** Only process mail with a valid tracking ID; all other mail will be ignored instead of creating a new ticket.
@ -109,6 +111,7 @@ These changes are visible throughout django-helpdesk
**Default:** ``HELPDESK_TICKETS_TIMELINE_ENABLED = True``
Options shown on public pages
-----------------------------
@ -149,9 +152,9 @@ Options that change ticket updates
- **HELPDESK_ALLOW_NON_STAFF_TICKET_UPDATE** Allow non-staff users to interact with tickets?
Set to True to allow any authenticated user to manage tickets.
You can also apply a custom authorisation logic for identifying helpdesk staff members, by setting this to a callable.
In that case, the value should be a function accepting the active user as a parameter and returning True if the user is considered helpdesk staff, e.g.
In that case, the value should be a function accepting the active user as a parameter and returning True if the user is considered helpdesk staff, e.g.::
lambda u: u.is_authenticated() and u.is_active and u.groups.filter(name='helpdesk_staff').exists()))
lambda u: u.is_authenticated() and u.is_active and u.groups.filter(name='helpdesk_staff').exists()
**Default:** ``HELPDESK_ALLOW_NON_STAFF_TICKET_UPDATE = False``
@ -203,36 +206,36 @@ Options that change ticket properties
The **default** is below::
HELPDESK_TICKET_STATUS_CHOICES = (
(HELPDESK_TICKET_OPEN_STATUS, _('Open')),
(HELPDESK_TICKET_REOPENED_STATUS, _('Reopened')),
(HELPDESK_TICKET_RESOLVED_STATUS, _('Resolved')),
(HELPDESK_TICKET_CLOSED_STATUS, _('Closed')),
(HELPDESK_TICKET_DUPLICATE_STATUS, _('Duplicate')),
)
HELPDESK_TICKET_STATUS_CHOICES = (
(HELPDESK_TICKET_OPEN_STATUS, _('Open')),
(HELPDESK_TICKET_REOPENED_STATUS, _('Reopened')),
(HELPDESK_TICKET_RESOLVED_STATUS, _('Resolved')),
(HELPDESK_TICKET_CLOSED_STATUS, _('Closed')),
(HELPDESK_TICKET_DUPLICATE_STATUS, _('Duplicate')),
)
If you wish to modify or introduce new status choices, you may add them like this::
# don't forget to import the gettext_lazy function at the begining of your settings file
from django.utils.translation import gettext_lazy as _
# Don't forget to import the gettext_lazy function at the begining of your settings file
from django.utils.translation import gettext_lazy as _
# explicitly define status list integer values
HELPDESK_TICKET_OPEN_STATUS = 1
HELPDESK_TICKET_REOPENED_STATUS = 2
HELPDESK_TICKET_RESOLVED_STATUS = 3
HELPDESK_TICKET_CLOSED_STATUS = 4
HELPDESK_TICKET_DUPLICATE_STATUS = 5
HELPDESK_TICKET_FORKED_STATUS = 6
# Explicitly define status list integer values
HELPDESK_TICKET_OPEN_STATUS = 1
HELPDESK_TICKET_REOPENED_STATUS = 2
HELPDESK_TICKET_RESOLVED_STATUS = 3
HELPDESK_TICKET_CLOSED_STATUS = 4
HELPDESK_TICKET_DUPLICATE_STATUS = 5
HELPDESK_TICKET_FORKED_STATUS = 6
# create the list with associated labels
HELPDESK_TICKET_STATUS_CHOICES = (
(HELPDESK_TICKET_OPEN_STATUS, _('Open')),
(HELPDESK_TICKET_REOPENED_STATUS, _('Reopened')),
(HELPDESK_TICKET_RESOLVED_STATUS, _('Resolved')),
(HELPDESK_TICKET_CLOSED_STATUS, _('Closed')),
(HELPDESK_TICKET_DUPLICATE_STATUS, _('Duplicate')),
(HELPDESK_TICKET_FORKED_STATUS, _('Forked')),
)
# Create the list with associated labels
HELPDESK_TICKET_STATUS_CHOICES = (
(HELPDESK_TICKET_OPEN_STATUS, _('Open')),
(HELPDESK_TICKET_REOPENED_STATUS, _('Reopened')),
(HELPDESK_TICKET_RESOLVED_STATUS, _('Resolved')),
(HELPDESK_TICKET_CLOSED_STATUS, _('Closed')),
(HELPDESK_TICKET_DUPLICATE_STATUS, _('Duplicate')),
(HELPDESK_TICKET_FORKED_STATUS, _('Forked')),
)
- **HELPDESK_TICKET_OPEN_STATUSES** Define the list of statuses to be considered as a type of open status.
@ -240,56 +243,58 @@ Options that change ticket properties
If you have added the ``HELPDESK_TICKET_FORKED_STATUS`` status and wish to have django-helpdesk treat it as an open status choice, add it to the list of OPEN_STATUSES like this::
HELPDESK_TICKET_OPEN_STATUSES = (HELPDESK_TICKET_OPEN_STATUS,
HELPDESK_TICKET_REOPENED_STATUS,
HELPDESK_TICKET_FORKED_STATUS)
HELPDESK_TICKET_OPEN_STATUSES = (HELPDESK_TICKET_OPEN_STATUS,
HELPDESK_TICKET_REOPENED_STATUS,
HELPDESK_TICKET_FORKED_STATUS)
- **HELPDESK_TICKET_STATUS_CHOICES_FLOW** Customize the allowed state changes depending on the current state.
The **default** is below::
HELPDESK_TICKET_STATUS_CHOICES_FLOW = {
HELPDESK_TICKET_OPEN_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_REOPENED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_RESOLVED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
HELPDESK_TICKET_CLOSED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
HELPDESK_TICKET_DUPLICATE_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
}
HELPDESK_TICKET_STATUS_CHOICES_FLOW = {
HELPDESK_TICKET_OPEN_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_REOPENED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_RESOLVED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
HELPDESK_TICKET_CLOSED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
HELPDESK_TICKET_DUPLICATE_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
}
If you wish to modify or have introduce new status choices, you may configure their status change flow like this::
# adding HELPDESK_TICKET_FORKED_STATUS to the other allowed states flow and defining its own flow
HELPDESK_TICKET_STATUS_CHOICES_FLOW = {
HELPDESK_TICKET_OPEN_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_REOPENED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_RESOLVED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
HELPDESK_TICKET_CLOSED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
HELPDESK_TICKET_DUPLICATE_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_FORKED_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
}
# Adding HELPDESK_TICKET_FORKED_STATUS to the other allowed states flow and defining its own flow
HELPDESK_TICKET_STATUS_CHOICES_FLOW = {
HELPDESK_TICKET_OPEN_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_REOPENED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_RESOLVED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
HELPDESK_TICKET_CLOSED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
HELPDESK_TICKET_DUPLICATE_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
HELPDESK_TICKET_FORKED_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
}
- **HELPDESK_TICKET_PRIORITY_CHOICES** Customize the priority choices for all tickets.
The **default** is below::
HELPDESK_TICKET_PRIORITY_CHOICES = (
(1, _('1. Critical')),
(2, _('2. High')),
(3, _('3. Normal')),
(4, _('4. Low')),
(5, _('5. Very Low')),
)
HELPDESK_TICKET_PRIORITY_CHOICES = (
(1, _('1. Critical')),
(2, _('2. High')),
(3, _('3. Normal')),
(4, _('4. Low')),
(5, _('5. Very Low')),
)
If you have a new instance, you may override those settings but if you want to keep previous tickets priorities and add new choices, you may increment integer values like this::
HELPDESK_TICKET_PRIORITY_CHOICES = (
(1, _('1. Critical')),
(2, _('2. High')),
(3, _('3. Normal')),
(4, _('4. Low')),
(5, _('5. Very Low')),
(6, _('6. Cold')),
(7, _('7. Hot')),
)
HELPDESK_TICKET_PRIORITY_CHOICES = (
(1, _('1. Critical')),
(2, _('2. High')),
(3, _('3. Normal')),
(4, _('4. Low')),
(5, _('5. Very Low')),
(6, _('6. Cold')),
(7, _('7. Hot')),
)
Time Tracking Options
---------------------
@ -304,15 +309,15 @@ Time Tracking Options
If HELPDESK_FOLLOWUP_TIME_SPENT_AUTO is ``True``, you may set open hours to remove off hours from 'time_spent'::
HELPDESK_FOLLOWUP_TIME_SPENT_OPENING_HOURS = {
"monday": (8.5, 19),
"tuesday": (8.5, 19),
"wednesday": (8.5, 19),
"thursday": (8.5, 19),
"friday": (8.5, 19),
"saturday": (0, 0),
"sunday": (0, 0),
}
HELPDESK_FOLLOWUP_TIME_SPENT_OPENING_HOURS = {
"monday": (8.5, 19),
"tuesday": (8.5, 19),
"wednesday": (8.5, 19),
"thursday": (8.5, 19),
"friday": (8.5, 19),
"saturday": (0, 0),
"sunday": (0, 0),
}
Valid hour values must be set between 0 and 23.9999.
In this example 8.5 is interpreted as 8:30AM, saturdays and sundays don't count.
@ -323,7 +328,7 @@ Time Tracking Options
This example removes Christmas and New Year's Eve in 2024::
HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_HOLIDAYS = ("2024-12-25", "2024-12-31",)
HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_HOLIDAYS = ("2024-12-25", "2024-12-31",)
- **HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_STATUSES** List of ticket statuses to exclude from automatic follow-up 'time_spent' calculation.
@ -331,15 +336,16 @@ Time Tracking Options
This example will have follow-ups to resolved ticket status not to be counted in::
HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_STATUSES = (HELPDESK_TICKET_RESOLVED_STATUS,)
HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_STATUSES = (HELPDESK_TICKET_RESOLVED_STATUS,)
- **HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_QUEUES** List of ticket queues slugs to exclude from automatic follow-up 'time_spent' calculation.
**Default:** ``HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_QUEUES = ()``
This example will have follow-ups to ticket queue 'time-not-counting-queue' not to be counted in::
This example will have follow-ups excluded from time calculation if they belong to the queue with slug ``time-not-counting-queue``::
HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_QUEUES = ('time-not-counting-queue',)
HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_QUEUES = ('time-not-counting-queue',)
Staff Ticket Creation Settings
------------------------------
@ -348,6 +354,7 @@ Staff Ticket Creation Settings
**Default:** ``HELPDESK_CREATE_TICKET_HIDE_ASSIGNED_TO = False``
Staff Ticket View Settings
------------------------------
@ -356,7 +363,6 @@ Staff Ticket View Settings
**Default:** ``HELPDESK_ENABLE_PER_QUEUE_STAFF_PERMISSION = False``
Default E-Mail Settings
-----------------------
@ -368,6 +374,7 @@ The following settings default to ``None`` but can be set as defaults, rather th
- ``QUEUE_EMAIL_BOX_USER``
- ``QUEUE_EMAIL_BOX_PASSWORD``
Discontinued Settings
---------------------

View File

@ -22,11 +22,10 @@ This service is free to use, within their terms and conditions.
If you have either of these settings enabled, the spam filtering will be done automatically. If you have *both* settings configured, TypePad will be used instead of Akismet.
Example
~~~~~~~
A sample configuration in ``settings.py`` may be::
TYPEPAD_ANTISPAM_API_KEY = 'abc123'
TYPEPAD_ANTISPAM_API_KEY = 'abc123'

View File

@ -1,6 +1,5 @@
==============================
Django-Helpdesk Standalone Installation
==============================
=======================================
Installation
------------
@ -9,25 +8,25 @@ Installation
.. code-block:: bash
git clone git@github.com:django-helpdesk/django-helpdesk.git
git clone git@github.com:django-helpdesk/django-helpdesk.git
2. Go to the standalone helpdesk installation directory:
.. code-block:: bash
cd django-helpdesk/standalone
cd django-helpdesk/standalone
3. Execute the installation script:
.. code-block:: bash
./setup.sh
./setup.sh
4. Start the services:
.. code-block:: bash
docker-compose up
docker-compose up
Creating an Admin User
----------------------
@ -36,25 +35,25 @@ Creating an Admin User
.. code-block:: bash
docker ps
docker ps
2. Execute into the `standalone-django-helpdesk-1` container:
.. code-block:: bash
docker exec -it standalone-django-helpdesk-1 bash
docker exec -it standalone-django-helpdesk-1 bash
3. Change directory to the application's root:
.. code-block:: bash
cd /opt/django-helpdesk/standalone
cd /opt/django-helpdesk/standalone
4. Create a superuser:
.. code-block:: bash
python3 manage.py createsuperuser
python3 manage.py createsuperuser
5. Visit `localhost:80` in your browser to access the server. Navigate to the `/admin` URL to set up new users. Ensure to configure the "Site" in the admin section for ticket email URLs to function correctly.
@ -71,16 +70,16 @@ Configuration for Production Use
.. code-block:: html
<style>
.navbar-brand {
background: url("https://www.libertyaces.com/files/liberty-logo.png") no-repeat;
background-size: auto;
width: 320px;
background-size: contain;
height: 40px;
text-align: right;
}
</style>
<style>
.navbar-brand {
background: url("https://www.libertyaces.com/files/liberty-logo.png") no-repeat;
background-size: auto;
width: 320px;
background-size: contain;
height: 40px;
text-align: right;
}
</style>
AWS SES Email Configuration
---------------------------
@ -89,23 +88,22 @@ An example `local_settings` configuration for utilizing AWS SES for email:
.. code-block:: python
from .settings import *
import os
from .settings import *
import os
DEFAULT_FROM_EMAIL = "support@bitswan.space"
SERVER_EMAIL = "support@bitswan.space"
AWS_ACCESS_KEY_ID = os.environ.get("AWS_ACCESS_KEY_ID")
EMAIL_BACKEND = "django_ses.SESBackend"
AWS_SES_REGION_NAME = "eu-west-1"
AWS_SES_REGION_ENDPOINT = "email.eu-west-1.amazonaws.com"
AWS_SECRET_ACCESS_KEY = os.environ.get("AWS_SECRET_ACCESS_KEY")
DEFAULT_FROM_EMAIL = "support@bitswan.space"
SERVER_EMAIL = "support@bitswan.space"
AWS_ACCESS_KEY_ID = os.environ.get("AWS_ACCESS_KEY_ID")
EMAIL_BACKEND = "django_ses.SESBackend"
AWS_SES_REGION_NAME = "eu-west-1"
AWS_SES_REGION_ENDPOINT = "email.eu-west-1.amazonaws.com"
AWS_SECRET_ACCESS_KEY = os.environ.get("AWS_SECRET_ACCESS_KEY")
To integrate `django-ses`, bindmount a file to `/opt/extra-dependencies.txt` containing:
.. code-block:: text
django-ses
django-ses
Make sure you update the `docker.env` file with the necessary secrets.
@ -127,10 +125,9 @@ Working from the previous SES example we add the following to `local_settings`:
DEFAULT_FILE_STORAGE = "storages.backends.s3boto3.S3Boto3Storage"
To integrate `django-ses`, bindmount a file to `/opt/extra-dependencies.txt` containing:
.. code-block:: text
django-storages
boto3
django-storages
boto3

View File

@ -1,4 +1,5 @@
.. _teams:
Working with teams and larger organizations
===========================================
@ -11,6 +12,7 @@ If you are embedding the helpdesk app into your own apps, it is possible that th
How It Works
------------
Rather than assigning tickets to teams directly, django-helpdesk allows you assign tickets to knowledge-base items and then assign knowledge base items to teams.
Knowledge-base items can be in either public or private knowledge-base categories, so this organizational structure need not have any influence on the external appearance of your public helpdesk web portal.
@ -21,22 +23,28 @@ You can assign a knowledge-base item to a team on the Helpdesk admin page.
Once you have set up teams. Unassigned tickets which are associated with a knowledge-base item will only be shown on the dashboard to those users who are members of the team which is associated with that knowledge-base item.
Implementing Custom Teams Functionality
--------------------------------
---------------------------------------
If you want to use a different team app or implement your own team based app, you can hook it into Helpdesk using the following 3 settings:
``HELPDESK_TEAMS_MODEL``: point this to the model that defines a team in your custom implementation
``HELPDESK_TEAMS_MIGRATION_DEPENDENCIES``: set this to an array of migration(s) that are required to have run that will ensure the link that will be added as defined in the HELPDESK_TEAMS_MODEL will be available as a model to Helpdesk
``HELPDESK_KBITEM_TEAM_GETTER``: the method that will be called that must return a list of users who belong to a given team
Configuring Teams Functionality
-----------------------------
-------------------------------
Teams functionality is enabled by default but can be disabled using this entry in your ``settings.py``::
HELPDESK_TEAMS_MODE_ENABLED=False
HELPDESK_TEAMS_MODE_ENABLED=False
If you do not disable teams functionality then you must add additional apps into the ``INSTALLED_APPS`` in your ``settings.py``.
The following can be pasted into your settings.py BELOW the ``INSTALLED_APPS`` definition::
INSTALLED_APPS.extend([
INSTALLED_APPS.extend([
'account', # Required by pinax-teams
'pinax.invitations', # required by pinax-teams
'pinax.teams', # team support
@ -45,7 +53,10 @@ INSTALLED_APPS.extend([
Alternatively just add the 4 apps listed above into the ``INSTALLED_APPS``.
Disabling Teams Functionality
-----------------------------
Teams functionality is enabled by default but can be disabled using this entry in your ``settings.py``::
HELPDESK_TEAMS_MODE_ENABLED=False
HELPDESK_TEAMS_MODE_ENABLED=False

View File

@ -3,7 +3,6 @@ Upgrading
Your ``django-helpdesk`` installation can be upgraded to the latest version using the release notes below.
Prerequisites
-------------
@ -22,13 +21,13 @@ The tips below are based on modifications of the original installation instructi
- Under `INSTALLED_APPS`, `bootstrapform` needs to be replaced with `bootstrap4form`
- Unless turning off `pinax_teams`, add the following to `INSTALLED_APPS` for `pinax_teams`:
```
"account",
"pinax.invitations",
"pinax.teams",
"reversion",
```
- Unless turning off `pinax_teams`, add the following to `INSTALLED_APPS` for `pinax_teams`::
"account",
"pinax.invitations",
"pinax.teams",
"reversion",
- If using `send_templated_mail`, then it now needs to be imported from `helpdesk.templated_email`