Import / Export Actions

Owned by Morten Lindequist Køhler
Feb 14, 2024
14 min read

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.

 

Figure 1: Action data setup

 

Action import data format is shown in the table below.

Data header

Mandatory

Description

Action

Action_ID

Yes

Actions feature item value or ID. This item will be referred to as “Action item”. 

String value, which represents the full hierarchical path to Action item. The path must be specified using rules as described in “Base Values of Action and From Items”.

It is a mandatory parameter.

The data header name must be defined as “Action” if Action item is defined using values, and as “Action_ID” when Action items are defined using Perfion IDs.

Action items will be used to match existing data in Perfion during actions import.

From Perfion 2021 R2 SR1: If some nodes are missing in the specified path, the importer will create the missing nodes as Virtual nodes.

Notes:

  • Values are case sensitive.

  • If values are defined using Perfion IDs, then all IDs defined in the import data must exist in Perfion.

  • One cannot import duplicate Action items when importing using Action data header. Duplicate Action items are such items, which both have the same base value, belong to the same parent and have the same brand type (e.g. both are Virtual items or both are normal items).

  • Catalog items cannot be imported or overwritten.

  • The order of Action items in import data is not important.

From

Yes

ActionMapFrom feature item value. This item will be referred to as “From item”.

String value, which represents the full hierarchical path to From item. The path must be specified using rules as described in “Base Values of Action and From Items”.

Notes:

  • Incoming From item values are not matched with existing values and are always created from scratch. If there are the same From items in Perfion already, then during import they will all be deleted and replaced with new From items coming from import data.

  • One can import duplicate From items.

  • Catalog items cannot be imported or overwritten.

  • The order of From items in import data is important and should be defined in the same sequence as it should be created in Perfion.

To

No

ActionMapTo feature value.

Parameter is optional.

String value.

Command

No

ActionMapCommand feature value.

Parameter is optional.

If a command is defined in import data, then it has to be one of existing action commands predefined in Perfion.

Values are case insensitive.

RefAction

No

ActionMapAction feature value.

Parameter is optional.

RefAction parameter is directly related to Action/Action_ID parameter and inherits its type.

When Action items are defined using paths and Action data header, then RefAction values must also be defined using paths.

When Action items are defined using IDs and Action_ID data header, then RefAction values must also be defined using IDs.

Notes:

  • Values are case sensitive.

  • RefAction value (if defined) should refer to an existing Action item from Perfion or one of the new Action items defined in the import data.

Script

No

ActionMapScript feature value.

Parameter is optional.

Text value.

Note

No

ActionMapNote feature value.

Parameter is optional.

Text value.

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.

NOTE: Default values are not supported by Actions import.

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.

Item type

Item value

Example

Normal

Full path to actual item starting with a root item

RootItem|Node2Item|ActualItem

Virtual

Full path to actual item starting with a root item with prefixed virtual item indicator

^RootItem|Node2Item|ActualItem

Catalog

The Catalog type items are not supported and have to be converted to virtual items.

-

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.

Figure 2: Action setup example - catalog, virtual, normal items

Item

Item type

Full path

Description

Action items

CatalogItem

Catalog

^CatalogItem

Catalog is treated as if it is a virtual item.

VirtualItem

Virtual

^CatalogItem|VirtualItem

The path references virtual item, therefore there is a virtual indicator as prefix to the path.

NormalItem

Normal

CatalogItem|VirtualItem|NormalItem

Normal item does not have a prefix.

VirtualItem2

Virtual

^VirtualItem2

 

NormalItem2

Normal

VirtualItem2|NormalItem2

 

From items

VirtualFromItem1

Virtual

^VirtaulFromItem1

From item paths follow the same rules as action items.

NormalFromItem1

Normal

VirtaulFromItem1|NormalFromItem1

VirtualFromItem2

Virtual

^VirtaulFromItem2

NormalFromItem2

Normal

VirtaulFromItem2|NormalFromItem2

RefAction items

NormalItem2

Normal

VirtualItem2|NormalItem2

RefAction refers to actual Action items and have the same paths.

VirtualItem2

Virtual

^VirtualItem2

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:

#

Rule

Example

Comment

1

The node value must be escaped if it contains a path separator (|) or one of 4 delimiter (‘, “, $, #) characters.

Note: The node value must be escaped even if it is a single node in the path.

abc

 

No escaping needed, because node value does not have separator or delimiter characters.

Value vs. escaped value:

  • a|b => ‘a|b’

  • a’b => “a’b”

  • a”b => ‘a”b’

  • a$b => ‘a$b’

  • a#b => ‘a#b’

Example of node values which has to be escaped, because they include either separator or delimiter character.

2

Escaping can be done using any of 4 delimiters which is not used in the node’s value.

Note: The delimiter use order is not important.

Value vs. escaped value:

  • a’b”c$d => #a’b”c$d#

  • a’b => “a’b”

  • a’b => #a’b”

 

3

Node value may not have all 4 delimiter (‘, “, $, #) characters.

a’b”c$d#e

Illegal node value, which cannot be escaped, because it has all delimiter characters.

4

Node value escaping is independent for each node in the path.

Note: Different delimiters can be used for different path nodes.

Value vs. escaped value:

  • Node 1: abc

  • Node 2: a|b|c => ‘a|b|c’

  • Node 3: I’m => “I’m”

  • Node 4: I am Path with escaped nodes: abc|’a|b|c’|”I’m”|I am

Node 1 and Node 4 do not need escaping.

Node 2 and Node 3 must be escaped.

Note, that Node 2 and Node 3 are escaped using different delimiters.

5

Node value can be escaped even if it does not have to be escaped.

Value: abc

Valid escaped values:

  • abc

  • “abc”

Escaping can be used even if there is no need for it.

6

Empty paths must be escaped, but only if they belong to From or RefAction items.

The items with empty base value (or no value) have to be escaped by using 2 delimiters, e.g.

  • ‘’

  • “”

  • ##

  • $$

When importing actions to Perfion, the From and RefAction items are optional and action importer needs to distinguish existing items with blank name and not existing (or not set) items.

7

Virtual indicator ^ (caret character) should be used to indicate if the path is of virtual (or catalog) type.

Path of normal items:

  • NormalItem1

  • Root|Parent1|NormalItem2

Path of virtual items:

  • ^VirtualItem1

  • ^Root|Parent1|VirtualItem2

 

 

Virtual indicator is not a node prefix, it is a path prefix. All node values are encoded in the same way regardless of their status independently, but if the path is pointing to the virtual item, then the path should be prefixed with virtual indicator character.

8

The root nodes which start with virtual indicator character must be escaped.

Example with normal item:

  • Root node: ^abc

  • Normal item node: def

  • Path: “^abc”|def

Example with virtual item:

  • Root node: ^abc

  • Virtual item node: def

  • Path: ^“^abc”|def

The rule is valid for normal and virtual items. The escaping is necessary in order to be able to avoid node with special characters identification as virtual paths.

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:

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

NOTE: The action export file is fully compatible with action importer, so action export can be used for action backup, which can be later restored.

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 2nd 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.

NOTE: In this mode any existing data related to those matching items will be deleted. We recommend exporting all actions as a precaution in case something will go wrong during the import.

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:

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.