Home

![New refactoring MindMap - WIP]

Datashift Wiki

• Options and Configuration

• Import facilities - Generic Rails import of models and all associations from CSV or Excel

• Export facilities - Generic Rails export of models and all associations from CSV or Excel

• Mapping facilities - Create mapping templates from models or files, and use automatic field mapping

• Import Paperclip facilities - Import Paperclip attachments, and attach to existing models.

• Excel facilities

• Defining and importing Complex Associations

• Testing - Running the specs, spree sandbox

• Technical - API - Details on key concepts, classes and API

• Walkthroughs

*Roadmap

N.B Spree facilities are now in their own project/gem : datashift_spree.

Summary

Datashift is an import/export tool for Rails projects, or any Ruby project that utilises ActiveRecord as it's ORM.

It provides extensive support for importing and exporting to .xls and CSV files, not only a single ActiveRecord model, but all it's associated data as well.

Example of Export API

    require 'excel_exporter'
    gen = DataShift::ExcelExporter.new( 'some_file' )

    gen.export(MyARModel.all, :sheet_name => MyARModel.name)

Spreadsheets are ubiquitous, many companies provide product data in this format, they are familiar to non technical users and can be a better way to view and manage complex data sets than traditional seed files or YAML.

Datashift helps map such data quickly and directly into database schema's and populate the database. It is most useful when either you have business logic you wish to fire during an upload, or have complex relationships to build between items in different tables. In terms of speed and efficiency it won't compete with traditional sql type database uploads but it will run all the data through any validation or business logic implemented in the active record models, and will perform joins automatically, and dynamically which cannot be achieved with a simple SQL import.

It provides a variety of ways to express such relationships, and supports an in-column syntax, for defining relationships between models, and also specify additional data to be added alongside the relationship, all from within a single spreadsheet column/row. This enables it to either find preexisting entries in an associated table, or create the required associations dynamically during the import.

Detailed instructions are here and there are many examples in the spec/fixtures area, many with comments in the column headings explaining how to define relationships, which makes visualizing the concept simple.

It can be used to export data to .xls or csv files, and also to generate header only template files, without any data. These can be very useful as the basis for planning the migration of data from another system, or format, or for giving to clients or customers to fill in, ready to be re-imported.

See the walk-throughs for an example of taking a suppliers product spreadsheet and preparing an import to the Spree e-commerce system from it.