---
title: "Mapping configuration"
manual: "External Import"
version: "main"
permalink: "https://docs.typo3.org/permalink/cobweb/external_import:administration-mapping@main"
source: "Administration/Mapping/Index.rst"
rendered: "2026-10-17T19:10:20+00:00"
---

# Mapping configuration {#administration-mapping}

The external values can be matched to values from an existing
TYPO3 CMS table, using the "mapping" property, which has its own
set of properties. They are described below.

## Properties {#administration-mapping-properties}

| Property | Data type |
| --- | --- |
| [default](https://docs.typo3.org/permalink/cobweb/external_import:default@main) | mixed |
| [matchMethod](https://docs.typo3.org/permalink/cobweb/external_import:matchmethod@main) | string |
| [matchSymmetric](https://docs.typo3.org/permalink/cobweb/external_import:matchsymmetric@main) | boolean |
| [multipleValuesSeparator](https://docs.typo3.org/permalink/cobweb/external_import:multiplevaluesseparator@main) | string |
| [referenceField](https://docs.typo3.org/permalink/cobweb/external_import:referencefield@main) | string |
| [table](https://docs.typo3.org/permalink/cobweb/external_import:table@main) | string |
| [valueField](https://docs.typo3.org/permalink/cobweb/external_import:valuefield@main) | string |
| [valueMap](https://docs.typo3.org/permalink/cobweb/external_import:valuemap@main) | array |
| [whereClause](https://docs.typo3.org/permalink/cobweb/external_import:whereclause@main) | string |

### table {#administration-mapping-properties-table}

-   **Type**

    string

-   **Description**

    Name of the table to read the mapping data from.

-   **Scope**

    Transform data

### referenceField {#administration-mapping-properties-reference-field}

-   **Type**

    string

-   **Description**

    Name of the field against which external values must be matched.

    > [!NOTE]
    > SQL functions may be used here. Example: `'CONCAT(first_name, \' \', last_name)'`.

-   **Scope**

    Transform data

### valueField {#administration-mapping-properties-value-field}

-   **Type**

    string

-   **Description**

    Name of the field to take the mapped value from. If not defined, this
    will default to "uid".

    > [!NOTE]
    > SQL functions may be used here. Example: `'CONCAT(first_name, \' \', last_name)'`.

-   **Scope**

    Transform data

### whereClause {#administration-mapping-properties-where-clause}

-   **Type**

    string

-   **Description**

    SQL condition (without the "WHERE" keyword) to apply to the referenced
    table. This is typically meant to be a mirror of the
    [foreign_table_where](https://docs.typo3.org/m/typo3/reference-tca/14.3/en-us/ColumnsConfig/Type/Select/Single/Index.html#columns-select-properties-foreign-table-where)
    property of select-type fields.

    However only one marker is supported in this case: `###PID_IN_USE###`
    which will be replaced by the current storage pid. So if you have
    something like:

    ```php
    'foreign_table_where' => 'AND pid = ###PAGE_TSCONFIG_ID###'
    ```

    in the TCA for your column, you should replace the marker by a hard-
    coded value instead for external import, e.g.

    ```php
    'whereClause' => 'pid = 42'
    ```

    > [!IMPORTANT]
    > The clause must start with neither the "WHERE", nor the "AND" keyword.

-   **Scope**

    Transform data

### default {#administration-mapping-properties-default}

-   **Type**

    mixed

-   **Description**

    Default value that will be used when a value cannot be mapped. Otherwise the field is unset for the record.

    > [!NOTE]
    > This is quite important when mapping MM relations. If an existing item has currently relations in the
    > TYPO3 database, but not any longer in the data to be imported, the existing MM relations will not be
    > removed if the field is unset. In such a case, make sure to use an empty string for the default value,
    > as this will tell the DataHandler that it has to remove the existing MM relations.
    >
    > **Example**
    >
    > ```php
    > $GLOBALS['TCA']['tx_externalimporttest_product']['columns']['categories']['external']['base'] = [
    >      'xpath' => './self::*[@type="current"]/category',
    >      'transformations' => [
    >           10 => [
    >                'mapping' => [
    >                     'table' => 'sys_category',
    >                     'referenceField' => 'external_key',
    >                     'default' => ''
    >                ]
    >           ]
    >      ]
    > ];
    > ```

-   **Scope**

    Transform data

### valueMap {#administration-mapping-properties-valuemap}

-   **Type**

    array

-   **Description**

    Fixed hash table for mapping. Instead of using a database table to
    match external values to internal values, this property makes it
    possible to use a simple list of key-value pairs. The keys correspond
    to the external values.

-   **Scope**

    Transform data

### multipleValuesSeparator {#administration-mapping-properties-multiplevaluesseparator}

-   **Type**

    string

-   **Description**

    Set this property if the field to map contains several values,
    separated by some symbol (for example, a comma). The values will
    be split using the symbol defined in this property and each resulting
    value will go through the mapping process.

    This makes it possible to handle 1:n or m:n relations, where the
    incoming values are all stored in the same field.

    > [!NOTE]
    > This property does nothing when used in combination with the
    > MM property, because we expect normalized
    > data with one and denormalized data with the other. The chapter about
    > [mapping data](https://docs.typo3.org/permalink/cobweb/external_import:user-mapping-data@main) hopefully helps understand this.

-   **Scope**

    Transform data

### matchMethod {#administration-mapping-properties-match-method}

-   **Type**

    array

-   **Description**

    Value can be "strpos" or "stripos".

    Normally mapping values are matched based on a strict equality. This
    property can be used to match in a "softer" way. It will match if the
    external value is found inside the values pointed to by the
    [referenceField](https://docs.typo3.org/permalink/cobweb/external_import:administration-mapping-properties-reference-field@main)
    property. "strpos" will perform a case-sensitive
    matching, while "stripos" is case-unsensitive.

    Caution should be exercised when this property is used. Since the
    matching is less strict it may lead to false positives. You should
    review the data after such an import.

    > [!NOTE]
    > It is important to understand how the `matchMethod` property
    > influences the matching process. Consider trying to map freely input
    > country names to the `static_countries` table inside TYPO3 CMS.
    > This may not be so easy depending on how names were input in the
    > external data. For example, "Australia" will not strictly match the
    > official name, which is "Commonwealth of Australia". However setting
    > `matchMethod` to "strpos" will generate a match, since "Australia"
    > can be found inside "Commonwealth of Australia"

-   **Scope**

    Transform data

### matchSymmetric {#administration-mapping-properties-match-symmetric}

-   **Type**

    boolean

-   **Description**

    This property complements [matchMethod](https://docs.typo3.org/permalink/cobweb/external_import:administration-mapping-properties-match-method@main).
    If set to `true`, the import process will not only
    try to match the external value inside the mapping values,
    but also the reverse, i.e. the mapping values
    inside the external value.

-   **Scope**

    Transform data

## Examples {#administration-mapping-example}

### Simple mapping {#administration-mapping-example-simple}

Here's an example TCA configuration.

```php
$GLOBALS['TCA']['fe_users']['columns']['tx_externalimporttut_department']['external'] = [
    0 => [
        'field' => 'department',
        'mapping' => [
            'table' => 'tx_externalimporttut_departments',
            'referenceField' => 'code'
        ]
    ]
];
```

The value found in the "department" field of the external data
will be matched to the "code" field of the "tx_externalimporttut_departments" table,
and thus create a relation between the "fe_users" and the
"tx_externalimporttut_departments" table.

### Mapping multiple values {#administration-mapping-example-multiple}

This second example demonstrates usage of the
[multipleValuesSeparator](https://docs.typo3.org/permalink/cobweb/external_import:administration-mapping-properties-multiplevaluesseparator@main)
property.

The incoming data looks like:

```xml
<catalogue>
    <products type="current">
        <item sku="000001">Long sword</item>
        <tags>attack,metal</tags>
    </products>
    <products type="obsolete">
        <item index="000002">Solar cream</item>
    </products>
    <products type="current">
        <item sku="000005">Chain mail</item>
        <tags>defense,metal</tags>
    </products>
    <item sku="000014" type="current">Out of structure</item>
</catalogue>
```

and the external import configuration like:

```php
$GLOBALS['TCA']['tx_externalimporttest_product']['columns']['tags']['external'] = [
  'base' => [
      'xpath' => './self::*[@type="current"]/tags',
      'transformations' => [
           10 => [
                'mapping' => [
                     'table' => 'tx_externalimporttest_tag',
                     'referenceField' => 'code',
                     'multipleValuesSeparator' => ','
                ]
           ]
      ]
  ]
];
```

The values in the `<tags>` nodes will be split on the
comma and each will be matched to a tag from "tx_externalimporttest_tag"
table, using the "code" field for matching.

This example is taken from the "externalimport_test" extension.