Enrich VA Geo Maps using a custom ESRI map with pinned locations

3 Likes

Recently, I received a request for a technique to display the location of SAS offices as a layer to a Visual Analytics geo map to serve as reference points to activity in the source data. The geo map was already plotting bubbles for recent hotel activity but the user wanted to enrich the visual by also showing the nearest SAS office location. In this article, I will explain how to create an ESRI Web Map to render a pin point for each SAS office around the world.

In bouncing ideas around with my colleagues, we thought to create custom polygons and import them in Viya. But this doesn't really meet the requirements. Custom polygons are nice when needed to build out areas on a geo map based on the border of the area. Unfortunately, custom polygons will not look as "slick" as a Google map.

So, I thought we could use Google maps combined with the Data-Driven Content object, but I would have to learn all the ins and outs from Google Map API (and give money to Google). This might be something I would spend some time on, but it would take too long to provide an answer.

I then came up with another idea: let's create a SAS Office Layer using ESRI. In our case, we will integrate the ESRI Web Map in a Data-Driven Content object. Therefore we will use a project developed by SAS on GitHub: sas-visualanalytics-geowebmap

You might wonder why using Data-Driven Content object instead of the map object in VA. I've to admit that I was originally thinking to create a Tile Layer in ESRI and to use it. Unfortunately, I could not create the map I wish. This is where the project on GitHub came into the game.

In order to create the map and make it available, you should have an ESRI server hosted at your company or an account on ArcGis website. In this case, I will use the ArcGIS website as I don't have a custom server.

For this example, I will use a list of the SAS offices around the world. The data will be loaded on the ArcGIS server to create the layer. The input data is in the form of a CSV file which contains latitude, longitude and additional descriptive information that can be displayed on the pin points.

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

Create the map with ESRI

There are different ways to integrate. What we want to do is add pin points for SAS Offices on to a street level map. Therefore we will need to first import our SAS Office coordinate information on top of an existing map so it has both the SAS Office pins and the level of detail we want, street level in this case.

Connect to ArcGIS online : www.arcgis.com and click on Sign In.
After entering your username and password, you get access to your company page. Select the Map tab.
A default map will load. From there we will load the data from the CSV file to define the layer. Click on Add, in the drop-down select Add Layer From File.
Choose the file containing the addresses, longitude and latitude. When done click on IMPORT LAYER.
You have now loaded the layer and the import process has identified that the file contained the necessary latitude and longitude data. If you click on one of the pin points, you will see the extra detailed information in the tooltip.
As we are loading pin points, we will change the Style from Types to Location. Doing this enforces all pin points to look the same regardless of the loaded descriptive information.
We will customize the pin points. Click on Options.
Click on Symbols.
Select the shape and change the size. When done, click on OK.
In the Change Style pane, click on OK at the bottom of the pane.
The map will now look like this.
Save the web map.

Deploy the geo web map project

Using the instructions in the GitHub project, it details how to deploy the web application on the web server that comes configured with SAS Viya. You could, if needed, host the project on another machine.

To achieve the deployment from your machine, you should have the following components installed:

nodeJS version 8.x.x or higher
a tool to transfer files from your machine to the web server machine: rsync, winscp, MobaxTerm, ...

Here are the steps to build and deploy the web application on the web server hosted on SAS Viya environment.

Download the project from GitHub. Click on Clone or download and select Download ZIP.
Unzip the content of the downloaded file on your Desktop.
When done, open a command line and navigate to the location where you unzipped the file.
The next step will be to install all the packages that are required to build the web application. The project has all the needed information to install the dependencies. Within that location where you unzipped the downloaded file, execute the following command: npm install
When the process is finished, we will have to build the web application that will be deployed. You should therefore execute this command: npm run build
Npm will build the needed packages and files and copy all of them to a folder called dist. You can check the content of the dist folder.
The next step will be to copy the files to the web server. By default, only the root user on the server environment can write files to /var/www/html location. We need to ask the System administrator to give access to the user who will upload the files. Of course, the user who will upload the files should be allowed to ssh to the SAS environment. As soon as the user can connect to the environment and write to /var/www/html location, we can create a folder in that location: geowebapp
Upload the files contained in the dist folder to the geowebapp folder. Using rsync, the command might look like:
rsync -arvz dist/* sbxxab@va84.gel.sas.com:/var/www/html/geowebapp
When the files are uploaded, you should be able to access the web application using a URL similar to:http://va84.gel.sas.com/geowebapp/. The result will be this:

Create Visual Analytics report

We have now all the needed components to display the map within a Visual Analytic report. We will create a report with a Data-Driven Content object and use the web application to display the map using the data passed from the report.

Create a VA report and add a Data-Driven Content object. As URL, use http://va84.gel.sas.com/geowebapp/.
In the Roles, you should add a few variables with different roles. In our example, we have used the following variables. To avoid any troubles with incorrect longitude and latitude, we have to change the aggregation for longitude and latitude to Maximum.
- Description: Hotel name
- Latitude: Hotel Latitude
- Longitude: Hotel Longitude
- Size: Total Nights.
So far, there is nothing to see on the map. This is because we will pass these data items to the Data-Driven Content (DDC) object, our geo map project, using the URL from the Options pane. To learn how the DDC URL should be formatted you can see the expected Role assignments detailed on GitHub.
- x
- y
- size
- visualizationType
- portalItemId
The Roles x, y and size point to the variables passed to the Data-Driven Content object. The Role visualizationType indicates which type of visualization is used while the portalItemId is the reference to the ESRI Web Map.

To get the reference to the ESRI Web Map, you should open the map within ESRI and copy the id from the URL. In our case, the URL is: http://sasinc.maps.arcgis.com/home/item.html?id=e0a6b464d7bb4417b0be6ca9a86600fe.

In this example, the reference is: e0a6b464d7bb4417b0be6ca9a86600fe

We have all the needed information to build the URL for the Data-Driven Content object. Here is the final version:
```
http://pdcesx03199.race.sas.com/geowebapp/?portalItemId=e0a6b464d7bb4417b0be6ca9a86600fe
&x=Hotel%20Longitude
&y=Hotel%20Latitude
&visualizationType=bubbles
&size=Total%20Nights
```
The URL should appear on one line, but for readability, I split it.
Please note that if there are blanks in the variable names like "Hotel Longitude" or "Hotel Latitude," the blanks should be encoded as "%20".
We have now written our URL. We just need to paste it in the URL field of the Data-Driven Content object and look at the result.

Extra features

If you compare the Geo map objects that are available out of the box with this web application, you will see that you are getting extra options.

Switch background map
Hide/Show layer

Conclusion

Even though this technique requires extra setup when compared to using maps that are available, the tool made available on GitHub makes it easy to use ESRI Web Maps. There is no need to be an expert in ESRI or to install any ESRI component on the development machine. With an ESRI account, you can create the map with the layers you want and use within SAS Visual Analytics for visualization.