RouteForce Setup Guide

Version: V7.8.0 | April 2026
Audience: Salesforce administrators during initial deployment
Goal: Install RouteForce, assign access, run the onboarding wizard, configure core settings, and validate the first working rollout

1. Before you start

Prerequisites

• Salesforce org with Lightning Experience enabled
• System Administrator profile access
• RouteForce package installation link (provided by your RouteForce contact)
• RouteForce licence key
• ORS API key (provided for your environment)
• Optional: Fallback API key if applicable to your deployment
• Geocoded data (latitude/longitude) on the records you want to display on the map

Recommended preparation

• Confirm whether your org uses Shipping or Billing addresses for field visits.
• Identify pilot users and their roles (admin, manager, field rep).
• Verify that key Account records already contain latitude and longitude values.
• Review which objects your team needs on the map (Accounts, Leads, Opportunities).

2. Install the package

Use the installation link matching your environment.

Installation steps

1. Open the installation URL in a browser where you are logged in as System Administrator.
2. Select Install for Admins Only. You will assign users intentionally after validation.
3. If Salesforce prompts you to approve third-party access for RouteForce callout endpoints, click Yes, grant access.
4. Wait for the installation confirmation email from Salesforce.

Verify installation

SELECT Id, SubscriberPackage.Name, SubscriberPackageVersion.MajorVersion,
       SubscriberPackageVersion.MinorVersion, SubscriberPackageVersion.PatchVersion
FROM InstalledSubscriberPackage
WHERE SubscriberPackage.Name = 'RouteForce'

3. Assign permission sets

RouteForce V7.8.0 ships with three permission sets to support different levels of access.

Assignment via Setup

1. Go to Setup > Permission Sets.
2. Open the desired permission set (e.g., RouteForce_Admin).
3. Click Manage Assignments.
4. Click Add Assignment and select the appropriate users.
5. Repeat for each permission set as needed.

Assignment via CLI

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

Verify assignments

SELECT Assignee.Name, PermissionSet.Name
FROM PermissionSetAssignment
WHERE PermissionSet.Name LIKE 'RouteForce_%'
ORDER BY PermissionSet.Name, Assignee.Name

4. Verify Remote Site Settings

RouteForce requires external access for routing, licence validation, and optional address enrichment. These Remote Site Settings should be created automatically during package installation. Verify that they exist and are active.

Verify in Setup

1. Go to Setup > Security > Remote Site Settings.
2. Confirm each URL above is listed and marked Active.
3. If any are missing, click New Remote Site and add the URL manually.

5. Launch the onboarding wizard

The RF_Onboarding flow has 4 screens: a Welcome screen, an API Keys screen where you enter your Licence Key, ORS API Key, and Fallback API Key, a Done confirmation screen, and an Error screen (displayed if key storage fails). Keys are stored securely via SecureConfigService into InternalConfig__c.

How to launch

1. Open the RouteForce app from the App Launcher.
2. Navigate to the Configuration tab.
3. Click Run Onboarding (or the RF_Onboarding flow will launch automatically on first access).

API Keys screen

Enter the following credentials:

After running the onboarding flow

After completing the RF_Onboarding flow, configure map defaults, feature toggles, and advanced settings directly in RouteForceConfig__mdt (Setup > Custom Metadata Types > RouteForceConfig > Default).

Map defaults

Configure the baseline map behavior:

Feature toggles

Enable or disable features based on your business needs:

Advanced settings

6. RouteForceConfig__mdt: Full configuration reference

All configuration is stored in the RouteForceConfig__mdt Custom Metadata Type (36 fields). The onboarding wizard sets the most important values, but you can edit any field directly in Setup > Custom Metadata Types > RouteForceConfig > Manage Records.

SOQL check: verify active configuration

SELECT DeveloperName, AddressFieldPrefix__c, DefaultZoom__c,
       EnableLeads__c, EnableOpportunities__c, EnableVisitReports__c,
       MaxRouteSteps__c, EnableHeatmap__c, EnableBulkSelect__c
FROM RouteForceConfig__mdt
WHERE DeveloperName = 'Default'

RouteForceAction__mdt: custom map actions

RouteForce also includes the RouteForceAction__mdt Custom Metadata Type for configuring custom quick actions on the map (e.g., launching Screen Flows from marker popups). See the Configuration Guide for full details.

Scheduled jobs (auto-managed)

The package includes three scheduled jobs, automatically registered by the post-install handler:

• LogPurgeSchedulable: purges RouteForce log records older than the configured retention period
• UsageAggregationSchedulable: aggregates feature usage statistics
• UsagePurgeBatch: purges aged usage tracking records on a weekly schedule

No manual scheduling is required. These jobs are registered automatically when the package is installed or upgraded.

7. Filter fields configuration

RouteForce uses a single comma-separated field to define which filters appear on the map. The default is:

Account.Industry,Account.Type

You can configure filters in two ways:

• RouteForceConfig__mdt: edit the FilterFields__c field on the Default record
• Lightning App Builder: set the filterFields property on the RouteForce component (overrides the CMDT value)

Filter field syntax

Each filter is an Object.FieldName path, comma-separated. Examples:

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

Cross-object references are supported:

Opportunity.Account.Industry

Supported field types

• Picklist: renders as a dropdown
• Multi-Select Picklist: renders as checkboxes
• Boolean (Checkbox): renders as a toggle

8. Configure the default user experience

After the onboarding wizard, fine-tune the user experience by adjusting configuration values and the Lightning page layout.

Recommended starting defaults

Visit report configuration

The visit report form fields and result options are controlled by two configuration values:

To add or remove fields from the visit report form, edit the comma-separated list in VisitReportCustomFields__c. To change the result dropdown options, edit VisitResultOptions__c.

Two levels of configuration

RouteForce is configured at two levels:

Cloning the RouteForce page (recommended)

The default RouteForce page ships with generic settings. We strongly recommend cloning it to configure the legend, filter fields, and marker popups for your specific business:

1. Go to Setup > Lightning App Builder.
2. Find the RouteForce page and open it.
3. Click Save As to create your own copy (e.g., RouteForce_MyCompany).
4. Click the RouteForce component on the canvas to adjust its properties:
   • Filter fields: which filter fields appear in the sidebar
   • Legend fields and values: marker color assignment for Accounts, Opportunities, and Leads
   • Marker popup fields: which fields display when clicking a marker
   • Multi-select fields: which filters render as checkbox lists
   • Address prefix: override Shipping/Billing for this page
5. Click Save, then Activation.
6. In Page Settings, activate for all users (this creates a custom tab).
7. Go to Setup > App Manager, find RouteForce, click Edit.
8. Under Navigation Items, add your new tab and optionally remove the default one.

Embedding the map on Account, Lead, or Opportunity pages

The RouteForce component can be placed directly on any Account, Lead, or Opportunity record page. When placed on a record page, the map automatically centers on the current record's location and loads nearby records, no additional configuration needed.

This gives field reps an instant geographic view of their territory right from any record they are working on.

1. Go to Setup > Lightning App Builder.
2. Open (or create) a Record Page for Account, Lead, or Opportunity.
3. Search for routeforce in the component panel and drag it onto the page.
4. Configure the component properties (filter fields, legend, marker popups), the same properties as on the App Page.
5. Save and activate the page for the appropriate record types or profiles.

Going further

Beyond the default app and record pages, the RouteForce LWC component (routeforce) is fully reusable. You can:

• Create dedicated App Pages: build separate pages with different configurations for different teams or use cases
• Build your own Lightning App: create a custom app with pages containing the routeforce component
• Add to Home Page: place the map on a Lightning Home Page for instant territory overview
• Clone layouts, reports, and dashboards: use Save As on any managed layout, report, or dashboard to create your own version
• Use a configuration preset: the Configuration Guide includes 4 ready-to-use presets (Account-only, Sales team, Prospecting, Full operations) with exact values to copy-paste

9. Verify your geocoded data

RouteForce plots records on the map using latitude and longitude fields. If these fields are empty, the map will appear blank.

Accounts

Depending on your AddressFieldPrefix setting, ensure either:

• ShippingLatitude / ShippingLongitude (if prefix is Shipping)
• BillingLatitude / BillingLongitude (if prefix is Billing)

Leads

Use the standard Latitude / Longitude fields on the Lead object.

Opportunities

Opportunities inherit the address from their parent Account. Ensure the parent Account is geocoded.

SOQL checks

Run these queries to verify data availability:

-- Accounts with Shipping coordinates
SELECT COUNT(Id)
FROM Account
WHERE ShippingLatitude != null AND ShippingLongitude != null

-- Accounts with Billing coordinates
SELECT COUNT(Id)
FROM Account
WHERE BillingLatitude != null AND BillingLongitude != null

-- Leads with coordinates
SELECT COUNT(Id)
FROM Lead
WHERE Latitude != null AND Longitude != null

-- Sample geocoded accounts
SELECT Id, Name, ShippingLatitude, ShippingLongitude, ShippingCity
FROM Account
WHERE ShippingLatitude != null
LIMIT 20

10. Run the full validation checklist

Before rolling out to users, complete this end-to-end validation as a user with RouteForce_Admin assigned.

Core functionality

1. Open the RouteForce tab from the App Launcher.
2. Confirm markers are visible on the map.
3. Apply at least one filter and verify the markers update.
4. Save a filter combination and reload the page to verify it persists.
5. Add 3 to 5 stops to the route panel.
6. Run route optimization and confirm distance and timing are calculated.
7. Create a route visit (if visit reports are enabled).
8. Check route history and confirm the record was saved.

Feature-specific tests

Route settings validation

Verify that the route panel respects these settings:

• Departure time
• Lunch break window
• End-of-day time
• Default visit duration
• Max route steps limit

11. Dashboards and reports

RouteForce V7.8.0 includes 2 dashboards and 18 reports out of the box, ready for use by admins and managers.

Included dashboards

Included reports (18)

Reports cover areas including:

• Route history and optimization usage
• Visit report summaries and completion rates
• User adoption and feature usage
• Territory coverage and not-visited accounts
• Check-in activity and GPS compliance

Find all reports in the RouteForce folder. Dashboards are in the RouteForce folder. Managers with RouteForce_Manager can view team-wide data; users with RouteForce_User see only their own records.

SOQL check: verify report folder

SELECT Id, DeveloperName, Name
FROM Folder
WHERE DeveloperName LIKE 'RouteForce%'
AND Type = 'Report'

12. Recommended rollout order

Phase 1: Admin validation (1-2 days)

• Install the package
• Assign RouteForce_Admin to yourself
• Run the onboarding wizard
• Verify Remote Site Settings
• Confirm licence activation
• Complete the full validation checklist (Section 10)
• Review dashboards and reports

Phase 2: Pilot users (1-2 weeks)

• Assign RouteForce_User to a small group of field reps (3-5 users)
• Assign RouteForce_Manager to their direct manager
• Gather feedback on filters, marker fields, and route behavior
• Adjust defaults in RouteForceConfig__mdt, or clone the FlexiPage to customize (see Section 8)
• Test visit reports with real field data

Phase 3: Broader deployment

• Assign permission sets to remaining users
• Train users on route creation, optimization, and check-in
• Share the RouteForce User Guide internally
• Add more filter fields to FilterFields__c based on pilot feedback
• Set up dashboard subscriptions for managers

13. Common setup issues

14. Handover to operations

Before closing the setup phase, confirm the following items are documented and communicated:

• Address model chosen (Shipping or Billing)
• Enabled features and their rationale
• Configured filter fields (including any custom additions)
• Visit report field configuration
• Permission set assignments and user roles
• Designated RouteForce admin owner
• Support email or escalation path for RouteForce issues
• User Guide shared with field teams
• Dashboard subscriptions configured for managers

Support

For package access, licence activation, routing issues, or general questions, contact your RouteForce support channel. When reaching out, include:

• Your Salesforce org ID
• Environment type (Production or Sandbox)
• RouteForce package version (V7.8.0)
• Description of the issue and steps to reproduce

RouteForce • contact@routeforce.app • routeforce.app