map.apps Manager
The map.apps Manager is used for management of apps, app templates, bundles and report templates in a browser.
To open the manager, call the URL https://<yourserver>/mapapps/manager or click Manager in the upper right corner of the app overview under https://<yourserver>/mapapps.
Access authorization
Access is allowed for two user types:
- Administrator
-
An administrator can fully manage map.apps (apps, app templates, bundles and report templates).
They can upload new content, change existing content and delete it.
- Editor
-
An editor can only manage apps in map.apps Manager.
They can use app templates, bundles and report templates provided by an administrator.
The credentials for these users are defined in the map.apps configuration. Please read section Authentication for further details.
Apps
Create new app
To create a new app, click + Create in the Apps tab.
Next, enter a title for your app. If you use the default layout, this title is displayed to users within the app and is also used as the title for the browser window.
Based on the title, an app ID is suggested. This ID is used in the URL with which the app is started. You can customize the ID.
| Do not create apps with IDs that only differ in their case from already existing apps. |
New apps can be created through one of the following three modes:
-
Default app
-
Use app template
-
Upload app
Default app
Select Default App to create a new app with the most commonly used features. Contents and further functions can be added to the app afterwards. For more information, see configuration of apps.
The template for the default app (default-app-4.zip) is located in map.apps data directory.
The app can be modified there or replaced by other apps so that they are used as default apps.
Publish app
Apps can have various states:
-
Draft (default)
-
Edited
-
Verified
-
Published
-
Deprecated
Users can only view and start published apps. Administrators and editors have access to all apps.
If map.apps is operated with the option for individual authentication, access to shared apps can be restricted to specific roles.
Follow these steps to protect an app:
-
Open the app publication dialog and set the app’s state to published:
-
Step forward to the sharing screen and select the roles the app is usable for. For security reasons, an administrator/editor can only authorize apps for roles that they themselves own.
-
Complete the dialog and save the app.
The app is now protected and invisible for non-authenticated users. Users can click Login in the app overview to sign in. After authentication, users see all public (non-protected) apps and all apps accessible for them. Protected apps can then be started without a separate login.
When opening an app directly with the app’s URL, a login dialog is shown. After a successful verification, the app is started.
To display user information as well as the logout-button inside the app, add the bundle authentication to the app configuration.
Delete app
An administrator or editor can delete apps in map.apps Manager. These apps are removed from the database and cannot be restored. Set an app to the Deprecated state to make it no longer accessible without deleting it.
| If an app is registered as an element in ArcGIS Online/ArcGIS Enterprise portal, this element is removed when the app is deleted. |
Export app
Apps can be exported as a zip file. In this file, all data of the app (including for example images or CSS files) is stored. Export an app to upload it as an app template, archive it or share it with others.
Register apps in ArcGIS Online or ArcGIS Enterprise portal
An app can be registered as a portal item in the map.apps Manager. Title, description and preview image are copied from the app metadata to the portal item. The map.apps dialog contains a link to the corresponding portal element. The used portal instance can be defined in the global configuration.
When creating a portal element, a login to the portal is necessary. This step is not necessary if map.apps is connected to the user management of the portal (see Authentication with ArcGIS Enterprise portal).
The status of the portal registration is represented by the following symbols in map.apps Manager:
App is not registered |
no symbol |
App is registered as Portal Item |
|
App is registered as Portal Item, portal is serving as identity provider (OAuth) |
|
| The display in the app overview is not updated if you remove the registration in the app editor or delete the item directly in ArcGIS Online or ArcGIS Enterprise portal. Open the Portal Registration dialog to update the status. |
Set bundle versions for an app
Bundles used in an app must be used in compatible versions.
The Manage product version in selected apps tool lets you change the versions of all bundles used for a product (such as map.apps or a product extension) at the same time. To do this, you must first select the product and the corresponding version.
In addition to selecting the minimum version, one of the following update guidelines can be selected:
| Choice | Description |
|---|---|
No updates |
The app is only compatible with the exact version specified. |
Bugfixes |
The app is compatible with all bugfix versions starting with the defined version. |
Minor Updates |
The app is compatible with all minor versions from the defined version onwards. |
Manually define bundle versions
The versions of bundles used can also be defined in the App Editor.
The bundle name must be separated from the version by a @. Example: toc@1.2.3.
The version number can be defined according to the Semantic Versioning specification .
The map.apps system is configured independently of the versions of individual bundles.
To define the version of the map.apps system, set the following property in the properties section of the app.json file:
{
"properties": {
"amdPackages": "apprt@1.2.3"
}
}Export app for native app
The Export for native app tool lets you export any app, including all resources, as a zip file. The app configuration and the bundles used in the app are analyzed and made available for download. Compared to the Export App tool, these results can be used as a basis for creating a native app.
To export all required JavaScript files, the tool integrates all AMD modules of the configured bundles.
If an app uses its own bundles, it must be ensured that these are optimized and that a dependencies.json file exists.
Use the appropriate input field to add further modules or files.
Use absolute URLs in an app, because the use of protocol-relative URLs like //www.example.com in native apps can lead to problems.
JavaScript files are sometimes loaded during the runtime of an app.
When exporting, these are not determined in advance and are therefore not integrated into the zip file.
The missing files can either be added manually in the expert settings or loaded in separate bundles.
If the bundles map-preload-2D and map-preload-3D are added to the app, the files are already loaded at the start of the app and also integrated into the zip file during export.
Pre-optimize app
Enable pre-optimization
To make the start of an app faster, click Enable pre-optimization in the app configuration window. The pre-optimization process might take several minutes.
Apps that are pre-optimized can be recognized in the apps table of the manager.
To disable pre-optimization, click the same button in the app configuration window again.
In which cases is performance improved?
Pre-optimization improves the startup performance of an app in the following cases:
- In case of repeated visits to an app by a user over a longer period of time
-
Without pre-optimization, static files are no longer loaded from the users browser cache after half a day (unless the expires setting is changed in the global configuration), but are loaded from the server again. For pre-optimized apps, certain files that are required to run the app are given a static ID as the file name. These files are loaded from the browser cache indefinitely, which significantly reduces the amount of data and thus the loading time when an app is called again.
- When many simultaneous calls are made by different users
-
Without pre-optimization, the different dependencies of bundles used in an app are analyzed each time an app is started to ensure that all required bundles are loaded. In pre-optimized apps, the bundle composition is considered complete and static, and this dependency analysis is omitted. This significantly reduces database queries and server-side processing operations, which provides a performance benefit, especially when there are many concurrent accesses.
What needs to be considered after activation?
Pre-optimized apps are detached from dynamic dependency resolution. This results in the fact that updated bundles or newly uploaded bundles of a pre-optimized app are not known.
Improvements or bug fixes in a bundle are thus not visible in the app. Furthermore, depending on the changes made to the bundles, the app may not launch at all or may not launch correctly. To ensure that changes in pre-optimized apps take effect, you must disable pre-optimization and then re-enable it. Pre-optimization is disabled if an app is uploaded, again.
Therefore, enable pre-optimization only for apps that are considered final and ready for production use.
|
When map.apps is updated to a newer version, pre-optimized apps are no more able to detect required bundles, because they are not present in the system anymore.
Global settings referenced by bundles from |
App Templates
Administrators have the ability to provide templates for apps. Templates define basic settings (for example used bundles and their configuration, map services, layout) which are adopted by every app created with the template.
Editors are not allowed to administrate templates. However, they can base their own apps on them.
Bundles
Upload bundles
New functions can be added in the form of so-called bundles. Bundles must be uploaded as ZIP or JAR files. The uploaded bundles are stored centrally in a database. Existing bundles are overwritten if bundles with identical versions are uploaded again. Pre-installed bundles cannot be overwritten.
Export bundles
Bundles that are added to the default bundles can be exported using the following URL call:
/resources/jsregistry/files/<file id>/download
Example:
https://<yourserver>/mapapps/resources/jsregistry/files/dn_querybuilder@1.0.0@MAIN/download
Add bundles from con terra Developer Network
Further bundles can be installed directly from the con terra GitHub in map.apps Manager.
This connection is activated by default.
To deactivate it remove the bundle mapapps-github-manager from the list manager.config.viewbundles in global configuration.
Report Templates
Administrators can manage report templates based on JasperReports technology. Templates are provided centrally and linked to the data in the respective apps (see Reports).
A default report is being provided.
This report template displays an overview map containing all features and includes a detail page for each feature containing the list of attributes and a detail map.
The default report is located in folder WEB-INF\classes\reports\default.
| Do not use special characters or umlauts in filenames used in a report template. |