Welcome MapServer: Visioglobe updates map retrieval mechanism

Explanation of new map retrieval mechanism…

Striving to provide tools that are simple and robust, Visioglobe has recently unveiled a new mechanism for retrieving Map Bundles.

Until Novembre 2015, the service in charge of storing and providing latest maps was the VisioMapManager. However after a long and successful duty of almost 4 years, needs have changed.

The expansion of features in the SDKs and VisioMapEditor required a more scalable and flexible service. After a few months of development and testing, VisioMapServer is now going to slowly replace its predecessor over 2016.

This brings several changes, in the map administration as well as in the code. This article will describe all the changes to help with the migration.

Why? Problems it solves:

What is this about Data Version?

A Map Bundle has two versions, the SDK version that determines the features that are available, for example footprints, and the SDK Minimum Version that determines the minimum version of SDK that can properly read or parse the map.

There are the following tricky scenarios:

• Old SDK does not handle new Map Bundle – There are other Map Bundle changes, for example optimizations on the rendering or load speed, that break backward compatibility (for example between VisioKiosk 1.7.10 and 1.7.14), so it is important that an old SDK does not try to read this new Map Bundle.

• Map Bundle doesn’t have feature support –  The Map Bundle changes that add new features such that it can be read by previous SDK versions, without taking advantage of these features.  Nevertheless, for certain applications, it is important to know if these features are supported.

• New SDK does not handle old Map Bundle – This is a future proof case, where a SDK would drop support for using very old Map Bundles

All are handled by having an sdk_version and sdk_min_version tied to the Map Bundle (in the description.json file) and having the SDK’s know the minimum data version they support (via SDK API’s VgEngine::VgILicenseManager::staticGetRevision() and VgEngine::VgILicenseManager::staticGetMinimumDataSDKVersion())

How is this all achieved?

The new architecture adds an extra level of indirection – a description .json file – that describes the different properties of the map and where to get the Map Bundle (.zip file) or the main map file (map.json for VisioKiosk), for example:

{
	name: "com.visioglobe.sdk/visioislandmultibuilding",
	timestamp: "20151222114822",
	zip_file: "map.editor.zip",
	secret_code: 123456,
	sdk_version: "4.0.0", // for Move it would be like 2.1.7, or Kiosk 1.7.19
	sdk_min_version: "2.0.0", // for Move generally be like 2.1.0
	sdk_type: "move" // or "kiosk" or "web2d"
}

One thing you will notice, is that the secret code is available on the description file, this moves the “secrecy” of the login/password to the URL used to access the map, which uses HTTPS for retrieval.  With VisioMapManager, the map was downloaded on VisioMove with a URL like:

https://mapmanager.visioglobe.com/public/download?map_id=XX&username=YY&password=ZZ

With VisioMapServer, the new url will be of the form: https://mapserver.visioglobe.com/mxxxxxx/map.zip

How will this impact existing applications?

Once your publishing target is changed from VisioMapManager to VisioMapServer, old applications (that don’t reference VisioMapServer), will no longer get map updates; new applications (referencing VisioMapServer) will get map updates.

Action Plan: What do you need to do:

We encourage you to migrate to the new architecture.  For that, you need to do 5 simple steps:

1. Request your account manager to configure your VisioMapEditor map to publish to VisioMapServer

2. Republish your map on VisioMapEditor, this will publish the map on VisioMapServer, ready for your application.  Recover the new hash URL from your user profile on VisioMapEditor.  See below.

You can also see the difference on how the publish window looks when publishing on VisioMapManager and VisioMapServer:

3. Update your application to use VisioMapServer, you can at this point, also update to the latest SDK.  For VisioKiosk/VisioWeb2D, it simply means updating the library files, and the URL used for the map

Since version 2.1.5 released on September 2015, VisioMove support the new hash management. The old credential method (mapname, username, secret) has been flagged as deprecated and the sample was using the new hash way to fetch the latest version of the sample VisioIsland map.

If your data are hosted on a specific server, you will have to specify it with mServerURL = …

Since version 1.7.15 released on September 2015, VisioKiosk and VisioWeb2D SDKs support the VisioMapServer.  Since it already uses a hash-based identifiers, the developers just have to replace the old mapURL with the new one.

4. If you update your SDK, please notify your account manager to update the Map’s target SDK within VisioMapEditor.  Currently, the Map’s target SDK are not updated automatically, to avoid breaking compatibility (for example in the case of VisioKiosk 1.7.14 and 1.7.9)

5. Publish your application on the application’s store.

The future of VisioMapManager:

Visioglobe is going to setup new clients using the VisioMapServer and encourage old clients to update their VisioMapEditor Maps and Applications/Websites to use the VisioMapServer.

VisioMapManager will continue to function, even after 2016, to serve un-updated applications.  We will work with clients to determine if VisioMapManager can be turned off in early 2017 or before.