Skip to content

Commit

Permalink
Switch to Zammad 6.3.
Browse files Browse the repository at this point in the history
  • Loading branch information
@ralf401
ralf401 committed Apr 17, 2024
2 parents 0ebff92 + 02d818b commit 2ad1e06
Show file tree
Hide file tree
Showing 10 changed files with 154 additions and 294 deletions.
72 changes: 50 additions & 22 deletions admin/console/other-useful-commands.rst
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
Other useful commands
Other Useful Commands
*********************

.. include:: /admin/console/missing-commands-ask-community.include.rst

Fetch mails
Fetch Mails
-----------

The below command will do a manual fetch of mail channels.
Expand All @@ -13,30 +13,58 @@ This will also show errors that might appear within that process.
>> Channel.fetch
Reprocess unprocessable mails
-----------------------------
Reprocess Failed Emails
-----------------------

When Zammad encounters a mail it cannot parse (e.g. due to a parser bug or a
malformed message), it will store the mail in
``var/spool/unprocessable_mail/<ID>.eml``, give up on attempting to parse the
mail, and will warn on the monitoring page that there are unprocessed mails.

To force Zammad to reattempt to parse those mails, run the following command:

.. code-block:: ruby
>> Channel::EmailParser.process_unprocessable_mails
When Zammad fetches a mail it cannot parse (e.g. due to a parser bug or a
malformed message), it will store the mail in the database and warn in
the monitoring section about it.

In case of a malformed message (e.g. an invalid email address in one of the
header fields), you may need to manually edit the mail before Zammad can process
it.
it. To do so, follow the steps below:

Export all Failed Emails to a Local Folder
Execute ``rake zammad:email_parser:failed_email:export_all``. You can find
the location of the exported email in the output of your console.
Every time you perform an export of failed (unprocessable) emails, it
creates one folder containing all failed emails at the time of execution.

Edit the Email
The email has been exported in the step above. Now you can have a look at it
and try to repair it. Make sure to leave the file name untouched, as the
import will otherwise fail.

Import and Reprocess Locally Modified Email
After editing the email, run
``rake zammad:email_parser:failed_email:import path/to/your/email.eml``
to apply your changes from the file to the database. You can also pass
the entire folder as argument, so all ``.eml`` files in it will we imported
and reprocessed. If the reprocessing of the email was successful, the file(s)
will be deleted, and the empty folder removed.

.. hint::

Make sure to run these commands only from the main Zammad folder ``/opt/zammad``.
There may be problems if you try to run it from within the generated subfolder.

Delete Unwanted Emails
In case of unwanted emails such as spam, you can delete them from the
database after exporting them with the command
``rake zammad:email_parser:failed_email:delete path/to/your/email.eml``.
If you pass the export folder as argument instead, all contained emails will
be removed from the database, their files deleted and finally the empty folder
removed.

Add Translation
---------------

.. warning::

If Zammad fails to process the message, it will remain in the
``var/spool/unprocessable_mail`` folder; otherwise it will be removed after it
has been parsed successfully.
Although the procedure described below still works, it is not recommended for usage any more.

Add translation
---------------
Since Zammad version 6.3 it's possible to customize any translation via graphical UI. All coupled with handy
suggestions for all translatable custom objects in the local system. For more information, see the documentation for the :admin-docs:`translations screen </system/translations.html>`.

This comes in handy if you e.g. added a new state that you need to translate
for several languages.
Expand All @@ -56,7 +84,7 @@ for several languages.

.. _Weblate: https://translations.zammad.org/

Translating attributes
Translating Attributes
~~~~~~~~~~~~~~~~~~~~~~

By default Zammad will not translate custom attributes.
Expand All @@ -83,7 +111,7 @@ with the name of your attribute.
If you're translating the display name of e.g. an Integer-attribute,
this works as well!

Fill a test system with test data
Fill a Test System With Test Data
---------------------------------

.. danger::
Expand Down
215 changes: 1 addition & 214 deletions admin/console/working-on-tickets.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,67 +45,11 @@ Update all tickets of a specific customer
>> Ticket.where(customer_id: 4).update_all(customer_id: 1)
Priorities
----------

Ticket priorities help your agent to see how important a customer request is.
Priorities are not available to customers and, Core wise, have no impact
on how Zammad handles a ticket. You can however adjust Zammad's behavior
with e.g. triggers, SLAs and schedulers.

Not sure what priorities are available in the system? Either have a look
in any ticket or run the following command.

.. code-block:: ruby
>> Ticket::Priority.pluck(:name)
Adding priorities for tickets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Ticket priorities come with several attributes, however, the most relevant
as of now are: ``name``, ``default_create`` and ``ui_color``.

.. warning::

``default_create`` allows you to define the default priority Zammad should
use during ticket creation. **However** - on default installations this is
the priority ``2 normal``.

*You cannot have more than one priority as the default_create priority!*

.. note::

``ui_color`` defines the CSS class to use. On default installations
you can either use ``low-priority`` (light blue) or ``high-priority``
(red). This affects how Zammad displays the ticket titles
*in overviews*.

.. code-block:: ruby
>> Ticket::Priority.create(
name: '4 super high',
default_create: false,
ui_color: 'high-priority',
created_by_id: 1,
updated_by_id: 1
)
Change priority
~~~~~~~~~~~~~~~

If needed you can also set priorities to inactive or rename them if they
don't fit your desired scheme. Renaming would look like so:

.. code-block:: ruby
>> Ticket::Priority.find_by(name: '1 low').update(name: '1 high')
.. _state_types:

Get ticket state types
----------------------

.. Not removed because it is still referenced in API state creation.
This will show all state types needed for creating new ticket states.

Expand All @@ -128,160 +72,3 @@ This will show all state types needed for creating new ticket states.
Above will return both, the type ID and name - e.g.:
``[[1, "new"], [2, "open"], ...``.


Add new ticket state
--------------------

.. note:: **🤓 Missing States you just created?**

You might want to use ``Ticket::State.pluck(:id, :name)``
to get a listing of all available ticket states.

.. tip:: **🙈 ignoring escalations**

You can use ``ignore_escalation: true,`` to ignore possible SLA
calculations (pending reminder and pending close do this by default).

Non-Pending states
~~~~~~~~~~~~~~~~~~

A state that's not a pending state (e.g. open, closed). Just replace ``'open'``
by whatever you need (like closed).

.. code-block:: ruby
>> Ticket::State.create_or_update(
name: 'Developing',
state_type: Ticket::StateType.find_by(name: 'open'),
created_by_id: 1,
updated_by_id: 1,
)
Pending reminders
~~~~~~~~~~~~~~~~~

A pending reminder state that will send a reminder notification to the agent if
the time has been reached.

.. code-block:: ruby
>> Ticket::State.create_or_update(
name: 'pending customer feedback',
state_type: Ticket::StateType.find_by(name: 'pending reminder'),
ignore_escalation: true,
created_by_id: 1,
updated_by_id: 1,
)
Pending Action
~~~~~~~~~~~~~~

A pending action that will change to another state if "pending till" has been
reached.

.. code-block:: ruby
>> Ticket::State.create_or_update(
name: 'pending and reopen',
state_type: Ticket::StateType.find_by(name: 'pending action'),
ignore_escalation: true,
next_state: Ticket::State.find_by(name: 'open'),
created_by_id: 1,
updated_by_id: 1,
)
(optional) Disable date and time picker (pending till) for pending states
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting with Zammad 5.0, :admin-docs:`Core Workflows </system/core-workflows.html>`
automatically handles displaying the "pending till" field for pending states.
Below snippet *is not required* and is only relevant if you don't want to
create a workflow within the UI of Zammad.

Replace ``pending customer feedback`` with the pending state of your choice.

.. code-block:: ruby
>> CoreWorkflow.create_if_not_exists(
name: 'remove pending till on state "pending customer feedback"',
object: 'Ticket',
condition_selected: { 'ticket.state_id'=>{ 'operator' => 'is', 'value' => Ticket::State.find_by(name: 'pending customer feedback').id.to_s } },
perform: { 'ticket.pending_time'=> { 'operator' => 'remove', 'remove' => 'true' } },
created_by_id: 1,
updated_by_id: 1,
)
.. _states_to_ui:

Make new states available to UI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before being able to use the new states within the WebApp, you need to run the
following commands to make them available.

.. warning::

Please **do not replace** anything below, state_id is a named attribute which
is correct and shall not be replaced!

.. code-block:: ruby
>> attribute = ObjectManager::Attribute.get(
object: 'Ticket',
name: 'state_id',
)
>> attribute.data_option[:filter] = Ticket::State.by_category(:viewable).pluck(:id)
>> attribute.screens[:create_middle]['ticket.agent'][:filter] = Ticket::State.by_category(:viewable_agent_new).pluck(:id)
>> attribute.screens[:create_middle]['ticket.customer'][:filter] = Ticket::State.by_category(:viewable_customer_new).pluck(:id)
>> attribute.screens[:edit]['ticket.agent'][:filter] = Ticket::State.by_category(:viewable_agent_edit).pluck(:id)
>> attribute.screens[:edit]['ticket.customer'][:filter] = Ticket::State.by_category(:viewable_customer_edit).pluck(:id)
>> attribute.save!
Limit available states for customers
------------------------------------

.. tip::

:admin-docs:`Core Workflows </system/core-workflows.html>` allows you to
achieve below described behavior any time without any issues. No need to use
the console if you don't want to!

By default Zammad allows customers to change Ticket states to ``open`` and
``closed``. If this does not meet your requirenments, you can adjust this at
anytime. The below example shows how to restrict your customer to only close
tickets if needed:

.. code-block:: ruby
>> attribute = ObjectManager::Attribute.get(
object: 'Ticket',
name: 'state_id',
)
>> attribute.screens['edit']['ticket.customer']['filter'] = Ticket::State.where(name: ['closed']).pluck(:id)
>> attribute.save!
.. hint::

If you want to allow several different states for customers, you need to
provide the state names as array - like so:
``['closed', 'open', 'my-amazing-state']`` (instead of ``['closed']``).

You can check the current active states that customers can set like so:

.. code-block:: ruby
>> ObjectManager::Attribute.get(
object: 'Ticket',
name: 'state_id',
).screens['edit']['ticket.customer']['filter']
The above will return one or more IDs - if you're not sure which state they
belong to, you can check the state name with the following command.
(Ensure to replace ``{ID}`` with your returned ID(s))

.. code-block:: ruby
>> Ticket::State.find({ID}).name
Loading

0 comments on commit 2ad1e06

Please sign in to comment.