Feature Defintion Import

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

The import allows adding new features to Perfion and/or updating features which already exist in Perfion.

Data Format

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

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

ControlType Column Values

ControlType values depend on various parameters and not all values can be used with any data. The table below provides more information about each control type value (editor) requirements.

Default value can be selected for any feature and it is a default editor.

In order to know if an editor is suitable for a feature there are four parameters which determines if an editor can be selected or not: feature data type and then three data properties: Selectable, Multi-value and Formula.

General Feature Definition Importer Data Handling Rules

The importer does a lot of things and handles data in various ways. The list below will describe general concepts and rules of how it works:

• The import data column order is not important.

• There can be no duplicate or empty columns in the import data.

• The columns in the import data are optional (except Feature column, which is mandatory). If the column is not defined, it is treated as if the column is present with all empty values.

• The column names are case insensitive.

• The order of rows in the import data is not important. The features in Perfion are hierarchical and the importer will process the data based on import data hierarchy starting from roots and ending with leaves to determine in which order rows have to be processed.

• Prefixing import data column name with ‘#’ (hash) character allows ignoring unwanted columns during import without physically removing them from the import data.

• The importer for creation of new features uses value inheritance and default values. The general concept how this works:

  • If the import item has a value defined in the import data for a column (value is not empty), then that value will be used regardless if the import item has parent defined or not. In case of feature identity inheritance, if parent and child must have the same values, then validation process will compare both and will report an error if values do not match.

  • If the import item has no parent (it is a root item) and there is no value defined in the import data for a column (or column is not present in the import data), then importer will use a default value.

  • If the import item has a parent and there is no value defined in the import data for a column (or column is not present in the import data), then importer will use parent’s value. This rule is not valid for translatable data.

• In case the import data has a new parent and child features, then they will be dependent from each other. The parent feature will be processed first, while the child feature will be processed in the next iteration. However, if the parent feature have invalid data, then child feature will also be selected as invalid feature, because of invalid parent.

• The importer creates new features and updates existing features.

  • The importer will use all import data columns when creating new features.

  • When updating existing features, the importer will use only those import data columns, which are defined as updatable. The importer will ignore all other columns even if they have data. The importer will not check if not updatable column values match actual feature definition values in Perfion.

  • The importer first updates all existing features and then creates new features.

  • The importer will update existing features in Perfion only if there are changes in the import data as compared to data in Perfion.

  • The importer will update existing feature values in Perfion only if values are defined, e.g. are not empty.

  • Importer does not support deletes, e.g. one cannot delete existing translatable property value.

• The importer first processes and validates all data and only then makes actual updates in Perfion database.

• The importer use all or nothing concept. If there is at least one error, the import will not be performed. In this case errors will be presented to user in the import log.

• Feature and parent can both be imported/updated using name or ID. One can also mix these in the same import data, e.g. one feature can be referred using name, while another using ID. The same is also valid for the data from the same row, e.g. feature can be referred by name, while parent using ID.

Data Validation

Feature definition import first validates all import data and Perfion status, and only then performs the import if there are no errors. Data referred in the import data (e.g. groups) 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 log file.

Import can only create or update feature definitions. Feature definition deletes are not supported.

The import will use many validation rules before it starts importing 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, etc.

• Feature identity validation. Each row in the import data must have a valid identification data, which is feature name or ID and also parent name or ID. If data is defined using ID, then data must exist in Perfion. If identification is defined using name, then it should be a valid name.

• Feature hierarchy validation. The importer will process all import data items and will analyze the hierarchy. At the same time it will determine if there are any import items which are not connected to any other import data items or to any existing features in Perfion.

• Duplicate items validation. Importer will check if there are any duplicate items in the import data. The importer will resolve all import items regardless if feature is defined using name or ID. The validation ignores the letter casing when comparing feature names.

• Data type validation. Importer detects features with invalid data types and also if data types does not match for child and parent.

• Information group validation. Importer checks if security group is defined and also if information groups defined in the import data match any existing information groups in Perfion. Moreover, the importer will check if Perfion configuration is in order from information group perspective. If information group setup is invalid in Perfion, then import will stop with error.

Information group setup in Perfion is invalid when information groups have duplicate group names for the same language or when groups do not have any name defined for selected language. The importer checks this only for those information groups, which are actually referred in the import data. The similar information group validation is also done in feature definition export.

• Data property validation. Importer checks if data property values defined in the import data can be used for a feature based on feature’s data type and other parameters.

• Control type validation. Importer checks if control type (feature data editor) is supported based on feature’s data type and data properties.

• Translation property validation. Importer checks translation properties in order to determine if caption data is present for selected language in case there are other translation properties for creation/update for the same language.

• Identity inheritance validation. Importer checks that parent and child feature definitions are defined correctly in relation to identity inheritance concept. Some data properties should match, some can be independently controlled. The importer will determine if the rules are not violated.

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

Importer

Feature definition 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 “Import / Export GUI” manual.

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

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

Import Examples

In this section we will show various examples of how feature definition 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 Inheritance and Default Values

In this example we create two new features. The first feature is a parent feature (TestFeatureParent) and the second feature is a child feature (TestFeatureChild). The purpose of this example is to demonstrate how data inheritance and default values are assigned automatically during import. The import data is shown in the table below:

To understand better how automatic data value assignments work during import we can define another import data, which is equivalent to the previous import data, but where all automatically assigned values are shown as they will be used by the importer.

Automatic value assignments:

• Values shown in green color are default values. Feature “TestFeatureParent” is a root feature and has no parents, so all of feature’s empty values in import data will be replaced with default values (except translatable properties, which does not have default values). In this case “Inheritable” and “Formula” data properties were assigned default values accordingly “1” and “0”.

• Values shown in red color are values inherited from the parent feature. Feature “TestFeatureChild” is a child feature to “TestFeatureParent” feature. Most of values which are not defined for a feature which has a parent will be replaced with parent feature’s values. The only exception is translatable property values, which are not inheritable. In this example, the feature “TestFeatureChild” will inherit the “DataType”, “SecurityGroup_EN”, “Localizable” and “Inheritable” data values from the parent feature.

• Value shown in orange color is a value, which is explicitly specified in import data and which is not inherited from the parent feature. “TestFeatureChild” feature has value “1” defined in import data and this means that value will not be overwritten from the parent feature, which has “Formula” data property value set to “0”.

• A value shown in the blue color will not get any default value and will not be inherited from the parent feature. “Caption_EN” is translatable property and it does not have any default value (or it can also be assumed as empty value) and will not inherit values from the parent feature. In this case it was not specified for a child feature and it will stay that way.

Import log is shown in Figure 6.

Open

Figure 6: Example using inheritance and default values import log

Both features will be imported to Perfion and their definitions are shown in Figure 7.

Open

Figure 7: Parent vs child features after import

Example Importing Existing Feature vs. New Feature

In this example we use one existing feature and one new feature. Both features are independent from each other, but during import the existing feature will be updated while the new feature will be created. Both actions will be performed during the same import, so one does not have to separate this data into two different import files.

The purpose of this example is to demonstrate how existing and new features are processed during import.

The existing feature definitions before import are shown in the Figure 8.

The import data is shown in the table below:

The data marked in different colors will be evaluated by importer in some special way:

• Fields marked with orange color will be ignored by importer, because the feature is an existing feature and those fields are not updatable. Even though if the data is explicitly defined in those fields, the fields will not be evaluated by importer.

• Fields marked with green color are updatable fields. These fields will be used by importer when updating the existing feature, however, any values which are empty will not be updated. In this case the importer will not overwrite the value with a default value which would be the case with a new feature import, but instead it will keep the existing value from Perfion.

 After the processing of import data, the importer will treat the data as if there were two different imports. The first import will update all existing features and the second import will create all new features. The same import data can be also defined using two import data table which are equivalent to the original import data table.

The import data for update of existing feature. Note, all empty and not updatable columns are removed.

The import data for creation of existing feature. In this case all the fields will be used. The only difference from original import data table is the “Inheritable” property, which in this case is set to “1”, because it is a default value for this data property.

Import log is shown in Figure 9.

Feature definitions after import are shown in Figure 10.

Example Importing Translatable Data

In this example we demonstrate translatable data import. We use a new feature and define various translatable data columns in import data with multiple languages for some of translatable features.

The purpose of this example is to demonstrate how importer treats translatable properties with multiple languages.

The import data is shown in the table below:

Feature definition importer allows importing translatable properties in all languages including those, which are not active Perfion languages. In our example, the Perfion is set up to use English (EN), Chinese (CHS), Danish (DAN), German (DE), Spanish (ES), French (FR) and Dutch (NLD) as active languages. From import data one can see that “Caption_AFK” shown in orange color has different language code than those used by Perfion. This data will still be imported, but importer will show warnings in the import log for each column which does not use one of the active languages. Refer to Figure 11 to see the import log with such warning which also shows which languages are active in Perfion. The same handling is also applicable to other localizable import data fields such as information groups, e.g. “SecurityGroup_EN” in our example.

The feature defined in import data after import will have definitions as shown in Figure 12. Note, that data imported for Afrikaans (AFK) language is not shown in Feature Definition window, but it is imported and will be visible once the language is added to the Perfion’s active language list.

Example Importing Identity Inheritance

In this example we use two new features which after import creates identity inheritance. Both features are created as selectable features. The first feature is a parent feature, while the second one is a child feature.

The purpose of this example is to demonstrate how identity inheritance is created and how one must be careful when specifying various data properties which must be in sync for both features.

Import data is shown in the table below.

In our import data example, some of the data properties which must be in sync does not match. These properties are shown in red color. Trying to import such data will fail, because the importer will detect the error as shown in the import log in Figure 13.

In order to be able to import both features, the data properties defined in “Localizable” and “Formula” columns should match as shown in the new import data example below. Note, the example shows only two data properties which must be in sync, but there are more.

The import log for the new import data is shown in Figure 14.

After both features from our example are imported, they create identity inheritance. Figure 15 shows how this looks like in the Feature pane and Figure 16 shows definitions for both features.