'Visit planner' action

Learn how to configure a 'Visit planner' action to cover various planning scenarios

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

A Visit planner action (or for short, Planner) plans recurring visits for an individual Mapsly user or a team of users based on its configuration. Just like any other action, a Planner can executed by a Button, a Schedule, or a Workflow. This article provides a detailed explanation of the Planner's configuration parameters and they influence the planning and re-planning.

If necessary, you may have multiple Planner actions that address different parts of your planning strategy. To learn about the role of the Planner action in setting up planning of regular visits, read this guide first.

Recurring execution of a Planner for re-planning

A Visit planner action is designed to enable recurring execution to re-plan previously planned visits - to incorporate new input data, like

When creating routes and output records for planned visits, a Planner "remembers" which routes/records it created, so during re-planning the Planner removes unvisited routes and records for the remainder of the planning period and re-plans visits for those dates.

Using the Offset parameters in the Planning period block, the Planner can also be configured to preserve previously planned visits for a few days ahead during re-planning, which can be useful for example to prevent unwanted changes to visits already agreed with customers.

Creating a Visit planner action

To create a Planner action, go to Setup -> Actions, click the + button and select Visit planner:

Configuring the Planner

Adjust the Planner's configuration parameters below to match your planning strategy.

General properties

Name: the name of this Planner.

Action API name: an optional API name of the Planner used to execute the Planner through code.

Mode: Choose whether the planner should only schedule records for the user who's running the planner and include only records already pre-assigned to this user, or whether records should be distributed among the entire team listed in Users (see below).

Planning period defines the range of dates for which the Planner will be planning visits.

Please note that the Planner will only be planning for future dates, even if Start date is in the past. The first planning date is the later of the two:

When Start date is earlier than today's date + Offset, the Planner will be checking the date range between Start date and today's date + Offset - 1 day to determine last visits to records from which to plan further visits.

Use Offset to preserve previously planned visits for a number of days and instead start planning starting only several days into the future. This ensures that a Planner can be executed many times without limitation to re-plan visits for the rest of the planning period, without interfering with visits that may be scheduled with customers.

Example: we'd like to plan visits for 3Q'2021 and re-plan them every day - to incorporate new records into the planning and remove records that are no longer need to be visited, while preserving previously planned visits for the current day (TODAY) and the next day, so for example when we execute the Planner on May 20th, the Planner would not remove visits that were earlier planned for May 21th and 22th, but rather would re-plan only visits starting May 23th. To achieve this, we'd set:

Business hours: days of week and hours when new visits are allowed to be planned. For a particular team member, visits will be planned for the days and hours that are the overlap between the team member’s working schedule and the Business hours here. In other words, no visits will be planned outside of Business hours for any team member, or outside of their individual working schedules.

[COMSING SOON] Exceptions: dates with non-standard business hours or when visits are not allowed at all. Use them to prevent visits on holidays or other similar days.

Default visit settings will be used to plan visits to all records unless they are overridden for particular records using field mapping in the next section (see below).

Days between visits: the desired default frequency of visits to a record. Mapsly will try to plan every next visit to a record this amount of days after a previous visit, and will always ensure it is not planned earlier. Cases when it can be planned for later are:

Visit duration: the default duration of a visit.

Objects to be planned

Parameters in this section define which records need to be visited and their individual visit settings.

Object: the object whose records need to be visited.

Owner ID: the field that stores the ID of the user (in the data source) who's assigned to visit this record. Usually, this is the record owner in the CRM. This field needs to be filled in in two cases:

Condition: Criteria that a record must meet to qualify for planning. If the Condition is defined, only records that meet it will be included into the planning. Use Mapsly's Expression builder to define the Condition:

Check the Only records with ROOFTOP accuracy box if you'd like to exclude from planning records with approximate locations (geocoding status is not "ok/exact").

Visit settings: optional field mapping that override the default visit settings. The overriding values will be applied when they are not empty; when an overriding value is empty, the default setting will still apply.

Days between visits: the frequency of visits to the record. When the value is null or empty, the default Days between visits will be applied.

Visit duration: the duration of a visit to the record. When the value is null or empty, the default Visit duration will be applied.

Fixed assignment condition appears only in the Team mode and allows you to define a condition that will force Mapsly to assign all visits to the record to the user indicated in the Owner ID field provided it's not empty.

This condition is useful, for example, to identify VIP customers who have dedicated account executives to which all visits to these customers must be assigned, as opposed to all other customers visits to whom can be assigned to any team member.

Please note that if the CRM user in the Owner ID field is not registered in Mapsly, visits to this record will be assigned to other team members, and not to the one indicated in the Owner ID. To prevent this from happening, make sure you add this CRM user to Mapsly before the Planner is executed.

Planner's deliverables

Parameters in this section define what the Planner should do with the planned visits: create routes with them, or create records of the specified object, or both.

Check the Create routes box to have the Planner create daily routes with the planned visits. The routes will be assigned to Mapsly users and will appear in their list of routes.

The the Create records box to have the Planner create a record for each of the planned visit and fill its fields with the data about the record being visited and the user who's visiting it. Usually, this is used to create Meeting or Event records in sales reps' calendar.

When Create records is checked, the following field mapping will appear below:

Object: records in which object to create.

Owner ID: the field to which to save the ID of the user (from the data source of the object being planned) to whom the visit is assigned.

Record ID: the field to which to save the record ID being visited.

Planner API name: the field that the Planner will use to store its API name to be able to identify which records were created by this Planner (required for further re-planning).

Visit start date/time: the field to which to save the date and time of the start of the visit.

Visit end date/time: the field to which to save the date and time of the visit.

'Visited' object

Parameters in this section define how the Planner will know when a record was visited last time.

'Visited' object: the object that keeps information which records were visited.

Visited when: the field that stores the date and time of when a record was visited.

Visited by whom: the field that stores the ID of the user (from the data source of the object being planned) who visited the record. Usually, it's the owner of the record, or another lookup on the User in the CRM.

Users (Team mode only)

Shown only if the Planner is in the Team mode, list here the Mapsly users for which the Planner should plan visits.

Did this answer your question?