Introduce Freshdesk-Migrator documentation (#212)

* Beginn freshdesk documentation

* Maintenance: Unify instance reset reference for better re-use

* WIP: Freshdesk Migrator

* Provide hint on how to start rails consoles and clean up console intro

* Unify console hint for migrations

* Maintenance: Correct typos as per Gerrits QA

* Maintenance: Extend user password reset part in limitations for more context

admin/console-rails-shell.include.rst

@@ -0,0 +1,7 @@
+.. code-block:: sh
+
+   # package installation
+   $ zammad run rails c
+
+   # source installation
+   $ rails c

admin/console.rst

@@ -1,9 +1,16 @@
 Console
 *******
 
-Zammad uses Ruby on Rails so you can make use of the `rails console <http://guides.rubyonrails.org/command_line.html>`_.
+Zammad uses Ruby on Rails so you can make use of the `rails console`_.
 
-.. 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**!
+.. _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**!
 
 To open the rails console on the shell you have to enter the following commands.
 
@@ -13,11 +20,16 @@ Start Zammad's Rails console
 Running a single command
 ------------------------
 
-The following command will allow you to run a single command, without running a shell (e.g. for automation).
+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!).
+.. 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!).
 
 .. code-block:: sh
 
@@ -32,16 +44,12 @@ The following command will allow you to run a single command, without running a
 Running several commands in a shell
 -----------------------------------
 
-The following command will provide you a rails console, you can run several commands inside it.
-
-.. code-block:: sh
-
-   # package installation
-   $ zammad run rails c
+The following command will provide you a rails console.
+It allows you to run several commands inside it.
 
-   # source installation
-   $ rails c
+This reduces loading times greatly.
 
+.. include:: /admin/console-rails-shell.include.rst
 
 Working on the console
 ======================

migration/freshdesk.rst

@@ -0,0 +1,278 @@
+From Freshdesk
+**************
+
+Limitations
+===========
+
+Please note below Freshdesk specific limitations. 
+These are additional limitations to the
+:ref:`general ones listed <migration_limitations>`.
+
+   * | Differential migrations are **not** supported!
+     | The general suggestion is to run a test import before to learn
+       how long the migration is going to take.
+   * **Important:** Please note that migration speed highly depends on your
+     Freshdesk plan (API rate limits apply).
+   * Due to API limitations Zammad will not show the total number of objects
+     to import, but instead correct them in steps of ``100``.
+   * User passwords are not migrated and will require the user to use the
+     `password reset link`_ on the login page.
+
+.. _password reset link:
+   https://admin-docs.zammad.org/en/latest/settings/security/base.html#lost-password
+
+   .. note::
+
+      Your Freshdesk plan has to provide API support.
+      This may not apply to all available plans.
+
+Prerequisites
+=============
+
+Zammad requires API access which is why you'll need to `create an API key`_
+for the migration. The migrator will request your Freshdesk subdomain and
+API key.
+
+.. warning:: **🥸 To be or not to be**
+
+  Ensure to retrieve the API key with a **full administrator** account.
+  Less privileged users will end in a broken migration.
+
+.. _create an API key:
+  https://support.freshdesk.com/support/solutions/articles/215517-how-to-find-your-api-key
+
+Importing Freshdesk data
+========================
+
+Generally you have two options on how to migrate data.
+If you have a fairly big instance with a lot of data, you may want to
+consider using the console over the browser version.
+
+.. tabs::
+
+   .. tab:: Via browser
+
+      After installing Zammad and configuring your 
+      :doc:`webserver </getting-started/configure-webserver>`, navigate to your 
+      Zammads FQDN in your browser and follow the migration wizard.
+
+      Depending on the number of users, tickets and Freshdesk plan this may take
+      some while.
+
+      .. figure:: /images/migration/freshdesk/import-via-ui.gif
+         :alt: Migration process of freshdesk via UI
+
+      .. note:: **😖 Scheduler got interrupted**
+
+         .. figure:: /images/migration/freshdesk/scheduler-interrupted.png
+
+         If this message appears after providing your credentials, please be
+         patient. The migration should start within 5 minutes.
+
+         If you receive above message after the migration begun, please
+         consider using the console approach instead and reset the
+         installation.
+
+   .. tab:: Via console
+
+      .. include:: /migration/rails-console-migrator-hint.include.rst
+
+      To prepare the migration, run the following commands
+         .. code-block:: ruby
+            :force:
+
+            # Set variables for easier settings
+            $ subdomain = '{freshdesk subdomain}.freshdesk.com'
+            $ token = '{freshdesk token}'
+
+            # Update Zammad settings for freshdesk import
+            $ Setting.set('import_freshdesk_endpoint', "https://#{subdomain}/api/v2")
+            $ Setting.set('import_freshdesk_endpoint_key', token)
+            $ Setting.set('import_backend', 'freshdesk')
+            $ Setting.set('import_mode', true)
+
+
+         .. hint::
+
+            Want to know if your configuration works before hand?
+            Run the following command:
+
+            .. code-block:: ruby
+
+               Sequencer.process('Import::Freshdesk::ConnectionTest')
+
+      To start the actual migration, run the following commands
+
+         .. code-block:: ruby
+            :force:
+
+            # That the actual job
+            $ job = ImportJob.create(name: 'Import::Freshdesk')
+            $ AsyncImportJob.perform_later(job)
+
+         .. tip::
+
+            **🤓 Want to check the state of the migration?**
+
+            Running the following command in a rails console will provide
+            detailed state information of your migration.
+
+            .. code-block:: ruby
+
+               pp ImportJob.find_by(name: 'Import::Freshdesk')
+
+            To give you an idea how the migration job state looks like, you can
+            use below tabs. As long as ``finished_at`` is ``nil``, the process is
+            still running.
+
+            .. tabs::
+
+               .. tab:: Freshly started import
+
+                  .. code-block:: ruby
+
+                     #<ImportJob:0x0000000008274310
+                      id: 1,
+                      name: "Import::Freshdesk",
+                      dry_run: false,
+                      payload: {},
+                      result:
+                       {"Organizations"=>
+                         {"skipped"=>0,
+                          "created"=>0,
+                          "updated"=>0,
+                          "unchanged"=>0,
+                          "failed"=>0,
+                          "deactivated"=>0,
+                          "sum"=>0,
+                          "total"=>100}},
+                      started_at: Mon, 03 Jan 2022 18:41:51 UTC +00:00,
+                      finished_at: nil,
+                      created_at: Mon, 03 Jan 2022 18:41:16 UTC +00:00,
+                      updated_at: Mon, 03 Jan 2022 18:43:32 UTC +00:00>
+
+               .. tab:: Import half way
+
+                  .. code-block:: ruby
+
+                     #<ImportJob:0x000055ba3d9dbbb8
+                      id: 1,
+                      name: "Import::Freshdesk",
+                      dry_run: false,
+                      payload: {},
+                      result:
+                       {"Groups"=>
+                         {"skipped"=>0,
+                          "created"=>3,
+                          "updated"=>0,
+                          "unchanged"=>0,
+                          "failed"=>0,
+                          "deactivated"=>0,
+                          "sum"=>3,
+                          "total"=>3},
+                        "Organizations"=>
+                         {"skipped"=>0,
+                          "created"=>193,
+                          "updated"=>1,
+                          "unchanged"=>0,
+                          "failed"=>0,
+                          "deactivated"=>0,
+                          "sum"=>194,
+                          "total"=>194},
+                        "Users"=>
+                         {"skipped"=>0,
+                          "created"=>3352,
+                          "updated"=>0,
+                          "unchanged"=>0,
+                          "failed"=>0,
+                          "deactivated"=>0,
+                          "sum"=>3352,
+                          "total"=>3352},
+                        "Tickets"=>
+                         {"skipped"=>0,
+                          "created"=>987,
+                          "updated"=>0,
+                          "unchanged"=>0,
+                          "failed"=>0,
+                          "deactivated"=>0,
+                          "sum"=>987,
+                          "total"=>1000}},
+                      started_at: Tue, 04 Jan 2022 11:37:38 UTC +00:00,
+                      finished_at: nil,
+                      created_at: Tue, 04 Jan 2022 11:37:36 UTC +00:00,
+                      updated_at: Tue, 04 Jan 2022 12:12:52 UTC +00:00>
+
+               .. tab:: Finished import
+
+                  .. code-block:: ruby
+
+                     #<ImportJob:0x0000561da0def350
+                      id: 1,
+                      name: "Import::Freshdesk",
+                      dry_run: false,
+                      payload: {},
+                      result:
+                       {"Groups"=>
+                         {"skipped"=>0,
+                          "created"=>3,
+                          "updated"=>0,
+                          "unchanged"=>0,
+                          "failed"=>0,
+                          "deactivated"=>0,
+                          "sum"=>3,
+                          "total"=>3},
+                        "Organizations"=>
+                         {"skipped"=>0,
+                          "created"=>193,
+                          "updated"=>1,
+                          "unchanged"=>0,
+                          "failed"=>0,
+                          "deactivated"=>0,
+                          "sum"=>194,
+                          "total"=>194},
+                        "Users"=>
+                         {"skipped"=>0,
+                          "created"=>3352,
+                          "updated"=>0,
+                          "unchanged"=>0,
+                          "failed"=>0,
+                          "deactivated"=>0,
+                          "sum"=>3352,
+                          "total"=>3352},
+                        "Tickets"=>
+                         {"skipped"=>0,
+                          "created"=>4714,
+                          "updated"=>0,
+                          "unchanged"=>0,
+                          "failed"=>1,
+                          "deactivated"=>0,
+                          "sum"=>4715,
+                          "total"=>4715}},
+                      started_at: Tue, 04 Jan 2022 11:37:38 UTC +00:00,
+                      finished_at: Tue, 04 Jan 2022 14:30:57 UTC +00:00,
+                      created_at: Tue, 04 Jan 2022 11:37:36 UTC +00:00,
+                      updated_at: Tue, 04 Jan 2022 14:30:57 UTC +00:00>
+
+      After the import has finished, run the following commands
+         .. code-block:: ruby
+            :force:
+
+            $ Setting.set('import_mode', true)
+            $ Setting.set('system_init_done', true)
+            $ Cache.clear
+
+After migration
+===============
+
+As the migration technically skips the getting started wizard, please
+note that you want to adjust your `FQDN settings`_ (FQDN & HTTP-Type).
+
+.. include:: /migration/how-to-login.include.rst
+
+.. _FQDN settings:
+   https://admin-docs.zammad.org/en/latest/settings/system/base.html
+
+After successfully migrating your Freshdesk instance, 
+continue with :doc:`/getting-started/first-steps`.
+
+.. include:: /migration/restarting-from-scratch.include.rst

migration/how-to-login.include.rst

@@ -0,0 +1,7 @@
+.. hint::
+
+   **😖 How do I login?**
+
+   Zammad provides admin access to the user whose API token you provided.
+   All other users will have to use the password reset function or login methods
+   like LDAP or one click logins.

migration/index.rst

@@ -34,6 +34,7 @@ Available Migration Options
 
    OTRS </migration/otrs>
    Zendesk </migration/zendesk>
+   Freshdesk </migration/freshdesk>
 
 .. note::
 

migration/otrs.rst

@@ -110,10 +110,7 @@ Importing OTRS data
 
    .. tab:: via Console
 
-      .. hint::
-
-         We have a dedicated page for :ref:`Zammads rails console <rails_shell>` 
-         to reduce this pages complexity.
+      .. include:: /migration/rails-console-migrator-hint.include.rst
 
       If you miss this at the beginning or you want to re-import again you have 
       to use the command line at the moment.
@@ -167,9 +164,4 @@ Set Zammad back into normal working mode
 All changes that occurred after your first migration should now also be available 
 within your Zammad installation.
 
-Restarting from scratch
-=======================
-
-Turned wrong at some point? 
-You can find the required commands to reset Zammad in our 
-:ref:`Dangerzone <dangerzone_reset_zammad>`.
+.. include:: /migration/restarting-from-scratch.include.rst

migration/rails-console-migrator-hint.include.rst

@@ -0,0 +1,7 @@
+.. hint::
+
+   Here's how to open a console.
+
+   .. include:: /admin/console-rails-shell.include.rst
+
+   Learn more about the :doc:`Zammad console </admin/console>`.

migration/restarting-from-scratch.include.rst

@@ -0,0 +1,6 @@
+Restarting from scratch
+=======================
+
+Turned wrong at some point? 
+You can find the required commands to reset Zammad in our 
+:ref:`Dangerzone <dangerzone_reset_zammad>`.