Introduction
Mapbox is one of the leaders in web mapping, for good reason. Their flexible web services lend themselves to dynamic, interactive maps that look great on any website or application. Even better, many of the tools they offer are open source.
Using the HTMLReportGenerator transformer, we can integrate Mapbox directly into our FME workflows to create custom web maps with our own data, eliminating the need to write a single line of code.
Part 1 of this tutorial creates a Mapbox web map from a SpatiaLite dataset. The data will be displayed on a web map that is built with the Mapbox GL JS library. This HTML file can be used as-is on the web.
However, the value of web mapping lies in its ability to provide access to information to a wide audience, including non-technical individuals. So Part 2 of this tutorial will build a web mapping application with the workspace from Part 1. With an FME Flow app, users can request specific datasets, then have that data streamed back to them in the browser.
Please note that the information in this tutorial is accurate; however, the screenshots may be outdated. FME Server was rebranded to FME Flow in 2023.0, and the screenshots may not reflect this change.
Requirements
- A token is required for authentication to use Mapbox services. Please make an account with Mapbox to obtain a token.
- FME Flow is required to make the workspace app in Part 2.
Step-by-Step Instructions
A web map typically consists of datasets, JavaScript, CSS, and an HTML document that contains it all. We can use FME Workbench and the HTMLReportGenerator transformer to automatically create and compile each of these components.
To follow along, download the dataset (CulturalSpaces.sqlite) from the tutorial’s resources.
Part 1: Building a Mapbox Web Map
In this section, we will create a workspace that generates an HTML file containing our Mapbox map of Vancouver's cultural spaces.
1. Add the Data
Open FME Workbench to begin the workflow.
- Add a FeatureReader transformer to the canvas to begin the workflow.
- Add a Creator transformer to the canvas. Then, add and connect a FeatureReader transformer.
As of FME 2025.2, many transformers have been updated to not require input from the creator transformer. For a list of all the transformers with this improvement, please see Transformers with an Optional Input Port
Inside the FeatureReader transformer, point the Dataset parameter to the CulturalSpaces.sqlite database. The Format should automatically update to SpatiaLite.
2. Allow the User to Select a Neighbourhood
Our dataset contains point data representing cultural spaces in Vancouver. The points are divided into different neighbourhoods. We’d like the user to choose their neighbourhood(s) (i.e., our Feature Types for this dataset) at runtime.
Inside the FeatureReader's Constraints section, beside the Feature Types to Read parameter, select the dropdown menu. Select User Parameter > Create User Parameter…
The Parameter Identifier (“Neighbourhood”) will be its attribute name in the workspace, and the Prompt (“Select a Neighbourhood”) are the instruction the user will see.
To add all our Feature Types as options, select the ellipses (...) next to Default Value. Tick the Select all box to add all of them.
Ensure that the 'Required' box is also ticked.
To return to the canvas, select OK in the User Parameter dialogue, then click OK again to close the FeatureReader.
3. Read in the Data
Save and run the workspace to review the data. Before the translation starts, the User Parameter we just created will prompt us to select the Neighbourhood(s) to view. Selecting all options will produce a workspace with data at each Feature Type port (make sure to enable Data Caching!).
Click the magnifying glass next to a Feature Type to display the point data in the Visual Preview window.
4. Start building the Map
Add an HTMLReportGenerator transformer to the page. We need to connect it to all of the FeatureReader’s Feature Type ports, since we can select any number of neighbourhoods at runtime. A quick way to connect multiple ports is by using the Feature Type Connections window (Main Menu > View > Windows > Feature Type Connections).
In Sources, select all the "FeatureReader: [Neighbourhoods]". In Destinations, select "HTMLReportGenerator: Input". Lastly, select Connect >>.
All the Feature Type ports will now be connected to the HTMLReportGenerator.
5. Start building the HTML
Open up the HTMLReportGenerator Parameters and select the Page Contents parameter to view all the HTML elements we can build. There are two options for Mapbox.
Mapbox Leaflet uses the Mapbox.js library, which is a plugin for Leaflet, an open-source JavaScript library. This legacy product still works, but is no longer in active development.
Mapbox GL JS also uses JavaScript libraries, but it incorporates Mapbox GL (OpenGL, or “Open Graphics Library”) to render more responsive and interactive maps. These maps are more customizable because they’re based on vector tiles.
Select Mapbox GL JS.
6. Style the Map
In the Content Settings section, enter your Mapbox Access Token.
Select “culturalsp” for the Label Attribute, it will display the cultural space’s name when a user selects a point.
Choose a colour for the Layer Colour. Using this template, all vector features will adopt this colour. (Advanced tip: if you have multiple features requiring different colours, consider customising the html_content attribute after running the transformer.)
The Basemap parameter offers default selections from Mapbox’s style, but can be used with custom styles created in Mapbox Studio, too. Select "Mapbox Light".
WMS URL(s) allow you to add layers that use the OGC Web Map Service Protocol. Since our FME Mapbox GL JS template is built to write only vector layers, WMS is a great choice if you need to include raster data.
7. Get Vector Layers from Mapbox Studio
The Vector Layers parameter allows you to add vector tile layers directly from Mapbox Studio, a third-party source, or a custom vector tileset uploaded to your own server.
From a browser, navigate to Mapbox Studio’s Tilesets page to view the default tilesets and any custom tilesets that you’ve created (Advanced tip: create your own tiles with the Mapbox Vector Tile (MVT) and MVT Tileset Reader/Writer)
Select the ellipses next to the "Mapbox Streets v8" tileset to copy the Tileset ID. We will paste this in our HTMLReportGenerator transformer.
Select the tileset view the data. Inside, there are 16 layers listed in the Vector Layers sidebar (toggle on and off to view). We can choose any of these layers to display on our map. Be aware of the Zoom Extent. Vector tiles load different features at different zoom levels. For example, avoid choosing layers that only load at high zoom levels (e.g., a city) for a map intended to be viewed at low zoom levels (e.g., a continent).
For our map, we’ll choose the Road layer to give context to the map. Our cultural centre point dataset covers a city-level scope (Vancouver), so the zoom levels will work (z0-z16).
8. Configure the Vector Layers
Back in FME Workbench, paste the Tileset ID ("mapbox.mapbox-streets-v8") into the Feature Layer URL column. We want to use the "road" layer, so enter that into the Source Layer column.
Our Mapbox map is now configured.
9. Add any Other Web Page Elements
A map is only one part of a web page. The HTMLReportGenerator transformer can add numerous other features to a webpage, providing your map with context. Add a descriptive Header, Separator, and Table to the Page Contents. This is entirely optional, but it makes for a better user experience.
10. Write the HTML
Add an HTML writer to the canvas, name the file (e.g. "CulturalSpacesMap.html") and connect it to the HTMLReportGenerator.
Run the workspace to write the HTML file. Open the HTML file in a browser, like Google Chrome. Selected cultural space points display a label. Notice that the road layer, the Mapbox Studio vector tileset, is responsive as we zoom in and out.
Use this HTML file as is, customise it, or proceed to Part 2 to turn it into a web application using FME Flow Workspace Apps.
Save the Workspace.
Part 2: Streaming a Mapbox Web Map in FME Flow
Web maps are a great option for sharing data with others. We can harness FME Flow Workspace Apps and the Data Streaming service to create a web application that streams our Mapbox web map on demand.
1. Publish the FME Workspace
From FME Workbench, select Publish from the ribbon menu to open the Publishing Wizard. Create a new Repository called “MapboxIntroTutorial” to save your workspace to. Ensure that you upload all data files. Continue.
In Register Services, select Data Streaming and the Job Submitter.
Publish.
For more detailed instructions on how to publish to FME Flow please see the information below.
-
To publish a workspace from FME Workbench to FME Flow, follow the generic instructions below using the specific details listed in the article. If the article does not have a specific repository name listed, we recommend creating a Training repository. If a specific service is not listed in the article, please use the default Job Submitter.
1. Click Publish
From the File menu, click Publish to FME Flow, or from the toolbar ribbon, click Publish.
Toolbar Ribbon:
File Menu:
Deploy Menu (2025.1+):
2. Add a Web Connection
In the Publish to FME Flow wizard, a FME Flow connection needs to be selected or created. To create an FME Flow connection, click the drop-down under FME Flow Connection and select Connect to FME Flow.
The following instructions are for a basic connection, but if your FME Flow is set up for Microsoft Azure, SAML, or Windows Credentials, please see the Using Web Connections to Connect to FME Flow documentation.
An FME Flow Connection dialog will appear; here, we will set up the connection. The connection information and credentials can be obtained from your FME Flow Administrator. If you have not yet logged into FME Flow after installing, please do so prior to continuing, as you will be prompted to change the password from the default:
Username: admin
Password: admin-
• Web Service: FME Flow
• Server URL: http://localhost
• Connection Name: Training FME Flow
• Authentication: Basic
• Username: your username
• Password: your password
Click OK. FME will try to authenticate the connection. Once authenticated, this connection will be available whenever you publish a workspace. The connection will only need to be created once.
-
• Web Service: FME Server
• Connection Name: Training FME Server
• Server URL: http://localhost
• Username: your username
• Password: your password
Click Authenticate. FME will try to authenticate the connection. Once authenticated, this connection will be available whenever you publish a workspace. The connection will only need to be created once.
Click Next to move to the Create Repository page of the dialog
3. Create Repository
Repositories are used to store groups of related items that have been published to FME Flow (similar to directories). Items such as workspaces, source data, custom formats, custom transformers, and templates can be published to a repository.
If you need to create a new repository, click on the New button next to Repository Name. Enter the repository name and an optional description. Click OK to close the Create New Repository dialog.
To select an existing repository, click the drop-down next to Repository Name and select the desired repository.
4. Upload Files
Some workspaces require additional files to run correctly on FME Flow, so these need to be uploaded along with the workspace. To upload files, enable Upload data files at the bottom of the dialog.
When files are uploaded through the publishing menu, they are stored within the repository. If you want to upload folder files (such as geodatabases) or to specify where the files stored, the Select Files button allows you to do that. For detailed instructions on how to use the Select Files button, see the documentation.
5. Register Services
The final step before publishing a workspace is to register services. Services control how the data will be output after the workspace is run.
Services return results in different forms:
• Data Download Service returns results as a downloadable zip file
• Data Streaming Service returns results as a data stream
• Job Submitter Service accepts and runs workspace job requests
• KML Network Link returns a KML Network Link that can be used in Google Earth
• Notification Service allows for event-driven messaging
Typically, the Job Submitter is always enabled, but multiple services can be enabled. Once services have been enabled, click Publish.
6. Review Translation Log
To confirm whether or not the workspace was published successfully, check the Translation Log. The Translation log will show which repository you published to, which files were included, and a quick link to run the workspace.
-
2. Create a Workspace App
Open FME Flow in a browser. From the main menu, select Server Apps > Build a Workspace App.
Give your app a Name (e.g. "CulturalSpacesWebMapApp"), Title, and Description. From the MapboxIntroTutorial Repository, select the CulturalSpaceWebMap.fmw Workspace. Make sure the Service is set to Data Streaming.
Select OK to publish.
3. Run the App
Open the Workspace App URL. Select a few neighbourhoods at runtime to test the app.
Select OK to run.
Using this Server app, our end user can now select which neighbourhood cultural spaces they’re interested in viewing. Those points are streamed back, in the browser, based on their selection. The embedded web map was built using FME and Mapbox GL JS libraries.
4. Put on your Web Developer Hat (optional)
Feeling adventurous? Open up the HTML file (CulturalSpacesMap.html) in a text editor to view the code. The SpatiaLite cultural spaces points are represented in GeoJSON.
GeoJSON is the most simple web mapping format and it’s compatible with almost any mapping platform. If you regularly use GeoJSON for your web maps, we have a MapboxStyler transformer just for that purpose.
Scroll down to the bottom of the HTML to view where the Mapbox vector tile layers are referenced.
Our final result is a fully functional HTML web page and an embedded Mapbox web map featuring our own data. The HTML file can be customised to use your own styling, additional functionality, or used as-is.
Additional Resources
[Webinar] Web Mapping 101: What Is It and Making It Work For You
[Article] Getting Started with FME Flow Apps
[Article] How to Customise HTML Reports
Data Attribution
The data used here originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.