Hooks

The external import process contains many hooks for improved flexibility. They are described below. When running in preview mode some hooks are not called.

Note

Since External Import version 4.0.0, custom process steps are available. In general, they are far more powerful than hooks, although hooks cover specific scenarios which custom steps can’t. No hook has been deprecated, but a notice has beed added to their description for those that could be replaced by custom steps.

Some hooks 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. Which hooks may do this is mentioned below.

processParameters

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

Example

Let’s assume that you are using the CSV connector and that you would like the filename to automatically adjust to the current year. Your parameters could be something like:

'parameters' => array(
        'filename' => 'fileadmin/imports/data-%Y.csv'
)

Inside the hook, you could run strftime() on the filename parameter in order to replace “%Y” with the current year.

The hook receives the parameters array as the first argument and a reference to the current configuration object (an instance of class \Cobweb\ExternalImport\Domain\Model\Configuration) as second argument. It is expected to return the full parameters array, even if not modified.

Note

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

preprocessRawRecordset

This hook makes it possible to manipulate the data just after it was fetched from the remote source, but already transformed into a PHP array, no matter what the original format. The hook receives the full recordset and a back-reference to the calling object (an instance of class \Cobweb\ExternalImport\Importer) as parameters. It is expected to return a full recordset too.

This hook may throw the \Cobweb\ExternalImport\Exception\CriticalFailureException.

Note

Since External Import version 4.0.0, use a custom step instead, using after:\Cobweb\ExternalImport\Step\HandleDataStep as a position.

validateRawRecordset

This hook is called during the data validation step. It is used to perform checks on the nearly raw data (it has only been through “preprocessRawRecordset”) and decide whether to continue the import or not. The hook receives the full recordset and a back-reference to the calling object (an instance of class \Cobweb\ExternalImport\Importer) as parameters. It is expected to return a boolean, true if the import may continue, false if it must be aborted. Note the following: if the minimum number of records condition was not matched, the hooks will not be called at all. Import is aborted before that. If several methods are registered with the hook, the first method that returns false aborts the import. Further methods are not called.

This hook may throw the \Cobweb\ExternalImport\Exception\CriticalFailureException.

Note

Since External Import version 4.0.0, use a custom step instead, using after:\Cobweb\ExternalImport\Step\ValidateDataStep as a position (or before: if you want to shortcircuit the default validation process).

preprocessRecordset

Similar to “preprocessRawRecordset”, but after the transformation step, so just before it is stored to the database. The hook receives the full recordset and a back-reference to the calling object (an instance of class \Cobweb\ExternalImport\Importer) as parameters. It is expected to return a full recordset too.

This hook may throw the \Cobweb\ExternalImport\Exception\CriticalFailureException.

Note

Since External Import version 4.0.0, use a custom step instead, using after:\Cobweb\ExternalImport\Step\TransformDataStep as a position.

updatePreProcess

This hook can be used to modify a record just before it is updated in the database. The hook is called for each record that has to be updated. The hook receives the complete record and a back-reference to the calling object (an instance of class \Cobweb\ExternalImport\Importer) as parameters. It is expected to return the complete record.

This hook may throw the \Cobweb\ExternalImport\Exception\CriticalFailureException.

insertPreProcess

Similar to the “updatePreProcess” hook, but for the insert operation.

This hook may throw the \Cobweb\ExternalImport\Exception\CriticalFailureException.

deletePreProcess

This hook can be used to modify the list of records that will be deleted. As a first parameter it receives a list of primary key, corresponding to the records set for deletion. The second parameter is a reference to the calling object (again, an instance of class \Cobweb\ExternalImport\Importer). The method invoked is expected to return a list of primary keys too.

This hook may throw the \Cobweb\ExternalImport\Exception\CriticalFailureException. However note that the data will already have been saved.

datamapPostProcess

This hook is called after all records have been updated or inserted using TCEmain. It can be used for any follow- up operation. It receives as parameters the name of the affected table, the list of records keyed to their uid (including the new uid’s for the new records) and a back-reference to the calling object (an instance of class \Cobweb\ExternalImport\Importer). Each record contains an additional field called tx_externalimport:status which contains either “insert” or “update” depending on what operation was performed on the record.

This hook may throw the \Cobweb\ExternalImport\Exception\CriticalFailureException. However note that the data will already have been saved.

Note

This hook is not called in preview mode.

cmdmapPostProcess

This hook is called after all records have been deleted using TCEmain. It receives as parameters the name of the affected table, the list of uid’s of the deleted records and a back- reference to the calling object (an instance of class \Cobweb\ExternalImport\Importer).

This hook may throw the \Cobweb\ExternalImport\Exception\CriticalFailureException. However note that the data will already have been saved.

Note

This hook is not called in preview mode.