OAC Integrating WMS Maps

What is a web map service? 

Web Map Service (WMS) is a standard protocol for serving geo-referenced map images and data generated by a Geographic Information System (GIS). The Open Geospatial Consortium developed the specification and first published it in 1999. So, simply put, WMS is a way of interacting with a web server which hosts map backgrounds. 

Oracle Analytics now includes the capability to directly consume map backgrounds via WMS. In this blog we will see how to set up a communication with a WMS server to create new map backgrounds for the map visualization in OAC.

Let us take the following example of web map server.

WMS Map representing the Ecosystem Vitality Objective - Fisheries

The above image shows a map background representing the world countries and a layer on top of that which depicts the Ecosystem Vitality Index for Fisheries.

This web map server also additionally hosts multiple other layers which are shown on the left side pane like Ecosystem Vitality index for Climate, forests, water, etc.

WMS map representing Ecosystem Vitality Objective - Climate layer

WMS Map representing the Ten-Year Percentage Change Layer

Now let us see how to bring any of these maps as a map background option in Oracle Analytics Cloud.

In OAC, go to Console -> Maps -> Background -> Add Map Background. You should see two options show up called Web Map Service and Tiled Web Maps.

Clicking on Web Map Service opens a dialog with numerous fields to be filled for setting up a WMS configuration.

• The first two properties are Name and Description. Name is the name that the user wants to assign for the WMS map background. For this example, let us assign the name WMS example. Description is optional, we will leave this field empty for now.
• The third property is URL : the URL of the web map server. The details of this should be provided by the admin of the map server.
• Small check box below the URL field : this needs to be checked so that the domain name of the map server is automatically added to the list of safe domains and the requests from OAC to map server are no longer blocked.
• The next property is the version number. By default is it pre-populated with WMS version 1.1.1. Check with the admin of the map server to get the correct WMS version numbers. In general most of the WMS servers support both 1.1.1 and 1.3.0 WMS versions.
• The CRS property is set to EPSG:3857 by default and this is because we are rendering the map background in a 2D format.
• The Layers property is the place where the user is required to enter one or more layers to render on the map background. In the current example, it does not make a lot of sense to add multiple layers since they will superimpose on each other. So let us give one layer name which depicts the  Ecosystem Vitality Index for Fisheries. In a case where a web map server hosts multiple layers and if one such layer is information on important places and other layer includes information on important routes in the area, then it would make sense to add multiple layers to our WMS config. The layer information needs to be provided to the user by the admin of the map server.
• The final property is Format property and is defaulted to PNG option. All web map servers support PNG option.

Having entered all the fields we can now click on the SAVE button. A message should pop up saying that a page refresh is required for the map config to become active. Once the page is refreshed (F5), we should see the WMS map appearing as an option in the backgrounds tab. Inspect the WMS map and click on the preview tab. We should see the Ecosystem Fisheries map rendering inside Oracle Analytics.

In an OAC project, upon creating a map visualization, user can go to the Background Map property in viz properties dialog and choose the newly added WMS map background to render map layers on top of this background.

How to know the value of parameters for my WMS service ?

Web Map Servers typically support the getCapabilities request. Using this request in the configuration url, a user can invoke it to get all the information he needs to fill out a WMS map configuration. This makes the user completely independent on the admin of the map server to provide all the information.

The http request has the following pattern :

<url_of_wms_server>?request=getcapabilities&service=wms

This should return an XML file which has all the information needed to fill out a WMS map config. Search for "layer" in the XML file to find all the layers supported by the web map server. Take the value under the <name> tag to fill it in the Layers property field in OAC.

Finally, there are some web map servers which restrict the domains that can connect with them. If OAC does not happen to be on the list of domains which can connect to the web map server, the server does not respond to the requests and hence we might not see anything rendering as a map background.

These are the cases where the map servers are highly restrictive and there is not much that can be done from OAC side

Thank you for reading that blog !