GeoJSON in Salesforce
How a GeoJSON file for a region layer differs in Mosaic's Salesforce package: the 3 MB limit, the records a saved file becomes, and hosting a file instead.
Overview
A file for the package needs what a file for Mosaic on the web needs: a FeatureCollection of polygons in WGS84, an ID property on every feature, and, if you like, a color property on each. GeoJSON covers all of that and how to prepare a file. This page covers what's different in Salesforce.
In the package, a region layer gets its shapes from the file and its data from Salesforce. One value joins the two. You name a property on each GeoJSON feature as the layer's Region ID Property, and Mosaic matches it against the Region ID on your Mosaic Byte records.
GeoJSON feature Mosaic Byte record
properties.region_id = "77002" ⟷ Region ID = "77002"
properties.color = "#2E86AB" ⟷ Color (Hex) = "#2E86AB"
You can carry the color in the file itself. When you upload a GeoJSON through the map and save the layer, Mosaic creates one Salesforce record per region with its color and stores the file on the layer. The map then draws the same colors on every later visit, and nobody has to touch a record by hand.
Uploading a file
In the Regions & Points panel, click Upload regions (the upload icon next to Regions).
The steps are the web's. See Uploading regions. The layer draws right away as a session layer, and nothing is saved to Salesforce until you choose Save to Salesforce from the layer's action menu.
Saving writes three things:
- The layer record, linked to the current map.
- One Mosaic Byte per feature. Each holds the region ID, the color, and every other property as metadata. The metadata makes regions searchable and filterable.
- The GeoJSON file itself, attached to the layer record as a Salesforce file. The map reads it back the next time someone opens that layer.
The shapes, colors, and data all survive a reload, and there's nothing to host.
If the file can't be stored (the Flourish API credentials aren't set, or the service is down), the save is abandoned rather than half done. Records that describe regions are useless without the shapes they color, so you get an error saying why and nothing is written. Fix the cause and save again.
Note: The file uploads through the Flourish service and is attached to the layer a moment after the save message appears. If you reload right away and the layer looks empty, give it a few seconds.
Size limit
Uploads are capped at 3 MB. Mosaic on the web takes 50 MB. The picker refuses a larger file and says why before you save. A larger file has to be hosted and named on the layer record instead. See the hosted URL alternative. That route has no size limit because the file goes straight from your host to the browser.
IDs
The Region ID field holds 40 characters, so longer IDs are skipped on upload as they are on the web. The ID property's name must be 40 characters or fewer, too. Short names work best, such as region_id, zip, or fips.
Colors in records
A region's color from the file ends up in the Color (Hex) field of its Mosaic Byte record. You can change it there later without uploading again.
A color scale overrides the file. An admin can set a color scale on the layer record (Region Color Map), a rule that colors regions from their data. Where the scale gives a region a color, the scale wins over your file. See Region Coloring.
Note: A transparent region still has its record, and you can search and filter it. Give its byte a Color (Hex) and it appears.
Note: A region is drawn only when a byte matches it. Uploading and saving a file creates those bytes for you. If you set up a layer by hand against a hosted URL, a region with no matching byte, or with a byte that has no color, stays invisible.
The hosted URL alternative
Instead of uploading, host the file and set Region GeoJSON URL on the Mosaic Layer record. Use it for anything over 3 MB and for files you update on a schedule from somewhere else. It's set on the layer record rather than in the map, so it's an admin task.
Mosaic loads the file from the browser, so:
- HTTPS, publicly readable. Test it in a private window with no Salesforce session. If it asks you to sign in, it won't work.
- CORS enabled. The host must allow cross-origin requests from your Salesforce domain. Object storage buckets need this turned on explicitly.
- Host allowed in Salesforce. It must be registered as a CSP Trusted Site with the connect-src context enabled. Ask your administrator before adopting a new host.
- No query strings. Anything after a
?is dropped, so presigned or token-bearing links fail. Use a plain, permanent path. - Colors still come from bytes. The URL gives the shapes only. Create the byte records (region ID and color) separately, or upload the file once to create them and then switch the layer to a URL.
Republishing at the same URL updates the map on the next page load.
Troubleshooting
What can go wrong with the file itself is on GeoJSON. These are the package's own:
| Symptom | Likely cause |
|---|---|
| Nothing appears on a layer set up by hand | Its byte records have no Color (Hex) and the layer has no color scale, so every region draws transparent. |
| Regions are invisible and the layer has no records | The chosen ID property is empty on most features, so no regions were created. |
| The layer says it has no boundary file | It was set up by hand without a GeoJSON URL, or the file didn't finish attaching. Upload one, or set Region GeoJSON URL. |
| The upload refuses the file for being too large | It's over the 3 MB upload limit. Simplify it, or host it and set Region GeoJSON URL on the layer record. |
| A hosted file opens in a browser tab but not in Mosaic | The host sends no CORS headers, it isn't a CSP Trusted Site, or the URL depends on a query string. |
| An updated file still shows old boundaries | Reload the page. Mosaic keeps a boundary file until the page reloads. |