Alternative to the Insight Map Viewer
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.
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.
1) An image file (person.png) representing the icon that we’ll use as a position marker in our map.
3) An HTML file (index.html), which contains the minimum amount of html needed to show the map in the browser.
Step 2.2 â€“ Write the html
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.
4) Styling for the map div; in this case just set the map size
5) The div to anchor our our map.
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.
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
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:
Rendering data on the map
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.
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:
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):