Feature Data Import - NEW

Introdcution and release versions

The new Feature Data Importer is introduced in Perfion 5.5 2024-R2. In this version, it is only available via the new action command IMPORT.FEATUREDATA.

The user import dialogue mentioned several times below will be introduced in Perfion 5.6 2025-R1.

Definition of Feature Data

Importing Feature Data is a vital function in Perfion. It enables users to import data from excel sheets, and it can be used in a multitude of ways by administrators to import data from other systems or as part of automations.

But what is Feature Data? Simply put, it is the data you see in the Feature Data section of the Perfion client. In Perfion terminology, Feature Data basically means items and their values.

Open

Limitations on data volumes

The new feature data import comes with a set of limitations on data volumens. These have been introduced to make sure all imports are completed in a reasonable time without overloading available hardware resources.

The following limitations apply:

Feature to import to / Base feature

The most basic element of any import is the feature to import to - also known as the base feature. It is the feature you import items to. The base feature is selected by the user in the import dialogue or defined by administrators in actions.

In the screenshot above, Brand (BrandName) is the base feature.

Supported data types for base features

You can import data to almost all selectable features in Perfion (base features) but there are a few exceptions.

Supported data types (base features)

• String

• Number

• Image

• File

• Date

• Table

Unsupported data types (base features)

• Boolean

• Link

• Search

• Text

• Related Value features

• Remote features

Import files

Import files are typically Excel-files consisting of rows, column headers and data cells.

• Rows correspond to items in Perfion,

• Column headers correspond to features,

• Data cells correspond to values.

This very typical import file contains four items, four features and 16 values:

Open

Key Feature

The key feature is used to match rows in the import file with items in Perfion. The key feature is by default the first feature (column) in the import file. You can use either the base feature or an explicit feature as key feature.

Base feature as key

The base feature is typically used as key when base values are unique and you want to create new items and/or update values on existing items.

Possible column headers:

• [BaseFeatureName] Example: Product (_Value is also supported for legacy purposes)

• [BaseFeatureName]_[Language] Example: Product_EN (or _Value_EN)

• [BaseFeatureName].ID Example: Product.ID (or _Value.ID)

• [BaseFeatureID] Example: 100

• [BaseFeatureID]_[Language] Example: 100_EN

• [BaseFeatureID].ID Example: 100.ID

Example

The import file below uses the base feature Product as key. When this file is imported, values (ItemName_EN, Image and WeightKG) are updated for Product items with matcing keys, and new Product items will be created when keys do not exist in Perfion.

NOTES:

• The importer will search for matching key values at all hierarchy levels (if base feature allows hierarchy):

  • If a single match is found, the item is updated (regardsless of hierarchy level)

  • If multiple matches are found, the import will fail

  • If no match is found, a new item will be created at root level (= no parents).

• Please refer to Items in hierarchy for more information about how to create and update items in hierarchy

Explicit feature as key

Most explicit features can be used as key (instead of base feature). This can be useful if base values are not unique and/or if you want to update existing base values with new values in the import file.

Explicit features must comply with these requirements to be used as key:

• String or Number Explicit feature must be either string or number (data type)

• Non-inheritable Explicit feature must be non-inheritable

• Single value Explicit feature must be single value (not allow multiple)

Possible column headers:

• [FeatureName] Example: EAN

• [FeatureID] Example: 101

• [FeatureName]_[Language] Example: ProductName_EN

• [FeatureID]_[Language] Example: 101_EN

Example

The import file below uses the explicit feature EANcode as key. When this file is imported, values (Product, ItemName_EN, Image and WeightKG) are updated for Product items with matcing keys (EANcodes), and new Product items will be created when keys do not exist in Perfion.

NOTE: Using a explicit value as key allows you to update base values. In this example, the base value of the third product will be updated from A102032 to A102032XX. This is not possible when the base value itself is used as key.

Items in hierarchy

If the base feature you import data to allows hierarchy, you can use the column _ParentPath to create and update items inside hierarchies.

When _ParentPath is included in the import file (typically in column B, but it can be in any column), the key value and the value in _ParentPath are “merged” to form a combined key.

Example

The import file below uses Product as key feature and also includes _ParentPath:

The importer will merge the two sets of values to these keys:

• A10|A1020|A102030

• A10|A1020|A102031

• A10|A1020|A102032

• A10|A1020|A102033

When the file is imported, the importer will search for exact mathes to the combined key:

• If a single match is found, the item is updated

• If multiple matches are found, the import will fail

• If no match is found, a new item will be created as a child to the indicated parents

  • NOTE: If one or more of the parent items do not exist, these will be created as well.

The end result in Perfion will look like this:

Updating parent items

Naturally, parent items can also be updated via the import. This is especially relevant when inherited values are managed at parent level(s).

Building on the example above, you might need to set a Brand value at the top parent (A10) and a Color value at the next parent level (A1020). This is achieved with an import file like this:

The end result in Perfion will look like this:

Explicit features

Explicit features hold values that are explicit to each item. Typical examples of explicit features are Item name, EAN code and Weight.

Importing data to explicit features is simple. The basic rule is that values found in import file will replace existing values in Perfion.

Localized explicit features

It is possible to update multiple language versions of the same explicit feature in the same import. This is done by adding the same feature with different language suffix to multiple columns:

Case sensitivity

The importer is case sensitive for explicit values. Example: If item name in Perfion is very nice product no 1 and import file has the value Very nice product no 1, the upper case value from the import file will replace the lower case value in Perfion.

Selectable features

Selectable features hold values that are shared by multiple items. Typical examples of selectable features are Color and Brand.

Importing data to selectable features is - in principle - as simple as for explicit features. Values found in import file will replace existing values in Perfion. In this example, all four products will be assigned the Color value Black and the Brand value NiceBrand:

However, in order for the importer to assign Black and NiceBrand as selectable values to the products, the values must exist in advace in Perfion. If not, the importer by default first creates the needed items belonging to the respective features, and then assign the values to the Product items.

Localized selectable features

The _Language suffix must be used when importing data to localized selectable features. See example with Color_EN above. Unlike explicit features, it is not allowed to update multiple language versions of the same selectable feature in the same import.

Hierarchical selectable features

Selectable features can also be set up to allow hierarchy. This means, that the list of selectable values can be organized in parent-child structures. As an example, this Website feature allows hierarchy:

In order to assign low level Website values to products via import, each value must be specified with its parent path in the import file. Each level in the path must be separated with a Pipe symbol (“|”):

The end result in Perfion will look like this; only the lowest level value is shown:

Case sensitivity

The importer is case insensitive for selectable values. Example: If Color value in Perfion is Black and import file has the value black, the upper case value in Perfion will be assigned to the product.

Exception: If Color value Black does not exist in Perfion, it will be created exactly as written in import file. If import file says black, the value will be created as black.

Importing via selectable IDs

Selectable values can be referenced via their Perfion Item IDs in stead of via their name. This is done by adding .ID as suffix to the header in the import file and specifying Item IDs as values. Example:

When this file is imported, the Brand item with ID 10200 and the Color item with ID 6310 is assigned to the products.

Inheritable features

Inheritable features allow child items to inherit value(s) from a parent item.

Importing data to inheritable features is done by specifying the value for the intended parent or child in the import file. If different values are specified for parents and children, the highest level always wins. All values at lower levels are ignored.

Example: The Color feature is inheritable. Black is specified for the parent product and White is spcified for all lowest level child products:

The end result in Perfion is this; Black is assigned to parent product and White is ignored:

Multivalue features

Multivalue features can hold more than one value for an item.

Importing data to multivalue features is done by separating each value in the import file with a semicolon (“;”). By default, the importer will merge values from the import file with existing values in Perfion.

Example: Country is a multivalue feature (a product can be sold in multiple countries). Products in Perfion all have the value Switzerland:

You now import this file:

The end result in Perfion is that existing and new values are merged:

Escaping multivalue separators

If any value in a multivalue feature contains the semicolon character in its name (e.g. East Territory;West Territory), the semicolon character can be “escaped” with a backslash (“\”) in the import file. This instructs the importer, that the semicolon character is a normal character and not a separator.

Sortable multivalue features

Multivalue features can also be set up to be sortable. This means, that the assigned list of values to a product can be sorted manually rather than alphabetically.

Example: The feature Designers is multivalue and sortable. This was chosen because we want to show the primary designer first on the list. In the import file, designer names are specified in the order we want them (not alphabetically):

The end result in Perfion is that the order from the import file is respected:

Number features

Importing numbers to number features is most often simple. Data formatted as numbers in Excel will be imported as-is to number features in Perfion; you do not need to worry about group and decimal separators. Correctly formatted numbers are right-aligned in Excel:

Multivalue number features

Importing data to multivalue number features is also simple as long as numbers in Excel contain no group or decimal separators. In this example, even though Excel considers the first two values to be strings, all values are imported and accepted as multivalue numbers:

If multivalue numbers in Excel contain group or decimal separators, the importer will throw an error. If you try to import this Excel sheet, you will get the error below:

Please specify a decimal and group-separator for converting a string to a number. Cell: (2,1) / B2.

To overcome this, you must instruct the importer, that dot (“.”) is used as decimal separator and comma (“,”) is used as group separator. This is done in user import dialogue or with a parameter when importing via actions.

String to number and number to string

If there is a mismatch between data format in Excel and data type in Perfion, you may also need to specify group and decimal separators. As with multivalue number features, it is only needed if data in Excel contains at least one comma or dot.

Date features

Importing dates to date features is most often simple. Data formatted as dates in Excel will be imported as-is to date features in Perfion; you do not need to worry about formats. Correctly formatted dates are right-aligned in Excel:

In Perfion, dates will be presented according to your user settings:

String to date features

If dates in Excel sheet are not correctly formatted as dates (but rather as strings), you must specify a date format. You can choose between these formats in the user import dialogue or with a parameter when importing via actions:

Multivalue date features

If you want to import dates to a multivalue date feature, you must also specify a date format. See options above.

Binary features as values

Binary features is a group term for Image and File features. These types of features are identical from an import perspective and are thus described as one. Image features will be used for all examples.

Importing binary files as values

Importing binary files as values on items is easy. In the import file, you simple insert references to the images you want to import:

The end result in Perfion looks like this:

Sources

Binary files can be imported from three different sources:

Multivalue binary features

Importing files to multivalue binary features is done by using semicolon (“;”) as separator. You can mix references to different sources in one cell:

The end result in Perfion looks like this:

Merge or replace

When importing to multivalue (sortable) binary features, new images are by default merged with exiting images. As an alternative, you can choose to replace existing images with images from the import file. This follows the principles described in multivalue features.

Identical or new files?

The importer compares binary files in a more advanced way than it compares normal string values.

Normal string-values are matched by their name. If value in import file is Nice product and value in Perfion also is Nice product, then the two values are considered identical.

For binary files, this is not enough. You could easily have two images called product.jpg showing completely different motives. We must make sure the importer knows that these images are different.

To acheive this, the importer not only compares filenames. It compares all of the following:

Only if all four elements are identical, are two files considered identical.

Binary features as base values

The new feature data importer supports import of binary files as base values. This means that you can add images and files to selectable image and file features - and enrich them with values - simply by stating file references as key values:

The end result in Perfion looks like this:

SWAP features

SWAP features are a special feature “construction” which allows users to maintain two-dimensional data in a single feature on an item. A typical example is Ingredients managed on food products. Please refer to Swap Relation Tables for further details.

Data for swapped features can not be imported as part of a “normal” import to items. This is due to the nature of two-dimensional data which cannot be represented in a single cell in the import file.

In stead, data for swapped features must be imported separately to the swap feature itself and linked to the “owner item” via a reference in the import file. Consider this example, where ingredients data is imported to the Ingredients feature and linked to products:

Notice how a special key feature (IngredientImportKey) with unique values is used. This is required since the base values in the Ingredients feature (Sugar, Salt and Water) are not unique.

The end result in Perfion looks like this. Two products have been created, and a list of ingredients has been added to each product:

When the Ingredients link is clicked in the grid cell, the two-dimensional ingredient list is shown in a grid of its own:

Unique values

Unique value features must have values that are unique across all items in Perfion. Typical examples are Item Number and EAN code.

Unique values are enforced by the importer in two ways:

1. If the import file contains duplicate values for two or more items, the importer stops

2. If a value in the import file is already used on another item in Perfion, the importer stops

Example: This file cannot be imported because EANcode is a unique value feature and two identical values exist in the file:

Default values

Default values can be applied to new items in Perfion when no other values are specified. Default values are also applied when new items are created via import.

Example: The default value for the Country feature is defined to be Denmark. This value is applied to new items when nothing else is specified in the import file. When this file is imported:

…the four new items in Perfion will look like this:

Feature validations

“Hard” feature validation rules (“Reject illegal values”) are enforced by the importer. If a string feature only allows 50 characters, the default behaviour of the importer is to stop if a value in the import file has more than 50 characters.

“Soft” feature validation rules (“Allow illegal values but warn user before saving”) are ignored by the importer, but warnings can be seen in the import log.

Empty cells / delete values

The default behaviour of the importer is to ignore empty cells in the import file. When empty cells are found, existing values in Perfion are left untouched.

This behaviour can be altered by adding the text [DeleteValues] (including square brackets) to individual cells in the import file. This instructs the importer to delete existing values in Perfion. Example: Importing this file will assign Denmark as Country for the first two products, and make sure Country is empty for the last two products:

Ignore columns in import file

By default, all columns in the import file are imported. The importer can be instructed to ignore individual columns by prefixing them with a hashtag character (“#”). In this example, the feature Color_EN will be ignored:

Known limitations

This section briefly describes known limitations to the new feature data import.

Staging

Staging is not supported. If you add the “Stage” feature to the import file, it will be considered a normal feature.

Filtered values

The new feature data import does not support filtered values.

In this example, Green is not a valid color for products in the category Coffee Machines but still specified in the import file:

The end result in Perfion will look like this. The invalid color is imported and marked as invalid:

Moving existing items from one parent to another

The new feature data import does not support moving existing items from one parent to another. This is further described in the section Items in hierarchy.

Import of other Perfion data structures

The new feature data import does not support import of other data structures like Feature Definitions, Feature Configurations, Actions, etc. Import of these structures are handled by separate import functions.