diff --git a/about-zammad.rst b/about/zammad.rst similarity index 87% rename from about-zammad.rst rename to about/zammad.rst index 172c6820..5f88b6e7 100644 --- a/about-zammad.rst +++ b/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 - diff --git a/admin-console.rst b/admin/console.rst similarity index 63% rename from admin-console.rst rename to admin/console.rst index 29a1b897..2ee7b272 100644 --- a/admin-console.rst +++ b/admin/console.rst @@ -1,11 +1,9 @@ -.. _zammad-console: - Console ******* 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**! +.. 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,24 +15,17 @@ 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 @@ -42,20 +33,13 @@ 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 - diff --git a/admin/console/dangerzone-for-experts.rst b/admin/console/dangerzone-for-experts.rst new file mode 100644 index 00000000..cd0e7b18 --- /dev/null +++ b/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 `_. + + +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 diff --git a/console/hidden-settings.rst b/admin/console/hidden-settings.rst similarity index 62% rename from console/hidden-settings.rst rename to admin/console/hidden-settings.rst index 33c8d34e..1dab5966 100644 --- a/console/hidden-settings.rst +++ b/admin/console/hidden-settings.rst @@ -2,23 +2,25 @@ 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 `_. +.. note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. 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 @@ -26,11 +28,12 @@ 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,14 +43,16 @@ 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 @@ -55,20 +60,23 @@ 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') diff --git a/admin/console/other-usefull-commands.rst b/admin/console/other-usefull-commands.rst new file mode 100644 index 00000000..eedfe024 --- /dev/null +++ b/admin/console/other-usefull-commands.rst @@ -0,0 +1,59 @@ +Other useful commands +********************** + +.. note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. + +Fetch mails +----------- + +The below command will do a manual fetch of mail channels. This will also show erors that might appear within that process. + +.. code-block:: ruby + + >> Channel.fetch + + +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", format: 'string', created_by_id: 1, updated_by_id: 1 ) + + +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}`` against 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 +--------------------------------- + +.. warning:: 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 "fill data". + +.. code-block:: ruby + + >> FillDB.load(agents: 50,customers: 1000,groups: 20,organizations: 40,overviews: 5,tickets: 100,) diff --git a/console/working-on-chat.rst b/admin/console/working-on-chat.rst similarity index 57% rename from console/working-on-chat.rst rename to admin/console/working-on-chat.rst index c2357148..e77348c7 100644 --- a/console/working-on-chat.rst +++ b/admin/console/working-on-chat.rst @@ -4,8 +4,6 @@ Working with chat logs .. hint:: To find out how to do something not listed below, post your question on the `community boards `_. -.. _console-chat-ip: - Removing IP address logs ------------------------ @@ -14,10 +12,10 @@ from **closed chats that haven’t been updated in the last seven days**: .. code-block:: ruby - Chat::Session.where(state: 'closed').where('updated_at < ?', 7.days.ago).each do |session| - next if session.preferences['remote_ip'].blank? + >> Chat::Session.where(state: 'closed').where('updated_at < ?', 7.days.ago).each do |session| + next if session.preferences['remote_ip'].blank? - session.preferences.delete('geo_ip') - session.preferences.delete('remote_ip') - session.save!(touch: false) - end + session.preferences.delete('geo_ip') + session.preferences.delete('remote_ip') + session.save!(touch: false) + end diff --git a/console/working-on-groups.rst b/admin/console/working-on-groups.rst similarity index 63% rename from console/working-on-groups.rst rename to admin/console/working-on-groups.rst index defe8cfe..c31c5767 100644 --- a/console/working-on-groups.rst +++ b/admin/console/working-on-groups.rst @@ -1,7 +1,7 @@ Working with groups ******************* -.. Note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. +.. note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. To open the rails console on the shell you have to enter the following commands. @@ -9,7 +9,6 @@ To open the rails console on the shell you have to enter the following commands. Find group ---------- -:: - - Group.find_by(name: 'Users').follow_up_possible +.. code-block:: ruby + >> Group.find_by(name: 'Users').follow_up_possible diff --git a/admin/console/working-on-tickets.rst b/admin/console/working-on-tickets.rst new file mode 100644 index 00000000..51beacab --- /dev/null +++ b/admin/console/working-on-tickets.rst @@ -0,0 +1,187 @@ +Working with ticket information +******************************* + +.. note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. + +Get the RAW mail that Zammad fetched +------------------------------------ + +The following command will help you to check on received emls Zamamd fetched. This comes in handy if you delete Mails upon fetching and you need to check the eml itself. + +To get the first articles eml, you can use the following command. In our example the ticket number in question is ``101234`` + +.. code-block:: ruby + + >> Ticket.find_by(number:'101234').articles.first.as_raw.content + +If needed, you can also get the raw content of later articles (you'll need to find the correct article though). Again, we expect ``101234`` to be our ticket number. +In the first step we get all article IDs of the ticket, from the list we get, we can then get the articles content. + +.. code-block:: ruby + + >> Ticket.find_by(number:'101234').articles_ids + => [4, 3, 2] + >> Ticket::Article.find(3).as_raw.content + +.. note:: If you just use ``Ticket::Article.find(3)`` you can see further information (like who sent the mail, when we fetched it, ...). + + +Update all tickets of a specific customer +----------------------------------------- + +.. warning:: Please note that this action can be expensive in ressource terms, if you have many tickets, this might slow down Zammad. + +.. code-block:: ruby + + >> Ticket.where(customer_id: 4).update_all(customer_id: 1) + + +Change priority +--------------- + +The following commands will enable you to change the naming of priorities. If you set ``.default_create`` to ``true`` you can manipulate what Zammad will use as default priority. + +.. code-block:: ruby + + >> priority2 = Ticket::Priority.find(2) + >> priority2.name = '2-high' + >> priority2.default_create = true + >> priority2.save! + + +Get ticket state types +---------------------- + +This will show all Ticket States needed for creating new states. + +.. note:: Missing States you just created? You might want to use ``Ticket.State.all`` to display all states for Tickets. + +.. code-block:: ruby + + >> Ticket::StateType.all + + +Add new ticket state +-------------------- + +.. note:: You can use ``ignore_escalation: true,`` to ignore possible SLA escalations (pending reminder and pending close use that 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, + ) + +Add a date and time picker (pending till) for pending states +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add the time picker (pending till) to the new pending state, you'll need to execute the following code: + +.. code-block:: ruby + + >> attribute = ObjectManager::Attribute.get( + object: 'Ticket', + name: 'pending_time', + ) + >> attribute.data_option[:required_if][:state_id] = Ticket::State.by_category(:pending).pluck(:id) + >> attribute.data_option[:shown_if][:state_id] = Ticket::State.by_category(:pending).pluck(:id) + >> attribute.save! + + +.. note:: In enhanced cases you might want do define the ``state_id`` on your own. In this case just pick the returned ``state_id`` from ``Ticket::State.by_category(:pending).pluck(:id)`` and use them with ``attribute.data_option[:required_if][:state_id] = {state_id(s)}`` and ``attribute.data_option[:shown_if][:state_id] = {state_id(s)}`` directly. Don't forget to save! + + + +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 +------------------------------------ + +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 diff --git a/console/working-on-users.rst b/admin/console/working-on-users.rst similarity index 60% rename from console/working-on-users.rst rename to admin/console/working-on-users.rst index 403c9fb8..54b15185 100644 --- a/console/working-on-users.rst +++ b/admin/console/working-on-users.rst @@ -1,35 +1,38 @@ Working on user information *************************** -.. Note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. +.. note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. Find user --------- In order to work on user information or to check for specific information, you'll need to find it first. -:: - User.find(4) # We already know the ID of the user - User.find_by(email: 'your@email') # Searching for the user by his E-Mail-Address - User.find_by(login: 'john.doe') # Searching for the user by his login +.. code-block:: ruby + + >> User.find(4) # We already know the ID of the user + >> User.find_by(email: 'your@email') # Searching for the user by his E-Mail-Address + >> User.find_by(login: 'john.doe') # Searching for the user by his login Re-activate a locked user account --------------------------------- It sometimes happens that a user locks himself out by wildly trying the wrong password multiple times. -Depending on your maximum failing login count (`default: 10 times`), Zammad might lock the account. +Depending on your maximum failing login count (`default: 10 times`), Zammad might lock the account. The user can't login any more (forever) if he doesn't change the password or you reset the counter. -:: - u=User.find(**USERID**) - u.login_failed=0 - u.save! +.. code-block:: ruby + + >> u=User.find(**USERID**) + >> u.login_failed=0 + >> u.save! You can also double check if the account is locked by running the following (result needs to be 1 above your limit, so `11` for the default of 10 failing logins) -:: - User.find(**USERID**).login_failed +.. code-block:: ruby + + >> User.find(**USERID**).login_failed Change / Update E-Mail-Adress of User @@ -37,28 +40,30 @@ Change / Update E-Mail-Adress of User If needed, you can simply change the E-Mail-Address of the user. -.. Note:: Please note that the login attribute is not affected by this and Zammad thus might show different information within the UI. -:: +.. note:: Please note that the login attribute is not affected by this and Zammad thus might show different information within the UI. + + .. code-block:: ruby + + >> u = User.find(**USERID**) + >> u.email = 'user@exmaple.com' + >> u.save! + - u=User.find(**USERID**) - u.email = 'user@exmaple.com' - u.save! - - You need to find the User-ID of the user first for this. - - + + Change / Update Login name of User ---------------------------------- Change the user name of the user (e.g. if you want to login with a shorter username instead of a mail address) -:: - u=User.find(**USERID**) - u.login = 'user@exmaple.com' - u.save! - - +.. code-block:: ruby + + >> u = User.find(**USERID**) + >> u.login = 'user@exmaple.com' + >> u.save! + + You need to find the User-ID of the user first for this. @@ -66,18 +71,19 @@ Set admin rights for user ------------------------- Don't have access to Zammad anymore? Grant yourself or another user administrative rights. -:: - u = User.find_by(email: 'you@example.com') - u.roles = Role.where(name: ['Agent', 'Admin']) - u.save! +.. code-block:: ruby + + >> u = User.find_by(email: 'you@example.com') + >> u.roles = Role.where(name: ['Agent', 'Admin']) + >> u.save! Set password for user --------------------- You or the user did forget his password? No problem! Simply reset it by hand if needed. -:: - User.find_by(email: 'you@example.com').update!(password: 'your_new_password') +.. code-block:: ruby + >> User.find_by(email: 'you@example.com').update!(password: 'your_new_password') diff --git a/admin/console/zammad-settings.rst b/admin/console/zammad-settings.rst new file mode 100644 index 00000000..09bc7c30 --- /dev/null +++ b/admin/console/zammad-settings.rst @@ -0,0 +1,87 @@ +Getting and Updating Zammad-Settings +************************************ + +.. note:: Please note that this is not a full setting list, if you're missing settings, feel free to ask over at our `Community `_. + + +Get ticket_hook setting +----------------------- + +This will give you the Ticket hook that you'll find inside the `[]` in front of the ticket number. +By default this will be `Ticket#` - you shouldn't change this setting in a productive system. + +.. code-block:: ruby + + >> Setting.get('ticket_hook') + + +Get fqdn setting +---------------- + +Get the current FQDN-Setting of Zammad and, if needed, adjust it. + +.. code-block:: ruby + + >> Setting.get('fqdn') # Get FQDN + >> Setting.set('fqdn', 'new.domain.tld') # Set a new FQDN + + +Find storage_provide setting +---------------------------- + +The following command returns a list of available settings for `storage_provider` (for attachments). + +.. code-block:: ruby + + >> Setting.find_by(name: 'storage_provider') + + +Set storage_rpovider Setting +---------------------------- + +Change the storage_provider if needed. + +.. code-block:: ruby + + >> Setting.set('storage_provider', 'DB') # Change Attachment-Storage to database + >> Setting.get('storage_provider') # get the current Attachment-Storage + + +Configuring Elasticsearch +------------------------- + +If your elasticsearch installation changes, you can use the following commands to ensure that Zammad still can access elasticsearch. + +.. code-block:: ruby + + >> Setting.set('es_url', 'http://127.0.0.1:9200') # Change elasticsearch URL to poll + >> Setting.set('es_user', 'elasticsearch') # Change elasticsearch user (e.g. for authentication) + >> Setting.set('es_password', 'zammad') # Change the elasticsearch password for authentication + >> Setting.set('es_index', Socket.gethostname + '_zammad') # Change the index name + >> Setting.set('es_attachment_ignore', %w[.png .jpg .jpeg .mpeg .mpg .mov .bin .exe .box .mbox]) # A list of ignored file extensions (they will not be indexed) + >> Setting.set('es_attachment_max_size_in_mb', 50) # Limit the Attachment-Size to push to your elasticsearch index + + +Use the OTRS importer from the shell +------------------------------------ + +If needed, you can configure and run the OTRS-Import from console. + +.. code-block:: ruby + + >> Setting.set('import_otrs_endpoint', 'http://xxx/otrs/public.pl?Action=ZammadMigrator') + >> Setting.set('import_otrs_endpoint_key', 'xxx') + >> Setting.set('import_mode', true) + >> Import::OTRS.start + + +Enable proxy +------------ + +Zammad needs to use a proxy for network communication? Set it here. + +.. code-block:: ruby + + >> Setting.set('proxy', 'proxy.example.com:3128') + >> Setting.set('proxy_username', 'some user') + >> Setting.set('proxy_password', 'some pass') diff --git a/api-group.rst b/api-group.rst deleted file mode 100644 index e794b912..00000000 --- a/api-group.rst +++ /dev/null @@ -1,183 +0,0 @@ -Group -***** - -List -==== - -Required permission: - -* admin.group (can read all groups) - -Request:: - - GET /api/v1/groups - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "name": "Group 1", - "signature_id": 123, - "email_address_id": 123, - "assignment_timeout": 180, - "follow_up_possible": "yes", - "follow_up_assignment": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "name": "Group 2", - "signature_id": 123, - "email_address_id": 123, - "assignment_timeout": 180, - "follow_up_possible": "no", - "follow_up_assignment": false, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - - - -Show -==== - -Required permission: - -* admin.group (can read all groups) - -Request:: - - GET /api/v1/groups/{id} - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "name": "Group 1", - "signature_id": 123, - "email_address_id": 123, - "assignment_timeout": 180, - "follow_up_possible": "yes", - "follow_up_assignment": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - -Create -====== - -Required permission: - -* admin.group - -Request:: - - POST /api/v1/groups - - - { - "name": "Group 1", - "signature_id": 123, - "email_address_id": 123, - "assignment_timeout": 180, - "follow_up_possible": "yes", - "follow_up_assignment": true, - "active": true, - "note": "some note" - } - - - -Response:: - - Status: 201 Created - - { - "id": 123, - "name": "Group 1", - "signature_id": 123, - "email_address_id": 123, - "assignment_timeout": 180, - "follow_up_possible": "yes", - "follow_up_assignment": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Update -====== - -Required permission: - -* admin.group - -Request:: - - PUT /api/v1/groups/{id} - - { - "id": 123, - "name": "Group 1", - "signature_id": 123, - "email_address_id": 123, - "assignment_timeout": 180, - "follow_up_possible": "yes", - "follow_up_assignment": true, - "active": true, - "note": "some note" - } - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "name": "Group 1", - "signature_id": 123, - "email_address_id": 123, - "assignment_timeout": 180, - "follow_up_possible": "yes", - "follow_up_assignment": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Delete -====== - -Required permission: - -* admin.group (only if no references in history tables and tickets exist) - -Request:: - - DELETE /api/v1/groups/{id} - - -Response:: - - Status: 200 Ok - - {} diff --git a/api-intro.rst b/api-intro.rst deleted file mode 100644 index 18677cf6..00000000 --- a/api-intro.rst +++ /dev/null @@ -1,239 +0,0 @@ -Introduction -************ - -Zammad is a web based open source helpdesk/ticket system with many features -to manage customer communication via several channels like telephone, facebook, -twitter, chat and e-mails. - -This chapter describes the Zammad API v1. - -The API -======= - -Zammad provides a REST/JSON API. Its endpoints are documented with the HTTP method for the request and a partial resource. - -Example:: - - GET /api/v1/users - - -The full URL looks like:: - - https://your_zammad/api/v1/users - - -Curly braces {} indicate values you have to supply for the URL. - -Example:: - - GET /api/v1/users/{id} - - -Authentication -============== - -Zammad supports three different authentication methods for API. - - -HTTP Basic Authentication (username/password) ---------------------------------------------- - -The username/password must be provided as HTTP header in the HTTP call. The Zammad admin can enable/disable the authentication method in the admin interface. Read more about HTTP basic authentication [here](https://en.wikipedia.org/wiki/Basic_access_authentication). - -Example:: - - curl -u {username}:{password} https://your_zammad/api/v1/users - - -HTTP Token Authentication (access token) ----------------------------------------- - -The access token must be provided as HTTP header in the HTTP call. Each user needs to create its own access token in the user preferences. The Zammad admin can enable/disable the authentication method in the admin interface. - -Example:: - - curl -H "Authorization: Token token={your_token}" https://your_zammad/api/v1/users - - -OAuth2 (token access) ---------------------- - -The Zammad API supports OAuth2 authorization. In order to create OAuth2 tokens for an external application, the Zammad user needs to create an application in the admin interface. The access token then has to be given within the HTTP header: - -Example:: - - curl -H "Authorization: Bearer {your_token}" https://your_zammad/api/v1/users - - -Request Format -============== - -Zammad uses JSON for its API, so you need to set a "Content-Type: application/json" in each HTTP call. Otherwise the response will be text/html. - -Example:: - - POST /api/v1/users/{id} HTTP/1.1 - Content-Type: application/json - - { - "name":"some name", - "organization_id": 123, - "note":"some note" - } - -Example CURL Requests -===================== - -Get information:: - - curl -u test@zammad.com:test123 https://xxx.zammad.com/api/v1/tickets/3 - -Put information:: - - curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X PUT -d '{ json: "data" }' https://xxx.zammad.com/api/v1/tickets/3 - -Post information:: - - curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{ json: "data" }' https://xxx.zammad.com/api/v1/tickets/3 - - -Example CURL Requests (for tickets and users) -============================================= - -Create a new ticket:: - - curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{"title":"Help me!","group": "Users","article":{"subject":"some subject","body":"some message","type":"note","internal":false},"customer":"email_of_existing_customer@example.com","note": "some note"}' https://xxx.zammad.com/api/v1/tickets - -Search for tickets (with contains "some message"):: - - curl -u test@zammad.com:test123 'https://xxx.zammad.com/api/v1/tickets/search?query=some+message&limit=10&expand=true' - -Search for tickets (for tickets with state new and open ):: - - curl -u test@zammad.com:test123 'https://xxx.zammad.com/api/v1/tickets/search?query=state:new%20OR%20state:open&limit=10&expand=true' - -For more search examples regarding searching, please see `this page `_ . - -Create an new user:: - - curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{"firstname":"Bob","lastname":"Smith","email":"email_of_customer@example.com","roles":["Customer"],"password":"some_password"}' https://xxx.zammad.com/api/v1/users - -Create an new user (with welcome email):: - - curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{"firstname":"Bob","lastname":"Smith","email":"email_of_customer@example.com","roles":["Customer"],"password":"some_password","invite":true}' https://xxx.zammad.com/api/v1/users - -Search for users:: - - curl -u test@zammad.com:test123 'https://xxx.zammad.com/api/v1/users/search?query=smith&limit=10&expand=true' - -Example CURL Request on behalf of a different user -========================================== - -It is possible to do a request on behalf of a different user. If you have your own application and you want to create a ticket for the customer -without the information that the api user has created this ticket then you can transfer the target user with the request to create the ticket on behalf of the customer user:: - - curl -u test@zammad.com:test123 -H "Content-Type: application/json" -H "X-On-Behalf-Of: user-login" -X POST -d '{"title":"Help me!","group": "Users","article":{"subject":"some subject","body":"some message","type":"note","internal":false},"customer":"email_of_existing_customer@example.com","note": "some note"}' https://xxx.zammad.com/api/v1/tickets - -The value of the header has to contain one of the following values: - -* user id -* user login -* user email - -The value types will be checked in a cascade and the first detected user by id, login or email will be used for the request action. - -This functionality can be used for any type of action. - -Requirements for the feature: - -* Authenticated user must have **admin.user** permissions -* Feature is available since Zammad version 2.4 - -Response Format -=============== - -If a response is successful, an HTTP status code in the 200 or 300 range will be returned. If an item has been created or updated, all new attributes will be returned (also server side generated attributes like created_at and updated_at). - -Example:: - - Status: 201 Created - Content-Type:application/json; charset=utf-8 - - { - "id": 123, - "name":"some name", - "organization_id": 123, - "note":"some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Response Format (expanded) -========================== - -If you want to retrieve expanded information for a request (e. g. the organization attribute), you just need to add an ``expand=true`` to the request URL. - -Example:: - - GET /api/v1/users/{id}?expand=true HTTP/1.1 - -will return the following structure, expanded by "organization":: - - Status: 200 Ok - Content-Type:application/json; charset=utf-8 - - { - "id": 123, - "name":"some name", - "organization_id": 123, - "organization": "Some Organization Name", - "note":"some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Pagination -========== - -All resources support pagination:: - - GET /api/v1/users?expand=true&page=1&per_page=5 HTTP/1.1 - -will return five records beginning with first record of all:: - - Status: 200 Ok - Content-Type:application/json; charset=utf-8 - - [ - { - "id": 1, - "name":"some name 1", - "organization_id": 123, - "organization": "Some Organization Name", - "note":"some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 2, - "name":"some name 2", - "organization_id": 345, - "organization": "Some Other Organization Name", - "note":"some note", - "updated_at": "2016-08-17T07:55:42.221Z", - "created_at": "2016-08-16T09:112:42.221Z" - }, - ... - } - - -API clients -=========== - -* Ruby Client - https://github.com/zammad/zammad-api-client-ruby -* PHP Client - https://github.com/zammad/zammad-api-client-php -* .NET Client - https://github.com/Asesjix/Zammad-Client -* Android API-Client - https://github.com/KirkBushman/zammad-android - .. Note:: Please note that this is a API client only, it's no "ready to use" App. diff --git a/api-notification.rst b/api-notification.rst deleted file mode 100644 index 1f1599d0..00000000 --- a/api-notification.rst +++ /dev/null @@ -1,151 +0,0 @@ -Online Notification -******************* - -List -==== - -Required permission: - -* authenticated user (content of notitifcations depends on user permissions) - -Request:: - - GET /api/v1/online_notifications - - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "o_id": 628, - "object": "Ticket", - "type": "escalation", - "seen": true, - "updated_at": "2016-08-16T07:55:42.119Z", - "updated_by_id": 123, - "created_at": "2016-08-16T07:55:42.119Z", - "created_at_id": 123 - }, - { - "id": 124, - "o_id": 629, - "object": "Ticket", - "type": "update", - "seen": false, - "updated_at": "2016-08-16T07:55:47.119Z", - "updated_by_id": 123, - "created_at": "2016-08-16T07:55:47.119Z", - "created_at_id": 123 - }, - { - "id": 125, - "o_id": 630, - "object": "Ticket", - "type": "create", - "seen": false, - "updated_at": "2016-08-16T07:57:49.119Z", - "updated_by_id": 123, - "created_at": "2016-08-16T07:57:49.119Z", - "created_at_id": 123 - }, - ] - - -Show -==== - -Required permission: - -* authenticated user (content of notifications depends on user permissions) - -Request:: - - GET /api/v1/online_notifications/{id} - -Response:: - - Status: 200 Ok - - { - "id": 123, - "o_id": 628, - "object": "Ticket", - "type": "escalation", - "seen": true, - "updated_at": "2016-08-16T07:55:42.119Z", - "updated_by_id": 123, - "created_at": "2016-08-16T07:55:42.119Z", - "created_at_id": 123 - } - -Update -====== - -Required permission: - -* admin.object - -Request:: - - PUT /api/v1/online_notifications/{id} - - { - "seen": true, - } - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "o_id": 628, - "object": "Ticket", - "type": "escalation", - "seen": true, - "updated_at": "2016-08-16T07:55:42.119Z", - "updated_by_id": 123, - "created_at": "2016-08-16T07:55:42.119Z", - "created_at_id": 123 - } - - -Delete -====== - -Required permission: - -* authenticated user (content of notifications depends on user permissions) - -Request:: - - DELETE /api/v1/online_notifications/{id} - - -Response:: - - Status: 200 Ok - - {} - -Mark all as read -================ - -Required permission: - -* authenticated user (content of notifications depends on user permissions) - -Request:: - - POST /api/v1/online_notifications/mark_all_as_read - - -Response:: - - Status: 200 Ok - - {} diff --git a/api-object.rst b/api-object.rst deleted file mode 100644 index c256dd83..00000000 --- a/api-object.rst +++ /dev/null @@ -1,278 +0,0 @@ -Object -****** - -List -==== - -Required permission: - -* admin (access to admin interface) - -Request:: - - GET /api/v1/object_manager_attributes - -Response:: - - Status: 200 Ok - - [ - { - "id":49, - "name":"anrede", - "display":"Anrede", - "data_type":"select", - "data_option":{ - "options":{ - "Mr":"Mr", - "Ms":"Ms", - "Company":"Company" - }, - "default":"Mr", - "null":true, - "maxlength":255, - "nulloption":true - }, - "data_option_new":{ - - }, - "editable":true, - "active":true, - "screens":{ - "create":{ - "Customer":{ - "shown":true, - "required":true - } - }, - "edit":{ - "Customer":{ - "shown":true - }, - "Agent":{ - "shown":true - } - }, - "create_middle":{ - "Agent":{ - "shown":true - } - } - }, - "to_create":false, - "to_migrate":false, - "to_delete":false, - "to_config":false, - "position":1550, - "created_by_id":3, - "updated_by_id":3, - "created_at":"2017-01-13T16:19:23.116Z", - "updated_at":"2017-01-17T11:16:13.298Z", - "object":"Ticket" - }, - # ... - ] - -Show -==== - -Required permission: - -* admin (access to admin interface) - -Request:: - - GET /api/v1/object_manager_attributes/:id - -Response:: - - Status: 200 Ok - - { - "id":49, - "name":"anrede", - "display":"Anrede", - "data_type":"select", - "data_option":{ - "options":{ - "Mr":"Mr", - "Ms":"Ms", - "Company":"Company" - }, - "default":"Mr", - "null":true, - "maxlength":255, - "nulloption":true - }, - "data_option_new":{ - - }, - "editable":true, - "active":true, - "screens":{ - "create":{ - "Customer":{ - "shown":true, - "required":true - } - }, - "edit":{ - "Customer":{ - "shown":true - }, - "Agent":{ - "shown":true - } - }, - "create_middle":{ - "Agent":{ - "shown":true - } - } - }, - "to_create":false, - "to_migrate":false, - "to_delete":false, - "to_config":false, - "position":1550, - "created_by_id":3, - "updated_by_id":3, - "created_at":"2017-01-13T16:19:23.116Z", - "updated_at":"2017-01-17T11:16:13.298Z", - "object":"Ticket" - } - -Create -====== - -Required permission: - -* admin (access to admin interface) - -Request:: - - POST /api/v1/object_manager_attributes - -Response:: - - Status: 200 Ok - - { - "name":"product", - "object":"Ticket", - "display":"Produkt", - "active":true, - "data_type":"select", - "data_option":{ - "options":{ - "wert1":"anzeige1", - "wert2":"anzeige12" - } - }, - "screens":{ - "create_middle":{ - "Customer":{ - "shown":true, - "item_class":"column" - }, - "Agent":{ - "shown":true, - "item_class":"column" - } - }, - "edit":{ - "Customer":{ - "shown":true - }, - "Agent":{ - "shown":true - } - } - } - } - -Update -====== - -Required permission: - -* admin (access to admin interface) - -Request:: - - PUT /api/v1/object_manager_attributes/:id - -Response:: - - Status: 200 Ok - - { - "id":49, - "name":"anrede", - "display":"Anrede", - "data_type":"select", - "data_option":{ - "options":{ - "Mr":"Mr", - "Ms":"Ms", - "Company":"Company" - }, - "default":"Mr", - "null":true, - "maxlength":255, - "nulloption":true - }, - "data_option_new":{ - - }, - "editable":true, - "active":true, - "screens":{ - "create":{ - "Customer":{ - "shown":true, - "required":true - } - }, - "edit":{ - "Customer":{ - "shown":true - }, - "Agent":{ - "shown":true - } - }, - "create_middle":{ - "Agent":{ - "shown":true - } - } - }, - "to_create":false, - "to_migrate":false, - "to_delete":false, - "to_config":false, - "position":1550, - "created_by_id":3, - "updated_by_id":3, - "created_at":"2017-01-13T16:19:23.116Z", - "updated_at":"2017-01-17T11:16:13.298Z", - "object":"Ticket" - } - -Execute Database Migrations -=========================== - -Required permission: - -* admin (access to admin interface) - -Request:: - - POST /api/v1/object_manager_attributes_execute_migrations - -Response:: - - Status: 200 Ok - - { } diff --git a/api-organization.rst b/api-organization.rst deleted file mode 100644 index 7ff4dcbf..00000000 --- a/api-organization.rst +++ /dev/null @@ -1,191 +0,0 @@ -Organization -************ - -List -==== - -Required permission: - -* ticket.agent or admin.organization (can read all organizations) -* any (can only read its own organization if exists) - -Request:: - - GET /api/v1/organizations - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "name": "Org 1", - "shared": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "name": "Org 2", - "shared": false, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - - -Search -====== - -Required permission: - -* ticket.agent or admin.organization (can read all organization) - -Request:: - - GET /api/v1/organizations/search?query=what&limit=10 - -Note: As of Zammad 2.6 parameters (sort_by=some_row and order_by=asc or desc) can also be used for sorting. - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "name": "Org 1", - "shared": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "name": "Org 2", - "shared": false, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - - - -Show -==== - -Required permission: - -* ticket.agent or admin.organization (can read all organizations) -* any (can only read its own user if exists) - -Request:: - - GET /api/v1/organizations/{id} - -Response:: - - Status: 200 Ok - - { - "id": 123, - "name": "Org 1", - "shared": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - -Create -====== - -Required permission: - -* admin.organization - -Request:: - - POST /api/v1/organizations - - { - "name": "Org 1", - "shared": true, - "active": true, - "note": "some note" - } - -Response:: - - Status: 201 Created - - { - "id": 123, - "name": "Org 1", - "shared": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Update -====== - -Required permission: - -* admin.organization - -Request:: - - PUT /api/v1/organizations/{id} - - { - "id": 123, - "name": "Org 1", - "shared": true, - "active": true, - "note": "some note" - } - -Response:: - - Status: 200 Ok - - { - "id": 123, - "name": "Org 1", - "shared": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - -Delete -====== - -Required permission: - -* admin.organization (only if no references in history tables and tickets exist) - -Request:: - - DELETE /api/v1/organization/{id} - - -Response:: - - Status: 200 Ok - - {} - diff --git a/api-tags.rst b/api-tags.rst deleted file mode 100644 index da4eaffb..00000000 --- a/api-tags.rst +++ /dev/null @@ -1,193 +0,0 @@ -Tags -**** - -List -==== - -Required permission: - -* ticket.agent or admin.tag - -Request:: - - GET /api/v1/tags?object=Ticket&o_id=10 - -Response:: - - Status: 200 Ok - - { - "tags": [ - "tag 1", - "tag 2", - "tag 3" - ] - } - - -Search -====== - -Required permission: - -* ticket.agent or admin.tag - -Request:: - - GET /api/v1/tag_search?term=tag - -Response:: - - Status: 200 Ok - - [ - { - "id": 7, - "value": "tag 1" - }, - { - "id": 8, - "value": "tag 2" - }, - { - "id": 9, - "value": "tag 3" - } - ] - -Add -==== - -Required permission: - -* ticket.agent or admin.tag - -Request:: - - GET /api/v1/tags/add?object=Ticket&o_id=10&item=tag+4 - -Response:: - - Status: 200 Ok - - true - -Remove -==== - -Required permission: - -* ticket.agent or admin.tag - -Request:: - - GET /api/v1/tags/remove?object=Ticket&o_id=10&item=tag+4 - -Response:: - - Status: 200 Ok - - true - -Admin - List -==== - -Required permission: - -* admin.tag - -Request:: - - GET /api/v1/tag_list - -Response:: - - Status: 200 Ok - - [ - { - "id": 7, - "name": "tag 1", - "count": 1 - }, - { - "id": 8, - "name": "tag 2", - "count": 1 - }, - { - "id": 9, - "name": "tag 3", - "count": 1 - }, - { - "id": 11, - "name": "tag 4", - "count": 0 - }, - { - "id": 6, - "name": "test", - "count": 0 - } - ] - -Admin - Create -==== - -Required permission: - -* admin.tag - -Request:: - - POST /api/v1/tag_list - - { - name: "tag 5" - } - -Response:: - - Status: 200 Ok - - {} - -Admin - Rename -==== - -Required permission: - -* admin.tag - -Request:: - - PUT /api/v1/tag_list/{id} - - { - id: 6, - name: "tag 5" - } - -Response:: - - Status: 200 Ok - - {} - -Admin - Delete -==== - -Required permission: - -* admin.tag - -Request:: - - DELETE /api/v1/tag_list/{id} - -Response:: - - Status: 200 Ok - - {} diff --git a/api-ticket-article.rst b/api-ticket-article.rst deleted file mode 100644 index 4c8b9e79..00000000 --- a/api-ticket-article.rst +++ /dev/null @@ -1,292 +0,0 @@ -Ticket Article -****** - -By Ticket -==== - -Required permission: - -* ticket.agent (access to related ticket) -* ticket.customer (access to related ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) - -Request:: - - GET /api/v1/ticket_articles/by_ticket/{ticketId} - -Response:: - - Status: 200 Ok - - [ - { - "id": 3, - "ticket_id": 3, - "from": "Bob Smith", - "to": "", - "cc": "", - "subject": "some subject", - "body": "huhuhuu
huhuhuu
huhuhuu

", - "content_type": "text/html", - "type": "note", - "internal": false, - ... - "updated_at": "2016-08-15T07:55:42.119Z", - "created_at": "2016-08-15T07:55:42.119Z" - }, - { - "id": 4, - "ticket_id": 3, - "from": "Bob Smith", - "to": "", - "cc": "", - "subject": "some subject", - "body": "huhuhuu
huhuhuu
huhuhuu

", - "content_type": "text/html", - "type": "note", - "internal": false, - ... - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - -Show -==== - -Required permission: - -* ticket.agent (access to related ticket) -* ticket.customer (access to related ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) - -Request:: - - GET /api/v1/ticket_articles/{id} - - -Response:: - - Status: 200 Ok - - { - "id": 3, - "ticket_id": 3, - "from": "Bob Smith", - "to": "", - "cc": "", - "subject": "some subject", - "body": "huhuhuu
huhuhuu
huhuhuu

", - "content_type": "text/html", - "type": "note", - "internal": false, - "attachments": [ - { - "id": 123, - "filename": "some_file1.txt", - "preferences": { - "Mime-Type": "text/plain" - } - }, - { - "id": 124, - "filename": "some_file2.txt", - "preferences": { - "Mime-Type": "text/plain" - } - } - ], - ... - "created_at": "2016-10-19T10:07:12.011Z", - "updated_at": "2017-01-18T12:45:53.420Z" - } - - -Create -====== - -Required permission: - -* ticket.agent (access to related ticket) -* ticket.customer (access to related ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) - -Request:: - - POST /api/v1/ticket_articles - - { - "ticket_id": 3, - "to": "", - "cc": "", - "subject": "some subject", - "body": "huhuhuu
huhuhuu
huhuhuu

", - "content_type": "text/html", - "type": "note", - "internal": false, - "time_unit": "12" - } - -Response:: - - Status: 201 Created - - { - "id": 3, - "ticket_id": 3, - "from": "Bob Smith", - "to": "", - "cc": "", - "subject": "some subject", - "body": "huhuhuu
huhuhuu
huhuhuu

", - "content_type": "text/html", - "type": "note", - "internal": false, - "time_unit": "12.0" - ... - "created_at": "2016-10-19T10:07:12.011Z", - "updated_at": "2017-01-18T12:45:53.420Z" - } - - -If you want to include attachments of articles, the payload looks like: - -Request:: - - POST /api/v1/ticket_articles - - { - "ticket_id": 3, - "to": "", - "cc": "", - "subject": "some subject", - "body": "huhuhuu
huhuhuu
huhuhuu

", - "content_type": "text/html", - "type": "note", - "internal": false, - "time_unit": "12", - "attachments": [ - { - "filename": "some_file1.txt", - "data": "content in base64", - "mime-type": "text/plain" - }, - { - "filename": "some_file2.txt", - "data": "content in base64", - "mime-type": "text/plain" - } - ] - } - -Response:: - - Status: 201 Created - - { - "id": 3, - "from": "Bob Smith", - "to": "", - "cc": "", - "subject": "some subject", - "body": "huhuhuu
huhuhuu
huhuhuu

", - "content_type": "text/html", - "type": "note", - "internal": false, - "time_unit": "12.0" - "attachments": [ - { - "id": 123, - "filename": "some_file1.txt", - "preferences": { - "Mime-Type": "text/plain" - } - }, - { - "id": 124, - "filename": "some_file2.txt", - "preferences": { - "Mime-Type": "text/plain" - } - } - ], - ... - "created_at": "2016-10-19T10:07:12.011Z", - "updated_at": "2017-01-18T12:45:53.420Z" - } - -To download attachments you need to call "GET /api/v1/ticket_attachment/#{ticket_id}/#{article_id}/#{id}". - - -If you want to add inline images, just use data URIs in HTML markup: - -Request:: - - POST /api/v1/ticket_articles - - { - "ticket_id": 3, - "to": "", - "cc": "", - "subject": "some subject", - "body": "some message witn inline image " - "content_type": "text/html", - "type": "note", - "internal": false, - "time_unit": "12" - } - -Response:: - - Status: 201 Created - - { - "id": 3, - "ticket_id": 3, - "from": "Bob Smith", - "to": "", - "cc": "", - "subject": "some subject", - "body": "huhuhuu
huhuhuu
huhuhuu

", - "content_type": "text/html", - "type": "note", - "internal": false, - "time_unit": "12.0" - "attachments": [ - { - "id": 123, - "filename": "44.262871107@zammad.example.com", - "preferences": { - "Mime-Type": "image/jpeg", - "Content-ID": "44.262871107@zammad.example.com", - "Content-Disposition": "inline" - } - } - ], - ... - "created_at": "2016-10-19T10:07:12.011Z", - "updated_at": "2017-01-18T12:45:53.420Z" - } - -To download attachments you need to call "GET /api/v1/ticket_attachment/#{ticket_id}/#{article_id}/#{id}". - -If you want to create a phone ticket on behalf for a specific customer, use origin_by_id: - -Required permission: - -* ticket.agent (access to related ticket) - -Request:: - - POST /api/v1/ticket_articles - - { - "ticket_id": 3, - "origin_by_id": 5, - "to": "", - "cc": "", - "subject": "some subject", - "body": "some message witn inline image " - "content_type": "text/html", - "sender": "Customer", - "type": "phone", - "internal": false, - "time_unit": "12" - } diff --git a/api-ticket-priority.rst b/api-ticket-priority.rst deleted file mode 100644 index f657c93b..00000000 --- a/api-ticket-priority.rst +++ /dev/null @@ -1,149 +0,0 @@ -Ticket Priority -*************** - -List -==== - -Required permission: - -* admin.object (can read all ticket states) -* ticket.agent (can read all ticket states) -* ticket.customer (can read all ticket states) - -Request:: - - GET /api/v1/ticket_priorities - - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "name": "Ticket Priority 1", - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "name": "Ticket Priority 2", - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - - -Show -==== - -Required permission: - -* admin.object (can read all ticket states) -* ticket.agent (can read all ticket states) -* ticket.customer (can read all ticket states) - -Request:: - - GET /api/v1/ticket_priorities/{id} - -Response:: - - Status: 200 Ok - - { - "id": 123, - "name": "Ticket Priority 1", - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Create -====== - -Required permission: - -* admin.object - -Request:: - - POST /api/v1/ticket_priorities - - { - "name": "Ticket Priority 1", - "active": true, - "note": "some note" - } - - -Response:: - - Status: 201 Created - - { - "id": 123, - "name": "Ticket Priority 1", - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - -Update -====== - -Required permission: - -* admin.object - -Request:: - - PUT /api/v1/ticket_priorities/{id} - - { - "id": 123, - "name": "Ticket Priority 1", - "active": true, - "note": "some note" - } - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "name": "Ticket Priority 1", - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Delete -====== - -Required permission: - -* admin.object (only if no references in history tables and tickets exist) - -Request:: - - DELETE /api/v1/ticket_priorities/{id} - - -Response:: - - Status: 200 Ok - - {} diff --git a/api-ticket-state.rst b/api-ticket-state.rst deleted file mode 100644 index 8f9499f5..00000000 --- a/api-ticket-state.rst +++ /dev/null @@ -1,169 +0,0 @@ -Ticket State -************ - -List -==== - -Required permission: - -* admin.object (can read all ticket states) -* ticket.agent (can read all ticket states) -* ticket.customer (can read all ticket states) - -Request:: - - GET /api/v1/ticket_states - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "name": "Ticket State 1", - "state_type_id": 1, - "next_state_id": null, - "ignore_escalation": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "name": "Ticket State 2", - "state_type_id": 2, - "next_state_id": 4, - "ignore_escalation": false, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - -Show -==== - -Required permission: - -* admin.object (can read all ticket states) -* ticket.agent (can read all ticket states) -* ticket.customer (can read all ticket states) - -Request:: - - GET /api/v1/ticket_states/{id} - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "name": "Ticket State 1", - "state_type_id": 1, - "next_state_id": null, - "ignore_escalation": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Create -====== - -Required permission: - -* admin.object - -Request:: - - POST /api/v1/ticket_states - - { - "name": "Ticket State 1", - "state_type_id": 1, - "next_state_id": null, - "ignore_escalation": true, - "active": true, - "note": "some note" - } - - -Response:: - - Status: 201 Created - - { - "id": 123, - "name": "Ticket State 1", - "state_type_id": 1, - "next_state_id": null, - "ignore_escalation": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Update -====== - -Required permission: - -* admin.object - -Request:: - - PUT /api/v1/ticket_states/{id} - - { - "id": 123, - "name": "Ticket State 1", - "state_type_id": 1, - "next_state_id": null, - "ignore_escalation": true, - "active": true, - "note": "some note" - } - -Response:: - - Status: 200 Ok - - { - "id": 123, - "name": "Ticket State 1", - "state_type_id": 1, - "next_state_id": null, - "ignore_escalation": true, - "active": true, - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Delete -====== - -Required permission: - -* admin.object (only if no references in history tables and tickets exist) - -Request:: - - DELETE /api/v1/ticket_states/{id} - - -Response:: - - Status: 200 Ok - - {} diff --git a/api-ticket.rst b/api-ticket.rst deleted file mode 100644 index 4ea5c4a8..00000000 --- a/api-ticket.rst +++ /dev/null @@ -1,336 +0,0 @@ -Ticket -****** - -List -==== - -Required permission: - -* ticket.agent (access to all ticket in allocated groups) -* ticket.customer (access to all ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) - -Request:: - - GET /api/v1/tickets - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "title": "Help me!", - "group_id": 1, - "state_id": 1, - "priority_id": 2, - "customer_id": 2, - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "title": "Just want to ask for support", - "state_id": 2, - "priority_id": 2, - "customer_id": 2, - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - -Search -====== - -Required permission: - -* ticket.agent (access to all ticket in allocated groups) -* ticket.customer (access to all ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) - -Request:: - - GET /api/v1/tickets/search?query=what&limit=10 - -Note: As of Zammad 2.6 parameters (sort_by=some_row and order_by=asc or desc) can also be used for sorting. - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "title": "Help me!", - "group_id": 1, - "state_id": 1, - "priority_id": 2, - "customer_id": 2, - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "title": "Just want to ask for support", - "state_id": 2, - "priority_id": 2, - "customer_id": 2, - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - - -Show -==== - -Required permission: - -* ticket.agent (access to all ticket in allocated groups) -* ticket.customer (access to all ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) - -Request:: - - GET /api/v1/tickets/{id} - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "title": "Help me!", - "group_id": 1, - "state_id": 1, - "priority_id": 2, - "customer_id": 2, - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -Create -====== - -Required permission: - -* ticket.agent (create in all allocated groups) -* ticket.customer - -Request:: - - POST /api/v1/tickets - - { - "title": "Help me!", - "group": "Users", - "customer": "email_of_existing_customer@example.com", - "article": { - "subject": "some subject", - "body": "some message", - "type": "note", - "internal": false - }, - ... - "note": "some note" - } - -Response:: - - Status: 201 Created - - { - "id": 123, - "title": "Help me!", - "group_id": 1, - "state_id": 1, - "priority_id": 2, - "customer_id": 2, - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - -For more article attributes have a look into "Ticket Article". - -If you want to include attachments of the first article, the payload looks like: - -Request:: - - POST /api/v1/tickets - - { - "title": "Help me!", - "group": "Users", - "article": { - "subject": "some subject", - "body": "some message", - "attachments": [ - { - "filename": "some_file1.txt", - "data": "content in base64", - "mime-type": "text/plain" - }, - { - "filename": "some_file2.txt", - "data": "content in base64", - "mime-type": "text/plain" - } - ] - }, - ... - "note": "some note" - } - -If you want to add inline images, just use data URIs in HTML markup: - -Request:: - - POST /api/v1/tickets - - { - "title": "Help me!", - "group": "Users", - "article": { - "content_type": "text/html", - "subject": "some subject", - "body": "some message witn inline image " - }, - ... - "note": "some note" - } - -If you want to use or create an customer by email address at ticket creation, you can do with "guess:customer@example.com" in the customer_id attribute: - -Request:: - - POST /api/v1/tickets - - { - "title": "Help me!", - "group": "Users", - "customer_id": "guess:customer@example.com", - ... - "note": "some note" - } - -Update -====== - -Required permission: - -* ticket.agent (access to all ticket in allocated groups) -* ticket.customer (access to all ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) - -Request:: - - PUT /api/v1/tickets/{id} - - { - "id": 123, - "title": "Help me!", - "group": "Users", - "state": "open", - "priority": "3 high", - "article": { - "subject": "some subject of update", - "body": "some message of update" - }, - ... - } - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "title": "Help me!", - "group_id": 1, - "state_id": 1, - "priority_id": 2, - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - - -If you want to include attachments of the article, the payload looks like: - - -Request:: - - PUT /api/v1/tickets/{id} - - { - "id": 123, - "title": "Help me!", - "group": "Users", - "article": { - "subject": "some subject", - "body": "some message", - "attachments": [ - { - "filename": "some_file1.txt", - "data": "content in base64", - "mime-type": "text/plain" - }, - { - "filename": "some_file2.txt", - "data": "content in base64", - "mime-type": "text/plain" - } - ] - }, - ... - "note": "some note" - } - -If you want to add inline images, just use data URIs in HTML markup: - -Request:: - - PUT /api/v1/tickets/{id} - - { - "id": 123, - "title": "Help me!", - "group": "Users", - "article": { - "content_type": "text/html", - "subject": "some subject", - "body": "some message witn inline image " - }, - ... - "note": "some note" - } - -Delete -====== - -Required permission: - -* admin - -Request:: - - DELETE /api/v1/tickets/{id} - -Response:: - - Status: 200 Ok - - {} diff --git a/api-user.rst b/api-user.rst deleted file mode 100644 index 6cf03692..00000000 --- a/api-user.rst +++ /dev/null @@ -1,234 +0,0 @@ -User -**** - -me - current user -================= - -Required permission: - -* any (only valid authentication) - -Request:: - - GET /api/v1/users/me - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "firstname": "Bob", - "lastname": "Smith", - "email": "bob@smith.example.com", - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - - -List -==== - -Required permission: - -* ticket.agent or admin.user (can read all users) -* any (can only read its own user if exists) - -Request:: - - GET /api/v1/users - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "firstname": "Bob", - "lastname": "Smith", - "email": "bob@smith.example.com", - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "firstname": "Martha", - "lastname": "Braun", - "email": "marta@braun.example.com", - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - - -Search -====== - -Required permission: - -* ticket.agent or admin.user (can read all users) - -Request:: - - GET /api/v1/users/search?query=what&limit=10 - -Note: As of Zammad 2.6 parameters (sort_by=some_row and order_by=asc or desc) can also be used for sorting. - -Response:: - - Status: 200 Ok - - [ - { - "id": 123, - "firstname": "Bob", - "lastname": "Smith", - "email": "bob@smith.example.com", - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - { - "id": 124, - "firstname": "Martha", - "lastname": "Braun", - "email": "marta@braun.example.com", - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - }, - ] - -Show -==== - -Required permission: - -* ticket.agent or admin.user (can read all users) -* customer with same organization (can read all users of same organization) -* any (can only read it's own user if exists) - -Request:: - - GET /api/v1/users/{id} - -Response:: - - Status: 200 Ok - - { - "id": 123, - "firstname": "Bob", - "lastname": "Smith", - "email": "bob@smith.example.com", - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - -Create -====== - -Required permission: - -* admin.user -* ticket.agent (can not set roles/role_ids and not set groups/group_ids - roles.default_at_signup roles will get assigned automatically) -* any - until user_create_account is disabled (can not set roles/role_ids and not set groups/group_ids - roles.default_at_signup roles will get assigned automatically) - -Request:: - - POST /api/v1/users - - { - "firstname": "Bob", - "lastname": "Smith", - "email": "bob@smith.example.com", - "organization": "Some Organization Name", - ... - } - - -Response:: - - Status: 201 Created - - { - "id": 123, - "firstname": "Bob", - "lastname": "Smith", - "email": "bob@smith.example.com", - "organization_id": 123, - "organization": "Some Organization Name", - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - -Update -====== - -Required permission: - -* admin.user -* ticket.agent (can only update customer accounts and not set roles/role_ids and not set groups/group_ids - already assigned attributes will not changed) - -Request:: - - PUT /api/v1/users/{id} - - { - "firstname": "Bob", - "lastname": "Smith", - "email": "bob@smith.example.com", - "organization": "Some Other Organization Name", - ... - } - - -Response:: - - Status: 200 Ok - - { - "id": 123, - "firstname": "Bob", - "lastname": "Smith", - "email": "bob@smith.example.com", - "organization_id": 124, - "organization": "Some Other Organization Name", - ... - "note": "some note", - "updated_at": "2016-08-16T07:55:42.119Z", - "created_at": "2016-08-16T07:55:42.119Z" - } - -Delete -====== - -Required permission: - -* admin.user (only if no references in history tables and tickets exist) - -Request:: - - DELETE /api/v1/users/{id} - - -Response:: - - Status: 200 Ok - - {} - diff --git a/api-user_access_token.rst b/api-user_access_token.rst deleted file mode 100644 index 7a3e769c..00000000 --- a/api-user_access_token.rst +++ /dev/null @@ -1,71 +0,0 @@ -User Access Token -****** - -List -==== - -Required permission: - -* user_preferences.access_token - -Request:: - - GET /api/v1/user_access_token - -Response:: - - Status: 200 Ok - - { - "tokens":[ - {"id":1,"label":"some user access token","preferences":{"permission":["cti.agent","ticket.agent"]},"last_used_at":null,"expires_at":null,"created_at":"2018-07-11T08:18:56.947Z"} - {"id":2,"label":"some user access token 2","preferences":{"permission":[ticket.agent"]},"last_used_at":null,"expires_at":null,"created_at":"2018-07-11T08:18:56.947Z"} - ], - "permissions":[ - {id: 1, name: "admin", note: "Admin Interface", preferences: {}, active: true,...}, - {id: 2, name: "admin.user", note: "Manage Users", preferences: {}, active: true,...}, - ... - ] - } - -Create -====== - -Required permission: - -* user_preferences.access_token - -Request:: - - POST /api/v1/user_access_token - - { - "label":"some test", - "permission":["cti.agent","ticket.agent"], - "expires_at":null - } - -Response:: - - Status: 200 Ok - - { - "name":"new_token_only_shown_once" - } - -Delete -====== - -Required permission: - -* user_preferences.access_token - -Request:: - - PUT /api/v1/user_access_token/:id - -Response:: - - Status: 200 Ok - - {} diff --git a/api/group.rst b/api/group.rst new file mode 100644 index 00000000..06a809e6 --- /dev/null +++ b/api/group.rst @@ -0,0 +1,177 @@ +Group +***** + +List +==== + +Required permission: + +* admin.group (can read all groups) + +Request:: + + GET /api/v1/groups + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "name": "Group 1", + "signature_id": 123, + "email_address_id": 123, + "assignment_timeout": 180, + "follow_up_possible": "yes", + "follow_up_assignment": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + { + "id": 124, + "name": "Group 2", + "signature_id": 123, + "email_address_id": 123, + "assignment_timeout": 180, + "follow_up_possible": "no", + "follow_up_assignment": false, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + ] + + +Show +==== + +Required permission: + +* admin.group (can read all groups) + +Request:: + + GET /api/v1/groups/{id} + +Response:: + + Status: 200 Ok + + { + "id": 123, + "name": "Group 1", + "signature_id": 123, + "email_address_id": 123, + "assignment_timeout": 180, + "follow_up_possible": "yes", + "follow_up_assignment": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + +Create +====== + +Required permission: + +* admin.group + +Request:: + + POST /api/v1/groups + + + { + "name": "Group 1", + "signature_id": 123, + "email_address_id": 123, + "assignment_timeout": 180, + "follow_up_possible": "yes", + "follow_up_assignment": true, + "active": true, + "note": "some note" + } + +Response:: + + Status: 201 Created + + { + "id": 123, + "name": "Group 1", + "signature_id": 123, + "email_address_id": 123, + "assignment_timeout": 180, + "follow_up_possible": "yes", + "follow_up_assignment": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Update +====== + +Required permission: + +* admin.group + +Request:: + + PUT /api/v1/groups/{id} + + { + "id": 123, + "name": "Group 1", + "signature_id": 123, + "email_address_id": 123, + "assignment_timeout": 180, + "follow_up_possible": "yes", + "follow_up_assignment": true, + "active": true, + "note": "some note" + } + +Response:: + + Status: 200 Ok + + { + "id": 123, + "name": "Group 1", + "signature_id": 123, + "email_address_id": 123, + "assignment_timeout": 180, + "follow_up_possible": "yes", + "follow_up_assignment": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Delete +====== + +Required permission: + +* admin.group (only if no references in history tables and tickets exist) + +Request:: + + DELETE /api/v1/groups/{id} + +Response:: + + Status: 200 Ok + + {} diff --git a/api/intro.rst b/api/intro.rst new file mode 100644 index 00000000..ea0c0ce7 --- /dev/null +++ b/api/intro.rst @@ -0,0 +1,226 @@ +Introduction +************ + +Zammad is a web based open source helpdesk/ticket system with many features +to manage customer communication via several channels like telephone, facebook, +twitter, chat and e-mails. + +This chapter describes the Zammad API v1. + +The API +======= + +Zammad provides a REST/JSON API. Its endpoints are documented with the HTTP method for the request and a partial resource:: + + GET /api/v1/users + +The full URL looks like:: + + https://your_zammad/api/v1/users + +Curly braces {} indicate values you have to supply for the URL:: + + GET /api/v1/users/{id} + + +Authentication +============== + +Zammad supports three different authentication methods for API. + + +HTTP Basic Authentication (username/password) +--------------------------------------------- + +The username/password must be provided as HTTP header in the HTTP call. The Zammad admin can enable/disable the authentication method in the admin interface. Read more about HTTP basic authentication [here](https://en.wikipedia.org/wiki/Basic_access_authentication). + +.. code-block:: sh + + $ curl -u {username}:{password} https://your_zammad/api/v1/users + + +HTTP Token Authentication (access token) +---------------------------------------- + +The access token must be provided as HTTP header in the HTTP call. Each user needs to create its own access token in the user preferences. The Zammad admin can enable/disable the authentication method in the admin interface. + +.. code-block:: sh + + $ curl -H "Authorization: Token token={your_token}" https://your_zammad/api/v1/users + + +OAuth2 (token access) +--------------------- + +The Zammad API supports OAuth2 authorization. In order to create OAuth2 tokens for an external application, the Zammad user needs to create an application in the admin interface. The access token then has to be given within the HTTP header: + +.. code-block:: sh + + $ curl -H "Authorization: Bearer {your_token}" https://your_zammad/api/v1/users + + +Request Format +============== + +Zammad uses JSON for its API, so you need to set a "Content-Type: application/json" in each HTTP call. Otherwise the response will be text/html. + +:: + + POST /api/v1/users/{id} HTTP/1.1 + Content-Type: application/json + + { + "name":"some name", + "organization_id": 123, + "note":"some note" + } + +Example CURL Requests +===================== + +.. code-block:: sh + + # Get information + $ curl -u test@zammad.com:test123 https://xxx.zammad.com/api/v1/tickets/3 + + # Put information + $ curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X PUT -d '{ json: "data" }' https://xxx.zammad.com/api/v1/tickets/3 + + # Post information + $ curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{ json: "data" }' https://xxx.zammad.com/api/v1/tickets/3 + + +Example CURL Requests (for tickets and users) +============================================= + +.. code-block:: sh + + # Create a new ticket + $ curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{"title":"Help me!","group": "Users","article":{"subject":"some subject","body":"some message","type":"note","internal":false},"customer":"email_of_existing_customer@example.com","note": "some note"}' https://xxx.zammad.com/api/v1/tickets + + # Search for tickets (with contains "some message"):: + $ curl -u test@zammad.com:test123 'https://xxx.zammad.com/api/v1/tickets/search?query=some+message&limit=10&expand=true' + + # Search for tickets (for tickets with state new and open ):: + $ curl -u test@zammad.com:test123 'https://xxx.zammad.com/api/v1/tickets/search?query=state:new%20OR%20state:open&limit=10&expand=true' + + # Create a new user + curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{"firstname":"Bob","lastname":"Smith","email":"email_of_customer@example.com","roles":["Customer"],"password":"some_password"}' https://xxx.zammad.com/api/v1/users + + # Create a new user (with welcome email) + $ curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{"firstname":"Bob","lastname":"Smith","email":"email_of_customer@example.com","roles":["Customer"],"password":"some_password","invite":true}' https://xxx.zammad.com/api/v1/users + + # Search for users + $ curl -u test@zammad.com:test123 'https://xxx.zammad.com/api/v1/users/search?query=smith&limit=10&expand=true' + +.. hint:: For more search examples regarding searching, please see `this page `_ . + +Example CURL Request on behalf of a different user +================================================== + +It is possible to do a request on behalf of a different user. If you have your own application and you want to create a ticket for the customer +without the information that the api user has created this ticket then you can transfer the target user with the request to create the ticket on behalf of the customer user: + +.. code-block:: sh + + $ curl -u test@zammad.com:test123 -H "Content-Type: application/json" -H "X-On-Behalf-Of: user-login" -X POST -d '{"title":"Help me!","group": "Users","article":{"subject":"some subject","body":"some message","type":"note","internal":false},"customer":"email_of_existing_customer@example.com","note": "some note"}' https://xxx.zammad.com/api/v1/tickets + +The value of the header has to contain one of the following values: + +* user id +* user login +* user email + +The value types will be checked in a cascade and the first detected user by id, login or email will be used for the request action. + +This functionality can be used for any type of action. + +Requirements for the feature: + +* Authenticated user must have **admin.user** permissions +* Feature is available since Zammad version 2.4 + +Response Format +=============== + +If a response is successful, an HTTP status code in the 200 or 300 range will be returned. If an item has been created or updated, all new attributes will be returned (also server side generated attributes like created_at and updated_at):: + + Status: 201 Created + Content-Type:application/json; charset=utf-8 + + { + "id": 123, + "name":"some name", + "organization_id": 123, + "note":"some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Response Format (expanded) +========================== + +If you want to retrieve expanded information for a request (e. g. the organization attribute), you just need to add an ``expand=true`` to the request URL:: + + GET /api/v1/users/{id}?expand=true HTTP/1.1 + +will return the following structure, expanded by "organization":: + + Status: 200 Ok + Content-Type:application/json; charset=utf-8 + + { + "id": 123, + "name":"some name", + "organization_id": 123, + "organization": "Some Organization Name", + "note":"some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Pagination +========== + +All resources support pagination:: + + GET /api/v1/users?expand=true&page=1&per_page=5 HTTP/1.1 + +will return five records beginning with first record of all:: + + Status: 200 Ok + Content-Type:application/json; charset=utf-8 + + [ + { + "id": 1, + "name":"some name 1", + "organization_id": 123, + "organization": "Some Organization Name", + "note":"some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + { + "id": 2, + "name":"some name 2", + "organization_id": 345, + "organization": "Some Other Organization Name", + "note":"some note", + "updated_at": "2016-08-17T07:55:42.221Z", + "created_at": "2016-08-16T09:112:42.221Z" + }, + ... + ] + + +API clients +=========== + +* Ruby Client - https://github.com/zammad/zammad-api-client-ruby +* PHP Client - https://github.com/zammad/zammad-api-client-php +* .NET Client - https://github.com/Asesjix/Zammad-Client +* Android API-Client - https://github.com/KirkBushman/zammad-android + .. note:: Please note that this is a API client only, it's no "ready to use" App. diff --git a/api/notification.rst b/api/notification.rst new file mode 100644 index 00000000..39292a64 --- /dev/null +++ b/api/notification.rst @@ -0,0 +1,147 @@ +Online Notification +******************* + +List +==== + +Required permission: + +* authenticated user (content of notitifcations depends on user permissions) + +Request:: + + GET /api/v1/online_notifications + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "o_id": 628, + "object": "Ticket", + "type": "escalation", + "seen": true, + "updated_at": "2016-08-16T07:55:42.119Z", + "updated_by_id": 123, + "created_at": "2016-08-16T07:55:42.119Z", + "created_at_id": 123 + }, + { + "id": 124, + "o_id": 629, + "object": "Ticket", + "type": "update", + "seen": false, + "updated_at": "2016-08-16T07:55:47.119Z", + "updated_by_id": 123, + "created_at": "2016-08-16T07:55:47.119Z", + "created_at_id": 123 + }, + { + "id": 125, + "o_id": 630, + "object": "Ticket", + "type": "create", + "seen": false, + "updated_at": "2016-08-16T07:57:49.119Z", + "updated_by_id": 123, + "created_at": "2016-08-16T07:57:49.119Z", + "created_at_id": 123 + }, + ] + + +Show +==== + +Required permission: + +* authenticated user (content of notifications depends on user permissions) + +Request:: + + GET /api/v1/online_notifications/{id} + +Response:: + + Status: 200 Ok + + { + "id": 123, + "o_id": 628, + "object": "Ticket", + "type": "escalation", + "seen": true, + "updated_at": "2016-08-16T07:55:42.119Z", + "updated_by_id": 123, + "created_at": "2016-08-16T07:55:42.119Z", + "created_at_id": 123 + } + +Update +====== + +Required permission: + +* admin.object + +Request:: + + PUT /api/v1/online_notifications/{id} + + { + "seen": true, + } + +Response:: + + Status: 200 Ok + + { + "id": 123, + "o_id": 628, + "object": "Ticket", + "type": "escalation", + "seen": true, + "updated_at": "2016-08-16T07:55:42.119Z", + "updated_by_id": 123, + "created_at": "2016-08-16T07:55:42.119Z", + "created_at_id": 123 + } + + +Delete +====== + +Required permission: + +* authenticated user (content of notifications depends on user permissions) + +Request:: + + DELETE /api/v1/online_notifications/{id} + +Response:: + + Status: 200 Ok + + {} + +Mark all as read +================ + +Required permission: + +* authenticated user (content of notifications depends on user permissions) + +Request:: + + POST /api/v1/online_notifications/mark_all_as_read + +Response:: + + Status: 200 Ok + + {} diff --git a/api/object.rst b/api/object.rst new file mode 100644 index 00000000..15cbb416 --- /dev/null +++ b/api/object.rst @@ -0,0 +1,278 @@ +Object +****** + +List +==== + +Required permission: + +* admin (access to admin interface) + +Request:: + + GET /api/v1/object_manager_attributes + +Response:: + + Status: 200 Ok + + [ + { + "id":49, + "name":"anrede", + "display":"Anrede", + "data_type":"select", + "data_option":{ + "options":{ + "Mr":"Mr", + "Ms":"Ms", + "Company":"Company" + }, + "default":"Mr", + "null":true, + "maxlength":255, + "nulloption":true + }, + "data_option_new":{ + + }, + "editable":true, + "active":true, + "screens":{ + "create":{ + "Customer":{ + "shown":true, + "required":true + } + }, + "edit":{ + "Customer":{ + "shown":true + }, + "Agent":{ + "shown":true + } + }, + "create_middle":{ + "Agent":{ + "shown":true + } + } + }, + "to_create":false, + "to_migrate":false, + "to_delete":false, + "to_config":false, + "position":1550, + "created_by_id":3, + "updated_by_id":3, + "created_at":"2017-01-13T16:19:23.116Z", + "updated_at":"2017-01-17T11:16:13.298Z", + "object":"Ticket" + }, + ... + ] + +Show +==== + +Required permission: + +* admin (access to admin interface) + +Request:: + + GET /api/v1/object_manager_attributes/:id + +Response:: + + Status: 200 Ok + + { + "id":49, + "name":"anrede", + "display":"Anrede", + "data_type":"select", + "data_option":{ + "options":{ + "Mr":"Mr", + "Ms":"Ms", + "Company":"Company" + }, + "default":"Mr", + "null":true, + "maxlength":255, + "nulloption":true + }, + "data_option_new":{ + + }, + "editable":true, + "active":true, + "screens":{ + "create":{ + "Customer":{ + "shown":true, + "required":true + } + }, + "edit":{ + "Customer":{ + "shown":true + }, + "Agent":{ + "shown":true + } + }, + "create_middle":{ + "Agent":{ + "shown":true + } + } + }, + "to_create":false, + "to_migrate":false, + "to_delete":false, + "to_config":false, + "position":1550, + "created_by_id":3, + "updated_by_id":3, + "created_at":"2017-01-13T16:19:23.116Z", + "updated_at":"2017-01-17T11:16:13.298Z", + "object":"Ticket" + } + +Create +====== + +Required permission: + +* admin (access to admin interface) + +Request:: + + POST /api/v1/object_manager_attributes + +Response:: + + Status: 200 Ok + + { + "name":"product", + "object":"Ticket", + "display":"Produkt", + "active":true, + "data_type":"select", + "data_option":{ + "options":{ + "wert1":"anzeige1", + "wert2":"anzeige12" + } + }, + "screens":{ + "create_middle":{ + "Customer":{ + "shown":true, + "item_class":"column" + }, + "Agent":{ + "shown":true, + "item_class":"column" + } + }, + "edit":{ + "Customer":{ + "shown":true + }, + "Agent":{ + "shown":true + } + } + } + } + +Update +====== + +Required permission: + +* admin (access to admin interface) + +Request:: + + PUT /api/v1/object_manager_attributes/:id + +Response:: + + Status: 200 Ok + + { + "id":49, + "name":"anrede", + "display":"Anrede", + "data_type":"select", + "data_option":{ + "options":{ + "Mr":"Mr", + "Ms":"Ms", + "Company":"Company" + }, + "default":"Mr", + "null":true, + "maxlength":255, + "nulloption":true + }, + "data_option_new":{ + + }, + "editable":true, + "active":true, + "screens":{ + "create":{ + "Customer":{ + "shown":true, + "required":true + } + }, + "edit":{ + "Customer":{ + "shown":true + }, + "Agent":{ + "shown":true + } + }, + "create_middle":{ + "Agent":{ + "shown":true + } + } + }, + "to_create":false, + "to_migrate":false, + "to_delete":false, + "to_config":false, + "position":1550, + "created_by_id":3, + "updated_by_id":3, + "created_at":"2017-01-13T16:19:23.116Z", + "updated_at":"2017-01-17T11:16:13.298Z", + "object":"Ticket" + } + +Execute Database Migrations +=========================== + +Required permission: + +* admin (access to admin interface) + +Request:: + + POST /api/v1/object_manager_attributes_execute_migrations + +Response:: + + Status: 200 Ok + + {} diff --git a/api/organization.rst b/api/organization.rst new file mode 100644 index 00000000..a60d0f0c --- /dev/null +++ b/api/organization.rst @@ -0,0 +1,189 @@ +Organization +************ + +List +==== + +Required permission: + +* ticket.agent or admin.organization (can read all organizations) +* any (can only read its own organization if exists) + +Request:: + + GET /api/v1/organizations + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "name": "Org 1", + "shared": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + { + "id": 124, + "name": "Org 2", + "shared": false, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + ] + + +Search +====== + +Required permission: + +* ticket.agent or admin.organization (can read all organization) + +Request:: + + GET /api/v1/organizations/search?query=what&limit=10 + +Note: As of Zammad 2.6 parameters (sort_by=some_row and order_by=asc or desc) can also be used for sorting. + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "name": "Org 1", + "shared": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + { + "id": 124, + "name": "Org 2", + "shared": false, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + ] + + + +Show +==== + +Required permission: + +* ticket.agent or admin.organization (can read all organizations) +* any (can only read its own user if exists) + +Request:: + + GET /api/v1/organizations/{id} + +Response:: + + Status: 200 Ok + + { + "id": 123, + "name": "Org 1", + "shared": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + +Create +====== + +Required permission: + +* admin.organization + +Request:: + + POST /api/v1/organizations + + { + "name": "Org 1", + "shared": true, + "active": true, + "note": "some note" + } + +Response:: + + Status: 201 Created + + { + "id": 123, + "name": "Org 1", + "shared": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Update +====== + +Required permission: + +* admin.organization + +Request:: + + PUT /api/v1/organizations/{id} + + { + "id": 123, + "name": "Org 1", + "shared": true, + "active": true, + "note": "some note" + } + +Response:: + + Status: 200 Ok + + { + "id": 123, + "name": "Org 1", + "shared": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + +Delete +====== + +Required permission: + +* admin.organization (only if no references in history tables and tickets exist) + +Request:: + + DELETE /api/v1/organization/{id} + +Response:: + + Status: 200 Ok + + {} diff --git a/api/tags.rst b/api/tags.rst new file mode 100644 index 00000000..475507f7 --- /dev/null +++ b/api/tags.rst @@ -0,0 +1,193 @@ +Tags +**** + +List +==== + +Required permission: + +* ticket.agent or admin.tag + +Request:: + + GET /api/v1/tags?object=Ticket&o_id=10 + +Response:: + + Status: 200 Ok + + { + "tags": [ + "tag 1", + "tag 2", + "tag 3" + ] + } + + +Search +====== + +Required permission: + +* ticket.agent or admin.tag + +Request:: + + GET /api/v1/tag_search?term=tag + +Response:: + + Status: 200 Ok + + [ + { + "id": 7, + "value": "tag 1" + }, + { + "id": 8, + "value": "tag 2" + }, + { + "id": 9, + "value": "tag 3" + } + ] + +Add +=== + +Required permission: + +* ticket.agent or admin.tag + +Request:: + + GET /api/v1/tags/add?object=Ticket&o_id=10&item=tag+4 + +Response:: + + Status: 200 Ok + + true + +Remove +====== + +Required permission: + +* ticket.agent or admin.tag + +Request:: + + GET /api/v1/tags/remove?object=Ticket&o_id=10&item=tag+4 + +Response:: + + Status: 200 Ok + + true + +Admin - List +============ + +Required permission: + +* admin.tag + +Request:: + + GET /api/v1/tag_list + +Response:: + + Status: 200 Ok + + [ + { + "id": 7, + "name": "tag 1", + "count": 1 + }, + { + "id": 8, + "name": "tag 2", + "count": 1 + }, + { + "id": 9, + "name": "tag 3", + "count": 1 + }, + { + "id": 11, + "name": "tag 4", + "count": 0 + }, + { + "id": 6, + "name": "test", + "count": 0 + } + ] + +Admin - Create +============== + +Required permission: + +* admin.tag + +Request:: + + POST /api/v1/tag_list + + { + name: "tag 5" + } + +Response:: + + Status: 200 Ok + + {} + +Admin - Rename +============== + +Required permission: + +* admin.tag + +Request:: + + PUT /api/v1/tag_list/{id} + + { + id: 6, + name: "tag 5" + } + +Response:: + + Status: 200 Ok + + {} + +Admin - Delete +============== + +Required permission: + +* admin.tag + +Request:: + + DELETE /api/v1/tag_list/{id} + +Response:: + + Status: 200 Ok + + {} diff --git a/api/ticket-article.rst b/api/ticket-article.rst new file mode 100644 index 00000000..951f8793 --- /dev/null +++ b/api/ticket-article.rst @@ -0,0 +1,291 @@ +Ticket Article +************** + +By Ticket +========= + +Required permission: + +* ticket.agent (access to related ticket) +* ticket.customer (access to related ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) + +Request:: + + GET /api/v1/ticket_articles/by_ticket/{ticketId} + +Response:: + + Status: 200 Ok + + [ + { + "id": 3, + "ticket_id": 3, + "from": "Bob Smith", + "to": "", + "cc": "", + "subject": "some subject", + "body": "huhuhuu
huhuhuu
huhuhuu

", + "content_type": "text/html", + "type": "note", + "internal": false, + ... + "updated_at": "2016-08-15T07:55:42.119Z", + "created_at": "2016-08-15T07:55:42.119Z" + }, + { + "id": 4, + "ticket_id": 3, + "from": "Bob Smith", + "to": "", + "cc": "", + "subject": "some subject", + "body": "huhuhuu
huhuhuu
huhuhuu

", + "content_type": "text/html", + "type": "note", + "internal": false, + ... + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + ] + +Show +==== + +Required permission: + +* ticket.agent (access to related ticket) +* ticket.customer (access to related ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) + +Request:: + + GET /api/v1/ticket_articles/{id} + +Response:: + + Status: 200 Ok + + { + "id": 3, + "ticket_id": 3, + "from": "Bob Smith", + "to": "", + "cc": "", + "subject": "some subject", + "body": "huhuhuu
huhuhuu
huhuhuu

", + "content_type": "text/html", + "type": "note", + "internal": false, + "attachments": [ + { + "id": 123, + "filename": "some_file1.txt", + "preferences": { + "Mime-Type": "text/plain" + } + }, + { + "id": 124, + "filename": "some_file2.txt", + "preferences": { + "Mime-Type": "text/plain" + } + } + ], + "created_at": "2016-10-19T10:07:12.011Z", + "updated_at": "2017-01-18T12:45:53.420Z", + ... + } + + +Create +====== + +Required permission: + +* ticket.agent (access to related ticket) +* ticket.customer (access to related ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) + +Request:: + + POST /api/v1/ticket_articles + + { + "ticket_id": 3, + "to": "", + "cc": "", + "subject": "some subject", + "body": "huhuhuu
huhuhuu
huhuhuu

", + "content_type": "text/html", + "type": "note", + "internal": false, + "time_unit": "12" + } + +Response:: + + Status: 201 Created + + { + "id": 3, + "ticket_id": 3, + "from": "Bob Smith", + "to": "", + "cc": "", + "subject": "some subject", + "body": "huhuhuu
huhuhuu
huhuhuu

", + "content_type": "text/html", + "type": "note", + "internal": false, + "time_unit": "12.0" + "created_at": "2016-10-19T10:07:12.011Z", + "updated_at": "2017-01-18T12:45:53.420Z", + ... + } + + +If you want to include attachments of articles, the payload looks like: + +Request:: + + POST /api/v1/ticket_articles + + { + "ticket_id": 3, + "to": "", + "cc": "", + "subject": "some subject", + "body": "huhuhuu
huhuhuu
huhuhuu

", + "content_type": "text/html", + "type": "note", + "internal": false, + "time_unit": "12", + "attachments": [ + { + "filename": "some_file1.txt", + "data": "content in base64", + "mime-type": "text/plain" + }, + { + "filename": "some_file2.txt", + "data": "content in base64", + "mime-type": "text/plain" + } + ] + } + +Response:: + + Status: 201 Created + + { + "id": 3, + "from": "Bob Smith", + "to": "", + "cc": "", + "subject": "some subject", + "body": "huhuhuu
huhuhuu
huhuhuu

", + "content_type": "text/html", + "type": "note", + "internal": false, + "time_unit": "12.0" + "attachments": [ + { + "id": 123, + "filename": "some_file1.txt", + "preferences": { + "Mime-Type": "text/plain" + } + }, + { + "id": 124, + "filename": "some_file2.txt", + "preferences": { + "Mime-Type": "text/plain" + } + } + ], + "created_at": "2016-10-19T10:07:12.011Z", + "updated_at": "2017-01-18T12:45:53.420Z", + ... + } + +To download attachments you need to call "GET /api/v1/ticket_attachment/#{ticket_id}/#{article_id}/#{id}". + + +If you want to add inline images, just use data URIs in HTML markup: + +Request:: + + POST /api/v1/ticket_articles + + { + "ticket_id": 3, + "to": "", + "cc": "", + "subject": "some subject", + "body": "some message witn inline image " + "content_type": "text/html", + "type": "note", + "internal": false, + "time_unit": "12" + } + +Response:: + + Status: 201 Created + + { + "id": 3, + "ticket_id": 3, + "from": "Bob Smith", + "to": "", + "cc": "", + "subject": "some subject", + "body": "huhuhuu
huhuhuu
huhuhuu

", + "content_type": "text/html", + "type": "note", + "internal": false, + "time_unit": "12.0" + "attachments": [ + { + "id": 123, + "filename": "44.262871107@zammad.example.com", + "preferences": { + "Mime-Type": "image/jpeg", + "Content-ID": "44.262871107@zammad.example.com", + "Content-Disposition": "inline" + } + } + ], + "created_at": "2016-10-19T10:07:12.011Z", + "updated_at": "2017-01-18T12:45:53.420Z", + ... + } + +To download attachments you need to call "GET /api/v1/ticket_attachment/#{ticket_id}/#{article_id}/#{id}". + +If you want to create a phone ticket on behalf for a specific customer, use origin_by_id: + +Required permission: + +* ticket.agent (access to related ticket) + +Request:: + + POST /api/v1/ticket_articles + + { + "ticket_id": 3, + "origin_by_id": 5, + "to": "", + "cc": "", + "subject": "some subject", + "body": "some message witn inline image " + "content_type": "text/html", + "sender": "Customer", + "type": "phone", + "internal": false, + "time_unit": "12" + } diff --git a/api/ticket-priority.rst b/api/ticket-priority.rst new file mode 100644 index 00000000..b7dca795 --- /dev/null +++ b/api/ticket-priority.rst @@ -0,0 +1,145 @@ +Ticket Priority +*************** + +List +==== + +Required permission: + +* admin.object (can read all ticket states) +* ticket.agent (can read all ticket states) +* ticket.customer (can read all ticket states) + +Request:: + + GET /api/v1/ticket_priorities + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "name": "Ticket Priority 1", + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + { + "id": 124, + "name": "Ticket Priority 2", + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + ] + + +Show +==== + +Required permission: + +* admin.object (can read all ticket states) +* ticket.agent (can read all ticket states) +* ticket.customer (can read all ticket states) + +Request:: + + GET /api/v1/ticket_priorities/{id} + +Response:: + + Status: 200 Ok + + { + "id": 123, + "name": "Ticket Priority 1", + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Create +====== + +Required permission: + +* admin.object + +Request:: + + POST /api/v1/ticket_priorities + + { + "name": "Ticket Priority 1", + "active": true, + "note": "some note" + } + +Response:: + + Status: 201 Created + + { + "id": 123, + "name": "Ticket Priority 1", + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + +Update +====== + +Required permission: + +* admin.object + +Request:: + + PUT /api/v1/ticket_priorities/{id} + + { + "id": 123, + "name": "Ticket Priority 1", + "active": true, + "note": "some note" + } + +Response:: + + Status: 200 Ok + + { + "id": 123, + "name": "Ticket Priority 1", + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Delete +====== + +Required permission: + +* admin.object (only if no references in history tables and tickets exist) + +Request:: + + DELETE /api/v1/ticket_priorities/{id} + +Response:: + + Status: 200 Ok + + {} diff --git a/api/ticket-state.rst b/api/ticket-state.rst new file mode 100644 index 00000000..c4667f45 --- /dev/null +++ b/api/ticket-state.rst @@ -0,0 +1,167 @@ +Ticket State +************ + +List +==== + +Required permission: + +* admin.object (can read all ticket states) +* ticket.agent (can read all ticket states) +* ticket.customer (can read all ticket states) + +Request:: + + GET /api/v1/ticket_states + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "name": "Ticket State 1", + "state_type_id": 1, + "next_state_id": null, + "ignore_escalation": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + { + "id": 124, + "name": "Ticket State 2", + "state_type_id": 2, + "next_state_id": 4, + "ignore_escalation": false, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + }, + ] + +Show +==== + +Required permission: + +* admin.object (can read all ticket states) +* ticket.agent (can read all ticket states) +* ticket.customer (can read all ticket states) + +Request:: + + GET /api/v1/ticket_states/{id} + +Response:: + + Status: 200 Ok + + { + "id": 123, + "name": "Ticket State 1", + "state_type_id": 1, + "next_state_id": null, + "ignore_escalation": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Create +====== + +Required permission: + +* admin.object + +Request:: + + POST /api/v1/ticket_states + + { + "name": "Ticket State 1", + "state_type_id": 1, + "next_state_id": null, + "ignore_escalation": true, + "active": true, + "note": "some note" + } + + +Response:: + + Status: 201 Created + + { + "id": 123, + "name": "Ticket State 1", + "state_type_id": 1, + "next_state_id": null, + "ignore_escalation": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Update +====== + +Required permission: + +* admin.object + +Request:: + + PUT /api/v1/ticket_states/{id} + + { + "id": 123, + "name": "Ticket State 1", + "state_type_id": 1, + "next_state_id": null, + "ignore_escalation": true, + "active": true, + "note": "some note" + } + +Response:: + + Status: 200 Ok + + { + "id": 123, + "name": "Ticket State 1", + "state_type_id": 1, + "next_state_id": null, + "ignore_escalation": true, + "active": true, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + + +Delete +====== + +Required permission: + +* admin.object (only if no references in history tables and tickets exist) + +Request:: + + DELETE /api/v1/ticket_states/{id} + +Response:: + + Status: 200 Ok + + {} diff --git a/api/ticket.rst b/api/ticket.rst new file mode 100644 index 00000000..aec688b7 --- /dev/null +++ b/api/ticket.rst @@ -0,0 +1,332 @@ +Ticket +****** + +List +==== + +Required permission: + +* ticket.agent (access to all ticket in allocated groups) +* ticket.customer (access to all ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) + +Request:: + + GET /api/v1/tickets + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "title": "Help me!", + "group_id": 1, + "state_id": 1, + "priority_id": 2, + "customer_id": 2, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + }, + { + "id": 124, + "title": "Just want to ask for support", + "state_id": 2, + "priority_id": 2, + "customer_id": 2, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + }, + ] + +Search +====== + +Required permission: + +* ticket.agent (access to all ticket in allocated groups) +* ticket.customer (access to all ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) + +Request:: + + GET /api/v1/tickets/search?query=what&limit=10 + +Note: As of Zammad 2.6 parameters (sort_by=some_row and order_by=asc or desc) can also be used for sorting. + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "title": "Help me!", + "group_id": 1, + "state_id": 1, + "priority_id": 2, + "customer_id": 2, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + }, + { + "id": 124, + "title": "Just want to ask for support", + "state_id": 2, + "priority_id": 2, + "customer_id": 2, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + }, + ] + + +Show +==== + +Required permission: + +* ticket.agent (access to all ticket in allocated groups) +* ticket.customer (access to all ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) + +Request:: + + GET /api/v1/tickets/{id} + +Response:: + + Status: 200 Ok + + { + "id": 123, + "title": "Help me!", + "group_id": 1, + "state_id": 1, + "priority_id": 2, + "customer_id": 2, + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + } + + +Create +====== + +Required permission: + +* ticket.agent (create in all allocated groups) +* ticket.customer + +Request:: + + POST /api/v1/tickets + + { + "title": "Help me!", + "group": "Users", + "customer": "email_of_existing_customer@example.com", + "article": { + "subject": "some subject", + "body": "some message", + "type": "note", + "internal": false + }, + "note": "some note", + ... + } + +Response:: + + Status: 201 Created + + { + "id": 123, + "title": "Help me!", + "group_id": 1, + "state_id": 1, + "priority_id": 2, + "customer_id": 2, + ... + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + +For more article attributes have a look into "Ticket Article". + +If you want to include attachments of the first article, the payload looks like: + +Request:: + + POST /api/v1/tickets + + { + "title": "Help me!", + "group": "Users", + "article": { + "subject": "some subject", + "body": "some message", + "attachments": [ + { + "filename": "some_file1.txt", + "data": "content in base64", + "mime-type": "text/plain" + }, + { + "filename": "some_file2.txt", + "data": "content in base64", + "mime-type": "text/plain" + } + ] + }, + "note": "some note", + ... + } + +If you want to add inline images, just use data URIs in HTML markup: + +Request:: + + POST /api/v1/tickets + + { + "title": "Help me!", + "group": "Users", + "article": { + "content_type": "text/html", + "subject": "some subject", + "body": "some message witn inline image " + }, + "note": "some note", + ... + } + +If you want to use or create an customer by email address at ticket creation, you can do with "guess:customer@example.com" in the customer_id attribute: + +Request:: + + POST /api/v1/tickets + + { + "title": "Help me!", + "group": "Users", + "customer_id": "guess:customer@example.com", + "note": "some note", + ... + } + +Update +====== + +Required permission: + +* ticket.agent (access to all ticket in allocated groups) +* ticket.customer (access to all ticket with customer_id ** current_user.id || organization_id ** current_user.organization_id) + +Request:: + + PUT /api/v1/tickets/{id} + + { + "id": 123, + "title": "Help me!", + "group": "Users", + "state": "open", + "priority": "3 high", + "article": { + "subject": "some subject of update", + "body": "some message of update" + }, + ... + } + +Response:: + + Status: 200 Ok + + { + "id": 123, + "title": "Help me!", + "group_id": 1, + "state_id": 1, + "priority_id": 2, + ... + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z" + } + +If you want to include attachments of the article, the payload looks like: + +Request:: + + PUT /api/v1/tickets/{id} + + { + "id": 123, + "title": "Help me!", + "group": "Users", + "article": { + "subject": "some subject", + "body": "some message", + "attachments": [ + { + "filename": "some_file1.txt", + "data": "content in base64", + "mime-type": "text/plain" + }, + { + "filename": "some_file2.txt", + "data": "content in base64", + "mime-type": "text/plain" + } + ] + }, + "note": "some note", + ... + } + +If you want to add inline images, just use data URIs in HTML markup: + +Request:: + + PUT /api/v1/tickets/{id} + + { + "id": 123, + "title": "Help me!", + "group": "Users", + "article": { + "content_type": "text/html", + "subject": "some subject", + "body": "some message witn inline image " + }, + "note": "some note", + ... + } + +Delete +====== + +Required permission: + +* admin + +Request:: + + DELETE /api/v1/tickets/{id} + +Response:: + + Status: 200 Ok + + {} diff --git a/api/user-access-token.rst b/api/user-access-token.rst new file mode 100644 index 00000000..537568e4 --- /dev/null +++ b/api/user-access-token.rst @@ -0,0 +1,103 @@ +User Access Token +***************** + +List +==== + +Required permission: + +* user_preferences.access_token + +Request:: + + GET /api/v1/user_access_token + +Response:: + + Status: 200 Ok + + { + "tokens": [ + { + "id": 1, + "label": "some user access token", + "preferences": { + "permission": ["cti.agent","ticket.agent"] + }, + "last_used_at": null, + "expires_at": null, + "created_at": "2018-07-11T08:18:56.947Z" + }, + { + "id": 2, + "label": "some user access token 2", + "preferences": { + "permission": ["ticket.agent"] + }, + "last_used_at": null, + "expires_at": null, + "created_at": "2018-07-11T08:18:56.947Z" + } + ], + "permissions": [ + { + id: 1, + name: "admin", + note: "Admin Interface", + preferences: {}, + active: true, + ... + }, + { + id: 2, + name: "admin.user", + note: "Manage Users", + preferences: {}, + active: true, + ... + }, + ... + ] + } + +Create +====== + +Required permission: + +* user_preferences.access_token + +Request:: + + POST /api/v1/user_access_token + + { + "label": "some test", + "permission": ["cti.agent","ticket.agent"], + "expires_at": null + } + +Response:: + + Status: 200 Ok + + { + "name": "new_token_only_shown_once" + } + +Delete +====== + +Required permission: + +* user_preferences.access_token + +Request:: + + PUT /api/v1/user_access_token/:id + +Response:: + + Status: 200 Ok + + {} diff --git a/api/user.rst b/api/user.rst new file mode 100644 index 00000000..3c105599 --- /dev/null +++ b/api/user.rst @@ -0,0 +1,229 @@ +User +**** + +me - current user +================= + +Required permission: + +* any (only valid authentication) + +Request:: + + GET /api/v1/users/me + +Response:: + + Status: 200 Ok + + { + "id": 123, + "firstname": "Bob", + "lastname": "Smith", + "email": "bob@smith.example.com", + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + } + + +List +==== + +Required permission: + +* ticket.agent or admin.user (can read all users) +* any (can only read its own user if exists) + +Request:: + + GET /api/v1/users + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "firstname": "Bob", + "lastname": "Smith", + "email": "bob@smith.example.com", + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + }, + { + "id": 124, + "firstname": "Martha", + "lastname": "Braun", + "email": "marta@braun.example.com", + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + }, + ] + + +Search +====== + +Required permission: + +* ticket.agent or admin.user (can read all users) + +Request:: + + GET /api/v1/users/search?query=what&limit=10 + +Note: As of Zammad 2.6 parameters (sort_by=some_row and order_by=asc or desc) can also be used for sorting. + +Response:: + + Status: 200 Ok + + [ + { + "id": 123, + "firstname": "Bob", + "lastname": "Smith", + "email": "bob@smith.example.com", + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + }, + { + "id": 124, + "firstname": "Martha", + "lastname": "Braun", + "email": "marta@braun.example.com", + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + }, + ] + +Show +==== + +Required permission: + +* ticket.agent or admin.user (can read all users) +* customer with same organization (can read all users of same organization) +* any (can only read it's own user if exists) + +Request:: + + GET /api/v1/users/{id} + +Response:: + + Status: 200 Ok + + { + "id": 123, + "firstname": "Bob", + "lastname": "Smith", + "email": "bob@smith.example.com", + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + } + +Create +====== + +Required permission: + +* admin.user +* ticket.agent (can not set roles/role_ids and not set groups/group_ids - roles.default_at_signup roles will get assigned automatically) +* any - until user_create_account is disabled (can not set roles/role_ids and not set groups/group_ids - roles.default_at_signup roles will get assigned automatically) + +Request:: + + POST /api/v1/users + + { + "firstname": "Bob", + "lastname": "Smith", + "email": "bob@smith.example.com", + "organization": "Some Organization Name", + ... + } + +Response:: + + Status: 201 Created + + { + "id": 123, + "firstname": "Bob", + "lastname": "Smith", + "email": "bob@smith.example.com", + "organization_id": 123, + "organization": "Some Organization Name", + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + } + +Update +====== + +Required permission: + +* admin.user +* ticket.agent (can only update customer accounts and not set roles/role_ids and not set groups/group_ids - already assigned attributes will not changed) + +Request:: + + PUT /api/v1/users/{id} + + { + "firstname": "Bob", + "lastname": "Smith", + "email": "bob@smith.example.com", + "organization": "Some Other Organization Name", + ... + } + +Response:: + + Status: 200 Ok + + { + "id": 123, + "firstname": "Bob", + "lastname": "Smith", + "email": "bob@smith.example.com", + "organization_id": 124, + "organization": "Some Other Organization Name", + "note": "some note", + "updated_at": "2016-08-16T07:55:42.119Z", + "created_at": "2016-08-16T07:55:42.119Z", + ... + } + +Delete +====== + +Required permission: + +* admin.user (only if no references in history tables and tickets exist) + +Request:: + + DELETE /api/v1/users/{id} + +Response:: + + Status: 200 Ok + + {} diff --git a/appendix-repo-file.rst b/appendix-repo-file.rst deleted file mode 100644 index 33a0057d..00000000 --- a/appendix-repo-file.rst +++ /dev/null @@ -1,95 +0,0 @@ -Package Repo Files -****************** - -Recently (24 Jul 2017) our packaging service provider (packager.io: http://www.packager.io/) improved its package distribution which makes it necessary that you update your Zammad repo file (e. g. /etc/apt/sources.list.d/zammad.list or /etc/yum.repos.d/zammad.repo) on your operating system. - -If you're using an old repo file, you will not be able to update Zammad. - -For more background information see: https://blog.packager.io/posts/24-change-of-repository-urls - -Please use the following commands to update your Zammad repo file: - - -CentOS 7 -============= - -:: - - sudo yum -y install epel-release wget - sudo wget -O /etc/yum.repos.d/zammad.repo https://dl.packager.io/srv/zammad/zammad/stable/installer/el/7.repo - sudo yum install zammad - - -Debian 8 -============= - -:: - - sudo apt-get install wget - wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - - sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/8.repo - sudo apt-get update - sudo apt-get install zammad - - -Debian 9 -============= - -:: - - sudo apt-get install wget - wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - - sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/9.repo - sudo apt-get update - sudo apt-get install zammad - - -Ubuntu 16.04 -============= - -:: - - sudo apt-get install wget - wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - - sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/ubuntu/16.04.repo - sudo apt-get update - sudo apt-get install zammad - - -Ubuntu 18.04 -============= - -:: - - sudo apt-get install wget - wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - - sudo wget -O /etc/apt/sources.list.d/zammad.list \ - https://dl.packager.io/srv/zammad/zammad/stable/installer/ubuntu/18.04.repo - sudo apt-get update - sudo apt-get install zammad - - -SLES 12 -============= - -:: - - sudo zypper install wget - sudo wget -O /etc/zypp/repos.d/zammad.repo https://dl.packager.io/srv/zammad/zammad/stable/installer/sles/12.repo - sudo zypper install zammad - - -Note -============= -If you're using an old repo file, you will get error messages like these: - -:: - - E: Failed to fetch https://deb.packager.io/gh/zammad/zammad/dists/xenial/stable/binary-amd64/Packages Writing more data than expected (7831 > 1153) - E: Some index files failed to download. They have been ignored, or old ones used instead. - -:: - - Paket zammad-1.5.0-1500965473.2be861e2.centos7.x86_64.rpm not signed - - diff --git a/appendix-backup-and-restore.rst b/appendix/backup-and-restore.rst similarity index 58% rename from appendix-backup-and-restore.rst rename to appendix/backup-and-restore.rst index 1e0c5654..0922297c 100644 --- a/appendix-backup-and-restore.rst +++ b/appendix/backup-and-restore.rst @@ -1,12 +1,10 @@ -.. _backup-and-restore: - Backup and Restore ****************** Zammad contains simple backup & restore scripts that can be executed via command line or cron job. You can find the scripts in the ``/opt/zammad/contrib/backup`` directory. -.. Warning:: You'll need to rename the config file for the backup before you can use this script! +.. warning:: You'll need to rename the config file for the backup before you can use this script! Configuration @@ -16,24 +14,29 @@ Configuration * Configure backup path in ``/opt/zammad/contrib/backup/config`` if you want. The default backup path is ``/var/tmp/zammad_backup`` (needs to be created!) * If needed, you can also adjust the variable ``HOLD_DAYS`` to any value you need. Default value here is 10 backups before the oldest backup is deleted. -.. Note:: Please note that the Backup script always creates a Full-Dump of ``/opt/zammad`` and a Full-Dump of your database. If your Zammad installation - is rather big, you might need to ensure you have enough space. +.. note:: Please note that the Backup script always creates a Full-Dump of ``/opt/zammad`` and a Full-Dump of your database. If your Zammad installation + is rather big, you might need to ensure you have enough space. Create Backup ============= Creating a Backup is done very easy, you can just call the following to backup your Zammad-Instance. -You can also run this as a cronjob to have a regular backup. -:: +You can also run this as a cronjob to have a regular backup: + +.. code-block:: sh + + $ cd /opt/zammad/contrib/backup + $ ./zammad_backup.sh - cd /opt/zammad/contrib/backup - ./zammad_backup.sh +.. note:: Please note that you should run the cronjob as User ``zammad`` (ensure this user can write to the backup-directory). If you're using the root user, you might want to consider the following issues `"Permission issue for Backup" `_ and `"Backup script asks for password" `_. -.. Note:: Please note that you should run the cronjob as User ``zammad`` (ensure this user can write to the backup-directory). If you're using the root user, you might want to consider the following issues `"Permission issue for Backup" `_ and `"Backup script asks for password" `_. +.. warning:: If you plan on migrating your Zammad-Installation to another system, ensure to stop Zammad before creating a Backup. Other wise, data might change! + You can do this with: -.. Warning:: If you plan on migrating your Zammad-Installation to another system, ensure to stop Zammad before creating a Backup. Other wise, data might change! - You can do this with: ``systemctl disable zammad && systemctl stop zammad`` + .. code-block:: sh + + $ systemctl disable zammad && systemctl stop zammad Migrating from another Zammad-Host @@ -53,29 +56,31 @@ If above requirenments are met, you can continue with restoring. Restore everything ================== -Change into the folder of Zammads backup-script. -:: +.. code-block:: sh - cd /opt/zammad/contrib/backup + # Change into the folder of Zammads backup-script: + $ cd /opt/zammad/contrib/backup With menu for choosing backup date ---------------------------------- -When you call the restore script without further arguments, Zammad will show you a list of available backups. -:: - ./zammad_restore.sh +.. code-block:: sh + + # When called without arguments, Zammad will show you a list of available backups. + $ ./zammad_restore.sh With command line argument for backup date ------------------------------------------ -.. Warning:: Only use the following option if you know what you're doing! The following command will overwrite existing data without further prompts! +.. warning:: Only use the following option if you know what you're doing! The following command will overwrite existing data without further prompts! -If you already know what backup you want to restore, you can just give the backup script the timestamp (from the filename) as argument, it will go straight to restoration. -:: +.. code-block:: sh - ./zammad_restore.sh 20170507121848 + # When called with a timestamp argument (matching the backup's filename), + # Zammad will proceed immediately to restoring the specified backup. + $ ./zammad_restore.sh 20170507121848 What to do after restoration has been completed @@ -84,51 +89,53 @@ What to do after restoration has been completed When migrated from a self hosted Zammad system ---------------------------------------------- -.. Note:: This step is only needed, if one of the following points is met: +.. note:: This step is only needed, if one of the following points is met: - * The source and destination Zammad-Version are not the same - * The Zammad-installation is not a source code installation - * The Zammad-Backup is not an Export from Hosted-Setup - - If no points affect you, just continue with `the things you need to do after migration on every system <#things-you-need-to-do-after-migration-on-every-system>`_. + * The source and destination Zammad-Version are not the same + * The Zammad-installation is not a source code installation + * The Zammad-Backup is not an Export from Hosted-Setup + + If no points affect you, just continue with `the things you need to do after migration on every system <#things-you-need-to-do-after-migration-on-every-system>`_. If your versions differ, it might happen, that your Zammad-Service will not start cleanly. You can update your installation -If you receive the following, you can workaround your problem with reinstalling Zammad (example on Debian, other Operating systems might differ) -:: - root@zammad:/# apt-get update && apt install zammad - Reading package lists... Done - Building dependency tree - Reading state information... Done - zammad is already the newest version (x.x.x-xxxxxx.xxxxxx.stretch). - 0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded. +If you receive the following, you can workaround your problem with reinstalling Zammad (example on Debian, other Operating systems might differ) :: + + root@zammad:/# apt-get update && apt install zammad + Reading package lists... Done + Building dependency tree + Reading state information... Done + zammad is already the newest version (x.x.x-xxxxxx.xxxxxx.stretch). + 0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded. The following will uninstall and install Zammad without resolving dependencies: **Debian, Ubuntu** -:: - dpkg -r --force-depends zammad - apt install zammad +.. code-block:: sh + + $ dpkg -r --force-depends zammad + $ apt install zammad **openSuSe** -:: - zypper remove -R zammad - zypper install zammad +.. code-block:: sh + + $ zypper remove -R zammad + $ zypper install zammad Things you need to do after migration on every system ----------------------------------------------------- -.. Note:: This does not apply to Docker images, as the following settings should be applied upon every start. +.. note:: This does not apply to Docker images, as the following settings should be applied upon every start. -.. Warning:: For Zammad-Versions **2.9 and earlier**, please run a change owner on your Zammad folder. - Default-Installations should be fine with ``chown -R zammad:zammad /opt/zammad/`` (Source code installations might differ). - Please restart Zammad after the change-owner command ``systemctl restart zammad``. +.. warning:: For Zammad-Versions **2.9 and earlier**, please run a change owner on your Zammad folder. + Default-Installations should be fine with ``chown -R zammad:zammad /opt/zammad/`` (Source code installations might differ). + Please restart Zammad after the change-owner command ``systemctl restart zammad``. Before you can use Zammad and all it's features, you'll need to ensure your Searchindex is up and running. If you didn't install elasticsearch yet, now's a good time. If you already did, ensure to configure the ES-URL (if migrated) and also run a reindex. -You can find further information on how to do that on the following page: :ref:`install_elasticsearch`. +You can find further information on how to do that on the following page: :doc:`/install/elasticsearch`. diff --git a/appendix-configure-env-vars.rst b/appendix/configure-env-vars.rst similarity index 62% rename from appendix-configure-env-vars.rst rename to appendix/configure-env-vars.rst index 0ecdb923..7d75c8f2 100644 --- a/appendix-configure-env-vars.rst +++ b/appendix/configure-env-vars.rst @@ -6,10 +6,10 @@ If you're using the DEB or RPM packages you can change Zammads environment varia Configure IP ============ -:: +.. code-block:: sh - zammad config:set ZAMMAD_BIND_IP=0.0.0.0 - systemctl restart zammad + $ zammad config:set ZAMMAD_BIND_IP=0.0.0.0 + $ systemctl restart zammad Configure ports @@ -17,50 +17,50 @@ Configure ports Please note that you also have to reconfigure Nginx when changing the ports! -:: +.. code-block:: sh - zammad config:set ZAMMAD_RAILS_PORT=3000 - zammad config:set ZAMMAD_WEBSOCKET_PORT=6042 - systemctl restart zammad + $ zammad config:set ZAMMAD_RAILS_PORT=3000 + $ zammad config:set ZAMMAD_WEBSOCKET_PORT=6042 + $ systemctl restart zammad Application Servers =================== -Per default one application server will get started. If you have more http requests (user sessions) you need to increase the amount of your application server. The typical problem is long waiting times in the web interface for opening or editing tickets. +Per default one application server will get started. If you have more http requests (user sessions) you need to increase the amount of your application server. The typical problem is long waiting times in the web interface for opening or editing tickets. -:: +.. code-block:: sh - zammad config:set WEB_CONCURRENCY=3 - systemctl restart zammad + $ zammad config:set WEB_CONCURRENCY=3 + $ systemctl restart zammad Configure Restart Command ========================= -If you need to make changes (creating objects) to Zammad, it can be necessary to restart the service. +If you need to make changes (creating objects) to Zammad, it can be necessary to restart the service. This can be done manually or automatic. If you like to use the automatic way you need to set an special environment variable. Note: you might need to adjust the value for APP_RESTART_CMD if you have / need a different command to restart your Zammad on your installation. -:: +.. code-block:: sh - zammad config:set APP_RESTART_CMD="systemctl restart zammad" + $ zammad config:set APP_RESTART_CMD="systemctl restart zammad" Configure Zammad to log to STDOUT ================================= If you want to log to STDOUT instead of the production-logfile (``/var/log/zammad/production.log``) you can set it: -:: - - zammad config:set RAILS_LOG_TO_STDOUT=true + +.. code-block:: sh + + $ zammad config:set RAILS_LOG_TO_STDOUT=true To reset this back to logfile logging run: -:: - - zammad config:set RAILS_LOG_TO_STDOUT= +.. code-block:: sh -.. Note:: **This applies to package installations:** Do not set it to ``enabled``, because we'll then unset the variable upon Update! - Using ``true`` is **update safe**. + $ zammad config:set RAILS_LOG_TO_STDOUT= +.. note:: **This applies to package installations:** Do not set it to ``enabled``, because we'll then unset the variable upon Update! + Using ``true`` is **update safe**. diff --git a/appendix-privacy.rst b/appendix/privacy.rst similarity index 96% rename from appendix-privacy.rst rename to appendix/privacy.rst index 2c848346..cda70398 100644 --- a/appendix-privacy.rst +++ b/appendix/privacy.rst @@ -15,7 +15,7 @@ Tickets and users `use the scheduler `_. To manually delete users and all their associated tickets (*e.g.,* in compliance with a “Right to Forget” request under the GDPR), - :ref:`use the console `. + :doc:`use the console `. .. note:: The ability to delete users via the admin panel is planned for a future release of Zammad. @@ -25,7 +25,7 @@ Chat sessions it is scheduled for automatic deletion 3 months later. IP address logs for chat sessions can be manually deleted - by :ref:`following the directions here `. + by :doc:`following the directions here `. CTI caller log The caller log shows only the 60 most recent entries. diff --git a/appendix/repo-file.rst b/appendix/repo-file.rst new file mode 100644 index 00000000..29bbd80a --- /dev/null +++ b/appendix/repo-file.rst @@ -0,0 +1,93 @@ +Package Repo Files +****************** + +Recently (24 Jul 2017) our packaging service provider (packager.io: http://www.packager.io/) improved its package distribution which makes it necessary that you update your Zammad repo file (e. g. /etc/apt/sources.list.d/zammad.list or /etc/yum.repos.d/zammad.repo) on your operating system. + +If you're using an old repo file, you will not be able to update Zammad. + +For more background information see: https://blog.packager.io/posts/24-change-of-repository-urls + +Please use the following commands to update your Zammad repo file: + + +CentOS 7 +============= + +.. code-block:: sh + + $ sudo yum -y install epel-release wget + $ sudo wget -O /etc/yum.repos.d/zammad.repo https://dl.packager.io/srv/zammad/zammad/stable/installer/el/7.repo + $ sudo yum install zammad + + +Debian 8 +============= + +.. code-block:: sh + + $ sudo apt-get install wget + $ wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - + $ sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/8.repo + $ sudo apt-get update + $ sudo apt-get install zammad + + +Debian 9 +============= + +.. code-block:: sh + + $ sudo apt-get install wget + $ wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - + $ sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/9.repo + $ sudo apt-get update + $ sudo apt-get install zammad + + +Ubuntu 16.04 +============= + +.. code-block:: sh + + $ sudo apt-get install wget + $ wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - + $ sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/ubuntu/16.04.repo + $ sudo apt-get update + $ sudo apt-get install zammad + + +Ubuntu 18.04 +============= + +.. code-block:: sh + + $ sudo apt-get install wget + $ wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - + $ sudo wget -O /etc/apt/sources.list.d/zammad.list \ + https://dl.packager.io/srv/zammad/zammad/stable/installer/ubuntu/18.04.repo + $ sudo apt-get update + $ sudo apt-get install zammad + + +SLES 12 +============= + +.. code-block:: sh + + $ sudo zypper install wget + $ sudo wget -O /etc/zypp/repos.d/zammad.repo https://dl.packager.io/srv/zammad/zammad/stable/installer/sles/12.repo + $ sudo zypper install zammad + + +Note +============= +If you're using an old repo file, you will get error messages like these: + +:: + + E: Failed to fetch https://deb.packager.io/gh/zammad/zammad/dists/xenial/stable/binary-amd64/Packages Writing more data than expected (7831 > 1153) + E: Some index files failed to download. They have been ignored, or old ones used instead. + +:: + + Paket zammad-1.5.0-1500965473.2be861e2.centos7.x86_64.rpm not signed diff --git a/console/dangerzone-for-experts.rst b/console/dangerzone-for-experts.rst deleted file mode 100644 index 8d969a85..00000000 --- a/console/dangerzone-for-experts.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. _console-dangerzone: - -DANGERZONE (Deletion of stuff) -****************************** - -.. DANGER:: Please note that the commands on this page cause **DATA LOSS**! Only proceed if you know what you're doing and you **have a backup**! - -.. Note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. - - -Delete a certain ticket ------------------------ - -The following command removes a specific ticket and all of it's articles from Zammad. -:: - - Ticket.find(4).destroy - -Delete some tickets ------------------- - -This will remove all existing tickets, except for those you specified within `tickets_to_keep`-variable before. -:: - - tickets_to_keep = [1, 2, 3] # enter the ids of all tickets you want to keep - (Ticket.all.pluck(:id) - tickets_to_keep).each { |id| Ticket.find(id).destroy } - - -Delete all tickets ------------------- - -This removes all existing tickets within Zammad. -:: - - Ticket.destroy_all - - -Delete one or more users with all their related information ------------------------------------------------------------ - -.. Warning:: You can't remove users without removing tickets of them! - -.. Note:: This is meant for deleting customers, agents differ a bit and might have different results - user with caution! - -The following will look for affected users. It will also give you a list of tickets being affected. -:: - - target_user_emails = ['customer@example.com'] - # This will generate an overview what Zammad will remove - list = '' - target_user_emails.each {|email| - User.where(email: email.downcase).each {|user| - next if user.id == 1 - next if !user.permissions?('ticket.customer') - list += "Customer #{user.login}/#{user.email}/#{user.id} has #{Ticket.where(customer_id: user.id).count} tickets #{Ticket.where(customer_id: user.id).pluck(:number)}\n" - } - } - puts list - - -The following is the real deal. It will delete all tickets linked to a customer and afterwards remove the user. - -.. Note:: You need to run the overview-part (lookup) before you can run the below! -:: - - # Actual deletion, requires overview run before - User.joins(roles: :permissions).where(email: target_user_emails.map(&:downcase), roles: { active: true }, permissions: { name: 'ticket.customer', active: true }).where.not(id: 1).find_each do |user| - puts "Customer #{user.login}/#{user.email} has #{Ticket.where(customer_id: user.id).count} tickets" - - Ticket.where(customer: user).find_each do |ticket| - puts " Deleting ticket #{ticket.number}..." - ticket.destroy - end - - puts " Removing references for user with E-Mail #{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) - if OnlineNotification.find_by(user_id: user.id)=="" - OnlineNotification.find_by(user_id: user.id).destroy! - end - - puts " Deleting user #{user.login}/#{user.email}..." - user.destroy - end - - -Removing organizations ----------------------- - -In order to delete groups, you need to ensure no users are assigned as group member. -If you want to search for other conditions of a group ( so not `active: false` ) just replace it inside the `where()` clause. -Ensure that the searched phrase is inside the organization Object! - -First to the preview of what is affected: -:: - - # preview - list = '' - Organization.where(active: false).each {|org| - list += "ORGANIZATION #{org.name} \n" - } - puts list - - -If the result is correct, you can run the below to finally un-assign users memberships followed by the organization removal. -:: - - # delete organization - Organization.where(active: false).each {|org| - puts "Working on '#{org.name}' \n" - User.where(organization_id: org.id).each {|user| - puts "... Removing User '#{user.firstname} #{user.lastname}' from Organization" - user.organization_id=nil - user.save! - } - puts "... Deleting organisation \n\n" - org.destroy - } - - -Destroy stuff -------------- - -These commands will destroy historical information within Zammad. -:: - - OnlineNotification.destroy_all # Remove all online notifications - ActivityStream.destroy_all # Remove all entries from the Activity Stream (Dashboard) - RecentView.destroy_all # Removes the entries for all recently viewed Objects (Tickets, Users, Organizations) - History.destroy_all # This removes all history information from Tickets, Users and Organizations (dangeorus!) - diff --git a/console/other-usefull-commands.rst b/console/other-usefull-commands.rst deleted file mode 100644 index fa84d201..00000000 --- a/console/other-usefull-commands.rst +++ /dev/null @@ -1,56 +0,0 @@ -Other useful commands -********************** - -.. Note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. - -Fetch mails ------------ - -The below command will do a manual fetch of mail channels. This will also show erors that might appear within that process. -:: - - Channel.fetch - - -Add translation ---------------- - -This comes in handy if you e.g. added a new state that you need to translate for several languages. -:: - - Translation.create_if_not_exists( :locale => 'de-de', :source => "New", :target => "Neu", format: 'string', created_by_id: 1, updated_by_id: 1 ) - - -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}`` against the name of your attribute. -:: - - 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 ---------------------------------- - -.. Warning:: 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 "fill data". -:: - - FillDB.load(agents: 50,customers: 1000,groups: 20,organizations: 40,overviews: 5,tickets: 100,) - diff --git a/console/working-on-tickets.rst b/console/working-on-tickets.rst deleted file mode 100644 index 6eb2c47d..00000000 --- a/console/working-on-tickets.rst +++ /dev/null @@ -1,182 +0,0 @@ -Working with ticket information -******************************* - -.. Note:: Please note that this is not a full command list, if you're missing commands, feel free to ask over at our `Community `_. - -Get the RAW mail that Zammad fetched ------------------------------------- - -The following command will help you to check on received emls Zamamd fetched. This comes in handy if you delete Mails upon fetching and you need to check the eml itself. - -To get the first articles eml, you can use the following command. In our example the ticket number in question is ``101234`` -:: - - Ticket.find_by(number:'101234').articles.first.as_raw.content - -If needed, you can also get the raw content of later articles (you'll need to find the correct article though). Again, we expect ``101234`` to be our ticket number. -In the first step we get all article IDs of the ticket, from the list we get, we can then get the articles content. -:: - - > Ticket.find_by(number:'101234').articles_ids - => [4, 3, 2] - > Ticket::Article.find(3).as_raw.content - -.. Note:: If you just use ``Ticket::Article.find(3)`` you can see further information (like who sent the mail, when we fetched it, ...). - - -Update all tickets of a specific customer ------------------------------------------ - -.. Warning:: Please note that this action can be expensive in ressource terms, if you have many tickets, this might slow down Zammad. - -:: - - Ticket.where(customer_id: 4).update_all(customer_id: 1) - - -Change priority ---------------- - -The following commands will enable you to change the naming of priorities. If you set ``.default_create`` to ``true`` you can manipulate what Zammad will use as default priority. -:: - - priority2 = Ticket::Priority.find(2) - priority2.name = '2-high' - priority2.default_create = true - priority2.save! - - -Get ticket state types ----------------------- - -This will show all Ticket States needed for creating new states. - -.. Note:: Missing States you just created? You might want to use ``Ticket.State.all`` to display all states for Tickets. - -:: - - Ticket::StateType.all - - -Add new ticket state --------------------- - -.. Note:: You can use ``ignore_escalation: true,`` to ignore possible SLA escalations (pending reminder and pending close use that 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). -:: - - 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. -:: - - 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. -:: - - 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, - ) - -Add a date and time picker (pending till) for pending states -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To add the time picker (pending till) to the new pending state, you'll need to execute the following code: - -:: - - attribute = ObjectManager::Attribute.get( - object: 'Ticket', - name: 'pending_time', - ) - attribute.data_option[:required_if][:state_id] = Ticket::State.by_category(:pending).pluck(:id) - attribute.data_option[:shown_if][:state_id] = Ticket::State.by_category(:pending).pluck(:id) - attribute.save! - - -.. Note:: In enhanced cases you might want do define the ``state_id`` on your own. In this case just pick the returned ``state_id`` from ``Ticket::State.by_category(:pending).pluck(:id)`` and use them with ``attribute.data_option[:required_if][:state_id] = {state_id(s)}`` and ``attribute.data_option[:shown_if][:state_id] = {state_id(s)}`` directly. Don't forget to save! - - - -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. - -.. Warn:: Please **do not replace** anything below, state_id is a named attribute which is correct and shall not be replaced! - -:: - - 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 ------------------------------------- - -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: - -:: - - 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: - -:: - - 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)) - -:: - - Ticket::State.find({ID}).name - diff --git a/console/zammad-settings.rst b/console/zammad-settings.rst deleted file mode 100644 index 16602197..00000000 --- a/console/zammad-settings.rst +++ /dev/null @@ -1,82 +0,0 @@ -Getting and Updating Zammad-Settings -************************************ - -.. Note:: Please note that this is not a full setting list, if you're missing settings, feel free to ask over at our `Community `_. - - -Get ticket_hook setting ------------------------ - -This will give you the Ticket hook that you'll find inside the `[]` in front of the ticket number. -By default this will be `Ticket#` - you shouldn't change this setting in a productive system. -:: - - Setting.get('ticket_hook') - - -Get fqdn setting ----------------- - -Get the current FQDN-Setting of Zammad and, if needed, adjust it. -:: - - Setting.get('fqdn') # Get FQDN - Setting.set('fqdn', 'new.domain.tld') # Set a new FQDN - - -Find storage_provide setting ----------------------------- - -The following command returns a list of available settings for `storage_provider` (for attachments). -:: - - Setting.find_by(name: 'storage_provider') - - -Set storage_rpovider Setting ----------------------------- - -Change the storage_provider if needed. -:: - - Setting.set('storage_provider', 'DB') # Change Attachment-Storage to database - Setting.get('storage_provider') # get the current Attachment-Storage - - -Configuring Elasticsearch -------------------------- - -If your elasticsearch installation changes, you can use the following commands to ensure that Zammad still can access elasticsearch. -:: - - Setting.set('es_url', 'http://127.0.0.1:9200') # Change elasticsearch URL to poll - Setting.set('es_user', 'elasticsearch') # Change elasticsearch user (e.g. for authentication) - Setting.set('es_password', 'zammad') # Change the elasticsearch password for authentication - Setting.set('es_index', Socket.gethostname + '_zammad') # Change the index name - Setting.set('es_attachment_ignore', [ '.png', '.jpg', '.jpeg', '.mpeg', '.mpg', '.mov', '.bin', '.exe', '.box', '.mbox' ] ) # A list of ignored file extensions (they will not be indexed) - Setting.set('es_attachment_max_size_in_mb', 50) # Limit the Attachment-Size to push to your elasticsearch index - - -Use the OTRS importer from the shell ------------------------------------- - -If needed, you can configure and run the OTRS-Import from console. -:: - - Setting.set('import_otrs_endpoint', 'http://xxx/otrs/public.pl?Action=ZammadMigrator') - Setting.set('import_otrs_endpoint_key', 'xxx') - Setting.set('import_mode', true) - Import::OTRS.start - - -Enable proxy ------------- - -Zammad needs to use a proxy for network communication? Set it here. -:: - - Setting.set('proxy', 'proxy.example.com:3128') - Setting.set('proxy_username', 'some user') - Setting.set('proxy_password', 'some pass') - - diff --git a/contributing-branches.rst b/contributing/branches.rst similarity index 99% rename from contributing-branches.rst rename to contributing/branches.rst index ccd0f117..76ed8377 100644 --- a/contributing-branches.rst +++ b/contributing/branches.rst @@ -37,4 +37,3 @@ Stable-X.x * There will be several more stable branches because we'll support the last three major versions of Zammad * If current stable version is 1.2.0 then the name of the branch is stable-1.2 and there also would be stable-1.1 and stable-1.0 - diff --git a/contributing-ci.rst b/contributing/ci.rst similarity index 93% rename from contributing-ci.rst rename to contributing/ci.rst index 0d6f5edd..708f0c52 100644 --- a/contributing-ci.rst +++ b/contributing/ci.rst @@ -19,6 +19,6 @@ Travis-CI * If you fork the Zammad repo you're able to also use travis-ci.org to get your builds tested * Just change the file ".travis.yml" to fit your needs * Current build test status is: -.. image:: https://travis-ci.org/zammad/zammad.svg?branch=develop - :target: https://travis-ci.org/zammad/zammad +.. image:: https://travis-ci.org/zammad/zammad.svg?branch=develop + :target: https://travis-ci.org/zammad/zammad diff --git a/contributing-code-quality.rst b/contributing/code-quality.rst similarity index 100% rename from contributing-code-quality.rst rename to contributing/code-quality.rst diff --git a/contributing-install-docker.rst b/contributing/install-docker.rst similarity index 81% rename from contributing-install-docker.rst rename to contributing/install-docker.rst index aa48c5c2..e947336a 100644 --- a/contributing-install-docker.rst +++ b/contributing/install-docker.rst @@ -6,7 +6,7 @@ Our Docker image is a **single container** based application designed to have Za Please note that this is a non persistent storage container and **all Zammad data is lost** when you're stopping the container. -If you like to run Docker in production environment try our Docker-compose version: :ref:`install_docker_compose` . +If you like to run Docker in production environment try our Docker-compose version: :doc:`/install/docker-compose` . Your Docker environment needs to be up and running. @@ -15,25 +15,25 @@ You can find the image at https://hub.docker.com/r/zammad/zammad/ You need at least 4 GB of RAM to run the container. Run the Docker Container -====================== +======================== Docker run will run a command in a new container, -i attaches stdin and stdout, -t allocates a tty. Set vm.max_map_count for Elasticsearch -------------------------------------- -:: +.. code-block:: sh - sysctl -w vm.max_map_count=262144 + $ sysctl -w vm.max_map_count=262144 -.. Tip:: For Mac OS: https://github.com/zammad/zammad-docker/issues/27#issuecomment-455171752 +.. tip:: For Mac OS: https://github.com/zammad/zammad-docker/issues/27#issuecomment-455171752 Run docker container -------------------- -:: +.. code-block:: sh - docker container run -ti --rm --name zammad -p 80:80 zammad/zammad + $ docker container run -ti --rm --name zammad -p 80:80 zammad/zammad That’s it! You’re now using a bash shell inside of a Zammad docker container using the develop branch of the GitHub repo. diff --git a/contributing-install-vagrant.rst b/contributing/install-vagrant.rst similarity index 80% rename from contributing-install-vagrant.rst rename to contributing/install-vagrant.rst index b38782ef..2c2894e4 100644 --- a/contributing-install-vagrant.rst +++ b/contributing/install-vagrant.rst @@ -11,10 +11,10 @@ First be sure that a Vagrant provider is installed. You can use "Virtual Box" fr Clone the Vagrant file ====================== -:: +.. code-block:: sh - git clone git@github.com:zammad/zammad-vagrant.git - cd zammad-vagrant + $ git clone git@github.com:zammad/zammad-vagrant.git + $ cd zammad-vagrant Run Vagrant @@ -24,16 +24,16 @@ Run Vagrant For stable branch package ------------------------- -:: +.. code-block:: sh - PACKAGER_REPO=stable vagrant up --provision + $ PACKAGER_REPO=stable vagrant up --provision For develop branch package -------------------------- -:: +.. code-block:: sh - vagrant up --provision + $ vagrant up --provision @@ -50,16 +50,16 @@ SSH into the machine After "vagrant up" -:: +.. code-block:: sh - vagrant ssh + $ vagrant ssh After this you can switch to root user via: -:: +.. code-block:: sh - sudo -i + $ sudo -i Problems starting the VM? @@ -76,8 +76,6 @@ If you get errors like: Use the following commands to fix it: -:: - - vboxmanage controlvm Zammad poweroff - +.. code-block:: sh + $ vboxmanage controlvm Zammad poweroff diff --git a/contributing-packages.rst b/contributing/packages.rst similarity index 100% rename from contributing-packages.rst rename to contributing/packages.rst diff --git a/contributing-start.rst b/contributing/start.rst similarity index 100% rename from contributing-start.rst rename to contributing/start.rst diff --git a/cti-api-intro.rst b/cti/api-intro.rst similarity index 98% rename from cti-api-intro.rst rename to cti/api-intro.rst index d28685af..d6fd15fc 100644 --- a/cti-api-intro.rst +++ b/cti/api-intro.rst @@ -1,5 +1,5 @@ Introduction -**** +************ In many use cases, agents work in connection customer conversations over the phone. @@ -8,7 +8,7 @@ It is a great relief when the telephone system (PBX) is integrated with Zammad, The goal of the document is to provide the necessary API documentation to enable PBX vendors to easily integrate with Zammad. Feature list -==== +============ **Inbound** @@ -28,5 +28,3 @@ Feature list * if supported by the PBX/telephone system - - diff --git a/cti-api-push.rst b/cti/api-push.rst similarity index 92% rename from cti-api-push.rst rename to cti/api-push.rst index 2344c761..24d52b75 100644 --- a/cti-api-push.rst +++ b/cti/api-push.rst @@ -44,9 +44,9 @@ Zammad supports the following three events (newCall, hangup and answer) in versi You can simulate this POST request and test your server with a CURL command: -:: +.. code-block:: sh - curl -X POST --data "event=newCall&from=493055571600&to=491711234567890&direction=in&callId=123456&user[]=Alice&user[]=Bob" http://localhost:3000/api/v1/cti/:token + $ curl -X POST --data "event=newCall&from=493055571600&to=491711234567890&direction=in&callId=123456&user[]=Alice&user[]=Bob" http://localhost:3000/api/v1/cti/:token *The response (optional)* @@ -62,12 +62,12 @@ Zammad currently supports the following responses for incoming calls: Example 1: Reject call signaling busy -:: +.. code-block:: json - { - "action": "reject", - "reason": "busy" - } + { + "action": "reject", + "reason": "busy" + } Zammad currently supports the following responses for outgoing calls: @@ -79,13 +79,13 @@ Zammad currently supports the following responses for outgoing calls: Example 1: Set custom caller id for outgoing call -:: +.. code-block:: json - { - "action": "dial", - "callerId": "493055571642", - "number": "491711234567890" - } + { + "action": "dial", + "callerId": "493055571642", + "number": "491711234567890" + } **Event: hangup** @@ -109,9 +109,9 @@ Example 1: Set custom caller id for outgoing call You can simulate this POST request and test your server with a CURL command: -:: +.. code-block:: sh - curl -X POST --data "event=hangup&cause=normalClearing&callId=123456&from=493055571600&to=491711234567890&direction=in&answeringNumber=4921199999999" http://localhost:3000/api/v1/cti/:token + $ curl -X POST --data "event=hangup&cause=normalClearing&callId=123456&from=493055571600&to=491711234567890&direction=in&answeringNumber=4921199999999" http://localhost:3000/api/v1/cti/:token Hangup causes: For these reasons, hangups may occur because of these causes: @@ -158,8 +158,6 @@ Hangup causes: For these reasons, hangups may occur because of these causes: You can simulate this POST request and test your server with a CURL command: -:: - - curl -X POST --data "event=answer&callId=123456&user=John+Doe&from=493055571600&to=491711234567890&direction=in&answeringNumber=21199999999" http://localhost:3000/api/v1/cti/:token - +.. code-block:: sh + $ curl -X POST --data "event=answer&callId=123456&user=John+Doe&from=493055571600&to=491711234567890&direction=in&answeringNumber=21199999999" http://localhost:3000/api/v1/cti/:token diff --git a/getting-started-first-steps.rst b/getting-started/first-steps.rst similarity index 100% rename from getting-started-first-steps.rst rename to getting-started/first-steps.rst diff --git a/index.rst b/index.rst index aa4cfa05..7c4ec7a1 100644 --- a/index.rst +++ b/index.rst @@ -8,77 +8,52 @@ The Zammad documentation consists of three parts: - Zammad user documentation (https://user-docs.zammad.org) -This system documentation for Zammad is organized into a couple of sections: - -* :ref:`about-docs` -* :ref:`prerequisites-docs` -* :ref:`install-docs` -* :ref:`getting-started-docs` -* :ref:`migration-docs` -* :ref:`admin-console` -* :ref:`contributing-docs` -* :ref:`rest-api-docs` -* :ref:`appendix` - - -.. _about-docs: - .. toctree:: :maxdepth: 2 :caption: About - about-zammad + /about/zammad -.. _prerequisites-docs: - .. toctree:: :maxdepth: 2 :caption: Prerequisites - prerequisites-software - prerequisites-hardware - + /prerequisites/software + /prerequisites/hardware -.. _install-docs: .. toctree:: :maxdepth: 1 :caption: Installation & Update - install-source - install-centos - install-debian - install-ubuntu - install-suse - install-elasticsearch - install-docker-compose - install-kubernetes - install-univention - install-update + /install/source + /install/centos + /install/debian + /install/ubuntu + /install/suse + /install/elasticsearch + /install/docker-compose + /install/kubernetes + /install/univention + /install/update -.. _getting-started-docs: - .. toctree:: :maxdepth: 2 :caption: Getting started - getting-started-first-steps - + /getting-started/first-steps -.. _migration-docs: .. toctree:: :maxdepth: 2 :caption: Migration - migration-otrs - migration-zendesk + /migration/otrs + /migration/zendesk -.. _admin-webfrontend: - .. toctree:: :maxdepth: 3 :glob: @@ -87,65 +62,55 @@ This system documentation for Zammad is organized into a couple of sections: Admin-Documentation -.. _admin-console: - .. toctree:: - :maxdepth: 2 - :glob: - :caption: Administration via console - - admin-console + :maxdepth: 2 + :glob: + :caption: Administration via console + /admin/console -.. _contributing-docs: .. toctree:: :maxdepth: 2 :glob: :caption: Contributing / Development - contributing-start - contributing-branches - contributing-packages - contributing-ci - contributing-code-quality - contributing-install-docker - contributing-install-vagrant - + /contributing/start + /contributing/branches + /contributing/packages + /contributing/ci + /contributing/code-quality + /contributing/install-docker + /contributing/install-vagrant -.. _rest-api-docs: .. toctree:: :maxdepth: 2 :glob: :caption: REST API - api-intro - api-user - api-organization - api-group - api-ticket - api-ticket-state - api-ticket-priority - api-ticket-article - api-notification - api-object - api-tags - api-user_access_token + /api/intro + /api/user + /api/organization + /api/group + /api/ticket + /api/ticket-state + /api/ticket-priority + /api/ticket-article + /api/notification + /api/object + /api/tags + /api/user-access-token -.. _cti-api-docs: - .. toctree:: :maxdepth: 2 :glob: :caption: CTI API - cti-api-intro - cti-api-push - + /cti/api-intro + /cti/api-push -.. _appendix: .. toctree:: :maxdepth: 2 @@ -153,7 +118,7 @@ This system documentation for Zammad is organized into a couple of sections: :caption: Appendix - appendix-backup-and-restore - appendix-configure-env-vars - appendix-repo-file - appendix-privacy + /appendix/backup-and-restore + /appendix/configure-env-vars + /appendix/repo-file + /appendix/privacy diff --git a/install-centos.rst b/install-centos.rst deleted file mode 100644 index 952a391a..00000000 --- a/install-centos.rst +++ /dev/null @@ -1,112 +0,0 @@ -Install on CentOS via RPM -************************* - -.. Note:: Currently we support RHEL7 & CentOS7. - -Prerequisites -============= - -Setup Elasticsearch -------------------- - -Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. -Please take a look at the following page: :ref:`install_elasticsearch` . - - -Add Zammad-Repo and Install Zammad -================================== - -:: - - sudo yum -y install epel-release wget - sudo wget -O /etc/yum.repos.d/zammad.repo https://dl.packager.io/srv/zammad/zammad/stable/installer/el/7.repo - - sudo yum -y install zammad - - -SeLinux & Firewalld -------------------- - -On Centos SeLinux & Firewalld are possibly enabled. -To get everything work you have to use the following commands: - -:: - - setsebool httpd_can_network_connect on -P - firewall-cmd --zone=public --add-service=http --permanent - firewall-cmd --zone=public --add-service=https --permanent - firewall-cmd --reload - - - -Go to http://localhost and you'll see: -====================================== - -* "Welcome to Zammad!", there you need to create your admin user and invite other agents. - - -Change your webserver configuration (non localhost connections): ----------------------------------------------------------------- - -Add your fully qualified domain name or public IP to server name directive in your web server configuration and restart your web server. -The installer will give you a hint where Zammad's web server config file is located. - -nginx ------ - -.. Warning:: Please **do not rename** the webserver config file for nginx or apache. - The update process will re create it, if it does not exist! - -*/etc/nginx/conf.d/zammad.conf* - -:: - - server { - listen 80; - - # replace 'localhost' with your fqdn if you want to use zammad from remote - server_name localhost; - - -You can manage the Zammad services manually: -=========================================== - -Zammad ------- - -:: - - sudo systemctl status zammad - sudo systemctl stop zammad - sudo systemctl start zammad - sudo systemctl restart zammad - -Only web application server ---------------------------- - -:: - - sudo systemctl status zammad-web - sudo systemctl stop zammad-web - sudo systemctl start zammad-web - sudo systemctl restart zammad-web - -Only worker process -------------------- - -:: - - sudo systemctl status zammad-worker - sudo systemctl stop zammad-worker - sudo systemctl zammad-worker - sudo systemctl restart zammad-worker - -Only websocket server ---------------------- - -:: - - sudo systemctl status zammad-websocket - sudo systemctl stop zammad-websocket - sudo systemctl start zammad-websocket - sudo systemctl restart zammad-websocket diff --git a/install-debian.rst b/install-debian.rst deleted file mode 100644 index 3988e55a..00000000 --- a/install-debian.rst +++ /dev/null @@ -1,146 +0,0 @@ -Install on Debian via DEB -************************* - -.. Note:: Currently we support Debian 8, 9 and 10 - -Prerequisites -============= - -Be sure to use an UTF-8 locale or PostgreSQL will not install. - - -Setup Elasticsearch -------------------- - -Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. -Please take a look at the following page: :ref:`install_elasticsearch` . - - -Check locale ------------- - -:: - - locale - -If there is nothing with UTF-8 in the name shown like "LANG=en_US.UTF-8" you have to set a new locale. - -Set locale ----------- - -:: - - sudo apt-get install apt-transport-https locales sudo wget - sudo locale-gen en_US.UTF-8 - sudo echo "LANG=en_US.UTF-8" > /etc/default/locale - - -Add Zammad DEB repo and install -=============================== - -:: - - wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - - - -For Debian 8 ------------- - -:: - - sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/8.repo - - -For Debian 9 ------------- - -:: - - sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/9.repo - -For Debian 10 ------------- - -:: - - sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/10.repo - - -:: - - sudo apt-get update - sudo apt-get install zammad - - - -Go to http://localhost and you'll see: -====================================== - -* "Welcome to Zammad!", there you need to create your admin user and invite other agents. - - -Change your webserver configuration (non localhost connections): -================================================================ - -Add your fully qualified domain name or public IP to server name directive in your web server configuration and restart your web server. -The installer will give you a hint where Zammad's web server config file is located. - -nginx ------ - -.. Warning:: Please **do not rename** the webserver config file for nginx or apache. - The update process will re create it, if it does not exist! - -*/etc/nginx/sites-enabled/zammad.conf* - -:: - - server { - listen 80; - - # replace 'localhost' with your fqdn if you want to use zammad from remote - server_name localhost; - - -You can manage the Zammad services manually: -============================================ - -Zammad ------- - -:: - - sudo systemctl status zammad - sudo systemctl stop zammad - sudo systemctl start zammad - sudo systemctl restart zammad - -only web application server ---------------------------- - -:: - - sudo systemctl status zammad-web - sudo systemctl stop zammad-web - sudo systemctl start zammad-web - sudo systemctl restart zammad-web - -only worker process -------------------- - -:: - - sudo systemctl status zammad-worker - sudo systemctl stop zammad-worker - sudo systemctl start zammad-worker - sudo systemctl restart zammad-worker - -only websocket server ---------------------- - -:: - - sudo systemctl status zammad-websocket - sudo systemctl stop zammad-websocket - sudo systemctl start zammad-websocket - sudo systemctl restart zammad-websocket diff --git a/install-source.rst b/install-source.rst deleted file mode 100644 index 9816c563..00000000 --- a/install-source.rst +++ /dev/null @@ -1,299 +0,0 @@ -Install from source (generic) -***************************** - -Setup Elasticsearch -------------------- - -Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. -Please take a look at the following page: :ref:`install_elasticsearch` . - - -1. Install Zammad on your system -================================ - -You can directly download Zammad from https://ftp.zammad.com/ or use the direct URL to get the latest stable release via https://ftp.zammad.com/zammad-latest.tar.gz - -:: - - root@shell> useradd zammad -m -d /opt/zammad -s /bin/bash - root@shell> cd /opt - root@shell> wget https://ftp.zammad.com/zammad-latest.tar.gz - root@shell> tar -xzf zammad-latest.tar.gz -C zammad - root@shell> su - zammad - - -2. Install all dependencies -=========================== - -Please note that a working ruby 2.5.5 environment is needed. - -:: - - zammad@shell> gem install bundler rake rails - -For PostgreSQL (note, the option says "without ... mysql") ----------------------------------------------------------- - -:: - - zammad@shell> bundle install --without test development mysql - -For MySQL (note, the option says "without ... postgres") --------------------------------------------------------- - -:: - - zammad@shell> bundle install --without test development postgres - - -3. Configure your databases -=========================== - -:: - - zammad@shell> cp config/database/database.yml config/database.yml - zammad@shell> vi config/database.yml - - -4. Initialize your database -=========================== - -:: - - zammad@shell> export RAILS_ENV=production - zammad@shell> export RAILS_SERVE_STATIC_FILES=true - zammad@shell> rake db:create - zammad@shell> rake db:migrate - zammad@shell> rake db:seed - - -5. Change directory to zammad (if needed) and start services: -============================================================= - -:: - - zammad@shell> rake assets:precompile - -You can start all services by hand or use systemd to start / stop Zammad. - -Starting all servers manually ------------------------------ - -:: - - zammad@shell> rails s -p 3000 # application web server - zammad@shell> script/websocket-server.rb start # non blocking websocket server - zammad@shell> script/scheduler.rb start # generate overviews on demand, just send changed data to browser - - -Starting servers with Systemd ------------------------------ - -:: - - zammad@shell> cd scripts/systemd - zammad@shell> sudo ./install-zammad-systemd-services.sh - - -6. Go to http://localhost:3000 and you'll see: -============================================== - -* "Welcome to Zammad!", there you need to create your admin user and invite other agents. - - -Reset a Zammad installation (for a fresh start after testing) -------------------------------------------------------------- - -Please note: this actions will delete all existing data! Dont use it on a production system. - -:: - - zammad@shell>sudo systemctl stop zammad - zammad@shell>rake db:drop - zammad@shell>rake db:create - zammad@shell>rake db:migrate - zammad@shell>rake db:seed - zammad@shell>sudo systemctl start zammad - - - - -Install from source (Debian 7, 8 / Ubuntu 16.04 / Ubuntu 18.04) -*************************************************************** - -With Nginx & MySQL -================== - -Prerequisites -------------- - -:: - - apt-get update - apt-get install curl git-core patch build-essential bison zlib1g-dev libssl-dev libxml2-dev libxml2-dev sqlite3 libsqlite3-dev autotools-dev libxslt1-dev libyaml-0-2 autoconf automake libreadline6-dev libyaml-dev libtool libgmp-dev libgdbm-dev libncurses5-dev pkg-config libffi-dev libmysqlclient-dev mysql-server nginx gawk libimlib2-dev - -Add User --------- - -:: - - useradd zammad -m -d /opt/zammad -s /bin/bash - echo "export RAILS_ENV=production" >> /opt/zammad/.bashrc - - -Create MySQL user zammad (for Debian: upgrade MySQL to v5.6+ before, see: http://dev.mysql.com/downloads/repo/apt/) -------------------------------------------------------------------------------------------------------------------- - -:: - - mysql --defaults-extra-file=/etc/mysql/debian.cnf -e "CREATE USER 'zammad'@'localhost' IDENTIFIED BY 'Your_Pass_Word'; GRANT ALL PRIVILEGES ON zammad_prod.* TO 'zammad'@'localhost'; FLUSH PRIVILEGES;" - -Get Zammad ----------- - -:: - - su - zammad - curl -O https://ftp.zammad.com/zammad-latest.tar.gz - tar -xzf zammad-latest.tar.gz - rm zammad-latest.tar.gz - - -Install environnment --------------------- - -:: - - gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 - curl -L https://get.rvm.io | bash -s stable - source /opt/zammad/.rvm/scripts/rvm - echo "source /opt/zammad/.rvm/scripts/rvm" >> /opt/zammad/.bashrc - echo "rvm --default use 2.5.5" >> /opt/zammad/.bashrc - rvm install 2.5.5 - gem install bundler - -Install Zammad --------------- - -:: - - bundle install --without test development postgres - cp config/database/database.yml config/database.yml - -* insert mysql user, pass & change adapter to mysql2 & change database to zammad_prod - -:: - - vi config/database.yml - -:: - - rake db:create - rake db:migrate - rake db:seed - rake assets:precompile - -Start Zammad ------------- - -:: - - rails s -p 3000 &>> log/zammad.log & - script/websocket-server.rb start &>> log/zammad.log & - script/scheduler.rb start &>> log/zammad.log & - - - -Create Nginx Config & restart Nginx ------------------------------------ - -:: - - exit - cp /opt/zammad/contrib/nginx/zammad.conf /etc/nginx/sites-available/zammad.conf - -* change servername "localhost" to your domain if your're not testing localy - - :: - - vi /etc/nginx/sites-available/zammad.conf - - :: - - ln -s /etc/nginx/sites-available/zammad.conf /etc/nginx/sites-enabled/zammad.conf - - - :: - - systemctl restart nginx - - -Go to http://localhost and you'll see: --------------------------------------- - -* "Welcome to Zammad!", there you need to create your admin user and invite other agents. - - - -Install from source (Mac OS 10.8) -********************************* - -Prerequisites -============= - -* Install Xcode from the App Store, open it -> Xcode menu > Preferences > Downloads -> install command line tools - -:: - - curl -L https://get.rvm.io | bash -s stable --ruby - source ~/.rvm/scripts/rvm - start new shell -> ruby -v - -Get Zammad -========== - -:: - - test -d ~/zammad/ || mkdir ~/zammad - cd ~/zammad/ - curl -L -O https://ftp.zammad.com/zammad-latest.tar.bz2 | tar -xj - - -Install Zammad -============== - -:: - - cd zammad-latest - bundle install - sudo ln -s /usr/local/mysql/lib/libmysqlclient.18.dylib /usr/lib/libmysqlclient.18.dylib # if needed! - rake db:create - rake db:migrate - rake db:seed - - -Database connect -================ - -:: - - cd zammad-latest - cp config/database/database.yml config/database.yml - rake db:create - rake db:migrate - rake db:seed - -Start Zammad -============ - -:: - - puma -p 3000 # application web server - script/websocket-server.rb start # non blocking websocket server - script/scheduler.rb start # generate overviews on demand, just send changed data to browser - - -Visit Zammad in your browser -============================ - -* http://localhost:3000/#getting_started diff --git a/install-suse.rst b/install-suse.rst deleted file mode 100644 index 6a53f4d1..00000000 --- a/install-suse.rst +++ /dev/null @@ -1,110 +0,0 @@ -Install on SUSE via RPM -*********************** - -.. Note:: Currently we support SLES 12 and OpenSUSE with versions 42.2 and 42.3 - -.. Warning:: OpenSUSE LEAP 15.0 hasn't been tested yet, but should work as well. - - -Install dependencies -==================== - -Setup Elasticsearch -------------------- - -Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. -Please take a look at the following page: :ref:`install_elasticsearch` . - - -nginx on SLES12 ---------------- - -:: - - sudo zypper addrepo "http://nginx.org/packages/sles/12" "nginx" - - -Add Zammad RPM repo and install -=============================== - -:: - - sudo zypper install wget - sudo wget -O /etc/zypp/repos.d/zammad.repo https://dl.packager.io/srv/zammad/zammad/stable/installer/sles/12.repo - sudo zypper install zammad - - - -Go to http://localhost and you'll see: -====================================== - -* "Welcome to Zammad!", there you need to create your admin user and invite other agents. - -Note: Make sure that the firewall is not blocking port 80 (configure firewall via "yast firewall" or stop it via "systemctl stop SuSEfirewall2"). - - -Change your webserver configuration (non localhost connections): -================================================================ - -Add your fully qualified domain name or public IP to server name directive in your web server configuration and restart your web server. -The installer will give you a hint where Zammad's web server config file is located. - -nginx --------- - -.. Warning:: Please **do not rename** the webserver config file for nginx or apache. - The update process will re create it, if it does not exist! - -*/etc/nginx/sites-enabled/zammad.conf* - -:: - - server { - listen 80; - - # replace 'localhost' with your fqdn if you want to use zammad from remote - server_name localhost; - - -You can manage the Zammad services manually: -============================================ - -Zammad ------- - -:: - - sudo systemctl status zammad - sudo systemctl stop zammad - sudo systemctl start zammad - sudo systemctl restart zammad - -Only web application server ---------------------------- - -:: - - sudo systemctl status zammad-web - sudo systemctl stop zammad-web - sudo systemctl start zammad-web - sudo systemctl restart zammad-web - -Only worker process -------------------- - -:: - - sudo systemctl status zammad-worker - sudo systemctl stop zammad-worker - sudo systemctl zammad-worker - sudo systemctl restart zammad-worker - -Only websocket server ---------------------- - -:: - - sudo systemctl status zammad-websocket - sudo systemctl stop zammad-websocket - sudo systemctl start zammad-websocket - sudo systemctl restart zammad-websocket diff --git a/install-ubuntu.rst b/install-ubuntu.rst deleted file mode 100644 index dadf8fd1..00000000 --- a/install-ubuntu.rst +++ /dev/null @@ -1,144 +0,0 @@ -Install on Ubuntu via DEB -************************* - -.. Note:: We currently support Ubuntu 16.04 LTS and 18.04 LTS. - - -Prerequisites -============= - -Be sure to use an UTF-8 locale or PostgreSQL will not install. - - -Setup Elasticsearch -------------------- - -Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. -Please take a look at the following page: :ref:`install_elasticsearch` . - - -Check locale ------------- - -:: - - locale - -If there is nothing with UTF-8 in the name shown like "LANG=en_US.UTF-8" you have to set a new locale. - -Set locale ----------- - -:: - - apt-get install apt-transport-https locales sudo wget - locale-gen en_US.UTF-8 - echo "LANG=en_US.UTF-8" > /etc/default/locale - - -Add Zammad DEB Repo -=================== - -Ubuntu 16.04 ------------- - -:: - - wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - - sudo wget -O /etc/apt/sources.list.d/zammad.list \ - https://dl.packager.io/srv/zammad/zammad/stable/installer/ubuntu/16.04.repo - - - -Ubuntu 18.04 ------------- - -:: - - wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - - sudo wget -O /etc/apt/sources.list.d/zammad.list \ - https://dl.packager.io/srv/zammad/zammad/stable/installer/ubuntu/18.04.repo - - -Install on Ubuntu (16.04 and 18.04) ------------------------------------ - -:: - - sudo apt-get update - sudo apt-get install zammad - -Note: You might need to apt-get install wget apt-transport-https for the above instructions to work. - - -Go to http://localhost and you'll see: -====================================== - -* "Welcome to Zammad!", there you need to create your admin user and invite other agents. - - -Change your webserver configuration (non localhost connections): -================= - -Add your fully qualified domain name or public IP to server name directive in your web server configuration and restart your web server. -The installer will give you a hint where Zammad's web server config file is located. - -nginx --------- - -.. Warning:: Please **do not rename** the webserver config file for nginx or apache. - The update process will re create it, if it does not exist! - -*/etc/nginx/sites-enabled/zammad.conf* - -:: - - server { - listen 80; - - # replace 'localhost' with your fqdn if you want to use zammad from remote - server_name localhost; - - -You can manage the Zammad services manually: -============================================ - -Zammad ------- - -:: - - sudo systemctl status zammad - sudo systemctl stop zammad - sudo systemctl start zammad - sudo systemctl restart zammad - -Only web application server ---------------------------- - -:: - - sudo systemctl status zammad-web - sudo systemctl stop zammad-web - sudo systemctl start zammad-web - sudo systemctl restart zammad-web - -Only worker process -------------------- - -:: - - sudo systemctl status zammad-worker - sudo systemctl stop zammad-worker - sudo systemctl start zammad-worker - sudo systemctl restart zammad-worker - -Only websocket server ---------------------- - -:: - - sudo systemctl status zammad-websocket - sudo systemctl stop zammad-websocket - sudo systemctl start zammad-websocket - sudo systemctl restart zammad-websocket diff --git a/install/centos.rst b/install/centos.rst new file mode 100644 index 00000000..3784c1b9 --- /dev/null +++ b/install/centos.rst @@ -0,0 +1,112 @@ +Install on CentOS via RPM +************************* + +.. note:: Currently we support RHEL7 & CentOS7. + +Prerequisites +============= + +Setup Elasticsearch +------------------- + +Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. +Please take a look at the following page: :doc:`/install/elasticsearch` . + + +Add Zammad-Repo and Install Zammad +================================== + +.. code-block:: sh + + $ sudo yum -y install epel-release wget + $ sudo wget -O /etc/yum.repos.d/zammad.repo https://dl.packager.io/srv/zammad/zammad/stable/installer/el/7.repo + + $ sudo yum -y install zammad + + +SeLinux & Firewalld +------------------- + +On Centos SeLinux & Firewalld are possibly enabled. +To get everything work you have to use the following commands: + +.. code-block:: sh + + $ setsebool httpd_can_network_connect on -P + $ firewall-cmd --zone=public --add-service=http --permanent + $ firewall-cmd --zone=public --add-service=https --permanent + $ firewall-cmd --reload + + + +Go to http://localhost and you'll see: +====================================== + +* "Welcome to Zammad!", there you need to create your admin user and invite other agents. + + +Change your webserver configuration (non localhost connections): +---------------------------------------------------------------- + +Add your fully qualified domain name or public IP to server name directive in your web server configuration and restart your web server. +The installer will give you a hint where Zammad's web server config file is located. + +nginx +----- + +.. warning:: Please **do not rename** the webserver config file for nginx or apache. + The update process will re create it, if it does not exist! + +:: + + # /etc/nginx/conf.d/zammad.conf + + server { + listen 80; + + # replace 'localhost' with your fqdn if you want to use zammad from remote + server_name localhost; + + +You can manage the Zammad services manually: +============================================ + +Zammad +------ + +.. code-block:: sh + + $ sudo systemctl status zammad + $ sudo systemctl stop zammad + $ sudo systemctl start zammad + $ sudo systemctl restart zammad + +Only web application server +--------------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-web + $ sudo systemctl stop zammad-web + $ sudo systemctl start zammad-web + $ sudo systemctl restart zammad-web + +Only worker process +------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-worker + $ sudo systemctl stop zammad-worker + $ sudo systemctl zammad-worker + $ sudo systemctl restart zammad-worker + +Only websocket server +--------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-websocket + $ sudo systemctl stop zammad-websocket + $ sudo systemctl start zammad-websocket + $ sudo systemctl restart zammad-websocket diff --git a/install/debian.rst b/install/debian.rst new file mode 100644 index 00000000..d13360e7 --- /dev/null +++ b/install/debian.rst @@ -0,0 +1,147 @@ +Install on Debian via DEB +************************* + +.. note:: Currently we support Debian 8, 9 and 10 + +Prerequisites +============= + +Be sure to use an UTF-8 locale or PostgreSQL will not install. + + +Setup Elasticsearch +------------------- + +Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. +Please take a look at the following page: :doc:`/install/elasticsearch` . + + +Check locale +------------ + +.. code-block:: sh + + $ locale + +If there is nothing with UTF-8 in the name shown like "LANG=en_US.UTF-8" you have to set a new locale. + +Set locale +---------- + +.. code-block:: sh + + $ sudo apt-get install apt-transport-https locales sudo wget + $ sudo locale-gen en_US.UTF-8 + $ sudo echo "LANG=en_US.UTF-8" > /etc/default/locale + + +Add Zammad DEB repo and install +=============================== + +.. code-block:: sh + + $ wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - + + +For Debian 8 +------------ + +.. code-block:: sh + + $ sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/8.repo + + +For Debian 9 +------------ + +.. code-block:: sh + + $ sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/9.repo + +For Debian 10 +------------- + +.. code-block:: sh + + $ sudo wget -O /etc/apt/sources.list.d/zammad.list https://dl.packager.io/srv/zammad/zammad/stable/installer/debian/10.repo + + +.. code-block:: sh + + $ sudo apt-get update + $ sudo apt-get install zammad + + + +Go to http://localhost and you'll see: +====================================== + +* "Welcome to Zammad!", there you need to create your admin user and invite other agents. + + +Change your webserver configuration (non localhost connections): +================================================================ + +Add your fully qualified domain name or public IP to server name directive in your web server configuration and restart your web server. +The installer will give you a hint where Zammad's web server config file is located. + +nginx +----- + +.. warning:: Please **do not rename** the webserver config file for nginx or apache. + The update process will re create it, if it does not exist! + + +:: + + # /etc/nginx/sites-enabled/zammad.conf + + server { + listen 80; + + # replace 'localhost' with your fqdn if you want to use zammad from remote + server_name localhost; + + +You can manage the Zammad services manually: +============================================ + +Zammad +------ + +.. code-block:: sh + + $ sudo systemctl status zammad + $ sudo systemctl stop zammad + $ sudo systemctl start zammad + $ sudo systemctl restart zammad + +only web application server +--------------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-web + $ sudo systemctl stop zammad-web + $ sudo systemctl start zammad-web + $ sudo systemctl restart zammad-web + +only worker process +------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-worker + $ sudo systemctl stop zammad-worker + $ sudo systemctl start zammad-worker + $ sudo systemctl restart zammad-worker + +only websocket server +--------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-websocket + $ sudo systemctl stop zammad-websocket + $ sudo systemctl start zammad-websocket + $ sudo systemctl restart zammad-websocket diff --git a/install-docker-compose.rst b/install/docker-compose.rst similarity index 91% rename from install-docker-compose.rst rename to install/docker-compose.rst index 849257fa..e6946d1a 100644 --- a/install-docker-compose.rst +++ b/install/docker-compose.rst @@ -1,9 +1,7 @@ -.. _install_docker_compose: - Install with Docker-Compose *************************** -.. Warning:: We currently do not support Docker environments in productive use. If you run Zammad on docker, it is fine. But we just support the application! +.. warning:: We currently do not support Docker environments in productive use. If you run Zammad on docker, it is fine. But we just support the application! Docker is a container-based software framework for automating deployment of applications. Compose is a tool for defining and running multi-container Docker applications. This repo is meant to be the starting point for somebody who likes to use dockerized multi-container Zammad in production. @@ -11,7 +9,7 @@ The Zammad Docker image uses the stable branch of Zammad's Git repo. The Docker images are hosted on `Dockerhub `_. -.. Tip:: Never use the "latest" tag. Use a tag which has a version attached. +.. tip:: Never use the "latest" tag. Use a tag which has a version attached. You need at least 4 GB of RAM to run the containers. @@ -45,7 +43,7 @@ Setting vm.max_map_count for Elasticsearch * sysctl -w vm.max_map_count=262144 -.. Tip:: For Mac OS: https://github.com/zammad/zammad-docker/issues/27#issuecomment-455171752 +.. tip:: For Mac OS: https://github.com/zammad/zammad-docker/issues/27#issuecomment-455171752 Start Zammad using DockerHub images diff --git a/install-elasticsearch.rst b/install/elasticsearch.rst similarity index 99% rename from install-elasticsearch.rst rename to install/elasticsearch.rst index 292fe021..fdaf4413 100644 --- a/install-elasticsearch.rst +++ b/install/elasticsearch.rst @@ -1,5 +1,3 @@ -.. _install_elasticsearch: - Set up Elasticsearch ******************** diff --git a/elasticsearch/indexed-attributes.rst b/install/elasticsearch/indexed-attributes.rst similarity index 100% rename from elasticsearch/indexed-attributes.rst rename to install/elasticsearch/indexed-attributes.rst diff --git a/install-kubernetes.rst b/install/kubernetes.rst similarity index 74% rename from install-kubernetes.rst rename to install/kubernetes.rst index 475bca53..9a153fd0 100644 --- a/install-kubernetes.rst +++ b/install/kubernetes.rst @@ -1,7 +1,7 @@ Install on Kubernetes via Helm ****************************** -.. Warning:: We currently do not support Kubernetes installations in productive use. +.. warning:: We currently do not support Kubernetes installations in productive use. Kubernetes_ (k8s) is an open-source system for automating deployment, scaling, and management of containerized applications. @@ -19,17 +19,10 @@ The used Docker images are hosted on `Dockerhub > /opt/zammad/.bashrc + + +Create MySQL user zammad (for Debian: upgrade MySQL to v5.6+ before, see: http://dev.mysql.com/downloads/repo/apt/) +------------------------------------------------------------------------------------------------------------------- + +.. code-block:: sh + + $ mysql --defaults-extra-file=/etc/mysql/debian.cnf -e "CREATE USER 'zammad'@'localhost' IDENTIFIED BY 'Your_Pass_Word'; GRANT ALL PRIVILEGES ON zammad_prod.* TO 'zammad'@'localhost'; FLUSH PRIVILEGES;" + +Get Zammad +---------- + +.. code-block:: sh + + $ su - zammad + $ curl -O https://ftp.zammad.com/zammad-latest.tar.gz + $ tar -xzf zammad-latest.tar.gz + $ rm zammad-latest.tar.gz + + +Install environnment +-------------------- + +.. code-block:: sh + + $ gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 + $ curl -L https://get.rvm.io | bash -s stable + $ source /opt/zammad/.rvm/scripts/rvm + $ echo "source /opt/zammad/.rvm/scripts/rvm" >> /opt/zammad/.bashrc + $ echo "rvm --default use 2.5.5" >> /opt/zammad/.bashrc + $ rvm install 2.5.5 + $ gem install bundler + +Install Zammad +-------------- + +.. code-block:: sh + + $ bundle install --without test development postgres + $ cp config/database/database.yml config/database.yml + +* insert mysql user, pass & change adapter to mysql2 & change database to zammad_prod + +.. code-block:: sh + + $ vi config/database.yml + +.. code-block:: sh + + $ rake db:create + $ rake db:migrate + $ rake db:seed + $ rake assets:precompile + +Start Zammad +------------ + +.. code-block:: sh + + $ rails s -p 3000 &>> log/zammad.log & + $ script/websocket-server.rb start &>> log/zammad.log & + $ script/scheduler.rb start &>> log/zammad.log & + + + +Create Nginx Config & restart Nginx +----------------------------------- + +.. code-block:: sh + + $ exit + $ cp /opt/zammad/contrib/nginx/zammad.conf /etc/nginx/sites-available/zammad.conf + +* change servername "localhost" to your domain if your're not testing localy + +.. code-block:: sh + + $ vi /etc/nginx/sites-available/zammad.conf + $ ln -s /etc/nginx/sites-available/zammad.conf /etc/nginx/sites-enabled/zammad.conf + $ systemctl restart nginx + + +Go to http://localhost and you'll see: +-------------------------------------- + +* "Welcome to Zammad!", there you need to create your admin user and invite other agents. + + + +on Mac OS 10.8 +============== + +Prerequisites +------------- + +* Install Xcode from the App Store, open it -> Xcode menu > Preferences > Downloads -> install command line tools + +.. code-block:: sh + + $ curl -L https://get.rvm.io | bash -s stable --ruby + $ source ~/.rvm/scripts/rvm + $ start new shell -> ruby -v + +Get Zammad +---------- + +.. code-block:: sh + + $ test -d ~/zammad/ || mkdir ~/zammad + $ cd ~/zammad/ + $ curl -L -O https://ftp.zammad.com/zammad-latest.tar.bz2 | tar -xj + + +Install Zammad +-------------- + +.. code-block:: sh + + $ cd zammad-latest + $ bundle install + $ sudo ln -s /usr/local/mysql/lib/libmysqlclient.18.dylib /usr/lib/libmysqlclient.18.dylib # if needed! + $ rake db:create + $ rake db:migrate + $ rake db:seed + + +Database connect +---------------- + +.. code-block:: sh + + $ cd zammad-latest + $ cp config/database/database.yml config/database.yml + $ rake db:create + $ rake db:migrate + $ rake db:seed + +Start Zammad +------------ + +.. code-block:: sh + + $ puma -p 3000 # application web server + $ script/websocket-server.rb start # non blocking websocket server + $ script/scheduler.rb start # generate overviews on demand, just send changed data to browser + + +Visit Zammad in your browser +---------------------------- + +* http://localhost:3000/#getting_started diff --git a/install/suse.rst b/install/suse.rst new file mode 100644 index 00000000..8974c4dc --- /dev/null +++ b/install/suse.rst @@ -0,0 +1,111 @@ +Install on SUSE via RPM +*********************** + +.. note:: Currently we support SLES 12 and OpenSUSE with versions 42.2 and 42.3 + +.. warning:: OpenSUSE LEAP 15.0 hasn't been tested yet, but should work as well. + + +Install dependencies +==================== + +Setup Elasticsearch +------------------- + +Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. +Please take a look at the following page: :doc:`/install/elasticsearch` . + + +nginx on SLES12 +--------------- + +.. code-block:: sh + + $ sudo zypper addrepo "http://nginx.org/packages/sles/12" "nginx" + + +Add Zammad RPM repo and install +=============================== + +.. code-block:: sh + + $ sudo zypper install wget + $ sudo wget -O /etc/zypp/repos.d/zammad.repo https://dl.packager.io/srv/zammad/zammad/stable/installer/sles/12.repo + $ sudo zypper install zammad + + + +Go to http://localhost and you'll see: +====================================== + +* "Welcome to Zammad!", there you need to create your admin user and invite other agents. + +Note: Make sure that the firewall is not blocking port 80 (configure firewall via "yast firewall" or stop it via "systemctl stop SuSEfirewall2"). + + +Change your webserver configuration (non localhost connections): +================================================================ + +Add your fully qualified domain name or public IP to server name directive in your web server configuration and restart your web server. +The installer will give you a hint where Zammad's web server config file is located. + +nginx +-------- + +.. warning:: Please **do not rename** the webserver config file for nginx or apache. + The update process will re create it, if it does not exist! + + +:: + + # /etc/nginx/sites-enabled/zammad.conf + + server { + listen 80; + + # replace 'localhost' with your fqdn if you want to use zammad from remote + server_name localhost; + + +You can manage the Zammad services manually: +============================================ + +Zammad +------ + +.. code-block:: sh + + $ sudo systemctl status zammad + $ sudo systemctl stop zammad + $ sudo systemctl start zammad + $ sudo systemctl restart zammad + +Only web application server +--------------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-web + $ sudo systemctl stop zammad-web + $ sudo systemctl start zammad-web + $ sudo systemctl restart zammad-web + +Only worker process +------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-worker + $ sudo systemctl stop zammad-worker + $ sudo systemctl zammad-worker + $ sudo systemctl restart zammad-worker + +Only websocket server +--------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-websocket + $ sudo systemctl stop zammad-websocket + $ sudo systemctl start zammad-websocket + $ sudo systemctl restart zammad-websocket diff --git a/install/ubuntu.rst b/install/ubuntu.rst new file mode 100644 index 00000000..10743dba --- /dev/null +++ b/install/ubuntu.rst @@ -0,0 +1,144 @@ +Install on Ubuntu via DEB +************************* + +.. note:: We currently support Ubuntu 16.04 LTS and 18.04 LTS. + + +Prerequisites +============= + +Be sure to use an UTF-8 locale or PostgreSQL will not install. + + +Setup Elasticsearch +------------------- + +Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. +Please take a look at the following page: :doc:`/install/elasticsearch` . + + +Check locale +------------ + +.. code-block:: sh + + $ locale + +If there is nothing with UTF-8 in the name shown like "LANG=en_US.UTF-8" you have to set a new locale. + +Set locale +---------- + +.. code-block:: sh + + $ apt-get install apt-transport-https locales sudo wget + $ locale-gen en_US.UTF-8 + $ echo "LANG=en_US.UTF-8" > /etc/default/locale + + +Add Zammad DEB Repo +=================== + +Ubuntu 16.04 +------------ + +.. code-block:: sh + + $ wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - + $ sudo wget -O /etc/apt/sources.list.d/zammad.list \ + https://dl.packager.io/srv/zammad/zammad/stable/installer/ubuntu/16.04.repo + + + +Ubuntu 18.04 +------------ + +.. code-block:: sh + + $ wget -qO- https://dl.packager.io/srv/zammad/zammad/key | sudo apt-key add - + $ sudo wget -O /etc/apt/sources.list.d/zammad.list \ + https://dl.packager.io/srv/zammad/zammad/stable/installer/ubuntu/18.04.repo + + +Install on Ubuntu (16.04 and 18.04) +----------------------------------- + +.. code-block:: sh + + $ sudo apt-get update + $ sudo apt-get install zammad + +Note: You might need to apt-get install wget apt-transport-https for the above instructions to work. + + +Go to http://localhost and you'll see: +====================================== + +* "Welcome to Zammad!", there you need to create your admin user and invite other agents. + + +Change your webserver configuration (non localhost connections): +================================================================ + +Add your fully qualified domain name or public IP to server name directive in your web server configuration and restart your web server. +The installer will give you a hint where Zammad's web server config file is located. + +nginx +-------- + +.. warning:: Please **do not rename** the webserver config file for nginx or apache. + The update process will re create it, if it does not exist! + +:: + + # /etc/nginx/sites-enabled/zammad.conf + + server { + listen 80; + + # replace 'localhost' with your fqdn if you want to use zammad from remote + server_name localhost; + + +You can manage the Zammad services manually: +============================================ + +Zammad +------ + +.. code-block:: sh + + $ sudo systemctl status zammad + $ sudo systemctl stop zammad + $ sudo systemctl start zammad + $ sudo systemctl restart zammad + +Only web application server +--------------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-web + $ sudo systemctl stop zammad-web + $ sudo systemctl start zammad-web + $ sudo systemctl restart zammad-web + +Only worker process +------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-worker + $ sudo systemctl stop zammad-worker + $ sudo systemctl start zammad-worker + $ sudo systemctl restart zammad-worker + +Only websocket server +--------------------- + +.. code-block:: sh + + $ sudo systemctl status zammad-websocket + $ sudo systemctl stop zammad-websocket + $ sudo systemctl start zammad-websocket + $ sudo systemctl restart zammad-websocket diff --git a/install-univention.rst b/install/univention.rst similarity index 77% rename from install-univention.rst rename to install/univention.rst index c4a3847d..172327f5 100644 --- a/install-univention.rst +++ b/install/univention.rst @@ -1,7 +1,7 @@ Installation on Univention Corporate Server via App Center ********************************************************** -.. Note:: As Zammad is using Docker Compose for Univention Corporate Server, the minimum requirement is UCS 4.3-2 errata 345. +.. note:: As Zammad is using Docker Compose for Univention Corporate Server, the minimum requirement is UCS 4.3-2 errata 345. Univention Corporate Server (UCS) is an enterprise server with focus on identity and infrastructure management. With its marketplace called App Center it can easily extended by solutions like Zammad that benefit from integrations with the LDAP directory service and the mail infrastructure. @@ -18,7 +18,7 @@ The basic installation will already meet our requirement. You'll need the follow * You should at least have **2 CPU-Cores and 4GB of free RAM**. -.. Note:: Running the Zammad app with less than 4GB free RAM will lead to unexpected errors! +.. note:: Running the Zammad app with less than 4GB free RAM will lead to unexpected errors! You see, that's not much - so go a head with the installation. @@ -29,7 +29,7 @@ Installing Zammad The app installation itself is quite easy: Just open the App Center within UCS management system and search for ``Zammad``. Press ``Install``, accept our license agreement and wait for the installation to finish. -.. image:: images/univention/zammad-in-store.png +.. image:: /images/univention/zammad-in-store.png The installation will take about 5-15 minutes, depending on your hardware speed. Please give the installation the needed time and don't abort. During the @@ -37,9 +37,9 @@ automated setup there are some waits for services to come up. Please be patient! If it's finished, you can press ``open`` - you'll get to our Zammad Wizard. It helps you with the minimum of information we need. ( See ``First steps you should consider`` ) - -.. image:: images/univention/installed-zammad.png - + +.. image:: /images/univention/installed-zammad.png + Values we automatically change during the UCS-Setup --------------------------------------------------- @@ -47,35 +47,35 @@ Values we automatically change during the UCS-Setup In order to make the installation as complete and convenient as possible, we're changing the following default values to the following: .. csv-table:: Changes values during installation - :header: "value", "default value", "new value" - :widths: 10,20,20 - - "notification sender", "Notification Master ", "Zammad ³" - "maximum email size", "10 MB", "35 MB" - "FQDN", "{FQDN-of-UCS}", "{FQDN-of-UCS}:10412 ³" - "HTTP-Type", "", "https" - "Allow customer registration", "true", "false" - "LDAP configuration", "", "Full LDAP-Configuration prepared ²" - "LDAP activated", "", "false" + :header: "value", "default value", "new value" + :widths: 10,20,20 + "notification sender", "Notification Master ", "Zammad ³" + "maximum email size", "10 MB", "35 MB" + "FQDN", "{FQDN-of-UCS}", "{FQDN-of-UCS}:10412 ³" + "HTTP-Type", "", "https" + "Allow customer registration", "true", "false" + "LDAP configuration", "", "Full LDAP-Configuration prepared ²" + "LDAP activated", "", "false" -.. Note:: ² Please note that the Zammad-LDAP integration is pre filled with authentication data and the group mapping ``Zammad-Admin`` to the Admin-Role and ``Zammad-Agent`` to the Agent-Role. You can use those security groups. - LDAP synchronization is disabled during installation, as activating it would disable the installation wizard of Zammad, which is needed to setup your Zammad instance properly. +.. note:: ² Please note that the Zammad-LDAP integration is pre filled with authentication data and the group mapping ``Zammad-Admin`` to the Admin-Role and ``Zammad-Agent`` to the Agent-Role. You can use those security groups. + LDAP synchronization is disabled during installation, as activating it would disable the installation wizard of Zammad, which is needed to setup your Zammad instance properly. -.. Note:: ³ Please note that these settings are updated automatically, if you update FQDN and Port settings within the :ref:`ucs-app-settings` . + +.. note:: ³ Please note that these settings are updated automatically, if you update FQDN and Port settings within the :doc:`/install/univention/app-settings` . First steps you should consider =============================== The most important part is obvious: Run the wizard and insert the information for your admin account. -.. Warning:: If the email address is used within UCS, you need to ensure that your user account within UCS has the needed Admin-Group, as otherwise a LDAP synchronization will downgrade your user account to the setup role! +.. warning:: If the email address is used within UCS, you need to ensure that your user account within UCS has the needed Admin-Group, as otherwise a LDAP synchronization will downgrade your user account to the setup role! You can now enter your company name and upload a company logo, if you want to. (the company name is mandatory). The system URL has been set by our installation routine already, you should be good to continue without changing it. -.. Note:: Changing the system URL might lead to broken links within notification mails. +.. note:: Changing the system URL might lead to broken links within notification mails. For the notification sender, you should use SMTP, as the Docker container does not come with any sendmail or local MTA. If you choose local MTA, Zammad will not be able to send you any notifications. @@ -95,9 +95,9 @@ If you want to take advantage of UCS identity management integration, you need t You can now go to Admin-Settings -> Integration -> LDAP and simply activate LDAP. The first LDAP synchronization will start shortly thereafter - Zammad will then synchronize user account data with the UCS LDAP directory hourly. -.. Note:: You're free to change the group-role mapping at any time. See `Configuring LDAP integration `_ for more information. +.. note:: You're free to change the group-role mapping at any time. See `Configuring LDAP integration `_ for more information. -.. image:: images/univention/initial-setup-ucs.gif +.. image:: /images/univention/initial-setup-ucs.gif Further configuration @@ -121,5 +121,4 @@ The following sub pages might come in handy and help you to understand how the a univention/running-console-commands-on-univention univention/issues-you-might-encounter -.. Warning:: **Never** change any configurations the Zammad-App scripts create and work with! This will lead to unexpected issues and loss of configurations upon update! - +.. warning:: **Never** change any configurations the Zammad-App scripts create and work with! This will lead to unexpected issues and loss of configurations upon update! diff --git a/univention/app-settings.rst b/install/univention/app-settings.rst similarity index 71% rename from univention/app-settings.rst rename to install/univention/app-settings.rst index 5a4f0f2a..9d83c7a3 100644 --- a/univention/app-settings.rst +++ b/install/univention/app-settings.rst @@ -1,9 +1,7 @@ -.. _ucs-app-settings: - Univention App-Settings *********************** -.. Note:: The App-Settings part is only valid starting with App version 3.1.0-7. +.. note:: The App-Settings part is only valid starting with App version 3.1.0-7. Within the managment interface of Univention, you can change some access related settings: @@ -11,10 +9,10 @@ Within the managment interface of Univention, you can change some access related * Another Port * Other certificates beside the Univention certificate -.. Note:: Some settings require you to have a combination of the above settings. - If the combination of settings is not met, the update script will automatically revert these changes. +.. note:: Some settings require you to have a combination of the above settings. + If the combination of settings is not met, the update script will automatically revert these changes. - This ensures that your Univention Host stays operational. Please do not try to trick the scripts, it might cause outages. + This ensures that your Univention Host stays operational. Please do not try to trick the scripts, it might cause outages. If you're using the default settings, we'll empty the values of the text fields to reduce confusion. This is not a Bug, but a "Feature". @@ -26,24 +24,24 @@ Using another FQDN This consists of two settings: a selection and a text field. The default setting of the App is ``Default UCS-Hostname`` which will use the FQDN of the Univention-Host (and it's SSL-Certificate). -.. Note:: In order to use custom hostnames, please also ensure to use a custom certificate. +.. note:: In order to use custom hostnames, please also ensure to use a custom certificate. If you set ``Custom Hostname``, you'll need to enter a hostname in the text field below. Ensure that your Univention host can resolve the hostname (and it's pointing to the host in question!). -.. Note:: We won't create any DNS entries or certificates during this process. +.. note:: We won't create any DNS entries or certificates during this process. Using another Port ================== Currently you can choose between ``Default Highport`` and ``Port 8443``. -By default, we'll use Port ``10412`` for Zammad, if you decide for Port ``8443``, we'll handle the firewall steps needed and adjust +By default, we'll use Port ``10412`` for Zammad, if you decide for Port ``8443``, we'll handle the firewall steps needed and adjust the vHosts-Port. -.. Warning:: Please ensure that if you choose another Port, that it's not used already! We do not verify this! +.. warning:: Please ensure that if you choose another Port, that it's not used already! We do not verify this! -.. Note:: Please note that for technical reasons (how Univention and Zammad work) it's not possible to use Zammad on Port 443 or within a subdirectory. +.. note:: Please note that for technical reasons (how Univention and Zammad work) it's not possible to use Zammad on Port 443 or within a subdirectory. Using other certificates @@ -52,17 +50,17 @@ Using other certificates By default we're using the Univention-Host certificate (``Univention (default)``). In some cases (and especially if you're using custom hostnames) this might be troublesome. -.. Note:: You can use custom certificates without changing the hostname. +.. note:: You can use custom certificates without changing the hostname. -.. Warning:: We're not verifying if the certificates are valid in any way (e.g. still valid in time and if the hostname is inside). - This step might follow, but please be aware that this might lead to certificate issues. +.. warning:: We're not verifying if the certificates are valid in any way (e.g. still valid in time and if the hostname is inside). + This step might follow, but please be aware that this might lead to certificate issues. If you choose ``Let's Encrypt``, please ensure that you already have installed the ``Let's Encrypt App`` (by Univention GmbH) and also already aquired a certificate via it. If you're applying the settings, we'll check for the following two files::: - - /etc/univention/letsencrypt/signed_chain.crt - /etc/univention/letsencrypt/domain.key + + /etc/univention/letsencrypt/signed_chain.crt + /etc/univention/letsencrypt/domain.key If we can't find these, we'll revert to the default Univention certificate. @@ -71,5 +69,4 @@ You can also choose to use your very own certificate by selecting ``Custom Certi For this it's important to know, that we expect the certificate to be within a specific location (``/etc/univention/ssl/``). Within the two text fields, you'll need to provide the filenames of your certificate and your certificate-key. -These certificates can be kept in a subfolder. If we cannot find either of the two files, we reset the setting to the default Univention certificate. - +These certificates can be kept in a subfolder. If we cannot find either of the two files, we reset the setting to the default Univention certificate. diff --git a/univention/issues-you-might-encounter.rst b/install/univention/issues-you-might-encounter.rst similarity index 95% rename from univention/issues-you-might-encounter.rst rename to install/univention/issues-you-might-encounter.rst index 6f112ab3..4cace043 100644 --- a/univention/issues-you-might-encounter.rst +++ b/install/univention/issues-you-might-encounter.rst @@ -6,7 +6,7 @@ Below we have gathered information to problems that might occur in combination w Zammad can't communicate with external systems ---------------------------------------------- -In rare cases (sometimes even right after installation), Zammad won't be able to communicate with e.g. external +In rare cases (sometimes even right after installation), Zammad won't be able to communicate with e.g. external e-mail servers. Simply restart the Zammad app in the App Center module in the UCS management system and it should be enough to get it back working. @@ -21,8 +21,7 @@ To solve this, just go into the Univention app-settings (for Zammad-app) and app Customers can't click on the "Knowledge Base"-URL within the customer portal ---------------------------------------------------------------------------- +---------------------------------------------------------------------------- This currently can't be fixed, as Zammad is available via one Port only. The issue is described within `Issue 2628 `_ and a subject to fix. - diff --git a/install/univention/running-console-commands-on-univention.rst b/install/univention/running-console-commands-on-univention.rst new file mode 100644 index 00000000..5459763e --- /dev/null +++ b/install/univention/running-console-commands-on-univention.rst @@ -0,0 +1,30 @@ +Running console commands on an Univention-Host +============================================== + +In some cases you might need to access Zammads rails console on the Univention-Host. +For this, you'll need to get the correct container ID first. + +Univention will hold this information for you, you can get it like that: + +.. code-block:: sh + + $ ucr get appcenter/apps/zammad/container + +Now where we have our ID, you can run any command from the :doc:`/admin/console` section with either: + +.. code-block:: sh + + $ docker exec -i "{Container-ID}" rails r "{COMMAND}" + +or -if you need a console for more commands- by: + +.. code-block:: sh + + $ docker exec -i "{Container-ID}" rails c + + +.. note:: Please replace ``{Container-ID}`` in the above commands by the ID the first command returns. + Replace ``{COMMAND}`` by any rails command Zammad supports. + + +That's it! diff --git a/install-update.rst b/install/update.rst similarity index 57% rename from install-update.rst rename to install/update.rst index 755d9717..b064fe64 100644 --- a/install-update.rst +++ b/install/update.rst @@ -1,7 +1,7 @@ Updating Zammad *************** -.. Note:: Please backup your Zammad instance before update! You can learn how to back up Zammad on :ref:`backup-and-restore`. +.. note:: Please backup your Zammad instance before update! You can learn how to back up Zammad on :doc:`/appendix/backup-and-restore`. Source update ============= @@ -11,29 +11,33 @@ Source update You can directly download Zammad from https://ftp.zammad.com/ or use the direct URL to get the latest stable release via https://ftp.zammad.com/zammad-latest.tar.gz -:: +.. code-block:: sh - root@shell> cd /opt - root@shell> wget https://ftp.zammad.com/zammad-latest.tar.gz - root@shell> tar -C zammad -xzf zammad-latest.tar.gz - root@shell> chown -R zammad /opt/zammad - root@shell> su - zammad + $ cd /opt + $ sudo wget https://ftp.zammad.com/zammad-latest.tar.gz + $ sudo tar -C zammad -xzf zammad-latest.tar.gz + $ sudo chown -R zammad /opt/zammad + $ sudo su - zammad 2. Install all dependencies --------------------------- -:: +.. code-block:: sh - zammad@shell> cd zammad - zammad@shell> gem install bundler + zammad@host $ cd zammad + zammad@host $ gem install bundler -* For PostgreSQL (note, the option says "without ... mysql"):: - - zammad@shell> bundle install --without test development mysql +* For PostgreSQL (note, the option says "without ... mysql"): -* For MySQL (note, the option says "without ... postgres"):: - - zammad@shell> bundle install --without test development postgres +.. code-block:: sh + + zammad@host $ bundle install --without test development mysql + +* For MySQL (note, the option says "without ... postgres"): + +.. code-block:: sh + + zammad@host $ bundle install --without test development postgres 3. Stop Zammad services @@ -44,12 +48,12 @@ Stop the application server, websocket server and scheduler. 4. Upgrade your database ------------------------ -:: +.. code-block:: sh - zammad@shell> export RAILS_ENV=production - zammad@shell> export RAILS_SERVE_STATIC_FILES=true # only if you use no HTTP reverse proxy - zammad@shell> rake db:migrate - zammad@shell> rake assets:precompile + zammad@host $ export RAILS_ENV=production + zammad@host $ export RAILS_SERVE_STATIC_FILES=true # only if you use no HTTP reverse proxy + zammad@host $ rake db:migrate + zammad@host $ rake assets:precompile 5. Start Zammad services ------------------------ @@ -67,17 +71,17 @@ Update with RPM 1. Stop Zammad ---------------- -:: +.. code-block:: sh - shell> sudo systemctl stop zammad + $ sudo systemctl stop zammad 3. Update Zammad ---------------- -:: +.. code-block:: sh - shell> sudo yum update zammad + $ sudo yum update zammad **Note: The package will automatically execute maintenance tasks like database changes and will restart Zammad for you.** @@ -85,9 +89,9 @@ Update with RPM 4. Start Zammad ---------------- -:: +.. code-block:: sh - shell> sudo systemctl start zammad + $ sudo systemctl start zammad 5. Go and log in to Zammad @@ -105,27 +109,27 @@ Update with DEB 1. Stop Zammad ---------------- -:: +.. code-block:: sh - shell> sudo systemctl stop zammad + $ sudo systemctl stop zammad 3. Update Zammad ---------------- -:: +.. code-block:: sh - shell> apt-get update - shell> apt-get upgrade + $ apt-get update + $ apt-get upgrade **Note: The package will automatically execute maintenance tasks like database changes and will restart Zammad for you.** 4. Start Zammad ---------------- -:: +.. code-block:: sh - shell> sudo systemctl start zammad + $ sudo systemctl start zammad 5. Go and log in to Zammad @@ -134,5 +138,5 @@ Update with DEB Updating elasticsearch ====================== -If you want to upgrade your elasticsearch installation, please take a look at the `elasticsearch documentation `_ +If you want to upgrade your elasticsearch installation, please take a look at the `elasticsearch documentation `_ as it will have the most current information for you. diff --git a/migration-otrs.rst b/migration/otrs.rst similarity index 70% rename from migration-otrs.rst rename to migration/otrs.rst index 7b4331d6..d79efc79 100644 --- a/migration-otrs.rst +++ b/migration/otrs.rst @@ -4,7 +4,7 @@ from OTRS Install plugins on OTRS ======================= -.. Note:: Currently only passwords of OTRS >= 3.3 can be reused in Zammad! Passwords that were stored in another format than the default SHA2 are not possible to use. Users then have to use the password reset procedure. +.. note:: Currently only passwords of OTRS >= 3.3 can be reused in Zammad! Passwords that were stored in another format than the default SHA2 are not possible to use. Users then have to use the password reset procedure. Install Znuny4OTRS-Repo ----------------------- @@ -22,7 +22,7 @@ This is a dependency of the OTRS migration plugin * On OTRS 4: * https://addons.znuny.com/api/addon_repos/public/309/latest - + * On OTRS 3: * https://addons.znuny.com/api/addon_repos/public/142/latest @@ -51,7 +51,7 @@ Install OTRS migration plugin Import via Browser ================== -.. Note:: If your OTRS installation is rather huge, you might want to consider using the command line version of this feature. +.. note:: If your OTRS installation is rather huge, you might want to consider using the command line version of this feature. After installing Zammad, open http://localhost:3000 with your browser and follow the installation wizard. From there you're able to start the migration from OTRS. @@ -70,19 +70,19 @@ Stop all Zammad processes and switch Zammad to import mode (no events are fired If you installed the Zammad DEB or RPM package ---------------------------------------------- -:: +.. code-block:: sh - zammad run rails c + $ zammad run rails c If you installed from source ---------------------------- -:: +.. code-block:: sh - su zammad - cd /opt/zammad - rails c + $ su zammad + $ cd /opt/zammad + $ rails c Extending import time for big installations (optional) @@ -95,9 +95,10 @@ For importing via console ^^^^^^^^^^^^^^^^^^^^^^^^^ * open the file ``config/initializers/delayed_jobs_settings_reset.rb`` and add the following at the end of it: - :: - - Delayed::Worker.max_run_time = 7.days + + .. code-block:: ruby + + >> Delayed::Worker.max_run_time = 7.days * Restart the Zammad-Service (``systemctl restart zammad``) @@ -105,58 +106,59 @@ For importing via browser (not recommended on big installations) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Run below in a Zammad console and ensure to not close it during import: - :: - - Delayed::Worker.max_run_time = 7.days + .. code-block:: ruby + + >> Delayed::Worker.max_run_time = 7.days + + +.. note:: The above setting is only valid for the lifetime of the Zammad rails console. + If you close the console, the change is reset to the default value. -.. Note:: The above setting is only valid for the lifetime of the Zammad rails console. - If you close the console, the change is reset to the default value. - Enter the following commands in the rails console ------------------------------------------------- -:: +.. code-block:: ruby - Setting.set('import_otrs_endpoint', 'http://xxx/otrs/public.pl?Action=ZammadMigrator') - Setting.set('import_otrs_endpoint_key', 'xxx') - Setting.set('import_mode', true) - Import::OTRS.start + >> Setting.set('import_otrs_endpoint', 'http://xxx/otrs/public.pl?Action=ZammadMigrator') + >> Setting.set('import_otrs_endpoint_key', 'xxx') + >> Setting.set('import_mode', true) + >> Import::OTRS.start After the import is done switch Zammad back to non-import mode and mark the system initialization as done. -:: +.. code-block:: ruby - Setting.set('import_mode', false) - Setting.set('system_init_done', true) + >> Setting.set('import_mode', false) + >> Setting.set('system_init_done', true) Start all Zammad processes again. Done. Importing a diff ================ -.. Note:: This is only possible after finishing an earlier OTRS import **successful**. +.. note:: This is only possible after finishing an earlier OTRS import **successful**. In some cases it might be desirable to update the already imported data from OTRS. This is possible with the following commands. Enter the following commands in the rails console ------------------------------------------------- -:: +.. code-block:: ruby - Setting.set('import_otrs_endpoint', 'http://xxx/otrs/public.pl?Action=ZammadMigrator') - Setting.set('import_otrs_endpoint_key', 'xxx') - Setting.set('import_mode', true) - Setting.set('system_init_done', false) - Import::OTRS.diff_worker + >> Setting.set('import_otrs_endpoint', 'http://xxx/otrs/public.pl?Action=ZammadMigrator') + >> Setting.set('import_otrs_endpoint_key', 'xxx') + >> Setting.set('import_mode', true) + >> Setting.set('system_init_done', false) + >> Import::OTRS.diff_worker After the import is done switch Zammad back to non-import mode and mark the system initialization as done. -:: +.. code-block:: ruby - Setting.set('import_mode', false) - Setting.set('system_init_done', true) + >> Setting.set('import_mode', false) + >> Setting.set('system_init_done', true) Start all Zammad processes again. Done. @@ -169,22 +171,22 @@ First make sure all Zammad processes are stopped. After that reset your database If you installed the Zammad DEB or RPM package ---------------------------------------------- -:: +.. code-block:: sh - zammad run rake db:drop - zammad run rake db:create - zammad run rake db:migrate - zammad run rake db:seed + $ zammad run rake db:drop + $ zammad run rake db:create + $ zammad run rake db:migrate + $ zammad run rake db:seed If you installed from source ---------------------------- -:: +.. code-block:: sh - rake db:drop - rake db:create - rake db:migrate - rake db:seed + $ rake db:drop + $ rake db:create + $ rake db:migrate + $ rake db:seed After that your DB is reset and you can start the import right over. diff --git a/migration-zendesk.rst b/migration/zendesk.rst similarity index 100% rename from migration-zendesk.rst rename to migration/zendesk.rst diff --git a/prerequisites-hardware.rst b/prerequisites/hardware.rst similarity index 84% rename from prerequisites-hardware.rst rename to prerequisites/hardware.rst index b37de3f6..c0f4f0c2 100644 --- a/prerequisites-hardware.rst +++ b/prerequisites/hardware.rst @@ -17,4 +17,4 @@ For optimal performance up to 40 agents: Of course at the end it depends on acutal load of concurent agents and data traffic. -.. Note:: We can't suggest any disk space recommendations, as this highly depends on how you work. Zammad will always try to recognize the same attachments and store it just once. +.. note:: We can't suggest any disk space recommendations, as this highly depends on how you work. Zammad will always try to recognize the same attachments and store it just once. diff --git a/prerequisites-software.rst b/prerequisites/software.rst similarity index 91% rename from prerequisites-software.rst rename to prerequisites/software.rst index 50069720..06d933cf 100644 --- a/prerequisites-software.rst +++ b/prerequisites/software.rst @@ -24,28 +24,16 @@ If you're using the package install, the packages below will automatically insta .. warning:: Please note that upgrading from Zammad 2.8 and earlier might fail, because your system does not satisfy the new dependencies. Below installation commands will help you out (you can update normally afterwards) -Debian 8 & 9, Ubuntu 16.04 & 18.04 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: sh -:: + # Debian 8 & 9, Ubuntu 16.04 & 18.04 + $ apt-get install libimlib2 libimlib2-dev - apt-get install libimlib2 libimlib2-dev + # openSUSE + $ zypper install imlib2 imlib2-devel - -OpenSuSe -^^^^^^^^ - -:: - - zypper install imlib2 imlib2-devel - - -CentOS 7 -^^^^^^^^ - -:: - - yum install imlib2 imlib2-devel + # CentOS 7 + $ yum install imlib2 imlib2-devel 3. Database Server diff --git a/univention/running-console-commands-on-univention.rst b/univention/running-console-commands-on-univention.rst deleted file mode 100644 index 1f450ff7..00000000 --- a/univention/running-console-commands-on-univention.rst +++ /dev/null @@ -1,26 +0,0 @@ -Running console commands on an Univention-Host -============================================== - -In some cases you might need to access Zammads rails console on the Univention-Host. -For this, you'll need to get the correct container ID first. - -Univention will hold this information for you, you can get it like that:: - - ucr get appcenter/apps/zammad/container - - -Now where we have our ID, you can run any command from the :ref:`zammad-console` section with either:: - - docker exec -i "{Container-ID}" rails r "{COMMAND}" - -or -if you need a console for more commands- by:: - - docker exec -i "{Container-ID}" rails c - - -.. Note:: Please replace ``{Container-ID}`` in the above commands by the ID the first command returns. - Replace ``{COMMAND}`` by any rails command Zammad supports. - - -That's it! -