Update an existing installation

This page describes how to upgrade an existing installation to a newer version. Existing apps, app templates and report templates as well as uploaded bundles are preserved.

Before updating
  • Note the update notes in the Release Notes of the current version as well as all versions that lie between the current version and the version you have installed so far.

  • We recommend to make a backup of the database before updating your installation.

Determine the map.apps version

To identify which version you are running, open the URL https://<yourserver>/mapapps/info.txt.

Updating the installation

To upgrade map.apps to a newer version, follow these steps:

  1. Stop the Apache Tomcat server.

  2. Remove the old map.apps context from %TOMCAT%\webapps\ (move it to a backup folder before deleting it completely).

  3. Extract the new map.apps version to %TOMCAT%\webapps\.

  4. Edit the file %TOMCAT%\webapps\mapapps\WEB-INF\classes\custom-application.properties and point the data.directory.location property to your .mapapps folder. This folder contains the customized application.properties of your previous map.apps installation. The step is only required if the location of the folder .mapapps differs from the default location.

  5. Start the Apache Tomcat server.

Simplified update with external application.properties file
Do not modify the file %TOMCAT%\webapps\mapapps\WEB-INF\classes\application.properties. Use an external configuration file instead as described in configuration.


If you use the same name for the web application (for example %TOMCAT%\webapps\mapapps), the browser cache on every client machine has to be deleted, to make sure that all changes take effect. After a defined time of half a day by default, the changes take effect for all users without actively clearing the browser cache.

Default Apps

When creating a new app, you can choose to create a default app. The template file for this app (default-app-4.zip) is located in the map.apps data directory. To define the path to this directory, use the parameter data.directory.location in file %TOMCAT%\webapps\mapapps\WEB-INF\classes\custom-application.properties.

If you have not made any customizations to the default app, remove it from the working directory so that updated versions of the default app are picked up from the new version of map.apps.

Product Extensions

If you are running map.apps product extensions that are not compatible to the current map.apps Manager version, see Compatibility mode map.apps Manager 3.x.

Custom Development

If you use custom bundles in your map.apps installation that use the ArcGIS API for JavaScript, check for breaking changes that might effect your implementation.

Update existing apps

After updating from map.apps 3.x to 4.x, apps that should continue to use the 3.x version of bundles need to be customized. To do this, follow these steps:

  1. Select all apps in the app list that should use the 3.x version of bundles and click the tool Manage product versions in selected apps.

  2. Select map.apps in the first dialog.

  3. In the next dialog select the map.apps version 3.10.10.

  4. You can also define the update policy for your apps, which specifies how your apps deal with later versions of map.apps 3.x:

    • none: Apps are compatible with the exact map.apps version 3.10.10.

    • Bugfix: Apps are also compatible with all bugfix releases starting with version 3.10.10.

    • Minor: Apps are also compatible with all minor releases starting with version 3.10.10 (recommended).

Bundles with version 4.12.3 are not used for your apps. After the settings are applied, a summary of all apps is shown. For each app a detailed list of all rewritten bundles and their versions is available.

Now all your apps are set to the 3.x-version of the map.apps bundles and can be used.

Usage of App-Templates

Existing app-templates have to be updated and uploaded manually. Otherwise when creating new apps the previously described step has to be repeated for every new app based on the map.apps 3.x app-template.

To do so, you can create an app based on the app-template, update it, export the app without changes and import it again by overwriting the app-template.