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.

WebCmsModule - Importing data