Bootstrap Resource Converter
Introduction
As of version 12.0, Bloomreach Experience Manager uses the YAML format to define what repository data should be bootstrapped, and how. If you have a pre-version 12 compatible project or plugin, the esv2yaml tool helps you convert your bootstrap resources from the old to the new format. The new format and the related concepts are described in detail in the Configuration Management section.
Get esv2yaml
Download hippo-configuration-management-migration-<version>-standalone.jar from the Hippo Maven repository. Make sure to download the latest version. Because further documentation will refer to the JAR as esv2yaml.jar, we recommend you save the tool under that name.
You can also download the latest development version using wget or curl:
wget "https://maven.onehippo.com/service/local/artifact/maven/content?r=maven2&g=org.onehippo.cms&a=hippo-configuration-management-migration&c=standalone&v=LATEST" -O esv2yaml.jar
curl 'https://maven.onehippo.com/service/local/artifact/maven/content?r=maven2&g=org.onehippo.cms&a=hippo-configuration-management-migration&c=standalone&v=LATEST' > esv2yaml.jar
Run esv2yaml
esv2yaml operates on a single Maven module, which contains a hippoecm-extension.xml file, in combination with any number of (nested) XML, CND and JSON (translations) bootstrap resources. It converts the input into a set of YAML Sources, which are divided into the config part (in the hcm-config folder) and the content part (in the hcm-content folder).
To run the tool, execute the following command:
java -jar esv2yaml.jar <options>
Running the command without options prints a short overview of the available options. Here are more details on these options:
Source directory
Use the option -s or --src to specify the root directory of your input bootstrap resources. Typically, this is the directory holding the hippoecm-extension.xml file, located at src/main/resources/ of the to-be-converted Maven module. You must specify an absolute path.
Target directory
Use the option -t or --target to specify the root directory of your output bootstrap resources. This is the directory where the hcm-config and hcm-content folders will be created. If they already exist, esv2yaml will first remove them. You must specify an absolute path. For in-place conversion, the target directory must be set identical to the source directory.
Conversion mode
Use the option -m or --mode to specify the conversion mode. For all modes, esv2yaml converts only XML files referenced by the module's hippoecm-extension.xml file. XML files not referenced will not be converted and remain untouched. esv2yaml supports 3 modes:
- copy In copy mode, esv2yaml creates the output files and folders, while leaving the input files untouched.
- move In move mode, esv2yaml creates the output files and folders, and removes the processed input files.
- git In git mode, esv2yaml converts the input to output in-place, while preserving their git history. When using this mode, you must specify the same path for source and target. After running esv2yaml using git mode, in order to complete git migration, the following two commands should be run:
- 'git commit' (handle movement/renaming of resource files by committing the already staged files).
- 'git add . && git commit' (commit actual changes)
Expert options
Custom location of hippoecm-extension.xml
In the odd case where your hippoecm-extension.xml file is not located in the source directory or has a different name, use the -i or --init option to specify the absolute path to it.
Content root paths
By default, most bootstrap resources are converted to config definitions. However, all nodes below (but excluding) the following nodes are considered content:
/content /content/documents /content/gallery /content/assets /content/attic /content/urlrewriter
Use the -content or --content option if you want additional node paths to be converted into content definitions. For example, to specify that nodes below /a and /b/c should be converted to content definitions, specify the content option as a comma-separated value, like this:
-content /a,/b/c
Custom residual category injection
By default, esv2yaml injects residual-child-node-category meta-data at certain locations into the converted YAML files. Use the -ir or --custominjectresidualcategory option to override the built-in default values. Specify a comma-separated list of path-category mappings. By default, esv2yaml injects the following residual child node categories at the following paths:
**/hst:workspace/**[hst:containercomponent]: content **/hst:workspace/**[hst:sitemenu]: content **/hst:workspace/hst:abstractpages: content **/hst:workspace/hst:channel: content **/hst:workspace/hst:components: content **/hst:workspace/hst:pages: content **/hst:workspace/hst:sitemap: content **/hst:workspace/hst:templates: content /hst:hst/hst:hosts: content /hst:hst/hst:hosts/**[hst:virtualhostgroup]: content /hst:hst/hst:hosts/**[hst:virtualhost]: content /hst:hst/hst:hosts/**[hst:mount]: content
These defaults match with the default settings of auto-export, and they ensure that the parts of the HST configuration data which are created run-time are converted to (and henceforth considered) content rather than config.
The injection of residual-child-node-category meta-data has two effect:
- The converted YAML files get this meta-data injected
- If the injected residual-child-node-category is content, esv2yaml produces content definitions for child nodes (and their sub-trees) of the specified paths
Custom residual category overriding
The -or or --customoverrideresidualcategory option allows overriding the 2nd effect of the injection of residual-child-node-category meta-data (see above). This is typically used to ensure that child nodes of a node which has a residual-child-node-category of content injected is converted into config definitions rather than content definitions. By default, esv2yaml overrides the following paths:
/hst:hst/hst:hosts: config /hst:hst/hst:hosts/**: config
This default ensures that hst:hosts configuration is converted to config YAML definitions, even though a residual-child-node-category of content gets injected into the YAML sources. When using custom values for this option, specify them as a comma-separated list of path-category mappings.
Known limitations
esv2yaml converts XML more or less as-is into YAML, operating with a scope of a single Maven module only. The pre-12 XML loading mechanism was somewhat lenient with regards to multi-value properties being set using a single value, or boolean properties being set using a string. The YAML model is much more strict, which may lead to errors when the YAML definitions are merged into the Configuration Model or applied to the repository. Therefore, thorough testing of the output produced by esv2yaml is required.
Running esv2yaml may fail initially, indicating that there are errors in your XML bootstrap sources (which were silently ignored by previous versions of the CMS). Fix them and try again.