Importing data

WebCmsModule provides infrastructure for easy importing of data using YAML files. The data import services are also the ones used for the default data of WebCmsModule, see the appendix for the YAML version of the default types and assets.

1. WebCmsDataImportService

The WebCmsDataImportService allows importing data from Map structures. The Map based data could for example be sourced from YAML, JSON or XML files.

When converting to the domain model, the WebCmsDataImportService will dispatch to WebCmsDataImporter beans for handling data items. The WebCmsDataConversionService is used to convert from raw values (for example String) to the actual data type (for example WebCmsPage).

Example importing from YAML file data
Yaml yaml = new Yaml();
Map<String, Object> data = (Map<String, Object>) yaml.load( inputStream );
dataImportService.importData( data );

2. Using an installer

The AbstractWebCmsDataInstaller is a base class for an installer that imports one or more YAML files using the WebCmsDataImportService. The files specified will be imported in registration order.

Example YAML data installer
@Installer(description = "Install some test data", phase = InstallerPhase.AfterContextBootstrap, version = 1)
@RequiredArgsConstructor
public class TestDataInstaller extends AbstractWebCmsDataInstaller
{
    @Override
        protected void registerResources( List<String> locations ) {
                locations.add( "classpath:installers/test-data/my-types.yml" );
                locations.add( "classpath:installers/test-data/my-assets.yml" );
        }
}

3. YAML structure

In this chapter we focus on the key structure for importing data and use YAML examples. The WebCmsDataImportService acts on Map/Collection data structures however, so JSON, XML or native structures could be used as well.
Example YAML data: updating a WebCmsPage with a component and menu item
assets:
  wcm:action: update
  page:
    - objectId: "wcm:asset:page:test-render-components"
      published: true
      wcm:components:
        page-title:
          componentType: plain-text
          title: Page title
          content: Demo titel
      wcm:menu-items:
        - title: test-1
          group: true
          path: /my/generic/path
          menu: sidenav

3.1. Root key values

By default, WebCmsModule supports 4 top-level keywords:

  • assets: specifies the children define WebCmsAsset import data

  • types: specifies the children define WebCmsTypeSpecifier import data

  • menus: specifies the children define WebCmsMenu import data

  • redirects : specifies the children define WebCmsRemoteEndpoint import data

For assets and types the child key (eg. page) determines the sub-type that is being imported (eg. WebCmsPage).

3.2. Data importers

WebCmsModule provides importers for most default assets like WebCmsPage, WebCmsMenu etc.

See the relevant chapters for examples and more details:

3.3. Generic importers

WebCmsModule has some generic importers that can be used in multiple situations. These importers act on a specific prefixed keyword.

Table 1. Generic importer keywords

wcm:action

Can be used on pretty much any data block and defines the action that should be performed with that data. See the chapter on import actions for more details.

wcm:components

Can be used on any data block representing a WebCmsObject. Specifies that the child data represents components owned by the parent WebCmsObject.

wcm:assets

Can be used on any data block representing a WebCmsObject. Specifies that the child data represents links between the parent WebCmsObject and a WebCmsAsset. These links are mapped using WebCmsAssetLink and WebCmsAssetLinkRepository

wcm:types

Can be used on any data block representing a WebCmsObject. Specifies that the child data represents links between the parent WebCmsObject and a WebCmsTypeSpecifier. These links are mapped using the WebCmsTypeSpecifierLink and WebCmsTypeSpecifierLinkRepository.

wcm:menu-items

Can be used on any data block representing a WebCmsAsset. Will create menu items for that asset provided that there is a WebCmsAssetEndpoint available as well. See page importing for examples.

wcm:urls

Can be used on any data block representing a WebCmsAsset. Will create urls for the asset provided that there is a WebCmsAssetEndpoint available.

3.4. Import action

The optional wcm:action represents the import action that should be performed with a data block (insert, update etc). If the parent data contains a wcm:action and the child doesn’t, the child action is the same as the parent one.

If no wcm:action is specified, the value is create-update which means the data will be created if it does not yet exist, or updated if it does.

Table 2. Possible import action values

create

Only insert the data if it does not yet exist.

update

Update any existing data, but do nothing if it does not exist.

create-update

Insert the data if it does not yet exist, update it otherwise. This is the default value if no action is specified.

delete

Delete the data if it exists.

replace

If the item exists, overwrite it entirely with the new data. This replaces the existing object but keeps the same identity (primary key).

3.5. Creating a custom importer

To create a custom object importer, simply implement the WebCmsDataImporter interface and provide your instances as beans.

The AbstractWebCmsDataImporter is a generic base class that provides useful hooks for implementing import logic, as well as logging and exception handling in line with the default importers.

If you want to import a custom WebCmsAsset, the AbstractWebCmsAssetImporter is a more specialized base class.

3.5.1. Importing custom properties

You can easily define custom properties to import as long as you namespace them (eg. mynamespace:). These properties will not be handled by the default value to object converters.

NOTE The wcm: namespace is for WebCmsModule itself, example properties are wcm:components and wcm:menu-items.

Provide your own property importer by implementing WebCmsPropertyDataImporter and creating your implementation as a bean. The AbstractWebCmsPropertyDataImporter is a useful base class for common implementations.

3.6. Debugging imports

Receiving debug information on data imports can be done by setting the log levels for WebCmsDataImporter and WebCmsPropertyDataImporter implementations to TRACE.