Configuration Endpoint Merging

Endpoint Configuration Merging uses the EM Agent to combine multiple AEMP configuration files, saved on one endpoint, into a single configuration. Nodes, reusable conditions and message libraries from each configuration are added to the merged configuration.

The merge is done by adding the individual configurations to a directory on the endpoint and specifying, in a manifest file, the configurations which are to be merged. The EM Agent monitors the merge directory and automatically merges configurations when a manifest file is added to the directory.

Endpoint Configuration Merging allows different areas of a business to work independently on a particular area of a configuration which can then be added to create a single configuration. Where small changes to large configurations are required, a snippet of the area that has changed can be created. The snippet can then be merged on endpoints removing the need to push out large configurations.

In this section:

Components in a Merge

Configuration merging relies on the following components.

Base Configuration

Every merge must have a base configuration - this is the first configuration in the merge onto which the other configurations are added. A merged configuration takes the global attributes such as Custom Settings, Auditing options and any Personalization settings, from the base configuration.

It is therefore essential that the settings which are not merged are defined in the base.

By default, the base configuration is set as the AEMP file which is created when a live configuration is saved on an endpoint:

%ProgramData%\AppSense\Environment Manager\Configuration.aemp

The base configuration and all component configurations in a merge must be version 10.0 or later of Environment Manager. Upgrade any older version configurations before merging.

Component Configurations

A merged configuration is made up of a base configuration and one or more component configurations. Component configurations are AEMP files which are added to the base configuration during a merge. To be part of a merge, component configurations must be stored in the MergeConfigs directory.

Nodes, pre-triggers, Run-As and User Messages from components are included in a merge. Other settings such as auditing options are taken only from the base configuration. The base configuration and all component configurations in a merge must be version 10.0 or later of Environment Manager. Upgrade any older version configurations before merging.

MergeConfigs Directory

This directory is where component configurations for merging are stored and where a merge is triggered when a valid manifest is detected.

When you start the EMCoreService on an endpoint, the MergeConfigs directory is created:

%ProgramData%\AppSense\Environment Manager\MergeConfigs

This directory is secured so only administrators can write to it. This ensures that end users cannot affect the merge configurations.

Manifest

The manifest is an XML file that includes details of the configurations to be merged and dictates which configuration is set as the base. The merge is initiated when the agent detects a manifest in the MergeConfigs directory.

Manifests are created using the ManifestGen command line tool.

Below is an example merge_manifest.xml file.

<MergeManifest UseSystemBase="true" WaitForConfigs="true">

<MergeFiles>

<FileEntry Name="config2.aemp" Checksum="563621a479c06d6d357b327283320288"/>

<FileEntry Name="config4.aemp" Checksum="4bc481043e6991253de15ec6993ee43f"/>

</MergeFiles>

</MergeManifest>

Manifest Attribute and Tags

Attribute/Tag Description
MergeManifest The root node of the configuration.
MergeFiles The container tag for the list of AEMP files which are to be included in the merge.
FileEntry Name Identifies a configuration to be included in the merge. The file must be present in the MergeConfigs directory to be included in a merge.

UseSystemBase

(Optional)

 Can be set to "true" or "false" and instructs whether to either include or exclude the default Configuration.aemp in the merge. This is the live Configuration.aemp file found in %ProgramData%\AppSense\Environment Manager. If set to true, the base configuration must already be present on endpoints when the manifest is deployed otherwise the merge will fail. If set to false the first configuration in the MergeFiles list is used as the base configuration unless otherwise defined by the BaseConfig attribute.

WaitForConfigs

(Optional)

 Determines the behavior when a manifest .xml is detected in the MergeConfigs directory and not all named configurations are present. Can be set to:
  • True - The merge will wait indefinitely until all configurations referenced in the manifest are present and then complete the merge.
  • False - The merge will fail if a manifest is detected in the MergeConfigs directory which references a configuration which is not present.
If you are using an installer, such as an MSI, to push out configurations and a manifest to endpoints, it is recommended that you set this to "true" as you cannot guarantee in what order the configurations and manifest will be added. This does not apply if using the SystemBase Configuration.aemp file. If the manifest merge is triggered and the Configuration.aemp is not present, the merge will fail - it will not wait for the base.

Checksum

(Optional)

 An MD5 checksum unique to an AEMP file. If included the manifest, the AEMP file in the MergeConfigs folder must have the same checksum to be included in the merge. Base configurations are not referenced by a checksum.

ManifestGen Tool

The ManifestGen is a command line tool which creates the XML manifest file used to define and trigger a configuration merge. The XML file contains details of the AEMP files to be merged and can dictate whether the default Configuration.aemp or a component configuration is used as the base in the merge.

If a merge_manifest.xml already exists in the output directory, the tool fails and a new manifest is not created - the current one is not overwritten.

To make using the tool easier, add the location to the Path environment variable at Advanced System Properties > Environment Variables > Path:
%PROGRAMFILES%\AppSense\Environment Manager\Console

Create a Manifest

  1. Save the configurations you want to be merged in the MergeConfigs directory:
  2. %ProgramData%\AppSense\Environment Manager\MergeConfigs
  3. Open the Command Line Interface.
  4. Enter cd %programdata%\appsense\environment manager to change the directory.
  5. Enter manifestgen mergeconfigs\*.aemp.

If you run manifestgen in the MergeConfigs folder, the agent will pick up the manifest as soon as it is created and immediately start the merge.

If successful, a merge_manifest.xml file is created in: %ProgramData%\AppSense\Environment Manager

The manifest can now be used to trigger the merge and create a configuration.

Additional Commands

Arguments can be used in the ManifestGen tool to alter the manifest and affect the merge. You can specify a different base configuration, output file and create a manifest without checksum values for the configurations.

Suffix Description and Usage
-o Output folder- Specify where the manifest.xml file is created, for example, manifestgen mergeconfigs\*.aemp -o c:\configs creates a manifest in the Configs folder on the C drive.
-b Base configuration - Identify the base configuration and exclude the default base configuration. For example, manifestgen mergeconfigs\*.aemp -b config1.aemp creates a manifest that will create a merged configuration with Config1.aemp set as the base configuration.
-nc No checksum entries - By default, each configuration listed in the manifest has an MD5 checksum which allows unique identification of a configuration. If the checksum in the manifest does not match that of the configuration the merge will fail or wait for a configuration with the correct checksum. Using the -nc suffix with the ManifestGen tool will not list checksums in the manifest and means that merges will succeed if the configuration file names are correct, regardless of the checksum value. For example: manifestgen mergeconfigs\*.aemp -nc
-nw The default behavior when a manifest is added to the MergeConfigs directory is to wait indefinitely until all configurations in the manifest are present and then perform the merge. Using the -nw suffix, a merge will fail if the configurations listed are not present when the manifest is added to the MergeConfigs directory. For example: manifestgen mergeconfigs\*.aemp -nw If the manifest lists five configurations and only four are present when the manifest is added to the MergeConfigs directory, the merge will fail. If you are using an installer, such as an MSI, to push out configurations and a manifest to endpoints, it is recommended that you do not use this suffix as you cannot guarantee in what order the configurations and manifest will be added.

Edit a Manifest

Although manifests can be edited and created in a text editor, it is recommended that you use the ManifestGen tool as it ensures the merge_manifest.xml file is in the correct format. If, for example, you have an "&" in a file name, the ManifestGen tool will escape this to make sure it is a valid XML file.

Once created, a manifest file can be edited to change the attributes such as the base configuration and the order in which the merge should take place.

For example, the command:

manifestgen mergeconfigs\*.aemp -b mergeconfigs\config3.aemp -nc

creates a manifest in which the default base configuration is not included and config3.aemp is set as the base. The WaitForConfigs attribute is set to the default of "true" and checksums are not included.

<MergeManifest UseSystemBase="false" WaitForConfigs="true">

<MergeFiles>

<FileEntry Name="config3.aemp" BaseConfig="true"/>

<FileEntry Name="config1.aemp"/>

</MergeFiles>

</MergeManifest>

To edit the manifest, open the manifest in a text editor, make the required changes and save the file.

In this example, UseSystemBase is set to "true" and the BaseConfig command has been removed from Config3.aemp. The order of the merge has also been changed.

<MergeManifest UseSystemBase="true" WaitForConfigs="true">

<MergeFiles>

<FileEntry Name="config1.aemp"/>

<FileEntry Name="config3.aemp"/>

</MergeFiles>

</MergeManifest>

When merged, the default base Configuration.aemp file is included in the merge as the base configuration and the order in which the component configurations are merged onto the base is reversed. Note that the configuration set as the base, includes the global configuration settings such as the Custom Settings that you want including in the merge. Therefore, care should be taken when selecting a different configuration as the base.

Setting BaseConfig="true" for a configuration and UseSystemBase="true" in the same manifest will cause a conflict and the merge will fail.

BatchConfig Tool

Only AEMP files which are at the latest version can be included in a merge. The BatchConfig tool converts old AEMP files and XML snippets to AEMP files of the correct version.

Multiple files can be converted at the same time, producing one output file per input.

If one or more configurations from the source already exist in the output directory, the tool fails and none of the configurations are converted.

To make using the tool easier, add the location to the Path environment variable at Advanced System Properties > Environment Variables > Path:
%PROGRAMFILES%\AppSense\Environment Manager\Console

Batch Convert Configuration Files

  1. Save or copy the AEMP and XML files you want to convert to a single folder.
  2. Open the Command Line Interface.

  3. Enter BatchConfigTool followed by details of the source and destination folders in the following format:

    BatchConfigTool <source directory\file type> -o <output directory>

Batch Convert Examples

BatchConfigTool C:\Configs\Source\*.xml -o C:\Configs\Output

This example converts XML snippets found in the source directory to current version AEMP files saved in the output directory. The same format can be used to update old AEMP files to the current version:

BatchConfigTool C:\Configs\Source\*.aemp -o C:\Configs\Output

You can also convert both file types simultaneously:

BatchConfigTool C:\Configs\Source\*.aemp C:\Configs\Source\*.xml -o C:\Configs\Output

In the example below, the Source directory contained an 8.3 AEMP file and two XML snippets. Following conversion, the output directory contains three current version AEMP files.

…ð

The BatchConfig tool installs with the Environment Manager Console. However, it can be installed independently using the EnvironmentManagerPolicyTools 32 and 64 bit installers which are included in the User Workspace Manager media.

Auditing Events - Configuration Endpoint Merging

New auditing events for Configuration Endpoint Merging have been added to Environment Manager. When viewed in Windows Event Viewer (select Windows Log > Applications), the events provide further details such as what has caused a merge failure.

Related Topics

Merging Configurations

Live Configuration Rules