10.0: Conditionally approve and deny record merges with automation events

[jstanden]

Introduction

Let's assume you only want to allow ticket records to be merged when they all share the same list of participants. In any other case you want to prevent the merge.

Cerb has a 'Ticket merge' permission in roles, but this just allows or denies the merge feature. It doesn't allow for custom business logic.

As of Cerb 10.0 you can implement this logic using the record.merge automation event.

In this guide we'll walk through setting this up.

Create an automation

First, we need an automation to implement our business logic.

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

Field	Value
Name:	wgm.merge.ticket.onlySameParticipants
Description:	Only allow tickets to be merged if they share the same participants
Trigger:	record.merge

Paste the following automation into the script editor:

start:
  # If these aren't ticket records, exit early
  outcome/notTickets:
    if@bool: {{record_type is not record type ('ticket')}}
    then:
      return:
  
  # Are the participant lists not identical?
  repeat/check:
    each@key: source_ids
    as: source_id
    do:
      outcome/notSameParticipants:
        if@bool:
          {{
            array_column(records[source_id].participants,'id')|sort|join(',') 
            is not same as 
            array_column(records[target_id].participants,'id')|sort|join(',')
          }}
        then:
          return:
            deny: The participants of merged tickets ({{array_column(records,'mask')|join(', ')}}) must be identical.

You can test the automation by pasting this input into the Input: window:

record_type: ticket
source_ids: [2,3]
target_id: 1
records:
  1:
    _context: ticket
    id: 1
  2:
    _context: ticket
    id: 2
  3:
    _context: ticket
    id: 3

__expandable:
- records.1
- records.2
- records.3

You can modify the IDs to meet your use case.

The __expandable key is a hint to the dictionary that those paths are sub-dictionaries. That means you can expand a placeholder like records[1].participants without doing any extra work. This is what happens with continuations.

When an automation event triggers outside of the simulator all of this is done for you.

You can also simulate participants in your test data (without key expansion) like:

record_type: ticket
source_ids: [2]
target_id: 1
records:
  1:
    _context: ticket
    id: 1
    mask: DEMO-001
    participants:
    - id: 1
    - id: 2
  2:
    _context: ticket
    id: 2
    mask: DEMO-002
    participants:
    - id: 3
    - id: 4

When you're satisfied with your test input, click the run button:

If you picked tickets with different participants, you'll see output like:

__exit: return
__return:
  deny: The participants of merged tickets (DEMO-001, DEMO-002, DEMO-003) must be identical.

This would deny the merge.

If you choose tickets with the same participants (or you fake the participants in the simulator), you'll see:

__exit: exit

This would allow the merge.

You can test this as much as you want since the automation doesn't change any data. It simply returns a __return:deny: key, or not, to whatever functionality invokes the automation.

Configure the automation event

Now that we have an automation that meets our needs, we can configure it on the event.

Navigate to Search -> Automation Events.

Edit the record.merge event.

Paste the following KATA into the event editor:

automation/ticketSameParticipants:
  uri: cerb:automation:wgm.merge.ticket.onlySameParticipants
  disabled@bool: {{record_type is not record type ('ticket')}}

This runs our record.merge automation only when the records being merged are tickets.

Click the Save Changes button.

Testing the event

Creating test data

You may want to create some test data at this point if you're on a production system.

Navigate to Setup -> Mail -> Incoming -> Import.

Paste the following message:

From: [email protected]
To: [email protected]
Subject: Message from [email protected]

This is a message from [email protected]

Click the Import button to create a ticket.

Repeat the above steps to create a duplicate message. We'll end up merging those tickets.

Now create a ticket from a different sender:

From: [email protected]
To: [email protected]
Subject: Message from [email protected]

This is a message from [email protected]

Click the Import button.

You now have three test tickets.

Merging with your custom logic

Navigate to Search -> Tickets. If you need to reset the results, run the query: sort:-updated

Select the message from [email protected] and one of the messages from [email protected] and click the merge button below the worklist.

Click Continue twice.

You should see an error:

Now select the two messages from [email protected] and click the merge button below the worklist.

Click Continue twice.

You should see a success message:

You now have full control over record merging logic.