Fix RST syntax and formatting repo-wide

about-zammad.rst → about/zammad.rst

@@ -5,11 +5,10 @@ Do you receive many emails and want to answer them with a team of agents?
 
 You're going to love Zammad_!
 
-Zammad is a web based open source helpdesk/customer support system with many features to manage customer communication via several channels like telephone, facebook, twitter, chat and emails. 
+Zammad is a web based open source helpdesk/customer support system with many features to manage customer communication via several channels like telephone, facebook, twitter, chat and emails.
 It is distributed under version 3 of the GNU AFFERO General Public License (GNU AGPLv3).
 
 The code is open source, and `available on GitHub`_!
 
 .. _Zammad: https://zammad.org/
 .. _available on GitHub: https://github.com/zammad/zammad
-

admin-console.rst → admin/console.rst

@@ -1,11 +1,9 @@
-.. _zammad-console:
-
 Console
 *******
 
 Zammad uses Ruby on Rails so you can make use of the `rails console <http://guides.rubyonrails.org/command_line.html>`_.
 
-.. Warning:: Please double check your commands before running, as some of those commands might cause data loss or damaged tickets! If you're unsure, **use a test system first**!
+.. warning:: Please double check your commands before running, as some of those commands might cause data loss or damaged tickets! If you're unsure, **use a test system first**!
 
 To open the rails console on the shell you have to enter the following commands.
 
@@ -17,45 +15,31 @@ Running a single command
 
 The following command will allow you to run a single command, without running a shell (e.g. for automation).
 
-.. Note:: Replace ``{COMMAND}`` with your command you want to run.
-
-.. Tip:: If you enter a ``p`` in front of your command (e.g. like ``rails r 'p Delayed::Job.count'``), you'll actually receive a printed output (without you won't!).
-
-when you've installed Zammad from a package
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
+.. note:: Replace ``{COMMAND}`` with your command you want to run.
 
- shell> zammad run rails r '{COMMAND}'
+.. tip:: If you enter a ``p`` in front of your command (e.g. like ``rails r 'p Delayed::Job.count'``), you'll actually receive a printed output (without you won't!).
 
-
-when you've installed Zammad from source
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: sh
 
-::
+   # package installation
+   $ zammad run rails r '{COMMAND}'
 
- shell> rails r '{COMMAND}'
+   # source installation
+   $ rails r '{COMMAND}'
 
 
 Running several commands in a shell
 -----------------------------------
 
 The following command will provide you a rails console, you can run several commands inside it.
 
-when you've installed Zammad from a package
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: sh
 
-::
+   # package installation
+   $ zammad run rails c
 
- shell> zammad run rails c
-
-
-when you've installed Zammad from source
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- shell> rails c
+   # source installation
+   $ rails c
 
 
 Working on the console
@@ -74,4 +58,3 @@ Here's a topic list for quick jumping and better overview.
    console/working-on-chat
    console/other-usefull-commands
    console/dangerzone-for-experts
-

admin/console/dangerzone-for-experts.rst

@@ -0,0 +1,119 @@
+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**!
+
+.. 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>`_.
+
+
+Deleting Tickets (and their articles)
+-------------------------------------
+
+.. code-block:: ruby
+
+   # Delete a ticket (specified by database ID)
+   >> Ticket.find(4).destroy
+
+   # Delete all tickets
+   >> Ticket.destroy_all
+
+   # Keep some tickets (specified by database ID); delete the rest
+   >> tickets_to_keep = [1, 2, 3]
+   >> Ticket.where.not(id: tickets_to_keep).destroy_all
+
+
+Deleting Customers
+------------------
+
+.. warning:: 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.
+
+.. code-block:: ruby
+
+   # Select customers by email address
+   >> customers = User.where(email: %w[customer@example.com customer@example.org])
+
+   >> customers = customers.joins(roles: :permissions)
+                           .where(roles: { active: true })
+                           .where(permissions: { name: 'ticket.customer', active: true })
+                           .where.not(id: 1)
+
+   # Preview affected users & tickets
+   >> puts customers.map do |user|
+        "Customer #{user.fullname}/#{user.id} has #{Ticket.where(customer_id: user.id).count} tickets #{Ticket.where(customer_id: user.id).pluck(:number)}"
+      end.join("\n")
+
+   # Proceed with deletion
+   >> customers.find_each do |user|
+        puts %{Preparing deletion of customer "#{user.fullname}" (and #{Ticket.where(customer_id: user.id).count} associated tickets)}
+
+        Ticket.where(customer: user).find_each do |ticket|
+          puts "  Deleting ticket ##{ticket.number}..."
+          ticket.destroy
+        end
+
+        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
+
+
+Deleting Organizations
+----------------------
+
+.. note:: Deleting an organization does **not** delete associated customers.
+
+.. code-block:: ruby
+
+   # Select organizations by "active" status
+   >> organizations = Organization.where(active: false)
+
+   # or, by name
+   >> organizations = Organization.where(name: 'Acme')
+
+   # or, by partial match on notes
+   >> organizations = Organization.where('note LIKE ?', '%foo%')
+
+   # Preview affected organizations
+   >> puts organizations.map { |org| "ORGANIZATION #{org.name}" }.join("\n")
+
+   # Proceed with deletion
+   >> organizations.each do |org|
+        puts %{Preparing deletion of organization "#{org.name}"...}
+
+        org.members.each do |member|
+           puts "  Removing #{member.fullname} from organization..."
+           member.update!(organization_id: nil)
+        end
+
+        puts "  Deleting #{org.name}..."
+        org.destroy
+      end
+
+
+Deleting System Records
+-----------------------
+
+.. code-block:: ruby
+
+   # Remove all online notifications
+   >> OnlineNotification.destroy_all
+
+   # Remove all entries from the Activity Stream (dashboard)
+   >> ActivityStream.destroy_all
+
+   # Remove entries for all recently viewed objects (tickets, users, organizations)
+   >> RecentView.destroy_all
+
+   # Remove all history information from tickets, users and organizations (dangerous!)
+   >> History.destroy_all

console/hidden-settings.rst → admin/console/hidden-settings.rst

@@ -2,35 +2,38 @@ 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. 
+Those settings might come in handy as it can change Zamnmads behavior.
 
-.. Note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community <https://community.zammad.org>`_.
+.. note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community <https://community.zammad.org>`_.
 
 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.
-::
-
- Setting.set('system_bcc', 'alias@domain.tld')
 
-You can easily check the current BCC-Setting by running the following: 
-::
-
- Setting.get('system_bcc')
+.. code-block:: ruby
+
+   >> Setting.set('system_bcc', 'alias@domain.tld')
+
+You can easily check the current BCC-Setting by running the following:
+
+.. code-block:: ruby
+
+   >> 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.
-::
-
-  Setting.set('ui_table_group_by_show_count', true)	# enable counter on grouped overviews
-  Setting.set('ui_table_group_by_show_count', false)	# disable counter on grouped overviews
-  Setting.get('ui_table_group_by_show_count')		# get current setting (if NIL, it's false)
+
+.. code-block:: ruby
+
+   >> Setting.set('ui_table_group_by_show_count', true)  # enable counter on grouped overviews
+   >> Setting.set('ui_table_group_by_show_count', false) # disable counter on grouped overviews
+   >> Setting.get('ui_table_group_by_show_count')        # get current setting (`nil` is false)
 
 .. image:: /images/console/ui_table_group_by_show_count-example.png
 
@@ -40,35 +43,40 @@ 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).
-::
-
-  Setting.set('ui_ticket_create_default_type', 'email-out')
-
+
+.. code-block:: ruby
+
+   >> Setting.set('ui_ticket_create_default_type', 'email-out')
+
 To check what setting is set currently, simply run
-::
-
-  Setting.get('ui_ticket_create_default_type')
+
+.. 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"=>""``.
-::
-
-  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:: 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 ( ``{}`` ).
-
+.. 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."})
+
+.. 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 ( ``{}`` ).
+
 
 To check what's currently set, you can use:
-::
-
-  Setting.get('ui_ticket_create_notes')
+
+.. code-block:: ruby
+
+   >> Setting.get('ui_ticket_create_notes')
 
 Sample of the above setting:
+
 .. image:: /images/console/ui_ticket_create_notes.gif
 
 
@@ -77,28 +85,31 @@ Show E-Mail-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.
-::
-
-  Setting.set('ui_user_organization_selector_with_email', true)
+
+.. code-block:: ruby
+
+   >> Setting.set('ui_user_organization_selector_with_email', true)
 
 Get the current state of this setting with:
-::
-
-  Setting.get('ui_user_organization_selector_with_email')
+
+.. code-block:: ruby
+
+   >> Setting.get('ui_user_organization_selector_with_email')
 
 
 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.
-::
-
-  Setting.set("html_email_css_font", "font-family:'Helvetica Neue', Helvetica, Arial, Geneva, sans-serif; font-size: 12px;")
+
+.. code-block:: ruby
+
+   >> Setting.set("html_email_css_font", "font-family:'Helvetica Neue', Helvetica, Arial, Geneva, sans-serif; font-size: 12px;")
 
 If you want to check the current setting, you can simply run the below code.
-::
-
-  Setting.get('html_email_css_font')
 
+.. code-block:: ruby
+
+   >> Setting.get('html_email_css_font')