Events

Several events are triggered during the external import process in order to provide entry points for custom actions, improving the flexibility of the whole tool. Some events are not triggered when running in preview mode.

All events may throw the special exception \Cobweb\ExternalImport\Exception\CriticalFailureException. This will cause their "parent" step to abort. More details in the chapter about critical exceptions. Any other exception will just be logged (depending on your logging configuration).

For usage, see the core documentation about PSR-14 events.

Change configuration before run

class ChangeConfigurationBeforeRunEvent

Fully qualified name: \Cobweb\ExternalImport\Event\ChangeConfigurationBeforeRunEvent

This event makes it possible to change the External Import at run-time, just before any of the import steps are executed. Since the \Cobweb\ExternalImport\Domain\Model\Configuration model class does not have accessor methods for every single property of the External Import configuration, it is not possible to change a single property.

Basically, the \Cobweb\ExternalImport\Domain\Model\Configuration object keeps a copy of the general configuration, the additional fields configuration and the columns configuration. The best way to change any of them is to retrieve that raw copy, modify it and set it again using the accessor methods provided by the event.

getImporter ( ): Current instance of \Cobweb\ExternalImport\Importer.

getConfiguration ( ): Current instance of \Cobweb\ExternalImport\Domain\Model\Configuration.

setGeneralConfiguration ( ): Used to set the modified version of the general configuration, previously retrieved using $this->getConfiguration()->getRawGeneralConfiguration().

setAdditionalFieldsConfiguration ( ): Used to set the modified version of the additional fields configuration, previously retrieved using $this->getConfiguration()->getRawAdditionalFieldsConfiguration().

setColumnsConfiguration ( ): Used to set the modified version of the columns configuration, previously retrieved using $this->getConfiguration()->getRawColumnsConfiguration().

Process connector parameters

class ProcessConnectorParametersEvent

Fully qualified name: \Cobweb\ExternalImport\Event\ProcessConnectorParametersEvent

This allows for dynamic manipulation of the parameters array before it is passed to the connector.

Note

This event is also triggered when displaying the configuration in the BE module. This way the user can see how the processed parameters look like.

getParameters ( ): Returns the connector parameters.

setParameters ( array $parameters): Sets the (modified) connector parameters.

getExternalConfiguration ( ): Instance of \Cobweb\ExternalImport\Domain\Model\Configuration with the current import configuration.

Substructure Preprocess

class SubstructurePreprocessEvent

Fully qualified name: \Cobweb\ExternalImport\Event\SubstructurePreprocessEvent

This event is triggered whenever a data structure is going to be handled by the substructureFields property. It is fired just before the directives defined in the substructureFields property are applied and makes it possible to change the substructure.

getSubstructureConfiguration ( ): Returns the corresponding substructureFields configuration.

getColumn ( ): Returns the name of the column being handled.

getDataType ( ): Returns the type of data being handled ("array" or "xml").

getStructure ( ): Returns the structure being handled.

setStructure ( mixed $structure): Sets the (modified) structure. This must be an array for array-type data or a \DomNodeList for XML-type data. Check the incoming type using the getDataType() method.

getImporter ( ): Current instance of \Cobweb\ExternalImport\Importer.

Update Record Preprocess

class UpdateRecordPreprocessEvent

Fully qualified name: \Cobweb\ExternalImport\Event\UpdateRecordPreprocessEvent

This event is triggered just before a record is registered for update in the database. It is triggered for each record individually.

The event may throw the special exception \Cobweb\ExternalImport\Exception\InvalidRecordException, in which case the record will be removed from the dataset to be saved.

Note

This event listener receives records only from the main table, not from any child table.

getUid ( ): Returns the primary key of the record (since we are talking about an update operation, the record exists in the database and thus has a valid primary key).

getRecord ( ): Returns the record being handled.

setRecord ( array $record): Sets the (modified) record.

getImporter ( ): Current instance of \Cobweb\ExternalImport\Importer.

Insert Record Preprocess

class InsertRecordPreprocessEvent

Fully qualified name: \Cobweb\ExternalImport\Event\InsertRecordPreprocessEvent

Similar to the "Update Record Preprocess" event above, but for the insert operation. It may also throw \Cobweb\ExternalImport\Exception\InvalidRecordException.

Note

This event listener receives records only from the main table, not from any child table.

Delete Record Preprocess

class DeleteRecordsPreprocessEvent

Fully qualified name: \Cobweb\ExternalImport\Event\DeleteRecordsPreprocessEvent

This event is triggered just before any record is deleted. It can manipulate the list of primary keys of records that will eventually be deleted.

Note that even if this event throws the \Cobweb\ExternalImport\Exception\CriticalFailureException, the data to update or insert will already have been saved.

getRecords ( ): Returns the list of records to be deleted (primary keys).

Note

This list of contains only records from the main table, not from any child table.

setRecords ( array $records): Sets the (modified) list of records.

getImporter ( ): Current instance of \Cobweb\ExternalImport\Importer.

Datamap Postprocess

class DatamapPostprocessEvent

Fully qualified name: \Cobweb\ExternalImport\Event\DatamapPostprocessEvent

This event is triggered after all records have been updated or inserted using the TYPO3 Core Engine. It can be used for any follow-up operation. The event has the following API:

Note that even if this event throws the \Cobweb\ExternalImport\Exception\CriticalFailureException, the data to update or insert will already have been saved.

Note

This event is not triggered in preview mode.

getData ( ): Returns the list of records keyed to their primary keys (including the new primary keys for the inserted records). Each record contains an additional field called tx_externalimport:status with a value of either "insert" or "update" depending on which operation was performed on the record.

Warning

This structure is one-dimensional, which is buggy when multiple tables are handled by the import (when using the "children" property), because records with the same primary key will override each other. Use getStructuredData() instead. Don't use getData() anymore, it will be dropped in the future.

getStructuredData ( )

Returns the list of tables and their records keyed to their primary keys (including the new primary keys for the inserted records). Each record contains an additional field called tx_externalimport:status with a value of either "insert" or "update" depending on which operation was performed on the record. Example:

[
    'pages' => [
        23 => [
            'title' => 'Page title'
        ],
    ],
    'sys_file_reference' => [
        47 => [
            'title' => 'Page image'
        ],
    ],
]

getImporter ( ): Current instance of \Cobweb\ExternalImport\Importer.

Cmdmap Postprocess

class CmdmapPostprocessEvent

Fully qualified name: \Cobweb\ExternalImport\Event\CmdmapPostprocessEvent

This event is triggered after all records have been deleted using the TYPO3 Core Engine. The event has the following API:

Note that even if this event throws the \Cobweb\ExternalImport\Exception\CriticalFailureException, the records will already have been deleted.

Note

This event is not triggered in preview mode.

getData ( ): Returns the list of primary keys of the deleted records.

getImporter ( ): Current instance of \Cobweb\ExternalImport\Importer.

Report

class ReportEvent

Fully qualified name: \Cobweb\ExternalImport\Event\ReportEvent

This event is triggered in the ReportEvent step. It allows for custom reporting. It also triggers the reporting webhook.

getImporter ( ): Current instance of \Cobweb\ExternalImport\Importer.

Report

class GetExternalKeyEvent

Fully qualified name: \Cobweb\ExternalImport\Event\GetExternalKeyEvent

This event is not related to the import process. It is triggered by the "Delete external data" reaction. It makes it possible to retrieve the key to the external data, if it is not stored in the "external_id" field as expected.

getConfiguration ( ): Instance of \Cobweb\ExternalImport\Domain\Model\Configuration with the targeted configuration.

getData ( ): An array with the data for the item to delete.

getExternalKey ( ): Value of the external key before the event is fired. It will be null if the key was not found as expected.

setExternalKey ( ): Use this method to set the value of the external key, once you have performed your custom processing of the data.