How to host Mapbox basemaps

Introduction

Flowfinity Actions allows users to visualize geographic location data in maps hosted within dashboard widgets. Administrators may customize their basemap designs by registering map source styles designed in Mapbox.

Once a map style has been created and saved in Mapbox Studio, simply download the JSON file style sheet and upload it into Flowfinity to use in your map configurations. Map styles are available for selection in map dashboard widgets, allowing you to customize Flowfinity data visualizations.

➤ You can see it in action here.

Instructions

1. Log into your Mapbox account.
   Note: If you already have an existing map that you would like to use as a base map in Flowfinity, then skip to Step 6 below.
2. To start designing a new map style, switch to Mapbox Studio.
   
3. Existing maps will be shown in a list, to create a new map style click the 'New style' button.
   
4. Make changes to the map format as required in Mapbox Studio and save, then publish the style. This style will now be added to the list of available designs.
   
5. Click the 'share' button to the right of the desired style, then scroll to the bottom of the pop-up window and download the Zip file.
   Note: The Style URL and Access token fields should be populated with data unique to your Mapbox account.
   
6. Open Flowfinity Actions and navigate to the Configure tab, then select the Maps section. Click 'Add New Map.'
   Note: If you are using Enterprise Edition, you will need to switch to the Public Site to access these settings.
   
7. In the Map Configuration window, specify a title, name, and description.
   Note: The title is a user-friendly name that will be shown in the dashboard. The name is a unique system identifier for the map and is not visible to end-users.
   Next, click Upload in the Source section. Upload the Zip archive saved from Mapbox Studio.
8. Once uploaded, Flowfinity unpacks the Zip archive and extracts the .JSON file containing the Vector Tile map settings. The configuration should look like this:
   
9. To allow Flowfinity to display the map, an access token is required. Return to Mapbox Studio. Either navigate to the 'share' window from Step 5 or locate the Access Tokens tab in Account Settings.
   Copy the relevant Access token.
   
10. Return to the Map Configuration window in Flowfinity Actions and paste the copied value into the 'Access Token' field.
    Note: Once the Access Token field has been configured, the Map Configuration window will refresh and display a preview of the map.
    
11. The basic Map Configuration is now complete. You can save the configuration and proceed. However, two additional optional settings can be configured to adjust the end-user experience – Default Marker and Map Bounds.
    
12. The Default Market Icon will be used to display data points on the dashboard map. To change the default, click on the Icon and select the desired marker shape and color.
    
13. Configuring Map Bounds allows administrators to restrict the map widget to display only a specific area to users. This is done by defining the Southwest (bottom left) and the Northeast (top right) coordinates, restricting the ability of users to zoom out beyond this area. Note: This feature is useful when the location coordinates are expected to be within a specific geographic region. Configuring Map Bounds will ensure a better end-user experience by pre-defining the scope of the map widget, removing the need for a user to navigate to the relevant area every time from a wider global view.
14. You can specify coordinates manually, or you can specify coordinates by using the map.
    When using the map to select coordinates, click the marker icon next to the Southwest Point to launch a popup map.
    Zoom and pan the map to the desired Southwestern point coordinate. Click to place the market and then click 'use selected location' to save.
    
15. When selecting the Northeastern coordinate, the map is already pre-zoomed to the estimated area and displays a suggested marker position. You can keep this pre-configured coordinate or change the location as desired by navigating to a new coordinate, placing the marker, and clicking 'use selected location' to save.
    
16. To use a map configuration in a dashboard widget, you will need to have an application that contains location field data. For this article, we have selected a Work Orders application that contains two records with location coordinates taken from GPS.
17. Add a widget to a new dashboard, selecting the desired application (e.g. Work Orders) and select a view. Make sure the 'Data source' is set to 'non-aggregated.'
18. The configuration should resemble the following screenshot:
    
19. If you do not see the map button at the top right of the widget, right-click on the widget and open the 'Widget Properties' window. Check that the 'widget display modes' are configured to allow the Map view.
    
20. Click on the Map icon to change the widget to map mode. The GPS coordinates for the records in the Work Orders should now be plotted onto the dashboard map.
    
    Note: If you have more than one map configuration in the system, the widget will select the first entry in the list. To change this, right-click on the map and select 'Map properties.'
    
21. In the Map Properties window, use the dropdown on the top to select the appropriate map.
    
22. In the Map Configuration window, you also have options to configure which marker to use, which columns to display (if the record has multiple GPS location columns), as well as the modes for data display and navigation.
    Note: The 'Displayed columns' list at the bottom specifies which record values will be displayed to the end-user when they select the market on their dashboard map. For example, the end-user will require the 'Address' field from the record to navigate to the work order location
    It is possible to add further columns to the marker icon, for example, a contact phone number or other fields from the source app.
    
23. Publish your dashboard.

You have now successfully hosted a Mapbox basemap in Flowfinity.