Akeneo

Akeneo PIM Developer Documentation: Product Tagging & Enrichment Pipeline

Welcome to the Helium Pulse developer documentation for Akeneo PIM integration. This guide walks you through the end-to-end setup required to enable automated product tagging and enrichment for Akeneo PIM instances. Brands using this integration will configure API access, enabling our system to securely access their product data, flatten complex AI-generated tag structures, enrich product attributes, and sync them back seamlessly.


1. API Client Configuration

1.1 Generating API Credentials

  • To enable our integration, you will need to create a "Connection" within your Akeneo PIM instance (usually under Connect > Connection settings). [3, 4]

  • This connection will generate a Client ID and a Client Secret. [3, 4]

  • Additionally, a Username and Password specific to this connection are generated. [3, 4]

  • Helium Pulse will use these four credentials (Client ID, Client Secret, Username, Password) to authenticate with the Akeneo PIM REST API via an OAuth 2.0 token-based authentication (password grant type). [4, 33, 37] This token allows us to perform enrichment and synchronization tasks.

1.2 Required Permissions (User Roles & API Permissions)

Our integration requires specific API permissions assigned to the user role associated with the generated connection credentials. [3, 8, 24]

Essential permissions typically include:

  • Overall Web API Access: Grants general access to the API. [24]

  • Products:

    • View products: To fetch product data.

    • Create products: (Potentially, if new products are pushed from Helium Pulse, though primary use is updating existing). [29]

    • Edit products: To update product attribute values. [28, 32]

  • Attributes:

    • View attributes: To check for existing enrichment attributes. [11]

    • Create attributes: To create new attributes for storing Helium Pulse data (e.g., h_tags_persona_age_group, h_tags_visual_color_primary_value). [2, 11, 20, 31]

    • Edit attributes: To manage attribute properties if needed. [11]

    • View attribute options: For select-type attributes. [14, 21]

    • Manage attribute options: For select-type attributes. [14]

  • Attribute Groups:

    • View attribute groups: To list existing groups. [11]

    • Create attribute groups: To create a dedicated group for Helium Pulse attributes (e.g., "Helium AI Enrichment"). [11, 16, 31]

    • Edit attribute groups: To assign new attributes to our group. [11, 16]

  • Families:

    • View families: To identify attributes within families. [30]

    • Edit families: To add newly created Helium Pulse attributes to the relevant product families, making them available for products. [1]

  • Categories (Optional, if managing product categorization):

    • View categories

    • Manage categories

These permissions allow us to fetch products, create and manage the necessary attributes for storing enriched data, assign these attributes to product families, and then write the enriched values back to the products. [17]


2. Product Fetching

2.1 Fetch Products via Akeneo REST API

We use Akeneo's REST API to fetch your products. Products are retrieved in batches using pagination (either page-based or search-after for better performance with large catalogs). [12, 13, 19]

GET /api/rest/v1/products?limit=100&pagination_type=search_after&search_after=xxx

2.2 Example Request (Conceptual Node.js using an OAuth token)

const axios = require('axios');

async function getAccessToken(akeneoUrl, clientId, clientSecret, username, password) {
  const tokenUrl = `${akeneoUrl}/api/oauth/v1/token`;
  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

  const response = await axios.post(tokenUrl, {
    grant_type: 'password',
    username: username,
    password: password
  }, {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Basic ${credentials}`
    }
  });
  return response.data.access_token;
}

async function fetchProducts(akeneoUrl, accessToken, searchAfter = null, limit = 100) {
  let url = `${akeneoUrl}/api/rest/v1/products?limit=${limit}&pagination_type=search_after`;
  if (searchAfter) {
    url += `&search_after=${searchAfter}`;
  }

  const response = await axios.get(url, {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    }
  });
  // The actual product data is usually in response.data._embedded.items
  // The next search_after cursor is in response.data._links.next.href (needs parsing)
  return response.data;
}

// Example usage:
// const accessToken = await getAccessToken('https://your-akeneo-instance.com', 'CLIENT_ID', 'CLIENT_SECRET', 'USERNAME', 'PASSWORD');
// const productsPage = await fetchProducts('https://your-akeneo-instance.com', accessToken);

3. Change Detection & Sync Triggers

3.1 Webhook Support (Optional)

Akeneo PIM offers webhook capabilities (Events API), particularly in its Enterprise Edition or through specific bundles, which can be used to listen for product events. [22, 26, 36]

Supported events might include:

  • product.created

  • product.updated

If webhooks are configured, Akeneo can send an HTTP POST notification when products are created or updated. We then use the product identifier from the webhook payload to fetch the full product details.

3.2 Daily Sync Option (Filtering by Update Date)

For instances not utilizing webhooks, or as a fallback, we perform a scheduled sync. We fetch products updated since the last successful sync using the updated date filter. [5, 6, 7, 9]

GET /api/rest/v1/products?search={"updated":[{"operator":">","value":"YYYY-MM-DDTHH:MM:SSZ"}]}&limit=100

4. Enrichment Pipeline & Data Flattening

Once products are fetched, our AI pipeline:

  • Analyzes product identifiers, family, categories, existing attributes (like name, description), and asset information.

  • Generates a rich, structured JSON object containing tags related to persona, usage, functional aspects, and visual details (see example below).

  • Flattens this JSON object: Nested keys are combined with underscores, and a prefix h_ is added. For example, tags.visual.color.primary.value becomes h_tags_visual_color_primary_value.

Example AI-Generated Tag Object:

{
    "sector": "apparel",
    "subcategory": "kurta",
    "category": "tops",
    "tags": {
        "persona": {
            "age_group": ["young adults", "adults"],
            "price_range": "mid-range",
            "gender": ["female"]
        },
        "usage": {
            "season": ["spring", "summer"],
            "occasions": ["everyday", "casual"]
        },
        "functional": {
            "eco_friendly": false
        },
        "visual": {
            "pattern": "checked",
            "material": ["viscose"],
            "color": {
                "primary": {
                    "value": "green",
                    "shade": "medium"
                }
            }
        }
    }
}

Flattened Attributes Ready for Akeneo:

  • h_sector: "apparel"

  • h_subcategory: "kurta"

  • h_category: "tops"

  • h_tags_persona_age_group: ["young adults", "adults"]

  • h_tags_persona_price_range: "mid-range"

  • h_tags_persona_gender: ["female"]

  • h_tags_usage_season: ["spring", "summer"]

  • h_tags_usage_occasions: ["everyday", "casual"]

  • h_tags_functional_eco_friendly: false

  • h_tags_visual_pattern: "checked"

  • h_tags_visual_material: ["viscose"]

  • h_tags_visual_color_primary_value: "green"

  • h_tags_visual_color_primary_shade: "medium"


5. Sync to Akeneo (Product Attributes)

5.1 Attribute Creation & Configuration

Enriched data, after flattening, is stored as Akeneo "attributes." If these attributes do not already exist, Helium Pulse will create them. [2, 17, 31]

  • Attribute Group: We typically create an "Attribute Group" (e.g., "Helium AI Enrichment") to logically group all attributes managed by our service. [11, 16, 31]

    POST /api/rest/v1/attribute-groups
    {
      "code": "helium_ai_enrichment",
      "labels": {
        "en_US": "Helium AI Enrichment"
      }
    }
  • Attribute Creation: For each piece of flattened enrichment data, we create a new attribute. The code will be the flattened key (e.g., h_tags_visual_color_primary_value). Attribute types are chosen appropriately:

    • pim_catalog_text for single string values.

    • pim_catalog_simpleselect for single string values from a predefined list.

    • pim_catalog_multiselect for array string values. [23]

    • pim_catalog_boolean for true/false values.

    POST /api/rest/v1/attributes

    Example 1: Text Attribute

    {
      "code": "h_tags_visual_color_primary_value",
      "type": "pim_catalog_text",
      "group": "helium_ai_enrichment",
      "labels": {
        "en_US": "Helium - Visual Primary Color"
      }
    }

    Example 2: Multi-Select Attribute

    {
      "code": "h_tags_persona_age_group",
      "type": "pim_catalog_multiselect",
      "group": "helium_ai_enrichment",
      "labels": {
        "en_US": "Helium - Persona Age Group"
      }
      // Options for multiselect are added via:
      // POST /api/rest/v1/attributes/h_tags_persona_age_group/options
      // Body: { "code": "young_adults", "labels": { "en_US": "Young Adults" } }
    }

    Example 3: Boolean Attribute

    {
      "code": "h_tags_functional_eco_friendly",
      "type": "pim_catalog_boolean",
      "group": "helium_ai_enrichment",
      "labels": {
        "en_US": "Helium - Functional Eco-Friendly"
      }
    }
  • Family Assignment: Newly created attributes must be assigned to the relevant "Families" to be usable by products. [1, 30, 38]

    PATCH /api/rest/v1/families/{family_code}
    // Payload to add "h_tags_visual_color_primary_value" and "h_tags_persona_age_group"
    {
      "code": "your_family_code",
      "attributes": [
        "existing_attribute1",
        "h_tags_visual_color_primary_value",
        "h_tags_persona_age_group"
        // ... other Helium attributes
      ]
    }

5.2 Updating Product Attribute Values

Once attributes are defined and assigned to families, we update products with the enriched (and flattened) values. This is done via a PATCH request to the product endpoint. [27, 28, 32]

PATCH /api/rest/v1/products/{product_identifier}
{
  "values": {
    "h_sector": [
      {
        "locale": null, "scope": null, "data": "apparel"
      }
    ],
    "h_tags_persona_age_group": [
      {
        "locale": null, "scope": null, "data": ["young adults", "adults"]
      }
    ],
    "h_tags_functional_eco_friendly": [
      {
        "locale": null, "scope": null, "data": false
      }
    ],
    "h_tags_visual_color_primary_value": [
      {
        "locale": null, "scope": null, "data": "green"
      }
    ],
    "h_tags_visual_material": [
      {
        "locale": null, "scope": null, "data": ["viscose"]
      }
    ]
    // ... other flattened attributes
  }
}

The product_identifier is typically the product's unique code or SKU. Akeneo also supports UUIDs for products. locale and scope are set to null if the attribute is not localizable or scopable, otherwise specific values (e.g., "en_US", "ecommerce") are used. [12]


6. Optional: Native Tag-like Injection (Multi-Select Attribute)

While Akeneo doesn't have a separate "tags" entity, a "Multi-Select" attribute (e.g., h_general_keywords) effectively serves this purpose. We can populate this with the most salient keywords derived from the AI enrichment.

The process is:

  1. Ensure a multi-select attribute (e.g., h_general_keywords) is created and added to families (as per section 5.1).

  2. Add options to this attribute for each keyword or allow "options by copy" if your Akeneo version supports it and it's desired. [14, 23]

  3. Update the product's h_general_keywords attribute with an array of keyword strings (as per section 5.2).


7. Daily Enrichment Summary

7.1 Delta CSV & Summary Report

  • Every enrichment cycle generates a CSV file detailing the changes made (Product Identifier, updated attributes (flattened codes), new values, timestamp).

  • A summary report is also created.

7.2 Email Notification

  • An automated summary email is sent daily to your brand team.

  • It includes the number of products enriched and a link to download the CSV report.


8. Best Practices

  • Rate Limits: Akeneo PIM APIs have rate limits (e.g., default is often 100 resources max per request for paginated endpoints). We respect these limits and implement request throttling and retry logic with exponential backoff. [19]

  • Efficient Updates: We use PATCH requests to update only modified attributes, rather than re-sending the entire product payload. [27]

  • Attribute Management: Using a dedicated attribute group (e.g., helium_ai_enrichment) helps organize Helium-generated attributes. All attributes are created with the h_ prefix for easy identification.

  • Error Resilience: Robust error handling and retry mechanisms are implemented for transient API issues.

  • Family and Attribute Management: Proper setup of attributes within appropriate groups and assignment to families is crucial for data visibility and usability within Akeneo. [17, 31]

  • Testing: All integrations are thoroughly tested on development/staging Akeneo PIM instances before deployment to production.


9. Technical References


This documentation can be extended to include:

  • Detailed attribute option management for select/multi-select types, including dynamic option creation.

  • Client-side SDK integration for deeper brand-side observability.

  • Webhook signature validation (if applicable).

  • Advanced error logging and structured retry handling.

For any questions, please contact your Helium Pulse onboarding engineer.

Last updated