Tourvia Setup Guide

Version: TourviaApp 7.37.0 | September 2026
Audience: Salesforce administrators during initial deployment
Goal: Install Tourvia, assign access, run the onboarding wizard, configure core settings, and validate the first working rollout

TourviaApp 7.37.0 — safe onboarding sequence

1. Install or upgrade the AppExchange package in a sandbox or approved org; do not configure production blindly.
2. Assign the managed permission-set group to a pilot admin and pilot rep, then verify object and field access.
3. Configure geocoding, routing credentials, and the CMDT defaults before inviting the wider team.
4. Set and test Plan My Day limits, offline check-in queue/synchronization, and the P4 next-step options with a small set of records.
5. Run a mobile pilot: plan a day, check in/out online, simulate loss of connectivity, wait for automatic sync or use Sync now, and confirm the Salesforce records.
6. Only after the pilot passes, assign the relevant groups to the production users and document the rollback/contact path.

Supported visible labels: EN Plan My Day, Check in, Next step; FR Planifier ma journée, J’y suis !, Prochaine étape; ES Planificar mi día, Registrar visita, Siguiente paso.

1. Before you start

Prerequisites

• Salesforce org with Lightning Experience enabled
• System Administrator profile access
• Tourvia package installation link (AppExchange listing or private install link)
• Tourvia licence key and routing API key — delivered automatically by email after installation (see §2, “Licences and access credentials”)
• 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.
• Run the local data-readiness checker on a CSV export before map review. It reports field and coordinate signals locally; it does not establish address accuracy.
• Review which objects your team needs on the map (Accounts, Leads, Opportunities).

2. Install the package

Tourvia is distributed through the public AppExchange listing. Open the listing and click Get It Now to install in your production, developer, or sandbox org.

Open the Tourvia AppExchange listing →

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 Tourvia 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 IN ('TourviaApp', 'Tourvia')

The managed package node-name is TourviaApp (since 7.22.0); the namespace remains routeforce.

Licences and access credentials

Since September 2026, access provisioning is automated through Salesforce's licence management:

1. Production or developer org: when you install TourviaApp, Salesforce registers a 30-day per-seat trial licence. Tourvia is notified automatically and provisions your access: the installing administrator receives an email with a one-time secure link (valid 48 h) that reveals your Tourvia licence key and routing API key. Keep them safe — the link burns after one view.
2. Assign the licence to users: the trial is per-seat. Go to Setup → Installed Packages → TourviaApp → Manage Licenses → Add Users and select every user who needs the app. Users without an assigned licence cannot open Tourvia.
3. Sandbox org: Salesforce automatically applies a site-wide licence to sandbox installations and no credentials email is sent. Email support@gettourvia.com and we will issue sandbox access manually within one business day.
4. Trial end: when the 30 days expire, access stops automatically. Contact us to convert to a paid subscription — no reinstallation is needed.

If the credentials email has not arrived within 15 minutes of installation, check spam, then write to support@gettourvia.com — we can re-issue a secure link.

3. Assign permission sets

TourviaApp 7.37.0 ships with three managed permission sets and, since 7.24.0, three Permission Set Groups (PSGs) that wrap them. The PSGs are the recommended assignment path.

3.0 Permission Set Groups (recommended, since TourviaApp 7.24.0)

Subscribers cannot edit managed 2GP permission sets directly. The three PSGs let you extend access by creating one small custom permset (with your additional FLS or object access) and adding it to the matching PSG — effective access is the union of the managed permset and your overlay.

Out-of-the-box standard object FLS (since TourviaApp 7.23.0)

The managed permsets now grant Read FLS on the standard fields Tourvia needs, so subscribers no longer have to grant them manually:

• Compound address fields (Salesforce only allows FLS at the compound level for these): Account.BillingAddress, Account.ShippingAddress, Contact.MailingAddress, Contact.OtherAddress, Lead.Address
• Matching Latitude / Longitude pairs on the same objects
• Phone fields: Account.Phone, Contact.Phone, Contact.MobilePhone, Lead.Phone, Lead.MobilePhone

3.1 Contained permission sets (reference)

Assignment via Setup

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

Assignment via CLI

Preferred — assign the PSG:

sf org assign permsetgroup --name TourviaApp_Admin_Group --target-org <your-org>
sf org assign permsetgroup --name TourviaApp_Manager_Group --target-org <your-org>
sf org assign permsetgroup --name TourviaApp_User_Group --target-org <your-org>

Fallback — assign the namespaced managed permset directly (works on subscriber orgs):

sf org assign permset --name routeforce__RouteForce_Admin --target-org <your-org>
sf org assign permset --name routeforce__RouteForce_Manager --target-org <your-org>
sf org assign permset --name routeforce__RouteForce_User --target-org <your-org>

Verify assignments

Permission set assignments:

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

Permission Set Group assignments (and which permsets each PSG contains):

-- Users assigned to a TourviaApp PSG
SELECT Assignee.Name, PermissionSetGroup.DeveloperName
FROM PermissionSetAssignment
WHERE PermissionSetGroup.DeveloperName LIKE 'TourviaApp_%_Group'
ORDER BY PermissionSetGroup.DeveloperName, Assignee.Name

-- Permsets contained in each TourviaApp PSG
SELECT PermissionSetGroup.DeveloperName, PermissionSet.Name
FROM PermissionSetGroupComponent
WHERE PermissionSetGroup.DeveloperName LIKE 'TourviaApp_%_Group'
ORDER BY PermissionSetGroup.DeveloperName, PermissionSet.Name

4. Verify package callout access

Tourvia requires external access for routing, licence validation, and optional address enrichment. The required Remote Site Settings are included in the managed package and created automatically during installation.

Verify in Setup

1. Go to Setup > Security > Remote Site Settings.
2. Confirm the Remote Site Settings installed with the Tourvia package are marked Active.
3. If a managed setting is missing, reinstall the current package version before continuing.

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, Primary Routing 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 Tourvia 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 — see the Configuration Guide for the canonical field list (44+ fields, evolving since 7.13.0). 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

Tourvia 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 Tourvia log records older than the configured retention period
• UsageAggregationSchedulable: aggregates feature usage statistics
• UsagePurgeBatch: purges aged usage tracking records every Sunday at 3:00 AM by default

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

7. Filter fields configuration

Tourvia 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 Tourvia 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

Tourvia is configured at two levels:

Cloning the Tourvia page (recommended)

The default Tourvia 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 Tourvia page and open it.
3. Click Save As to create your own copy (e.g., RouteForce_MyCompany).
4. Click the Tourvia 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 Tourvia, click Edit.
8. Under Navigation Items, add your new tab and optionally remove the default one.

Embedding the map on Account, Lead, Opportunity, or Campaign pages

The Tourvia component can be placed directly on any Account, Lead, Opportunity, or Campaign (Campaign NEW in 7.20.0) record page. On Account / Lead / Opportunity, the map automatically centers on the current record's location and loads nearby records. On a Campaign record page, the layer is auto-scoped to that campaign and shows every geocoded member (resolved via the Lead or Contact parent address).

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, Opportunity, or Campaign.
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 Tourvia 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

Tourvia 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 Tourvia 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

TourviaApp 7.37.0 ships dashboards and reports for activity, pipeline, and route execution — see the Configuration Guide for the canonical list. They are ready for use by admins and managers out of the box.

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 Tourvia folder. Dashboards are in the Tourvia 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 'Tourvia%'
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 Tourvia 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
• PermissionSetGroup assignments (TourviaApp_User_Group / TourviaApp_Manager_Group / TourviaApp_Admin_Group) and any custom permsets added to the PSG for extensibility
• Designated Tourvia admin owner
• Support email or escalation path for Tourvia 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 Tourvia support channel. When reaching out, include:

• Your Salesforce org ID
• Environment type (Production or Sandbox)
• TourviaApp package version (7.37.0)
• Description of the issue and steps to reproduce

Tourvia • contact@gettourvia.com • gettourvia.com

End of document. Back to topDocumentation index