Merging multiple sets of data

By default the identifiers are changed when importing data, making it possible to merge several projects into one installation. The table identifiers are automatically changed in such a way that content elements remain attached to their pages and images to their content elements.

It is also possible to keep the identifiers (uids) to allow the reproduction of the exact same page and content tree.

What doesn't it do?

• Exported content does not include code from any installed extensions or sitepackages.
• This extension is not used for the Download feature in the List module.

Backward compatibility

The data structure for content exports have seen very little changes since their original inception. It is sometimes possible to export content from a fifteen year old TYPO3 installation straight into a current installation of TYPO3.

It is often more feasible to use the import/export tool than it is to attempt to update old installations of TYPO3.

The following images show the export dialog of a current TYPO3 installation and TYPO3 v3.8.0: They correspond pretty much.

However, several details may change due to Deprecations and Breaking Changes, which can lead to issues with old import data. In cases where the import fails, it is recommended to try to manually export assets/files, and re-create the reference Index after import. The older an installation is, the more manual rework is expected.

Ongoing improvements to the Import/Export code base can only made, when legacy considerations are not the first priority. A "guaranteed" fully-working export and re-import is only given for T3D structures within the same major version.

Installation with Composer

Check whether you are already using the extension with:

composer show | grep impexp

This should either give you no result or something similar to:

typo3/cms-impexp       v12.4.11

If it is not installed yet, use the composer require command to install the extension:

composer require typo3/cms-impexp

The given version depends on the version of the TYPO3 Core you are using.

Installation without Composer

In an installation without Composer, the extension is already shipped but might not be activated yet. Activate it as follows:

1. In the backend, navigate to the Admin Tools > Extensions module.
2. Click the Activate icon for the Import / Export extension.

Open the export module

In the page tree, right-click the page from which you want to start the export (1) and select More options ... > Export (2).

Configure the export settings

On the first tab of the export module you can fine-tune the export (1).

• If you want to export all data of the selected page including its subpages, select the "Infinite" option in the Levels selection box.
• Under Include tables you can limit the types of records to be exported.
• Under Include relations to tables you specify which relations of the records should be included in the export file. The related records will be included even if they are outside the pages selected for export.
• Under Use static relations for tables you select which relations should be included without including the related record. This is useful if the related record already exists in the target TYPO3 instance.
• If the same table is selected in both Include relations to tables and Use static relations for tables, the relation is treated as static.
• The Exclude disabled elements checkbox excludes records that are disabled according to their TCA configuration. This is checked by default.

Apply your changes via the Update button and repeat this step until the preview meets your expectations.

Review the records to be exported

All pages selected for export are listed in the upper part of the dialog (1).

Below this is a detailed list of all data to be exported (2). Here you can exclude individual records or manually make them editable, if supported.

If the relation to records is lost, an orange exclamation mark will be shown. This happens if records are stored outside the export page tree or if excluded tables break relations.

Apply your changes by pressing the Update button and repeat this step as needed until the preview matches your expectations (3).

Then switch to the Advanced Options tab (4).

Optionally select advanced export options

In the third tab of the export module you can specify further export options (1).

Checking Save files in extra folder .. saves linked files in a separate folder instead of embedding them in the export file. This is mandatory for distributions or useful when handling large file sets that would otherwise bloat the export file and potentially exhaust memory. The folder is named "{filename}.files".

Apply your changes via the Update button (2) and then switch to the File & Preset tab (3) to proceed.

Perform the export

In the second tab of the export module you can specify the metadata for the export (1) before starting the export process.

You can then either:

• Download the export file (2.a), or
• Save it on the server (2.b).

Saving on the server is currently required if you have enabled saving related files in a separate folder (see Optionally select advanced export options).

Open the import module

In the page tree, right-click the page you want to import to (1) and select More options ... > Import (2).

Upload the export file

On the second tab of the import module you can upload the export file to your target TYPO3 instance.

Select the file to upload (1) and click the Upload files button (2).

Then switch to the Import tab (3).

Configure the import settings

On the first tab of the import module you can configure the import.

First select the uploaded export file (1). Then adjust the general settings (2). Finally, press the Preview button (3).

• Checking Update records means that existing records with the same UID will be updated instead of newly inserted.
• Checking Do not show differences in records prevents calculation of differences between existing and imported records. Note: The compare function is currently broken and therefore disabled in the screenshot.

Review the data to be imported

A tree with the records to be imported is displayed below the configuration form (1). If you change any of the options (2), you can reload this preview with the Preview button (3).

Execute the import

Click the Import button to execute the import process.

Updating content using the TYPO3 backend

To update existing content without creating duplicates, check the option:

Import > Import Options > Update records

This ensures that records with matching UIDs are updated in place.

Saving a new preset

To save a new preset:

1. Go to Export > File & Preset > Presets.
2. Enter a Title of new preset (A.1).
3. Click Save (A.2).

Loading an existing preset

To load a saved preset:

1. Select the desired preset from Select Preset (B.1).
2. Click Load (B.2).

Modifying an existing preset

To modify an existing preset:

1. Load the preset as described above.
2. Make the required changes to the export settings.
3. Select the same preset again in Select Preset (!).
4. Click Save to overwrite the preset.

Managing preset visibility

Checking Public allows any TYPO3 backend user to load this preset. If left unchecked, only the creator can access the preset.

Exporting content from the command line

Export the entire TYPO3 page tree (or selected parts of it) to a data file of format XML or T3D:

vendor/bin/typo3 impexp:export [options] [--] [<filename>]

typo3/sysext/core/bin/typo3 impexp:export [options] [--] [<filename>]

With these options available:

Arguments:
    filename                             The filename to export to (without file extension)

Options:
    --type[=TYPE]                        The file type (xml, t3d, t3d_compressed). [default: "xml"]
    --pid[=PID]                          The root page of the exported page tree. [default: -1]
    --levels[=LEVELS]                    The depth of the exported page tree.
                                         "-2": "Records on this page", "0": "This page",
                                         "1": "1 level down", .. "999": "Infinite levels". [default: 0]
    --table[=TABLE]                      Include all records of this table.
                                         Examples: "_ALL", "tt_content", "sys_file_reference", etc.
                                         (multiple values allowed)
    --record[=RECORD]                    Include this specific record. Pattern is "{table}:{record}".
                                         Examples: "tt_content:12", etc. (multiple values allowed)
    --list[=LIST]                        Include records of this table and page. Pattern is "{table}:{pid}".
                                         Examples: "be_users:0", etc. (multiple values allowed)
    --include-related[=INCLUDE-RELATED]  Include record relations to this table, including the related record.
                                         Examples: "_ALL", "sys_category", etc. (multiple values allowed)
    --include-static[=INCLUDE-STATIC]    Include record relations to this table, excluding the related record.
                                         Examples: "_ALL", "be_users", etc. (multiple values allowed)
    --exclude[=EXCLUDE]                  Exclude this specific record. Pattern is "{table}:{record}".
                                         Examples: "fe_users:3", etc. (multiple values allowed)
    --exclude-disabled-records           Exclude records considered disabled by their TCA configuration,
                                         e.g. "disabled", "starttime", or "endtime" fields.
    --exclude-html-css                   Exclude referenced HTML and CSS files.
    --title[=TITLE]                      The meta title of the export.
    --description[=DESCRIPTION]          The meta description of the export.
    --notes[=NOTES]                      The meta notes of the export.
    --dependency[=DEPENDENCY]            Declare required TYPO3 extensions for the export.
                                         Examples: "news", "powermail", etc. (multiple values allowed)
    --save-files-outside-export-file     Save files in a separate folder named "{filename}.files"
                                         instead of embedding them in the export file.

Importing content from the command line

Import an export dump file in XML or T3D format into a TYPO3 instance:

vendor/bin/typo3 impexp:import [options] [--] <file> [<pid>]

typo3/sysext/core/bin/typo3 impexp:import [options] [--] <file> [<pid>]

With these options available:

Arguments:
    file                         The file path to import from (.t3d or .xml).
    pid                          The page to import to. [default: 0]

Options:
    --update-records             Update existing records with the same UID instead of inserting new ones.
    --ignore-pid                 Prevent page ID correction for updated records
                                 (requires --update-records).
    --force-uid                  Force UIDs from the file.
    --import-mode[=IMPORT-MODE]  Set the import mode for specific records.
                                 Pattern: "{table}:{record}={mode}".
                                 Modes:
                                 - For new records: "force_uid", "exclude"
                                 - For existing records: "as_new", "ignore_pid",
                                   "respect_pid", "exclude"
                                 Examples: "pages:987=force_uid", "tt_content:1=as_new",
                                           etc. (multiple values allowed)
    --enable-log                 Log all database actions.

Disable the extension when not in use

Exported content may contain sensitive and restricted information related to your site. It is recommended that this extension be deactivated when it is not in use to prevent content being exported in error.

Prevent unauthorized access

The export function is available by default for editors without admin rights. It is limited to content to which the editor has access. The export functionality can be hidden in the editor's context menu by using the user TSconfig setting contextMenu disableItems.

Note that it cannot be completely disabled as there are currently other entry points.

Secure the export directory

Exports are stored in fileadmin/user_upload/_temp_/importexport/. TYPO3 will automatically create a .htaccess file to prevent access to this folder from external sources. On Nginx webservers, the .htaccess file has no effect. Follow the Security guidelines for System Administrators to find out how to prevent access to specific directories on Nginx webservers.

Reporting a security issue

If you believe you have found a security-related issue that is not listed here, please contact the TYPO3 Security Team.