Skip to content
Branch: master
Find file Copy path
Find file Copy path
@ZakarFin ZakarFin Fixed typo 7dbbd60 May 23, 2019
6 contributors

Users who have contributed to this file

@ZakarFin @kessu @jampukka @data-ux @krotti @okauppinen
executable file 709 lines (480 sloc) 33.9 KB

Migration guide


Class renaming:

  • BundleServiceIbatisImpl is now BundleServiceMybatisImpl
  • ViewServiceIbatisImpl is now AppSetupServiceMybatisImpl
  • DataProviderServiceIbatisImpl is now DataProviderServiceMybatisImpl
  • OskariLayerServiceIbatisImpl is now OskariLayerServiceMybatisImpl

These might be used in app-specific migrations so you will need to update references to these.

Userlayer SLD update

There was a small issue on the SLD for userlayers where polygon border style was rendered with line style. To fix this you will need to manually update the SLD on the GeoServer Oskari uses to store userlayers. The SLD to use can be found here:

Optional: New WFS-integration system

This version includes a new implementation for interacting with WFS-based map layers that will replace the current "transport" webapp in the future. It supports WFS 3.0 endpoints and hands the features as vectors instead of images to the frontend. We would appreciate any feedback on the new implementation and testing it should not be a huge pain to setup.

Replace 'Oskari.mapframework.bundle.mapwfs2.plugin.WfsLayerPlugin' with 'Oskari.wfsvector.WfsVectorLayerPlugin' on mapfull bundle configurations. You can do this by modifying the applications/[your app folder]/index.js on your applications frontend code to change the appsetup it gets from the server:

jQuery(document).ready(function() { + 'action_route=GetAppSetup', window.controlParams, function() {
        jQuery('#mapdiv').append('Unable to start');
    }, function() {
         // App started
    }, function(appSetup) {
        // modify the appsetup we got from server
        var plugins = JSON.stringify(appSetup.configuration.mapfull.conf.plugins);
        var pluginRemoved = plugins.split('Oskari.mapframework.bundle.mapwfs2.plugin.WfsLayerPlugin');
        var modifiedPlugins = pluginRemoved.join('Oskari.wfsvector.WfsVectorLayerPlugin');
        appSetup.configuration.mapfull.conf.plugins = JSON.parse(modifiedPlugins);

OR you can use this Flyway migration as an example for your own instance to test it out:

You will also need to add "wfsvector" after "mapwfs2" bundle import in applications/[your app folder]/main.js on the frontend of your app:

import 'oskari-loader!oskari-frontend/packages/mapping/ol3/mapwfs2/bundle.js';
import 'oskari-loader!oskari-frontend/packages/mapping/ol3/wfsvector/bundle.js';


Logging configuration changes required

Log4j was updated to version 2.x.

  • If your application only uses the Oskari logger (fi.nls.oskari.log.LogFactory), no changes are needed.
  • If your application depends directly on the old 1.2.x log4j provided by Oskari, you should migrate to version 2
  • If your application depends slf4j provided by Oskari, you should change the slf4j implementation library from slf4j-log4j12 to

Log4j2 uses a new syntax for logger configuration. It will look for log4j2.xml named file on the class path (you can put it under Jetty directory resources/). Example configuration can be found in the documentation:

SLDs need to be updated to work with current GeoServer version

The updated SLDs can be found in

These need to be manually updated on the GeoServer that is used for providing the user generated content (the included GeoServer if not customized).


This release requires Jetty 9 to be used with the transport webapp. Jetty 8 no longer works as the CometD library has been updated. For migrating from the previous Jetty 8 package to the new Jetty 9 package you can download the new Jetty bundle from The migration is pretty straightforward:

  1. Download the new Jetty 9 package from

  2. Move any customized configuration from {Jetty 8}/start.ini to {Jetty 9}/oskari-server/start.d/oskari.ini

  3. Build your app with Oskari 1.50.0+ version and replace the war-files under {Jetty 9}/oskari-server/webapps

  1. Copy everything under {Jetty 8}/resources to {Jetty 9}/oskari-server/resources
  2. Start Jetty 9 with:
  • work directory as {Jetty 9}/oskari-server

  • Run:

    java -jar ../jetty-distribution-9.4.12.v20180830/start.jar

See and for more details.

You will also need to update the frontend for Oskari 1.50.0+ as the CometD client library has been updated and the old one doesn't work with the new server or vice versa.


JSP-files modified to match the new frontend build

There are some changes required for any customized JSP-pages:

  • jQuery is now part of oskari.min.js - remove script tag for jQuery
  • bundles/bundle.js has been removed - remove reference to it
  • resources/portal.css and forms.css are now part of oskari.min.css - remove references to them
  • app/overwritten.css is now part of oskari.min.css - remove reference to it
  • the "preloaded" variable is now always true - remove any logic using it

The frontend code is now always minified/bundled as oskari.min.js even on development environment. See the example app in oskari-server for template JSP in custom installs.


Due to being specific to NLS Finland services the code has been moved to nlsfi/oskari-server-extras#1 and but it's still available in For drop-in replacement change:





Changes to JSP-pages

Cross-site request forgery protection

Security features in Oskari has been improved by enabling cross-site request forgery protection. Any requests done with HTTP-methods other than GET is required to include a token as header or parameter to be accepted.

There are some changes required for any customized JSP-pages:

Oskari frontend code will automatically include the token by default on any action route calls made by it ( Most of the action routes (ones doing write operations) have been changed to only respond to non-GET requests(POST/PUT/DELETE).

jQuery update

The default jQuery version has been updated from 1.10.2 to 3.3.1 ( The functionality in oskari-frontend has been modified to work with the new version, but if you have customized bundles you might want to take a look at the official upgrade guide:

Here are most of the changes done for oskari-frontend:


AppSetup migration (OpenLayers 4)

Oskari 1.47.0 drops support for OpenLayers 2 ( Existing AppSetups of type 'DEFAULT' and 'USER' are automatically migrated to use the OpenLayers 4 implementations of the bundles. The other types (PUBLISH and PUBLISHED) have been using OL 4 for a long time already and don't need the migration.

Note! Any app using custom view types needs to make an app-specific migration for the custom types. Copy-pasting the migration (content-resources/src/main/resources/flyway/oskari/V1_47_3__migrate_appsetup_to_ol4.sql) and adding the types to the where-clause at the beginning should suffice:

type IN ('DEFAULT', 'USER') AND -- is right view type


UserLayer to separate modules

In order to use UserLayers in the future in your application you'll have to add the following dependency to your webapp-map:


Additionally, userlayer.default.source.epsg property is no longer used. Instead oskari.native.srs (same property used by GeoServer populator, defaults to "EPSG:4326") is used to determine the target projection to which all the UserLayers will be reprojected before they are stored in the database.

jQuery update 1.7.x -> 1.10.2

The frontend has been updated to work with a bit newer jQuery library. We recommend updating any app-specific JSP-files to be updated to use it as this is the version that is used when testing features:

 -    <script type="text/javascript" src="/Oskari/libraries/jquery/jquery-1.7.1.min.js">
 +    <script type="text/javascript" src="/Oskari/libraries/jquery/jquery-1.10.2.min.js">

New printout backend

A new printout backend has been added as part of the oskari-server. As of 1.46.0 ( the frontend uses the new backend so the old one can be removed.

Note! The new backend is part of the oskari-map.war so any installations using oskari-printout-backend.war can remove it from Jetty.


myplaces, userlayer, analysis baselayers migration

Due to changes in the initialization the baselayer setup has been moved from core to functionality specific flyway modules. The layers are now inserted with the same code used with the setup.war that initializes geoserver configuration. Configs that are used include:

# initialized the layer srs (also updated by setup.war if used to generate GeoServer config)
# connection info for GeoServer hosting the myplaces etc user content

Oskari initialization

Initialization of Oskari on empty database has been revised. All content creation has been moved to application specific flyway modules. The core module only creates the base database, migrates the schema and transforms existing data when needed.

For existing databases this is a non-issue and everything works as before. For new applications and application specific initialization for the database (like initial layers and appsetups) this changes a few things.

The sample application now creates the appsetups, layers and users for demo-purposes. Any oskari-server-extension should modify the application init on empty db accordingly.

The template for oskari-server-extension has been updated to match this change:

Check the readme for details!

GeoServer migration

If you have the bundled GeoServer (for myplaces etc) running on the same Jetty as oskari-map you should add this to

# skip geoserver setting as its by default on the same server -> geoserver is not running when migrations are run

Otherwise migrations will stop at 1.45.0 as this migration cannot be run. You can manually add a memory restriction for the GeoServer so asking for very large image for myplaces etc won't cause the server to run out of memory.

Database changes

There's at least a couple of database table that have been renamed and due to the order of code is running on server startup you will get an error with the first startup due to database migrations. The logs show some tables are missing. This is expected and you should just restart the server after migrations have completed. The latest version row in oskari_status database table should be at least 1.45.18 when the migrations have been completed.

Thematic maps

The release will force thematic maps (statsgrid bundle in frontend) to be updated to the new version. This requires a migration for any appsetups (including published maps) using the old version of the bundle. The configurations required for are (based on the database contents):

# datasource ids added for old indicators
# [SELECT id FROM oskari_statistical_datasource where config like '']
# [SELECT id FROM oskari_statistical_datasource where plugin = 'UserStats']

# layer name mappings for old regionsets (layer name for matching statslayer)
# [select name from oskari_maplayer where type = 'statslayer']

If your instance wasn't using the old thematic maps functionality you don't need to configure these. If you have the old thematic maps functionality in your application you need to add maplayers corresponding the regionsets before running the migration and configure the layer-names in

To configure the layers see:

For more information about the migration see:


Requirements change

Oskari-server now requires Java 8 to run and compile due to (and in preparation of) library upgrades.

Common issues:

Transparent fill & stroke on polygons

DefaultStyle SLDs needs to be manually updated on Geoserver from

Users service

The database access library has been updated from iBATIS to MyBatis. DatabaseUserService now uses MybatisRoleService and MybatisUserService. If you are using old IbatisRoleService or IbatisUserService in your own Oskari server extensions, you have to update them to use MybatisRoleService and MybatisUserService implementations.

Injected profile link (personaldata bundle)

Personal data (My data in UI) previously used the "edit profile" link from property 'auth.register.url' which is also used by other functionality as property that holds registration url.

This has been changed and personaldata now uses a more appropriate 'auth.profile.url' so registration and personaldata can co-exist without conflict.


User registration feature

The feature has been significantly changed. See ReleaseNotes for details.

Layer urls handling for https-services

Layers with http:// urls are now proxied using the GetLayerTile action route by default. Previously the protocol was replaced with https:// and to preserve this functionality you can add a property for


Thematic maps regionsets

Any statslayer rows in the database table oskari_maplayer should include a value in the srs_name column (like 'EPSG:4326'). This is required for creating GeoJSON for the regions and doing transforms on the geometry.

New bundle "maprotator" for sample application

The new bundle allows published maps to be rotated. The bundle is added to sample application views automatically. If you don't want it to be added to the sample you can add this property to


Openlayers 3 version for geoportal view for development

Initial Openlayers 3 geoportal view can be added for the sample application. To add it a property is required in


The view is NOT added automatically if you don't opt in. The view to create can be further configured with optional properties:

flyway.sample.1_0_11.view=[id for view to use as config/state template]

File needs to point to a json-file similar to The file should be located in the server classpath under /json/views/[filename]. Note that only bundle startup information is used while config/state is being copied from the default view of the Oskari-instance. If you want to use a custom view as config/state template you can use the flyway.sample.1_0_11.view-property to point such view. The log will show the uuid for the new view once it's added or you can check the database table portti_view for the uuid of the latest view in the system.


Code refactoring

fi.nls.oskari.control.view.modifier.param.ParamHandler has been moved from control-base to fi.nls.oskari.view.modifier.ParamHandler in service-control Maven module. Please update any references to point to the new package.

Database migration

In preparation for Oskari 2.0 some of the code has been moved to more appropriate places. As a result some of the previously mandatory imports on mapfull bundle have been removed. Update any custom minifierAppSetup.json files by removing references to these packages:

There is a Oskari core Flyway-migration that removes the references from database:

FlywayHelper method changes

There has been some changes to the FlywayHelper class. If you have used it in your applications Flyway-migrations you might need to change some of the existing Java-based migration classes. This might be the reason your previous Java-based migration classes don't compile after updating to new Oskari version. Java-based migrations are not tracked the same way as SQL-based ones so you can modify the existing migrations to accommodate this change. Here are the changes to the FlywayHelper signature:

FROM ArrayList<Long> getViewIdsForTypes(Connection connection, String... types) throws Exception
TO   List<Long> getViewIdsForTypes(Connection connection, String... types) throws SQLException

FROM ArrayList<Long> getUserAndDefaultViewIds(Connection connection) throws Exception
TO   List<Long> getUserAndDefaultViewIds(Connection connection) throws SQLException

FROM Bundle getBundleFromView(Connection connection, String bundle, Long viewId) throws Exception
TO   Bundle getBundleFromView(Connection connection, String bundle, Long viewId) throws SQLException

FROM Bundle updateBundleInView(Connection connection, Bundle bundle, Long viewId) throws Exception
TO   Bundle updateBundleInView(Connection connection, Bundle bundle, Long viewId) throws SQLException


The sample application can be updated to include the new statistics UI. If you are using the sample-application flyway module (have "sample" included in "db.additional.modules" property) and would like to have this bundle included, you can add a property:


This functionality is opt-in with the configuration since it needs additional manual configuration for datasources and maplayers to use as regionsets. The frontend minifierAppSetup.jsons for sample/servlet app include references to the frontend code so to optimize the filesize clients need to download you might want to remove them if not using the statistics functionality.

The sample application will also add more zoom-levels for the configuration. All views except published maps with EPSG:4326 will be have the resolutions (zoom-levels) set to:


You can opt-out of the resolutions change by adding a property in



This update includes a forced migration of publish template to Openlayers 3 based map. The possible Openlayers 2 based publish template will be copied to a new ID and the log will show a message like "Previous publish template was saved as a backup with view id: 1234." The update is skipped if Openlayers 3 based template is already defined for publishing, but you can also skip the update entirely by adding a skip property to

flyway.1_39_1.skip = true

Note! All new development is happening for Openlayers 3 based published maps and some features may be broken if migration is skipped. You should update the template manually if automation isn't working for you.

The bundles in the template are changed based on this template:

If you would like to use different page(JSP-file), application or path for the template you can override these by adding configuration to

flyway.1_39_1.application = servlet_published_ol3
flyway.1_39_1.path = /applications/sample = published

You can also specify a custom template to be used by providing a similar file in classpath with /json/views/my-template.json and using the property:

flyway.1_39_1.file = my-template.json

The update keeps any state and configuration values for the template as they are, but updates the bundles to use and the startup-fragment (filepath/location of the bundle).

Note! You will need to update the minifierAppSetup.json to reflect the new template. This can be used with the default setup:

Another update is used to migrate all published maps using Openlayers 2 based published maps to use the new publish template. This will programmatically "republish" all the maps having OL2 with the current publish template. This means that if you skipped 1.39.1 update for the template AND haven't done anything for updating the template manually this will use an unmigrated publish template. This is something to consider. You can skip the migration by adding a property to

flyway.1_39_2.skip = true

Note! If you skip this update you might need to have a separate template for new published maps using OL3 and older published maps using OL2. The migration will take a while depending how many published maps there are in the system. It can also fail, usually if there is broken/invalid JSON in config or state columns for bundles. You should fix the JSON manually in the database and restart Jetty to run the migration again for the rest of the published maps.

Tip! If you are trying to make a custom template you can:

  1. Skip this migration
  2. Try using the custom template with the publishing functionality
  3. When you are ready to use the template: delete the row from database table oskari_status for 1.39.2 migration
  4. Restart Jetty to run the migration using the custom template


The default config for statsgrid-bundle has changed and is now part of the code. The default config in portti_bundle is updated to empty config.

The storing of layer coverage geometries has changed in a way that might cause problems. If layer disappear from the browser UI a ~second after it has been added to the map you should wipe the oskari_maplayer_metadata table in the database:

     DELETE FROM oskari_maplayer_metadata;

This is only relevant if you have the scheduled coverage job enabled.


Forced view migrations - IMPORTANT!

Map publishing functionality has been implemented with a bundle called publisher. All current work toward improving the publishing feature has been done on a bundle publisher2. Since the old one is no longer maintained we are forcing an update to any view having the publisher bundle to start using the publisher2 bundle. This shouldn't cause any problems if you are using the standard publisher bundle with no modifications. If you absolutely want to keep the current publisher bundle and will deal with the changes yourself you can add a property to to skip this update:


You might also have ran this kind of update on your environment previously (through sample-module migrations for example). In such case this migration does nothing.

servlet-map/webapp-map - Openlayers polyfill

The latest Openlayers 3 doesn't work with IE9 since it lacks for example requestAnimationFrame() function: A polyfill has been added to published.jsp for browsers <= IE 9.

You might want to do the same for any custom JSP for published maps if you need to support IE 9.


Application changes to JSP-files

If you have a custom JSP in your Oskari installation you will need to modify it a bit:

Custom JSPs may have links to Oskari css and have global variables set for Oskari:


<script type="text/javascript">
    var ajaxUrl = '${ajaxUrl}';
    var viewId = '${viewId}';
    var language = '${language}';
    var preloaded = ${preloaded};
    var controlParams = ${controlParams};

These can be replaced with the following:


<script type="text/javascript">
    var ajaxUrl = '${ajaxUrl}';
    var controlParams = ${controlParams};

Note that you need to remove any references to these globals (language, viewId, preloaded) in index.js as well (in the frontend)

See for more details on frontend changes.

You should also remove any links to oskari_lang_all.js in JSPs as it's no longer generated and its content is included in all of the language files.

Geotools 14.2 upgrade (was 13.1)

There are some improvements in geojson parsing and new methods for parsing WMS/WFS capabilities. Basic oskari-server source is not modified because of this upgrade, only some unit tests.

toolbar in embedded maps

The configuration has changed for any published maps with toolbar. Automatic migration is done as part of the core migration.


Update IntersectionFeatureCollection2-2.7.1.jar in your webapps/geoserver/WEB-INF/lib directory. Build updated version in This is improvement for analysis Geometry clip method.


A new publisher template has been added: content-resources/src/main/resources/json/views/ol3-publisher-template-view.json. This can be inserted to database and configured as a publish template in to use Openlayers 3 as the map-engine for published maps:

view.template.publish=[view id]

This will affect all new maps that are published after the change. The previous ones will remain the same. If a view that is published earlier is edited and saved it will use the new publish template.


The sample application replaces publisher bundle with a refactored version named publisher2. This needs metadata to be generated for appsetups/views created with the original publisher. The sample flyway module has an example (flyway/sample/ how to make the switch in your application when you are ready. The script generates the metadata from existing published views and replaces the publisher bundle with publisher2 on all views which have the original publisher.

In older Oskari instances users might have saved views that still reference old bundles: mapwfs and featuredata. Views of type USER (portti_view.type) that have these (others shouldn't have them anyways anymore) are automatically updated to replace these with the current implementations. The code for these outdated bundles have been removed from Oskari frontend code a while ago so we need to remove references to them so the personalized default view can work properly.

Old saved views (that users can save) have the bundle setup that was used when the view was saved. Bundles added to default view after the view was saved are not part of those views. This results in personalized default views not having all of the functionality that is available in the default view. A workaround for this is for the user to click the saved view so the application state is changed based on the view and then save the current view as a new one. Then use the new view as the personalized default and delete the old saved view. To update all views of type USER to current bundle setup automatically, there is an example upgrade script in the sample flyway module (flyway/sample/ This update is not forced since some Oskari installs might have used the USER-typed views for other purposes than views saved by users.


Update sld_muutos_n1.sld in Geoserver Styles (updated file in \oskari\oskari-server\content-resources\config\geoserver\data\styles)



Flyway checksum validation fails if line-endings change in files for example between development environments: To work around this, can be used to autorepair the checksums:



servlet-map replacement

The servlet-map module has been replaced with spring-based packaging. This uses servlet 3 webapp initialization without web.xml. If you are using the Jetty-bundle downloadable from Add this row to {JETTY_HOME}/start.ini. Take a look at the new Jetty-bundle for example:


HTML-loading and action route handling has been separated with HTML response coming from the root path (/) and action routes are now handled with path /action. This propably requires a change in for the property:

# url path to call for ajax requests/action routes

The Maven artifactId was changed to clearly signal the change:



Java update

As the updated geotools version has dropped Java 6 support, Oskari now requires Java 7 as well.

Geoserver 2.7.1 and geotools 13.1 upgrade

Keep your current Geoserver data dir as is Replace your geoserver directory under webapps with geoserver dir in jetty-package

  • Current Geoserver build is against Geotools 13.1
  • know issue: RYSP WFS parser is not working and partly WFS transport tests fails, if older version of geotools is in use


DB upgrades

Update bundlepath of routesearch bundle

Routesearch bundle has been moved from under framework to paikkatietoikkuna. Bundlepaths in db need to be updated. Run the node.js upgrade scripts under content-resources/db-upgrade:

SCRIPT=1.29/01_update_routesearch_bundle_bundlepath node app.js
SCRIPT=1.29/02_update_routesearch_bundle_view_bundlepath node app.js

Update default configs for userguide and printout

Run on oskaridb:


Create new table ( oskari_wfs_parser_config) for WFS 2.0.0 initial parser configs and insert initial values



Now builds transport.war instead of transport-0.0.1.war as this is the default Oskari frontend uses.

You can’t perform that action at this time.