*** This file is partially outdated but should still be helpful ***

_____________________________________________________________________________________

ATImportTool

    This tool aims to put an end to ugly, ad-hoc import scripts for migrating
    data into Plone. Right now only simple cases are supported but this is improving.

Features:

    * Command line interface for selecting import options
    
    * Binary file importing
    
    * Create new folders for content on the fly
    
    * Update existing content
    
    * Users can create custom Data Transforms
    
    * Users can create custom Data Readers
    

Using ATImportTool:

    * Make sure your CSV files are prepped and ready to go. (see below for more info)

    * The actual tool can be put anywhere (for now), because it is only a py script.
      But it is recommended to put it in your Products directory
      
    * Create your own config from config.py.example
    
    * You must run zopectl from the ATImportTool directory. ie:
       >> cd instance/Products/ATImportTool
       >> ../../bin/zopectl run ATImportTool.py
        

Preparing your CSV files when using the flat_file DataReader: 

    * Your csv files should be tab delimited, for now this is the best method to insure 
      nothing messes up.
      
    * Your csv files need to have unix style line endings.
      
    * Your csv files must have a header row. This row will tells the import tool which 
      columns pertain to which content-type properties. For example, let's say your csv 
      file looks like so:
        
        I like Bees     Bees are yellow and black. Sometimes they hurt.
        I like Plone    Plone is a funny word but there is nothing funny about what it does!
        I like Python   Python is a great language that is named after a funny man.
        
                
      So we have 3 rows and 2 columns of data. Let's say we want import this data and create 
      ATDocument content. The first column is the 'title' property and the second column is
      the 'text' property. So, once we prepend our header row, it should look like this:

        title           text
        I like Bees     Bees are yellow and black. Sometimes they hurt.
        I like Plone    Plone is a funny word but there is nothing funny about what it does!
        I like Python   Python is a great language that is named after a funny man.
      
    * Binary files that need to be imported should be placed in the BINARY_FOLDER path, 
      specified in config. Your csv should just include the file name of the binary. See 
      example for more info.
      
Data Transforms

    __Overview__
    Data transforms are used to modify imported data before it is applied to Plone content.
    Any data that is imported in which a string type is not sufficient, a Data Transform must 
    be applied to change it to your desired data type. For example, images, lists, dicts, etc.
    Data Transforms can be applied sequentially on one piece of content. For example, you could 
    use Data Transforms to use a file path to load an image then have another Data Transform which
    takes the loaded image and resizes it or crops it. 
    
    __Usage__
    Data Transforms are applied by column - in the header definition (Row 0) of your data file. A
    Data Transform follows the field name and is preceeded by a colon. For example, say you have a 
    field named "product_image" and you want to use the file path in that column data to load an image 
    for each piece of content. The header definition for that column would show "product_image:image"
    
    __Custom Transforms__
    ATImportTool comes with basic Data Transforms but custom ones can eaisly be made - the complexity 
    only comes in how you want to transform the data. Take a look at any of the transforms in the 
    transforms folder.
    
      
Questions, Comments:
    
    matt@dopelogik.com