App state management

This page describes the new app state management since version 5.5.0. If you are using the deprecated bundles, please consult the documentation for version 5.4 or older.

In map.apps SDI it is possible to save the state of an app, share it with other people and restore it again at a later time.

The saved app states includes the following parts:

  • all map services and layers (including services added at runtime)

  • visibility of services and layers

  • transparency of services and layers

  • order of services, groups and layers

  • background maps

  • object sketches

  • map.apps ETL uploads

  • spatial reference system (SRS)

  • map scale

  • view mode (2D or 3D) and the associated camera position

  • the app’s color theme

Some things, e.g. the selected Styled Layer Descriptors (SLDs) for a WMS service, are not saved.

If you store app states containing a lot of geometries or data uploaded to the map with map.apps ETL, the database size in the save state service can increase significantly fast.

Use map.apps ETL upload tool config parameters maxFeaturesPerLayer and maxUploadSize to limit upload sizes.

Configuration

Save state backend service

The Save State backend service is required to save app states on the server. To install and configure it, read Installation of Save State Service.

App state management

To include the app state management features add the following bundles to your app.

sdi_appstate-ui (required)

This bundle provides the user interface to create, update, delete and load app states.

sdi_appstate-share

This bundle provides the function to share app states and generates links. It’s necessary to show the "link" function in the app state management user interface.

sdi_appstate-map

This bundle includes the necessary components to save and restore the state of the map, including the services and layers and their visibility, as well as the actual extent or spatial reference system. It is optional but recommended.

sdi_appstate-layout

This bundle includes a component to save and restore the color theme of the app.

For further configuration options of each bundle see the bundle documentation .

Services and layers

Always assign unique IDs (id property) to services and layers in your map configurations in the app.json file so that their state can be saved and restored properly.

If you do not specify IDs, dynamic IDs will be generated. Since these dynamic IDs vary with every app start, they do not work properly in combination with app states.

Access restrictions

If you are not logged in, you are allowed to create only public app states. These automatically get the view and edit permissions assigned, so they can be updated and deleted by everyone. However, existing permissions on those app states can only be changed by admin users.

If you are logged in, you can grant for each app state a number access permissions to certain users, user roles or to every user. Each permission is bound to one of these actions: view or edit. Those permissions can only be changed by the owner of the state or admin users after creating the state.

Users having the view permission for an app state are allowed to load it. For changing and deleting an app state, the edit permission is required.

If a permission is assigned to multiple user roles it applies to all users having at least one of those roles.

An admin user can view, update, or delete every application state — independently of the app and configured access restrictions.

Without further configuration all roles of the current user are shown in the list of roles. This can be configured. To configure the visibility options and user roles to show in the dialog, see the documentation of the StateDetailsModelFactory component in the sdi_appstate-ui bundle documentation .

To utilize this security feature, you have to configure map.apps and the savestate backend service for security. See Authentication for Save State Service for more details.
restrictions

Compatibility with legacy app states

The previous version of map.apps SDI had a simpler state access protection system. New states saved with the current version of map.apps SDI are not compatible with previous versions of map.apps SDI.

However, states saved with previous map.apps SDI versions are fully compatible with the current map.apps SDI version. They are automatically converted to the new format, once they are modified by a user.

App state properties and URL parameters

When using the parameter-url bundle shipped with map.apps in combination with map.apps SDI, URL parameters might be in conflict with properties having the same name in the saved app state. For this reason, when starting an app from a saved state, URL parameters always have precedence over properties with the same name in the saved app state. This allows you to selectively override properties that are stored in an app state.

Example

In this example, the c parameter in the query part of the URL will override the c property from the app state.

URL query part: ?c=7.13,52.4&bm=topo

App State:

{
    "mapView": {
        "c": "5.34,48.9"
    }
}