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.

The Basics

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:

  • Patient object is the base object, and the concrete patient, for which we're looking for clinics, is the base record. In formulas and action parameters it's mentioned with the prefix record.

  • Clinic object is the match object. In formulas and action parameters it's mentioned with the prefix match.

  • Clinics that offer the service the patient needs is the match condition, and Clinic records that meet the condition are match candidates.

    If in our example the service that a client needs is a single-choice or multi-choice picklist ServiceNeeded in the Lead object, and the services a clinic offers is stored as a multi-choice picklist ServicesOffered on the Account record, the Match condition would be:
    match.ServicesOffered contains all record.ServiceNeeded

  • Closest by distance tells us how we must pick the 3 best-matching clinics out of the match candidates. In Match records such criteria is called the rating, and since Mapsly selects records with the highest rating, this criterion translates into the rating formula of -driving_time (the driving time with the minus sign) - so that a closer clinic would have a higher rating.

  • Not father than 20 minute drive sets a restriction on the value of the criterion used to pick the best-matching clinics. In Match records such a limit is called the threshold and it's the minimal value a match candidate's rating for it to be considered a matched record. In our example this restriction translates into the threshold of -20 .

    Records with the rank below the threshold are omited from the end set of matched records.

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

Match record action configuration popup


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:

  • when you're looking to find exactly 1 matched record and store it in the single-lookup field on the base record;

  • when you're looking to find multiple matched records and store them in the multi-select lookup fields.

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.

Array of found records records, number of found records MatchedRecordsCount, and system fields __rank and __directDistance

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:

  • __rank: the rank of this particular record calculated rank based on the rank formula (if the formula is defined);

  • __directDistance: the direct distance in km or miles (depending on your Mapsly account's distance unit) between this particular record and the MR's base record.

Important considerations about Match actions and Base actions

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.

Example: for a new Lead find 3 closest Stores and email a report to the admin

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.

Accessing matched records in subsequent actions

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

  • from the action that immediately follow your MR action using the lastAction context key, like {{lastAction.MatchedRecordsCount}},

  • or from any further actions using the named context key (if you added your MR action to a condition/actions block and set the name for the action's context key),

  • or using GetC(), if you executed your MR action using Do().

How to execute a Match record action

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.

Limits in Match records

Driving distance and time not allowed in match condition

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.

Max number of match candidates is 1000, or 100 when using CurrentRoute()

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

  • 100, if you're using CurrentRoute() in the rating or threshold;

  • 1000 in all other cases.

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.

See also

Did this answer your question?