Rules File Specifications

Introduction

The following document describes the concepts and specifications for the ruleset files VersaFeed accepts as an alternative to using each rules page's web interface:

The ruleset file upload is designed for clients who have a large quantity of rules to add or manage often. In general, if you have less than 10-15 rules it's most likely going to be easier to just use the web page interface. To better understand the tools pages themselves, please visit each page in your VersaFeed client account.

Format & Global Columns

The ruleset files must be UTF-8 encoded CSV files. We highly recommend downloading each example CSV ruleset file (available at the bottom of each rules page) before attempting to upload your own. All of the rules files have the following columns plus additional columns that are unique to each rules page:

[enabled, attribute, match, value, name]

The attribute-match-value set of fields are the means to select items to apply the rule on. For instance, "Title | contains_word | Acme" would apply the rule to all items whose title contains the whole word Acme. The following describes the formats and accepted values for these fields:

enabled
  • Info : Enables or disables the rule.
  • Accepted values : 0, 1
  • 0 : disable the rule
  • 1 : enable the rule
name
  • Info : (most rulesets) An arbitrary name given to a rule. Useful for identifying rules later.
  • Accepted values : Can be anything (or blank in Single Field feed modifications).
attribute
  • Info : The field to the 'match' and 'value' columns refers to.
  • Accepted values : All values visible in the field selections on any of the rules pages. For "Custom: xxxxx" fields, please just use the "xxxxx" name. You can also specify Custom fields that do not exist to be used elsewhere in the ruleset or other ruleset pages (see Feed Modifications below for more info).
  • any/all : See Compound Rules & Nesting below regarding these special operators.
  • default : Some rulesets allow or require the special value of "default" to be set as the last row of the ruleset. For these cases, 'match' and 'value' must be left empty. See each ruleset and "cascade-style" section at the end of this document for specifics.
match
  • Info : The comparison operator to evaluate 'attribute' and 'value'. We provide two sets of match types: non-numeric, numeric. Only certain fields are numeric (Price, Sale Price, Quantity, etc.) so most of the time you will be using non-numeric match types.
  • Non-numeric :
    • icontains_word : contains word (whole words only)
    • icontains : contains (can be part of a word)
    • contains : contains (case sensitive)
    • istartswith : starts with
    • iendswith : ends with
    • iexact : is
    • exists : is set
    • regex : matches regular expression
    • not_iexact : is not
    • not_icontains : does not contain
    • not_icontains_word : does not contain word
    • not_contains : does not contain (case sensitive)
    • not_istartswith : does not start with
    • not_iendswith : does not end with
    • not_exists : is not set
    • not_regex : does not match regular expression
  • Numeric :
    • > : greater than
    • >= : greater than or equal
    • < : less than
    • <= : less than or equal
    • = : equal
    • != : not equal
value
  • Info : The value applied to the 'match' type on the 'attribute' field.
  • Accepted values : Anything, with restrictions based on 'match' type. For instance, the "exists" match type cannot have a 'value', since all you are checking for is if a given 'attribute' has any value. Multiple values can be comma-delimited as a shorthand for "OR-ing" them together. For example, Title contains Acme, Widgets will match all items with Acme OR Widgets in the title.

Specific Ruleset Files

Below, we have listed each ruleset file's [header rows] and highlighted the fields that are not common to all files. The columns must appear in the orders specified below. Please see the note below regarding "cascading" rulesets.

Feed Exclusions

[enabled, name, shopping_engines, attribute, match, value]
shopping_engines
  • Info : The shopping engine feeds to exclude the matched items from.
  • Accepted values : A comma-delimited list of long or shorthand names for the feeds. Leave blank to apply exclusions to all feeds. You can see the exact names by hovering over the feed buttons on the Feed Exclusions page (if you have no groups create a new group to see the feeds).
  • Examples : google_base_xml__US, google_base_xml, google, bing__US, bing

Feed Categories *

[enabled, name, shopping_engine, country, attribute, match, value, category]
shopping_engine
  • Info : The shopping engine to apply the category rule to. All of the shopping engines' rules must appear in the same file. It's not required to sort each shopping engine's rules together but it's a good idea to keep your sanity.
  • Accepted values : A comma-delimited list of exact feed names (without the "__country-code" declarator). You can see the exact feed names by hovering over the feed tabs on the Feed Categories page.
  • Examples : google_base_xml, bing, thefind_new, pricegrabber
country
  • Info : The exact country code.
  • Accepted values : US, UK, etc. (You can see the exact country codes by hovering over the feed tabs on the Feed Categories page)
attribute
  • default : Each shopping engine can have one "default" category rule that will apply to all items not matched by previous rules. It must appear as the last rule per engine. Set this field to "default" and leave 'match' and 'value' blank.
category
  • Info : The category value to set the selected items to. VersaFeed utilizes automatic category matching for certain clients so please check with us first before using this tool.
  • Accepted values : See the taxonomy links at the top of each feed tab for the full taxonomy files.

Feed Modifications (Freeform)

[enabled, name, shopping_engines, attribute, match, value, output_attribute,
    action, parm1, parm2, parm3, parm4]
shopping_engines
  • Info : The shopping engine feeds to apply a given modification to.
  • Accepted values : A comma-delimited list of long or shorthand names for the feeds. Leave blank to apply the modification to all feeds. You can see the exact names by hovering over the feed buttons on the Feed Modifications page (if you have no rules create a new rule to see the feeds).
  • Examples : google_base_xml__US, google_base_xml, google, bing__US, bing
output_attribute
  • Info : The field you are modifying. See 'attribute' above in the Global Columns section for basic info. You can also create new "custom" fields on the fly by using names that don't appear in the standard attribute list. Once you populate these new fields you can use them elsewhere in the VersaFeed tool suite (exclusions, categories, other feed modifications).
action
  • Info : The modification type/action you are performing on 'output_attribute'
  • Accepted values : See web interface for Basic and Advanced action types.
  • Basic :
    • Set : assign the value(s) in 'parm1-4'
    • Set Multi-value : assign the value(s) in 'parm1-4', given 'output_attribute' can accept multiple values (e.g., AdWords Labels)
    • Unset : remove any value, leaving it blank
    • Find & Replace : find 'parm1' and replace with 'parm2'
    • Change Case : set case to case code in 'parm1' (accepted: title, sentence, upper, lower)
    • Set Tagging : append value in 'parm1' to an existing or non-existing query string
    • Encode Tagging : same as Set Tagging, but with URL encoding
  • Advanced :
    • Regex Replace : same as Find & Replace, except with regex notation, including capturing groups
    • Calculate : assign the result of a mathematical expression using any combination of field values, constants, and mathematical operators (see 'parm1-4')
parm1-4
  • Info : The values used to assign to 'output_attribute'. Most of the time you should only need 1-2 of these fields. You can stack the values in 'parm2-4' onto 'parm1'. In the web interface, it's the same as clicking the "append value" link. There are 2 types of values accepted in these columns (Field, Constant), plus special cases (e.g., Change Case codes).
  • Field value : Use the syntax ${field name}. For example, to prepend brand to the beginning of the title, you could do parm1 = ${Brand}, parm2 = ${Title}. You could also do the equivalent using only 'parm1' = ${Brand} ${Title} (note, the space in-between is a constant value).
  • Constant value : When the value is a literal string, just use the raw string. For instance, taking the example above a step further, we could do 'parm1' = Nike ${Title} - ${Color} (size ${Size}). Applying the rule to the title "Running Shoes" would modify it to "Nike Running Shoes - Green (size 9)". We could set the shipping price to 15% of the item price using Calculate with 'parm1' = ${Price} * 0.15. To set a field to empty, use the syntax ${empty} (because just an empty field will be ignored).

Feed Modifications (Single Field) *

[enabled, set_value, attribute, match, value, name]
set_value
  • Info : This ruleset uses the Set action type on a single field, so all you need to do is assign the value of that field with this column.
  • Accepted values : Constant values only.
attribute
  • Catchall : (optional) Single field feed modification rulesets may have a "catchall" rule which, if used, must appear as the last row in the ruleset. Its 'set_value' value will get assigned to all items not matched by previous rules. Set this field to "catchall" and leave 'match' and 'value' blank.
name
  • Info : (optional) Assigning a name is optional for this ruleset. Think of it as a helpful label.

* Cascading Rulesets

In these rulesets, items can only match one rule. Once an item matches a given rule it is excluded from matching any rules below it. Each item flows from the first rule to the next, cascading into each following rule until it matches. For this reason, it's important to put the more specific rules at the top and move towards broader rules. For instance, if you have a rule selecting items with Internal Categories containing the word "furniture" above a rule selecting specific SKU's that also happen to be furniture items, the SKU rules will not get executed on items that have already matched the furniture rule above. These rulesets allow you to provide one "default" rule as the last row in the ruleset.

Compound Rules & Nesting

Once you have more than one selection rule for a given group or action, we refer to it as a compound rule. Compound rules are connected with All or Any selectors, which equivolate to AND and OR standard logic operators. We provide the means to achieve unlimited nesting of compound rules and subgroups in the ruleset files using special operators. These compound operators will appear in the 'attribute' column:

  • all : All rules within the group must be true for the compound rule to match.
  • any : Only one of the rules within the group must be true to produce a match.
  • * : Precede each attribute value with one asterisk per level of indentation.

When using "any" and "all", always leave the 'match' and 'value' columns empty for this row, as the real selection happens on the following row(s) within each any/all. Let's look at some examples:

Example 1: Simple compound rule

This 2-rule compound statement is equivalent of saying: Select all items whose Title contains "Acme" AND Description contains "widget". The single asterisk in front of Title and Description signify these two rows below to the "all" in row 2.

Example 2: Nested subgroup

We now have a 4-rule compound rule group, with a nested subgroup. This is equivalent of saying: Select all items whose Title contains "Acme" OR Description contains "widget" OR (Price > $100 AND Brand is not set). The double asterisk in front of Price and Brand signify they are part of the "all" in row 5.