Loading Custom Entities

If you have not reviewed the Getting Started page, please do so to understand the fundamentals of loading data.

Custom Entities represent a way to store data in VibeIQ that doesn't fit into the standard data model. Like all entity types, these are organized by typePath. It is especially important to get this field correct upon load, so that the data is not inadvertently duplicated onto another Custom Entity type.

Examples organizing Custom Entities by typePath:

• "Vendor" as specified by typePath: custom-entity:vendor
• "Colorway Reference" as specified by typePath: custom-entity:colorwayReference

To load data into each of Custom Entity sub-types, the correct typePath must be specified.

Required Config Properties

• loadType: ['CUSTOM_ENTITY']
• federatedId
• name
• typePath: Must follow the format custom-entity:<subtype> (e.g., custom-entity:vendor, custom-entity:colorwayReference)

typePath Format

The typePath for custom entities must always begin with custom-entity: followed by the sub-type path. This is what distinguishes different kinds of custom entities from each other.

Incorrect typePath will cause a validation error

If typePath does not match the format custom-entity:<subtypepath>, the load will fail with: "typePath must be set to 'custom-entity:\<subtypepath>' via csv data, conditionalColumn, or federatedMappings."

Federated ID Auto-Prefixing

When loading custom entities, the Loader automatically prefixes the federatedId with the typePath value if it is not already prefixed with custom-entity:. This ensures federated IDs are unique across custom entity sub-types.

For example, if you load a vendor with federatedId: "VNDR-001" and typePath: "custom-entity:vendor", the stored federated ID will be custom-entity:vendor:VNDR-001.

Load Example

Config YAML / JSON

Please review the Creating a Loader Process to understand how to provide this Config example to the Loader.

YAMLJSON

loadType:
  - CUSTOM_ENTITY
federatedMappings:
  federatedId: "name"
  name: "name"
conditionalColumns:
  - toProperty: "typePath"
    default: "custom-entity:colorwayReference"

{
  "loadType": [
    "CUSTOM_ENTITY"
  ],
  "federatedMappings": {
    "federatedId": "name",
    "name": "name"
  },
  "conditionalColumns": [
    {
      "toProperty": "typePath",
      "default": "custom-entity:colorwayReference"
    }
  ]
}

Providing typePath in the CSV

If your CSV contains rows for a single sub-type, use a conditional column with a default (as shown above). If your CSV contains rows for multiple sub-types, include typePath as a column in the CSV:

CSVConfig (JSON)

name,typePath,description
Acme Corp,custom-entity:vendor,Primary vendor
Cotton,custom-entity:material,Fabric type

{
  "loadType": ["CUSTOM_ENTITY"],
  "federatedMappings": {
    "federatedId": "name",
    "name": "name"
  }
}

Loading multiple sub-types

When loading multiple custom entity sub-types in a single CSV, each row's typePath value determines the entity type. Properties that don't exist on a particular sub-type will be ignored for that row.