The Match records action (or for short, MR) is one of the most powerful tools in the Mapsly automation suite. It allows you find records in any specific object that match your base record based on a condition and a ranking formula, and then execute a sequence of actions for the entire set of matched records, and - separately - for each of the matched records. It addresses a wide range of scenarios mentioned on our website that would normally require writing and maintaining code.

Let's take a look at an example: for a healthcare patient we're looking for the 3 closest clinics that offer the service the patient needs (like MRI), closest by driving time but not farther than 20 minutes drive. The found clinics should be saved to the Patient's CRM record.

Let's define the terms used in the Match records action:

This example MR action could be executed, for example, by a workflow triggered by a new Lead.

​Action name: a descriptive name of your action.

Action API name: a technical name of your action if you're planning to execute it from code.

For a record in: this is the base object. MR will be executed for a record from this object.

Find records in: this is the match object. MR will be looking for records in this object.

Records to find: how many records maximum would you like to find. The resulting record set may contain fewer records, if fewer records than the required amount match the condition and have a rating above the threshold, but never more.

Store matched records in: a lookup field in the base object that references match object. Optional.

You would want to use it in the following two scenarios:

In all other scenarios you will need to use Base actions to handle the MR's result.

Match criteria: a group of configuration settings that define which records should be included in the resulting records set (become matched records).

Match condition: this is the match condition. It can only be edited in the Expression builder, but not in Expression editor.

In the example above, to ensure that we won't exceed the max number of match candidates after the match condition is applied to all Accounts (see section Limitations below), we should filter out unneeded records by distance, too. To do this, we're adding the following match condition using the logical AND:
​

Here, we're selecting Current direct distance from the Special block as the left operand and entering the distance in meters (32,000 meters is approximately 20 miles).
​
​Note. Since calculating driving distance or time is a resource-intensive operation, it is not available match condition which can be applied to millions of records, so when you need to filter by distance in the match condition, always use Current direct distance as shown above. The word current here refers to the distance between the base record and the current match record being evaluated.

Have the highest rating: here you can set the rating. Optional.

Here you can also use the CurrentDirectDistance() and CurrentRoute() functions.

In the example above, we're using the -CurrentRoute().time in the rating formula, which is the driving time between the base record and the current match record. The minus sign at the beginning is used in order for the minumal time to produce the maximal rating.

But not lower than: here you can set the threshold. Optional.

Match actions: condition/actions blocks to be executed for each of the matched record (if any). Match actions are executed for all the found records before base acrtions.

Base actions: condition/actions blocks to be executed once, at the end of the MR's execution. These actions have access to the records array of matched records, which can be used to store them on the base record in a custom way, send out an email report with the their list via a Send email action, push them to an external API via an Invoke URL action, and such. Base actions are executed after all match actions have been executed for all the found records.

After the MR action finds records that match the condition/rank/threshold and before the match actions and base actions are executed, the MR action creates a records array in its execution context containing the found records, and adds a MatchedRecordsCount key with the number of matched records.

Apart from all the object fields and the standard system fields, each record in the records array will also contain two more system fields:

The list of match actions is executed for each of the matched records, before the Base actions. Since these actions are executed for a single record, the current record's fields are available at the current level of the execution context, directly accessible in Twig fields of match actions, for exaomple: {{record.id}} or {{record.__rank}}

Base actions are executed only once - after the match actions have been executed for all the matched records, which are accessible in Twig fields of base actions via the records array.

The example task: For every new Lead automatically find 3 stores closest by driving distance, but not further away than 20 miles, and email a report to the company's admin that would list the found stores and the delivery price for each of them calculated based on the driving distance to the Lead and the cost per mile of a particular store.

To solve it, we'll create a workflow triggered when a Lead is updated and its mapsly_geo_status becomes 1 (Mapsly successfully geocoded the Lead's address into a rooftop location), and execute a MR action:

This MR action finds all Store recrods within the 30 miles from the Lead, for each of them calculates the driving distance and removes the store if it's further than 20 miles away from the Lead. Out of the remaining stores the MR actions takes 3 closest stores and executes this Send email base action:

Please note the following:

1- We specified CurrentDirectDistance() < "20" as the MR action's match condition to filter out stores located outside of the 20-mile radius from the Lead - to make sure we won't hit the Match records limits described below. When searching records by a driving distance, always filter out far-away records by direct distance first.

2- In the MR action's rank formula we specified -CurrentRoute().distanceMi. By adding a minus sign to the distance we made sure that the closest store would have the highest rank.

3- In the email body's Twig template we used -r.__rank to get the driving distance, since it was already calculated with the minus sign as the store's rank, which is accessible via the __rank system field. We added a minus sign before r.__rank to cancel out the minus sign stored in the rank. For example, a store located within 12 miles from the Lead would have the rank of -12, so the -r.__rank expression would produce 12.

Since the MatchedRecordsCount key and the records array are added to the MR action's [nested] execution context, you may access them:

Normally, to execute a MR action you would want to set up a workflow triggered by a new or updated base object's record, or a button for the base object. But it's also possible to execute it from a schedule or a form event handler.

You can't use driving distance or driving time in the match condition, because they are too resource-consuming to be applied to the whole record set of the match object. When you need to filter by distance in the match condition, use a direct distance, and then use CurrentRoute() or Route() in the rating or threshold formulas.

There is a limit on the max number of match candidates:

If the number of match candidates exceed this limit, the MR action will fail at runtime.

If you need these limits raised for your Mapsly organization, please contact Mapsly support.