[Docs] Update and refine docs#657
Merged
Merged
Conversation
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
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
- 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
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
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
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>
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.
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.
prepareImport() is called with $ignoreActiveFlag = true only from the manual Start Import action; execute-cron and prepare-import skip inactive configurations.
faq_execution_status.png was byte-identical to execution.png after the recapture. Reference the single remaining file from both pages.
Contributor
There was a problem hiding this comment.
Pull request overview
Reorganizes and expands Data Importer documentation for Pimcore Studio and the 2026.x release line.
Changes:
- Adds installation, getting-started, troubleshooting, and detailed reference guides.
- Updates Studio workflows, extension points, events, and execution behavior.
- Removes obsolete paths and legacy API documentation.
Reviewed changes
Copilot reviewed 31 out of 46 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
README.md |
Refreshes project overview and navigation. |
doc/08_Troubleshooting_FAQ.md |
Adds expanded troubleshooting guidance. |
doc/07_Studio.md |
Removes internal Studio API reference. |
doc/06_Troubleshooting_FAQ.md |
Removes superseded FAQ. |
doc/06_Extending/README.md |
Updates extension overview. |
doc/06_Extending/03_Events.md |
Removes old events page. |
doc/06_Extending/02_Events.md |
Documents import and Studio events. |
doc/06_Extending/01_Extend_Custom_Strategies.md |
Removes obsolete extension guide. |
doc/06_Extending/01_Custom_Strategies.md |
Adds Studio-oriented strategy guide. |
doc/05_Import_Progress_and_Logging.md |
Expands progress and logging documentation. |
doc/04_Import_Execution_Details.md |
Clarifies preparation and processing phases. |
doc/03_Configuration/README.md |
Reorganizes configuration navigation. |
doc/03_Configuration/07_Execution_Configuration.md |
Expands trigger and scheduling guidance. |
doc/03_Configuration/06_Processing_Settings.md |
Adds updated processing reference. |
doc/03_Configuration/06_Mapping_Configuration/README.md |
Removes old mapping path. |
doc/03_Configuration/06_Mapping_Configuration/03_Data_Target/README.md |
Removes old target reference. |
doc/03_Configuration/06_Mapping_Configuration/03_Data_Target/05_Classification_Store_Batch_Details.md |
Removes old batch guide. |
doc/03_Configuration/06_Mapping_Configuration/02_Transformation_Pipeline.md |
Removes old pipeline guide. |
doc/03_Configuration/05_Processing_Settings.md |
Removes superseded processing page. |
doc/03_Configuration/05_Mapping_Configuration/README.md |
Adds mapping and autofill reference. |
doc/03_Configuration/05_Mapping_Configuration/02_Data_Target/README.md |
Documents current target types. |
doc/03_Configuration/05_Mapping_Configuration/02_Data_Target/01_Classification_Store_Batch_Details.md |
Adds relocated batch guide. |
doc/03_Configuration/05_Mapping_Configuration/01_Transformation_Pipeline.md |
Documents current operators. |
doc/03_Configuration/04_Resolver_Settings.md |
Expands resolver strategy documentation. |
doc/03_Configuration/03_Import_Preview.md |
Clarifies preview behavior. |
doc/03_Configuration/02_File_Formats.md |
Expands format reference. |
doc/03_Configuration/01_Data_Sources.md |
Expands source reference. |
doc/02_Getting_Started.md |
Adds first-import walkthrough. |
doc/01_Installation/README.md |
Adds current installation guide. |
doc/01_Installation/01_Upgrade.md |
Refines upgrade notes. |
doc/01_Installation.md |
Removes obsolete installation page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.