Merge pull request #218 from zammad/mh/improve/console

Closes #152, Closes #134, Closes #85 - Improve console documentation

admin/console.rst

@@ -66,5 +66,5 @@ Here's a topic list for quick jumping and better overview.
    console/working-on-ticket-articles
    console/working-on-groups
    console/working-on-chat
-   console/other-usefull-commands
+   console/other-useful-commands
    console/dangerzone-for-experts

admin/console/dangerzone-for-experts.rst

@@ -1,12 +1,15 @@
-Deleting Records
+Deleting records
 ****************
 
-.. danger:: ☠️ The commands listed here cause **irrecoverable data loss**! Only proceed if you know what you're doing **and you have a backup**!
+.. danger::
 
-.. note:: The list of commands below is not exhaustive. If you can't find what you're looking for here, you are encouraged to `ask the community <https://community.zammad.org>`_.
+   ☠️ The commands listed here cause **irrecoverable data loss**!
+   Only proceed if you know what you're doing and you
+   :doc:`have a backup </appendix/backup-and-restore/index>`!
 
+.. include:: /admin/console/missing-commands-ask-community.include.rst
 
-Deleting Tickets (and their articles)
+Removing tickets (and their articles)
 -------------------------------------
 
 .. code-block:: ruby
@@ -21,58 +24,50 @@ Deleting Tickets (and their articles)
    >> tickets_to_keep = [1, 2, 3]
    >> Ticket.where.not(id: tickets_to_keep).destroy_all
 
+Removing users
+--------------
 
-Deleting Customers
-------------------
+.. warning::
 
-.. warning:: Customers **may not** be deleted while they have tickets remaining in the system.
+   Customers **may not** be deleted while they have tickets remaining in the
+   system.
 
-   As such, the examples below will delete not only the specified customers, but **all tickets associated with them**, as well.
+   As such, the examples below will delete not only the specified customers,
+   but **all tickets associated with them**, as well. Below commands remove
+   upon executing without any further warnings.
 
-Step 1: Select customers by email address
-   .. code-block:: ruby
+.. hint::
 
-      >> customer_emails = %w[customer@example.com customer@example.org]
+   If you're not sure what to do and need to learn more about what Zammad does
+   upon removing users, please consider using Zammad's UI options in stead.
 
-      >> customers = User.joins(roles: :permissions).where(email: customer_emails, roles: { active: true }, permissions: { name: 'ticket.customer', active: true }).where.not(id: 1)
+   Our documentation for the `data privacy`_ function will help you a lot!
 
-Step 2: Preview affected users & tickets
-   .. code-block:: ruby
+.. _data privacy:
+   https://admin-docs.zammad.org/en/latest/system/data-privacy.html
 
-      >> puts customers.map { |user| <<~PREVIEW }.join("\n")
-           Customer #{user.fullname}/#{user.id}/#{user.email} has #{Ticket.where(customer_id: user.id).count} tickets #{Ticket.where(customer_id: user.id).pluck(:number)}
-         PREVIEW
+Removing users is possible in 2 ways: A single user and in bulk.
 
-Step 3: Proceed with deletion
-   .. code-block:: ruby
+.. tabs::
 
-      >> customers.find_each do |user|
-           puts %{Preparing deletion of customer "#{user.fullname}" (and #{Ticket.where(customer_id: user.id).count} associated tickets)}
+   .. tab:: Remove a single user
 
-           Ticket.where(customer: user).find_each do |ticket|
-             puts "  Deleting ticket ##{ticket.number}..."
-             ticket.destroy
-           end
+      .. code-block:: ruby
 
-           puts "  Removing references for user with email #{user.email}..."
-           ActivityStream.where(created_by_id: user.id).update_all(created_by_id: 1)
-           History.where(created_by_id: user.id).update_all(created_by_id: 1)
-           Ticket::Article.where(created_by_id: user.id).update_all(created_by_id: 1)
-           Ticket::Article.where(updated_by_id: user.id).update_all(updated_by_id: 1)
-           Store.where(created_by_id: user.id).update_all(created_by_id: 1)
-           StatsStore.where(created_by_id: user.id).update_all(created_by_id: 1)
-           Tag.where(created_by_id: user.id).update_all(created_by_id: 1)
-           OnlineNotification.find_by(user_id: user.id)&.destroy!
-
-           puts "  Deleting #{user.fullname}..."
-           user.destroy
-         end
+         >> User.find_by(email: '<email address>').destroy
+
+   .. tab:: Remove several users
 
+      .. code-block:: ruby
 
-Deleting Organizations
+         >> User.where(
+               email: ['<email address 1>', '<email address 2>']
+            ).destroy_all
+
+Removing organizations
 ----------------------
 
-.. note:: Deleting an organization does **not** delete associated customers.
+.. note:: Removing an organization does **not** delete associated customers.
 
 Step 1: Select organizations
    .. code-block:: ruby
@@ -106,8 +101,7 @@ Step 3: Proceed with deletion
            org.destroy
          end
 
-
-Deleting System Records
+Removing system records
 -----------------------
 
 .. code-block:: ruby
@@ -118,10 +112,12 @@ Deleting System Records
    # Remove all entries from the Activity Stream (dashboard)
    >> ActivityStream.destroy_all
 
-   # Remove entries for all recently viewed objects (tickets, users, organizations)
+   # Remove entries for all recently viewed objects
+   # (tickets, users, organizations)
    >> RecentView.destroy_all
 
-   # Remove all history information from tickets, users and organizations (dangerous!)
+   # Remove all history information from tickets, users and organizations
+   # (dangerous!)
    >> History.destroy_all
 
 .. _dangerzone_reset_zammad:
@@ -131,8 +127,9 @@ Reset Zammad installation
 
 .. hint:: 
 
-   Below commands are incomplete intentionally, error outputs will hint you through! 
-   The following operations will cause data loss and for development / testing only.
+   Below commands are incomplete intentionally, error outputs will hint you
+   through! The following operations will cause data loss and are for
+   development / testing only.
 
    Don't forget to stop Zammad before trying to drop the database!
 

admin/console/hidden-settings.rst

@@ -1,16 +1,17 @@
 Advanced customization settings
 *******************************
 
-On this page you can find some settings that you won't find within the Zammad UI.
-Those settings might come in handy as it can change Zamnmads behavior.
+On this page you can find some settings that you won't find within the Zammad
+UI. Those settings might come in handy as it can change Zammad's behavior.
 
-.. note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at the `Community <https://community.zammad.org>`_.
+.. include:: /admin/console/missing-commands-ask-community.include.rst
 
 Send all outgoing E-Mails to a BCC-Mailbox
 ------------------------------------------
 
-This option allows you to send all outgoing E-Mails (not notifications) to a specific mailbox.
-Please note that this shouldn't be a mailbox you're importing already! This will apply to all groups and is a global setting.
+This option allows you to send all outgoing E-Mails (not notifications) to a
+specific mailbox. Please note that this shouldn't be a mailbox you're importing
+already! This will apply to all groups and is a global setting.
 
 .. code-block:: ruby
 
@@ -22,12 +23,12 @@ You can easily check the current BCC-Setting by running the following:
 
    >> Setting.get('system_bcc')
 
-
 Activate counter on grouped overviews
 -------------------------------------
 
 This is a hidden setting which you can only set via Command-Line.
-This will globally enable a ticket number value in each heading for grouped elements.
+This will globally enable a ticket number value in each heading for grouped
+elements.
 
 .. code-block:: ruby
 
@@ -37,36 +38,53 @@ This will globally enable a ticket number value in each heading for grouped elem
 
 .. image:: /images/console/ui_table_group_by_show_count-example.png
 
-
-Default Ticket type on creation
+Default ticket type on creation
 -------------------------------
 
-Zammad allows you to define the default article type upon Ticket creation. By default this will be a incoming phone call.
-You can choose between ``phone-in`` (incoming call, **default**), ``phone-out`` (outgoing call) and ``email-out``  (Sending an E-Mail out).
+Zammad allows you to define the default article type upon ticket creation.
+By default this will be a incoming phone call.
+
+You can choose between
+
+   * ``phone-in`` (incoming call, **default**),
+   * ``phone-out`` (outgoing call) and
+   * ``email-out``  (Sending an E-Mail out).
 
 .. code-block:: ruby
 
    >> Setting.set('ui_ticket_create_default_type', 'email-out')
 
-To check what setting is set currently, simply run
+To check what setting is set currently, simply run:
 
 .. code-block:: ruby
 
    >> Setting.get('ui_ticket_create_default_type')
 
-
 Adding a warning to the ticket creation process
 -----------------------------------------------
 
-If in case you need to give your agent a note or warning during ticket creation, you can do so with the below command.
-You can use three different warnings for Incoming Calls ``:"phone-in"=>""``, Outgoing Calls ``:"phone-out"=>""`` and Outgoing E-Mails ``:"email-out"=>""``.
+If in case you need to give your agent a note or warning during ticket creation,
+you can do so with the below command.
+
+You can use three different warnings for
+
+   * Incoming Calls ``:"phone-in"=>""``,
+   * Outgoing Calls ``:"phone-out"=>""`` and
+   * Outgoing E-Mails ``:"email-out"=>""``.
 
 .. code-block:: ruby
 
-   >> Setting.set('ui_ticket_create_notes', {:"phone-in"=>"You're about to note a incoming phone call.", :"phone-out"=>"You're about to note an outgoing phone call.", :"email-out"=>"You're going to send out an E-Mail."})
+   >> Setting.set('ui_ticket_create_notes', {
+         :"phone-in"=>"You're about to note a incoming phone call.",
+         :"phone-out"=>"You're about to note an outgoing phone call.",
+         :"email-out"=>"You're going to send out an E-Mail."
+      })
+
+.. note::
 
-.. note:: You can use those three sub-settings independently, if you e.g. don't need a warning on incoming calls, simply leave out ``:"phone-in"=>""`` out of the setting.
-   The setting itself is done within an array ( ``{}`` ).
+   You can use those three sub-settings independently, if you e.g. don't need a
+   warning on incoming calls, simply leave out ``:"phone-in"=>""`` out of the
+   setting. The setting itself is done within an array ( ``{}`` ).
 
 
 To check what's currently set, you can use:
@@ -79,9 +97,8 @@ Sample of the above setting:
 
 .. image:: /images/console/ui_ticket_create_notes.gif
 
-
-Show E-Mail-Address of customer on customer selection (Ticket-Creation)
------------------------------------------------------------------------
+Show Email address of customer on customer selection (ticket creation)
+----------------------------------------------------------------------
 
 By default Zammad will not display the E-Mail-Addresses of customers.
 The below option allows you to change this behavior.
@@ -96,13 +113,16 @@ Get the current state of this setting with:
 
    >> Setting.get('ui_user_organization_selector_with_email')
 
-
-Change Font-Settings for outgoing HTML-Mails
+Change font settings for outgoing HTML mails
 --------------------------------------------
 
-.. note:: Some Clients (like Outlook) might fallback to other Settings while it might work for other Clients.
+.. note::
+
+   Some clients (like Outlook) might fallback to other settings while it might
+   work for other clients.
 
-The below setting allows you to adjust Zammads email font setting. This setting does not require a service restart.
+The below setting allows you to adjust Zammad's email font setting.
+This setting does not require a service restart.
 
 .. code-block:: ruby
 

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

@@ -0,0 +1,6 @@
+.. note::
+
+   Please note that this is not a full command list, if you're missing commands,
+   feel free to ask over at the `Community`_.
+
+.. _Community: https://community.zammad.org

admin/console/other-useful-commands.rst

@@ -0,0 +1,100 @@
+Other useful commands
+*********************
+
+.. include:: /admin/console/missing-commands-ask-community.include.rst
+
+Fetch mails
+-----------
+
+The below command will do a manual fetch of mail channels.
+This will also show errors that might appear within that process.
+
+.. code-block:: ruby
+
+   >> Channel.fetch
+
+Reprocess unprocessable mails
+-----------------------------
+
+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
+``tmp/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
+
+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.
+
+If Zammad fails to process the message, it will remain in the
+``tmp/unprocessable_mail`` folder; otherwise it will be removed after it has
+been parsed successfully.
+
+Add translation
+---------------
+
+This comes in handy if you e.g. added a new state that you need to translate
+for several languages.
+
+.. code-block:: ruby
+
+   >> Translation.create_if_not_exists(:locale => 'de-de', :source => "New", :target => "Neu", created_by_id: 1, updated_by_id: 1)
+
+.. warning::
+
+   While Zammad knows further attributes for the Translation model, please
+   *do not* set them manually. Doing so may interfere with our `Weblate`_
+   translation process and cause you loosing your custom translations.
+
+   If you want to translate code base strings that are available within standard
+   code, please use `Weblate`_ instead.
+
+.. _Weblate: https://translations.zammad.org/
+
+Translating attributes
+~~~~~~~~~~~~~~~~~~~~~~
+
+By default Zammad will not translate custom attributes.
+With the following code you can enable translation.
+This will translate the attribute display name and the display names of values
+(if it's a value field). For this to work, just replace ``{attribute-name}``
+with the name of your attribute.
+
+.. code-block:: ruby
+
+   >> attribute = ObjectManager::Attribute.find_by(name: '{attribute-name}')
+   >> attribute.data_option[:translate] = true  # set this to false to disable
+                                                # translation again
+   >> attribute.save!
+
+.. note::
+
+   Translating value display names works for the following attribute types:
+
+   * Boolean
+   * Select
+   * Tree Select
+
+   If you're translating the display name of e.g. an Integer-attribute,
+   this works as well!
+
+Fill a test system with test data
+---------------------------------
+
+.. danger::
+
+   Don't run this in a productive environment! This can slow down Zammad and is
+   hard to revert if you create much!
+
+The below command will add ``50`` agents, ``1000`` customers, ``20`` groups,
+``40`` organizations, ``5`` new overviews and ``100`` tickets.
+You can always use ``0`` to not create specific items.
+Zammad will create random data which make no logical sense.
+
+.. code-block:: ruby
+
+   >> FillDb.load(agents: 50,customers: 1000,groups: 20,organizations: 40,overviews: 5,tickets: 100,)