[Docs] Update and refine docs (#657)

* Restructure and correct Data Importer documentation

Reorder the docs to follow the Studio "Data Setup" wizard, add a
Getting Started walkthrough, and resolve duplicate numeric prefixes
(03_Configuration/03_Upgrade, 06_Extending/06_Troubleshooting_FAQ).

Correct content that no longer matched the source:

- Installation targeted Pimcore 10.5/11 and admin-ui-classic-bundle.
  composer.json requires pimcore/pimcore ^2026.1 and PHP 8.4/8.5, and
  registerDependentBundles() wires Datahub automatically.
- Element Location Update was documented as applying to all imported
  objects. Resolver::loadOrCreateAndPrepareElement() applies the
  creation strategy to new elements and the update strategy to
  existing ones only.
- CSV "Skip First Row" was documented as turning the header row into
  column names. It only skips the row; the separate "Save Header Name"
  option does that.
- The Extending page described the removed ExtJS plugin API. The
  frontend is now a Studio UI plugin using dynamic type registries.

Document features present in code and UI but not in the docs: the
Upload data source, the SQL file format, the String Replace operator,
the Many-to-Many Relation data target, the Find or Create Folder and
Do Not Create location strategies, As Variant, Include unpublished
objects, the ID data index gating Delta Check and Cleanup, the
Write If Target Is Not Empty / Write If Source Is Empty flags,
Autofill, the one-time job schedule, and PostPreparationEvent.

Replace doc/07_Studio.md, a hand-maintained mirror of the Studio REST
API, with doc/06_Extending/03_Studio_Integration.md. All 20 Studio
controllers are @internal and Studio serves generated OpenAPI docs at
/pimcore-studio/api/docs, so the copy could only drift. It already had:
it named the PHP constant PLUGIN_DATA_IMPORTER_CONFIG as the permission,
whose value is plugin_datahub_config. The replacement keeps the
permission model, the API docs location, and the supported ways to
drive imports from outside.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6

* Replace Admin Classic screenshots with Pimcore Studio captures

Recapture the Data Importer screenshots from Pimcore Studio on the
public demo. The previous images showed the removed ExtJS Admin Classic
interface.

Replaced: datasource_asset, datasource_sql, import_preview,
resolver_settings, transformation_pipeline, data_target_direct,
execution, logging, and a fresher mapping.

Added: data_target_types (all four data target types) and
processing_settings, neither of which had an image.

Correct three details the live UI disproved:

- The tab order is General, Data Setup, Execution, Import Logs,
  Permissions. Getting Started listed Permissions second.
- Start Import sits in the Manual Execution panel, not in the
  Execution Settings panel.
- The Data Source Type dropdown lists HTTP before SFTP.

Verified live against the demo: the six data sources, the five Data
Setup steps, the four data target types including Many-to-Many Relation,
the Import Asset options (Parent folder, Use existing, Overwrite
existing, Preg match), the Processing Settings groups, and the two
schedule types.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6

* Restructure installation and complete the Studio event list

- Installation becomes a folder with the upgrade notes as its subpage, matching
  the other bundles.
- Delete the Studio Integration page. It described @internal endpoints and
  duplicated permissions. The supported-interfaces table ("driving imports from
  outside Pimcore": push data source, the CLI commands, Messenger) was the
  valuable part and moves to Import Execution Details.
- Permissions are now documented once, in the installation chapter, covering the
  gate, adapter and per-configuration permissions.
- The events page named three Studio events as examples. There are fourteen.
  Document all of them, with payloads read from each event class.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6

* Require installing the Datahub bundle, not only loading it

The page said Composer pulls Datahub in and the bundle registers it as a
dependent bundle, which reads as "Datahub is set up automatically". It is not.
registerDependentBundles only loads a bundle into the kernel, and
pimcore:bundle:install never cascades. Datahub's own installer is what creates
the plugin_datahub_config permission and the Datahub permission category this
adapter's controllers require, so without it every non-admin user is locked out.

Add the explicit install step for Datahub.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6

* Recapture the execution screenshots and document the XLSX sheet default

The execution and troubleshooting screenshots were still Admin Classic. Recapture
the manual execution, execution status and cron settings in Pimcore Studio, each
cropped to its own section. Remove datasource.png, which no page references.

Add the XLSX Sheet Name default (Sheet1), which XlsxFileInterpreter applies.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6

* Recapture Studio screenshots at the agreed resolution

Reshoot the Data Setup screenshots against real demo data at 1440x900 and crop them to
the relevant section:

- execution / faq_execution_status: taken during an actual import run, so the progress
  bar and item counter show real values.
- datasource_asset, datasource_sql, processing_settings: proper section crops, no cut
  content.
- mapping: wider crop with real source preview values.
- transformation_pipeline, data_target_types, data_target_direct: modal-only crops, no
  background bleed. data_target_direct now shows the Direct target with its own config
  fields instead of repeating the type dropdown.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Correct the per-configuration permission model

The adapter permission and the Permissions tab are alternatives, not layers:
Configuration::isAllowed() falls back to plugin_datahub_adapter_dataImporterDataObject
only while the permission grid is empty, and ignores it entirely once a single user or
role entry exists. Also document plugin_datahub_admin, which bypasses both.

* Fix result type and operator details in the mapping reference

The Many-to-Many Relation target accepts advancedDataObjectArray, not
advancedDataObject; the product's own error message is wrong, supportsType() is
authoritative. The Date operator has a Format setting defaulting to Y-m-d rather
than requiring one. Add the 10 MB limit both preview file options enforce.

* Document which triggers respect the Active flag

prepareImport() is called with $ignoreActiveFlag = true only from the manual
Start Import action; execute-cron and prepare-import skip inactive configurations.

* Drop the duplicate execution status screenshot

faq_execution_status.png was byte-identical to execution.png after the recapture.
Reference the single remaining file from both pages.

* Use Pimcore Studio consistently and wrap the upgrade notes at 120 chars

* Address Copilot review findings on the restructured docs

Verified each claim against the source before applying:

- Custom Strategies: cleanup strategies and element factories have no Studio
  registry. The cleanup options are hard-coded in processing-settings-step.tsx
  and the factory is not exposed at all, so mark both backend-only in the
  extension point table instead of implying a settings form can be registered.
- Import Execution Details: preparation does not always queue one item per
  record. AbstractInterpreter::processImportRow() skips unchanged records when
  Delta Check is enabled.
- Data Sources: drop the recommendation to encode credentials into the HTTP
  URL. HttpLoader puts the full URL into its InvalidConfigurationException, so
  the password reaches logs and error reporting.
- Getting Started: the Studio operator is labeled "Numeric", not "As Numeric"
  (dynamic-type-transformer-numeric.tsx).
- Processing Settings: DeltaChecker::hasChanged() writes the hash during
  preparation, before the record is processed, so a failed record is skipped on
  the next identical run. Document the actual checkpoint.
- Troubleshooting: the "command is already running" message is also the normal
  result of a concurrent run. Require process verification first, note the 24h
  lock TTL from SequentialProcessQueueCommand, and stop assuming the database
  lock store.
- File Formats: there is no JMESPath validation on save. ConfigurationService
  persists the array directly; JsonFileInterpreter::setSettings() parses the
  expression only when the interpreter is instantiated for preview or import.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011gNY3NwTbQPwco5wyWgpE8

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: fashxp

README.md

@@ -1,41 +1,46 @@
 ---
 title: Data Importer
 ---
- 
+
 # Pimcore Data Importer
 
-This extension adds a comprehensive import functionality to Pimcore Datahub. It allows importing data from external 
-sources and adjusting it to Pimcore Data Objects based on a configured mapping without writing any code.
-
-## Features in a Nutshell
-- Multiple imports configuration directly in Datahub. 
-- Data import from various data sources.
-- Supported File Formats: `csv`, `xlsx`, `json`, `xml`.
-- Strategies configuration for: 
-  - loading existing elements for updating data.
-  - defining location for newly imported data.
-  - publishing data.
-  - cleanup of existing data. 
--  Mappings definition for adjusting data to Pimcore Data Objects with:
-   - simple transformations.
-   - preview of imported data.
-- Imports execution directly in Pimcore Datahub or on a regular base via cron definitions. 
-- Import status updates and extensive logging information. 
+The Data Importer adds import functionality to Pimcore Datahub. It reads data from external sources and writes it into
+Pimcore data objects based on a configured mapping, without writing code.
 
 ![Mapping](./doc/img/mapping.png)
 *Mapping and preview of data*
 
-## Documentation Overview
-- [Installation](./doc/01_Installation.md)
-- [Configuration](./doc/03_Configuration/README.md)
-- [Import Execution Details](./doc/04_Import_Execution_Details.md)
-- [Import Progress and Logging](./doc/05_Import_Progress_and_Logging.md)
-- [Extending](./doc/06_Extending/README.md)
-- [Troubleshooting/FAQ](./doc/06_Troubleshooting_FAQ.md) 
-
-## Further Information
-On other Pimcore Datahub adapters and export solutions:
-- [Datahub (GraphQL API)](https://pimcore.com/docs/platform/Datahub/)
-- [Datahub Simple Rest API](https://pimcore.com/docs/platform/Datahub_Simple_Rest/)
--  [Datahub File Export](https://pimcore.com/docs/platform/Datahub_File_Export/)
-- [Datahub Productsup](https://pimcore.com/docs/platform/Datahub_Productsup/)
+## Features
+
+- Import configurations managed directly in Datahub, edited in Pimcore Studio.
+- Six data sources: asset, upload, HTTP, SFTP, push endpoint, and SQL.
+- Five file formats: CSV, JSON, XML, XLSX, and SQL query results.
+- Resolver strategies that decide whether a record updates an existing data object or creates a new one, where it is
+  stored, and whether it is published.
+- A mapping editor with a live preview of the source data and of every transformation step.
+- Delta check to skip unchanged records, and cleanup to remove data objects that left the source.
+- Manual, scheduled, command-line and push-triggered execution.
+- Progress tracking and detailed import logs.
+
+## Documentation
+
+Start here:
+
+- [Installation](./doc/01_Installation/README.md): install the bundle and set up queue processing.
+- [Getting Started](./doc/02_Getting_Started.md): build a first import end to end.
+
+Reference:
+
+- [Configuration](./doc/03_Configuration/README.md): every option of an import configuration.
+- [Import Execution Details](./doc/04_Import_Execution_Details.md): what happens between the trigger and the data.
+- [Import Progress and Logging](./doc/05_Import_Progress_and_Logging.md): watch and audit an import.
+- [Extending](./doc/06_Extending/README.md): custom strategies and events.
+- [Troubleshooting / FAQ](./doc/08_Troubleshooting_FAQ.md): common problems.
+- [Upgrade Notes](./doc/01_Installation/01_Upgrade.md): breaking changes per release.
+
+## Other Datahub Adapters
+
+- [Datahub (GraphQL API)](https://github.com/pimcore/data-hub/blob/2026.x/doc/01_Installation_and_Upgrade/README.md)
+- [Datahub Simple REST API](https://github.com/pimcore/data-hub-simple-rest/blob/2026.x/doc/01_Installation/README.md)
+- [Datahub File Export](https://github.com/pimcore/data-hub-file-export/blob/2026.x/doc/01_Installation/README.md)
+- [Datahub Productsup](https://github.com/pimcore/data-hub-productsup/blob/2026.x/doc/01_Installation/README.md)

doc/01_Installation.md

@@ -1,4 +1,9 @@
-# Update Notes
+---
+title: Upgrade Notes
+description: Breaking changes and migration steps per release.
+---
+
+# Upgrade Notes
 
 ## Upgrade to 2026.1.0
 
@@ -9,15 +14,19 @@
 
 ### Removed Admin Classic / ExtJS UI
 
-- Removed `pimcore/admin-ui-classic-bundle` dependency. The bundle no longer implements `PimcoreBundleAdminClassicInterface` or uses `BundleAdminClassicTrait`.
-- Removed all ExtJS-based JavaScript and CSS paths (`getCssPaths()`, `getJsPaths()` methods removed from `PimcoreDataImporterBundle`).
+- Removed the `pimcore/admin-ui-classic-bundle` dependency. The bundle no longer implements
+  `PimcoreBundleAdminClassicInterface` and no longer uses `BundleAdminClassicTrait`.
+- Removed all ExtJS-based JavaScript and CSS paths. `getCssPaths()` and `getJsPaths()` were removed from
+  `PimcoreDataImporterBundle`.
 - `PimcoreAdminBundle` is no longer registered as a dependent bundle.
-- The Admin UI configuration panel is now implemented using the Pimcore Studio UI.
-- `Pimcore\Bundle\AdminBundle\Helper\QueryParams` is no longer used; replaced by `DataTypeServiceInterface::extractSortingSettings()`.
+- The configuration panel is now implemented in Pimcore Studio.
+- `Pimcore\Bundle\AdminBundle\Helper\QueryParams` is no longer used. It was replaced by
+  `DataTypeServiceInterface::extractSortingSettings()`.
 
-### Studio UI
+### Pimcore Studio
 
-- Added Studio UI implementation for the Data Importer configuration panel (tabs: Data Setup, Execution, Import Logs).
+- Added the Pimcore Studio implementation of the Data Importer configuration panel, with the tabs Data Setup,
+  Execution and Import Logs.
 - Studio frontend assets are now shipped with the bundle.
 
 ### Namespace Changes
@@ -26,23 +35,28 @@
 
 ### Messenger Transport Configuration
 
-- The messenger transport DSN is now configurable via the `%pimcore.messenger.transport_dsn_prefix%` container parameter instead of being hardcoded to `doctrine://default`. This allows the installer to wire the transport DSN from environment variables (e.g. `PIMCORE_MESSENGER_TRANSPORT_DSN_PREFIX`).
+- The messenger transport DSN is configurable via the `%pimcore.messenger.transport_dsn_prefix%` container parameter
+  instead of being hardcoded to `doctrine://default`. The installer can now wire the transport DSN from environment
+  variables such as `PIMCORE_MESSENGER_TRANSPORT_DSN_PREFIX`.
 
 ### Interface & Return Type Changes
 
-- `DataTypeServiceInterface`: Added new method `extractSortingSettings(?string $sort): array` to the interface. Any custom implementations of `DataTypeServiceInterface` must implement this method.
+- `DataTypeServiceInterface`: added the method `extractSortingSettings(?string $sort): array`. Custom implementations
+  of the interface must implement it.
 - `CronValidationResponse::isValid(): bool` renamed to `CronValidationResponse::getIsValid(): bool`.
 - `ImportProgressResponse::isRunning(): bool` renamed to `ImportProgressResponse::getIsRunning(): bool`.
-- `PimcoreDataImporterBundle::getInstaller()` return type changed from `?InstallerInterface` to `InstallerInterface` (non-nullable).
+- `PimcoreDataImporterBundle::getInstaller()` return type changed from `?InstallerInterface` to
+  `InstallerInterface` (non-nullable).
 
 ### Class Visibility & Finalization
 
 - Many classes have been marked `final` and/or `@internal`. Custom subclasses of these classes are no longer supported:
-  - `CronScheduler`, `JobScheduler`, `SchedulerFactory` — marked `final` and `@internal`
-  - `PreviewData` — marked `final` and `@internal`
-  - `PimcoreDataImporterBundle` — marked `final`
-  - Various exception classes (`InvalidScheduleException`, etc.) — marked `final`
-- Several `protected` methods on final classes have been changed to `private`. If you were overriding these methods in subclasses, you must refactor.
+  - `CronScheduler`, `JobScheduler`, `SchedulerFactory`: marked `final` and `@internal`
+  - `PreviewData`: marked `final` and `@internal`
+  - `PimcoreDataImporterBundle`: marked `final`
+  - Various exception classes (`InvalidScheduleException`, etc.): marked `final`
+- Several `protected` methods on final classes were changed to `private`. Subclasses overriding them have to be
+  refactored.
 - `ConfigDataObjectController::saveAction()` return type changed from `?JsonResponse` to `JsonResponse` (non-nullable).
 - `Installer::getLastMigrationVersionClassName()` return type changed from `?string` to `string` (non-nullable).
 
@@ -56,7 +70,8 @@
 
 ### API Schema Changes
 
-- `UnitDataResponse`: Schema property renamed from `UnitList` to `unitList` (camelCase). If you consume this API response, update your client accordingly.
+- `UnitDataResponse`: the schema property was renamed from `UnitList` to `unitList`. Update clients consuming this
+  response.
 
 ## Update to Version 1.11