--- title: "Upgrading instructions for older versions" manual: "External Import" version: "main" permalink: "https://docs.typo3.org/permalink/cobweb/external_import:appendix-old-upgrades@main" source: "Appendix/Upgrades/Index.rst" rendered: "2026-10-17T19:10:20+00:00" --- # Upgrading instructions for older versions {#appendix-old-upgrades} ## Upgrade to 7.3.0 {#installation-upgrade-730} This version introduces a new reaction dedicated to deleting already imported data. ## Upgrade to 7.2.0 {#installation-upgrade-720} The `HandleDataStep` process now keeps `null` values found in the imported data. This is an important change, but is has a concrete effect only if the target field is nullable (i.e. it has an `eval` property including `null` or has property `nullable` set to `true` in its TCA configuration). In such cases, existing values will be set to `null` where they would have been left untouched before. It may also affect user functions in transformations where a `null` value was not expected to be found until now. ## Upgrade to 7.1.0 {#installation-upgrade-710} External Import now supports PHP 8.2. When running the preview mode from the backend module, some steps now provide a download button, to retrieve the data being handled in its current state. When setting a fixed value, the new [column configuration property](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-value@main) should be preferred over the historical [transformation property](https://docs.typo3.org/permalink/cobweb/external_import:administration-transformations-properties-value@main). It is now possible to define explicitly [the order in which columns are processed](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-columnsorder@main). ## Upgrade to 7.0.0 {#installation-upgrade-700} Support for old-style Connector services was droppped (i.e. connectors registered as TYPO3 Core Services). If you use custom connector services, make sure to update them (see the [update instructions](https://docs.typo3.org/p/cobweb/svconnector/main/en-us/Installation/Index.html#installation-updating-500) provided by extension "svconnector"). When editing Scheduler tasks in the External Import backend module, it is no longer possible to define a start date (this tiny feature was a lot of hassle to maintain across TYPO3 versions). All hooks were removed. If you were still using hooks, please refer to the [archived page about hooks](https://docs.typo3.org/permalink/cobweb/external_import:appendix-hooks@main) to find replacement instructions. A new `ReportStep` has been introduced, which triggers a webhook reporting about the just finished import run. In order for this step to run (and do the reporting) even when the process is aborted, a new possibility has been added for steps to run despite the interruption. This actually fixes a bug with the `ConnectorCallbackStep` which was never called when the process was aborted. If you use such a post-processing, you can now report about failed imports if needed. ## Upgrade to 6.3.0 {#installation-upgrade-630} External Import now supports Connector services registered with new system introduced with extension "svconnector" version 5.0.0, while staying compatible with the older versions. Another small new feature is the possibility to define a storage pid for the imported data on the [command line](https://docs.typo3.org/permalink/cobweb/external_import:user-command@main) or when creating a [Scheduler task](https://docs.typo3.org/permalink/cobweb/external_import:user-scheduler@main), which overrides storage information that might be found in the TCA or in the extension configuration. ## Upgrade to 6.2.0 {#installation-upgrade-620} The [Substructure Preprocess event](https://docs.typo3.org/permalink/cobweb/external_import:developer-events-substructure-preprocess@main) is now fired for both array-type and XML-type data (previously, only for array-type data). To know which type of data is being handled, a new `getDataType()` method is available. The type of structure that must be returned after modfication (by calling `setStructure()` must be either an array or a `DomNodeList`, as opposed to just an array in older versions. Existing event listeners may need to be adapted. ## Upgrade to 6.1.0 {#installation-upgrade-610} Records which have no external key set (the value referenced by the [referenceUid](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-reference-uid@main) property) are now skipped in the import. Indeed it makes no sense to import records without such keys, as they can never be updated and - if several are created in a single import run - they will override each other. Still it is a change of behaviour and should be noted. ## Upgrade to 6.0.0 {#installation-upgrade-600} All properties that were deprecated in version 5.0.0 were removed and the backwards-compatibility layer was dropped. Please refer to the [5.0.0 upgrade instructions](https://docs.typo3.org/permalink/cobweb/external_import:installation-upgrade-500@main) and check if you have applied all changes. All hooks were marked as deprecated. They will be removed in version 7.0.0. You should migrate your code to use either [custom process steps](https://docs.typo3.org/permalink/cobweb/external_import:developer-steps@main) or the newly introduced [PSR-14 events](https://docs.typo3.org/permalink/cobweb/external_import:developer-events@main). See the [hooks chapter](https://docs.typo3.org/permalink/cobweb/external_import:developer-hooks@main) for information about how to migrate each hook. External Import is now configured for using the standard (Symfony) dependency injection mechanism. This means it is not necessary to instantiate the `\Cobweb\ExternalImport\Importer` class using Extbase's `\TYPO3\CMS\Extbase\Object\ObjectManager` anymore when using the Importer as an API. The PHP code was cleaned up as much as possible and strict typing was declared in every class file. This may break your custom code if you were calling public methods without properly casting arguments. ## Upgrade to 5.1.0 {#installation-upgrade-510} There is a single change in version 5.1.0 that may affect existing imports: when a user function fails to handle the value it was supposed to transform (by throwing an exception), that value is now removed from the imported dataset. Before that it was left unchanged. ## Upgrade to 5.0.0 {#installation-upgrade-500} There are many changes in version 5.0.0, but backwards-compatibility has been provided for all them (except the minor breaking change mentioned below). Please make sure to update your configuration as soon as possible, backwards-compatibility will be dropped in version 5.1.0. Messages for deprecated configuration appear in the backend module when viewing the details of a configuration. ### Changes {#installation-upgrade-500-changes} The general configuration must now be placed in `$GLOBALS['TCA'][table-name]['external']['general']` instead of `$GLOBALS['TCA'][table-name]['ctrl']['external']`. The "additionalFields" property from the general configuration (and not from the "MM" property) has been moved to its own configuration space. Rather than `$GLOBALS['TCA'][table-name]['ctrl']['external'][some-index]['additionalFields]` it is now `$GLOBALS['TCA'][table-name]['external']['additionalFields'][some-index]`. Furthermore, it is no longer a simple comma-separated list of fields, but an array structure with all the same options as standard column configurations. For more details, [see the relevant chapter](https://docs.typo3.org/permalink/cobweb/external_import:administration-additionalfields@main). The "MM" property is deprecated. It should not be used anymore. Instead the new [multipleRows](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-multiple-rows@main) or [children](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-children@main) properties should be used according to your import scenario. The "userFunc" property of the transformations configuration has been renamed to [userFunction](https://docs.typo3.org/permalink/cobweb/external_import:administration-transformations-properties-userfunction@main) and its sub-property "params" has been renamed "parameters". If both "insert" and "update" operations are disabled in the general configuration (using the [disabledOperations property](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-disabledoperations@main)), External Import will now delete records that were not marked for update (even if the actual update does not take place). Previously, no records would have been deleted, because the entire matching of existing records was skipped. Accessing the external configuration inside a custom step with `$this->configuration` or `$this->getConfiguration()` is deprecated. `$this->getImporter()->getExternalConfiguration()` instead. The "scheduler" system extension is required instead of just being suggested. ### New stuff {#installation-upgrade-500-new} It is possible to import nested structures using the [children](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-children@main) property. For example, you can now import data into some table and its images all in one go by creating a nested structure for the "sys_file_reference" table. The [multipleRows](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-multiple-rows@main) and [multipleSorting](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-multiple-sorting@main) properties allow for a much clearer handling of denormalized external sources. Check out the revamped [Mapping data](https://docs.typo3.org/permalink/cobweb/external_import:user-mapping-data@main) chapter which should hopefully help you get a better picture of what is possible with External Import and how different properties (especially the new ones) can be combined. [Custom steps](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-customsteps@main) can now receive an array of arbitrary parameters. ### Breaking changes {#installation-upgrade-500-breaking-changes} The `\Cobweb\ExternalImport\Step\StoreDataStep` class puts the list of stored records into the "records" member variable of the `\Cobweb\ExternalImport\Domain\Model\Data` object. This used to be a simple list of records for the imported table. Since child tables are now supported, the structure has changed so that there's now a list of records for each table that was imported. The table name is the key in the first dimension of the array. If you were relying on this data in a custom step, you will need to update your code as no backward-compatibility was provided for this change. ## Upgrade to 4.1.0 {#appendix-old-upgrades-410} Version 4.1.0 introduces one **breaking change**. There now exists custom permissions for backend users regarding usage of the backend module. On top of table-related permissions, users must have been given explicit rights (via the user groups they belong to) to perform synchronizations or define Scheduler tasks. See the [User rights chapter](https://docs.typo3.org/permalink/cobweb/external_import:administration-user-rights@main) for more information. ## Upgrade to 4.0.0 {#appendix-old-upgrades-400} ### Importer API changes {#appendix-old-upgrades-400-importer-api} The External Import configuration is now fully centralized in a `\Cobweb\ExternalImport\Domain\Model\Configuration` object. Every time you need some aspect of the configuration, you should get it via the instance of this class rather than through any other mean. The most current use case was getting the name of the current table and index from the `\Cobweb\ExternalImport\Importer` class, using `Importer::getTableName()` and `Importer::getIndex()`. Such methods were deprecated and should not be used anymore. Use instead: ```php $table = $importer->getExternalConfiguration()->getTable(); $index = $importer->getExternalConfiguration()->getIndex(); ``` The `Importer::synchronizeData()` method was renamed to `Importer::synchronize()` and the `Importer::importData()` method was renamed to `Importer::import()`. The old methods were kept, but are deprecated. The `Importer::synchronizeAllTables()` method should not be used anymore as it does not allow for a satisfying reporting. Instead a loop should be done on all configurations and `Importer::synchronize()` called inside the loop. See for example `CobwebExternalImportCommandImportCommand::execute()`. Other deprecated methods are `Importer::getColumnIndex()` and `Importer::getExternalConfig()`. The `Importer::getExistingUids()` method was moved to a new class called `\Cobweb\ExternalImport\Domain\Repository\UidRepository` (which is a Singleton). ### Transformation properties {#appendix-old-upgrades-400-transformation-properties} All column properties that are related to the "Transform data" scope have been grouped into a new property called [transformations](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-transformations@main). This is an ordered array, which makes it possible to use transformation properties several times on the same field (e.g. calling several user functions) and to do that in a precise order. As an example, usage of such properties should be changed from: ```php $GLOBALS['TCA']['fe_users']['columns']['starttime']['external'] = [ 0 => [ 'field' => 'start_date', 'trim' => true 'userFunction' => [ 'class' => \Cobweb\ExternalImport\Task\DateTimeTransformation::class, 'method' => 'parseDate' ] ] ]; ``` to: ```php $GLOBALS['TCA']['fe_users']['columns']['starttime']['external'] = [ 0 => [ 'field' => 'start_date', 'transformations => [ 10 => [ 'trim' => true ], 20 => [ 'userFunc' => [ 'class' => \Cobweb\ExternalImport\Task\DateTimeTransformation::class, 'method' => 'parseDate' ] ] ] ] ]; ``` If you want to preserve "old-style" order, the transformation properties were called in the following order up to version 3.0.x: "trim", "mapping", "value", "rteEnabled" and "userFunc". Also note that "value" was ignored if "mapping" was also defined. Now both will be taken into account if both exist (although that sounds rather like a configuration mistake). A compatibility layer ensures that old-style transformation properties are preserved, but this is a temporary convenience, which will be removed in the next version. So please upgrade your configurations. > [!NOTE] > The upgrade wizard from version 3.0.0 has been removed. If you are upgrading from TYPO3 > 6.2 to TYPO3 8.7, you must go through TYPO3 7.6 first and use the upgrade wizard from > External Import 3.0.x before moving on to TYPO3 8.7. ### Renamed properties {#appendix-old-upgrades-400-renamed-properties} To continue the move to unified naming conventions for properties started in version 3.0, the mapping and MM properties which had underscores in their names were moved to lowerCamelCase name. The old properties are interpreted for backwards-compatibility, but this will be dropped in the next major version. The backend module will show you the deprecated properties. ### Breaking changes {#appendix-old-upgrades-400-breaking-changes} While all hooks were preserved as is, in the sense that they still receive a back-reference to the `\Cobweb\ExternalImport\Importer` object, the `processParameters` hook was modified due to its particular usage (it is called in the backend module, so that processed parameters can be viewed when checking the configuration). It now receives a reference to the `\Cobweb\ExternalImport\Domain\Model\Configuration` object and not to the `\Cobweb\ExternalImport\Importer` object anymore. Please update your hooks accordingly. ## Upgrade to 3.0.0 {#appendix-old-upgrades-300} The "excludedOperations" column configuration, which was deprecated since version 2.0.0, was entirely removed. The same goes for the "mappings.uid_foreign" configuration. More importantly the Scheduler task was renamed from `tx_externalimport_autosync_scheduler_Task` to `\Cobweb\ExternalImport\Task\AutomatedSyncTask`. As such, existing Scheduler tasks need to be updated. An upgrade wizard is provided in the Install Tool. It will automatically migrate existing old tasks. ![The update wizard shows that there are tasks to update](../../Images/UpdateWizard.png) If there are no tasks to migrate, the External Import wizard will simply not show up. Otherwise just click on the "Execute" button and follow the instructions. Several general TCA configuration properties were renamed, to respect a global lowerCamelCase naming convention. This is the list of properties and how they were renamed: - additional_fields => additionalFields - reference_uid => referenceUid - where_clause => whereClause ## Upgrade to 2.0.0 {#appendix-old-upgrades-200} The column configuration "excludedOperations" has been renamed to "disabledOperations", for consistency with the table configuration option. The "excludedOperations" is preserved for now and will log an entry into the deprecation log. You are advised to change the naming of this configuration if you use it, support will be dropped at some point in the future.