Error handling

Any operation dealing with user-provided information is exposed to find some missing or invalid values along the way, and importing data is no exception. The file may not be readable, or it may not contain the expected set of columns. And even when it does, some rows may not be valid or processable.

Error callbacks

active_importer deals with these situations by providing a set of event callbacks to which you can listen, and take some action, or just be informed of the progress of the import process. All these error-handling callbacks receive as an argument the exception that caused the error condition, so in that sense they have some resemblance to a Ruby rescue block.

Let's take a look at the callbacks that are useful for error handling:

import_failed

This event happens when the importer cannot even start processing the spreadsheet. It could be because the file does not exist or is not readable. It may be readable but not recognizable as a valid supported format. Additionally, it may be recognized as a spreadsheet, but still it might not contain the expected set of columns declared to the importer, or the sheet which the importer expects to the read the data from.

If you wish your importer inform your app know about this error condition, you can declare a callback for this event:

class EmployeeImporter < ActiveImporter::Base
  imports Employee

  # ...

  on :import_failed do |ex|
    some_logger.error("Could not start importing data: #{ex}")
  end
end

It's important to note that these kind of errors always happen during the initialization phase of the importer instance, and besides calling the callbacks, the importer's initialize method fails by re-raising the exception after invoking the callbacks. Bottom line is, if your importer fails to even start, you will get an exception in addition to be notified in the callbacks.

row_error

This event happens when an error occurs while processing a row. It means that the row contents could not be imported, and the row cannot be processed further. This happens when an exception of any kind gets raised and not handled, and it is caught by the importer, to prevent this exception to affect the processing of the remaining rows (although this behavior changes when using a transactional importer).

Some examples of error conditions that may occur while processing a row are:

• Validation errors. All processing of the row data went fine, but the model object was not valid and it could not be saved.
• Exceptions occurring in any custom block of code. You may be invoking methods on nil, or whatever.

Callbacks for this error event are usually used alongside callbacks for the row_success and row_processed events. The row_success event is the opposite of row_error. It gets fired for every row that could be processed successfully, and stored in the corresponding model object.

class EmployeeImporter < ActiveImporter::Base
  imports Employee

  # ...

  on :row_error do |ex|
    some_logger.error("Could not start importing data: #{ex}")
    @rows_with_errors += 1
  end

  on :row_success do
    @rows_imported += 1
  end

  on :row_processed do
    @rows_processed += 1
  end
end