All imports and exports in Perfion can be performed via application programming interface (API), e.g. from a custom project by utilizing Perfion libraries and importer/exporter interfaces.

This page describes import/export procedures which can be performed in Perfion version 2020 R2 or newer. Before Perfion version 2020 R1 the access to imports was limited and importers had less features as compared to the new interfaces. Form Perfion version 2020 R2 the export interface was implemented.

The previously used import procedures are still usable, but have been deprecated. It is recommended to use only the new procedures from Perfion version 2020 R1.

Import

Import via API uses a generic Perfion Importer interface which can be used to perform all types of imports supported by Perfion.

Perfion Importer Interface

All imports in Perfion implement IPerfionImporter interface. The interface is generic and allows doing the following:

• Load the import data from different sources

• Get loaded import data

• Set import parameters

• Get import parameters

• Start import

• Stop import

• Get import status

• Get import name and type

• Subscribe to Log and Status events

Import Initialization

There are two types of importers:

• Generic importer. It is based on IPerfionImporter interface and all importers are based on this interface.

• Specific importer for chosen import type. There is one specific importer for each type of import. Specific importers are based on generic importer and the only difference is that specific importer allows strong typed parameters.

Get Feature Data importer

Open

Loading Import Data

The import data can be loaded from different sources. Perfion supports loading data from:

• File. There are several type of files supported by Perfion:

  • Microsoft Excel 97/2003 or newer (.xlsx, .xls).

  • XML (.xml).

  • CSV (.csv).

  • XLIFF (.xliff, .xlf) – Only Feature Data import supports this file type.

• DataTable. The import data can be loaded using C# .NET DataTable. This allows importing data from any other data sources by implementing a custom interface for that specific data source and then loading data as DataTable. The data must be set up based on requirements for each import type.

For more information about supported file formats refer to “Perfion Import & Export – Data & File Formats” and “Perfion Import / Export Translations XLIFF” manuals.

For more information about data setup requirements for different type of imports refer to the manuals for actual imports.

Import Parameters

There are different ways to load import parameters.

• Using key-value concept where all parameters are loaded using parameter name and value. All importers support this method. To set parameters using this method one can use only those parameters which have to get a new value. The process is loosely coupled so that all parameters passed to the importer which are not related to that importer will be ignored and those parameters which are known will be updated with new values. Most of import parameters have default values, so one has to set only those parameters which are mandatory.

• Using importer’s properties. This can be done only by using the specific importers. For example, the feature data importer will allow setting only those properties, which are related to feature data import. As it was a case with key-value concept, mandatory parameters must be specified, while all other parameters will have default values if not set explicitly.

Set Feature Data importer parameters

Open

Parameters for different types of imports:

For more information about import parameters refer to the manuals for actual imports.

Start Import

Before one can start the import the import data has to be loaded and import parameters must be set to correct values.

All imports in Perfion are controlled globally and typically only a single import can run at a time. All this control is done by the import/export manager. When the import is started it is assigned a queue number and is put in a waiting list. If there are no other imports running or waiting, then the import will start immediately.

To learn more about import/export manager refer to “Import/Export Manager” manual.

Import Status

Importers can report their status either by asking importer directly or one can also subscribe to status change event.

There are following import statuses:

• NA. The import was not started.

• Waiting. The import was initiated, but it is waiting for its turn to run. The data from all imports is logged in Perfion database and it can take some time before all preparation procedures are completed and the actual import process can start. There could also be other imports with higher priority running or waiting in a queue, so the import will stay in this state until other imports are completed.

• Running. The import process have started. In this state importer starts data validation process and various other procedures.

• Importing. It depends on import type what is actually happening when importer is in this state, but in general it means that data validation have been completed and that importer is performing the actual data import to Perfion database.

• Stopped. The import have been stopped by a user.

• Failed. The import have been stopped because of some failure. The cause of the failure should be available in the import log.

• Succeeded. The import have successfully completed.

Stop Import

The imports are designed to be stopped at any time. The stopping, however, may not happen immediately, because the “soft” stop is used. This means, that the import will stop as soon as it have finished the operation it currently performs. Based on what the importer is currently doing, it can take some time. For example, if the import is running some procedure for data insertion to the database, then after issuing the stop command the import will stop only after that procedure is completed.

Stopping of the import affects not just the actual import, but also the import/export manager. Import/export manager is designed to remove any waiting imports from the queue when the stop command is issued. The import/export manager have some predefined status check intervals and stopping can be done only at those times when it wakes up to check for import status.

Import Events

All imports log data and status updates to Perfion database, but users can get access to some of this information as well by subscribing to import Status and Log events.

• Status event. The status event is fired each time the importer changes its state. Subscribing to this event allows monitoring the progress of the import.

• Log event. The log event is fired each time when the importer writes some notifications about what it is doing. There are different types of log messages issued when the import runs:

  • Info messages. Information about what import does, e.g. which operation it performs at the moment, etc.

  • Warning messages. The log messages which include important information which may affect import results because of some detected data or configuration issues.

  • Error messages. The log messages which describe the errors which happened during the import. The error messages are issued before the import is terminated.

Export

Export via API uses a generic Perfion Exporter interface which can be used to perform all types of exports supported by Perfion.

Perfion Exporter Interface

All exports in Perfion implement IPerfionExporter interface. The interface is generic and allows doing the following:

• Get exported data

• Set export parameters

• Get export parameters

• Start export

• Stop export

• Get export status

• Get export name and type

• Subscribe to Log and Status events

• Write exported data to file

Export Initialization

There are two types of exporters:

• Generic exporter. It is based on IPerfionExporter interface and all exporters are based on this interface.

• Specific exporter for chosen export type. There is one specific exporter for each type of export. Specific exporters are based on generic exporter and the only difference is that specific exporter allows strong typed parameters.

Export Parameters

There are different ways to load export parameters.

• Using key-value concept where all parameters are loaded using parameter name and value. All exporters support this method. To set parameters using this method one can use only those parameters which have to get a new value. The process is loosely coupled so that all parameters passed to the exporter which are not related to that exporter will be ignored and those parameters which are known will be updated with new values. Most of export parameters have default values, so one has to set only those parameters which are mandatory.

• Using exporter’s properties. This can be done only by using the specific exporters. For example, the action data exporter will allow setting only those properties, which are related to action data export. As it was a case with key-value concept, mandatory parameters must be specified, while all other parameters will have default values if not set explicitly.

Parameters for different types of exports:

For more information about export parameters refer to the manuals for actual exports.

Start Export

Before one can start the export the export parameters must be set to correct values.

All exports in Perfion are controlled globally and typically only a single export of the same type can run at a time. All this control is done by the import/export manager. When the export is started it is assigned a queue number and is put in a waiting list. If there are no other exports running or waiting, then the export will start immediately.

To learn more about import/export manager refer to “Import/Export Manager” manual.

Export Status

Exporters can report their status either by asking exporter directly or one can also subscribe to status change event.

There are following export statuses:

• NA. The export was not started.

• Waiting. The export was initiated, but it is waiting for its turn to run. The data from all exports is logged in Perfion database and it can take some time before all preparation procedures are completed and the actual export process can start. There could also be other exports with higher priority running or waiting in a queue, so the export will stay in this state until other exports are completed.

• Running. The export process have started. In this state exporter starts data validation process and various other procedures.

• Exporting. It depends on export type what is actually happening when exporter is in this state, but in general it means that data validation have been completed and that exporter is performing the actual data export from Perfion database.

• Stopped. The export have been stopped by a user.

• Failed. The export have been stopped because of some failure. The cause of the failure should be available in the export log.

• Succeeded. The export have successfully completed.

Stop Export

The exports are designed to be stopped at any time. The stopping, however, may not happen immediately, because the “soft” stop is used. This means, that the export will stop as soon as it have finished the operation it currently performs. Based on what the exporter is currently doing, it can take some time. For example, if the export is running some procedure for data request from the database, then after issuing the stop command the export will stop only after that procedure is completed.

Stopping of the export affects not just the actual export, but also the import/export manager. Import/export manager is designed to remove any waiting exports from the queue when the stop command is issued. The import/export manager have some predefined status check intervals and stopping can be done only at those times when it wakes up to check for export status.

Export Events

All exports log data and status updates to Perfion database, but users can get access to some of this information as well by subscribing to export Status and Log events.

• Status event. The status event is fired each time the exporter changes its state. Subscribing to this event allows monitoring the progress of the export.

• Log event. The log event is fired each time when the exporter writes some notifications about what it is doing. There are different types of log messages issued when the export runs:

  • Info messages. Information about what export does, e.g. which operation it performs at the moment, etc.

  • Warning messages. The log messages which include important information which may affect export results because of some detected data or configuration issues.

  • Error messages. The log messages which describe the errors which happened during the export. The error messages are issued before the export is terminated.

Console Application Example

The import/export via API will be shown as an example how one can create a simple console application project and to call Perfion import and export.

• Create a new C# console application project in Visual Studio.

• Add the following .dll libraries to the project as references:

  • Pims.Dal.dll

  • Perfion.Lib.dll

  • Perfion.API.dll

  • NativeExcel.dll

  • Perfion.Integration.dll

  • ImageGlue.dll

  • ImageGlue7-32.dll

  • ImageGlue7-64.dll

The libraries can be found in the Perfion Integration package, which can be downloaded from Perfion Knowledge Base.

• Use our console application example code to get started.

Console Application – Main

The console application will import feature data from a file and can also export action data.

The application can be quickly adjusted to do any type of import or export. The application’s workflow:

• Read user defined parameters which will determine if the import or the export should be performed including all import/export related parameters.

  • Import procedure allows to import from a file.

  • Export procedure exports action data to selected file.

• Read database connection string and log file path from application’s configuration.

• Perform import or export.

  • Import initialize “NewImporter” class, which will do the actual import and then based on user provided parameters will run the import procedure.

  • Export initialize “NewExporter” class, which will do the actual export and then based on user provided parameters will run the export procedure.

Console Application – NewImporter Class

NewImporter Class is generic and can do any type of import. It allows performing import from a file and can write all import messages and status updates to a log file.

The methods which perform the import are practically the same. The only difference is how the data is loaded.

Console Application – NewExporter Class

NewExporter Class is generic and can do any type of export. It allows performing export by writing the exported data to file and can write all export messages and status updates to a log file.

Console Application – Configuration

The configuration file contains connection string to database and log file path.

Console Application – Run Import

Run the import from the console from the directory with console application’s executable. The example shows how to run the feature data import by providing “Product” as ImportToFeature and the path to the import data file.

The content of the import data file “ImportFile.xlsx” is shown in Figure 1.

The import log file from the first example when importing feature data from a file.

Console Application – Run Export

Run the export from the console from the directory with console application’s executable. The example shows how to run the action data export by providing the path to the export data file which has to be created.

The content of the export data file “ExportFile.xlsx” is shown in Figure 2.

The export log file.