[opencms-dev] Bulk insert content

[Michael Emmerich]

Hello Atle,

first of all — *inserting data directly into the OpenCms database is 
strongly discouraged*. Doing so can easily corrupt your system.

The correct and safe way to migrate or import data is to *create an 
importer* that uses the *OpenCms API* to generate content based on the 
data from your existing system. Fortunately, this is not as complicated 
as it sounds.


      Step 1: Export Data from Your Current System

Before you can import anything into OpenCms, determine how you can 
*export* your articles from your current system, and in what *format* 
(e.g., XML, JSON, CSV).
Each article should ideally be exported as a separate file — for 
example, one XML file per article — or retrieved directly via an 
interface (API).


      Step 2: Import Process Overview

For each article, your import process will roughly follow these steps:

 1.

    *Extract* the data from the exported file.

 2.

    *Create* a new OpenCms resource of the desired type.

 3.

    *Populate* the resource with the extracted data.


        1) Extract the Data

This step depends heavily on the format of your export.
Let’s assume you’ve parsed the export into a |contentData| object, for 
example:

contentData.get("title");
contentData.get("text");
contentData.get("teaser");

This could be a simple |HashMap<String, String>| or a dedicated Java 
object with getters like |getTitle()|, |getText()|, etc.


        2) Create or Update the Resource

String filename = [some logic to define the name of the new resource];

if (!cms.existsResource(filename)) {
     // Create new resource
     CmsResource res = cms.createResource(
         filename,
OpenCms.getResourceManager().getResourceType("[RESOURCETYPE]")
     );
     CmsFile file = cms.readFile(res);
     fillContent(cms, file, contentData);
} else {
     // Update existing resource
     CmsFile file = cms.readFile(filename);
     cms.lockResource(file);
     fillContent(cms, file, contentData);
}

*Explanation:*

  *

    |cms| → The current |CmsObject|

  *

    |[RESOURCETYPE]| → The name of the resource type you want to create

  *

    |fillContent()| → A helper method to insert the actual data (see below)

After this step, you have either a new empty resource or an existing one 
ready to be updated.


        3) Fill the Content

Here’s an example |fillContent()| method that writes your data into all 
available locales:

CmsXmlContent content = CmsXmlContentFactory.unmarshal(cms, file);
List<Locale> locales = OpenCms.getLocaleManager().getAvailableLocales();

for (Locale locale : locales) {
     if (!content.hasLocale(locale)) {
         content.addLocale(cms, locale);
     }

     setValue(cms, content, XPATH_TITLE, contentData.get("title"), locale);
     setValue(cms, content, XPATH_TEXT, contentData.get("text"), locale);
     setValue(cms, content, XPATH_TEASER, contentData.get("teaser"), 
locale);
}

// Marshal XML back into file and save
file.setContents(content.marshal());
cms.writeFile(file);

*Notes:*

  *

    |XPATH_TITLE|, |XPATH_TEXT|, and |XPATH_TEASER| refer to the XML
    schema elements defined in your content type.
    For example:

<xsd:element name="Title" type="OpenCmsString"/>
<xsd:element name="Text" type="OpenCmsString"/>
<xsd:element name="Teaser" type="OpenCmsString"/>

Corresponding XPaths would be |"Title"|, |"Text"|, and |"Teaser"|.


        4) Set Value Helper Method

private void setValue(CmsObject cms, CmsXmlContent content, String 
xpath, String value, Locale locale) {
     int index = 0;
     if (value == null) {
         return;
     }
     if (!content.hasValue(xpath, locale, index)) {
         content.addValue(cms, xpath, locale, index);
     }
     content.getValue(xpath, locale, index).setStringValue(cms, value);
}

This method ensures the XML element exists and safely inserts the 
provided value.


      Summary

  *

    *Never* write directly into the OpenCms database.

  *

    *Always* use the OpenCms API to create and populate resources.

  *

    Prepare your data export first (XML/JSON/CSV).

  *

    Use a simple Java importer to create or update content.

This approach is reliable, maintainable, and ensures that your data 
stays consistent with OpenCms’s internal structure.


Kind regards,

Michael


Am 16.10.25 um 11:34 schrieb Atle Enersen via opencms-dev:
>
> Hello.
>
> We have some hundred (at least) articles in our old system that we 
> wold like to insert into OpenCms automagically. We are not gonna take 
> all, but that’s not OpenCms’ problem.
>
> We have a working structure on the old site, so filtering content is 
> manageable. Old articles will be marked as ... old.
>
> Is there any documentation on this? Does som kind of database scheme 
> exist for us external people? Are there any functions for this 
> internally in OpenCms? I am aware that doing hack son the database 
> would leave us «alone», no support.
>
> Thanks in advance :-)
>
> Vennlig hilsen, Atle Enersen
>
> -- 
>
> Tel.: +47 48 06 31 71
>
>
> _______________________________________________
> This mail is sent to you from the opencms-dev mailing list
> To change your list options, or to unsubscribe from the list, please visit
> https://lists.opencms.org/mailman/listinfo/opencms-dev
>
>
>
-- 
Michael Emmerich
  
-------------------

Alkacon Software GmbH & Co. KG - The OpenCms Experts

http://www.alkacon.com
http://www.opencms.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.opencms.org/pipermail/opencms-dev/attachments/20251017/24592907/attachment.htm>