Import

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

Data Format

The import data is table like data and can be specified as import data headers and import data values. The import data closely resembles Actions data setup in Perfion. The example is shown in Figure 1.

 

Action 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 “#Note” will be ignored by importer.

Base Values of Action and From Items

Action and From items are hierarchical and if defined using base values, they have to be defined using the full path starting from the root hierarchy node to the actual base value. In addition, RefAction item has the same format as Action item and the same rules are valid also for this parameter. The exception is only when Action and RefAction items are defined using IDs.

Virtual indicator is the caret (^) character and to separate the nodes in the path the pipe (|) character is used.

Example

The Figure 2 shows an example Action setup with catalog, virtual and normal items and then the table below shows how to build paths for Action, From and RefAction items for this particular setup.

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:

Limitations

The action importer have several limitations:

• Catalog type items are not supported. The actions are not meant to be used with catalogs and therefore all catalogs should be converted to virtual items. The catalog items from functionality point of view works exactly like virtual items, so there should be no issues converting all existing catalog items to virtual items. In Perfion one can convert catalog item to virtual item by right clicking the catalog item and then from context menu selecting “Convert Item…” and then selecting “Convert to Virtual” and click OK button.

If the actions data is exported, then the exporter will automatically export all catalog items as if they are virtual items. However, if during import action importer will find some catalog items which match incoming virtual item, then it will stop the import with an error.

• Duplicate action items are not supported. Multiple Action items can be defined using the same base value. If such Action items belong to the same parent, then importer cannot distinguish one from the other. That means, that when import data contains at least 1 action item which refers to such duplicate item in Perfion, then import of such Action item is not possible, because importer has no possibility to determine which of those 2 duplicate items it refers to. In such case the importer will stop the import with an error. In order to import such items either import using Action item IDs, or exclude all duplicates from import data.
• From items cannot be deleted if they are in feature configuration. The Action items which have From items which are also used in feature configuration as item dependency items, cannot be updated (replaced). Each time the Action items are matched with incoming Action items from import data and the user chose Replace import option, the action importer will remove all existing From items from those matched Action items and will replace them with those coming from the import data. If there is at least 1 From item in feature configuration, then such deletion cannot be done until the From item is removed from feature configuration. The action importer in this situation will report an error and will stop the import.
• Default values are not supported. The importer will ignore any default values set for action features.
• Action item deletion is not supported. The importer can only add or update existing Action items, but it cannot delete existing Action items.

Data Validation

Action 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.

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 import data headers are correctly defined, if mandatory headers are present, etc.
• Action item identity validation. In case Action items are defined using IDs, then action importer will validate if all defined IDs are valid. The same check is also done for all RefAction values.
• Duplicate item 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.
• From item in feature configuration status validation. Importer determines if there are any From items in feature configuration which has to be deleted.
• Import data hierarchy validation. Importer checks if all paths are defined correctly and that there are no unconnected nodes (Obsolete from Perfion 2021 R2 SR1).
• Reference Action validation. Importer checks if all reference action (RefAction) values are existing Action items or new Action items which are being imported.
• Catalog item validation. Importer checks if any of Action items have unsupported catalog items.

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

Importer

Action 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 import using the Perfion API.

Import procedure

The importer will only import data if it is valid and if Perfion data related to imported data is correct.

1. The import data is loaded. The loading of data will differ based on which importer interface is used.
2. Data is validated. All validations are done in stages checking all data rows for potential issues. If at any stage there are found any issues, then all those failed import data rows are reported to the log including specific information what have failed and where. Refer to Data Validation below for more information.
3. The data from Perfion is synchronized with the import data.
4. The old data is deleted from Perfion (only related to those items defined in the import data).
5. The new data is created in Perfion.

The import runs all data creation or modification in Perfion procedures in a transaction and follows the concept all or nothing. Any action data modifications will not be saved in Perfion until all import operations are successfully completed. If delete operation completed successfully, but the new data creation failed, then none of changes will be saved in Perfion and all modifications will be discarded.

Import Examples

In this section we will show various examples of how action data can be imported to Perfion using action GUI importer.

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 Migrating Actions from another Perfion

In this example we export actions from 1 Perfion and reimport them to another Perfion which has no actions. Instead of using 2 Perfion applications, we instead:

• Export actions to a file.
• Delete actions from Perfion.
• Restore the actions by importing them from the import file which was generated during action export.

The original action setup is shown in the figure below. Note, that there is 1 Action item of catalog type. After import this item will become virtual. In this setup, only “NormalItem” Action item has From items. All other Action items are empty, e.g. has no From item assignments.

We export the current action setup data from Perfion by going to “Import/Export” main menu and clicking a button “Export Actions”. Then, we export actions by Name in Excel format. The content of exported data is shown in Figure 4.

Now we delete all action data from Perfion and import the same file again. To import we go to “Import/Export” main menu and click a button “Import Actions”. Then, we select the same exported actions file. After import, the actions are restored in Perfion as shown in the figure below. The only difference is that now the catalog item was restored as a virtual item.

Example of Using Stop, Skip and Replace Import Options

In this example we will import some Action items to Perfion and will demonstrate how action importer behaves when there are matching Action items, e.g. items which we try to import, but they already exist in Perfion.

We use the action setup as it is shown in Figure 5. We will import 2 Action items, where the 1st item is a new Action item and the 2^nd item already exist in Perfion. The item which already exist will have a different setup then the items already in Perfion, e.g. it will have different From items. The data for import is shown below.

The first time when we import the file shown above, we use Stop option. Stop option should stop import if there are any matching items. The import log from the import with Stop option:

The import have detected that there is a matching Action item and stopped the import.

This time we try again to import the same data, but choose Skip option instead. The import log is shown in Figure 8.

In this case the import succeeded to import data, but the matching Action item was skipped in the process. The import log reports all skipped Action items, so importing using Skip option is a safe way to import new actions. All new actions will be imported and those matching will be shown in the log file.

After this import, the actions in Perfion were updated and the new Action item “NormalItem2” was imported as shown in Figure 9.

In case we want to update the matching Action item in Perfion, then Skip option in action importer is not useful. In such case we have to use the Replace option, which will not ignore any matching items, but will overwrite them with a new data coming from the import file.

After importing the same import file again as in previous cases but with Replace option, we get the following import log:

From the import log we can see that the import succeeded and imported all Action items without producing any warnings. During this import all 3 import rows where processed by action importer and were “re-imported” to Perfion, because all items in the import file are now matching items. The “NormalItem2” Action item was successfully imported in the previous import attempt using Skip option, so during this import it is now also a matching item. However, Action item “NormalItem2” do not have any changes. It is only the Action item “NormalItem” which had changes in import data which we wanted to transfer to Perfion. The setup of Action item “NormalItem” after the import is shown in the Figure 11. As we can see, it no longer have any From items which were previously in Perfion and they were all replaced by the new From items defined in the import data.

Export

Export Formats

It is possible to export action 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

Action 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 import using the Perfion API interface.

Export Validation

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