Verweis zu sachsen.de
Documentation
Tutorials
General Tutorial - Zoom API Tutorial - Graphics API Tutorial - Get Graphics API Tutorial - Filter API Tutorial - Selection API Tutorial - Map Load API Tutorial - Map Export API Tutorial - Tool Visibility API Tutorial - Element Visibility API Tutorial - Service-Layer API Tutorial - Print geo documents Tutorial - Get search results Tutorial - Filter und Zoom (Landwirtschaft) Analysis interface Feature attributes by messages Set user interaction

Tutorial

App Versioning

General information

Because of technical and organizational reasons, the actual production environment (geoviewer/geoportal.sachsen.de) is also used for internal testing regarding various integration scenarios done by external contractors. Using the production environment three separate profiles need to be prepared and deployed; both of them with different purposes:

  1. Development Version (Development)
    • Development of migration tasks because of e.g. breaking changes.
    • Switching to different technical approaches
    • Testing and evaluating new functionalities and bugfixes.
    • Testing purposes, which should be be transported to test or prod system.
  2. Test Version (Test/Staging)
    • Represents the most up-to-date version with the latest changes
    • New functionalities, which are not fully tested in the actual integration scenarios, are introduced in those version.
    • Bugfixes, which need to be retested by specific stakeholders
  3. Productive Version (Production)
    • Represents the version, which is defined as stable by all stakeholders
    • Quality ensured functionalities
    • Solid implementation without the risk of accidental applied changes

Challenges

Although the underlying map.apps framework offers functionalities for versioning the clientside implemented bundles (e.g. GeoBAK Integration API), it is not trivial to create a sophisticated workflow for administrating and maintaining the actual used "Geoviewer Apps / map profiles", which are then used for the 3rd party implemented applications. Indeed, the map.apps framework itself can be seen as a running web-service, hosting the preconfigured and for an specific use case adapted specialized apps, but organizational aspects plus technical limitations need to be considered:

  • Geobak-Integration API application developers are responsible for the implementation of new features and bugfixes, which are then available to other 3rd party integrations.
  • Geoviewer Administrators is responsible for the functional and technical deployment of a "map profile". This is realized using the map.apps framework, where different apps are created and published.
  • 3rd party application developers use the "geobak-integrationAPI" as well as the provided "map profile" for their applications. There should be no need to worry about the first two points. Also due to the fact that the complexity should be as low as possible and an expert knowledge in one of the two areas should not be needed.

For a better understanding in regard to the technical limitations, a short summary of the "app" and "bundle" concept is given.

Bundles concept

  • Clientside functionalities are implemented as separate bundles, which can be understood as packaged, independent runnable components within the map.apps framework.

  • The bundles themselves are defined via a specific "bundle-version", which is automatically increased during the internal development process. If a new version is deployed, a newer version-declaration is used.

  • The map.apps framework supports a "bundle-versioning approach" by hosting a "JS Registry". The JS Registry is a REST service provided by the map.apps web application to upload, browse and query JavaScript packages (bundles). The JS Registry can handle multiple versions of the same JavaScript packages.

App concept

  • An app is a definition of several functionalities and tools (implemented as bundles), which are combined and configured within an app.json file.

  • A Geoviewer Administrator is able to set app-specific parameters and settings within this application. It is also possible to define a concrete "bundle" version, which should be loaded to the map. If no bundle-version-definition is used, the latest/newest available bundle implementation is loaded.

  • In contrast to the JS Registry approach, where multiple versions of one bundle can be handled, the app concept is based on "app-identifiers" (appId) without the feature of versioning an app.

App Versioning Appoach

Based on the last mentioned facts that per default the lastest/newest available bundle-version is loaded in an app, bundle-implementations might be integrated in productive used apps, which were not fully tested, evaluated or integrated in 3rd party applications. To solve this potential risk, we will provide two different app-profiles (a third, if a development version is needed) for each needed app, all with the same functionalities, but with different bundle versions. To differ between the "dev", "test" and the "production"-app, different "app-identifiers" (appId) will be used. To give an example:

  • integration-app_dev
    • This app will always include the latest/newest bundle implementation. The _dev application can be used for early testing. The dev app might not be stable in their functionalities since breaking changes and bugs could be present. All changes and improvements are listed in the corresponding changelog.
  • integration-app_test
    • This app will include the most recent stable bundle implementation. After the actual implementation is done, the _test app could be used to be integrated in the 3rd party staging environment, where the overall integration mechanism is tested.
  • integration-app_prod
    • This app will include the production related bunde implementation, which was previously used in the test app and which is fully tested in the corresponding integrated szenario.

Workflow

The overall workflow of providing these apps is outlined in the following diagram. [//]: # (![Schematic visualization for app versioning.](tutorial/assets/app_versioning.png "Schematic visualization for app versioning.")) Schematic visualization for app versioning

Some additional information regarding the diagram (from left to right)

  • API Developer Responsibilities
    • Developing the IntegrationAPI
    • Deploying new IntegrationAPI version(s)
  • App Admin
    • Providing the required and desired functionalities in form of apps
    • Creating the needed app-profiles (dev, test, prod)
    • Configuring the apps regarding the corresponding IntegrationAPI versions
      • app_dev: Define IntegrationAPI version @latest
      • app_test: Define IntegrationAPI version @latest or latest+1 version
      • app_prod: Define IntegrationAPI version @most stable version, which were tested via dev and test integration
  • 3rd Party Dev
    • Ensure that the appropriate app profile is referenced in the corresponding environment. This ensures that the matching IntegrationAPI Version is loaded and used.