🗺️ Spatial Services Map — NSW Government Data on Salesforce

Bring NSW government spatial data to life inside your Salesforce org

Important note: This is a personal project and is not affiliated with the NSW Government in any way.

This project embeds an interactive NSW vector basemap directly into Lightning record pages — no external GIS tools, no context switching. It pairs live map rendering with optional server-side geocoding (via OpenStreetMap/Nominatim or NSW Point) and a Visualforce host page that drives MapLibre tile rendering behind the scenes.

The Vector Map (NSW) Lightning Web Component handles the address fields via Apex, geocodes on demand, and renders a crisp, responsive map iframe — all wired together through shared custom settings for tile configuration and provider selection.

Prerequisites

• Salesforce CLI (sf) installed and authenticated to the target org (sf org login web or equivalent).
• Node.js and npm (for deploy scripts, ESLint, and LWC unit tests).
• Outbound access from Salesforce to NSW Spatial Services, NSW Point, and (if using OpenStreetMap) Nominatim — remote endpoints are deployed as Remote Site Settings with this package; admins should align usage with org policy and Nominatim usage policy where relevant.

Architecture

• High-level components and data flow: docs/arch/architecture.md
• LWC, Visualforce, and Apex sequence: docs/arch/architecture-simple.md

Deployment

This repo includes an ordered deployment script at scripts/deploy.sh to reduce metadata dependency issues during deploy. Metadata includes Remote Site Settings for required HTTPS endpoints.

Phase 2 deploys classes and pages and runs Apex tests (default RunLocalTests). To validate without running tests, use --dry-run or -l NoTestRun (avoid skipping tests in production if your org requires coverage).

Deploy Order

1. remoteSiteSettings + objects
2. classes + pages (with Apex test execution)
3. staticresources + lwc

Commands

• Deploy using configured default org:
  • npm run deploy
• Deploy to a specific org alias:
  • npm run deploy -- -o <org-alias>
• Validate only (no commit to org):
  • npm run deploy:validate
• Validate specific org:
  • npm run deploy:validate -- -o <org-alias>

Target Org Resolution

If -o/--target-org is not provided, deploy resolves target org in this order:

1. SF_TARGET_ORG environment variable
2. sf CLI config value target-org

If no target org is found, deploy exits with setup guidance.

Optional Flags

• -l, --test-level: NoTestRun | RunSpecifiedTests | RunLocalTests | RunAllTestsInOrg
• -w, --wait: wait time in minutes (default 30)
• --dry-run: validate only

Configure Salesforce

After deploy, open Setup and configure the Vector Map Geocoding custom setting. This is a hierarchy custom setting: use Manage to set organization defaults so every user gets the same vector tile URL, geocoding provider, and (if needed) NSW Point API key.

Where to find it: Setup → Custom Settings → Vector Map Geocoding → Manage (set values at the Organization level unless you need per-profile overrides).

On the manage screen, create or edit the default organization level row. Set:

• Geocoding Provider — OpenStreetMap (Nominatim, default), NSW_Point (NSW Point geocoding; requires NSW Point API Key), or None (no external HTTP geocoding; use Salesforce compound Address lat/lng only).
• NSW Point API Key — required only when Geocoding Provider is NSW Point; used by Apex as the x-api-key header for NSW Point Geocode Address.
• Vector Tile Service URL — optional ArcGIS VectorTileServer URL (must end with VectorTileServer). Leave blank to use the built-in NSW Spatial Services basemap URL (same default as Apex and the LWC).

The install script should setup remote sites to allow Salesforce to reach these services, but for reference they should look like this:

Configure LWC Control

Add the Vector Map (NSW) component to a record page, select it, and use the properties in the right panel: center coordinates, zoom levels, External geocoding, Address Field Names (comma-separated field paths such as Contact.MailingAddress), Debug, and Map height (pixels).

Geocoding: With External geocoding enabled, the LWC calls Apex using the Geocoding Provider from Vector Map Geocoding (not a separate LWC-only setting). With External geocoding off, the map relies on compound Address latitude and longitude from Salesforce when present.