Importing data
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
).
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.
@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.
|
WebCmsPage
with a component and menu itemassets:
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 defineWebCmsAsset
import data -
types
: specifies the children defineWebCmsTypeSpecifier
import data -
menus
: specifies the children defineWebCmsMenu
import data -
redirects
: specifies the children defineWebCmsRemoteEndpoint
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.
|
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. |
|
Can be used on any data block representing a |
|
Can be used on any data block representing a |
|
Can be used on any data block representing a |
|
Can be used on any data block representing a |
|
Can be used on any data block representing a |
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.
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.