SfSkills Domains Docs GitHub

Home / integration / salesforce-maps-setup

salesforce-maps-setup

Use when configuring Salesforce Maps (formerly MapAnything) — territory planning, route optimization, live tracking, geo-grid visualizations, and check-in/check-out workflows for Sales or Service field reps not on Field Service.

Open the skill folder on GitHub

Salesforce Maps Setup

This skill activates when a practitioner is configuring Salesforce Maps (the rebranded MapAnything product, marketed as Maps for Sales Cloud and Maps for Service Cloud). It covers package installation, geocoding setup, territory polygon design, route optimization, and live tracking — all distinct from Field Service Lightning's territory model and from Consumer Goods Cloud's RoutePlan/Visit. Use it when the question is "how do I configure Salesforce Maps," not "how does FSL territorying work."

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Package Installation Sequence

Salesforce Maps ships as multiple managed packages that must be installed in order:

  1. Salesforce Maps (base) — geocoding, plotting, basic visualization, Lightning Maps component.
  2. Salesforce Maps Advanced — territory planning with polygons, advanced visualizations, dataset-driven layers.
  3. Salesforce Maps Routing (or Routing & Live Tracking add-on) — daily route optimization, multi-stop routing, ETA, live tracking, breadcrumbs.

The packages have inter-dependencies. Installing Routing without the base Maps package fails; installing Advanced without base also fails. Confirm the licensed tier before downloading any package.

After install, post-install steps are required even though the packages are managed. The most common forgotten step: assigning the Maps permission sets (Salesforce Maps, Salesforce Maps Advanced, Salesforce Maps Routing) to the actual users — package install does not auto-assign permissions to existing users.

The Maps Object Family

Maps adds its own custom object set in the package namespace (maps__ for the modern packages):

Reports and SOQL against these are how you audit territory coverage, route adherence, and tracking integrity. They are not exposed to users by default — administrators query them.

Territory Models: Polygon, ZIP, Hierarchical

Maps territories support three model types, each with tradeoffs:

ModelWhen to useConstraint
PolygonCustom geo boundaries (e.g., a sales region drawn on the map)Polygon vertices live in the package; not portable to other systems
ZIP / PostalCoverage by US ZIP-3 / ZIP-5 or international postalUS-centric default; international ZIP support varies by country
Rule-based / HierarchicalAssignment by Account fields (industry, AnnualRevenue)Not strictly geographic; harder to visualize on the map

Mixing models in one Territory Plan is supported but operationally fragile — a record matching both a polygon and a rule needs an explicit precedence configured in the Plan. Most production rollouts pick one model per Plan.

Geocoding: The Silent Failure Mode

Maps cannot plot records without latitude/longitude. The Maps Geocoding service runs as a scheduled batch (default daily) and processes any record with a Maps-tracked address that has no geocode yet. Two failure modes that bite every implementation:

  1. Real-time geocoding is OFF by default per object. New Accounts created today will not appear on the map until the next batch runs. Enable real-time geocoding under Maps Setup → Configure Salesforce Maps → Geocoding for every object users plot.
  2. Geocode failure for incomplete addresses fills the failure log silently. A record with City but no State, or a Country code Maps doesn't recognize, is logged in MapsGeocodeFailure__c-style records (or the Maps "Geocoding Issues" list view) but does not raise a user-visible error. Audit failures weekly.

Live Tracking Privacy And Permissions

Live Tracking emits breadcrumb events (a new record per location ping at the configured interval). Two operational realities:

  1. Privacy and labor compliance. Live tracking is regulated in some jurisdictions (e.g., requires explicit employee consent in California, EU). The customer's HR or legal team must approve enablement per region before activating.
  2. Volume. A 100-rep deployment with 5-minute pings during a 10-hour workday generates ~120,000 breadcrumb records per day. Plan an archival job (Big Object archive or scheduled hard delete after retention period) before turning Live Tracking on org-wide.

Common Patterns

Pattern 1: First-Time Maps Install For Outside Sales

When to use: Customer is licensing Salesforce Maps for the first time to map Accounts and Opportunities for an outside-sales team (no FSL, no Live Tracking).

How it works:

  1. Install Salesforce Maps (base) into a sandbox first; do not install in production until validated.
  2. Run the post-install wizard: configure the Geocoding service for Account (and Lead, if mapped) — set the address-source fields (BillingStreet/City/State/PostalCode/Country) and enable real-time geocoding.
  3. Schedule the initial batch geocode for existing records (Setup → Maps → Geocoding → "Geocode All").
  4. Validate ≥ 90% geocode success on the sample (50–100 records). Investigate failures: typically missing State or invalid Country.
  5. Build a MapsLayer__c for "Open Opportunities" and place the Lightning Maps component on the home page or a dedicated tab.
  6. Assign the Salesforce Maps permission set to the outside-sales profile cohort.
  7. Train: 30-minute "How to plot, filter, and route your day from Maps" session before access goes live.

Why not the alternative: Activating Maps in production before sandbox validation is a high-volume DML mistake — the initial geocode batch can take hours and fail silently for records with bad addresses. Validate in sandbox; move to production only after the geocode failure rate is understood.

Pattern 2: Polygon-Based Territory Plan For US Field Reps

When to use: Customer needs sales reps assigned to geographic territories drawn as custom polygons (not ZIP-aligned).

How it works:

  1. Install Salesforce Maps Advanced alongside the base Maps package.
  2. Create a MapsTerritoryPlan__c titled e.g. "FY26 US Sales Territories."
  3. Use Maps Advanced UI to draw polygons on the map; each polygon becomes a MapsTerritory__c linked to the Plan.
  4. Configure assignment rules: when an Account's geocode falls within a polygon, the named user/queue is set as the territory owner. Assignment runs as a scheduled batch (default nightly).
  5. Validate via SOQL: SELECT COUNT() FROM Account WHERE BillingState IN (...) AND Maps_Territory__c = NULL should be near zero after the first batch.
  6. Create reports on MapsTerritory__c for territory coverage health (account count, opportunity pipeline, white-space).

Why not the alternative: ZIP-based territories are simpler to maintain but cannot represent "the eastern half of New Jersey except this corridor" without splitting ZIPs. Polygon territories handle custom boundaries; the operational cost is the polygon-redraw work each fiscal-year boundary change.

Pattern 3: Daily Route Optimization For Service Reps

When to use: Customer has Maps Routing tier; reps want a one-tap "optimize my day" for visiting 8–15 accounts.

How it works:

  1. Confirm Maps Routing is licensed (separate from base + Advanced).
  2. Configure routing parameters: max stops per day (typically 8–15), service-time-per-stop (e.g., 30 min), start/end location (home or office), travel mode (driving).
  3. Build a Maps Filter for "Today's Visits" using a saved list view (e.g., Opportunities with Visit_Date__c = TODAY AND Owner = $User).
  4. The user opens Maps, selects today's filter, taps "Optimize" — Maps Routing returns an ordered stop sequence and ETA per stop.
  5. The user can save the sequence as a MapsAdvancedRoute__c for the day; route adherence (actual vs planned) reports off this object.

Why not the alternative: Manual day-routing with a spreadsheet costs reps 30–60 minutes per day. Maps Routing's optimization saves the time but does not consider non-Maps constraints (rep's standing meetings, physical health/break needs); always allow user override.

Decision Guidance

SituationRecommended ApproachReason
Outside sales reps need to plot accounts and opportunities on a mapSalesforce Maps base + Geocoding configured for those objectsCore Maps use case; doesn't need Advanced or Routing
Sales territories need custom polygon boundariesAdd Salesforce Maps Advanced; build polygon-based TerritoryPlanPolygon support is Advanced-tier; base Maps cannot draw polygons
Reps need one-click "optimize my day" multi-stop routingAdd Maps Routing tier; configure routing parameters per profileRouting engine is a separate licensed component
Need to track field-rep location continuouslyLive Tracking add-on; HR/legal approval required firstPrivacy and volume considerations dominate the technical work
Field service workforce with work-order dispatchUse Field Service (FSL), not MapsFSL has the dispatch engine; Maps is for sales-style coverage
Retail-execution store-cadence visitsUse Consumer Goods Cloud RoutePlanCG Cloud has retail-specific objects; Maps is general-purpose
Customer is migrating from MapAnythingConfirm package version (modern Maps managed package); plan data migration of polygons and saved routesMapAnything pre-rebrand has different namespace; not a no-op upgrade
100k+ Accounts to geocode in initial batchRun batch in a low-traffic window; monitor governor-limit consumption; expect partial completionBatch geocoding can hit org daily API limit on the geocoding callout

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Scope the work against the entitlement and the data.
    • Confirm license tier. Ask which Maps package(s) the customer holds (Maps, Advanced, Routing, Live Tracking). Match the work plan to the entitlement.
    • Identify source objects. Which records need to plot? (Account is most common; Lead, Opportunity, Case, custom objects also supported.) Capture the address-field mapping per object.
  2. Install in sandbox first. Install the package(s) in install order (base → Advanced → Routing). Document any post-install wizard steps the customer's admin must run with their credentials.
  3. Configure geocoding per source object. Set address-source fields, enable real-time geocoding, schedule the initial batch geocode. Validate ≥ 90% success on a sample.
  4. Build the visualization. MapsLayer__c per record set (e.g., "Open Opportunities," "Active Accounts in Territory"); Lightning Maps component on home page or app tab.
  5. Add the tier-gated modules that are in scope.
    • (If polygon territories) Build TerritoryPlan + polygons in Maps Advanced. Configure assignment rules. Run the assignment batch and validate coverage.
    • (If routing) Configure routing parameters per cohort (max stops, service time, start/end). Train users on the Optimize button.
    • (If live tracking) HR/legal approval first. Configure ping interval and retention. Build the archival job before enablement.
  6. Grant access and validate before promoting.
    • Permission-set assignments. The Maps permission set must be assigned to the user cohort — package install does not assign it.
    • Validate end-to-end in sandbox before promoting to production. Run the full user workflow (open Maps → filter → plot → route) with a real cohort member.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

(Detailed entries live in references/gotchas.md.)

  1. Real-time geocoding is OFF by default per object — newly created records do not appear on the map until the next batch.
  2. Geocode failures are silent — they accumulate in a log; users see "missing pin" without an error.
  3. Permission-set assignment is not automatic — package install grants nothing to existing users.
  4. Maps and FSL territories are separate object models — do not assume ServiceTerritory and MapsTerritory__c interoperate.
  5. Live Tracking volume can overwhelm storage — plan archival before enablement.
  6. Polygon definitions are package-internal — they cannot be exported to Tableau or non-Maps systems without manual extraction.

Output Artifacts

ArtifactDescription
Package install planOrdered list of packages, sandbox-first sequence, post-install wizard steps
Geocoding configuration matrixPer object: address fields, real-time on/off, batch schedule
MapsLayer__c definitionsPer record set: filter, style, fields shown in info-window
Territory Plan with polygons (if Advanced)MapsTerritoryPlan__c + child MapsTerritory__c records
Routing configuration (if Routing)Max stops, service time, start/end location, travel mode
Live Tracking enablement memo (if licensed)HR/legal approval, ping interval, retention, archival design
Permission-set assignment runbookMaps permission set(s) → user cohort mapping

Package files