diff --git a/.rstcheck.cfg b/.rstcheck.cfg index a3f3d2eb..3dcf6d35 100644 --- a/.rstcheck.cfg +++ b/.rstcheck.cfg @@ -2,7 +2,8 @@ report_level=WARNING ignore_directives = mermaid, - tabs + tabs, + video ignore_roles= docs, user-docs diff --git a/guides/additional-customization.rst b/guides/additional-customization.rst new file mode 100644 index 00000000..b5a75ea8 --- /dev/null +++ b/guides/additional-customization.rst @@ -0,0 +1,122 @@ +Additional Customization +======================== + +You can find useful customization options on this page. They mainly refer to +the actual section in the documentation and should give you an idea what could +be useful. +It is recommended to follow the basic configuration of Zammad first, as +described in the :doc:`start-with-zammad` section. + +Create Custom Field +------------------- + +Zammad allows you to easily add new fields for different objects like tickets +users and groups. You want to have a ticket category field where your agents +can select from pre-defined categories? No problem! You can even set it to +required to have a proper base for statistics. + +Head over to the :doc:`object attributes page ` where it is +explained in detail. + +.. or watch the video about how to create a mandatory category field for tickets. +.. ADD VIDEO HERE. + +Set Up Automation +----------------- + +There are different ways in Zammad how to automate things. Namely +:doc:`triggers `, :doc:`schedulers ` and +:doc:`macros `. In simple terms, the execution of a trigger is +action based, the execution of a scheduler job is time based and the execution +of a macro is done manually (without a condition). + +By default, there is already one active trigger which sends out auto-reply +emails to customers after they contacted you in a new support case. You can even +define in the channel configuration, to which group specific messages should be +dispatched to and what attributes you want to set for those tickets. You can +find it in the :doc:`Filter ` tab in the email based +channels. + +.. The following video shows three examples: + +.. - An automatic deletion of old tickets and customers via scheduler +.. - An email rule (postmaster filter) for a specific customer +.. - A trigger to increase priority for tickets when a specific organization member +.. is involved. + +.. ADD VIDEO HERE. + +Add Text Modules +---------------- + +:doc:`Text modules ` are a nice time saver for your agents. +In case they answer similar questions over and over again and/or you want to +unify their answers, add text modules for that. Your agents can then fetch a +text by typing :kbd:`:` :kbd:`:` in the editor, followed by the name or content +of the text module. You can even use variables to automatically include ticket- +or customer specific text like ticket title or customer name. Just type +:kbd:`:` :kbd:`:` in the text module content editor to search for available +variables. + +.. The video shows how to create a text module, including usage of variables and +.. how it works for agents when dealing with a ticket. + +.. ADD VIDEO HERE. + +Enable Checklist Feature +------------------------ + +Zammad's :doc:`checklist feature ` allows you to keep track +of certain tasks in a ticket. The feature allows you to create checklist +templates and link to other tickets as checklist item too. In case an agent +wants to close a ticket which still has open checklist items, a dialog asks +if the agents really wants to close it. + +.. See how to set it up, create a template and reference to another ticket in a +.. checklist item in the video. + +.. ADD VIDEO HERE. + +Add AI Agents +------------- + +:doc:`AI agents ` can work on specific routine tasks and relieve +your agents so they can concentrate on more important things. To break the +configuration down: + +- Prerequisite: add an AI provider +- Create an AI agent with the type of task you want to delegate +- Call the AI agent in a trigger or scheduler job + +.. The video shows an example of how to set up an AI agent which rewrites the +.. title of a ticket. A use case for this is when your customers often tend to use +.. generic titles (like "problem") or you receive tickets from a web form which +.. all have the same title. + +.. ADD VIDEO HERE (created). + +Next Steps +---------- + +Depending on your use case, you might want to adjust more things. Have a look +at the left navigation menu where you can find a detailled explanation of +all features in Zammad. + +- To provide more ways for your customers to contact you, add additional + channels like :doc:`/channels/whatsapp/index` and :doc:`/channels/sms`. +- Leverage productivity by: + + - Automate additional things via :doc:`/manage/trigger`, + :doc:`/manage/scheduler` and :doc:`/manage/macros` + - Use additional :doc:`AI features ` to relieve your agents so + they can focus on more important tasks. + +- In case you want to bill the support provided, use the + :doc:`time accounting ` feature +- Add and customize your :doc:`overviews ` for agents. This + is useful for team leaders or in case your needs are not covered by the + default overviews. +- And don't forget to sign up for our + `cloud services `_ or get in touch with our + `sales colleagues `_ about a support contract + for self-hosting Zammad. diff --git a/guides/start-with-zammad.rst b/guides/start-with-zammad.rst new file mode 100644 index 00000000..5a998ca9 --- /dev/null +++ b/guides/start-with-zammad.rst @@ -0,0 +1,150 @@ +Start With Zammad +================= + +This page covers a guide about how to configure basic settings in Zammad. To +find more details about the features and their configuration, have a look at +the navigation menu or follow the provided links. + +What is Zammad? +--------------- + +Zammad is a ticketing and helpdesk software which helps you manage your +communication with customers and internal departments. Like a shared inbox +with superpowers. Even without advanced configuration, Zammad helps you working +much more structured and transparent and avoids duplicate work. If you deal with +third party communication with more than one person (which is not recommended, +though), Zammad is your go-to solution and improves your communication a lot. + +Concept +------- + +It is all about tickets. A ticket is a central entity which holds all information +of a customer request in one place. Such a ticket is created when someone +gets in touch with you by sending a message or manually by support agents when +they receive a call from a customer. A ticket includes every conversation part +as an article. + +Zammad can be invisible to customers and doesn't require your customers to use +the system at all (but they can, if you allow them to). You just connect a +communication channel and the customer requests are created as tickets in Zammad. + +Your colleagues who work on tickets are called agents in Zammad. By default, +Zammad ships three roles. Two of them are for internal users (admin, agent). +When a new tickets gets created and the email address is not yet known to Zammad, +it automatically creates a user with the customer role, which is the third one. + +The relation between users, roles and groups should be clear when you follow +this guide. However, you can find a visual representation in the following +image. If this is confusing for you currently, just ignore it and read on in +this page. + +.. figure:: /images/guides/roles-permissions.svg + +And just a note at this point so you are aware: Zammad allows you to automate +many tasks. Keywords are :doc:`/manage/trigger`, :doc:`/manage/scheduler` and +:doc:`/manage/macros`. However, we recommend to follow this guide first and +then do the advanced configuration. + +Basic Setup +----------- + +Follow the steps below for a simple setup of Zammad. You can add some +information via getting started wizard or skip the steps and configure it +afterwards. + +The guide assumes your Zammad is not yet configured. In case you see the +getting started wizard, provide as much information as you desire or skip it +for later configuration. + +.. The video below shows an example with providing minimal information in the wizard. +.. ADD VIDEO HERE. + +Company Details +^^^^^^^^^^^^^^^ + +The basic customization step in Zammad is to add your company name and your +logo. If not already set in the getting started wizard, visit Zammad's admin +settings and go to *Settings > Branding* to adjust it. Additional information +on this topic can be found in the +:doc:`branding settings section `. + +Create Groups +^^^^^^^^^^^^^ + +A group in Zammad typically represents a department of a company. You can define +which agent has access to which group and define permissions. A group can +have a specific email address and department name. Use the default shipped +**Users** group by renaming it. +At this point, just add your groups and give them a fitting name. Create A +structure in case you need it by setting parent groups. It is totally fine to +stay with one group too, of course. + +.. You can find a video about a simple group and role configuration in the next +.. section. + +Create or Modify Roles +^^^^^^^^^^^^^^^^^^^^^^ + +Zammad comes with three pre-defined :doc:`roles ` for +customers, agents and admins. A user can have one or more roles assigned. In a +role, you can define the application permissions (what areas/features are +accessible) as well as the access level to groups (read, create, change, +overview, full). These three roles should cover standard scenarios. In case you +wonder which additional roles could make sense, here are some examples: + +- Team leader +- Reporting person +- Knowledgebase editor + +You can assign application and group permissions to a specific user as well. In +case you expect more than one person with specific permissions, creating a role +may be a good idea. + +.. ADD VIDEO HERE. + +Connect Email Accounts to Zammad +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Depending on your used email system, follow the actual guide for it: + +- :doc:`Standard IMAP/SMTP ` +- :doc:`M365 Graph ` +- :doc:`M365 IMAP ` +- :doc:`Google Email ` + +After adding an email channel, create one or more signatures. You can use one +signature for many groups or create different signatures, depending on your +company's department structure. + +.. The following video shows a dummy email channel configuration as well as adding +.. email adresses and signatures to different groups. + +.. ADD VIDEO HERE. + +Configure Groups +^^^^^^^^^^^^^^^^ + +After setting up an email based channel, a revisiting of the groups is +indicated. Go to *Manage > Groups*, select each group and set an outbound email +adress as well as a signature. + +Create Agent Accounts +^^^^^^^^^^^^^^^^^^^^^ + +Create a :doc:`user ` for each of your support agents by +going to the first steps section and use the +**Invite agents/colleagues to help working on tickets** function. You can find +it by activating the **Dashboard** on the taskbar and switch to the +**First Steps** tab. +Make sure to assign the right role to each of the agents. +This step sends out invitation emails to your agents. + +.. ADD VIDEO HERE. + +Further Steps +------------- + +At this stage, you are ready to use Zammad in production and take advantage of +the collaboration and organization features. To customize it further, +follow the :doc:`additional customization guide ` or +read on in the specific documentation sections. diff --git a/images/guides/roles-permissions.svg b/images/guides/roles-permissions.svg new file mode 100644 index 00000000..93bea578 --- /dev/null +++ b/images/guides/roles-permissions.svg @@ -0,0 +1,90 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/index.rst b/index.rst index f6cad483..964e2500 100644 --- a/index.rst +++ b/index.rst @@ -6,6 +6,13 @@ Zammad Admin Documentation also :docs:`system ` and :user-docs:`user manuals ` available. +.. toctree:: + :maxdepth: 2 + :caption: Guides + + guides/start-with-zammad + guides/additional-customization + .. _manage-docs: .. toctree:: @@ -101,4 +108,4 @@ Zammad Admin Documentation misc/composer misc/object-conditions/index misc/first-steps - misc/zabbix \ No newline at end of file + misc/zabbix diff --git a/locale/admin-docs.pot b/locale/admin-docs.pot index 01c889b6..016b674b 100644 --- a/locale/admin-docs.pot +++ b/locale/admin-docs.pot @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Zammad Admin Documentation pre-release\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-24 09:43+0100\n" +"POT-Creation-Date: 2025-11-26 07:58+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -2575,8 +2575,8 @@ msgstr "" #: ../channels/email/settings.rst:2 #: ../channels/email/settings.rst:2 #: ../channels/email/settings.rst:2 -#: ../index.rst:56 -#: ../index.rst:56 +#: ../index.rst:63 +#: ../index.rst:63 #: ../manage/time-accounting.rst:15 #: ../system/integrations/checkmk/admin-panel-reference.rst:5 msgid "Settings" @@ -3739,6 +3739,7 @@ msgid "G Suite users may need to contact their administrators in order to add al msgstr "" #: ../channels/google/basic-setup.rst:2 +#: ../guides/start-with-zammad.rst:49 msgid "Basic Setup" msgstr "" @@ -5937,34 +5938,283 @@ msgstr "" msgid "After finishing this step, you can click on the **Finish** button in Zammad and you should now be ready to receive tickets from your WhatsApp channel!" msgstr "" -#: ../index.rst:11 -#: ../index.rst:11 +#: ../guides/additional-customization.rst:2 +msgid "Additional Customization" +msgstr "" + +#: ../guides/additional-customization.rst:4 +msgid "You can find useful customization options on this page. They mainly refer to the actual section in the documentation and should give you an idea what could be useful. It is recommended to follow the basic configuration of Zammad first, as described in the :doc:`start-with-zammad` section." +msgstr "" + +#: ../guides/additional-customization.rst:11 +msgid "Create Custom Field" +msgstr "" + +#: ../guides/additional-customization.rst:13 +msgid "Zammad allows you to easily add new fields for different objects like tickets users and groups. You want to have a ticket category field where your agents can select from pre-defined categories? No problem! You can even set it to required to have a proper base for statistics." +msgstr "" + +#: ../guides/additional-customization.rst:18 +msgid "Head over to the :doc:`object attributes page ` where it is explained in detail." +msgstr "" + +#: ../guides/additional-customization.rst:25 +msgid "Set Up Automation" +msgstr "" + +#: ../guides/additional-customization.rst:27 +msgid "There are different ways in Zammad how to automate things. Namely :doc:`triggers `, :doc:`schedulers ` and :doc:`macros `. In simple terms, the execution of a trigger is action based, the execution of a scheduler job is time based and the execution of a macro is done manually (without a condition)." +msgstr "" + +#: ../guides/additional-customization.rst:33 +msgid "By default, there is already one active trigger which sends out auto-reply emails to customers after they contacted you in a new support case. You can even define in the channel configuration, to which group specific messages should be dispatched to and what attributes you want to set for those tickets. You can find it in the :doc:`Filter ` tab in the email based channels." +msgstr "" + +#: ../guides/additional-customization.rst:50 +msgid "Add Text Modules" +msgstr "" + +#: ../guides/additional-customization.rst:52 +msgid ":doc:`Text modules ` are a nice time saver for your agents. In case they answer similar questions over and over again and/or you want to unify their answers, add text modules for that. Your agents can then fetch a text by typing :kbd:`:` :kbd:`:` in the editor, followed by the name or content of the text module. You can even use variables to automatically include ticket- or customer specific text like ticket title or customer name. Just type :kbd:`:` :kbd:`:` in the text module content editor to search for available variables." +msgstr "" + +#: ../guides/additional-customization.rst:67 +msgid "Enable Checklist Feature" +msgstr "" + +#: ../guides/additional-customization.rst:69 +msgid "Zammad's :doc:`checklist feature ` allows you to keep track of certain tasks in a ticket. The feature allows you to create checklist templates and link to other tickets as checklist item too. In case an agent wants to close a ticket which still has open checklist items, a dialog asks if the agents really wants to close it." +msgstr "" + +#: ../guides/additional-customization.rst:81 +msgid "Add AI Agents" +msgstr "" + +#: ../guides/additional-customization.rst:83 +msgid ":doc:`AI agents ` can work on specific routine tasks and relieve your agents so they can concentrate on more important things. To break the configuration down:" +msgstr "" + +#: ../guides/additional-customization.rst:87 +msgid "Prerequisite: add an AI provider" +msgstr "" + +#: ../guides/additional-customization.rst:88 +msgid "Create an AI agent with the type of task you want to delegate" +msgstr "" + +#: ../guides/additional-customization.rst:89 +msgid "Call the AI agent in a trigger or scheduler job" +msgstr "" + +#: ../guides/additional-customization.rst:99 +msgid "Next Steps" +msgstr "" + +#: ../guides/additional-customization.rst:101 +msgid "Depending on your use case, you might want to adjust more things. Have a look at the left navigation menu where you can find a detailled explanation of all features in Zammad." +msgstr "" + +#: ../guides/additional-customization.rst:105 +msgid "To provide more ways for your customers to contact you, add additional channels like :doc:`/channels/whatsapp/index` and :doc:`/channels/sms`." +msgstr "" + +#: ../guides/additional-customization.rst:107 +msgid "Leverage productivity by:" +msgstr "" + +#: ../guides/additional-customization.rst:109 +msgid "Automate additional things via :doc:`/manage/trigger`, :doc:`/manage/scheduler` and :doc:`/manage/macros`" +msgstr "" + +#: ../guides/additional-customization.rst:111 +msgid "Use additional :doc:`AI features ` to relieve your agents so they can focus on more important tasks." +msgstr "" + +#: ../guides/additional-customization.rst:114 +msgid "In case you want to bill the support provided, use the :doc:`time accounting ` feature" +msgstr "" + +#: ../guides/additional-customization.rst:116 +msgid "Add and customize your :doc:`overviews ` for agents. This is useful for team leaders or in case your needs are not covered by the default overviews." +msgstr "" + +#: ../guides/additional-customization.rst:119 +msgid "And don't forget to sign up for our `cloud services `_ or get in touch with our `sales colleagues `_ about a support contract for self-hosting Zammad." +msgstr "" + +#: ../guides/start-with-zammad.rst:2 +msgid "Start With Zammad" +msgstr "" + +#: ../guides/start-with-zammad.rst:4 +msgid "This page covers a guide about how to configure basic settings in Zammad. To find more details about the features and their configuration, have a look at the navigation menu or follow the provided links." +msgstr "" + +#: ../guides/start-with-zammad.rst:9 +msgid "What is Zammad?" +msgstr "" + +#: ../guides/start-with-zammad.rst:11 +msgid "Zammad is a ticketing and helpdesk software which helps you manage your communication with customers and internal departments. Like a shared inbox with superpowers. Even without advanced configuration, Zammad helps you working much more structured and transparent and avoids duplicate work. If you deal with third party communication with more than one person (which is not recommended, though), Zammad is your go-to solution and improves your communication a lot." +msgstr "" + +#: ../guides/start-with-zammad.rst:19 +msgid "Concept" +msgstr "" + +#: ../guides/start-with-zammad.rst:21 +msgid "It is all about tickets. A ticket is a central entity which holds all information of a customer request in one place. Such a ticket is created when someone gets in touch with you by sending a message or manually by support agents when they receive a call from a customer. A ticket includes every conversation part as an article." +msgstr "" + +#: ../guides/start-with-zammad.rst:27 +msgid "Zammad can be invisible to customers and doesn't require your customers to use the system at all (but they can, if you allow them to). You just connect a communication channel and the customer requests are created as tickets in Zammad." +msgstr "" + +#: ../guides/start-with-zammad.rst:31 +msgid "Your colleagues who work on tickets are called agents in Zammad. By default, Zammad ships three roles. Two of them are for internal users (admin, agent). When a new tickets gets created and the email address is not yet known to Zammad, it automatically creates a user with the customer role, which is the third one." +msgstr "" + +#: ../guides/start-with-zammad.rst:36 +msgid "The relation between users, roles and groups should be clear when you follow this guide. However, you can find a visual representation in the following image. If this is confusing for you currently, just ignore it and read on in this page." +msgstr "" + +#: ../guides/start-with-zammad.rst:43 +msgid "And just a note at this point so you are aware: Zammad allows you to automate many tasks. Keywords are :doc:`/manage/trigger`, :doc:`/manage/scheduler` and :doc:`/manage/macros`. However, we recommend to follow this guide first and then do the advanced configuration." +msgstr "" + +#: ../guides/start-with-zammad.rst:51 +msgid "Follow the steps below for a simple setup of Zammad. You can add some information via getting started wizard or skip the steps and configure it afterwards." +msgstr "" + +#: ../guides/start-with-zammad.rst:55 +msgid "The guide assumes your Zammad is not yet configured. In case you see the getting started wizard, provide as much information as you desire or skip it for later configuration." +msgstr "" + +#: ../guides/start-with-zammad.rst:63 +msgid "Company Details" +msgstr "" + +#: ../guides/start-with-zammad.rst:65 +msgid "The basic customization step in Zammad is to add your company name and your logo. If not already set in the getting started wizard, visit Zammad's admin settings and go to *Settings > Branding* to adjust it. Additional information on this topic can be found in the :doc:`branding settings section `." +msgstr "" + +#: ../guides/start-with-zammad.rst:72 +msgid "Create Groups" +msgstr "" + +#: ../guides/start-with-zammad.rst:74 +msgid "A group in Zammad typically represents a department of a company. You can define which agent has access to which group and define permissions. A group can have a specific email address and department name. Use the default shipped **Users** group by renaming it. At this point, just add your groups and give them a fitting name. Create A structure in case you need it by setting parent groups. It is totally fine to stay with one group too, of course." +msgstr "" + +#: ../guides/start-with-zammad.rst:86 +msgid "Create or Modify Roles" +msgstr "" + +#: ../guides/start-with-zammad.rst:88 +msgid "Zammad comes with three pre-defined :doc:`roles ` for customers, agents and admins. A user can have one or more roles assigned. In a role, you can define the application permissions (what areas/features are accessible) as well as the access level to groups (read, create, change, overview, full). These three roles should cover standard scenarios. In case you wonder which additional roles could make sense, here are some examples:" +msgstr "" + +#: ../guides/start-with-zammad.rst:95 +msgid "Team leader" +msgstr "" + +#: ../guides/start-with-zammad.rst:96 +msgid "Reporting person" +msgstr "" + +#: ../guides/start-with-zammad.rst:97 +msgid "Knowledgebase editor" +msgstr "" + +#: ../guides/start-with-zammad.rst:99 +msgid "You can assign application and group permissions to a specific user as well. In case you expect more than one person with specific permissions, creating a role may be a good idea." +msgstr "" + +#: ../guides/start-with-zammad.rst:106 +msgid "Connect Email Accounts to Zammad" +msgstr "" + +#: ../guides/start-with-zammad.rst:108 +msgid "Depending on your used email system, follow the actual guide for it:" +msgstr "" + +#: ../guides/start-with-zammad.rst:110 +msgid ":doc:`Standard IMAP/SMTP `" +msgstr "" + +#: ../guides/start-with-zammad.rst:111 +msgid ":doc:`M365 Graph `" +msgstr "" + +#: ../guides/start-with-zammad.rst:112 +msgid ":doc:`M365 IMAP `" +msgstr "" + +#: ../guides/start-with-zammad.rst:113 +msgid ":doc:`Google Email `" +msgstr "" + +#: ../guides/start-with-zammad.rst:115 +msgid "After adding an email channel, create one or more signatures. You can use one signature for many groups or create different signatures, depending on your company's department structure." +msgstr "" + +#: ../guides/start-with-zammad.rst:125 +msgid "Configure Groups" +msgstr "" + +#: ../guides/start-with-zammad.rst:127 +msgid "After setting up an email based channel, a revisiting of the groups is indicated. Go to *Manage > Groups*, select each group and set an outbound email adress as well as a signature." +msgstr "" + +#: ../guides/start-with-zammad.rst:132 +msgid "Create Agent Accounts" +msgstr "" + +#: ../guides/start-with-zammad.rst:134 +msgid "Create a :doc:`user ` for each of your support agents by going to the first steps section and use the **Invite agents/colleagues to help working on tickets** function. You can find it by activating the **Dashboard** on the taskbar and switch to the **First Steps** tab. Make sure to assign the right role to each of the agents. This step sends out invitation emails to your agents." +msgstr "" + +#: ../guides/start-with-zammad.rst:145 +msgid "Further Steps" +msgstr "" + +#: ../guides/start-with-zammad.rst:147 +msgid "At this stage, you are ready to use Zammad in production and take advantage of the collaboration and organization features. To customize it further, follow the :doc:`additional customization guide ` or read on in the specific documentation sections." +msgstr "" + +#: ../index.rst:9 +#: ../index.rst:9 +msgid "Guides" +msgstr "" + +#: ../index.rst:18 +#: ../index.rst:18 msgid "Manage" msgstr "" -#: ../index.rst:37 -#: ../index.rst:37 +#: ../index.rst:44 +#: ../index.rst:44 msgid "Channels" msgstr "" -#: ../index.rst:65 -#: ../index.rst:65 +#: ../index.rst:72 +#: ../index.rst:72 msgid "AI" msgstr "" -#: ../index.rst:76 +#: ../index.rst:83 msgid "API (System-Documentation)" msgstr "" -#: ../index.rst:76 -#: ../index.rst:76 +#: ../index.rst:83 +#: ../index.rst:83 #: ../misc/object-conditions/basics.rst:169 #: ../settings/system/index.rst:2 msgid "System" msgstr "" -#: ../index.rst:96 -#: ../index.rst:96 +#: ../index.rst:103 +#: ../index.rst:103 msgid "Misc" msgstr ""