Workflows: Automatically add specific watchers and/or recipients to tickets

[loujacob66]

Hello,

On a much older version of Cerb, I had automations in place to automatically add watchers to tickets, based upon the org the original sender was aligned with, and where watchers of that org would then be added as watchers to any ticket opened by an original recipient was the originator of a ticket.

For example, I could have an Organization named ACME, and then have three agents set up as watchers on that Org. If a new ticket was created by [email protected], a VA would trigger and add all three agents, who were watchers on ACME, added as watchers to that ticket. Additionally, I had an additional component of the VA that could add [email protected] to that ticket as a recipient, and then Joe and Jane would both get an autoreply -- this way, multiple team members from a customer would know that one of them created a ticket and that the other could follow along, and that they did not accidentally create a redundant ticket.

How would I create a workflow that could add a predetermined list of people as "watchers" when a new ticket is created on a specific org? I don't see a builder capability that is quite as interactive as the older way of managing VAs.

Thanks!

[jstanden]

Hi Lou! That workflow will be very similar to: https://cerb.ai/workflows/cerb.email.org_by_hostname/

The automation event is: https://cerb.ai/docs/automations/events/mail.received/

Ticket records have an expansion key for org_watchers: https://cerb.ai/docs/records/types/ticket/

Here's an automation to add org watchers to their new tickets.

From Search >> Workflows >> (+) select (Empty) and paste:

workflow:
  name: cerb.email.org_watchers
  version: 2024-12-17T05:17:20Z
  description: Add org watchers to new tickets
  website: https://cerb.ai/resources/workflows/
  requirements:
    cerb_version: >=11.0 <11.1
    cerb_plugins: cerberusweb.core,
records:
  automation/automation_add_org_watchers:
    fields:
      name: cerb.email.org_watchers.addOrgWatchers
      extension_id: cerb.trigger.mail.received
      description: Add organization watchers to new tickets
      script@raw:
        start:
          outcome/isInvalid:
            if@bool:
              {{
                not is_new_ticket 
                or not message_ticket_org_id 
                or message_ticket_org_watchers is empty
              }}
            then:
              return:
          
          record.update:
            inputs:
              record_type: ticket
              record_id: {{message_ticket_id}}
              fields:
                links@list:
                  {% for worker_id in message_ticket_org_watchers|keys %}
                  worker:{{worker_id}}
                  {% endfor %}
      policy_kata@raw:
        commands:
          record.update:
            deny/type@bool: {{inputs.record_type is not record type ('ticket')}}
            allow@bool: yes
  automation_event_listener/listener_mail_received:
    fields:
      name: Ticket org watchers
      event_name: mail.received
      priority@int: 100
      is_disabled: 0
      event_kata@raw:
        automation/orgWatchers:
          uri: cerb:automation:cerb.email.org_watchers.addOrgWatchers
          disabled@bool:
            {{
              not is_new_ticket 
              or not message_ticket_org_id 
              or message_ticket_org_watchers is empty
            }}

Click the Continue button three times.

When a new ticket comes in and it's linked to an org, the org's watchers will be added to the ticket.

When I get a few free mins, I'll comment on this thread with a description of how the automation works.

The workflow here is just another "package" format. The actual components are an automation and an automation event listener.

[loujacob66]

Hi Jeff,

Thank you! This works really well. I will tinker a bit more to see how to use the same approach with other things.

Please add more info when you can!

Cheers

[jstanden]

Hi @loujacob66,

This workflow contains two records: an automation and an automation event listener.

Unlike bot behaviors in earlier versions of Cerb, automations don't run automatically just by existing. Instead they are triggered -- usually from an event or toolbar.

Since automations can take custom inputs, this means you can reuse a single automation in several places with slightly different inputs. For instance, a single auto-responder automation used by different groups that uses a custom snippet to pick the right template.

An automation "binds" to an event or toolbar with conditional logic. With bot behaviors, they had to invoke and use logic to determine if they were needed. With automations, the event binding can enable or disable a set of automations without having to invoke them first.

Since v11.0+, automation event "listeners" and toolbar "sections" sit between automations and those triggers. They are basically just chunks of bindings that are concatenated together at runtime based on their "priority" (1 before 100). But their advantage is that they allow a workflow (like this one) to own an entire event listener or toolbar section; rather than mixing everything together and trying to make partial updates.

The event listener in this workflow is mail.received, which triggers when a new inbound message is received after filtering and routing have run. It's a convenient way to react to only new client messages. The listener defines only one automation, cerb.email.org_watchers.addOrgWatchers, and disabled@bool: sets the conditions where the automation would be ignored. We do this because all defined automations are enabled by default.

In this case, the automation does not trigger for the event if:

• The message is not opening a new ticket (i.e. it is a reply)
• or, the message's parent ticket has no organization linked
• or, the message ticket's organization has no watchers linked

When those disabled conditions don't match, the automation is invoked for the message.

The automation itself is based on the mail.received trigger, which is like a spec for the expected inputs and outputs. In this case, inputs are both the message_ placeholders (with key expansion, like message_ticket_org_id), and any custom inputs defined within the automation. Custom inputs: would be passed from the listener, and we don't use them here.

Automations, event bindings, and workflows are all written in our KATA syntax. It's similar to YAML but without all the headaches.

A KATA document is a hierarchical dictionary of keys and values. Keys indented below other keys form a Parent->Child relationship. Keys at the same level of indentation are "siblings". The name of each sibling must be unique, and that's accomplished by appending an arbitrary /name to a command if it's used more than once.

Unlike YAML, which haphazardly converts your values to different data types in an attempt to be helpful, KATA treats all values as text (i.e. strings) by default. Consequently, values never need to be escaped.

Instead, you can tag one or more @annotations to a key to tell KATA how to treat a value. For instance, number@int: 123 would format the number key's value of 123 as an integer.

Every annotation also supports multiple-line values indented one level below their key.

comment@text:
  This is a multiple line value indented
  one level below the parent key.

There are different "dialects" of KATA within Cerb: automations, events, maps, charts, etc.

Automation KATA treats its keys as commands to run.

When the cerb.email.org_watchers.addOrgWatchers automation runs, it begins at the start: command. That is the entry point for all automations regardless of their event. It invokes any child keys as commands.

The first child key is outcome/isInvalid:. The command is outcome (a conditional statement) and its name is isInvalid. This name can be anything -- in this case it's descriptive.

An outcome runs its then: branch if the value of its if@bool: statement is true. We repeat the same logic from the event listener here. This shouldn't be necessary if the listener bindings are set up correctly, but it's a good practice to abort early from the automation if invoked incorrectly. To abort here we use the return: command.

If the outcome doesn't match, we continue to the next command, which is record.update:. This provides a record_type, record_id, and list of fields to modify as its inputs:.

The only field we're providing is links:, which is a field for record links available on every record type. The @list annotation tells KATA we're going to provide a single item per line (we could have used @csv, @json, @key, etc.

Any value in KATA supports scripting. This is a syntax we build on top of the Twig templating language. For instance, {{placeholder}} and {% command %}.

The value of links is some scripting syntax that looks through all of the watchers on the ticket's org (message_ticket_org_watchers) and prints their ids in the format record_type: record_id.

That's it for the automation.

Finally, since automations can be generated -- for instance, by LLMs or other automations -- they are governed by a "policy" that sets boundaries on the commands they can use, and the resources available to those commands. They are access control lists, where the first true allow or deny statement wins.

In this policy, we have a deny statement if the target of record.update is anything other than a ticket. We then have an allow@bool: yes statement that allows the command in every other case. It may seem like this could just be a single allow statement, but it's a good practice to do it this way because you can have multiple deny statements in a row without requiring complex AND/OR logic between them.

The workflow itself is just a KATA syntax that groups versioned records together. If you were to change the Workflow KATA document and its workflow:version: at the top, you could update any instantiated copies of the workflow in any Cerb environment. Cerb will figure out what changed and make only those changes to the local environment. You can rollback undesirable changes to an earlier version as an atomic set (everything or nothing).

This allows you to iteratively build workflows in dev, test them in staging, and deploy them in production. It doesn't matter that the local IDs for each record are different in each environment, because Cerb will manage that for you.

You could write workflows by hand, and records like automations or widgets can be exported directly to that format. However, there's also a workflow builder when you create a new workflow that can convert any existing record into that format and keep it in sync with your changes. You can also "import" existing records into a new workflow for easier deployment and maintenance.

You can view the raw Workflow KATA for any built-in workflow from here:
https://github.com/cerb/cerb-release/tree/v11.0/features/cerberusweb.core/workflows

In Cerb, you can open the automation editor to get a feel for how they work.

The Visualization tab shows a DAG (directed acyclic graph):

You can click on a node to jump directly to that part of the code w/o a ton of scrolling.

At the top of the editor you can also enable code "folding":

For instance, folding to level 2 makes it much easier to get an overview of an automation's logic:

You can then expand only the branch you're interested in.

The Run tab allows you to simulate the automation and see its entire internal state on the right. This is similar to how Jupyter notebooks work with Python. You don't have to save changes to an automation before running it.

Let me know if any part of this could use more detail. :) I'm hoping to find time in 2025 to put it into a course somewhere (Udemy, etc). :)