Usage

Setup

Create a config/configuration.yml file with expected format and customize
Create a data/products.csv file with the expected format, you can use data_examples/ as a reference

Nagual Command

Install the nagual gem
Use the following commands:
- nagual review - to validate input and see if there are invalid rows, an error_report will be generated with information about input data.
- nagual export - to generate a catalog.xml (only valid products will be used)
By default nagual will read from a csv and out put a catalog xml file, location of input and output files can be modified in configuration.yml file

Nagual API

If you rather use the gem inside your project you can use it like this:

nagual = Nagual::API.new
puts nagual.transform(:catalog, :csv, :xml_catalog)
puts nagual.transform(:catalog, :csv, :error_report)

Mapping

All valid product attributes can be mapped from a csv file using the mapping section of the configuration.yml file, for that you need to define a mutation for each expected columns:

key: expected name in the input
to: product field name to where values will be saved
name: mutation name, can be either:
- 'none' to copy the values as it is
- 'date' to parse a date column
  - format: string format to parse input value
- 'convert' to modify the value and it has the following params:
  - default: if value is not found this value will be used
  - values: it's a map to convert a field value to another one.

In example configuration file we convert a column named status with values 'online' or 'offline' to the product field 'online_flag' with values 'true' or 'false'

Decoration

In ths configuration section you can add additional values or enrich the input values with different options:

Fixed

All products will be created with a default fixed value, key represents the product field name to be used.

Copy

The value from one product field will be copied as it is to another value.

key: product field name that will be copied
to: product field name that will be the destination

Merge

You can use one or more input keys to generate an output pattern to be saved in an specific product field

keys: name of the fields to be used in pattern
pattern: string with the expected output (keys can be used with %{} notation)
to: name of the field that will be used to save the output

Images

You can add configuration to add images links to specified products.

view_type: name for the image type, must be one of the catalog view_types defined.
filter_key and filter_value are used to select the rows that will contain the images defined.
names: this are a list of images that you want to add.

For example:

images:
  - view_type: large
    filter_key: online_flag
    filter_value: true
    names:
      - standard
      - shot1

Will create 2 large images for each product with online_flag=true, the names for those images will be: images/large/id_standard.png and images/large/id_shot1.png

Images will be expected to exist in the specified location.

To modify where images are stored or name pattern, modify ouput.xml.product.image value in configuration file.

Variations

To generate a new variation for products in the catalog a column needs to be added in the csv file and then added to the variations section for decoration

  variations:
    - color

For example to set a color variation a input values can have values such as "blue,green" or "red"

Division

Variation

You can create multiple products from a single entry by selecting a variation and using that to generate new products.

Product id for each product will be generated by using the specified pattern and also a custom attribute will be added to each product with the variation name.

For example, if input contains an entry for sizes with value: S,M and a manufacturer sku with value: SKU

With this configuration:

division:
  product:
    strategy: variation
    params:
      variations: sizes
      variation: size
      pattern: '%{manufacturer_sku}_%{size}'

Nagual will produce two products 2 products with the following attributes

product id: 'SKU_S', size: 'S', manufacturer sku: SKU
product id: 'SKU_M', size: 'M', manufacturer sku: SKU

None

If you don't want to use this feature select 'none' strategy in configuration, and only 1 product will be generated for each input entry.

division:
  product:
    strategy: none

Ignore columns

If a column is not mapped in configuration file it will be ignored.

Custom attributes

If a column is mapped but there is not product field with that name, then a custom attribute will be generated for that value.

Variants

Variants will be automatically generated when a value for a variation is set for a product.

The number of variants created for a product depends on how many variation values are defined, for example if a product contains 3 different variation values, then 9 variants will be generated, considering all the possible combination of values.

magma-labs/nagual