Prequisites

Supported Feature Data Types

Feature configurations import supports the following feature data types:

Compound data type is considered as deprecated.

Feature Configuration

Features can be configured to have relations to other features. Based on this configuration there can be two types of features:

• Simple features. If the feature is not configured to have any relations to other features, then it is a normal feature and usually called just a feature, simple feature or normal feature.

• Base features. If the feature is configured to have any relations to other features, then it is called a base feature. Example of base feature is a product feature. In order to define product one has to use many features which may have values important to describe a product, e.g. color, size, price, etc. The base feature still holds its own value of its base type (e.g. String), but by combining the base product feature with other features it becomes a complex feature with many more values originating from all those other features referenced by product feature.

The base features have their configuration, but there can also be features, which belong to other base features.

Feature configurations import supports all feature configuration related data, except feature default values.

The feature configuration window is shown in Figure 1.

Open

Figure 1: Feature configuration

Feature Item Dependency

Feature configuration can be further extended by specifying dynamic configurations which are called item dependencies. Item dependencies can be configured only for selectable type features. Item dependencies allow to add features to configuration dynamically based on which item values the selectable feature has.

In Figure 1 base feature Product have feature Category in its configuration. This feature is selectable and have several predefined values: Accessories, Coffee Machines, Coffee Makers, etc. Under Coffee Machines value there are added 13 features: e.g. Water Tank Capacity and No. of bean containers, while under Coffee Makers value there are other features: e.g. No. of cups and Material. When product data is used anywhere in Perfion, the product configuration will be treated differently depending on which Category feature value is assigned to the product item. If the product item will have Coffee Makers specified as category value, then product configuration will include No. of cups feature to its configuration and when product item will have Coffee Machines, then Water Tank Capacity feature will be included in its configuration. However, in both cases User Guide feature will be also included, because both items depend on it.

Feature Order

The order in which features are added to base feature configuration is important and one can modify the existing order by sliding features up or down in feature configuration window.

Feature Behaviors, Groups, Filters and Views

The features, which have configuration can be further configured to define how the data of those other features related to the base feature will be displayed or handled in different situations in Perfion application or when searching for feature data, etc. This is done by specifying Behaviors, Groups, Filters and Views in feature configuration window for each feature in base feature configuration as shown in Figure 1.

Behaviors, Groups, Filters and Views can be defined only for features in configuration. Feature items (when configuration has item dependencies) are only used as virtual items in configuration.

Configuration Item Types

Feature configuration may have three types of items:

• Feature. A base feature or any other feature in configuration.

• Reversed Feature. This is a regular selectable feature with reversed relation direction. One can reverse relation direction for selectable features in configuration from context menu by choosing “Swap Relation Direction”. Reversed feature cannot have any children configuration items, e.g. it can be only the last node in feature configuration hierarchy.

• Item. A selectable feature item which is used with item dependency to dynamically specify features and/or features with reversed relation direction. It can be assumed as a virtual feature configuration item, which defines a condition for feature configuration. Item type configuration item cannot have order or any other properties such as behaviors, groups, filters or views.

Import

In this section we will go into details how to specify import data and import feature configurations.

The import allows adding new feature configuration values, update existing values and delete existing values.

The feature configuration import will not create or delete any of existing features or feature items during import. In order to import the data to Perfion all features and feature items referenced in the import data must exist.

Data Format

The import data is table like data and can be specified as import data headers and import data values.

Feature configuration import data format is shown in the table below.

ConfigPath Column

ConfigPath column name in the import data can be defined with language indicator or without.

LanguageCode is one of predefined Perfion language codes. Refer to “Perfion Language Codes” manual for supported values. The language code can be two or three characters long. ConfigPath column name may have the following configurations:

• ConfigPath. Column name without language indicator. In this case language will be determined automatically from Admin user language setup in Perfion. In this case the Admin user’s first specified language will be used as default language for configuration import.

• ConfigPath_XX. XX is Perfion language code with two characters, e.g. “ConfigPath_EN”.

• ConfigPath_XXX. XXX is Perfion language code with three characters, e.g. “ConfigPath_DAN”.

The default language specification is important in order to determine how configuration item nodes will be identified in case they belong to the selectable localizable feature. The language specification allows to overwrite default language, but in case there are no nodes of feature item type in any paths in the import data, then defined language value will not be used.

Configuration Path

ConfigPath column value is a string with path of nodes separated with a pipe character (|).

All nodes in the path may be either features, reversed features or feature items.

One row in the import data will define only data for one node, which is defined as the last one in the path. For this node one will have to specify its type and other properties. The types of other nodes will be determined automatically and they define the hierarchical path to the last node.

The value of each node in the path will depend on node type:

• Feature. It can be defined using feature name or ID.

• Reversed feature. It can be defined using feature name or ID, but one must use an extra caret (^) character as prefix, e.g. “^<reversed feature name>”. 

• Feature item. It can be defined using feature item name or ID, but one must surround it using square brackets ([]), e.g. “[<feature item name>]”. Feature item name depends on feature type it belongs to:

  • Not localizable feature. The feature base value should be used as name.

  • Localizable feature. The base feature value in language chosen for configuration import should be used as name.

  • Hierarchical feature. The feature item can be defined using a path if there is more than one hierarchy level, e.g. “[<level 1 item name>|<level 2 item name>]”. The individual nodes in this path can be defined using item names or IDs just like for non-hierarchical items.

Configuration path definition can become complicated, because feature item type nodes may use names, which may have various characters. For example, the configuration path node name may have a pipe character, which is also used as a separator in the path. Moreover, in case the feature item node in the path is hierarchical and defined as a path, then one may have a path, which consist of one or more sub-paths. In order to be able to define paths with various complicated names one can use four delimiters (‘, “, $, #). These delimiters can be used only with feature item type nodes. Feature and reverse feature nodes use unique names, which does not allow special characters and thus, there is no need to use escaping.

The rules for path construction are shown in the table below:

Views Column

Views column value is a product of various Behaviors, Groups, Filters and Views values, which have to be applied to configuration item. The list of available values:

Import allows to specify multiple choices by specifying Views column value, which is a combined value of multiple choices. One can define the value in two ways:

• Numeric value. One can simply use the numeric value from the table directly in the Views column. However, if multiple choice have to be defined, then one has to calculate the final value by summing individual values shown in the table. When adding values, each value can be added only once. For example, to add chosen feature configuration item to ‘Variant’ family view (value = 1024) and ‘Compare’ workflow view (value = 128), one has to set Views column value for selected configuration item to value: 1024 + 128 = 1152.

• String value. One can simply use the string value from the table directly in the Views column. However, if multiple choice have to be defined, then one has to add multiple choices into a single string, by separating all values with a separator ‘;’ (semicolon). For example, to add chosen feature configuration item to ‘Variant’ family view (value = 1024) and ‘Compare’ workflow view (value = 128), one has to set Views column value for selected configuration item to value: Variant;Compare. Note, that string values are not case sensitive and it is also allowed to specify the same value multiple times (duplicates will be ignored).

Action Column

Action column allows specifying the purpose of configuration item in the import data. All items specified for adding or updating will be independent from items which are configured for deletion.

The configuration items for update or delete will be matched with existing items in Perfion and any action will be performed only if there is an exact match based on existing configuration item structure and the starting point for import. In case item for update is not found, it will be added as a new item. All items for deletion must exist in Perfion.

In case the item selected for deletion has children in Perfion, all children items will be deleted.

The configuration items for deletion are processed first and only then insert/update items are processed. If configuration items for deletion and for insert/update are mixed in a single import data, the insert/update items should be specified so, that they match the hierarchy structure after all deleted items are processed. For example, in order to make sure that item ‘a|b|[c]’ is updated correctly, one can first delete ‘a|b|[c]’ item and then insert new. If existing item ‘a|b|[c]’ have children, then such action will clear all children first before inserting new data and the final state of the item will be as defined in import data. If the item is not deleted first, then insert/update procedure will perform an action which is closest to a ‘merge’ action, where existing items will be mixed with incoming items if they do not match, and overwritten when they match (if the item property values have changed).

Data Validation

Configuration import does not create any new features or feature items. Any data referred in import data must exist during import. If any referenced data is not present in Perfion at the time of import, the import will not be performed and error will be reported to the log file. Import can only create/update/delete configuration items.

The import will use many validation rules before it starts to import the actual data. The data will be imported only if validation and data preparation for import is successful. Validation rules:

• Start node reference validation. If import reference configuration is selected (e.g. when user imports data via context menu by selecting a feature or feature configuration item in Perfion) or feature configuration ID is provided (e.g. when performing import via API), it will be checked if it is valid. The existing feature configuration data will be checked if it has any relation to provided reference. Moreover, the reference will be checked if it is valid as a reference configuration, e.g. it should be a selectable feature.

• Import language validation. The language for import is provided as a suffix to ConfigPath column name or automatically from Perfion configuration. If language is manually defined in the import data, then language will be validated.

• The first node in import data should always start with a reference node. One can import feature configuration data only in the context of selected reference and all paths should be relative to that selected reference, e.g. starting with selected reference node. This also means that one cannot alter any other configuration data, which is not related to the reference node.

Validation of reference node is done only when reference node is selected. If import is from a root node (e.g. when user starts import from toolbar menu), then all paths in import data should originate from the root nodes (nodes with parent ID equal to 0).

• All ConfigPath values must be correctly specified. All ConfigPath values must be defined correctly following configuration path definition rules as specified in ConfigPath column description.

• All independent path nodes should exist in Perfion. All path nodes defined in import data as ConfigPath value should exist in Perfion. Several validations will be performed to check this:

  • All feature and reverse feature nodes must match names (or IDs if nodes are referenced using IDs) of the existing features in Perfion.

  • All feature item type nodes must match names (or IDs if nodes are referenced using IDs) of feature items. The feature to which the feature item node belongs to will be determined from the parent node in the path. That feature must have correct data type, e.g. it must be a selectable feature. The chosen import language will be used when determining if the names of feature items match. Moreover, if feature items are hierarchical and are defined using a sub-path with more than one node, then all nodes in that path must exist, e.g. the same rules applies for sub-path nodes as for the configuration path nodes.

• All paths for deletion action must exist. All paths defined for deletion should exist in configuration.

• Duplicate feature item values validation. Feature and reverse feature type nodes do not have duplicates, because all feature names in Perfion are unique. However, for feature item type nodes there can be duplicates. If import will refer to selectable feature items, which have duplicate values in the same hierarchy level, duplicate items belong to the same parent node, and item name is used as a node name, then such item is invalid. Usage of duplicate names creates a risk of ruining the existing configuration data and also importing new data incorrectly, therefore it is illegal to refer to duplicate names when importing feature configurations.

This validation is only performed if feature item type nodes are defined using a name. If Item type nodes are defined using ID, then there are no problems when determining the actual item in Perfion. 

• Duplicate path validation. Import data cannot have the same path defined more than once for a given action type. The ConfigPath column value will be checked if it has any duplicates.

• Any non-existing path validation. The import data must have configuration paths, which have relation to given root node. They must be connected to any of existing configuration items, or they have to be connected to other new incoming configuration items, which are connected to existing nodes.

• Example: In Perfion there exist a root node A and it is also the end node (does not have any children). In import data there are three paths defined: A|B, A|B|[C] and A|B|[C]|D|[E]. The first and second nodes are valid new configuration items, because they both have a connection to existing node A (path A|B) or incoming new configuration item, which is connected (A|B|[C] node is connected to A|B node). However, the third node A|B|[C]|D|[E] is not valid, because it does not have any connections. The node A|B|[C]|D does not exist in configuration and also is not in import data.

• Feature and reverse feature type node can be present in a single path only once. Feature configuration does not allow to define the same feature in a single path twice, so if the feature is already defined in the path, it cannot be defined again.

• Node – parent node type dependency validation. All nodes in the path will be checked if they have correct relation with their parent node. This validation is done for all nodes in the path.

  • Feature and reverse feature type nodes should have feature item type node as parent node or feature type node (in case parent node is a root node).

  • Feature item type node should have feature type node as parent node and the feature of parent node should be selectable.

The import of feature configuration have a concept of all or nothing, which means that failures detected by any of the validations will lead to import failure.

Importer

Feature configuration data can be imported using different types of Perfion importers. Each importer have different requirements so in order to see how data can be imported using the particular importer, please refer to documentation for that importer. The supported importers:

• GUI Importer. GUI Importer can be opened from Perfion application. Refer to “Perfion Import & Export - GUI” manual.

• Actions. The import can be executed by using the IMPORT action command. Refer to “Perfion Actions” manual.

• API. One can implement a custom importer by using Perfion Importer interface. Refer to “Perfion Import & Export – API” manual.

Import Examples

In this section we will show various examples of how feature configuration data can be imported to Perfion.

Import examples will show how to achieve various import goals. We will show the data before the import, the import data and the data after the import. In all examples we use default language EN and base feature - Product.

All examples will be shown using small amount of data to show the concept of how it can be done, but procedure would be the same also with large amounts of data.

The example Product feature configuration in Perfion, which will be used in examples are shown in Figure 2.

Open

Figure 2: Example of Product base features configuration in Perfion

The import data to create such configuration from scratch is shown in the Figure 3.

The same import data as above, but using feature and feature item IDs is shown in Figure 4.

Example Using Reference Configuration Item

Example will show how to import feature configuration data to Perfion when reference configuration is used. Refer to “Import Examples” to see the standard settings used for this example.

Let’s say that “Category” configuration item is selected as a reference configuration for import. When reference configuration is selected, then import scope will only allow to insert/update/delete configuration items, which are under “Category” reference. It will also allow to update the reference itself. Data before import is shown in the table below.

If the reference configuration is selected, then all configuration paths in the import data should start with a start node, which is a configuration reference item. The import data shown below will delete all “Car type 2” items from configuration including all their children.

The result of feature configuration data after the import:

Example without Using Reference Configuration Item

Example will show how to import feature configuration data to Perfion when reference configuration is not used. Refer to “Import Examples” to see the standard settings used for this example.

The data before the import is shown in the table below.

If the reference configuration is not selected, then all configuration paths in import data should start with a root node (e.g. base feature). The import data shown below will delete all “Car type 2” items from configuration including all their children. This example will perform the same import as the previous example (refer to “Example Using Reference Configuration Item”). The difference will be only in how the configuration path is specified.

The result of feature configuration data after the import:

Example Using Sub-paths

Example will show how to import feature configuration data to Perfion when reference configuration is not used. Refer to “Import Examples” to see the standard settings used for this example.

The data before the import is shown in the table below.

The sub-paths must be used if import data targets any configuration items, which have hierarchical feature items in their path. Moreover, those hierarchical items must be referred in import data using item name. Example of import data, which deletes a single configuration item.

The path refers to the feature “PerformanceEngine”, which belongs to “Car type 2” feature item. The “Car type 2” feature item is the third hierarchy level feature item and belongs to virtual feature item “Type”, which belongs to another virtual feature item “2018”.  Note, that sub-path node “2018” is a name of the item and it is numeric. This requires that the node should be escaped with delimiters (single quote in this case) in order to avoid it to be detected as ID.

The import data targeting the same configuration item can be also defined using ID:

In this example, the sub-path for “Car type 2” feature item was replaced with ID= 101675.

The result of feature configuration data after the import:

Example Using Delete Action

Please refer to examples “Example Using Reference Configuration Item”, “Example without Using Reference Configuration Item” and “Example Using Sub-paths”, which all show how to delete data from configuration.

Example Using Add Action

Example will show how to import feature configuration data to Perfion by modifying existing configuration items and adding a new configuration item. Refer to “Import Examples” to see the standard settings used for this example.

The data before the import is shown in the table below.

In this example we will modify the order of the “Category” feature and will add “StandardEngine” feature directly under the base feature “Product”. Note, the import is without using reference configuration.

Note that Action column value by default is set to “Add” if it is not defined, so one does not need to specify it explicitly. Moreover, Action column is optional and can be ignored. It is needed only if there is at least one item in import data, which uses “Delete” action. The action value “Add” corresponds to existing item update and also when new item should be created. The difference of configuration items in import data will be determined when importer will compare the incoming data with existing and will determine which item is for update and which one is new. The import data shown below is equivalent to the one shown above.

The configuration data after the import:

Example Using Add and Delete Actions

Example will show how to import feature configuration data to Perfion by mixing “Add” and “Delete” actions. Refer to “Import Examples” to see the standard settings used for this example.

The data before the import is shown in the table below.

The normal import by only adding or updating existing configuration items will perform an operation, which is known as “merge” operation. That means that importer will determine which item defined in import data exist already in Perfion and will select it for update. If the item in import data is not known in Perfion, then the item will be selected as a new item. However, this approach does not allow to update the absolute configuration item state to a new state, which is fully defined in the import data. Let’s say that one wants to export all feature configurations for backup purposes and then to restore all configurations exactly as they were at backup time. Using standard import this would not be possible, because those configuration items, which were added as new items to configuration after the backup was done, cannot be deleted during import. The import of configuration backup data could restore deleted configuration items, but it cannot delete new items. This is where “Delete” action is useful. The “Delete” action can be mixed with “Add” action in a single import data. If there are “Delete” actions, then these actions will be processed first and only after all deletes were executed, the “Add” actions will be executed. Note, that order of any configuration items in import data is not important.

The import data shown below will completely re-create all configuration items. Note, the import is without using reference configuration.

The results of the import data shown above will lead to exactly the same data as it was before.

Example Updating Views

Example will show how to import feature configuration data to Perfion and correctly specify Views column values. Refer to “Import Examples” to see the standard settings used for this example.

The data before the import is shown in the table below.

In this example we will modify the Views column value. The Views value can be set only for feature or reverse feature type configuration items, so any data specified in Views column for feature item type configuration items will not be used when updating data in Perfion. In this example, we will update “ItemName” and “Category” configuration item Views column values to new values. The new value will add those items to “Filter”, “Detail” and “Variant” views. Note, the import is without using reference configuration.

The numeric value of Views column is calculated like this: Filter (16777216) + Detail (2048) + Variant (1024) = 16777216 + 2048 + 1024 = 16780288.

The configuration data after the import:

Feature Configuration Export

Export Formats

It is possible to export configuration data from Perfion in two different file formats:

• Microsoft Excel (.xlsx)

• XML (.xml)

For more information about file formats refer to “Perfion Import & Export – Data & File Formats” manual.

In addition to export to file one can also export data to DataTable by using Actions command EXPORT or by implementing a custom exporter.

Export Procedure

Feature configuration data can be exported using different types of Perfion exporters. Each exporter have different requirements so in order to see how data can be exported using the particular exporter, please refer to documentation for that exporter. The supported exporters:

• GUI Exporter. GUI Exporter can be opened from Perfion application. Refer to “Perfion Import & Export - GUI” manual.

• Actions. The export can be executed by using the EXPORT action command. Refer to “Perfion Actions” manual.

• API. One can implement a custom exporter by using Perfion Exporter interface. Refer to “Perfion Import & Export – API” manual.

Export Validation

Before the export “Feature Configuration Exporter” will validate Perfion data in order to determine if all data is created correctly and is suitable for export.