Solidus Importer

This extension aims to create a component to import data from other popular e-commerce solutions to Solidus.

Installation

Add solidus_importer to your Gemfile:

gem 'solidus_importer'

Instead of a stable build, if you want to use the bleeding edge version, use this line:

gem 'solidus_importer', github: 'solidusio-contrib/solidus_importer'

Bundle your dependencies and run the installation generator:

bin/rails generate solidus_importer:install

Upgrading

After upgrading this gem, be sure to re-run the installation generator, and resolve any conflicts your modified solidus_importer.rb initializer file may have with new default configuration values.

bin/rails generate solidus_importer:install

Usage

The imports can be fully managed from the backend UI, following progress (image processing can take a few seconds for each image).

From the console

Sample code to import some products:

SolidusImporter.import! 'some_path/sample_products.csv', type: :products

Accepted Format

The accepted format is the Shopify CSV for which is also relatively easy to find exporters for every major platform (e.g. shopify_transporter).

There are three supported CSV types:

1. Product
2. Order
3. Customer

---

Alternatively, we accept CSV files that conform to the ones shown in the examples/csvs folder

The Processors

The importing is managed by a list of processors for each CSV type, the default processors are:

customers: {
  importer: SolidusImporter::BaseImporter,
  processors: [
    SolidusImporter::Processors::Address,
    SolidusImporter::Processors::Customer,
    SolidusImporter::Processors::Log
  ]
},
orders: {
  importer: SolidusImporter::BaseImporter,
  processors: [
    SolidusImporter::Processors::Order,
    SolidusImporter::Processors::Log
  ]
},
products: {
  importer: SolidusImporter::BaseImporter,
  processors: [
    SolidusImporter::Processors::Product,
    SolidusImporter::Processors::Variant,
    SolidusImporter::Processors::OptionTypes,
    SolidusImporter::Processors::OptionValues,
    SolidusImporter::Processors::ProductImages,
    SolidusImporter::Processors::VariantImages,
    SolidusImporter::Processors::Log
  ]
}

Each processor is a callable that will accept a context Hash. It will perform its function within the #call(context) method and will return an equally valid context Hash. The returned context can be augmented with additional data.

Example:

CUSTOM_LOGGER = Logger.new(Rails.root.join('log/importer.log'))
CustomLoggerProcessor = ->(context) {
  context.merge(logger: CUSTOM_LOGGER)
}
# Replace the original Log processor with CustomLoggerProcessor
SolidusImporter::Config.solidus_importer[:customers][:processors].map! do |processor|
  if processor == 'SolidusImporter::Processors::Log'
    'CustomLoggerProcessor'
  else
    processor
  end
end

Each list of processors can be configured to add, remove, or replace any of the default processors.

Advanced Configuration

Defining Processors

To define your own processors (in this example for products), add to the spree initializer:

SolidusImporter::Config[:solidus_importer] = {
  products: {
    importer: SolidusImporter::Importers::Products,
    processors: [
      SolidusImporter::Processors::Product,
      SolidusImporter::Processors::Variant,
      SolidusImporter::Processors::Log
    ]
  }
}

The importer class is responsible of the whole import process of a single source file. The processors classes are responsible of the import of a single row of the source file; every processor has a call method (with an input context) which makes a specific action and updates the context if needed.

Defining CSV format validators

Custom validators for the CSV data can be defined to verify high level attributes about the CSV before it is parsed into individual import rows.

This configuration can be found and overridden in the solidus_importer.rb initializer file.

SolidusImporter.configure do |config|
  # By default, the imported CSV data is validated to have headers that exist and are not blank
  config.import_data_validators = [
    ->(csv_table) {
      headers = csv_table.headers
      if headers.blank? || !headers.exclude?(nil)
        'Invalid headers'
      end
    }
  ]
end

Development

Testing the extension

First bundle your dependencies, then run bin/rake. bin/rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using bin/rake extension:test_app.

bin/setup
bin/rake

To run Rubocop static code analysis run

bundle exec rubocop

When testing your application's integration with this extension you may use its factories. Simply add this require statement to your spec_helper:

require 'solidus_importer/factories'

Running the sandbox

To run this extension in a sandboxed Solidus application, you can run bin/sandbox. The path for the sandbox app is ./sandbox and bin/rails will forward any Rails commands to sandbox/bin/rails.

Here's an example:

$ bin/rails server
=> Booting Puma
=> Rails 6.0.2.1 application starting in development
* Listening on tcp://127.0.0.1:3000
Use Ctrl-C to stop

Updating the changelog

Before and after releases the changelog should be updated to reflect the up-to-date status of the project:

bin/rake changelog
git add CHANGELOG.md
git commit -m "Update the changelog"

Releasing new versions

Please refer to the dedicated page on Solidus wiki.

License

Copyright (c) 2020 Nebulab SRLs, released under the New BSD License