Overview

Automatic Imports allow you to schedule regular data ingestion from external sources (URLs) using defined mapping templates and configuration rules. This guide outlines the key workflows for creating and managing these imports.

Navigation

• Automatic Imports: [navigate:/automaticImports|Automatic Imports|upload]
• Import Templates: [navigate:/importTemplates|Import Templates|file-text]

1. Create Basic URL Import

Create an automatic import that fetches data from a URL and imports it using a template.

Entry Point: [navigate:/automaticImports|Automatic Imports|upload] -> Create button -> Automatic Import Editor

1. Click the **Create** button (`data-testid="grid-add-new"`) in the toolbar.
2. In the **Automatic Import Editor**, enter a descriptive name in the `Name` field.
3. Enter the data source URL in the `Url` field.
4. Choose a mapping template in the `Import Template` field.
5. Select `hourly`, `daily`, `weekly`, or `monthly` in the `Frequency` dropdown.
6. Click **Save** to create the schedule.

Data Mapping

2. Create Import with Field Mapping Transformations

Configure an import template to transform source data using expressions.

Entry Point: [navigate:/importTemplates|Import Templates|file-text] -> Edit a template -> Mapper

1. Open the **Mapper** (displayed as "Raw Mapper Syntax" or Configurator).
2. Click on the value of a target field (e.g., `description`).
3. Enter a transformation expression using `${...}` syntax.
4. Check the **Preview** pane (if available) to see the transformed values.
5. Click **Save** in the mapper editor.

**Example Expression:** `${UPPER(name)} - ${TRIM(description)}`

Transformation Syntax

3. Create Import with Nested Relation Handling

Import complex data structures with parent-child relationships (e.g., Products -> Variants).

Entry Point: Mapper

1. Click the `+` button next to a relation field (e.g., `variants`).
2. Click the `+ @loop` button on the nested row.
3. Enter the JSON path to the child array in the source data.
4. Map fields within the nested row relative to the child object.

**Example Path:** `$.variants[*]`

Loop Directive

4. Create Import with Upsert and Conflict Resolution

Configure how existing records are handled during import.

Entry Point: [navigate:/automaticImports|Automatic Imports|upload] -> Edit an import -> Automatic Import Editor

1. Open the **Automatic Import Editor**.
2. In the `Operation` dropdown, select your desired mode.
3. Ensure the `Lookup Field` in the linked Import Template is set to a unique identifier (e.g., `code`, `ean`).

Operation Modes

5. Create Import with Post-Processing Script

Run a custom script after the import to enrich or validate data.

Entry Point: [navigate:/automaticImports|Automatic Imports|upload] -> Automatic Import Editor

1. Open the **Automatic Import Editor**.
2. Locate the `Import Script` field (text area).
3. Write the post-processing logic in the Scripting Language.
4. Save the configuration.

update(product, { "customStatus": "imported" })

6. Create Import with ChangeSet Review

Stage changes for manual approval before applying them to the database.

Entry Point: [navigate:/automaticImports|Automatic Imports|upload] -> Automatic Import Editor

1. Check the `Requires Change Set` checkbox in the **Automatic Import Editor**.
2. When the import runs, it will create a `ChangeSet` instead of applying changes immediately.
3. Navigate to [navigate:/changesets|Changesets|list].
4. Click on the new changeset to view details.
5. Review the "Modified Entities" table and statistics.
6. Click **Apply** to commit or **Reject** to discard.

7. Create Import with Missing Record Handling

Configure the behavior for records that are present in the database but missing from the import feed.

Entry Point: [navigate:/automaticImports|Automatic Imports|upload] -> Automatic Import Editor

1. Open the **Automatic Import Editor**.
2. In the `Handle Missing` dropdown, select the desired behavior.
3. Save the configuration.

Options

8. Create Import with Multi-Source Aggregation

Merge data from multiple sources into a single entity by using multiple Automatic Imports.

1. Create an Automatic Import for "Source A" (e.g., Price Feed) mapping `code` and `price`. Set Operation to `Update Only`.
2. Create an Automatic Import for "Source B" (e.g., Description Feed) mapping `code` and `description`. Set Operation to `Update Only`.
3. Set overlapping or sequential schedules for both imports.

The product record will be enriched by both sources, matched by the `code` field.

9. Create Import with Variable Configuration

Use variables in mapping templates to allow reuse across different imports with different parameters.

Entry Point: Mapper

1. In the **Mapper**, open the Variables configurator (or edit JSON manually).
2. Define a variable (e.g., `defaultCategory`).
3. Use the variable in a field value using `${defaultCategory}`.
4. When creating the `AutomaticImport`, optionally override default variable values (if supported by UI).

10. Create Import with Conditional Record Creation

Conditionally skip or create records based on source data.

Entry Point: Mapper

1. Select the root entity mapping or a specific row in the **Mapper**.
2. Click the `+ @if` button.
3. Enter a condition expression.

**Examples:** `${price > 0}` or `${active == 'true'}`

Behavior

• If the condition evaluates to false, the record (or field) is skipped.
• If true, it is processed.