MapBox classic style migration

Modified on Tue, 2 Jun, 2020 at 10:53 AM

This article documents the MapBox "classic styles" deprecation and how to migrate your installations and/or IOK files to resolve it. 


For Omniscope Classic users and publishers, action is required. If only using Omniscope Evo, nothing is required; Omniscope Evo is unaffected by this issue.


Omniscope Classic (or 2.9) uses MapBox to provide some of the base maps used in the Map views within your IOK file dashboards/reports. In all versions of Omniscope Classic prior to Omniscope 2020.2 b20956 ROCK, these used a legacy MapBox style configuration and API to retrieve the images forming the base map. 


From June 2020, these have been deprecated by MapBox, meaning reduced SLA and only available to pre-existing apps for a limited time (no greater than a year / June 2021, perhaps earlier).


When these maps stop working for your Omniscope installations, you will see blank base maps instead of the usual, for any IOK files using any of the following Omniscope map configurations:

  • Online world
  • Online world, calm
  • Other online maps → Blue
  • Other online maps → Red
  • Other online maps → Road 1
  • Other online maps → Road 2


It's also possible, but extremely unlikely, that you've created IOK files with Map views utilising "custom online tiled maps" and with a MapBox URL in their configuration. These will be shown in the Map view's Map menu as Online tiles "<name>". If you do have such a case, get in touch with us and we'll help you migrate them. For the purposes of the remainder of this article, we'll disregard that case.


Wstrongly recommend you migrate your installations or reconfigure your IOK files as soon as possible to avoid loss of mapping in your dashboards.


There are two ways to resolve this issue; you should do the first, and perhaps both:


  1. Upgrade your Omniscope installations (recommended).
    This is the simplest solution. Omniscope 2020.2 b20956 and later uses new MapBox styles automatically for all the 6 affected Omniscope map configurations affected (above); these are designed to match the previous styles reasonably closely. If you're in control of your Omniscope installation(s), this is all you need to do. Download now.

  2. Reconfigure your IOK files to have an embedded map.
    This is only recommended if you are not fully in control of your Omniscope installations. For example, you may be distributing IOK files to your clients, as part of the Omniscope Classic "free viewer" publishing paradigm. If you believe some of your IOK files may be opened by users who are unable or unwilling to upgrade their Omniscope installations, you should follow this approach too.
    1. Download the OnlineWorld.map attachment to this article (below).
    2. For each IOK file that has Map views, open it (in whatever Omniscope Classic or 2.9 version you have installed - regardless of whether you have upgraded it yet or not).
    3. Find the first Map view, and open the Map menu; choose Browse for image file:
    4. Browse for the OnlineWorld.map file you downloaded. Omniscope will embed the map into the IOK file (such that it will work without needing an upgraded Omniscope installation), and will select it for this Map view.
    5. For every other Map view in the same IOK file, open the Map menu and choose Online tiled map "OnlineWorld.map":

Your maps should now render correctly. If hosting IOK files as legacy Omniscope Mobile web deployments, either approach above will work, but only the first is necessary.


For any help with this issue, please don't hesitate to get in touch.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article