Loading Line Sheet Data¶

In VibeIQ, "line sheet data" refers to Item, ProjectItem, and AssortmentItem data.

Item: Item data is global and exists outside the context of a Project.
- Items can also be part of a Family, as indicated by a single Family Item. Families can have Options, which are variations of the Family Item. In other terms, you could think of this as Product (Family) vs Colorway (Option).
ProjectItem: ProjectItem data is specific to an Item as it exists in a Project.
- This is typically considered as seasonal data and can change season over season.
- If an Item is carried over into a following season, the data from the prior season, as represented by ProjectItem, will not necessarily be the same.
AssortmentItem: AssortmentItem data is specific to an Item as it exists within an Assortment and a Project.
- An item can exist within many different Assortments in a single Project.
- Organizing your regions into many Assortments is an example of this.

Despite this hierarchical structure: Item (Global) > ProjectItem (Seasonal) > AssortmentItem (Grouping/Regional), the load file for this structure remains tabular-CSV. This is possible because a single property key should not be shared across more than one of these three entities. An important note, the loader is only able to load data for one Project at a time when it comes to ProjectItems and AssortmentItems.

Loading Items¶

Required Properties¶

In your load file, you must provide the following properties for each row. These may be the CSV column headers or usage of federatedMappings or conditionalColumns in the loader configuration to match these keys.

Loading an Item Option for a Family:¶

itemFamilyFederatedId: The federatedId of the Item Option's Family Item.
name: The name of the Item Option's Family Item.
itemOptionFederatedId The federatedId of the Item Option.
optionName: The name of the Item Option itself.

Upon load, the loader will search for an Item Option by itemOptionFederatedId. If one does not exist, a new Item will be created and assigned to the Item Family that has federatedId of itemFamilyFederatedId. If that Item Family does not exist, it will be created as well.

name and optionName will be updated on the Family and Option Items, respectively, if they already exist. Therefore, it's critical that name and optionName remain consistent across subsequent loads of the same Items.

YAMLJSON

loadType:
- ITEM
federatedMappings:
  itemFamilyFederatedId: 'style'
  itemOptionFederatedId: 'colorName'
  name: 'styleName'
  optionName: colorName
conditionalColumns:
- default: item:product:apparel
  toProperty: typePath
- default: color
  toProperty: optionGroup

{
  "loadType": ["ITEM"],
  "federatedMappings": {
    "itemFamilyFederatedId": "style",
    "itemOptionFederatedId": "colorName",
    "name": "styleName",
    "optionName": "colorName"
  },
  "conditionalColumns": [
    {
      "default": "item:product:apparel",
      "toProperty": "typePath"
    },
    {
      "default": "color",
      "toProperty": "optionGroup"
    }
  ]
}

Loading Only an Item Family¶

itemFamilyFederatedId: The federatedId of the Item Option's Family Item.
name: The name of the Item Option's Family Item.

Upon load, the loader will search for an Item Family by itemFamilyFederatedId. If one does not exist, a new Item will be created.

name will be updated on the Family Item if it already exists. Therefore, it's critical that name remains consistent across subsequent loads of the same Items.

YAMLJSON

loadType:
  - ITEM
federatedMappings:
  itemFamilyFederatedId: 'style'
  name: 'styleName'
conditionalColumns:
  - default: item:product:apparel
    toProperty: typePath
  - default: color
    toProperty: optionGroup

{
  "loadType": ["ITEM"],
  "federatedMappings": {
    "itemFamilyFederatedId": "style",
    "name": "styleName",
  },
  "conditionalColumns": [
    {
      "default": "item:product:apparel",
      "toProperty": "typePath"
    },
    {
      "default": "color",
      "toProperty": "optionGroup"
    }
  ]
}

Loading ProjectItems:¶

Required Properties¶

Loading ProjectItems means taking a list of Items and inserting them into a Project. An Item's existence in an Project is determined by the existence of a ProjectItem entity.

To load ProjectItems, you must specify the federatedIds for the Items you want to load into a Project. There are two different ways you can identify this Project to load these Items into:

Using Assortment Parameters (i.e. assortmentSplit) if you are also loading into an Assortment. Since Assortments live within Projects, the loader will automatically identify and select the Project from the specified Assortment. See the "Loading AssortmentItem" section for more information.
Using the workspaceIdentifier if you are only loading Items into a Project and not also loading them into an Assortment. Specify the user-defined identifier for the Project. You may find and manage this in the Hub UI's Project view. Click the "hamburger menu" icon to the right of the project name, select "Configure Project", and view the Project's identifier property.

Example loading just into a Project, without an Assortment load (with workspaceIdentifier):

YAMLJSON

loadType:
  - ITEM
  - PROJECT_ITEM
federatedMappings:
  itemFamilyFederatedId: 'STYLE_NUMBER'
  name: 'STYLE_NAME'
  itemOptionFederatedId: 'MATERIAL_OPTION_NUMBER'
  itemOption: 'MATERIAL_OPTION_NAME'
workspaceIdentifier: 'fall:2022'

{
  "loadType": ["ITEM", "PROJECT_ITEM"],
  "federatedMappings": {
    "itemFamilyFederatedId": "STYLE_NUMBER",
    "name": "STYLE_NAME",
    "itemOptionFederatedId": "MATERIAL_OPTION_NUMBER",
    "itemOption": "MATERIAL_OPTION_NAME"
  },
  "workspaceIdentifier": "fall:2022"
}

Loading AssortmentItems¶

Required Properties¶

Loading AssortmentItems means taking a list of Items and inserting them into an Assortment. An Item's existence in an Assortment is specified by the existence of an AssortmentItem entity. If you have included PROJECT_ITEM in your loadType parameter, the selected Project that will be loaded into will be automatically selected by the loader. The Project in which the Assortment lives in will be selected.

There are two types of AssortmentItem loads:

Full Assortment Load (default)¶

When performing a full load, the entire state of the Assortment's Items will match the load file. This means that any Items not in the load file will be removed from the Assortment. Using the parameters below, you may use the Assortment's ID or Identifier to dictate the Assortment to load into.

assortmentId: The ID of the Assortment to load into.
assortmentIdentifier : The identifier of the Assortment to load into. This is an internal property and is not the Assortment Name.
assortmentSplit: An object allowing you to conditionally split the Items in the load file across multiple Assortments.
- fieldToSplitOn: The column name in the load file to use for splitting.
- values: An array of objects specifying the value to split on and the Assortment to load into.
  - value: The value in the fieldToSplitOn column to split on. Example "mens".
  - assortmentId: The ID of the Assortment to load any rows with value matching in column fieldToSplitOn.
  - assortmentIdentifier: The identifier of the Assortment to load any rows with value matching in column fieldToSplitOn.
    - This may be combined with assortmentId only within the assortmentSplit object.

Example with `assortmentId`:¶

YAMLJSON

loadType:
  - ITEM
  - ASSORTMENT
  - PROJECT_ITEM
federatedMappings:
  itemFamilyFederatedId: 'style'
  itemOptionFederatedId: 'colorName'
  name: 'styleName'
  optionName: colorName
conditionalColumns:
  - default: item:product:apparel
    toProperty: typePath
  - default: color
    toProperty: optionGroup
assortmentId: "assortmentId1"
# assortmentIdentifier: "assortmentIdentifier2" # this may be used interchangeably with assortmentId

{
  "loadType": [
    "ITEM",
    "ASSORTMENT",
    "PROJECT_ITEM"
  ],
  "federatedMappings": {
    "itemFamilyFederatedId": "style",
    "itemOptionFederatedId": "colorName",
    "name": "styleName",
    "optionName": "colorName"
  },
  "conditionalColumns": [
    {
      "default": "item:product:apparel",
      "toProperty": "typePath"
    },
    {
      "default": "color",
      "toProperty": "optionGroup"
    }
  ],
  "assortmentId": "assortmentId1"
  // "assortmentIdentifier": "assortmentIdentifier2" // this may be used interchangeably with assortmentId
}

Example with `assortmentSplit`:¶

YAMLJSON

loadType:
  - ITEM
  - ASSORTMENT
  - PROJECT_ITEM
federatedMappings:
  itemFamilyFederatedId: 'style'
  itemOptionFederatedId: 'colorName'
  name: 'styleName'
  optionName: colorName
conditionalColumns:
  - default: item:product:apparel
    toProperty: typePath
  - default: color
    toProperty: optionGroup
assortmentSplit:
  fieldToSplitOn: wearer
  values:
    - value: mens
      assortmentId: "assortmentId1"
    - value: womens
      assortmentIdentifier: "assortmentIdentifier2"

{
  "loadType": [
    "ITEM",
    "ASSORTMENT",
    "PROJECT_ITEM"
  ],
  "federatedMappings": {
    "itemFamilyFederatedId": "style",
    "itemOptionFederatedId": "colorName",
    "name": "styleName",
    "optionName": "colorName"
  },
  "conditionalColumns": [
    {
      "default": "item:product:apparel",
      "toProperty": "typePath"
    },
    {
      "default": "color",
      "toProperty": "optionGroup"
    }
  ],
  "assortmentSplit": {
    "fieldToSplitOn": "wearer",
    "values": [
      {
        "value": "mens",
        "assortmentId": "assortmentId1"
      },
      {
        "value": "womens",
        "assortmentIdentifier": "assortmentIdentifier2"
      }
    ]
  }
}

Partial Assortment Load¶

To add Itemsto an Assortment without removing existing Items that do not exist in the load file, you may do so with a few properties within assortmentSplit. With them, you can either add or remove Items from an Assortment without requiring the entire Assortment's state on-hand while doing the load.

assortmentSplit
- partialAssortmentUpdate?: An optional boolean property indicating whether you want to perform a partial update on the Assortment instead of a full update.
  - Set this to true if you want to append the Items in the load file to the assortment(s).
  - Set this to false or omit it if you want to perform a full update on the Assortment.
- addField?: An optional string property where if a value exists in the column of this name, the row will be added to the Assortment. Expected values in the CSV are true, false, or empty ''.
- dropField?: An optional string property where if a value exists in the column of this name, the row will be dropped from the Assortment. Expected values in the CSV are true, false, or empty ''.
- fieldToSplitOn: The column name in the load file to use for splitting.
- values: An array of objects specifying the value to split on and the Assortment to load into.
  - value: The value in the fieldToSplitOn column to split on. Example "mens".
  - assortmentId: The ID of the Assortment to load any rows with value matching in column fieldToSplitOn.
  - assortmentIdentifier: The identifier of the Assortment to load any rows with value matching in column fieldToSplitOn.
    - This may be combined with assortmentId only within the assortmentSplit object.

Example with `partialAssortmentUpdate`:¶

YAMLJSON

loadType:
- ITEM
- PROJECT_ITEM
- ASSORTMENT
assortmentSplit:
  partialAssortmentUpdate: true
  addField: addItem
  dropField: dropItem
  fieldToSplitOn: season
  values:
    - value: "spring"
      assortmentId: "someAssortmentId"

{
  "loadType": [
    "ITEM",
    "PROJECT_ITEM",
    "ASSORTMENT"
  ],
  "assortmentSplit": {
    "partialAssortmentUpdate": true,
    "addField": "addItem",
    "dropField": "dropItem",
    "fieldToSplitOn": "season",
    "values": [
      {
        "value": "spring",
        "assortmentId": "someAssortmentId"
      }
    ]
  }
}

Loading Line Sheet Data¶

Loading Items¶

Required Properties¶

Loading an Item Option for a Family:¶

Loading Only an Item Family¶

Loading ProjectItems:¶

Required Properties¶

Loading AssortmentItems¶

Required Properties¶

Full Assortment Load (default)¶

Example with assortmentId:¶

Example with assortmentSplit:¶

Partial Assortment Load¶

Example with partialAssortmentUpdate:¶

Example with `assortmentId`:¶

Example with `assortmentSplit`:¶

Example with `partialAssortmentUpdate`:¶