Mapping Strategies

Mapping is the process of translating entities between VARIO ERP and the external platform. Payment methods, shipping methods, customer groups, categories, and other entities rarely have the same identifiers or structures in both systems. A mapping configuration bridges this gap.

What Needs Mapping?

Entity	ERP Side	Platform Side
Payment methods	ERP payment method ID	Platform payment key (e.g., "credit_card", "paypal")
Shipping methods	ERP shipping method ID	Platform shipping key (e.g., "standard", "express")
Customer groups	ERP customer group ID	Platform customer group (e.g., "wholesale", "retail")
Categories	ERP category tree	Platform category/collection IDs
Tax rates	ERP tax rate IDs	Platform tax zone/rate IDs
Units	ERP unit codes	Platform unit labels
Languages	ERP language codes (ISO)	Platform locale codes
Currencies	ERP currency codes	Platform currency codes
Order statuses	ERP document statuses	Platform order statuses

Mapping Storage

Store mappings as structured data in an EAV group, scoped to the sales channel:

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

// Save a mapping
async function saveMapping(salesChannelId, mappingType, mappings)
{
  const groupKey = `my-shop-mappings-${salesChannelId}`;

  await ErpApi.eav.changeGroup(groupKey, (data) =>
  {
    data[mappingType] = mappings;
    return data;
  });
}

// Retrieve a mapping
async function getMapping(salesChannelId, mappingType)
{
  const groupKey = `my-shop-mappings-${salesChannelId}`;
  const group = await ErpApi.eav.getGroup(groupKey);

  return group?.data?.[mappingType] || [];
}

Mapping Data Structure

A mapping is typically an array of pairs linking ERP IDs to platform IDs:

const paymentMappings = [
  {
    erpId: 'erp-payment-uuid-1',
    erpLabel: 'Credit Card',
    platformId: 'credit_card',
    platformLabel: 'Credit Card'
  },
  {
    erpId: 'erp-payment-uuid-2',
    erpLabel: 'PayPal',
    platformId: 'paypal',
    platformLabel: 'PayPal'
  },
  {
    erpId: 'erp-payment-uuid-3',
    erpLabel: 'Invoice',
    platformId: 'invoice',
    platformLabel: 'Pay by Invoice'
  }
];

await saveMapping(salesChannelId, 'paymentMethods', paymentMappings);

Using Mappings in Sync

Order Import (Inbound)

When importing orders, resolve platform payment and shipping IDs to ERP IDs:

async function resolvePaymentMethod(salesChannelId, platformPaymentId)
{
  const mappings = await getMapping(salesChannelId, 'paymentMethods');
  const match = mappings.find(m => m.platformId === platformPaymentId);

  if (!match)
  {
    throw new Error(`No mapping found for payment method: ${platformPaymentId}`);
  }

  return match.erpId;
}

Product Sync (Outbound)

When syncing products to the platform, map ERP categories to platform categories:

async function resolveCategoryMapping(salesChannelId, erpCategoryId)
{
  const mappings = await getMapping(salesChannelId, 'categories');
  const match = mappings.find(m => m.erpId === erpCategoryId);

  return match?.platformId || null;
}

Building a Mapping UI

Provide a settings page where users can configure mappings:

1. Fetch options from both sides — Query ERP entities (payment methods, shipping methods, etc.) and platform entities

2. Display side-by-side — Show ERP options on the left, platform options on the right

3. Let users connect — Allow drag-and-drop or dropdown selection to create pairs

4. Save the mapping — Store the mapping configuration for this sales channel

Fetching ERP Options

// Get payment methods from ERP
app.apiServer.get('/mappings/payment-methods/erp', async (req, res) =>
{
  const { data } = await ErpApi.vql(
    `SELECT id, label FROM masterdata.paymentMethods WHERE active = true`,
    {},
    100
  );

  res.json(data);
});

Fetching Platform Options

// Get payment methods from the platform
app.apiServer.get('/mappings/payment-methods/platform', async (req, res) =>
{
  const salesChannelId = req.headers['x-sales-channel'];
  const platformPayments = await platformApi.getPaymentMethods();

  res.json(platformPayments);
});

Category Mapping

Categories deserve special attention because they are hierarchical. ERP and platform may have completely different category trees.

Strategies:

• Flat mapping — Map individual categories regardless of hierarchy. Simple but may lose structural information.

• Tree mapping — Map parent categories and let children inherit. More complex but preserves structure.

• Default category — Assign a default platform category for products that don't have a mapping. Prevents sync failures.

Fallback Values

For essential mappings (payment methods, shipping methods), define fallback values to prevent import failures when a mapping is missing:

async function resolvePaymentMethodWithFallback(salesChannelId, platformPaymentId)
{
  const mappings = await getMapping(salesChannelId, 'paymentMethods');
  const match = mappings.find(m => m.platformId === platformPaymentId);

  if (match)
  {
    return match.erpId;
  }

  // Fallback to default payment method
  const defaultId = await getChannelParameter(salesChannelId, 'DEFAULT_PAYMENT_METHOD');
  if (defaultId)
  {
    return defaultId;
  }

  throw new Error(`No mapping or fallback found for payment method: ${platformPaymentId}`);
}