Configuration Flow

Before you can leverage Trustana's AI-powered enrichment capabilities, your account must be properly configured through a structured setup process. This configuration creates the foundation that drives all enrichment workflows and determines how products are processed through the system.

Configuration-First Architecture

Trustana requires complete configuration setup before API integration becomes meaningful. The quality and scope of your enrichment results depend entirely on how well the category tree and attribute system are configured. For hands-on API integration guidance, see Getting Started.

Account Prerequisites Workflow

The following six-step process must be completed before OpenAPI integration can begin:

Step-by-Step Prerequisites

1. Account Creation

Initial account provisioning with basic organizational settings and user access configuration.

2. Category Tree Import

Upload or configure your product taxonomy structure with proper hierarchical relationships. Trustana CS team will provide assistance on this step.

3. Attribute Import/Creation

Define the complete set of attributes that will describe your products across all categories. This can be done through the web interface.

4. Attribute Configuration

The most critical step involving:

• Category Mappings: Link attributes to specific categories (global scope or targeted to root, branch, or leaf nodes)
• Dictionary Setup: Configure validation rules and dropdown values
• AI Configuration: Enable for Enrichment and define instructions for each attribute

5. OpenAPI Key Generation

Generate secure API keys through the Portal interface for programmatic access.

6. Account Ready for OpenAPIs

With configuration complete, APIs can retrieve the setup and begin processing products according to the defined structure.

Category Tree System

The category tree serves as the backbone of Trustana's classification and enrichment system. Each category node contains specific data that drives both AI understanding and system integration.

Category Data Structure

Every category in the tree contains five essential components:

Field	Purpose	Example
ID	Unique identifier for API reference (sourced from customer data or auto-generated during upload)	5192
Node Name	Human-readable category name	"Smartphones"
Parent	Hierarchical relationship reference	166 (Mobile Devices)
Description	AI context defining category scope, including what products belong and exclusion criteria	"Mobile communication devices with advanced computing capabilities. Exclude tablet devices or pocket computers."
Reference	External system integration identifier (non-unique, used for mapping)	"MOBILE_SMART"

Hierarchical Structure Example

Attribute System Architecture

Trustana's attribute system supports multiple data types and follows a sophisticated hierarchy that determines which attributes apply to which products based on their category classification.

Attribute Types

User-Configurable Types

Type Name	Type	Description	Use Cases
Number	NUMBER	Numeric values with optional units	Weight, dimensions, quantity
Price	PRICE	Monetary values with currency support	Product price, MSRP, cost
Short Text	TEXT	Brief text fields (typically 255 chars), plain text	Product names, SKUs, references
Long Text	LONG_TEXT	Extended text content, multi-line and plain text	Product descriptions, specifications, ingredients
RTF	RICH_TEXT	HTML-based rich text with optional HTML templates	Marketing copy, detailed descriptions
Date	DATE	Date values without time	Launch date, expiration date
Date-time	DATETIME	Complete timestamp	Created date, last synchronized
URL	URL	Web address validation	Storefront Product pages, documentation links
Dropdown	DROPDOWN	Single selection from predefined values	Color, size, category
Multiselect	MULTI_SELECT	Multiple selections from predefined values	Features, certifications, tags

System-Only Types

These attribute types are managed by Trustana and not user-configurable:

• MEASURE: Dimensional data with units (length, weight, volume)
• TREE_NODE: Category assignment ID, only leaf-nodes selectable.
• MEDIA_GALLERY: Image and document collections, sorted list of IDs.

Default Attributes

Every Trustana account includes a fixed set of class default attributes that apply to all products:

Attribute Name	Attribute Key	Description	Required
Product Name	name	Primary product identifier for display and search	Required for creation
Brand	brand	Manufacturer or brand name (essential for enrichment processing)	Required for creation
Description	description	Basic product description content	Optional
Price	price	Product pricing and monetary information	Optional
Supplier SKU	supplierSku	External system reference identifier	Optional
Trustana ID	skuId	Internal platform identifier	System-generated
Product Category	productCategory	Category tree node assignment (required for enrichment workflows)	Optional
Google Category	googleCategory	Alternative taxonomy classification system	Optional
Images	media	Media gallery supporting up to 100 images per product record	Optional
Product Model	productModel	Global brand-specific identifier used for cross-platform product discovery (essential for enrichment processing)	Optional

These attributes ensure basic product data consistency across all accounts and categories.

Attribute Assignment Hierarchy

The system determines which attributes apply to each product through a sophisticated hierarchy that considers global, inherited, and direct attribute assignments.

Assignment Types

Global Attributes

• Assignment: Not linked to any specific category (category = null)
• Scope: Apply to all products regardless of category
• Purpose: Universal attributes like Product Name, Brand, Price

Inherited Attributes

• Assignment: Linked to parent categories in the hierarchy
• Scope: Apply to all products in child categories
• Purpose: Broad attributes relevant to entire product families

Direct Attributes

• Assignment: Linked specifically to the product's exact category
• Scope: Apply only to products in that specific category
• Purpose: Highly specific attributes for precise categorization

Applicable Attributes Calculation

For a product in category 5192 (Smartphones), the system calculates:

Applicable Attributes = WHERE attribute.customcategories IN (null, 100, 166, 5192)

This means the product receives attributes assigned to:

• null (Global)
• 100 (Electronics - top-level parent)
• 166 (Mobile Devices - direct parent)
• 5192 (Smartphones - direct category)

API Implementation

To retrieve these applicable attributes via the API, use the /v1/attributes/search endpoint:

Request:

POST /v1/attributes/search
{
  "filter": {
    "linkedCategories": ["5192"],
    "categoryScopes": ["GLOBAL", "INHERITED", "DIRECT"]
  },
  "pagination": {
    "limit": 100,
    "offset": 0
  },
  "sort": {
    "field": "createdAt",
    "order": "DESC"
  }
}

Where:

• linkedCategories: ["5192"] - The leaf node category ID for Smartphones
• categoryScopes - Returns attributes from:
  • GLOBAL - null (applies to all products)
  • INHERITED - 100, 166 (parent categories)
  • DIRECT - 5192 (exact category match)

This returns all attributes applicable to products in the Smartphones category.

Enrichable Attributes

Not all applicable attributes are eligible for AI enrichment. The system applies additional filters to determine which attributes should be processed by the enrichment engine.

Enrichment Protection and Best Practices

The enrichment system does not override user-added or user-modified values to preserve manual data integrity. This creates important workflow considerations:

Source vs Enriched Attributes Strategy:

• Source Attributes: Create a set of attributes for importing/adding contextual data that users control
• Enriched Attributes: Create separate attributes specifically designed for AI-generated content
• Approval Impact: Once an enriched attribute is approved on a product, that attribute becomes not eligible for re-enrichment

Example Implementation:

• description_source (user-provided context) → description_enriched (AI-generated)
• specifications_raw (imported data) → specifications_formatted (AI-enhanced)
• features_input (basic list) → features_marketing (SEO-optimized)

This dual-attribute approach ensures clean separation between human-controlled data and AI-generated content while providing maximum enrichment flexibility.

Enrichment Eligibility Criteria

An attribute becomes "enrichable" when it meets these conditions:

1. Category Applicable: Must be in the applicable attributes set (global + inherited + direct) for a product
2. Custom or Library Type: Must be CUSTOM or LIB attribute class
3. AI-Enabled Toggle: Must have the AI enrichment toggle enabled in configuration

Variant Product Handling

For variant products (child products with variations), the system applies additional filtering:

1. Variant-specific Attributes: From applicable attributes, only those marked as "variant-specific".
2. Mixed Use-Case: Variant-specific attributes also apply to parent products as well to support simple product, which are both 'parent and variant' in one record.

SPU vs SKU Data Inheritance

Attributes without the variant-specific flag will be enriched at the parent level and the values automatically inherited down to all variants. This is particularly useful for handling SPU (Standard Product Unit) level data that applies to the entire product family.

SPU Level Data (Parent → All Variants):

• Product descriptions and marketing copy
• Brand information and product model
• Technical specifications and features
• Category classifications and certifications

SKU Level Data (Variant-Specific):

• Size, color, style variations
• Individual pricing and availability
• Variant-specific images and measurements
• SKU-specific inventory and shipping data

Example: A "Nike Air Max 90" parent product gets enriched with brand story, technical features, and marketing descriptions. These enriched values automatically inherit to all variants (different sizes/colors), while each variant maintains its own size, color, and price attributes.

Example: Parent Product with Variants

• 40 total applicable attributes
• 10 marked as variant-specific (size, color, etc.)
• 8 variant-specific attributes have AI enabled
• Variant Enrichable Attributes: 8

Configuration Impact on API Integration

Your configuration choices directly influence how the APIs function and what data validation occurs:

API Behavior Effects

Configuration Aspect	API Impact
Category Hierarchy	Determines valid category assignments for products
Attribute Types	Defines expected data formats and validation
Enrichment Targets	Determines which fields will be populated by AI
Global vs Direct Attributes	Affects product validation across different categories

Next Steps

Now that you understand Trustana's configuration architecture:

✨ Learn More

• Enrichment Service: Understand how AI processing works with your configured attributes
• Portal Overview: Explore the Portal interface where configuration happens

🛠️ Start Building

• Getting Started: Set up API authentication and explore your account configuration
• Creating Products: Apply configuration concepts to product creation workflows
• Creating Variants: Understand how variant-specific attributes work in practice

📖 Reference

• API Reference: Interactive documentation for all configuration and product endpoints

---

Understanding configuration is essential for successful Trustana integration. The concepts covered here directly influence how your product creation workflows and enrichment processes will function.