External Layers

To augment our existing mapping tools, we’ve released a new feature we call “external layers” that will enable customers to display data on the map in ThingTech from external systems, like ESRI. This new feature makes it easy for customers to view their equipment in ThingTech right alongside this external data and open up a whole new range of possibilities for geospatial analysis and decision making.

This feature supports endpoints that return standard JSON, as well those that return GeoJSON data. The configuration tools we’ve built allow us to interpret different data structures through a data annotation process that users will complete when setting up an external layer.

To create an external layer, we’ll start by clicking the “Create New Layer” button in Visualization.

Layer Settings
On the “Layer Settings” screen, we can use the “Data Source” toggle to select “External Data Source”. This will expose fields for the layer name, the URL of the external data source, and authentication settings for that data source.

Here, we need to specify a layer name and add the URL of the endpoint that returns the data we want to display on the map. If that endpoint requires authentication, we support API key and username/password authentication methods.

 Annotating the Data Structure

 On the next step, we need to understand the structure of the data that comes back from the external source. We need a few keys pieces of information:

●       Feature Type - This refers to the type of objects contained in the dataset. Data sets should only ever contain one type of map object (points, polygons, or lines).

●       Feature Collection - This field refers to the list of objects in the data set that you want to display on the map. This field is often called “FeatureCollection” in ESRI datasets.

●       Feature Properties - For a single mappable object in the dataset, this field refers to the list of attributes for an object. When manually typing this value in, the path should start from the individual object itself, not from the top level of the dataset.

●       Longitude Field - This field corresponds to the longitude value of the object’s location. For ESRI data sets, this value is usually the first (0) index under “geometry.coordinates” for that object. For North America, this value will be a negative number.

●       Latitude Field - This field corresponds to the latitude value of the object’s location. For ESRI data sets, this value is usually the second (1) index under “geometry.coordinates” for that object. For North America, this value will be a positive number.

While you can type these values in manually, we’ve made it much easier to set them by exploring the dataset that comes back from the external endpoint you set up in step 1. On the left side of this screen, use the arrows to expand the various levels of the data hierarchy. When you want to set one of the fields mentioned above, click on the ellipsis icon to reveal options for setting the field that may correspond with this object.

Data Mapping

 Once we have the data structure annotated, we can move on to setting up the data types for the fields. When you get to this step, you’ll notice that we’ve already set some default data types based on a snapshot of the data coming back from the external endpoint.

 There are a few important things to know about the fields in each row on this screen

●       Field Name: This corresponds to the field name that comes back from the external dataset. This is usually not something you’ll want to change, as we use this value to find the field in the dataset. We leave it editable in the event that you need to add or modify something, but these situations will likely be rare.

●       Field Label: This is the label that will display in the grid and on the map popup when you run this layer. You can safely change this field as you please, as its value is for display purposes only.

●       Data Type: We’ll automatically try to discern the data type for each row, but you can change that if needed.

●       Is Name Field: To help distinguish between different objects on the map, we need to know which field corresponds to the “name” of the object. This field will be used to display text on the map marker, as well as the title of the popup that displays when you click on a marker.

Display Fields

This step defines the fields that will display when clicking on a map marker. We can select as many or as few fields as we want here.

Map Styles

Map styling works the same way in external layers as it does for regular layers in ThingTech. We can set up different colors and icons for different objects on the map using some sort of criteria.