App template synchronization (deprecated)

In a map.apps environment with several similar apps it’s often required to perform changes on the configuration of all apps in the same way. If many apps are affected this results in error-prone work and maintenance becomes more difficult. There is a tendency that apps slowly diverge from their common app template and lose their consistent appearance.

Here, the app synchronization feature of map.apps helps out. This feature makes it possible to merge changes done on an app template into all apps that are based on that template.

Activating App Synchronization

To create apps based on app templates and make use of map.apps' synchronization feature, first upload an app template in the map.apps Manager. Afterwards you can create apps based on that app template. In the wizard for configuring apps you can switch on synchronization in step 5.

app template information

Synchronization can be triggered either by clicking Synchronize now or each time a new app template is uploaded.

Synchronization Modes

There are two types of synchronization:

Replace: On every synchronization the app is replaced completely by the app template it is based on. All changes previously made to the app are lost.
Merge: The app is merged with the app template on a per-file basis. Additionally, single configuration properties in the app configuration files (app.json) are taken into account. The nex section describes this synchronization mode in detail.

The "Merge" synchronization mode

The merge synchronization mode works like this:

All files in the app are synchronized with the app template.

Files that have been deleted from the app template are also deleted from the app (regardless whether the files in the app have been changed or not). So all changes are lost.
Files that habe been added to the app template are also added to the app.
Files that have been changed in the app template overwrite the corresponding files in the app. Individual changes in the app are lost.

The contents of files are not analyzed and synchronized, but only the existence of certain files is checked. The app.json files are an exception.

Synchronizing the app.json files

When synchronizing the app.json files single configuration properties are taken into account.

By default, every change of a property in the app template is merged into the corresponding app. So if a property is added to the app template it is also added to the apps. Changes to a property in the app template are even merged to the app, when this property has previously been changed in the app. Therefore, the change made in the app is lost. If a property in the app template is removed, this property is also removed from the apps. Only properties that are newly introduced in an app and that do not exist within the app template, are preserved.

Example: The app template contains a bundle configuration like this:

{
  "bundles" : {
    "bundleA" : {
      "ComponentA" : {
        "templatePropA": "template1",
        "templatePropB": "template1"
      }
    }
  }
}

The app configuration based on this app template is quite identical, but contains one additional property appProp:

{
  "bundles" : {
    "bundleA": {
      "ComponentA": {
        "templatePropA": "template1",
        "templatePropB" : "template1",
        "appProp": "fromApp"
      }
    }
  }
}

Now the value for the property templatePropA is changed, the property templatePropB is deleted and a new property templatePropC is added:

{
  "bundles" : {
    "bundleA": {
      "ComponentA": {
        "templatePropA": "template2",
        "templatePropC": "template2"
      }
    }
  }
}

After synchronization the new app configuration looks like this:

{
  "bundles" : {
    "bundleA" : {
      "ComponentA" : {
        "templatePropA": "template2",
        "appProp": "fromApp",
        "templatePropC": "template2"
      }
    }
  }
}

The templatePropA property has been overwritten with the value from the app template. The property templatePropB has been deleted from the template and thus, also from the app.The new property templatePropC from the app template has been added to the app. The property appProp was only present in the app and is retained.

Advanced adjustment for the synchronization

By setting synchronization flags in the app.json file of the app template you can modify the default behavior for adding, replacing, or deleting configuration properties during synchronization. For example, if you want to prevent the properties of a component in an app from being replaced by a property in the app template you can add the statement "ComponentA$merge": "MERGE_APP_WINS" to that component. Here, ComponentA is the name of the component.

In the following section from the app.json of an app template the statement "ComponentA$merge": "MERGE_APP_WINS" is set next to the component configuration of ComponentA:

{
  "bundles": {
    "bundleA" : {
      "ComponentA$merge": "MERGE_APP_WINS",
      "ComponentA" : {
        "templatePropA": "template1"
      }
    }
  }
}

By default, when the value of the property templatePropA in the app template is changed this property gets overwritten with that value in all apps.By using the statement "ComponentA$merge": "MERGE_APP_WINS" you can specify to always retain the values configured in the app, no matter how the values of that property in the app template are changed. Only properties that have been newly added to the app template and are not yet present in the app are added to the app.

Additional possible values for the property ComponentA$merge are:

MERGE_TEMPLATE_WINS: This is the default setting. Always the settings from the app template are written to the app. Additional properties in the app that are not present in the app template are preserved.
APP_REPLACES: Changes to the app template are ignored. Not any configuration changes for the component are taken from the app template into the app.
TEMPLATE_REPLACES: All app-specific properties for the component are removed and are replaced with the properties from the app template.

Limitations

It is only possible to set synchronization flags for single components, not for single properties. So, for example, it is not possible to define to only retain one certain property in an app after synchronization whereas all other properties are replaced with the properties from the template.

Summary

Here is a summary of how the synchronization works on files and on properties in the app.json files.

Changes in File Structure in the App Template

added files are added to the app
deleted files are removed from the app, independent of potential changes in the app’s file version
retained files are added to the app overriding potential changes to the same file in the app – except for the app.json file

Changes to the app.json File

The following rules apply when the app.json files of a template and an app are merged:

Any component property changed in the new template (by being added, modified, or deleted) is applied to the app, even if the changed property already exists in the app.
All component properties in the app that are not subject to a change remain untouched. Example for a merge using the default merge behavior MERGE_TEMPLATE_WINS:

Before synchronization After synchronization

	Before synchronization	After synchronization
App	`{ "bundles" : { "bundleA": { "componentA": { "templatePropA" : "template1", "templatePropB" : "template1", "appProp" : "fromApp" } } } }`	`{ "bundles" : { "bundleA" : { "componentA" : { "templatePropA" : "template2", "appProp" : "fromApp", "templatePropC" : "template2" } } } }`
App Template	`{ "bundles" : { "bundleA" : { "componentA" : { "templatePropA" : "template1", "templatePropB" : "template1" } } } }`	`{ "bundles" : { "bundleA" : { "componentA" : { "templatePropA" : "template2", "templatePropC" : "template2" } } } }` templatePropA: (value) changed templatePropB: removed templatePropC: added

App

{
  "bundles" : {
    "bundleA": {
      "componentA": {
        "templatePropA" : "template1",
        "templatePropB" : "template1",
        "appProp" : "fromApp"
      }
    }
  }
}

{
  "bundles" : {
    "bundleA" : {
      "componentA" : {
        "templatePropA" : "template2",
        "appProp" : "fromApp",
        "templatePropC" : "template2"
      }
    }
  }
}

App Template

{
  "bundles" : {
    "bundleA" : {
      "componentA" : {
        "templatePropA" : "template1",
        "templatePropB" : "template1"
      }
    }
  }
}

{
  "bundles" : {
    "bundleA" : {
      "componentA" : {
        "templatePropA" : "template2",
        "templatePropC" : "template2"
      }
    }
  }
}

templatePropA: (value) changed
templatePropB: removed
templatePropC: added

List of merge options

Flag Value Effect

Flag Value	Effect
`MERGE_TEMPLATE_WINS`	Template changes are preferred (equivalent to default behavior) All template changes are applied. Only additional app properties remain.
`MERGE_APP_WINS`	App properties are preferred All app properties remain untouched. Only template changes that add properties are applied.
`APP_REPLACES`	Template changes are completely ignored All app properties remain untouched. No template changes are applied.
`TEMPLATE_REPLACES`	App properties are replaced by template properties All app properties are removed. All properties of the new template are added.

MERGE_TEMPLATE_WINS

Template changes are preferred (equivalent to default behavior)

All template changes are applied.
Only additional app properties remain.

MERGE_APP_WINS

App properties are preferred

All app properties remain untouched.
Only template changes that add properties are applied.

APP_REPLACES

Template changes are completely ignored

All app properties remain untouched.
No template changes are applied.

TEMPLATE_REPLACES

App properties are replaced by template properties

All app properties are removed.
All properties of the new template are added.