How to Use Pimcore DataHub Importer: A Practical Guide for Non-Developers

This guide is for everyone who wants to use the Pimcore DataHub to import data. It is based on real scenarios, not just explaining the functions, but helping you understand when and how to use certain features. It’s written for non‑technical users who work with data every day and face different import situations.

After reading this article, you’ll be able to import data on your own, without needing a developer, across several common situations. You’ll also learn how to combine different steps to achieve the end result: successfully imported data and assets.

What is Pimcore DataHub

The Pimcore DataHub is a central data distribution layer. It allows businesses to share, synchronize, and expose their Pimcore data to other systems in a controlled and flexible way. For a non-developer, the DataHub is a vital tool because it gives you direct control over how business data is shared. It allows you to manage the flow of data in and out of Pimcore with minimal developer involvement.

In this article, we’ll look at how this works by focusing on the Data Importer.

The Pimcore Data Objects Importer is a tool that automatically brings data into Pimcore from external sources, like Excel files, CSVs, ERP systems, or supplier feeds. Instead of creating products or other objects manually, the importer maps incoming data to fields in Pimcore and then creates or updates the objects for you. Its main purpose is to keep your data in Pimcore accurate, consistent, and in sync with other systems.

When to Use Pimcore DataHub: Common Business Scenarios

There are probably hundreds of different scenarios for using the DataHub Importer, but some of the most common ones include:

Initial Product Data Imports

If you have an ERP system where products are first created, if you get a product list from a supplier as an Excel file, or if you’re just starting to use Pimcore as your main source of truth and don’t have all your information stored in a PIM yet, this scenario will help you get there. Instead of creating every product manually, one by one (which could take hours or even days depending on how many products you need), you can use the DataHub Importer to bulk import them all at once.

Mass Updates of Existing Product Data

Did your supplier send you updated packaging information, and now you need to update thousands of products in bulk? Maybe you don’t want to use grid view because there’s too much searching involved. Does that sound familiar? If so, this is exactly where the DataHub Import comes in; it will help you do it quickly.

Reorganizing Product Hierarchies

Have you decided now is the right time to create product variations? You could do it manually, sure, but it’s time-consuming. Instead, use the DataHub Import to import all variations as a flat list, and then run a separate import to reorganize them as variations of other products.

Assigning Assets at Scale

This can feel overwhelming, especially when you’re working with thousands of assets, some of which might be localized. Doing this kind of work manually is nearly impossible. It would cost more to hire several people to do it than it would to pay a developer. But why pay at all when you can do it yourself for free?

Prerequisites and Responsibilities

To start working with DataHub, it must first be installed on your Pimcore instance, which requires a developer's help. But once it’s set up, using the DataHub Importer is all yours.

The DataHub Importer has some limitations with certain field types. For example, it doesn’t support imports into field-collections or blocks, which are commonly used. On top of that, importing into the classification store attributes can be quite challenging, especially when dealing with attributes shared across multiple groups. It’s not impossible, but it does take some extra time and organization.

Step-by-Step: Configuring a Data Object Importer for Bulk Import

Bulk import is used for situations where you need to bring in tens, hundreds, or even thousands of objects, such as Products, Categories, or Customers, in a short time, without having to add them manually one by one. Doing it manually could take hours or even days. Not to mention, adding objects individually is error-prone; it’s easy to miss something when your focus has to be perfect 100% of the time.

Step 1 - Create a new DataHub Data Import configuration

Access DataHub module and select option to create a new Data object importer.

Define a name and confirm.

Set it as active.

Step 2 - Choose upload format

Select the file format (I will use XLSX in this example) and choose which sheet from the workbook you want to use for the import. Usually, the first row contains column labels like "Product name" or "Category", so in that case, you should also select "Skip first Row." (If your file doesn’t have headers, leave this unchecked.)

Then, in the "Type" field, choose "Upload" since we are uploading the file into Pimcore. Finally, select the actual file you want to import.

For example, your Excel might look like the one below:

Step 3 - Import settings - Resolver

In the Import Settings tab, the first thing you need to do is click the blue icon in the Import Preview section. This copies preview data from your data source. This step is very important, and you can’t continue without doing it first.

After that, go to the Resolver subtab and select the object class you want to import. In my case, that’s Product, but it could be anything you’re importing in bulk, such as Category, Supplier, User, etc.

Under Element loading, keep "No loading" selected, since we are not updating existing products but creating new ones.

For Element creation, this setting indicates that we are creating new objects, so we need to choose a Location Strategy. There are a few options. If you choose "Static Path," you must select the exact folder (path) where the new objects will be created. Other options like “Find parent” and “Find or create Folder” are useful but will be covered in other scenarios. For now, we'll select the specific folder where new objects should be stored.

For Element Location Update, keep it as "No change," since we are not moving existing objects.

For Element Publishing, you have several options, and the best choice depends on your specific use case. You can read more about these options in our Data Importer blog.

In our example, we will select: No Change, Unpublish New.

Step 4 - Import Settings - Processing settings

In subtab “Processing Settings” under “Execution type” you can choose:

• Parallel - import of one object at a time, in a strict order
• Sequential - import of multiple records at the same time (concurrently)

What should be selected depends on the structure of the data from the source you are importing. For our case, you can use Parallel.

Step 5 - Import Settings - Mapping

In the Mappings subtab, we now need to set up the mapping. This tells the system which column from your Excel file corresponds to which attribute on the object in Pimcore after the import finishes. In the sections below, I’ll explain a few different examples of how to configure this mapping.

First, click Add, then define a Label (this is used only internally for easier management). Next, in the Source attribute, select the column from your file that you want to map.

First, we want to name the objects in Pimcore so they aren’t randomly assigned names during the import. To do this, select the attribute that will represent the object name (in our case, that’s "Child ID"). Then, in the Data Target section, choose Direct in the "Type" field, and in the "Field name" field, select SYSTEM Key.

Step 6. - Start Import

After all configurations and mappings are completed, go to the Execution tab, select “Once”, and click “Start”.

Note: If the “Start” button is disabled, click Save in the bottom-left corner and try again. Once the execution starts, a progress bar will appear showing how many items are being processed. When the import is finished, the progress bar will disappear.

Mapping Strategies Explained

Some of the examples of attribute mappings that occur in Step 5:

Input type mapping

Input field mapping is the simplest type of mapping. All you need to do is choose the column from your Excel sheet that holds the value in the Source attribute field (in our example, this is the "Identifier" column). In the Type field, select "Direct". Then, in the Field name field, locate the matching input-type attribute in Pimcore (in our case, that's the Identifier attribute).

Select field type mapping

The approach for select field mapping is similar to mapping an input field. The key thing to ensure is that the values in your Excel file match exactly the options defined in the select-type attribute. In our example, the column in Excel is named "Energy efficiency class of the light source according to EU regulation 2019/2015." This will be mapped to a select-type attribute in Pimcore with the exact same name.

Multi-selection field type

For a multiselection type, the mapping needs to use a transformation called "Explode." This separates the different values, for example, values in your file that are listed with a delimiter like ";" between them.

Note: Be careful when entering the delimiter in the transformer. Double-check that there is no space before the delimiter, or it will not work correctly.

In our case, the values in the Excel sheet look like this:

Localized field type mapping

If you need to map a localized field to a specific attribute, the process is straightforward. Simply choose the Source attribute, set the Type to "Direct", and select the Field name where you want to store the value. If the selected field is localized, Pimcore will automatically recognize this and present you with a list of all available languages to store the information in.

Quantity value inside the Classification store mapping

If you need to map a field that is inside a classification store and holds a quantity value, you’ll first need to set up a transformation. The process goes like this:

First, choose the Source attribute from your file. Then, in the Transformation Pipeline section, select Quantity value. This step is necessary because a quantity value in Pimcore is a specific data format; it’s not as simple as a standard input field. We use this transformation to convert the data into the correct format before importing.

After adding it, set Unit source to "Static Unit" and choose the unit you’re using (in our case, that’s mm).

Once the transformation is set up, you need to select the Pimcore attribute where this value will be stored. In the Type field, choose "Classification store". Then, in Field name, select the specific classification store that contains the attribute. (Sometimes there’s only one classification store in the system, but some projects have multiple.)

After the classification store is selected, locate the exact attribute by clicking the search button in the Data Key field. Keep in mind that the same attribute in a classification store can belong to multiple Groups (listed in the “Group” column). It’s very important to select the correct group where your attribute is actually stored.

The language field in our case can remain empty, as it is not localized.

Many to many relationship mapping

If a single Excel cell contains multiple values separated by a delimiter and these values need to be imported into a many-to-many relation field, the Explode function must be used in the Transformation Pipelines section. The Explode function separates the multiple values into individual entries.

The delimiter to be entered depends on the delimiter used in the Excel file (for example: ;, ., ,). In our case, comma (,) is used.

Additionally, the Load DataObject transformer must be configured. This transformer is used to find the corresponding object in Pimcore and connect it to the target attribute as a relation based on the defined mapping. In our case, existing Product objects are identified and added as relations based on the selected Attribute, with the reference set to Identifier.

In the Data Target section, the Many-to-Many Relation type is selected. The field where the product relations are stored is called “Similar Products”. Additional options allow configuring overwrite behavior when the target is not empty or the source is empty.

When overwrite mode is enabled, and the option to overwrite when the target is not empty is selected, it can be defined whether the existing relations should be fully overwritten or whether the new relations should be appended to the existing related objects.

Combination of two or more fields

If you need to combine two or more columns from an Excel sheet into a single piece of information, separated by a delimiter, you don’t need to create an extra column in Excel and prepare it manually. Instead, you can use a transformation called "Combine."

For example, when a product name needs to include details from multiple columns, such as combining Product name and ID into one value to serve as the object name in the tree (the SYSTEM KEY), here's what you do:

First, select all the Excel columns you want to use in the Source attributes field. Then, add the "Combine" transformation and define the separator (delimiter) in the "Glue" field. After that, in Data target, choose Type "Direct" and set the field name to "SYSTEM Key"; this will become the object name in the tree.

After import is finished, your objects in the tree will contain all information you selected (in our case Product name + delimiter “-” + ID

Updating Existing Objects in Bulk

While the first scenario dealt with an initial import, bringing new data objects into Pimcore, updating existing objects in bulk assumes the object (for example, a Product) is already in the system. Here, the goal is to update the data it contains or fill in fields that are currently empty.

Step 1 and Step 2 here are the same as in the "Import objects in bulk" section. The difference begins in Step 3, within the Import Settings > Resolver tab, where the element loading configuration must be selected.

In the Loading Strategy field, choose the loading type, which can be based on either Product ID or Product Attributes. In our case, we are using Attributes.

Next, in the Data Source Index field, select the attribute from your Excel sheet that acts as the unique identifier (in our example, that's "ID [0]"). Then, in the Attribute field, choose the product attribute in Pimcore that will be used to match and link the records between your Excel file and the system.

After Step 3, Step 4 is the same as described in the “Import Objects in Bulk” section. After completing Step 4, the mapping must be configured; several examples are provided in the “Mapping strategies” section.

Step 6 is the same as described in the “Import Objects in Bulk” section.

Updating Object Location and Hierarchy in Bulk

When you're just starting with Pimcore, or for other reasons, your object structure might be flat, meaning all objects (like products or categories) exist on the same level without any hierarchy. But now you might decide to organize your objects more clearly.

Perhaps you need to add product variants as children of another product that represents the main group, or you just want to rearrange your hierarchy to make products easier to find and manage. You could do this manually, but if you’re working with many products, it will take considerable time and effort. It’s also easy to make a mistake, you might think you moved something as a child, but it didn't quite take.

Instead, using the DataHub Importer lets you do this quickly. All you need is to prepare an Excel file that defines what is a parent and what is a child, then follow the steps explained below. Your time and effort will be saved.

Step 1 and Step 2 are the same as in the section "Import objects in bulk". The difference begins in Step 3, within the Import Settings > Resolver tab, where you need to set up the configuration.

Step 3.

In the Import Settings > Resolver tab, two separate configurations must be set up:

Element Loading: The Child ID column from your Excel sheet is used to find the corresponding product in Pimcore. The same ID value is matched against the Attribute name field, which acts as the product reference.

Element Location Update: The selected location strategy is "Find parent." The parent product is identified using the Identifier attribute in the Product class. This means the value in the Parent ID column of your Excel file must exactly match the Identifier value of the corresponding product already in Pimcore.

We have also configured a Fallback Path (in this case, /Products2). If no matching parent is found, those products will be stored in this folder.

Step 4. No need to Map attributes

There is no need to configure any mappings in the Mappings tab. It can be left empty, as the process only moves products from the parent level to the child level and does not import actual product data.

Step 5.

In the Execution tab, proceed with the process as described in the “Import Objects in Bulk” section

Importing and Assigning Assets to Products

Whether you have a new product line with multiple assets for each item, or your Pimcore wasn’t used as a DAM before, and now you need to import thousands of unrelated assets, the solution follows a two‑step process.

First, upload all assets to Pimcore in a dedicated folder, or, even better, separate them into different folders (for example, one for product images, another for videos, a third for documents, etc.). Then, in the second step, follow the guidelines below to assign those assets to the correct products.

Yes, you could do this manually, taking each asset and linking it to an individual product. But are you really willing to spend days, or even weeks, doing that?

Asset Assignment

This is how the Excel sheet used in Step 2 looks. Make sure when you add an asset path in the Excel file that it begins with a forward slash (“/”).

Step 1 and Step 2 are the same as in the "Import objects in bulk" section. The difference begins in Step 3, within the Import Settings > Resolver tab, where you need to configure the loading.

Step 3

In the Import Settings > Resolver tab, set up the element loading as follows:

• In the Loading strategy field, select Attribute, as products will be identified from the Excel sheet based on an attribute.
• For Attribute data source index, choose the column in the Excel sheet that contains the product identifier.
• In the Attribute name field, select Identifier from the Product class. This value must match the identifier provided in your Excel sheet.

Step 4. Is described in the header Import objects in bulk

Step 5. Mapping

In Import Settings → Mappings, you must map all Excel columns that you want to import to the corresponding Pimcore attributes where the data will be stored. Below are some of the scenarios that might happen when working with assets.

Single image mapping to one attribute

For example, if you have an attribute Main Image that stores a single image, you need to select the Excel column that contains the image reference. In our case, the source attribute from the Excel sheet is Column 1.

In the Transformation Pipeline section, add a transformation called Load Asset. This transformation allows the system to locate assets that were previously uploaded to Pimcore and stored in a specific folder. Since the Excel sheet contains the exact asset path (for example, /Test2/0.png), configure the transformation to load the asset by path. Alternatively, assets can also be loaded using their Pimcore asset ID.

In the Data Target section, select the Direct type and then choose the appropriate Pimcore attribute where the value should be saved, in this case, Main Image.

Multiple images mapping to one attribute

For example, if you have attribute that is Gallery type in Pimcore, and you want to map multiple images to the single attribute. In our example, we have 5 different column but all the columns refer to one attribute (Other product images - gallery)

In the Source attributes you need to choose all 5 columns

In the Transformation Pipeline section, add a transformation called Load Asset. This transformation allows the system to locate assets that were previously uploaded to Pimcore and stored in a specific folder. Since the Excel sheet contains the exact asset path (for example, /Test2/0.png), configure the transformation to load the asset by path. Alternatively, assets can also be loaded using their Pimcore asset ID.

As well in transformation pipeline section, you need to add a transformation “As Gallery” so that system knows that you are trying to import multiple images in Gallery data format.

In the Data Target section, select the Direct type and then choose the appropriate Pimcore attribute where the assets should be saved, in this case, Other product images.

Step 6 is the same as described in the “Import Objects in Bulk” section.

Document import in a relational field

If the asset is a PDF, Word document, Excel file, or any other kind of document, the process is similar to images. First, make sure the file is uploaded to Pimcore in the Assets section.

After that, follow the same instructions explained earlier. The only difference is in the mapping step. In Source Attribute, choose the column from your uploaded Excel file that contains the document reference (in my example, that column is named Datasheet).

In the Transformation Pipeline section, add a "Load asset" transformation and select "Path" as the source type.

In the Data Target section, select the Direct type and then choose the appropriate Pimcore attribute where the assets should be saved, in this case, Datasheet (EN).

The end result, after the import is finished, is that the file will be assigned to the Datasheet (EN) attribute on the product.

Monitoring Execution and Handling Errors

It would be hard to check each created/updated object using DataHub Importer and validate if everything went smooth or not. Instead, part of the importer is Log section.

In the Import Logs tab, you can verify whether the import was successful. If the import fails, error details will be displayed in the table, along with an explanation of what went wrong.

To Conclude

At first glance, the Pimcore DataHub Import tool can seem complex and difficult to grasp. That impression usually comes from the sheer number of options and configurations it offers. In reality, that flexibility is exactly what makes it such a powerful solution.

In this article, we focus on the scenarios we most often encounter while working with our clients who use the importer in real projects. These are not theoretical examples, but practical situations that come up again and again during implementations, integrations, and ongoing maintenance. Along the way, we also touch on additional use cases that go beyond the most common ones, to give a broader picture of what’s possible.

The content of this article is the result of years of hands-on experience, working through many different data import scenarios across various industries. It reflects the challenges our clients face, the questions they ask, and the solutions we have proven in practice. Our goal is to help you better understand the tool, avoid common pitfalls, and approach Pimcore DataHub imports with the confidence that comes from real-world experience.