--- title: "General TCA configuration" manual: "External Import" version: "main" permalink: "https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca@main" source: "Administration/GeneralTca/Index.rst" rendered: "2026-10-17T19:10:20+00:00" --- # General TCA configuration {#administration-general-tca} Here is an example of a typical general section syntax, containing two import configurations. Each configuration must be identified with a key (in the example below, `0` and `'api'`). The same keys need to be used again in the [column configuration](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns@main). ```php $GLOBALS['TCA']['tx_externalimporttest_tag'] = array_merge_recursive( $GLOBALS['TCA']['tx_externalimporttest_tag'], [ 'external' => [ 'general' => [ 0 => [ 'connector' => 'csv', 'parameters' => [ 'filename' => 'EXT:externalimport_test/Resources/Private/ImportData/Test/Tags.txt', 'delimiter' => ';', 'text_qualifier' => '"', 'encoding' => 'utf8', 'skip_rows' => 1 ], 'data' => 'array', 'referenceUid' => 'code', 'priority' => 5000, 'description' => 'List of tags' ], 'api' => [ 'data' => 'array', 'referenceUid' => 'code', 'description' => 'Tags defined via the import API' ] ] ], ]); ``` All available properties are described below. ## Properties {#administration-general-tca-properties} | Property | Data type | Scope/Step | | --- | --- | --- | | [additionalFields](https://docs.typo3.org/permalink/cobweb/external_import:additionalfields@main) | string | Read data | | [arrayPath](https://docs.typo3.org/permalink/cobweb/external_import:arraypath@main) | string | Handle data (array) | | [arrayPathFlatten](https://docs.typo3.org/permalink/cobweb/external_import:arraypathflatten@main) | bool | Handle data (array) | | [arrayPathSeparator](https://docs.typo3.org/permalink/cobweb/external_import:arraypathseparator@main) | string | Handle data (array) | | [clearCache](https://docs.typo3.org/permalink/cobweb/external_import:clearcache@main) | string | Clear cache | | [columnsOrder](https://docs.typo3.org/permalink/cobweb/external_import:columnsorder@main) | string | Transform data | | [connector](https://docs.typo3.org/permalink/cobweb/external_import:connector@main) | string | Read data | | [customSteps](https://docs.typo3.org/permalink/cobweb/external_import:customsteps@main) | array | Any step | | [data](https://docs.typo3.org/permalink/cobweb/external_import:data@main) | string | Read data | | [dataHandler](https://docs.typo3.org/permalink/cobweb/external_import:datahandler@main) | string | Handle data | | [description](https://docs.typo3.org/permalink/cobweb/external_import:description@main) | string | Display | | [disabled](https://docs.typo3.org/permalink/cobweb/external_import:disabled@main) | boolean | General | | [disabledOperations](https://docs.typo3.org/permalink/cobweb/external_import:disabledoperations@main) | string | Store data | | [disableLog](https://docs.typo3.org/permalink/cobweb/external_import:disablelog@main) | boolean | Store data | | [enforcePid](https://docs.typo3.org/permalink/cobweb/external_import:enforcepid@main) | boolean | Store data | | [groups](https://docs.typo3.org/permalink/cobweb/external_import:groups@main) | array | Sync process | | [minimumRecords](https://docs.typo3.org/permalink/cobweb/external_import:minimumrecords@main) | integer | Validate data | | [namespaces](https://docs.typo3.org/permalink/cobweb/external_import:namespaces@main) | array | Handle data (XML) | | [nodetype](https://docs.typo3.org/permalink/cobweb/external_import:nodetype@main) | string | Handle data (XML) | | [nodepath](https://docs.typo3.org/permalink/cobweb/external_import:nodepath@main) | string | Handle data (XML) | | [parameters](https://docs.typo3.org/permalink/cobweb/external_import:parameters@main) | array | Read data | | [pid](https://docs.typo3.org/permalink/cobweb/external_import:pid@main) | integer | Store data | | [priority](https://docs.typo3.org/permalink/cobweb/external_import:priority@main) | integer | Display/automated import | | [referenceUid](https://docs.typo3.org/permalink/cobweb/external_import:referenceuid@main) | string | Store data | | [updateSlugs](https://docs.typo3.org/permalink/cobweb/external_import:updateslugs@main) | boolean | Store data | | [useColumnIndex](https://docs.typo3.org/permalink/cobweb/external_import:usecolumnindex@main) | string or integer | Configuration | | [whereClause](https://docs.typo3.org/permalink/cobweb/external_import:whereclause@main) | string | Store data | ### connector {#administration-general-tca-properties-connector} - **Type** string - **Description** Connector service subtype. Must be defined only for pulling data. Leave blank for pushing data. You will need to install the relevant connector extension. Here is a list of available extensions and their corresponding types: | Type | Extension | | --- | --- | | csv | svconnector_csv | | json | svconnector_json | | sql | svconnector_sql | | feed | svconnector_feed | - **Scope** Read data ### parameters {#administration-general-tca-properties-parameters} - **Type** array - **Description** Array of parameters that must be passed to the connector service. Not used when pushing data. - **Scope** Read data ### data {#administration-general-tca-properties-data} - **Type** string - **Description** The format in which the data is returned by the connector service. Can be either `xml` or `array`. - **Scope** Read data ### dataHandler {#administration-general-tca-properties-datahandler} - **Type** string - **Description** A class name for replacing the standard data handlers. See the [Developer's Guide](https://docs.typo3.org/permalink/cobweb/external_import:developer@main) for more details. - **Scope** Handle data ### disabled {#administration-general-tca-properties-disabled} - **Type** bool - **Description** A disabled configuration is completely ignored by External Import. It does not appear in any listing, not will it ever by synchronized. This can be useful, for example, when you share a package between TYPO3 installations, but do not need to run the imports everywhere. - **Scope** General ### groups {#administration-general-tca-properties-groups} - **Type** array - **Description** Any External Import configuration may belong to one or more groups. A group is just an arbitrary string. It is possible to execute the synchronization of all configurations in a given group in one go, in order of priority (lowest goes first). Group synchronization is available on the command line and in the Scheduler task. - **Scope** Sync process ### nodetype {#administration-general-tca-properties-nodetype} - **Type** string - **Description** Name of the reference nodes inside the XML structure, i.e. the children of these nodes correspond to the data that goes into the database fields (see also the description of the [field](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-field@main) attribute). - **Scope** Handle data (XML) ### nodepath {#administration-general-tca-properties-nodepath} - **Type** string - **Description** XPath expression for selecting the reference nodes inside the XML structure. This is an alternative to the [nodetype](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-nodetype@main) property and will take precedence if both are defined. - **Scope** Handle data (XML) ### arrayPath {#administration-general-tca-properties-arraypath} - **Type** string - **Description** Pointer to a sub-array inside the incoming external data, as a list of keys separated by some marker. The sub-array pointed to will be used as the source of data in the subsenquent steps, rather than the whole structure that was read during the `ReadDataStep`. For more details on usage and available options, [see the dedicated page](https://docs.typo3.org/permalink/cobweb/external_import:administration-array-path@main). - **Scope** Handle data (array) ### arrayPathFlatten {#administration-general-tca-properties-arraypathflatten} - **Type** bool - **Description** When the special `*` segment is used in an [arrayPath](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-arraypath@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-general-tca-properties-arraypathseparator} - **Type** string - **Description** Separator to use in the [arrayPath](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-arraypath@main) property. Defaults to `/` if this property is not defined. - **Scope** Handle data (array) ### referenceUid {#administration-general-tca-properties-reference-uid} - **Type** string - **Description** Name of the column where the equivalent of a primary key for the external data is stored. Records for which this data does not exist are skipped (since version 6.1). This is tested with PHP's `isset()` function. If you think your data may contain empty values and you wish to skip them too, use the [isEmpty](https://docs.typo3.org/permalink/cobweb/external_import:administration-transformations-properties-isempty@main) transformation property with the `invalidate` option set to `true`. > [!IMPORTANT] > This is the name of a field in the TYPO3 CMS database, not in > the external data! It is the field where the reference > (or primary) key of the external data is stored. - **Scope** Store data ### priority {#administration-general-tca-properties-priority} - **Type** integer - **Description** A level of priority for the execution of the synchronization. Some tables may need to be synchronized before others if foreign relations are to be established. This gives a clue to the user and a strict order for scheduled synchronizations (either when synchronizing all configurations or when synchronizing a [group](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-groups@main)). The lowest priority value goes first. If priority is not defined, a default value of 1000 is applied (defined by class constant `CobwebExternalImportImporter::DEFAULT_PRIORITY`). Not used when pushing data. - **Scope** Display/Automated import process ### pid {#administration-general-tca-properties-pid} - **Type** string - **Description** ID of the page where the imported records should be stored. Can be ignored and the general storage pid is used instead ([see Configuration](https://docs.typo3.org/permalink/cobweb/external_import:installation-configuration@main)). - **Scope** Store data ### enforcePid {#administration-general-tca-properties-enforcepid} - **Type** boolean - **Description** If this is set to true, all operations regarding existing records will be limited to records stored in the defined pid (i.e. either the above property or the general extension configuration). This has two consequences: 1. when checking for existing records, those records will be selected only from the defined pid. 1. when checking for records to delete, only records from the defined pid will be affected This is a convenient way of protecting records from operations started from within the external import process, so that it won't affect e.g. records created manually. - **Scope** Store data ### useColumnIndex {#administration-general-tca-properties-usecolumnindex} - **Type** string or integer - **Description** In a basic configuration the same index must be used for the general TCA configuration and for each column configuration. With this property it is possible to use a different index for the column configurations. The general configuration part has to exist with its own index (say "index A"), but the columns may refer to another index (say "index B") and thus their configuration does not need to be defined. Obviously the index referred to ("index B") must exist for columns. The type may be a string or an integer, because a configuration key may also be either a string or an integer. Since version 6.1, it is possible to define specific configurations for selected columns using the index from the general configuration ("index A"). It will not be overridden by the configuration corresponding to the index referred to with `useColumnIndex` property ("index B"). Example: ```php 'stable' => [ 'connector' => 'feed', 'parameters' => [ 'uri' => 'EXT:externalimport_test/Resources/Private/ImportData/Test/StableProducts.xml', 'encoding' => 'utf8' ], 'groups' => [ 'Products', ], 'data' => 'xml', 'nodetype' => 'products', 'referenceUid' => 'sku', 'priority' => 5120, 'useColumnIndex' => 'base', ... ], ``` This general configuration makes reference to the "base" configuration. This means that all columns will use the "base" configuration, unless they have a configuration using specifically the "stable" index. So the "sku" column will use the configuration from the "base" index: ```php 'sku' => [ 'exclude' => false, 'label' => 'SKU', 'config' => [ 'type' => 'input', 'size' => 10 ], 'external' => [ 'base' => [ 'xpath' => './self::*[@type="current"]/item', 'attribute' => 'sku' ], 'products_for_stores' => [ 'field' => 'product' ], 'updated_products' => [ 'field' => 'product_sku' ] ] ], ``` However, the "name" column has a specific configuration corresponding to the "stable" index, so it will be used, and not the configuration from the "base" index: ```php 'name' => [ 'exclude' => false, 'label' => 'Name', 'config' => [ 'type' => 'input', 'size' => 30, 'eval' => 'required,trim', ], 'external' => [ 'base' => [ 'xpath' => './self::*[@type="current"]/item', ], 'stable' => [ 'xpath' => './self::*[@type="current"]/item', 'transformations' => [ 10 => [ 'userFunction' => [ 'class' => \Cobweb\ExternalimportTest\UserFunction\Transformation::class, 'method' => 'caseTransformation', 'parameters' => [ 'transformation' => 'upper' ] ] ] ] ], 'updated_products' => [ 'field' => 'name' ] ] ], ``` - **Scope** Configuration ### columnsOrder {#administration-general-tca-properties-columnsorder} - **Type** string - **Description** By default, columns (regular columns or additional fields) are handled in alphabetical order whenever a loop is performed on all columns (typically in the `\Cobweb\ExternalImport\Step\TransformDataStep` class). This can be an issue when you need a specific column to be handled before another one. With this property, you can define a comma-separated list of columns, that will be handled in that specific order. It is not necessary to define an order for all columns. If only some columns are explicitly ordered, the rest will be handled after the ordered ones, in alphabetical order. The order is visually reflected in the backend module, when viewing the [configuration details](https://docs.typo3.org/permalink/cobweb/external_import:user-backend-module-synchronizable-details@main). - **Scope** Transform data (essentially) ### customSteps {#administration-general-tca-properties-customsteps} - **Type** array - **Description** As explained in the [process overview](https://docs.typo3.org/permalink/cobweb/external_import:user-overview@main), the import process goes through several steps, depending on its type. This property makes it possible to register additional steps. Each step can be placed before or after any existing step (including previously registered custom steps). The configuration is a simple array, each entry being itself an array with three properties: - **class (required)**: name of the PHP class containing the custom step. - **position (required)**: states when the new step should happen. The syntax for position is made of the keyword `before` or `after`, followed by a colon (`:`) and the name of an existing step class. - **parameters (optional)**: array which is passed as is to the custom step class when it is called during the import process. Inside the step, it can be accessed using `$this->parameters`. Example: ```php 'customSteps' => [ [ 'class' => \Cobweb\ExternalimportTest\Step\EnhanceDataStep::class, 'position' => 'after:' . \Cobweb\ExternalImport\Step\ValidateDataStep::class ] ], ``` If any element of the custom step declaration is invalid, the step will be ignored. More information is given in the [Developer's Guide](https://docs.typo3.org/permalink/cobweb/external_import:developer-steps@main). - **Scope** Any step ### whereClause {#administration-general-tca-properties-where-clause} - **Type** string - **Description** SQL condition that will restrict the records considered during the import process. Only records matching the condition will be updated or deleted. This condition comes on top of the "enforcePid" condition, if defined. > [!WARNING] > This may cause many records to be inserted over time. > Indeed if some external data is imported the first time, but then > doesn't match the `whereClause` condition, it will never be found > for update. It will thus be inserted again and again. Whenever you > make use of the `whereClause` property you should therefore watch > for an unexpectedly high number of inserts. - **Scope** Store data ### additionalFields {#administration-general-tca-properties-additional-fields} - **Type** string - **Description** This property is not part of the general configuration anymore. Please refer to [the dedicated chapter](https://docs.typo3.org/permalink/cobweb/external_import:administration-additionalfields@main). - **Scope** Read data ### updateSlugs {#administration-general-tca-properties-update-slugs} - **Type** boolean - **Description** Slugs are populated automatically for new records thanks to External Import relying on the `\TYPO3\CMS\Core\DataHandling\DataHandler` class. The same is not true for updated records. If you want record slugs to be updated when modified external data is imported, set this flag to `true`. - **Scope** Store data ### namespaces {#administration-general-tca-properties-namespaces} - **Type** array - **Description** Associative array of namespaces that can be used in [XPath queries](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-xpath@main). The keys correspond to prefixes and the values to URIs. The prefixes can then be used in XPath queries. **Example** Given the following declaration: ```php 'namespaces' => array( 'atom' => 'http://www.w3.org/2005/Atom' ) ``` a Xpath query like: ```text atom:link ``` could be used. The prefixes used for XPath queries don't need to match the prefixes used in the actual XML source. The defaut namespace has to be registered too in order for XPath queries to succeed. - **Scope** Handle data (XML) ### description {#administration-general-tca-properties-description} - **Type** string - **Description** A purely descriptive piece of text, which should help you remember what this particular synchronization is all about. Particularly useful when a table is synchronized with multiple sources. - **Scope** Display ### disabledOperations {#administration-general-tca-properties-disabledoperations} - **Type** string - **Description** Comma-separated list of operations that should **not** be performed. Possible operations are insert, update and delete. This way you can block any of these operations. - **insert** The operation performed when new records are found in the external source. - **update** Performed when a record already exists and only its data needs to be updated. - **delete** Performed when a record is in the database, but is not found in the external source anymore. See also the column-specific property [disabledOperations](https://docs.typo3.org/permalink/cobweb/external_import:administration-columns-properties-disabledoperations@main). - **Scope** Store data ### minimumRecords {#administration-general-tca-properties-minimumrecords} - **Type** integer - **Description** Minimum number of items expected in the external data. If fewer items are present, the import is aborted. This can be used – for example – to protect the existing data against deletion when the fetching of the external data failed (in which case there are no items to import). - **Scope** Validate data ### disableLog {#administration-general-tca-properties-disablelog} - **Type** integer - **Description** Set to `true` to disable logging by the TYP3 Core Engine. This setting will override the general "Disable logging" setting (see [Configuration for more details](https://docs.typo3.org/permalink/cobweb/external_import:installation-configuration@main)). - **Scope** Store data ### clearCache {#administration-general-tca-properties-clearcache} - **Type** string - **Description** Comma-separated list of caches identifiers for caches which should be cleared at the end of the import process. See [Clearing the cache](https://docs.typo3.org/permalink/cobweb/external_import:user-clear-cache@main). - **Scope** Clear cache