---
title: "Tutorial"
manual: "External Import"
version: "main"
permalink: "https://docs.typo3.org/permalink/cobweb/external_import:user-tutorial@main"
source: "User/Tutorial/Index.rst"
rendered: "2026-10-17T19:10:20+00:00"
---

# Tutorial {#user-tutorial}

Extension [externalimport_tut](https://docs.typo3.org/p/cobweb/externalimport_tut/main/en-us/Index.html#start) provides
an extensive tutorial about external import.
It makes use of many configuration options.
All examples are discussed in the extension's manual.

## Test extension {#user-tutorial-test}

Extension [externalimport_test](https://github.com/cobwebch/externalimport_test/)
also contains many example configurations which are use for integration (functional) testing.
The extension itself does not contain a detailed documentation like the tutorial,
but it is still a useful resource. The many scenarios and features covered in
that extension are briefly mentioned below to help you find your way around it.
It is structured according to the file names containing the TCA, either in
`Configuration/TCA`.

-   **tx_externalimporttest_bundle.php**

    Scenario: import of 1:n relationships (bundles to products) with denormalized data,
    preserving sorting order, using [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).

    Additional usage of: additional fields, user function transformations, array path (at column level).

-   **tx_externalimporttest_designer.php**

    Scenario: import data (designers) nested inside other data (products) in a XML structure using XPath
    ([nodepath](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-nodepath@main) property).

-   **tx_externalimporttest_invoice.php**

    Scenario: import denormalized data from a XML file with namespaced tags,
    using properties [namespaces](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-namespaces@main)
    and [fieldNS](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-fieldns@main).

-   **tx_externalimporttest_order.php**

    Scenario: import 1:n relationships (orders to products) from nested data into an
    IRRE structure. Usage of [arrayPath](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-arraypath@main) (at general level),
    [substructureFields](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-substructure-fields@main)
    and [children](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-children@main) properties.

-   **tx_externalimporttest_product.php**

    Products are used for testing several scenarios. They are described below
    according to the configuration key:

    -   **base**: usage of an EventListener (listening to `\Cobweb\ExternalImport\Event\ProcessConnectorParametersEvent`),
        of a custom step, of XPath at column level (property [xpath](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-xpath@main));
        creation of 1:n relations to tags from comma-separated values (property
        [multipleValuesSeparator](https://docs.typo3.org/permalink/cobweb/external_import:administration-mapping-properties-multiplevaluesseparator@main)) and creation of file references
        using both [substructureFields](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-substructure-fields@main)
        and [children](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-children@main) properties.
    -   **more**: simpler import scenario than "base", but from a siliar XML structure and thus
        the same mapping. Tests the usage of the [useColumnIndex](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-usecolumnindex@main)
        property.
    -   **stable**: same as "more", testing the disabling of both "update" and "delete" operations,
        using property [disabledOperations](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-disabledoperations@main).
    -   **products_for_stores**: creation of m:n relations between stores and products, from the
        product side. Again usage of the [children](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-children@main) property
        for creating IRRE entries.
    -   **general_configuration_errors**: as the name implies, this configuration contains many errors and is used
        for testing the general configuration validator.
    -   **updated_products**: importing products that change name (for testing the
        [updateSlugs](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-update-slugs@main) property)
        and also that change "pid" (for testing the moving of records).

-   **tx_externalimporttest_store.php**

    Scenario: import stores and their m:n relations to products, from the store side,
    again usage of the [children](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-children@main) property
    for creating IRRE entries.

-   **tx_externalimporttest_tag.php**

    Like products, tags are used to test several scenarios:

    -   **0**: usage of a custom step to filter out some entries.
    -   **only-delete**: this one is really specific to integration testing, as it is used
        to test the deletion of existing tags (loaded from a fixture during testing) when
        importing.
    -   **api**: tests the usage of External Import as an API. See class
        `\Cobweb\ExternalimportTest\Command\ImportCommand`.

-   **Overrides/pages.php**

    Scenario: importing some data (in this case products) as pages to test ordering
    and nesting (some pages are children of others). The configuration itself is very simple.

-   **Overrides/sys_category.php**

    Two scenarios are tested here:

    -   **product_categories**: simple import into an existing table, extending for storing the external id.
    -   **column_configuration_errors**: this configuration contains many errors and is used
        for testing the column configuration validator.

-   **Overrides/tx_externalimporttest_product.php**

    This is just used to demonstrate how to make a table categorizable and import categories relationships.
    It is related to the **"base"** configuration for products above.