10.0: Send an email when tickets are closed using record.changed automations

[jstanden]

Introduction

A common workflow is sending an automated email message when a ticket is closed. For instance, sending a customer satisfaction survey after a resolution.

In earlier versions of Cerb this was accomplished with behaviors. In this guide you'll learn how to implement an improved version of the workflow using automations in the 10.0 update.

Build the automation

When you want to react to changes in field values on a record, create a record.changed automation.

Navigate to Search -> Automations as an administrator and click the (+) icon in the top right of the worklist to create a new one.

Use the following field values:

Field	Value
Name	wgm.example.ticketClosedAutoReply
Description	Send an email when tickets are closed
Trigger	record.changed

Now we can write the automation.

All automations begin at the start: command.

Unlike behaviors in earlier versions of Cerb, we don't have to add conditions to the top of our automation to specify when it should run. We'll do that when we bind our automation to the event later. We can simply start writing our logic.

If you expand the Inputs panel at the top, you'll notice we have placeholders for the changed record in was_record_ and record_. This allows us to refer to record fields and detect field transitions between certain values.

We'll be working with a ticket record, so we can refer to the available placeholder in the docs.

To send an email from automations we need to create a draft record and schedule it for delivery. This allows us to use all of Cerb's mail sending functionality (draft resumption, delivery retries, encryption, custom fields, #commands, etc).

The automation will also run faster, because it creates a queued draft record and stops. It doesn't have to wait for the email message to be delivered since that's handled in the background by the scheduler.

We could add our automated message to the ticket conversation, but this usually isn't desirable for auto-replies. Instead, we'll create a mail.transactional draft. This is an outgoing message that isn't saved in Cerb. For instance: auto-replies, notifications, surveys, invites, password resets, etc.

So let's start with:

start:
  record.create:
    output: new_draft
    inputs:
      record_type: draft
      # See: https://cerb.ai/docs/records/types/draft/
      fields:
        type: mail.transactional
        to: {{record_initial_message_sender_email}}
        name: Close auto-reply: {{record__label}}
        is_queued: 1
        queue_delivery_date@date: +5 mins
        params:
          to: {{record_initial_message_sender_email}}
          subject: Resolved: {{record__label}}
          headers:
            Auto-Submitted: auto-replied
            Precedence: bulk
          format: parsedown
          content@text:
            The following issue has been resolved:
            
            **{{record__label}}**
            
            Please reply to this message if you have any questions.
            
            -- 
            Example, Inc.
            <https://example.com>

This creates a draft to the initial sender of the ticket. It's scheduled for delivery in 5 mins.

We're also including headers to let the recipient know that this is an automated sender and their software should not auto-reply back to it.

You can modify the content@text: template above to meet your needs. Formatting is enabled by default, so you can use Markdown syntax.

Note that a draft can have a different name than the subject of the message being sent. This is useful to describe the source and purpose of a draft. We're prefixing the ticket subject with "Close auto-reply:".

Automations that modify data require permission in their policy.

At the bottom of the automation editor, select the Policy tab.

For now, we only need this automation to be able to create new draft records. Paste the following policy:

commands:
  record.create:
    deny/type@bool: {{inputs.record_type is not record type ('draft')}}
    allow@bool: yes

To properly test the automation, we also need to set the inputs that Cerb would normally provide for us on the event.

Find a ticket you want to test with from Search >> Tickets. We need the ticket's record ID, so click the gear icon in the top right of the search results and add the ID column.

Once you have an ID you can close the search results popup.

Select the Run tab at the bottom of the automation editor.

In the Inputs editor, paste the following:

record__context: ticket
record_id: 123

Replace 123 with the ID of the ticket you want to test with.

Click the Run button in the inputs editor:

You should see output like:

We didn't simulate the record creation with an on_simulate: option, so a new draft record was created by our test.

You can find it from Search >> Drafts.

We configured the automation to deliver these auto-replies in 5 minutes. This is useful in testing (giving you a chance to delete it), but it's also helpful for combating mail loops in a situation where you auto-reply to a mailbox that auto-replies back to you. The 5 minute delay throttles the responses and you can simply delete the outgoing draft to break the cycle.

The best prevention of mail loops is making sure any new ticket auto-reply automations check for an automated sender and avoid sending to them.

After inspecting this test draft, you can let it deliver or delete it.

Save the automation by clicking the Save Changes button at the bottom of the editor popup.

Configure the automation event

Now we have an automation that sends an automated email to the targeted ticket.

When using behaviors in earlier versions of Cerb, our code would start running right after we saved it. Automations work differently.

We need to bind our automation to an event in order for it to run. There can be multiple automations on an event, and they can be enabled or disabled conditionally each time the event runs based on its attributes. Depending on the event, it will use the first enabled automation, all enabled automations, or the first enabled automation to return: output.

The record.changed event runs all enabled automations.

In this case, we only want our code to run when a ticket record has its status changed to closed from any other status.

Navigate to Search >> Automation Events as an administrator.

Hover over the row for the record.changed event and click the button to open its editor popup.

Click Edit at the top of the popup.

In the automation event editor, click the first icon in the toolbar to find the automation you created earlier.

And select wgm.example.ticketClosedAutoReply:

Click the blue button to continue.

Currently, this would run our automation for any change on every record. We need to customize the disabled@bool: option to define our conditions ("scope").

Replace the event binding with the following:

automation/autoReplyOnTicketClose:
  uri: cerb:automation:wgm.example.ticketClosedAutoReply
  disabled@bool:
    {{
      record__type is not record type ('ticket')
      or record_status != 'closed'
      or was_record_status == 'closed'
    }}

That says our automation should be disabled when the record is not a ticket, or the ticket's new status isn't "closed", or the ticket's status was already "closed".

Some people have commented that writing inverse logic (what you don't want) is confusing.

If you feel the same way, you could also do something like this:

automation/autoReplyOnTicketClose:
  uri: cerb:automation:wgm.example.ticketClosedAutoReply
  disabled@bool:
    {{
      not (
        record__type is record type ('ticket')
        and record_status == 'closed'
        and was_record_status != 'closed'
      )
    }}

That does the same thing as the first binding, but it specifies exactly what we do want to match, then disables in the opposite case by wrapping the rules within not().

It's always a good idea to test your event binding before saving.

You can click the "potion" icon in the editor toolbar to open the tester:

This allows you to simulate placeholders and see which automations would run.

Paste the following placeholders:

record__type: ticket
record_status: closed
was_record_status: open

And click the run button in the tester:

This shows that our new automation would run when a ticket record is closed.

Change the placeholders to an event we don't care about, like:

record__type: task

or:

record__type: ticket
record_status: closed
was_record_status: closed

When you run the tester in those other cases, our automation doesn't run (as expected).

Click the Save Changes button to save the automation binding on the vent.

Testing the automation with live data

Finally, let's close a real ticket to verify that the new message is being sent automatically.

Navigate to Search >> Tickets and select a suitable ticket for closing (or create one).

You can close it from the worklist, its peek popup, or profile page. It shouldn't matter where the field change happens.

Navigate to Search >> Drafts and verify a new "Close auto-reply:" draft was created for that ticket in the past few seconds.

You're all set!

Conclusion

You learned about record.changed automations and how to conditionally bind them to the record.changed event. With this knowledge you can react to any field change on any record type.

You now know how to create mail.transactional drafts to send email from automations.

You also learned how to test automations and events before deploying them.