10.1: Add a required custom fieldset on ticket replies using automations

[jstanden]

Introduction

In the Cerb 10.1 update, we added a mail.draft automation event for conditionally modifying the defaults on drafts when composing or replying.

In this guide we'll create an automation that adds a 'Classification' fieldset to every reply if the field isn't already set. We'll also require that the worker sets the custom field before sending.

Classification is a very common workflow where tickets are assigned a type, and reports can then visualize the breakdown of work being done. However, it's tedious for workers to remember to always add the fieldset.

We can use automations to make this workflow simpler.

Building the workflow

Creating a ticket classification fieldset

First, we'll need a custom fieldset for 'Classification' on tickets, with a 'Type' picklist of the kinds of tickets we receive.

We've prepared an example if you don't already have a fieldset for this. If you do, you can skip ahead to the next section.

Navigate to Setup >> Packages >> Import in Cerb.

Copy and paste the following package:

{
  "package": {
    
  },
  "records": [
    {
      "uid": "customfieldset_classification",
      "_context": "custom_fieldset",
      "name": "Classification",
      "context": "ticket",
      "owner__context": "app",
      "owner_id": 0
    },
    {
      "uid": "customfield_type",
      "_context": "custom_field",
      "name": "Type",
      "uri": "classification_type",
      "context": "ticket",
      "custom_fieldset_id": "{{{uid.customfieldset_classification}}}",
      "type": "D",
      "params": {
        "options": ["Billing Issue","Bug Report","Feature Request","Question","Sales Inquiry","Technical Support"]
      }
    }
  ]
}

Click the Import button.

You should see the following:

Using the classification fieldset on ticket replies

Normally, workers would have to manually add our new fieldset on every reply:

cerb_10_1_mail_draft_manual_fieldset.mp4

Fortunately, we can now automate this.

Automating adding a custom fieldset when replying

Creating the mail.draft automation

Navigate to Search >> Automations >> (+).

Field	Value
Name:	wgm.example.draft.addFieldset
Description:	Add a custom fieldset to all new reply drafts
Trigger:	mail.draft

Paste the following Script:

start:
  # Only on a reply with no custom field on ticket or draft
  outcome/notRequired:
    if@bool:
      {{
        draft_type != 'ticket.reply'
        or draft_ticket_classification_type is not empty
      }}
    then:
      return:
  
  return:
    draft:
      # See: https://cerb.ai/docs/records/types/draft/#records-api
      params:
        subject: Testing....!
        custom_fields:
          classification_type@text: (default)

Click the Save Changes button.

Binding the automation to the mail.draft event

Navigate to Search >> Automation Events and edit the mail.draft event.

Click the magnifying glass button in the toolbar above the event editor:

Select the wgm.example.draft.addFieldset automation we just created:

Click the blue Continue button.

This generates a binding on the event for the automation, like:

automation/y26z3j:
  uri: cerb:automation:wgm.example.draft.addFieldset
  #disabled@bool: yes

Let's customize the random name (y26z3j above) so it's more descriptive. We can also make the automation more efficient by only running it when the draft is new (and not resumed).

automation/addFieldset:
  uri: cerb:automation:wgm.example.draft.addFieldset
  disabled@bool:
    {{
      draft_type != 'ticket.reply'
      or draft_ticket_classification_type is not empty
    }}

Click the Save Changes button.

The automation will now run every time a new draft is created from the 'Reply' button, but only if the custom field isn't already set on the ticket.

Testing the automation

Navigate to Search >> Tickets and pick a ticket to reply to. Click on its subject to view its profile.

Click the Reply button on a message.

The custom fieldset is already enabled for us:

You can also set a proper default value (like "Question") in the automation. Any invalid value will default to the blank entry at the top of the list.

Requiring the custom field value

You may have noticed that even though we're defaulting the "Classification Type" custom field to enabled, we're not requiring that a value is selected before the message is sent.

We can optionally use another new feature in 10.1 for this -- a mail.draft.validate automation.

Navigate back to Search >> Automation Events and edit the mail.draft.validation event.

You may already have some automations bound to the event. Move the cursor to the bottom and click the magnifying glass button ("Find automation") in the toolbar:

This time we don't have an automation yet, so click the Create button above the list:

Enter the following field values:

Field	Value
Name:	wgm.example.draft.validate.ticketClassification
Description:	Require a ticket classification when replying
Trigger:	mail.draft.validate

Copy and paste the following KATA over the default start:

inputs:
  record/draft:
    record_type: draft
    required@bool: yes
    default@key: caller_params:draft_id

start:
  outcome/noFieldset:
    # If a reply, and the custom field isn't set on the ticket or draft
    if@bool:
      {{
        inputs.draft.type == 'ticket.reply'
        and not inputs.draft.ticket_classification_type
        and not inputs.draft.params.custom_fields_uri.classification_type
      }}
    then:
      await:
        form:
          title: Before you send...
          elements:
            say:
              content@text:
                This ticket needs classification
                =======
                You forgot to set the 'Classification Type' field.
            submit:
              buttons:
                continue:
                  label: I'll fix it!
      
      return:
        reject@bool: yes

Click the Save Changes button.

Select the new wgm.example.draft.validate.ticketClassification automation in the list and then click the blue Continue button.

This generates an automation event binding for us. We can finish it up like:

automation/requireClassification:
  uri: cerb:automation:wgm.example.draft.validate.ticketClassification
  inputs:
    draft@key: draft_id
  disabled@bool:
    {{
      draft_type != 'ticket.reply'
      or draft_params.custom_fields_uri.classification_type
    }}

This will run the automation for ticket replies when there is no 'Classification' custom field set.

Conclusion

You now know how to conditionally modify the default settings of a draft.

You also know how to require a custom field in certain conditions.