RouteForce Configuration Guide

Version: V7.8.0 | April 2026
Audience: Salesforce Administrators
Applies to: RouteForce 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 (36 fields)
7. RouteForceAction__mdt: Custom Actions Reference
8. FlexiPage Configuration (App Builder)
9. Shared Filters (SavedFilter__c)
10. Address Enrichment (France only)
11. Usage Tracking
12. Scheduled Jobs
13. Permission Sets
14. Data Requirements
15. Remote Site Settings
16. Licence System
17. API Key Management
18. Onboarding Wizard (RF_Onboarding)
19. Configuration Presets NEW
20. Configuration Examples
21. Troubleshooting
22. Quick Reference: All 36 Defaults

1. Configuration Model: Where Does Each Setting Live?

RouteForce has two configuration layers with clear ownership:

Ownership rule

Override cascade

App Builder property (if set)
  ↓ fallback
CMDT RouteForceConfig.Default (if set)
  ↓ fallback
Hardcoded product default

Only two fields follow this cascade: addressFieldPrefix and filterFields. All other fields are exclusively App Builder or exclusively CMDT.

Quick reference map

┌─────────────────────────────────────────────────────────┐
│                  ROUTEFORCE CONFIG MAP                   │
├─────────────────────────┬───────────────────────────────┤
│     APP BUILDER         │         CMDT                  │
│     (per page)          │         (org-wide)            │
├─────────────────────────┼───────────────────────────────┤
│ addressFieldPrefix  ──► │ AddressFieldPrefix__c         │
│ filterFields        ──► │ FilterFields__c               │
│ typeField/Values        │                               │
│ oppTypeField/Values     │                               │
│ leadTypeField/Values    │                               │
│ forceMultiPicklist      │                               │
│ markerFields            │                               │
│                         │ 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 overrides CMDT when set              │
│  All others = exclusive to their layer                  │
└─────────────────────────────────────────────────────────┘

2. Deployment Patterns

RouteForce 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 RouteForce 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 RouteForce component onto the page
4. Configure the App Builder properties to match your org (see Section 4)
5. Save → name it (e.g., "RouteForce 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., "RouteForce")
3. Choose the RouteForce icon (or any preferred icon)

Step 3: Add to your App

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

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

Option B: Create your own app shell:

1. Setup → App Manager → New Lightning App
2. Add your custom RouteForce 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

RouteForce 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 36 settings reside in the Default record (RouteForceConfig__mdt.Default). Each field is documented below, organized by category.

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.

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

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

4. FlexiPage Configuration (App Builder)

While RouteForceConfig__mdt controls product behavior (feature toggles, query filters, map defaults), the FlexiPage properties control the visual presentation: which filters appear, how the legend is colored, what fields show in marker popups. Both should be configured during initial setup.

The default RouteForce page ships with generic settings and serves as a template. We recommend cloning it to match your organization's data model (see 4.3 Option B). The RouteForce LWC component (routeforce) is fully reusable; you can also place it on Record Pages (Account, Lead, Opportunity), custom App Pages, or 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. The same component properties (filters, legend, popup fields) are available for configuration.

4.1 Filter Fields Configuration

The RouteForce 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 RouteForce page and open it
3. Click Clone (or Save As) to create your own copy
4. Click the RouteForce 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 RouteForce app via Setup > App Manager > RouteForce > 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)

RouteForce 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 RouteForce 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, RouteForce 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 RouteForce 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

RouteForce includes three schedulable Apex classes that must be scheduled after installation.

8.1 UsageAggregationSchedulable

Schedule via Anonymous Apex:

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

8.2 LogPurgeSchedulable

Schedule via Anonymous Apex:

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

8.3 UsagePurgeBatch

Schedule via Anonymous Apex:

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

9. Permission Sets

9.1 RouteForce Admin

Target: Salesforce Administrators responsible for configuring RouteForce.

9.2 RouteForce 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 RouteForce 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 RouteForce Admin or RouteForce 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 RouteForce, 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. RouteForce 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

RouteForce 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 (RouteForce 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 36 Default Values

Map Settings (7)

Feature Toggles (11)

Route Settings (2)

Filter Settings (8)

Visit Report Settings (5)

System Settings (3)

Total: 36 fields (7 Map + 11 Feature Toggles + 2 Route + 8 Filter + 5 Visit Report + 3 System)