From 21799ba14210fda2223b6881cc2338379bddaf28 Mon Sep 17 00:00:00 2001 From: Benbb96 Date: Mon, 11 Mar 2024 14:46:27 +0100 Subject: [PATCH 1/5] Revert "Set an absolute path to get the module recognized when running from root folder" This reverts commit c2276ce7e16c2d90f99ba797dd1b93ec66b96f99. --- demo/demodesk/config/settings.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demo/demodesk/config/settings.py b/demo/demodesk/config/settings.py index 64ad1738..a8366d22 100644 --- a/demo/demodesk/config/settings.py +++ b/demo/demodesk/config/settings.py @@ -68,7 +68,7 @@ MIDDLEWARE = [ 'django.middleware.clickjacking.XFrameOptionsMiddleware', ] -ROOT_URLCONF = 'demo.demodesk.config.urls' +ROOT_URLCONF = 'demodesk.config.urls' TEMPLATES = [ { @@ -87,7 +87,7 @@ TEMPLATES = [ }, ] -WSGI_APPLICATION = 'demo.demodesk.config.wsgi.application' +WSGI_APPLICATION = 'demodesk.config.wsgi.application' # django-helpdesk configuration settings From ceb137eb97d6bd5b7d595e12ab107bfb570ef1b8 Mon Sep 17 00:00:00 2001 From: Benbb96 Date: Mon, 11 Mar 2024 17:06:33 +0100 Subject: [PATCH 2/5] chore: :see_no_evil: add `.venv` folder to gitignore --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 5ff0d848..35a1f114 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,7 @@ docs/doctrees/* *.swp .idea .tox/** +.venv # ignore demo attachments that user might have added helpdesk/attachments/ @@ -25,4 +26,3 @@ demo/demodesk/media/helpdesk/attachments/DH-3/3/* demo/demodesk/media/helpdesk/attachments/DH-3/4/* !demo/demodesk/media/helpdesk/attachments/DH-3/3/someinfo.txt !demo/demodesk/media/helpdesk/attachments/DH-3/4/helpdesk.png - From cc74b82deed990973cb6deb2baa6336a415ec932 Mon Sep 17 00:00:00 2001 From: Benbb96 Date: Mon, 11 Mar 2024 17:09:10 +0100 Subject: [PATCH 3/5] docs: :memo: Update README.rst with better explanations and formatting + fix broken link --- README.rst | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index caa1d400..abd82169 100644 --- a/README.rst +++ b/README.rst @@ -28,11 +28,11 @@ get started with testing or developing `django-helpdesk`. The demo project resides in the `demo/` top-level folder. It's likely that you can start up a demo project server by running -only the command: +only the command (consider creating a virtualenv before): make rundemo -or with docker: +or with docker:: docker build . -t demodesk docker run --rm -v "$PWD:/app" -p 8080:8080 demodesk @@ -74,27 +74,33 @@ Developer Environment Follow these steps to set up your development environment to contribute to helpdesk: - check out the helpdesk app to your local file system:: - git clone https://github.com/django-helpdesk/django-helpdesk.git + + git clone https://github.com/django-helpdesk/django-helpdesk.git - - install a virtual environment - - using virtualenv from the helpdesk base folder do:: - virtualenv .venv && source .venv/bin/activate + - install a virtual environment and activate it:: + + python -m venv .venv && source .venv/bin/activate - install the requirements for development:: + pip install -r requirements.txt -r requirements-dev.txt - - install the requirements for testing as well:: - pip install -r requirements.txt -r requirements-dev.txt -r requirements-testing.txt + - you can install the requirements for testing as well:: -To reactivate a VENV just run: - source .venv/bin/activate + pip install -r requirements-testing.txt + +To deactivate the virtual environment, use ``deactivate``. Then to reactivate it, just run:: + + source .venv/bin/activate To see option for the Makefile run: `make` The project enforces a standardized formatting in the CI/CD pipeline. To ensure you have the correct formatting run:: + make checkformat To auto format any code use this:: + make format Testing @@ -145,5 +151,5 @@ Note that django-helpdesk is distributed with 3rd party products which have their own licenses. See LICENSE.3RDPARTY for license terms for included packages. -.. _note: http://docs.djangoproject.com/en/dev/ref/databases/#sqlite-string-matching +.. _note: https://docs.djangoproject.com/en/dev/ref/databases/#substring-matching-and-case-sensitivity From 4b096a3010ca9027cb81ebe5e1eeedc8c7a41f3d Mon Sep 17 00:00:00 2001 From: Benbb96 Date: Tue, 12 Mar 2024 12:36:18 +0100 Subject: [PATCH 4/5] docs: :memo: fix formatting errors in demo README.rst --- demo/README.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/demo/README.rst b/demo/README.rst index 87513afa..69e31da8 100644 --- a/demo/README.rst +++ b/demo/README.rst @@ -24,15 +24,13 @@ Ideally, you'd use a virtualenv instead (see below for details). To use your system directory, from the top-level -django-helpdesk directory, simply run: +django-helpdesk directory, simply run:: make rundemo Once the console gives a prompt that the HTTP server is listening, open your web browser -and navigate to: - - localhost:8080 +and navigate to http://localhost:8080 You should see the django-helpdesk public web portal! @@ -40,7 +38,7 @@ If you shut down the server, you can't immediately re-run the demo because the make commands would encounter problems trying to re-write the database. Instead, before running the demo, you will need -to first clean the demo: +to first clean the demo:: sudo make distclean @@ -53,7 +51,7 @@ want to use a virtualenv. If so, you might change the pip in the makefile to point to your virtualenv's pip instead -before running: +before running:: make rundemo From ed1fd8c1f1ea314a855c0eae3574c16e36f024cf Mon Sep 17 00:00:00 2001 From: Benbb96 Date: Tue, 12 Mar 2024 12:40:51 +0100 Subject: [PATCH 5/5] docs: :memo: hamronize all docs files (fix indent, code blocks, links, and some wording) --- docs/configuration.rst | 14 +-- docs/custom_fields.rst | 2 - docs/custom_templates.rst | 1 - docs/iframe_submission.rst | 2 +- docs/index.rst | 9 +- docs/install.rst | 137 ++++++++++++++++++----------- docs/license.rst | 6 +- docs/settings.rst | 173 +++++++++++++++++++------------------ docs/spam.rst | 3 +- docs/standalone.rst | 65 +++++++------- docs/teams.rst | 21 +++-- docs/upgrade.rst | 15 ++-- 12 files changed, 246 insertions(+), 202 deletions(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index 714a18d5..05d56a7e 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -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 `_. @@ -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. \ No newline at end of file diff --git a/docs/custom_fields.rst b/docs/custom_fields.rst index 1258f5e9..6e35f58c 100644 --- a/docs/custom_fields.rst +++ b/docs/custom_fields.rst @@ -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. diff --git a/docs/custom_templates.rst b/docs/custom_templates.rst index 1a590340..4e829184 100644 --- a/docs/custom_templates.rst +++ b/docs/custom_templates.rst @@ -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. - diff --git a/docs/iframe_submission.rst b/docs/iframe_submission.rst index 367716d7..5db205f0 100644 --- a/docs/iframe_submission.rst +++ b/docs/iframe_submission.rst @@ -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: diff --git a/docs/index.rst b/docs/index.rst index 4b2c3898..7f1ffe04 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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. - - diff --git a/docs/install.rst b/docs/install.rst index 9f3fccf7..a72de66a 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,12 +1,12 @@ -.. _installation: Installation ============ .. note:: - For standalone installation, refer to the :doc:`standalone installation docs `. + For standalone installation, refer to the :doc:`standalone installation docs `. -``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` 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 -------------------------------- diff --git a/docs/license.rst b/docs/license.rst index bfeadd50..01b4c469 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -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 diff --git a/docs/settings.rst b/docs/settings.rst index 70ba5f6d..8fc2aaec 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -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 --------------------- diff --git a/docs/spam.rst b/docs/spam.rst index 4501dd42..55533f68 100644 --- a/docs/spam.rst +++ b/docs/spam.rst @@ -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' diff --git a/docs/standalone.rst b/docs/standalone.rst index be1fd953..3d1e14b8 100644 --- a/docs/standalone.rst +++ b/docs/standalone.rst @@ -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 - + 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 diff --git a/docs/teams.rst b/docs/teams.rst index 6f804a7d..4bfa32da 100644 --- a/docs/teams.rst +++ b/docs/teams.rst @@ -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 diff --git a/docs/upgrade.rst b/docs/upgrade.rst index 1fd3d00f..64dc0c3e 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -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`