Category File

If you have a category hierarchy, you can map it onto each record by doing 3 things:

Category File: an XML file that has a list of categories, with their IDs
Product Record: specify a categoryId field array on the record
Upload Configuration: defines how you want to map the categories in the upload configuration

Our upload service will map the structured product taxonomy onto your product catalog at upload time.

Category File

The category file must in in XML. Each level of your hierarchy should be listed as an <entry>.

A category ID can be defined as a string or as an integer in your category file.

Parent <entry> tags must be above their children.

For example, here are 2 entries, a parent of Accessories with a child of Hats:

<entry>
<id>300</id>
  <title>Accessories</title>
  <parents/>
</entry>
<entry>
  <id>310</id>
  <title>Hats</title>
  <parents>300</parents>
</entry>

Product Record

In the category file you have given each category an <id> attribute.

In the data file, tag the product with the most specific category ID via categoryId. At upload time, the engine will build the hierarchy of categories and layer into the record.

You can specify multiple categoryId values by populating with an array of the values you wish it to hold.

Array of Strings

The array of category IDs must be a String; in other words each categoryId value must be in quotes: "categoryId":["220","250"]

Example

E.g., in our sample data record 1007 has 2 different categories can live under:

{"id":"1007","title":"Women's Adidas Lightweight Hiking Shoes", "categoryId":["220","250"],  "variants":[ "... omitting for brevity ... "] }

Upload Configuration

Within the upload configuration file that is sent with each data load, there is a setting for categoryVersion. This can be set to legacy, v1 or v2; v1 by default.

We recommend that v2 is used.

Here is how you would define it within your upload config file:

  categoryVersion: v2

Category Mapping Structures

The sample below refer to record 1003 from our sample file. This record maps to rain boots, via category id 240, which is defined in our sample XML file:

<entry>
  <id>200</id>
  <title>Shoes</title>
  <parents/>
</entry>
<entry>
  <id>235</id>
  <title>Boots</title>
  <parents>200</parents>
</entry>
<entry>
  <id>240</id>
  <title>Rainboots</title>
  <parents>235</parents>
</entry>

Below are the 3 ways that this hierarchy can be mapped onto the record, by changing the specification in the upload config.

v1

When categoryVersion: v1 is used in the upload config, the below structure will be used for mapping the category hierarchy. This structure does not enforce cross-hierarchy taxonomy.

"categories" : [ {
  "categories" : [ {
    "categories" : [ {
      "value" : "Rainboots"
    } ],
    "value" : "Boots"
  } ],
  "value" : "Shoes"
} ]

v2

When categoryVersion: v2 is used in the upload config, the below structure will be used for mapping the category hierarchy.

You can make your new hierarchy searchable by adding this into the upload configuration:

fieldDefinition: {name: "categories.*", search: true}

V2 also support multiple hierarchies elegantly: you can map multiple categories by using "categoryId" : [ "220", "250" ] (see record 1007 as an example).

Sample mapping of a single hierarchy (record 1003, category 240):

categories:
[
{
"1": "Shoes",
"2": "Boots",
"3": "Rainboots",
"leaf": "Rainboots"
}
]

The V2 version of categories brings back the leaf category and enforces the taxonomy when records belong to multiple hierarchies. Sample mapped structure for 2 hierarchies (record 1007):

"categories" : [ {
  "1" : "Shoes",
  "2" : "Hiking",
  "leaf" : "Hiking"
}, {
  "1" : "Shoes",
  "2" : "Trail Running",
  "leaf" : "Trail Running"
} ],

When category.leaf="Train Running" is selected, category.2="Hiking" no longer shows up as a navigation option.

legacy

if you define categoryVersion: legacy in the upload configuration file, then the legacy, flattened, category structure format will be used. E.g., if you have a record that contains an attribute categoryId="240" the resulting record will have the following attributes assigned to it.

Please note, legacy doesn’t support multiple hierarchies.

category1: Shoes
category1_id: 200
category2: Boots
category2_expanded: Shoes~Boots
category2_expanded_id: 200~235
category2_id: 235
category3: Rainboots
category3_expanded: Shoes~Boots~Rainboots
category3_expanded_id: 200~235~240
category3_id: 240
category_leaf: Rainboots
category_leaf_expanded: Shoes~Boots~Rainboots
category_leaf_expanded_id: 200~235~240
category_leaf_id: 240

Samples

Sample files

Here is how you would load the above 3 files:

curl -X POST--form "config=@config.txt"     --form "category=@sampleDataCategories.xml"     --form "data=@sampleData.json" \
"https://--customerId--.groupbycloud.com/data/v1/upload/stream"

Sample output

This will map v2 arrays onto the records, e.g.:

{ "categories": [{"1":"Shoes","2":"Hiking","leaf":"Hiking"},{"1":"Shoes","2":"Trail Running","leaf":"Trail Running"}] }