Migrator Methods

The Migrator class from the VARIO App Framework provides methods for setting up your app's infrastructure during installation. This reference covers all methods relevant to shop and marketplace integrations.

Creating a Migrator

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

const migrator = new Migrator('migration-key');

The migration-key is a unique identifier for this set of migrations. It's used to track which migrations have already been executed.

Core Methods

setMigration(key, callback)

Executes a migration function once. The framework tracks the execution using the key. On subsequent installations or updates, the migration is skipped.

await migrator.setMigration('create-sales-channel', async (methods) =>
{
  // This code runs only once
  const backend = await methods.createSalesChannelBackend('My Shop', ['ECOMMERCE']);
});

Parameters:

Parameter	Type	Description
key	string	Unique migration identifier
callback	function	Async function receiving a methods object

always(key, callback)

Executes a function every time the migration runs (on every install/update). Use this for things that should always be up to date, like app scripts or webhook URLs.

await migrator.always('update-scripts', async (methods) =>
{
  // This code runs on every install/update
  await methods.addAppScriptingTrigger(scriptTrigger);
});

Sales Channel Methods

createSalesChannelBackend(label, validChannelTypes)

Creates a sales channel backend for your app. There should be exactly one backend per app.

const backend = await methods.createSalesChannelBackend(
  'My Shop Platform',     // Display label
  ['ECOMMERCE']           // Array of valid channel types
);

Returns: Backend object with id and other properties.

createSalesChannel(backend, label, description, channelType)

Creates a sales channel under a backend.

const channel = await methods.createSalesChannel(
  backend,                // Backend object from createSalesChannelBackend
  'Online Store',         // Display label
  'Primary connection',   // Description
  'ECOMMERCE'             // Channel type (must be in backend's validChannelTypes)
);

Returns: Sales channel object.

activateSalesChannelBackend(backend)

Activates a sales channel backend, enabling its channels.

await methods.activateSalesChannelBackend(backend);

changeSalesChannelBackend(body)

Updates an existing sales channel backend.

await methods.changeSalesChannelBackend({
  id: backend.id,
  label: 'Updated Name',
  validChannelTypes: ['ECOMMERCE', 'B2B']
});

findSalesChannelBackend()

Finds the APP-type sales channel backend for the current app.

const backend = await migrator.findSalesChannelBackend();

Returns: Backend object or null.

getSalesChannels()

Returns all sales channels for the current app.

const channels = await migrator.getSalesChannels();

Returns: Array of sales channel objects.

getSalesChannelBackend(id)

Returns a specific sales channel backend by ID.

const backend = await migrator.getSalesChannelBackend(backendId);

EAV Methods

createEavGroup(key, data, description)

Creates an EAV group for storing custom data.

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,
      position: 1
    }
  ],
  linkedEntities: ['article']
}, 'My Shop custom fields');

getEavGroup(key)

Retrieves an EAV group by key.

const group = await methods.getEavGroup('my-shop');

changeEavGroup(key, callback)

Modifies an EAV group using a callback pattern:

await methods.changeEavGroup('my-shop', (currentData) =>
{
  currentData.attributes.push({
    key: 'newField',
    label: 'New Field',
    type: 'TEXT'
  });
  return currentData;
});

deleteEavGroup(key)

Deletes an EAV group and all its data.

await methods.deleteEavGroup('my-shop');

removeDataFromEavGroup(key, attributes)

Removes specific attributes from an EAV group without deleting the group.

await methods.removeDataFromEavGroup('my-shop', ['oldField1', 'oldField2']);

Webhook Methods

registerWebhook(destinationQueue, url, destinationOwner)

Registers a webhook to receive ERP event notifications.

await methods.registerWebhook(
  'article.update',                    // Event type
  '/api/webhooks/article-update'       // Endpoint path (relative to rootUrl)
);

With custom destination owner:

await methods.registerWebhook(
  'article.update',
  '/api/webhooks/article-update',
  'SYSTEM'                             // Destination owner
);

deregisterWebhook(destinationQueue, url, destinationOwner)

Removes a previously registered webhook.

await methods.deregisterWebhook(
  'article.update',
  '/api/webhooks/article-update'
);

Import Preset Methods

createMultipartImportPreset(template)

Creates an import preset for the MultiPart Import API.

await methods.createMultipartImportPreset({
  name: 'My Shop Order Import',
  entity: 'account-order'
  // ... additional template configuration
});

updateMultipartImportPreset(id, template)

Updates an existing import preset.

await methods.updateMultipartImportPreset(presetId, {
  name: 'My Shop Order Import v2',
  entity: 'account-order'
  // ... updated configuration
});

Text Enum Methods

createTextEnumGroup(key, description, enums)

Creates a group of text enumerations (dropdown options):

await methods.createTextEnumGroup(
  'my-shop-order-statuses',
  'Order statuses for My Shop',
  [
    { value: 'new', label: 'New' },
    { value: 'processing', label: 'Processing' },
    { value: 'shipped', label: 'Shipped' },
    { value: 'delivered', label: 'Delivered' }
  ]
);

App Scripting Methods

addAppScriptingTrigger(trigger)

Registers a server-side script trigger in the ERP.

await methods.addAppScriptingTrigger({
  code: 'beforeCreateOrder',
  script: scriptContent,
  // ... trigger configuration
});

updateAppScriptingTrigger(id, trigger)

Updates an existing scripting trigger.

getAppScriptingTriggerId(code)

Gets the ID of a scripting trigger by its code.

Finance Backend Methods

createFinanceBackend(label)

Creates a finance backend for payment processing.

await methods.createFinanceBackend('My Shop Payments');

changeFinanceBackend(label, description)

Updates a finance backend.

await methods.changeFinanceBackend('My Shop Payments', 'Updated description');

Usage Example: Complete Shop Installation

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

async function runMigrations()
{
  const migrator = new Migrator('install');

  // One-time: Create sales channel infrastructure
  await migrator.setMigration('setup-sales-channel', async (methods) =>
  {
    const backend = await methods.createSalesChannelBackend('My Shop', ['ECOMMERCE']);
    await methods.createSalesChannel(backend, 'Default Store', 'Primary connection', 'ECOMMERCE');
    await methods.activateSalesChannelBackend(backend);
  });

  // One-time: Create EAV custom fields
  await migrator.setMigration('create-eav-fields', 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 }
      ],
      linkedEntities: ['article']
    });
  });

  // One-time: Register webhooks
  await migrator.setMigration('register-webhooks', async (methods) =>
  {
    await methods.registerWebhook('article.update', '/api/webhooks/article-update');
    await methods.registerWebhook('stock.update', '/api/webhooks/stock-update');
    await methods.registerWebhook('article-price.update', '/api/webhooks/price-update');
    await methods.registerWebhook('sales_channel.create', '/api/webhooks/sales-channel-create');
    await methods.registerWebhook('sales_channel.delete', '/api/webhooks/sales-channel-delete');
  });

  // One-time: Create import preset
  await migrator.setMigration('create-import-preset', async (methods) =>
  {
    await methods.createMultipartImportPreset({
      name: 'My Shop Order Import',
      entity: 'account-order'
    });
  });
}