Tourvia Configuration Guide

Version: V1.3.0-1 | May 2026
Audience: Salesforce Administrators
Applies to: Tourvia for Salesforce (managed package)

Table of Contents

1. Configuration Model: Where Does Each Setting Live? NEW
2. Deployment Patterns NEW
3. Customizing the Global Workspace NEW
4. App Builder Property Reference NEW
5. Configuration Architecture
6. RouteForceConfig__mdt: Complete Field Reference (44 fields)
7. RouteForceAction__mdt: Custom Actions Reference
8. RouteForceEventDefault__mdt: Event Field Defaults NEW V1.2.0
9. FlexiPage Configuration (App Builder)
10. Shared Filters (SavedFilter__c)
11. Address Enrichment (France only)
12. Usage Tracking
13. Scheduled Jobs
14. Permission Sets
15. Data Requirements
16. Remote Site Settings
17. Licence System
18. API Key Management
19. Onboarding Wizard (RF_Onboarding)
20. Configuration Presets NEW
21. Configuration Examples
22. Troubleshooting
23. Quick Reference: All 44 Defaults

1. Configuration Model: Where Does Each Setting Live?

Tourvia has two configuration layers with clear ownership:

Ownership rule

Override cascade

App Builder property (if set on this page)
  ↓ fallback
CMDT RouteForceConfig.Default (org-wide source of truth)
  ↓ fallback
Hardcoded product default

Since 7.13.0, this cascade applies to all 9 visual configuration parameters: addressFieldPrefix, filterFields, typeField / typeValues, oppTypeField / oppTypeValues, leadTypeField / leadTypeValues, forceMultiPicklist, and markerFields. Each has a matching CMDT field on RouteForceConfig__mdt (see Section 5). The packaged FlexiPages ship with no properties set — defaults come from CMDT.

Quick reference map

┌─────────────────────────────────────────────────────────┐
│                  ROUTEFORCE CONFIG MAP                   │
├─────────────────────────┬───────────────────────────────┤
│     APP BUILDER         │         CMDT                  │
│  (per-page override)    │     (org-wide default)        │
├─────────────────────────┼───────────────────────────────┤
│ addressFieldPrefix  ──► │ AddressFieldPrefix__c         │
│ filterFields        ──► │ FilterFields__c               │
│ typeField           ──► │ TypeField__c                  │
│ typeValues          ──► │ TypeValues__c                 │
│ oppTypeField        ──► │ OppTypeField__c               │
│ oppTypeValues       ──► │ OppTypeValues__c              │
│ leadTypeField       ──► │ LeadTypeField__c              │
│ leadTypeValues      ──► │ LeadTypeValues__c             │
│ forceMultiPicklist  ──► │ ForceMultiPicklist__c         │
│ markerFields        ──► │ MarkerFields__c               │
│                         │ Enable*__c (feature flags)    │
│                         │ Default*__c (map settings)    │
│                         │ *QueryFields__c (data shape)  │
│                         │ *QueryFilter__c (data scope)  │
│                         │ VisitReport*__c (visit config)│
│                         │ RouteForceAction__mdt (flows) │
├─────────────────────────┴───────────────────────────────┤
│  ──► = App Builder property overrides CMDT when set     │
│  All other CMDT fields = no App Builder counterpart     │
└─────────────────────────────────────────────────────────┘

Migration notes — Upgrading to 7.13.0

No breakage on saved filters, route history, check-in, visit reports, or custom actions. The migration only changes where the visual configuration defaults live, not the runtime behavior.

2. Deployment Patterns

Tourvia supports two deployment models. Both are first-class.

Pattern A: Contextual (Record Page)

Best for teams that work from Account/Lead/Opportunity record pages.

Pattern B: Global Workspace (App Page / Tab / Home / Utility Bar)

Best for field reps and managers who use the map as their primary work surface.

Which pattern to use?

3. Customizing the Global Workspace

The packaged Tourvia app includes a default App Page with pre-configured values. Because it is a managed-package page, you cannot edit it directly in customer orgs. Use the clone-and-compose pattern below.

Step 1: Create your own App Page

1. Setup → Lightning App Builder → New → App Page
2. Choose One Region layout
3. Drag the Tourvia component onto the page
4. Configure the App Builder properties to match your org (see Section 4)
5. Save → name it (e.g., "Tourvia Custom")
6. Activation → choose where to expose it (App Page, Tab)

Step 2: Create a Tab for your page

1. Setup → Tabs → Lightning Page Tabs → New
2. Select your new page → give it a label (e.g., "Tourvia")
3. Choose the Tourvia icon (or any preferred icon)

Step 3: Add to your App

Option A: Use the packaged Tourvia app (recommended):

1. Setup → App Manager → find Tourvia → Edit
2. In Navigation Items, add your new tab
3. Optionally remove the default Tourvia tab if you want full control

Option B: Create your own app shell:

1. Setup → App Manager → New Lightning App
2. Add your custom Tourvia tab + any other tabs you need
3. Assign to the right profiles/permission sets

4. App Builder Property Reference

These properties are set per-page in the Lightning App Builder when you configure the routeforce component.

addressFieldPrefix

Shipping → uses ShippingLatitude/ShippingLongitude. Billing → uses BillingLatitude/BillingLongitude. Leave blank to use the org-wide default from RouteForceConfig.

filterFields

Syntax: {Object}.{FieldApiName}, always prefix with the object name.

typeField / typeValues (Account markers)

Assigns distinct marker colors to Account records based on a field value. App Builder only, no CMDT equivalent.

Example: typeField = Type, typeValues = Customer - Direct,Customer - Channel,Prospect,Other

Each value gets a distinct color. Order determines color assignment: first value = first color in the palette. Leave both blank for uniform Account markers.

oppTypeField / oppTypeValues (Opportunity markers)

Same pattern as Account, with warm-toned colors. Requires EnableOpportunities__c = true in CMDT.

Example: oppTypeField = StageName, oppTypeValues = Prospecting,Qualification,Needs Analysis,Closed Won,Closed Lost

leadTypeField / leadTypeValues (Lead markers)

Same pattern, cool-toned colors. Requires EnableLeads__c = true in CMDT.

Example: leadTypeField = Status, leadTypeValues = Open - Not Contacted,Working - Contacted,Closed - Converted

forceMultiPicklist

Example: Industry,Type: the Industry and Type filters become multi-select. Only applies to fields already listed in filterFields.

markerFields

Account fields have no prefix. Opportunity/Lead fields use {Object}.{Field}.

Configuration Presets

Copy-paste these ready-made configurations. Each preset lists the App Builder properties and CMDT settings to apply.

Preset A: Account-only map (simple)

CMDT: EnableLeads__c = false, EnableOpportunities__c = false

Preset B: Account + Opportunity (sales team)

CMDT: EnableOpportunities__c = true, OpportunityQueryFilter__c = IsClosed = false

Preset C: Prospecting mode (Leads-heavy)

CMDT: EnableLeads__c = true, LeadQueryFilter__c = IsConverted = false, DefaultDisplayMode__c = leads

Preset D: Full operations workspace

CMDT: EnableLeads__c = true, EnableOpportunities__c = true, EnableHeatmap__c = true, EnableBulkSelect__c = true, EnableVisitReports__c = true, EnableCSVExport__c = true

1. Configuration Architecture

Tourvia uses a Custom Metadata Type-first approach. All configurable application settings are stored in two CMDTs:

• RouteForceConfig__mdt: 36 fields controlling map behavior, features, queries, visit reports, and system settings
• RouteForceAction__mdt: Custom action buttons displayed in marker popups (one record per action)

This architecture provides:

• Deployable configuration across sandboxes and production
• Editable without code changes (Setup UI or Metadata API)
• Accessible to the onboarding wizard (Screen Flow)
• No DML governor limits (CMDT reads are free)

RF_Onboarding Flow (Screen Flow)
 |
 +---> SecureConfigService --> InternalConfig__c (API keys, protected)
 |
 +---> Custom Metadata deployment (Setup UI) --> RouteForceConfig__mdt (app settings, 36 fields)
 |                                          --> RouteForceAction__mdt (custom actions)
 |
 v
 ConfigService.cls (Apex reader, cached)
 |
 v
 LWC Components (@wire getConfig)

2. RouteForceConfig__mdt: Complete Field Reference

The central configuration record. All 44 settings reside in the Default record (RouteForceConfig__mdt.Default). Each field is documented below, organized by category.

Section 2.7 (Map Legend & Marker Display) is new in 7.13.0 — it documents the 8 fields that hold the org-wide defaults for marker color segmentation, popup fields, and multi-select filter rendering. Before 7.13.0 these were configured exclusively as App Builder properties on the FlexiPage.

2.1 Map Settings (7 fields)

Control the initial map appearance, clustering behavior, and display mode.

2.2 Feature Toggles (11 fields)

Enable or disable major application features. All toggles are Checkbox fields (true/false).

2.3 Route Settings (2 fields)

Control route optimization behavior and display.

2.4 Filter Settings (8 fields)

Configure which data is queried and how filters behave.

2.5 Visit Report Settings (5 fields)

Configure the check-in/check-out visit report system.

2.6 System Settings (3 fields)

Application-level system configuration.

2.7 Map Legend & Marker Display (8 fields, NEW in 7.13.0)

Org-wide defaults for marker color segmentation (Account / Opportunity / Lead), popup field display, and multi-select filter rendering. Each field is overridable per-page via the matching App Builder property (see Section 4 — FlexiPage Configuration).

3. RouteForceAction__mdt: Custom Actions Reference

Each record in RouteForceAction__mdt defines a custom action button that appears in marker popups, route step cards, or both. Actions launch Screen Flows, allowing administrators to build custom workflows triggered directly from the map interface.

3.1 Field Reference

3.2 Example: Create a "Log Call" Action

Prerequisites: A Screen Flow named RF_Log_Call that accepts a recordId input variable.

3.3 Example: Conditional Action for Prospects Only

3.4 Flow Input Variables

Tourvia passes the following input variables to the launched Screen Flow:

3.bis RouteForceEventDefault__mdt: Event Field Defaults NEW in V1.2.0

When a user saves a tournée from route mode, Tourvia inserts Salesforce Event records. If your org has validation rules requiring custom Event fields (e.g. Motif__c, Type_Evenement__c, Categorie__c…), the insert is rejected by the VR. With V1.2.0, Tourvia surfaces a clear error toast with the VR message instead of the previous misleading "All visits already exist" warning, and provides this CMDT so admins can pre-fill those required fields without touching code.

Edit in Setup → Custom Metadata Types → Tourvia Event Default → Manage Records. Create one record per Event field to pre-fill.

How it works

Just before inserting Events from route mode, RouteService.applyEventDefaults reads all active records of this CMDT. For each record:

1. Looks up FieldApiName__c on the Event SObject
2. If the field exists and the Event has no value set → assigns DefaultValue__c (with type coercion: picklist/text → string, date → Date, etc.)
3. If the field doesn't exist → logs a warning in RouteForceLog__c and continues (zero impact on event creation in orgs without those fields)

Default records shipped with the package

What happens if a VR still blocks the insert

If a validation rule rejects the Event despite the defaults (e.g. unrelated VR, or a DefaultValue that doesn't match a restricted picklist value), the user now gets an explicit error toast with the actual server message — they (or their admin) can act on it. The same message is logged in RouteForceLog__c.

4. FlexiPage Configuration (App Builder) — Override Path

The properties below take precedence over their CMDT counterparts when set. Leave them blank to inherit from RouteForceConfig.Default. The mapping is one-to-one (see Section 1 — Quick reference map).

The Tourvia LWC component (routeforce) is fully reusable; you can place it on Record Pages (Account, Lead, Opportunity), custom App Pages, Tabs, the Utility Bar, or in your own Lightning Apps.

Record Page integration: When placed on an Account, Lead, or Opportunity record page, the map automatically centers on the current record and loads nearby items. This gives field reps a contextual geographic view directly from any record, with no manual search needed.

Record Page integration: When placed on an Account, Lead, or Opportunity record page, the map automatically centers on the current record and loads nearby items. This gives field reps a contextual geographic view directly from any record, with no manual search needed. The same component properties (filters, legend, popup fields) are available for configuration.

4.1 Filter Fields Configuration

The Tourvia component accepts a single comma-separated string of filter field paths: either via the filterFields App Builder property or via FilterFields__c in RouteForceConfig__mdt. There are no numbered slots. Each field path uses one of three syntaxes:

Supported field types: Picklist, Multi-Picklist, Boolean (Checkbox). Text and Number fields are not supported as filters but can be displayed in marker popups.

4.2 Default Filter Configuration

Out of the box, FilterFields__c is set to:

Account.Industry,Account.Type

This means only 2 filters appear by default. To add more, edit the value in RouteForceConfig__mdt or in App Builder.

Example with more filters:

Account.Industry,Account.Type,Account.Rating,Opportunity.StageName,Lead.Status,Opportunity.Account.Industry

4.3 Adding or Changing Filter Fields

Option A: via RouteForceConfig__mdt:

1. Go to Setup > Custom Metadata Types > RouteForceConfig > Default
2. Edit the FilterFields__c field
3. Add comma-separated field paths (e.g. Account.Industry,Account.Type,Lead.Status)
4. Save

Option B: via Lightning App Builder (overrides CMDT):

1. Open Setup > Lightning App Builder
2. Find the Tourvia page and open it
3. Click Clone (or Save As) to create your own copy
4. Click the Tourvia component, then in the properties panel set the filterFields property to your comma-separated field paths
5. Configure any other properties as needed (legend, marker fields, etc.)
6. Click Save, then Activation. Create a custom tab for this page and add it to the Tourvia app via Setup > App Manager > Tourvia > Edit > Navigation Items.

4.4 Legend Configuration

The legend assigns distinct colors to marker values. Configure these comma-separated lists in the App Builder properties:

Order matters: the first value gets the first color in its palette, the second value gets the second color, and so on. Colors cycle if there are more values than colors in the palette.

4.5 Color Assignment by Position

4.6 Marker Popup Fields

Configure which fields appear in marker popups via the markerFields property. Any field type is supported (not limited to picklists).

Phone,Industry,Website,Opportunity.StageName,Opportunity.Amount,Opportunity.CloseDate,Lead.Company,Lead.LeadSource,Lead.Status,Lead.Email

4.7 Other FlexiPage Properties

5. Shared Filters (SavedFilter__c)

Users can save their current filter configuration for instant reload. Saved filters are stored in the SavedFilter__c custom object.

5.1 How It Works

1. User applies filters on the map (Industry = "Technology", Type = "Customer - Direct", etc.)
2. User clicks Save Filter and enters a name
3. The filter state is serialized to JSON and stored in the Configuration__c field
4. To reload, the user selects a saved filter from the dropdown; all filter values are restored instantly

5.2 Object Fields

5.3 JSON Configuration Format

The Configuration__c field stores a JSON object with the following structure:

{
  "displayMode": "both",
  "filters": {
    "Account.Industry": ["Technology", "Finance"],
    "Account.Type": ["Customer - Direct"],
    "Opportunity.StageName": ["Prospecting", "Qualification"]
  },
  "notVisitedSince": 30,
  "recordType": null
}

6. Address Enrichment (France Only)

Tourvia integrates with the BAN API (Base Adresse Nationale) to enrich French addresses with latitude/longitude coordinates.

6.1 Overview

• Coverage: France only (metropolitan + overseas territories)
• Data source: BAN (Base Adresse Nationale), the official French government address database
• Enriched fields: Latitude and Longitude on Account and Lead records
• Access: Admin panel in the Configuration tab

6.2 How to Use

1. Navigate to the Configuration tab (requires Tourvia Admin permission set)
2. Open the Address Enrichment panel
3. Select the target object: Account or Lead
4. The batch processes 95 records per batch (hard limit due to Salesforce callout governor limits)
5. Click Start Enrichment
6. The batch processes records without coordinates and queries the BAN API for each address
7. Results are written back to the Latitude/Longitude fields on each record

6.3 Configuration Options

7. Usage Tracking

When EnableUsageTracking__c is set to true, Tourvia automatically tracks feature usage to help managers understand adoption and identify training needs.

7.1 Tracked Events

7.2 Daily Aggregation

Raw usage events are aggregated daily by the UsageAggregationBatch (see Section 8). The aggregation produces daily summaries per user per event type, reducing storage requirements while preserving analytics value.

7.3 Usage Dashboard

The Usage Dashboard LWC component is available to managers and administrators. It displays:

• Daily/weekly/monthly usage trends by event type
• Top users by activity
• Feature adoption rates (percentage of users using each feature)
• Check-in completion rates

Access the dashboard from the Configuration tab (requires Tourvia Admin permission set).

7.4 Disabling Usage Tracking

Set EnableUsageTracking__c to false on the RouteForceConfig__mdt.Default record. This immediately stops all event tracking. Existing aggregated data is retained until manually deleted or purged by the LogPurgeSchedulable job.

8. Scheduled Jobs

Tourvia includes three schedulable Apex jobs, automatically registered by the post-install handler during install or upgrade.

8.1 UsageAggregationSchedulable

If a job is missing in a damaged org or after manual cleanup, you can restore it via Anonymous Apex:

System.schedule(
  'Tourvia Usage Aggregation',
  '0 0 1 * * ?',
  new routeforce.UsageAggregationSchedulable()
);

8.2 LogPurgeSchedulable

If this job is missing, restore it via Anonymous Apex:

System.schedule(
  'Tourvia Log Purge',
  '0 0 2 * * ?',
  new routeforce.LogPurgeSchedulable()
);

8.3 UsagePurgeBatch

If this job is missing, restore it via Anonymous Apex:

System.schedule(
  'Tourvia Usage Purge',
  '0 0 3 ? * SUN',
  new routeforce.UsagePurgeBatch()
);

9. Permission Sets

9.1 Tourvia Admin

Target: Salesforce Administrators responsible for configuring Tourvia.

9.2 Tourvia Manager

Target: Sales managers and team leads.

Key difference from User: Managers have viewAllRecords on History__c, VisitReport__c, and RouteForceUsageSummary__c, allowing them to see team activity and reports. They do not have access to admin tabs (Configuration, Licence).

9.3 Tourvia User

Target: Sales Reps and field users.

Key difference: Users do not see the Configuration or Licence tabs, and cannot modify CMDT settings or manage API keys.

9.4 Assigning Permission Sets

Via Setup UI:

1. Setup > Permission Sets
2. Click Tourvia Admin or Tourvia User
3. Click Manage Assignments > Add Assignments
4. Select users > Assign

Via SF CLI:

sf org assign permset --name RouteForce_Admin --target-org <org-alias>
sf org assign permset --name RouteForce_Manager --target-org <org-alias>
sf org assign permset --name RouteForce_User --target-org <org-alias>

10. Data Requirements

10.1 Account Geocoding

Accounts must have latitude/longitude fields populated to appear on the map:

Geocoding options:

• BAN API enrichment (France only): built into Tourvia, see Section 6
• Salesforce Data.com Clean: automatic geocoding (requires licence)
• Third-party tools: Geocodio, Google Geocoding API, or similar batch geocoders

Tip: Records without coordinates are silently excluded from the map, no error is thrown.

10.2 Lead Geocoding

Leads use their standard Latitude and Longitude fields (part of the Lead Address compound field).

10.3 Opportunity Geocoding

Opportunities do not have their own address. Tourvia uses the parent Account's address (via the AccountId relationship). The parent Account must be geocoded.

10.4 Events

Events appear on the map when they have a related record (WhatId or WhoId) with geocoded coordinates. Events without a geocoded related record appear in the calendar panel but not on the map.

11. Remote Site Settings

Tourvia requires callout access to external services:

These are included in the managed package and deployed automatically on install. If missing, add them manually via Setup > Remote Site Settings > New.

12. Licence System

12.1 How It Works

1. Validation callout to https://ors.routeforce.app/api/licence/{key}
2. Server returns: { valid: true, expires: "2026-12-31", client: "Acme Corp" }
3. Result is cached in LicenceCache__c for 24 hours
4. If the server is unreachable, the app continues for 7 days (fail-open grace period)
5. After 7 days without successful contact, the app blocks with a licence error overlay

12.2 Licence States

12.3 HTTP Response Handling

13. API Key Management

API keys are stored in InternalConfig__c (Hierarchy Custom Setting), protected by the routeforce namespace; subscribers cannot read them directly.

Keys are set during the RF_Onboarding wizard (Step 1) and stored via SecureConfigService.storeKeys().

14. Onboarding Wizard (RF_Onboarding)

The onboarding wizard is a Screen Flow accessible from the Configuration tab (Tourvia Admin only). It walks through all essential settings in 6 steps.

Step 1: API Keys

Step 2: Map Settings

Step 3: Feature Toggles

Step 4: Query Configuration

Step 5: Visit Report & System Settings

Step 6: Deploy

After running the onboarding flow, configure all remaining settings directly in RouteForceConfig__mdt.Default via Setup > Custom Metadata Types > RouteForceConfig > Default.

15. Configuration Examples

15.1 Minimal Setup (Accounts only)

For organizations that only need Account mapping without Leads or Opportunities:

15.2 Full Pipeline View (Accounts + Opportunities + Leads)

15.3 Manager View (Role + Team Filtering)

This configuration enables managers to view accounts across their team and monitor usage adoption via the Usage Dashboard.

15.4 Visit-Heavy Configuration (Field Service)

15.5 Custom Action: Create a Follow-Up Task

Create a new RouteForceAction__mdt record:

16. Troubleshooting

17. Quick Reference: All 44 Default Values

Map Settings (7)

Feature Toggles (11)

Route Settings (2)

Filter Settings (8)

Visit Report Settings (5)

System Settings (3)

Map Legend & Marker Display (8) — NEW in 7.13.0

Total: 44 fields (7 Map + 11 Feature Toggles + 2 Route + 8 Filter + 5 Visit Report + 3 System + 8 Map Legend & Marker Display)