Environment Manager
This page refers to an older version of the product.
View the current version of the User Help.
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
- ManifestGen Tool
- BatchConfig Tool
- Auditing Events - Configuration Endpoint Merging
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. |
|
(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. |
|
(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:
|
|
(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
- Save the configurations you want to be merged in the MergeConfigs directory:
- %ProgramData%\AppSense\Environment Manager\MergeConfigs
- Open the Command Line Interface.
- Enter
cd %programdata%\appsense\environment managerto change the directory. - 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
- Save or copy the AEMP and XML files you want to convert to a single folder.
- Open the Command Line Interface.
-
Enter
BatchConfigToolfollowed 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.