Prerequisite

Any base feature (e.g. “Product”) may have other features in its configuration. If one of those other features is a selectable feature (e.g. “Category”), then the “Product” feature items can be categorized using “Category” feature items by creating a custom section in Perfion. In this section user can create a special view, where “Product” items will be shown in the right window and in the left window there will be “Category” items. Then user can select any “Category” feature item in the left window to filter out “Product” feature items in the right window. Example of such custom section use is shown in Figure 1, where CategorizerFeature feature is a “Category” feature (further called categorizer feature) and RelatedFeature is a “Product” feature (further called related feature).

In order to be able to sort related feature items for each categorizer feature item one has to enable “Sortable Related Items” data property for categorizer feature. If this data property is enabled, then one can change the order of related feature items in the right window by using order change buttons “up arrow” (Alt+Up) and “down arrow” (Alt+Down) (refer to Figure 1). After ordering RelatedFeature items for chosen CategorizerFeature item, the order values will be saved to Perfion database. The related feature items can be ordered independently for each categorizer item and related sort order import and export allows to import and export these orders.

Supported Feature Data Types

Related sort order supports the following feature data types:

Compound data type is considered as deprecated while Table and Search data types are not supported, because they cannot have related sort orders.

Supported Feature Data Properties

Related sort orders data import depends on data properties and allows importing data only to those features which meet specifications. The table below shows which data properties are supported.

Import

In this section we will go into details how to specify import data and import related sort orders.

Data Format

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

Related sort order import data format is shown in the table below.

Some other details about import data:

• Data header names are case insensitive.
• Data header order in import data is not important.
• One can comment the data header in import data by using # prefix. For example, data header “#Cat_Feature” will be ignored by importer.
• If “Order” data header is present in import data and all order values are defined, then row order in import data is not important.

Item Base Values

In order to define feature item base value one must define it using the full path from the root item. This is actual only when a feature is hierarchical and has hierarchy. To separate the nodes in the path the pipe (|) character is used.

Example

Example of hierarchical feature and how to define its values. The hierarchical feature is shown in Figure 2. The table below shows how all feature items of HierarchicalFeature can be defined in import data using a full path.

Refer to Example Using Various Order Values below to see an example how hierarchical data can be imported to Perfion.

Node Escaping

Item base value may have any characters if it is a String or Text type feature. In order to be able to distinguish between separate path nodes, the node’s value must not include the character used as a path separator or the path node must be escaped. One can use 4 delimiters (‘, “, $, #) for escaping.

The rules for path node escaping:

Order Determination Rules

The order values for import data items will be determined based on which data is defined in import data. The table below shows how order value will be determined:

 

The steps how the order is determined:

1. Actual order is determined for all items. If order values are not defined in import data (order value is empty or order column is not present) then it will be treated as if it is the maximum possible order value, e.g. 2147483647. This means that any order values defined in import data have priority over not defined values.
2. Items are sorted by actual order. Because not defined values are treated as if they have the maximum possible value, then those values will always be moved to the end of item list after this sorting.
3. Items will be sorted again by item row numbers. The second sorting ensures that all items are sorted correctly in case the actual order has duplicate values. In case order data is not present in import data, all items will have duplicate order values and order will be automatically determined by item row numbers.
4. The new order values are assigned. The importer will determine new order values as a final order values which start from 1 and it will also use sequential order values. The new orders will be reset for each context, which is based on all items which belong to a single categorizer feature item and a single related feature.

The items defined in import data may not include all possible items defined in Perfion. It is allowed to import related sort order data only for some items. In this case the orders for items defined in import data will be set exactly as they are defined in import data and the items which exist in Perfion will be added to the end. The importer will resort all items in Perfion for given context if there is at least 1 item present in import data for that context. The context in this case is all related feature items which belong to a single categorizer feature item and the single related feature. The concept is shown in the table below.

In the table we can see what the final order in Perfion will be after the import. If we look at context 1 data, then we can see that only 3 items out of 6 were defined in the import data, e.g. “Rel. item 1”, “Rel. item 2” and “Rel. item 3”. These items had order in Perfion accordingly: 4, 5 and 6. The other 3 items which exist in Perfion, but were not defined in import data (“Rel. item 4”, “Rel. item 5” and “Rel. item 6”) had order values in Perfion accordingly 3, 1 and 2. The items present in the import data have priority, so these items will be positioned as the first 3 items. The items which were missing in the import data will be added at the end. Moreover, those missing items will be ordered using the same order they were ordered in Perfion. The “Rel. item 5” had order 1, so it will be added as the first item after all items where in the import, e.g. the new order will be 4. Then “Rel. item 6” will be added with order 5 and finally “Rel. item 4” will be added as the last item with order 6.

Refer to Example Using Various Order Values below to see an example of order import.

Data Validation

Related sort order importer first validates all import data and Perfion status, and only then performs the import if there are no errors.

Data referred in import data must exist in Perfion during import. If any referenced data is not present in Perfion at the time of import, or the Perfion data is not correctly set up, the import will not be performed and errors will be reported to the import log.

Import can only handle related sort order values. Related sort order import will not create any new items and will not make any new relations between items. If those items or relations are not present in Perfion, they will be detected as import errors.

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:

• Import data validation. The import data is checked if it has correct columns, if localized columns are defined correctly, if mandatory columns are present, if language codes are valid, etc.
• Feature item identity validation. Each row in import data must have a valid identification data for categorizer and related feature items. These items can be defined either using Perfion IDs or using feature name and feature item base value. In any case, the importer will check if provided data is correct.
• Import scope validation. The import can be limited by defining the import scope, e.g. to limit import to a selected categorizer item, to selected categorizer feature, etc. In this case the importer will check if all import data is within this predefined scope and will report errors if any data was found which is out of scope.
• Duplicate items validation. Importer will check if there are any duplicate items in import data. It will detect possible import issues, when any items from import data cannot be identified in Perfion because of duplicate item base value issues.
• Data type validation. Importer detects features with invalid data types.
• Data property validation. Importer checks if categorizer and related feature data property values meet requirements.
• Order value validation. Importer checks if order values are valid and in the predefined allowed range.
• Stage validation. Importer will check if any of features in import data have stage. Stage is not supported with related sort order importer and it will show warnings to indicate about possible data matching issues.

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

Importer

Related sort order 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 related sort order 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.

All examples will be shown using small amount of data in order to demonstrate the concept of how it can be done, but procedure with large amount of data would be similar.

Example Using Feature Item IDs

In this example we will reorder related feature items for a single categorizer feature. We will use categorizer item “Categorizer item 1” as shown in the Figure 3.

 

In this test we will reverse the order of related items. Instead of having order 1, 2, 3, we will have order 3, 2, 1. The import data is shown in the table below. For this import we use feature item IDs for categorizer feature items and also for related feature items.

After the import of the data from the table, the related feature item order was reversed for the “Categorizer item 1”. Refer to Figure 4.

Example Using Feature Item Values with Different Languages

In this example we will reorder related feature items for a single categorizer feature. We will use categorizer item “Categorizer item 1” as shown in the Figure 5.

In this test we will reverse the order of related items just like in the previous test with IDs. Instead of having order 1, 2, 3, we will have order 3, 2, 1. The import data is shown in the table below. For this import we use feature item base values for categorizer feature items and also for related feature items. Using feature item base values requires adding extra columns with information about features they belong to. In addition to just using feature item base values, we will use localizable values. For categorizer feature items we use DE language and for related feature we will use EN language. Refer to Figure 6 to see the categorizer item “Categorizer item 1” values for different languages.

After the import of the data from the table, the related feature item order was reversed for the “Categorizer item 1”. Refer to Figure 7. Note, that when importing data we can independently select which language to use for categorizer and related feature items.

Example Using Feature Item IDs and Values

In this example we will reorder related feature items for a single categorizer feature. We will use categorizer item “Categorizer item 1” as shown in the Figure 5. Note, this tests is the same as the previous test, but we only going to change how the feature items will be referenced.

In this test we will reverse the order of related items just like in the previous test with base values. Instead of having order 1, 2, 3, we will have order 3, 2, 1. The import data is shown in the table below. For this import we will identify the categorizer feature items using IDs, while related feature items will be identified using base values.

After the import of the data from the table, the related feature item order was reversed for the “Categorizer item 1”. Refer to Figure 7. Note, that when importing data we can independently select how to reference categorizer and related feature items. That means that we can select to reference categorizer feature items by ID or values and do the same for related feature items and the reference type does not have to match in between those 2 types of features.

Example Using Various Order Values

In this example we will reorder related feature items for a single categorizer feature. We will use categorizer item “Categorizer item 1” as shown in the Figure 8.

In this test we will reverse the order of related items. Instead of having order 1, 2,..,9 we will try to get order 9, 8,…, 1. The import data is shown in the table below. For this import we use feature item base values for categorizer feature items and also for related feature items. For this test we will demonstrate how the item ordering is resolved when we define only some order values in import data. Moreover, we will use not sequential order numbers and duplicate order numbers.

Before we perform import we will explain how the order definitions will work in our test. Note, that our target is to reverse all items. First it is important to understand what reversing of all items means when we have hierarchical data. Even though we can freely choose order values for all related items, the sorting of items is independent for each hierarchy level. This means that all items in Perfion will be sorted based on which parent item related items belong to. This also means that we cannot order all values independently so that they all will appear in Perfion in the order we want. Instead, the order will be determined for all items which belong to the same parent independently by Perfion. Hierarchical items cannot just be flattened into a list where all items can be sorted.

In the table below one can see that in our case there are 3 groups of items which will be sorted independently regardless of what order numbers will be defined in other groups. This also means that in order to sort those items correctly we have to provide order numbers relative to each group members. For example, it does not matter what is the order number for related item “Related item 2 - virtual|Related item 5” which belongs to group “Virtual (2) items”  if we want to determine the orders for items belonging to “Root items” group, because those groups are not related and are sorted independently. However, if we want to sort all items in “Root items” group, then all order values given to items belonging to that group are important and should be defined so that they determine desired order. 

The table below shows that empty order values are replaced with maximum possible order value which is equal to 2147483647 (maximum integer value). Importer will also resort all items, so the actual order numbers one gets after import will be as shown in the “Actual Final Order” column. However, by meaning, the order values will be treated by Perfion for each group independently, so one can assume that “the real” orders as perceived by users in Perfion will be as shown in the “Final Order per Group” column. 

Note, there are no difference in between normal and virtual items when sorting orders are applied, so in the “Root items” group all items will be sorted as if they are of the same type.

After the import of the data from the table, the related feature item order was reversed for the “Categorizer item 1”. However, since there are constrains how the hierarchical data can be sorted in Perfion, the items were reversed in their own groups only. Refer to Figure 9.

Example Using Duplicate Feature Items

In this example we will demonstrate how duplicate feature items affect import. We will use categorizer item “Categorizer item 1” as shown in the Figure 10. Note, that there are two related feature items which have the same name, e.g. “Related item 1”. In this situation if the related feature items in import data are defined using base values, then targeting those duplicate related feature items in order to change their order is not possible. In this test we will show what happens if one tries to import such duplicate values. We will also show alternative ways how to do it or how to fix the problem.

The import data is shown in the table below. For this import we use feature item base values for categorizer feature items and also for related feature items. Moreover, in this import we will not use Order column, because it is optional and in this case the order values will be determined based on item row numbers. Duplicate related feature items are shown in red color.

When trying to import the data shown above the importer finds the error and stops the import. Refer to Figure 11 to see the import log and the error it found on line 2. Even from the import data one can see that the first 2 lines are identical and it shows the problem that one cannot determine how to link those items in import data and in Perfion.

Trying to import only one of the duplicate values will also produce import error, because the problem is still the same. The data with only one duplicate related feature item is shown in the table below. Even though import data does not have duplicate import lines, but the Perfion still have 2 related feature items which are identical from their base value perspective and thus, cannot be referenced by using only their base values. The importer will detect this and will stop import. Refer to Figure 12 to see the import log and the error it found on line 1.

Even though Perfion has duplicate values, one can still perform import. Here are several ways how to perform import even when some duplicate values are present in Perfion:

• Import can be done using related feature item IDs. IDs are always unique and this would allow to import data without any issues.
• Import can be done using different language if the related feature is localizable. In some cases different items may have the same value in one language, but different values in another language.
• In case the item has the same value in all languages where this data is used, one can use any other language which maybe is not used in production environment, but which can be used to store the unique item values.
• One can remove duplicate items from import data. If data is not present in the import data, Perfion will find those missing items and will update orders based on their original order values which they had before the import. This will not allow defining specific order values for those duplicate items, but it will allow to perform the import for all other items and those duplicate items will be moved to the end of other items.
• One can remove duplicate items from Perfion. This is the best way to solve this issue, because duplicate values will not allow to perform related sort order export. The export will detect that there are duplicate values and will not allow to export such data, because the data cannot be reimported again. Trying to export the data which has duplicates will produce the error shown in Figure 13.

Export

Export Formats

It is possible to export related sort order 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

Related sort order 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 “Related Sort Order Exporter” will validate Perfion data in order to determine if all data is created correctly and is suitable for export.