EAV Custom Fields

EAV (Entity-Attribute-Value) is VARIO ERP's system for extending standard entities with custom fields. In shop integrations, EAV is essential for storing platform-specific data — such as external product IDs, sync timestamps, and platform configuration.

What Is EAV?

EAV lets you add custom attributes to standard ERP entities (articles, customers, documents) without modifying the database schema. Custom fields are:

• Namespaced under your app key (e.g., custom.myShop.externalProductId)

• Searchable via VQL queries

• Visible in the ERP UI (if configured)

• Scoped to your app — other apps can't accidentally overwrite your fields

Creating EAV Groups

Define your custom fields during installation using the Migrator:

const { Migrator } = require('@vario-software/vario-app-framework-backend/utils/migrator');

const migrator = new Migrator('install');

await migrator.setMigration('create-eav-groups', async (methods) =>
{
  await methods.createEavGroup('my-shop', {
    key: 'my-shop',
    label: 'My Shop',
    attributes: [
      {
        key: 'externalProductId',
        label: 'External Product ID',
        type: 'TEXT',
        viewMode: 'READ_ONLY',
        active: true,
        fulltextSearchEnabled: true,
        searchIndexEnabled: true
      },
      {
        key: 'lastSyncDate',
        label: 'Last Sync',
        type: 'TEXT',
        viewMode: 'READ_ONLY',
        active: true
      },
      {
        key: 'syncStatus',
        label: 'Sync Status',
        type: 'TEXT',
        viewMode: 'READ_ONLY',
        active: true
      }
    ],
    linkedEntities: ['article']
  });
});

Attribute Properties

Property	Description
key	Unique identifier within the group
label	Display name in the ERP UI
type	Data type (see below)
viewMode	Visibility in the UI: EDITABLE, READ_ONLY, or HIDDEN
active	Whether the attribute is active
fulltextSearchEnabled	Include in fulltext search results
searchIndexEnabled	Include in search index for fast lookups
position	Display order in the UI
description	Description shown as help text

Attribute Types

Type	Description	Use Case
TEXT	Short text string	External IDs, status values
INTEGER	Whole number	Counts, sequence numbers
DECIMAL	Decimal number	Prices, quantities
BOOLEAN	True/false	Flags (synced, active)
DATE	Date only	Sync dates
DATETIME	Date and time	Timestamps

Linked Entities

The linkedEntities array defines which ERP entities your custom fields attach to:

Entity Key	Description
article	Products/articles
crmActivity	CRM activities

Reading Custom Fields

Via VQL

Query custom fields using the custom. prefix:

const { data } = await ErpApi.vql(
  `SELECT
     id,
     articleNumber,
     custom.myShop.externalProductId,
     custom.myShop.lastSyncDate
   FROM article.queryArticles
   WHERE custom.myShop.externalProductId = '${platformProductId}'`,
  {},
  1
);

Via REST API

Custom fields are included in the entity response:

const result = await ErpApi.fetch(`/erp/articles/${articleId}`, {
  useInternalApi: true
});

const externalId = result.data.custom?.myShop?.externalProductId;

Writing Custom Fields

Update custom fields by including them in an entity update:

const article = await ErpApi.fetch(`/erp/articles/${articleId}`, {
  useInternalApi: true
});

article.data.custom.myShop.externalProductId = 'platform-id-123';
article.data.custom.myShop.lastSyncDate = new Date().toISOString();

await ErpApi.fetch(`/erp/articles/${articleId}`, {
  method: 'POST',
  useInternalApi: true,
  body: JSON.stringify(article.data)
});

Using the EAV Module Directly

The framework also provides a lower-level EAV module for managing groups and data:

const ErpApi = require('@vario-software/vario-app-framework-backend/api/ErpApi');

// Get an EAV group by key
const group = await ErpApi.eav.getGroup('my-shop');

// Update an EAV group
await ErpApi.eav.setGroup('my-shop', newData, 'Updated description');

// Modify an EAV group with a callback
await ErpApi.eav.changeGroup('my-shop', (currentData) =>
{
  currentData.someKey = 'newValue';
  return currentData;
});

// Delete an EAV group
await ErpApi.eav.deleteGroup('my-shop');

Common EAV Patterns for Shop Apps

Storing External Platform IDs

Store the platform's ID for each synced entity. This lets you find the corresponding platform resource when you need to update it:

// After creating a product on the platform
await updateArticleCustomField(articleId, 'externalProductId', platformProduct.id);

// When syncing — find the platform product
const externalId = article.custom?.myShop?.externalProductId;
if (externalId)
{
  await platformApi.updateProduct(externalId, transformedData);
}
else
{
  const created = await platformApi.createProduct(transformedData);
  await updateArticleCustomField(articleId, 'externalProductId', created.id);
}

Tracking Sync Status

Use custom fields to track whether an entity has been synced and when:

await updateArticleCustomField(articleId, 'syncStatus', 'synced');
await updateArticleCustomField(articleId, 'lastSyncDate', new Date().toISOString());

Storing App Configuration

Use EAV groups without linked entities to store app-level configuration:

await migrator.setMigration('create-config-group', async (methods) =>
{
  await methods.createEavGroup('my-shop-config', {
    key: 'my-shop-config',
    label: 'My Shop Configuration',
    attributes: [],
    data: {
      lastOrderImportTimestamp: null,
      defaultLanguage: 'de',
      syncEnabled: true
    }
  });
});