.. ==================================================
.. ==================================================
.. ==================================================
.. Header hierarchy
.. ==
.. --
.. ^^
.. ""
.. ;;
.. ,,
..
.. --------------------------------------------used to the update the records specified ---------
.. Best Practice T3 reST: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html
.. Reference: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/Index.html
.. Italic *italic*
.. Bold **bold**
.. Code ``text``
.. External Links: `Bootstrap `_
.. Internal Link: :ref:`downloadButton` (default url text) or :ref:`download Button` (explicit url text)
.. Anker for internal link: .. _`download`:
.. Add Image: .. image:: ./Images/a4.jpg
..
.. Add image with caption: .. figure:: ./Images/black_dot.png
.. :class: with-border
.. :width: 20px
..
.. black_dot.png
..
..
.. Admonitions
.. .. note:: .. important:: .. tip:: .. warning::
.. Color: (blue) (orange) (green) (red)
..
.. Definition:
.. some text becomes strong (only one line)
.. description has to indented
.. -*- coding: utf-8 -*- with BOM.
.. include:: Includes.txt
.. _`issue`:
Issue
=====
The **Issue** feature is a ticket management tool integrated within the QFQ framework. It handles issue tracking, permissions, notifications, and comment management.
How to get started
------------------
* Create a new page in your Typo3 Backend.
* Set the ‘URL slug’ to /issue.
* Create a content element of type 'QFQ Element'.
* Insert ``file=_issue``
Configuration
-------------
To use the Issue feature, the following configuration steps are required:
Database Tables
^^^^^^^^^^^^^^^
Ensure the following tables exist in your database:
* ``Grp``: Must include records with the following references:
* ``qfq_project_access_write``
* ``qfq_project_access_read``
* ``qfq_project_access_admin``
* ``qfq_upload_issue``
* ``qfq_upload_comment``
* ``qfq_upload_commentNew``
* ``qfq_status_issue``
* ``Project``
* ``Status``
* ``Comment``
* ``FileUpload``
* ``Issue``
System Store Variables
^^^^^^^^^^^^^^^^^^^^^^
Define the following variables in the **SYSTEM-STORE** (Dynamic/Custom) via QFQ configuration:
* ``pIdUser``: ID of the current user
* ``emailUser``: Email of the current user
* ``personTableName``: Table name for person records
* ``personFirstNameColumnName``: First name column in person table
* ``personLastNameColumnName``: Last name column in person table
* ``personEmailColumnName``: Email column in person table
Use
---
The core interface is accessible via the report at ``/issue``.
Functionality
^^^^^^^^^^^^^
* Displays a table of issues the current user has permission to access
* Fully filterable and sortable using *tablesorter*
* Works with or without SIP
* Can be embedded using ``AS _restClient`` for dashboards or integrations (:ref:`integration`)
URL Parameters
^^^^^^^^^^^^^^
Filter issues by passing URL parameters. Each parameter corresponds to a column in the ``Issue`` table. All parameters use the ``=`` operator, except for ``sea``, which uses ``LIKE`` on both `title` and `description`.
+-----------+---------------------------+
| Parameter | Column |
+===========+===========================+
| pro | prId |
+-----------+---------------------------+
| sta | stId |
+-----------+---------------------------+
| xid | xId |
+-----------+---------------------------+
| fid | formId |
+-----------+---------------------------+
| fna | formName |
+-----------+---------------------------+
| cre | pIdCreator |
+-----------+---------------------------+
| ass | pIdAssignee |
+-----------+---------------------------+
| con | pIdContact |
+-----------+---------------------------+
| mco | mailContact |
+-----------+---------------------------+
| mws | mailWatcherSet |
+-----------+---------------------------+
| msn | mailSetNotification |
+-----------+---------------------------+
| mno | mailNotification |
+-----------+---------------------------+
| tit | title |
+-----------+---------------------------+
| des | description |
+-----------+---------------------------+
| str | start |
+-----------+---------------------------+
| due | due |
+-----------+---------------------------+
| rem | reminder |
+-----------+---------------------------+
| eti | estimatedTime |
+-----------+---------------------------+
| del | deleted |
+-----------+---------------------------+
| sea | title, description (LIKE) |
+-----------+---------------------------+
Form: issue
-----------
Most fields in this form are self-explanatory, but the following may require additional context:
* **Status**: Dropdown listing all records from the ``Status`` table where ``grId = qfq_status_issue``
* **Project**: Dropdown listing all records from the ``Project`` table
* **Assignee**: TypeAhead input listing all users with permissions on the selected project
* **Creator**: TypeAhead input listing all users. Only visible to users logged into the Typo3 backend or users with admin permissions on the selected project
* **Contact person**: TypeAhead input listing all users
* **Contact person mail**: Optional email address when the contact person is not in the database
* **Watcher mail (list)**: Comma-separated list of email addresses
* **Notification**: See :ref:`notification`
* **Comment**: See :ref:`comments`
.. note::
QFQ provides forms to configure status and projects (``status.json`` and ``project.json``).
Permissions
-----------
Access Control
^^^^^^^^^^^^^^
Access is automatically managed by QFQ:
1. **Project-Based Access**
Users gain access to issues by being assigned permissions on a project (the issue belongs to) via the ``Glue`` table. Available permission levels:
+--------+--------------------------+-----------------------------------------+
| Level | Reference | Description |
+========+==========================+=========================================+
| Write | qfq_project_access_write | View, create, edit, delete |
+--------+--------------------------+-----------------------------------------+
| Read | qfq_project_access_read | View only |
+--------+--------------------------+-----------------------------------------+
| Admin | qfq_project_access_admin | Like Write + extra options in form |
+--------+--------------------------+-----------------------------------------+
2. **Contact/Watcher-Based Access**
Even without project permissions, users may access an issue if they are:
* Listed as a **contact person** or **watcher**
* And **access contact/watcher** is enabled
Additional Rules
^^^^^^^^^^^^^^^^
* **Creators** of an issue or comment always have access
* **Logged-in Typo3 backend users** (typically developers) have full access
* **Unassigned issues** (no project) can be accessed only by:
* The creator
* The contact person (if allowed)
* The watcher (if allowed)
* Backend users
Comments
--------
There are two ways a user can add a comment to an issue:
1. **Edit Issue**
When editing an existing issue, a ``Comment`` tab (pill) is available. This allows users to add a new comment along with its permissions.
This method is ideal when the user needs to update the issue and leave a comment simultaneously — for example, when closing an issue and providing a reason.
2. **New Comment**
Use this option when no changes to the issue itself are required and only a comment needs to be added.
Each comment can have specific permissions:
* Comments can be restricted from **contact person** and **watchers**
* A badge beside the edit button indicates if a comment is restricted or not
Notification
------------
The notification mechanism allows to alert involved parties via email when changes are made to an issue.
Recipients:
* Creator
* Contact person
* Watchers
* Assignee
Behavior:
* Upon saving an issue/comment, a timestamp (+2 minutes) is added if recipients are selected
* This 2-minute delay allows batching of quick consecutive changes
* If all recipients are removed, the timestamp is reset to ``0000-00-00 00:00:00``
.. note::
Use a cron job to regularly check timestamps and dispatch emails.
Integration
-----------
Issue linked to a specific record
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Issues can be linked to a specific record (and form) by enabling the ``issue`` option under **Show button** in the form editor of the primary form.
When this option is enabled:
* An **Issue** button appears on the form
* The button displays the number of issues associated with the current record, including how many are still open
* Clicking the button redirects the user to ``/issue``
* When creating a new issue from this view, it is automatically assigned to the originating record (``xId``) and form (``formId``)
Embedded view
^^^^^^^^^^^^^
The `/issue` page can be embedded with `AS _restClient`, which is useful for integrating issue views in dashboards or external systems. By using the parameter ``type=2`` only the raw HTML will be returned. ::
{
sql = SELECT 'n:{{baseUrl:Y}}issue?type=2' AS _restClient
, 'n:{{baseUrl:Y}}issue?type=2&ass=1&pro1' AS _restClient
}
Deleting issues/comments
------------------------
Issues and comments are never physically deleted; instead, they are marked as deleted by setting ``deleted = yes``.