All Collections
Advanced concepts
Twig templates: add record data to workflows and actions, and extend your automation with code
Twig templates: add record data to workflows and actions, and extend your automation with code

Learn how to use record data and other data available at runtime, like user location, in your workflows and actions.

Sergey Shurygin avatar
Written by Sergey Shurygin
Updated over a week ago

Most parameters in Mapsly's actions, including conditions in condition/actions are Twig templates and you may use most of the Twig tags, filters, functions and operators and execute Mapsly functions, other actions and access data variables from the current execution context.

Twig is a concise yet powerful template engine and a programming language primarily aimed at producing content from a template with Twig statements and expressions that are resolved at run-time to form the resulting value of the template.

Twig statements and expressions are enclosed in Twig delimiters and {%...%} and {{...}}, respectively. A Twig expression can be a simple {{record.Account_Name}}, which resolves into the value of the field with the API name Account_Name, or a multi-line code snippet featuring if and for operators that may produce the body for an email notification with a list of records or the JSON-body in an Invoke URL action to make an API callout.

For the full Twig reference visit the official Twig documentation page.

Twig template editor

A Twig template is edited in the Twig template editor:

In all Twig fields except:

  1. Condition in a condition/action block,

  2. Rating formula in the Match record action,

use the Twig delimeters {{ ... }} and {% ... %} to insert Twig code into your template.

In the two exceptions above, Mapsly assumes you're already entering a Twig expression, so you should NOT use Twig delimiters there.

Insert fields

Click the Insert field button to insert a variable that represents a record field:

Insert functions

Click the Insert function button to insert a Mapsly system function:

Twig code examples

Example #1: How system check-in uses Twig code

Here's a System Check In button that comes out-of-the-box with your Mapsly account and, when activated for an object, lets you log visits to any locations into the Check In object of the System data source:

The button executes 3 condition/actions blocks that implement the following business logic with the help of some Twig code:

  1. If the current location of the user [who clicked the Check In button] is available and the record into which the user is checking in has a Rooftop-accuracy location:

    1. Calculate the direct distance between the user's location and the record's location and save it to the Context under the distance key.

    2. If the distance is shorter than 0.25 km/miles (depending on the account's distance metric), set the verified Context key to verified, or to
      โ€‹not verified otherwise.

    3. Bring up the System Check-in form. Further business logic is implemented in the OnClick event handler of this form.

  2. If the user's current location is unavailable (which may happen, for example, if the user denied Mapsly access to their phone's location data, or clicked the Check In button from their laptop without a GPS module):

    1. Store Unable to obtain user's location into a Context key message, and set the message style key to error.

    2. Execute Show 'message' with 'style' standard Show message action that will show the message on the red background as designated by the style.

  3. If the record into which the user is checking doesn't have a rooftop location (mapsly_geo_status is not 1, which is ok/exact, or 5, which is ok/imported meaning Mapsly is using GPS coordinates provided by the data source):

    1. Save a message Unable to check in: object_name record_name doesn't have rooftop location. with the error style. Here:
      - object_name will be replaced with the label of the object to which the record belongs; and
      - record_name will be replaced with the name of the record, which is retrieved from the field(s) mapped as the object's name on the object settings.

Example #2: Emailing a report about records found with Match record action

In this example, we're using Twig to construct the body of a notification email listing the closest stores found for a lead, and for each of them - the distance from the Lead and the delivery cost:

{{ MatchedRecordsCount }} stores found: 
{% for r in records %} {{r.Account_Name}} ({{-r.__rank}} mi, ${{-r.__rank * r.Price_of_transport_per_mile}}){{ loop.last == false ? ', ' : ''}}
{% endfor %}

Example #3: Calculate distance traveled by sales rep through check-in points

If you need to calculate the driving distance traveled by a sales rep through all the locations into which s/he checked in on a given day, you may use a Match records action to find all such records (the matched records will be stored in a records array in the MR action's nested context), and then add the following Code action to the MR action's base actions:

{{ Route(records | sort((a, b) => a.Check_In_Time | date('U') <=> b.Check_In_Time | date('U')) | map(record => {lat: record.mapsly_geo_lat, lng: record.mapsly_geo_lng}) | slice(0), {optimize: false}).distanceMi }}

This code:

  1. sorts records by its check-in time,

  2. constructs an array of waypoints required by the Route() function,

  3. builds the route through the points, and retrieves its distance in miles, which is the result of the Twig template. You may use it as a target value in a Create record or Update record action, or in any other Twig field.

Implementation services are included in your Mapsly subscription

Implementation of custom business logic using the Mapsly automation suite and writing Twig code are included in your Mapsly subscription free-of-charge. Simply contact us in chat or at [email protected] to discuss your needs, and our engineers will implement them within hours.

Did this answer your question?