The Insight Map Viewer
This is the first 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. The tutorial is at an introductory level and its goal is to give readers an understanding of the process that they need to follow to represent DSI data on a map. For a deeper understanding of the Insight Map Viewer and the DSI geospatial capabilities we recommend that you explore the links in the reference section.
Part 1 of the tutorial is not just about the Insight Map Viewer. It is also about the development and configuration steps that you need to follow from the moment that you decide to use geospatial features in a DSI solution to the point that geospatial data is rendered by Insight Map Viewer.
Part 2 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.
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.
The Insight Map Viewer feature (hereafter referred to as â€śMap Viewerâ€ť) is intended to be used by DSI Solutions that have geospatial attributes (for example, points or moving geometries). The Map Viewer uses â€“ primarily – OSM for map viewing. In order to show maps in a browser, OSM requires map tiles to be served from an OSM tile server. Except for very limited testing purposes, you should not use the tiles supplied by OpenStreetMap.org itself. You have the option of creating your own OSM tile server (please see references) or consider a commercial tile serving service. Some of these commercial services have free options – albeit with restrictions – that may be sufficient for your development and testing needs, for example, at the time of the writing of this tutorial:
- MapQuest Open has been discontinued but you can now sign up to a MapQuest plan that is free and has a cap of 15000 transactions per month.
- Mapbox has a free service that is capped at 50K map views
Until recently IBM used to provide an OSM tile server for IBM and customer practitioners to use in DSI demos, POCs and DSI solution development and testing. The IBM tile server is still configured as the default tile server in the latest DSI release but, unfortunately, IBM no longer provides this service. In addition, IBM Interactive Maps for Bluemix has been retired and is no longer available as a Bluemix service. For this reason, strictly for this tutorial, we will be using OpenStreetMap.org tiles.
Step 1 â€“ Define the â€śbusinessâ€ť problem
I’ve decided to go on a long cycling trip this summer. I plan to start at IBM’s lab in Hursley and go all the way to Paris to visit my ODM friends and colleagues. Since this is a solo effort I want to keep my family informed of where I am at a particular point in time and I’ve chosen DSI and its Map Viewer feature for this purpose. Yes, I know, there are easier ways to tackle this particular problem but, for the Map Viewer basics, I need a really simple example.
Step 2 – Create a DSI solution with geospatial capabilities
Step 2.1 â€“ Create the business model definitions
We assume that you are familiar with the process of creating a simple DSI solution. If you are not, please consult the references section below. Based on this assumption we go straight to the business model definition to create entities and events. The entity I need to track is me, but given that I have ambitions for this project, I’ve decided to create a solution that tracks not just me, but also any person who chooses to use this solution. So my entity definition will look like this:
a person is a business entity identified by an id number .
a person has a name.
a person has a location ( a point).
That’s it! We now have an entity capable of storing a person’s identification data as well as a person’s geographic point location.
Next I need to have a means of creating the specific instance of the entity that I need to track. One way to do this is via the use of an event and an entity initializer. The required event definition is as follows:
a create person event is a business event.
a create person event has an id number.
a create person event has a name.
a create person event has a location (a point ).
…and this is the initializer: (defined in the model’s ‘Statements’ tab):
a person is initialized from a create person event , where this person comes from the id number of this create person event :
- set the name of this person to the name of this create person event
- set the location of this person to the location of this create person event .
At this point we have a way of creating a person and setting that person’s initial location but we still don’t have a way of tracking the person’s location has he/she changes location. For this we need another event, which we define like this: (the ‘id number’ is the id number of the person, which is used for correlation)
an update location event is a business event.
an update location event has an id number.
an update location event has a location (a point ).
With this we conclude our business model definitions.
Step 2.2 â€“ Create the required business rules
We don’t need a rule for creating the Person entity because we have an entity initializer for this purpose, but we do need a rule for updating the entity. First, we create a Rule Agent project with the following agent descriptor so that the agent is capable of processing our update location event:
'dsi_map_example_rules' is an agent related to a person ,
processing events :
- update location event , where this person comes from the id number of this update location event
then, we create the update location rule itself:
when an update location event occurs
then set the location of 'the person' to the location of this update location event ;
We’re done with the rules. The next step is to create the instances of entities and events that we will use to test our solution.
Step 2.3 â€“ Create the solution’s tests
Once the solution is deployed in production, the initialization of the entity and the update location events will likely come from a personal mobile phone. For development and testing purposes, DSI has a number of testing capabilities (the description of which is out of the scope of this tutorial). For this solution we’ll use ‘event sequences’ to carry out our tests.
For example, this event sequence creates the entity and initializes the location coordinates to a point in the village of Hursley:
define 'jose' as a new create person event where
the name is "Jose" ,
the id number is "111" ,
the location is the point with -1.39114 as longitude and 51.02279 as latitude ;
emit 'jose' , time-stamped 1/6/2017 ;
Another event sequence is used to emit an update location event with a point location in Winchester:
emit a new update location event where
the id number is "111" ,
the location is the point with -1.308 as longitude and 51.0632 as latitude , time-stamped 1/6/2017;
…and yet another for London:
emit a new update location event where
the id number is "111" ,
the location is the point with -0.118092 as longitude and 51.509865 as latitude , time-stamped 1/6/2017 ;
We don’t care too much about the time stamp of the events because we’ll be running the event sequences manually (and separately).
Before we run our tests, we need to first configure the development server with the Map Viewer feature and then deploy the solution.
Step 3 â€“ Configure the Map Viewer
Step 3.1 â€“ Add the Map Viewer feature to your development server
Open the cisDev server.xml file and install the Map Viewer feature by adding <feature>ia:iaMaps-8.8.1</feature> to this server’s feature manager, like this:
Step 3.2 â€“ Configure the Map Viewer
After deploying the solution and starting the server, you should see the following messages in the console log:
[AUDIT ] CWMBD0060I: Solution dsi_map_example-0.0 ready.
[AUDIT ] CWWKT0016I: Web application available (default_host): http://<your ip address>:9080/ibm/maps/
Open a browser on that url.
Follow these steps to point to another OSM tile server:
1 – On the 3 bar menu, select â€śExport settingsâ€ť . This option exports the following json file: (I have formatted the file so it makes easier reading)
2 – Replace the map specification with the following one and save the file. Again, we emphasize that you should only use OpenStreetMap.org tiles in very limited situations and should point instead to your own Tile server or to a commercial one:
3 â€“ Select â€śImport settingsâ€ť and import the modified settings file.
In order to avoid errors in the log resulting from polling for entities that don’t exist, run the â€ścreate personâ€ť event sequence, which creates an initialized entity.
If you right click on the position marker and select ‘edit’ you’ll find that there are a number of interesting ways to convey information about the entity. For example, I chose a person icon and changed the colour of the marker. This can be seen below after sending a Paris location:
There are much more advanced things that you can do with the DSI geospatial capabilities and the Map Viewer. As a next step we recommend that you install and study the Car Rental sample that comes with the product.
In this tutorial we have followed the development and configuration steps that are necessary to display DSI entity data on a map. We conclude that this is a relatively easy process that does not require that you write map rendering or data access logic. If you need greater flexibility and are willing to write some code there are other ways of rendering entity information on a map. In Part 2 of this tutorial we’ll explore one of those alternatives.
ODM Knowledge Center – Viewing entities on a map
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
IBM Interactive Maps for Bluemix Documentation