--- title: "Columns configuration" manual: "External Import" version: "main" permalink: "https://docs.typo3.org/permalink/cobweb/external_import:administration-columns@main" source: "Administration/Columns/Index.rst" rendered: "2026-10-17T19:10:20+00:00" --- # Columns configuration {#administration-columns} You also need an "external" syntax for each column to define which external data goes into that column and any handling that might apply. This is also an indexed array. Obviously indices used for each column must relate to the indices used in the [general configuration](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca@main). In its simplest form this is just a reference to the external data's name: ```php 'code' => [ 'exclude' => 0, 'label' => 'LLL:EXT:externalimport_tut/locallang_db.xml:tx_externalimporttut_departments.code', 'config' => [ 'type' => 'input', 'size' => 10, 'max' => 4, 'eval' => 'required,trim', ], 'external' => [ 0 => [ 'field' => 'code' ] ] ], ``` The properties for the columns configuration are described below. > [!WARNING] > Columns "crdate", "tstamp" and "cruser_id" cannot be mapped as they are overwritten by the > `DataHandler`. If you need to manipulate these columns you should use the > [Datamap Postprocess event](https://docs.typo3.org/permalink/cobweb/external_import:developer-events-datamap-postprocess@main) or the > [Cmdmap Postprocess event](https://docs.typo3.org/permalink/cobweb/external_import:developer-events-cmdmap-postprocess@main) > which are triggered after `DataHandler` operations. > [!TIP] > **Hint** > > You can set static values by using the [transformation > value](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-value@main). ## Properties {#administration-columns-properties} | Property | Data type | Step/Scope | | --- | --- | --- | | [arrayPath](https://docs.typo3.org/permalink/cobweb/external_import:arraypath@main) | string | Handle data (array) | | [arrayPathSeparator](https://docs.typo3.org/permalink/cobweb/external_import:arraypathseparator@main) | string | Handle data (array) | | [arrayPathFlatten](https://docs.typo3.org/permalink/cobweb/external_import:arraypathflatten@main) | bool | Handle data (array) | | [attribute](https://docs.typo3.org/permalink/cobweb/external_import:attribute@main) | string | Handle data (XML) | | [attributeNS](https://docs.typo3.org/permalink/cobweb/external_import:attributens@main) | string | Handle data (XML) | | [children](https://docs.typo3.org/permalink/cobweb/external_import:children@main) | [Children records configuration](https://docs.typo3.org/permalink/cobweb/external_import:administration-children@main) | Store data | | [disabledOperations](https://docs.typo3.org/permalink/cobweb/external_import:disabledoperations@main) | string | Store data | | [field](https://docs.typo3.org/permalink/cobweb/external_import:field@main) | string | Handle data | | [fieldNS](https://docs.typo3.org/permalink/cobweb/external_import:fieldns@main) | string | Handle data (XML) | | [multipleRows](https://docs.typo3.org/permalink/cobweb/external_import:multiplerows@main) | boolean | Store data | | [multipleSorting](https://docs.typo3.org/permalink/cobweb/external_import:multiplesorting@main) | string | Store data | | [substructureFields](https://docs.typo3.org/permalink/cobweb/external_import:substructurefields@main) | array | Handle data | | [transformations](https://docs.typo3.org/permalink/cobweb/external_import:transformations@main) | [Transformations configuration](https://docs.typo3.org/permalink/cobweb/external_import:administration-transformations@main) | Transform data | | [value](https://docs.typo3.org/permalink/cobweb/external_import:value@main) | Simple type (string, integer, float, boolean) | Handle data | | [xmlValue](https://docs.typo3.org/permalink/cobweb/external_import:xmlvalue@main) | boolean | Handle data (XML) | | [xpath](https://docs.typo3.org/permalink/cobweb/external_import:xpath@main) | string | Handle data (XML) | ### value {#administration-columns-properties-value} - **Type** Simple type (string, integer, float, boolean) - **Description** Sets a fixed value, independent of the data being imported. For example, this might be used to set a flag for all imported records. Or you might want to use different types for different import sources. This can be used for both array-type and XML-type data. - **Scope** Handle data ### field {#administration-columns-properties-field} - **Type** string - **Description** Name or index of the field (or node, in the case of XML data) that contains the data in the external source. For array-type data, this information is mandatory. For XML-type data, it can be left out. In such a case, the value of the current node itself will be used, or an attribute of said node, if the [attribute](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-attribute@main) property is also defined. - **Scope** Handle data ### arrayPath {#administration-columns-properties-array-path} - **Type** string - **Description** Replaces the [field](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-field@main) property for pointing to a field in a "deeper" position inside a multidimensional array. The value is a string comprised of the keys for pointing into the array, separated by some character. For more details on usage and available options, [see the dedicated page](https://docs.typo3.org/permalink/cobweb/external_import:administration-array-path@main). Works only for array-type data. If both "field" and "arrayPath" are defined, the latter takes precedence. - **Scope** Handle data (array) ### arrayPathFlatten {#administration-columns-properties-arraypathflatten} - **Type** bool - **Description** When the special `*` segment is used in an [arrayPath](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-array-path@main), the resulting structure is always an array. If the `arrayPath` target is actually a single value, this may not be desirable. When `arrayPathFlatten` is set to `true`, the result is preserved as a simple type. > [!NOTE] > If the `arrayPath` property uses the special `*` segment several times, > `arrayPathFlatten` will apply only to the last occurrence. The reason is that > the method which traverses the array structure is called recursively on each `*` segment. > When the result of the final call is flattened, a simple type is returned back up the > call chain, which means that `arrayPathFlatten` has no further effect. - **Scope** Handle data (array) ### arrayPathSeparator {#administration-columns-properties-array-path-separator} - **Type** string - **Description** Separator to use in the [arrayPath](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-array-path@main) property. Defaults to `/` if this property is not defined. - **Scope** Handle data (array) ### attribute {#administration-columns-properties-attribute} - **Type** string - **Description** If the data is of type XML, use this property to retrieve the value from an attribute of the node rather than the value of the node itself. This applies to the node selected with the [field](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-field@main) property or to the current node if [field](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-field@main) is not defined. - **Scope** Handle data (XML) ### xpath {#administration-columns-properties-xpath} - **Type** string - **Description** This property can be used to execute a XPath query relative to the node selected with the [field](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-field@main) property or (since version 2.3.0) directly on the current node if [field](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-field@main) is not defined. The value will be taken from the first node returned by the query. If the [attribute](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-attribute@main) property is also defined, it will be applied to the node returned by the XPath query. If the XPath query is just a function (without selector), the resulting string will be returned. Please see the [namespaces](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-namespaces@main) property for declaring namespaces to use in a XPath query. - **Scope** Handle data (XML) ### fieldNS {#administration-columns-properties-fieldns} - **Type** string - **Description** Namespace for the given field. Use the full URI for the namespace, not a prefix. **Example** Given the following data to import: ```xml A1 100.00 000001 ... ``` getting the value in the `` tag would require the following configuration: ```php 'external' => [ 0 => [ 'fieldNS' => 'urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2', 'field' => 'LineExtensionAmount' ] ] ``` - **Scope** Handle data (XML) ### attributeNS {#administration-columns-properties-attributens} - **Type** string - **Description** Namespace for the given attribute. Use the full URI for the namespace, not a prefix. See [fieldNS](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-fieldns@main) for example usage. - **Scope** Handle data (XML) ### substructureFields {#administration-columns-properties-substructure-fields} - **Type** array - **Description** Makes it possible to read several values that are located inside nested data structures, creating one row per element in the nested structure. The configuration is an associative array where the keys correspond to the names of the columns where the values must be stored. The configuration for each element can use all the existing properties for retrieving data: - [field](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-field@main) - [fieldNS](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-fieldns@main) - [arrayPath](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-array-path@main) - [arrayPathSeparator](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-array-path-separator@main) - [attribute](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-attribute@main) - [attributeNS](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-attributens@main) - [xpath](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-xpath@main) - [xmlValue](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-xmlvalue@main) The substructure fields are searched for inside the structure selected for the column itself. Since this process generally creates several rows, you probably want to use this property in conjunction with the [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. > [!WARNING] > Correctly using this property is not trivial. Please read > [the full example](https://docs.typo3.org/permalink/cobweb/external_import:import-configuration-examples-substructure-children@main) provided in this manual > as a complement to the description above. - **Scope** Handle data ### multipleRows {#administration-columns-properties-multiple-rows} - **Type** boolean - **Description** Set to `true` if you have denormalized data. This will tell the import process that there may be more than one row per record to import and that all values for the given column must be gathered and collapsed into a comma-separated list of values. See the [Mapping data](https://docs.typo3.org/permalink/cobweb/external_import:user-mapping-data@main) chapter for explanations about the impact of this flag. If these values need to be sorted, use the [multipleSorting](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-multiple-sorting@main) property. - **Scope** Store data ### multipleSorting {#administration-columns-properties-multiple-sorting} - **Type** string - **Description** If the [multipleRows](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-multiple-rows@main) need to be sorted, use this property to name the field which should be used for sorting. This can be any of the mapped fields, additional fields or substructure fields. > [!NOTE] > The sorting is done using the PHP function `strnatcasecmp()`, so make sure > that your data plays well with it. - **Scope** Store data ### children {#administration-columns-properties-children} - **Type** array (see [Children records configuration](https://docs.typo3.org/permalink/cobweb/external_import:administration-children@main)) - **Description** This property makes it possible to create nested structures and import them in one go. This may typically be "sys_file_reference" records for a field containing images. This should be used anytime you are using a MM table into which you need to write specific properties (like "sys_file_reference"). For simple MM tables (like "sys_category_record_mm"), you don't need to create this children sub-structure for the MM table. It is enough to gather a comma-separated list of "sys_category" primary keys. - **Scope** Store data ### transformations {#administration-columns-properties-transformations} - **Type** array (see [Transformations configuration](https://docs.typo3.org/permalink/cobweb/external_import:administration-transformations@main)) - **Description** Array of transformation properties. The transformations will be executed as ordered by their array keys. **Example:** ```php $GLOBALS['TCA']['fe_users']['columns']['starttime']['external'] = [ 0 => [ 'field' => 'start_date', 'transformations' => [ 20 => [ 'trim' => true ], 10 => [ 'userFunction' => [ 'class' => \Cobweb\ExternalImport\Transformation\DateTimeTransformation::class, 'method' => 'parseDate' ] ] ] ] ]; ``` The "userFunction" will be executed first (`10`) and the "trim" next (`20`). - **Scope** Transform data ### xmlValue {#administration-columns-properties-xmlvalue} - **Type** boolean - **Description** When taking the value of a node inside a XML structure, the default behaviour is to retrieve this value as a string. If the node contained a XML sub-structure, its tags will be stripped. When setting this value to `true`, the XML structure of the child nodes is preserved. - **Scope** Handle data (XML) ### disabledOperations {#administration-columns-properties-disabledoperations} - **Type** array - **Description** Comma-separated list of database operations from which the column should be excluded. Possible values are "insert" and "update". See also the general property [disabledOperations](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-disabledoperations@main). - **Scope** Store data