Fixes #967 - Optimize wording in triggers

manage/trigger.rst

@@ -1,30 +1,22 @@
 Triggers
 ========
 
-Use triggers to set up all kinds of **if-this-then-that** automation
-workflows. For time-based or recurring automation workflows, try
-:doc:`schedulers </manage/scheduler>` instead.
-
-The first thing to know about triggers is that **you're already using them**.
-From the moment you set up Zammad, it starts sending auto-replies
-to all incoming emails. Recognize this line?
-
-.. figure:: /images/manage/trigger/trigger-based-auto-reply-in-ticket-zoom.png
-   :alt: Screenshot of auto-reply notification in ticket view
-   :align: center
-   :scale: 70%
-
-It means that the ticket is from an incoming customer email and that the
-customer received this message in response:
-
-.. figure:: /images/manage/trigger/trigger-based-auto-reply-in-a-customer-mailbox.png
-   :alt: Screenshot of auto-reply in customer's inbox
-   :align: center
-   :scale: 80%
-
-This auto-reply message is a **trigger**.
-You can disable it, modify it, or create new ones
-for all sorts of automation tasks on the Trigger page of the admin panel:
+Triggers are one way to automate Zammad. You can create *if this then that*
+rules by defining which tickets should get changed and which changes you want
+to apply to them.
+
+In case you are looking for a time-based automation, use
+:doc:`scheduler jobs </manage/scheduler>` instead. To execute pre-defined
+changes manually via UI (without a condition), use :doc:`/manage/macros`
+instead.
+
+Zammad ships one active trigger by default: an auto reply trigger which sends an
+email to the customer after a new ticket is created. This leads to an article in
+the ticket. This article only displays the title and the recipient as a text
+string to maintain clarity in the ticket view.
+You can disable it, modify it or create new ones
+for all sorts of automation tasks in the **Triggers** section in the admin
+settings:
 
 .. figure:: /images/manage/trigger/trigger-management.png
    :alt: Screenshot of “Triggers” page in admin panel

manage/trigger/how-do-they-work.rst

@@ -1,24 +1,27 @@
 How Do Triggers Work
 ====================
 
-Triggers consist of three parts:
+Triggers consist mainly of three parts:
 
-* **Activators:** define "when the question is asked?"
-* **Conditions:** answer the question "when should this trigger fire?"
-* **Actions:** answer the question "what should happen when it does?"
+* **Activator:** defines when and how the trigger has to be evaluated.
+* **Condition:** defines the tickets for which an action has to be executed
+  based on attributes.
+* **Actions:** define what to change in a ticket which matches the condition.
 
 Triggers are evaluated in alphabetical order by **name.**
 In some situations, triggers might be the wrong choice, see
 :doc:`/manage/trigger/limitations` for more information.
 
-.. hint:: **🤓 Emails can adjust some behavior on their own**
+Activator
+---------
 
-   See :doc:`/channels/email/email-headers` for more information.
+Choose between an action- or time-based activator in the **Activated by**
+section.
 
-Activators
-----------
-
-Triggers support two types of activators:
+.. figure:: /images/manage/trigger/activator-of-a-trigger.png
+   :alt: Screenshot of activator section in trigger dialog.
+   :scale: 80%
+   :align: center
 
 Action
 ^^^^^^
@@ -28,63 +31,70 @@ update by an agent or even internal system updates like updated SLA times.
 See the explanation below for more details.
 
 Selective
-   Checks if any attribute from the condition was updated. If yes, the
-   trigger runs. If the attributes from the condition weren't touched, the
-   trigger doesn't run.
+   Checks if any attribute from the condition was updated OR an article was
+   added and the condition matches. If the attributes of the condition weren't
+   touched and no new article was added, the trigger doesn't run.
 
    **Example:** A trigger with a condition for priority **1 low** will run if
    the ticket was changed to **1 low**.
 
 Always
    Checks if the current state of the ticket matches the condition. This means:
-   the trigger always runs when the ticket is updated, no matter what was
-   changed. This can lead to executing such a trigger more often.
+   the trigger always runs when the ticket is updated and the condition matches,
+   no matter what was changed. This can lead to more often executions of such a
+   trigger.
 
    **Example:** A trigger with a condition for priority **1 low** will run if
    the ticket was moved to another group while priority was set **1 low**.
 
-   .. hint:: If in doubt, use **Selective**. The **Always** action activator can
-      lead to unexpected behavior, e.g. the trigger runs after internal system
-      changes of the ticket, which aren't visible in the ticket history.
+.. hint:: If in doubt, use **Selective**. The **Always** action activator can
+   lead to unexpected behavior, e.g. the trigger runs after internal system
+   changes of the ticket, which aren't visible in the ticket history.
 
 Time Event
 ^^^^^^^^^^
 
-The execution is triggered at a specific time when a certain event is
-reached, e.g. ticket pending time.
+The execution is triggered when one of the following events occur:
 
-This activator simply checks if **conditions** match.
-This is the same behavior as action-based activator's "always" mode.
+- Time of a reminder is reached
+- Escalation is reached
+- Escalation warning is reached
 
-When creating a trigger, choose activator here:
-
-.. figure:: /images/manage/trigger/activator-of-a-trigger.png
+When such a time event is reached, the trigger runs if the condition
+matches. This is the same behavior as action-based activator's "always" mode.
 
-Conditions
-----------
+Condition
+---------
 
-When creating a trigger, define your conditions here:
+Use one or more attributes and values in a condition, which the tickets have to
+match you want to apply changes to. Create your condition in the
+**Conditions for affected objects** section:
 
-   .. figure:: /images/manage/trigger/conditions-of-a-trigger.png
-
-Trigger conditions must match as configured for the trigger to fire.
+.. figure:: /images/manage/trigger/conditions-of-a-trigger.png
+   :alt: Screenshot of condition section in trigger dialog.
+   :scale: 80%
+   :align: center
 
 .. include:: /misc/object-conditions/conditioning-depth-hint.include.rst
 
-Actions
--------
+Action
+------
 
-When creating a trigger, define your changes here:
+Define which changes to apply for tickets which match your condition in the
+**Execute changes on objects** section:
 
-   .. figure:: /images/manage/trigger/actions-of-a-trigger.png
+.. figure:: /images/manage/trigger/actions-of-a-trigger.png
+   :alt: Screenshot of action section in trigger dialog.
+   :scale: 80%
+   :align: center
 
-.. hint:: Certain actions (such as *email*, *SMS* and *notes*) support
-   :doc:`/misc/variables`, which can be used to build
+.. hint:: Certain actions (such as email, SMS and notes) support
+   :doc:`/misc/variables` (see screenshot above), which can be used to build
    highly-customized message templates.
 
 A trigger can do the following things once its conditions have been met:
 
-* Modify the ticket
+Modify the ticket
    Examples: escalate its priority, close it, reassign it, rename it,
    add tags, subscribe and unsubscribe specific/all users, etc.
 
@@ -95,7 +105,7 @@ A trigger can do the following things once its conditions have been met:
    Remember that the placeholders' values have to be known during trigger
    runtime. Learn more about :doc:`/misc/variables`.
 
-* Send an email or SMS
+Send an email or SMS
    Either to the customer, the agent who owns the ticket, or every agent in
    the system.
 
@@ -106,14 +116,15 @@ A trigger can do the following things once its conditions have been met:
    an email address for the group, the trigger is working in. If you
    don't, Zammad will skip the trigger completely.
 
-* :doc:`Fire a webhook </manage/webhook>`
+:doc:`Fire a webhook </manage/webhook>`
    Connect Zammad to another web service or application to give it live updates
    about new tickets.
-* Add internal or public notes to the ticket
+
+Add internal or public notes to the ticket
    This allows you to help your agents with specific information if needed.
    (e.g. automated changes a trigger applied to the ticket)
 
-* :doc:`Run an AI agent </ai/ai-agents>`
+:doc:`Run an AI agent </ai/ai-agents>`
    Trigger an AI agent to run using triggers.
 
 .. _trigger-localization:

manage/trigger/limitations.rst

@@ -4,17 +4,16 @@ Limitations
 Triggers are one way of automated actions. In addition, there are also
 :doc:`scheduler </manage/scheduler>` and
 :doc:`postmaster filter </channels/email/filters>` based automation. Make sure
-to have a look at those, too. They can be more suitable, depending on your
+to have a look at those too. They can be more suitable, depending on your
 use case.
 
 Limitations of triggers:
 
 - Triggers are executed when a ticket is updated via clicking the "Update"
-  button. Changing a value without updating the ticket (e.g. setting a tag) will
-  not execute the trigger.
-- Triggers are always affecting the last article of a ticket. This means you
-  can't run triggers based on older articles.
-- Triggers always handle the current ticket attributes and the article
-  (if applicable) that causes the trigger to fire. A related object context
-  might not be available for performing changes.
+  button. Changing a value without updating the ticket (e.g. setting a tag) does
+  not lead to a trigger execution.
+- If a trigger runs due to an an  added article, the context for the trigger
+  is always this last article. Triggers aren't running based on older ticket
+  states or articles.
+- Related object attributes might not be available for performing changes.