The Match records action (or for short, MR) is one of the most powerful tools in Mapsly's 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 .

To execute the MR action, we would set up a Workflow in Mapsly, triggered by a new Lead and add the MR action to its list of actions.

'Match record' action configuration


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 system functions CurrentDirectDistance() and CurrentRoute().

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.

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).

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.

How to execute a 'Match record' action

Normally, 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 - to execute a MR action.

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 direct distance instead, and then use driving distance or time in the rating (or threshold).

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.

Did this answer your question?