Alternative to the Insight Map Viewer

Introduction

This is the second of a two part tutorial that has the objective of providing step by step guidelines on the use of the ODM Decision Server Insights (DSI) Insight Map Viewer feature, as well as introducing you to an alternative way of rendering DSI data in maps. In Part 1 we created a simple DSI solution with geospatial capabilities and rendered a location on an OSM map using the Insight Map Viewer. This part is aimed at readers who may have special rendering requirements that are not fully satisfied by the Insight Map Viewer and wish to know how to get the data from DSI and render it in their own map application. In our example, we’ve chosen to use OSM but the same objectives could be achieved using other map technologies, such as Google Maps. Like Part 1, Part 2 is at an introductory level and the main goal is to provide step-by-step guidance without obscuring the process with too many unnecessary details.

Target Audience

This tutorial is targeted at DSI developers who have a need to represent geospatial attributes on a map. A basic knowledge of DSI solution development and Open Street Map (OSM) or other map technologies is assumed. In addition, the reader should have a basic understanding of javascript and know how to develop and deploy a simple web application. Because part 2 of this tutorial has dependencies on part 1, including sharing the same basic scenario, it is strongly recommended that the reader completes part 1 of the tutorial first.

Map Service Requirements

For this tutorial we will also be using an OSM map. The same requirements and restrictions that apply when when we use OSM with the Map Viewer also apply here. In particular, we need an OSM tile server and, for this tutorial, we will also be using tiles served by OpenStreetMap.org.

Step 1 – Define the “business” problem

We’ll use the same scenario that was defined in Part 1. In addition, we’ll be reusing the DSI solution that we created for part 1, as well as the test event sequences. To carry out the part 2 tests you will need to make sure that the solution developed in Part 1 is deployed and working.

Step 2 – Create a Web Application

2.1 – Create the Web Application Project

The first step in the implementation of our custom map viewer is to create the web application project that will contain the logic that is required to display the map in a browser. There are many options to do this but we chose to create our web project using the ‘Dynamic Web Project’ wizard in Eclipse.
Under the ‘WebContent’ folder we’ve created an ‘images’ folder where we’ll store our icon images and a ‘js’ folder for our javascript files. We’ll only need to create 3 files for our custom map viewer:
1) An image file (person.png) representing the icon that we’ll use as a position marker in our map.
2) A javascript file (dsimap.js) that contains the logic to render the map and the logic to get DSI entity data using the REST API.
3) An HTML file (index.html), which contains the minimum amount of html needed to show the map in the browser.

Project structure in Eclipse:

f1

Step 2.2 – Write the html

The html required to display your map is simple and looks like this:

f2

We’ll offer a brief explanation of the important elements in our html file, which are pointed to by the numbered arrows in the figure above:
1) This is a reference to the jquery library, from which we’ll borrow the AJAX capability used to issue our REST call. Note that you don’t have to use jquery for this purpose if you don’t want to.
2) We’ve decided to use the Leaflet open source javascript map library to simplify our map rendering logic. Here, we link to this library and also the Leaflet style sheet.
3) This points to our very own javascript file where the map rendering and data retrieval logic is kept.
4) Styling for the map div; in this case just set the map size
5) The div to anchor our our map.

Step 2.3 – Write the javascript logic

As previously mentioned, we need code to render the map and to retrieve DSI data. All the code that we need in this example is in the dsimap.js javascript file. Our example contains the basic components that you’ll need to render any OSM map and populate it with information obtained from DSI entities. In this section we’ll explain all the code in dsimap.js at the required level of detail.

Declarations

f3

Line 1 is the jquery instruction that says that the code in this file – given that the scope of the parenthesis is the whole file – is only to be executed once the html document is ready.

Line 3 obtains the root URL for the server in which this code runs. This server will typically be your development (cisDev) server or a container server if the map web application is deployed on a DSI container server. This URL is used to build the REST URL required to perform DSI REST invocations. Note that if this web application is deployed on a server which is not a DSI cisDev or cisContainer server then you need to supply the URL of the target server (and resolve any cross domain issues that may arise).

Lines 4-7 define various global variables needed by our code.

Lines 9-13 define the icon that we’ll use as our person marker on the map. The ‘L’ is the variable that is used for Leaflet (so we’re creating a Leaflet icon structure). The ‘iconUrl’ points to our ‘person’ image. The ‘popupAnchor ‘ defines the point, relative to the icon anchor, where our pop-up will be anchored.
Map Initialization

f4

Line 15 calls the map initialization function (initMap()).
Line 16 calls the function that will retrieve the Person data from DSI (getPersons()).
Lines 19 -26 create the Leaflet map. The quoted ‘map’ parameter (in blue) is the identifier for the map div that we defined in our html. Note that in this case tiles are obtained from OpenStreetMap.org.

Using the DSI REST API

f5

Lines 30-37 – constitute the jquery ajax asynchronous call that is used to get the data from DSI (using the REST API). This is a ‘get’ call to a supported REST URL. The URL is constructed from the root url (defined above) and the standard DSI REST syntax and structure needed to access a DSI entity. For simplicity we’re only getting one Person entity instance (identified by the ‘111’ id). Once we receive the response (in an async way), we call a function called renderPersons() that we’ll use to render the retrieved Person data on the map. The object returned by our DSI REST API call looks like this:

f6

Polling DSI
Line 41 (below) is an important one.

f7

Because a person’s location will change over time, we need to constantly poll the Person entity in case it has changed since we last retrieved it. The more often you poll, the bigger the burden you place on the DSI system, so it is important to determine an adequate polling interval based on your solution’s requirements. Line 41 executes the getPersons() function every 5 seconds (5000 milliseconds). This is an approximate interval because javascript is not a multithreaded language.

Rendering data on the map

f8

The renderPersons() function is used to show a marker on the map at the location of our Person entity. The location coordinates are obtained from the returned Person object, as is the person name, which is displayed in the popup. To avoid unnecessary execution of rendering logic every 5 seconds, we compare the current coordinates to the previous and only do the rendering if the person’s location has changed since the last call (please see the sameLocation() code below).
Lines 48-50 remove previous markers so that we have only one marker for the entity.
Line 52 creates the marker at the required location, with the icon that we defined above, and adds it (as a layer) to the map. Line 53 pans the map to that location.
Line 54 creates the popup content (with the person name, in this example) and binds it to the marker.
Finally, lines 56-58 are used to show the popup every time the mouse hovers over the marker.

f9

This constitutes all the javascript code that we need to write for our simple map viewer. The next step is to deploy the web application and test our code.

Step 3 – Deploy the Web Application and Test it

After deploying the web application and starting the server, you should see the following message in the console log:
[AUDIT ] CWWKT0016I: Web application available (default_host): http://:9080/dsimap/

If your cisDev server is using security, you’ll need to access the application via its secure url (instead of the one above), typically:
https://localhost:9443/dsimap/

Assuming that the solution that you developed in Part 1 is deployed in the same server, you can now run the event sequence tests that you created for part 1. Start with the “createPerson” event sequence. After running this event sequence you should see a map that looks like this (the pop-up is shown when you hover over the marker and remains open until you close it):

f10

Conclusions

In Part 2 of our tutorial we have shown that it is relatively easy to display DSI data on a map using the DSI REST API, javascript, AJAX and Leaflet. Only basic skills were needed to develop our example but if you are thinking of creating an advanced interactive map you’ll need to be comfortable with javascript and Leaflet. The DSI Insight Map Viewer, which was discussed in Part 1 of the tutorial, does not require writing any code.

References

Leaflet
ODM Knowledge Center
Open Street Map
Open Street Map Org tile usage policy
Building your own OSM tile server
MapQuest Tile Server options
MapBox OSM Tile Server options

Join The Discussion

Your email address will not be published. Required fields are marked *