Ucommerce Connector Setup
- Morten Lindequist Køhler
Ucommerce Connector setup parameters are defined in Connector’s configuration file and also in Perfion ECommerce mappings. Ucommerce Connector uses Perfion ECommerce API and Ucommerce API to synchronize data between Perfion and Ucommerce. Ucommerce Connector acts as master of data. All data synchronization is done from Ucommerce Connector, e.g. there is no active Ucommerce involvement in the synchronization process. Perfion Ucommerce Connector reads all required data from Ucommerce, compares it to what is stored in Perfion and performs synchronization accordingly.
Ucommerce Connector in essence is a code library which implements Ucommerce synchronization manager. The library can be integrated into a custom project, but Perfion also offers a few end user friendly applications, which use the before mentioned library to perform synchronization. Currently there are following options:
C# dynamically linked library. The library allows to start and control Ucommerce synchronization manager. This library is used by all other Connector applications offered by Perfion and it can also be used when building a custom application or when integrating Connector to other projects.
Windows service. Windows service is a special application, which can be installed in Windows OS and then it runs in a background. It will be controlled by Windows OS, e.g. it can be started automatically when Windows starts. Windows service can also be controlled by Perfion Connector App, which can be installed in Ucommerce.
Console application. A console application is Windows OS executable file, which can be run from a command line.
Prerequisites
Before using the Ucommerce Connector the following Perfion components must be installed:
Perfion application (optional). Perfion is a cloud based solution, so all the data Ucommerce Connector is using is in remotely accessible database. Connector communicates with this database by using Perfion ECommerce API, so for Connector itself to run, the Perfion application is not needed. The Perfion application is needed only to setup data, Connector related mappings and settings.
Perfion API Service. It consists of Perfion API, Perfion ECommerce API and other components.
Both prerequisites can be downloaded from Perfion Knowledge Base (https://knowledge.perfion.com/ ).
Ucommerce Connector version | Perfion API version | Compatible Perfion version |
v0.94 | v4.5.36 or newer | v4.5.42 or newer |
v1.0 | v4.5.52 or newer | 2019 R1 (v4.5.52) or newer |
Ucommerce Connector Configuration File
Ucommerce Connector uses configuration file which is used to initialize Ucommerce Connector synchronization manager. The configuration file is located in Ucommerce Connector installation folder. There are several configuration files available in installation folder and each file is dedicated to different Ucommerce Connector applications. All configuration file parameters are shown in the table below:
Parameter name | Description |
ServiceName | Name of Ucommerce Connector application, which will be used when logging. Recommendation: use short name without spaces. |
PerfionChannelName | Perfion channel name. Connector will synchronize data only for one channel. |
LogDirectory | Directory where log files will be saved. The log file will be automatically created by using date and ServiceName parameter value. The format of log file name will be: <date>_<ServiceName>_log.txt. There will be created one log file per day. Date format: YYYYMMDD. |
LogType | Type of log messages written to log file. The following values can be defined:
Default: “Progress”. |
ProgressReportStepInPct | The step in percent (%) refers to how often Ucommerce Connector will write synchronization status update for entity (product or category). Default: 10 Values: 1-99 NOTE: Reporting of status depends on how many entity items are synchronized. If there are only 3 items, then the first reported status will be after the first item is synchronized and will be 33.3%, the next one will be 66.6%, etc. NOTE: The status reporting is based on overall entity synchronization progress, which means that progress reporting will not be independent per entity item creations, updates and deletes. |
ECBaseURL | Base URL to Perfion API, e.g. where ECommerce API and Perfion API queries can be called from. |
ECBearerToken | OAuth bearer token for authenticating to Perfion API. Setting is optional if the Perfion API does not have authentication enabled (SecureApiService=false). We strongly suggest enabling authentication. See Installation guide | Configuring secure access for further details. (Introduced in uCommerce Connector 1.6) |
ECRetryCount | Number of retries for failed ECommerce API requests. Default: 3 Values (integer): >= 0 |
ECTimeoutInSec | Request to ECommerce API timeout in seconds. Default: 300 seconds Values (integer): >= 0 (0 - unlimited) NOTE: The default timeout for web service configuration in Microsoft IIS server is 120 seconds for connection timeout and 110 seconds of execution timeout. If the value specified by this parameter exceeds timeout values set in IIS server, then it will not be effective until IIS server timeout values are also updated to the same or higher values.
|
ECDataChunkSize | Number of entity items ECommerce API will retrieve at a time. Ucommerce Connector processes data in chunks to limit needed resources to process data. This parameter defines how many items will be handled at once. Default: 25 items Values (integer): > 0 |
UCRetryCount | Number of retries for failed Ucommerce API requests. Default: 3 Values (integer): >= 0 |
EnableStatistics | Enables or disabled statistics calculation. Default: False Values (boolean): True|False |
UCConnectionString | Connection string to Ucommerce database. Example: server=uc_server_name;database=uc_db;user id=uc_user;password='uc_password' |
LogToUcDb | Enable logging to Ucommerce database. This parameter must be enabled in order to use the Perfion Connector App in Ucommerce. Default: False Values (boolean): True|False |
Connector configuration file will be used only by Windows service and console application. In custom applications built using Connector manager library, one has to initialize all parameters manually.
Ucommerce Connector as Windows Service
Windows service must be installed before use.
Windows Service Installation
To install Ucommerce Connector as Windows service:
Download the Ucommerce Connector files from Perfion knowledge base site.
Place all the files into folder, e.g. “C:/PerfionUcommerceService”.
Find Windows service install utility files. They must be located in the following folder: "C:\Windows\Microsoft.NET\Framework64\
There should be several .NET versions available, where each is located in separate folder. Use one, which is above v4. For example:
"C:\Windows\Microsoft.NET\Framework64\v4.0.30319\".
From the folder found in step 3. select files listed below and copy them to the installation folder created in step 2.
InstallUtil.exe
InstallUtil.exe.config
InstallUtilLib.dll
Open “Windows Command Prompt” or “PowerShell” with administrator user privileges and navigate to Ucommerce Connector installation folder created in step 2.
Install the Ucommerce Connector by running this command:
Windows service installation |
InstallUtil.exe /servicename="<unique_service_name>" UcommerceService.exe |
After installation of Ucommerce Connector service it will be available from Windows Services application. To open it press “Win+R” and then in “Run” window “Open:” field write “services.msc” and press “Enter”. Example of Windows Services application after installation is shown in Figure 1.
Update Ucommerce Connector configuration file. Before starting the Ucommerce Connector service it is important to update its configuration file with correct parameters. There are several configuration files in installation folder. Use “UcommerceService.exe.config” file to update Connector parameters. Refer to “Ucommerce Connector Configuration File” to see which parameters can be used in configuration file and how to correctly set them up.
Start the service. Select the service in Windows Services application and start it by clicking green “Play” button in application toolbar or by right clicking on service name with a mouse and from context menu choosing “Start”. The service can be stopped by selecting it and then pressing “Stop” button in application toolbar or by right clicking on service name with a mouse and from context menu choosing “Stop”.
Windows Service Update
To update the Ucommerce Connector service it does not have to be reinstalled. The procedure is:
Stop the service.
Overwrite the old service executable (UcommerceService.exe) and any library files (*.dll) with new service files.
Compare old configuration file to the new configuration file coming with installation. If there are new parameters in the new configuration file, then they have to be added to the old configuration file.
The default configuration file parameters coming with Ucommerce Connector installation use recommended values, but they are all user configurable.
Start the service again.
Windows Service Removal
The removal procedure of Ucommerce Connector service:
Open “Windows Command Prompt” or “PowerShell” with administrator user privileges and navigate to Ucommerce Connector service installation folder.
Run the following command:
Ucommerce Connector removal |
InstallUtil.exe /u UcommerceService.exe |
Ucommerce Connector as Console Application
Ucommerce Connector as console application is an independent executable file and does not need to be installed. There are several ways to start the Connector as a console application:
By executing the Connector console application executable file “UCommerceConsoleApp.exe” directly from Windows file browser. The executable file is in Connector installation folder.
By running the Connector console application from a command line interface in a manager mode. To do that first open “Windows Command Prompt” or “PowerShell” and then start the application by running the following command:
Running Connector as console application from command prompt |
UCommerceConsoleApp.exe |
Note, by running the command without any extra parameters, the Connector will start in the default manager mode. In this mode the Connector on start will perform the first synchronization and then will initialize a scheduler based on parameters defined in Perfion ECommerce Settings. Scheduler will determine when connector should perform the next synchronization and will wait until that time comes. Then it will perform another synchronization and will do this indefinitely until user terminates the console application.
By running the Connector console application from a command line interface in a single synchronization mode. This mode differs from the default mode, because in this case the Connector will not start in a manager mode, but instead will perform a single synchronization and then will quit. To run Connector in a single synchronization mode, run the following command:
Running Connector in a single synchronization mode from command prompt |
UCommerceConsoleApp.exe -runonce |
Before starting the Ucommerce Connector console application it is important to update its configuration file with correct parameters. There are several configuration files in installation folder. Use “UCommerceConsoleApp.exe.config” file to update Connector parameters. Refer to Ucommerce Connector Configuration File to see which parameters can be used in configuration file and how to correctly set them up.
To stop the Connector, just close the application window. The Connector is designed to be abruptly stopped at any time. There could be some issues with some entity items which were under synchronization during Connector termination, but Connector was design to resynchronize all failed items on next start.
Note, Ucommerce Connector console application must be restarted after each modification of configuration file.
Ucommerce Connector as Library for a Custom Application
The Ucommerce Connector can be integrated into other projects or one can create a custom Connector application, which has a custom logger or even GUI. To do that one has to use Perfion Ucommerce Connector manager library. Refer to Appendix A: Code Example of Connector as a Custom Console Application to see an example of code which shows how to create a custom console application which uses most of Connector’s features.
The Connector manager have the following features:
The manager can be initialized with a custom logger. The standard Ucommerce Connectors in a form of console application and Windows service use a logger, which writes log messages to a text file. The user is, however, not limited to that and can use their own logger to get all information from manager and to control how and where the log messages will be saved. The example of a custom logger is provided in Appendix A: Code Example of Connector as a Custom Console Application.
The Connector manager consist of three interfaces and each interface may have its own independent logging.
Perfion Ecommerce API. Handles any communication with Perfion.
Ucommerce API. Handles any communication with Ucommerce.
Connector manager. The manager, which uses Perfion Ecommerce and Ucommerce APIs to perform a synchronization of data and also manage synchronization scheduling tasks.
Manager can be started. One can start the manager only if it is in initialized state or in stopped state. When starting the manager once can choose to start it in default manager mode where scheduled synchronization will be initialized or to choose to synchronize data once.
Manager can be stopped. One can stop the manager only if it is started. The stopping procedure will check which state the manager has and will handle stopping procedure accordingly. If the manager is sleeping or downloading new configuration, then it will be stopped immediately. In case the manager is performing synchronization, then it will try to stop it nicely. All synchronization items which were started to be synchronized will be allowed to finish and only then the manager will be stopped. For example, if there are 100 items to synchronize and manager have completed synchronizing 20 items, 5 items are currently are being synchronized and 75 items are still waiting to be synchronized. The manager stopping procedure will allow to finish synchronization of those 5 items and will ignore the remaining 75 items.
Manager has four events, where each is triggered when manager state is changing.
State change event. The event is fired when manager changes its main state.
Error state change event. The event is fired when:
Manager fails for any reason in any of its states, e.g. if it fails to retrieve the configuration or synchronization fails.
Manager is stopped externally. This may happen if the manager is stopped using “Stop” method.
Manager error state is restored when it retries after failure. The manager is running in continuous loop and activates predefined actions at predefined time intervals. If some error is detected, e.g. while retrieving configuration from Perfion or Ucommerce, then it will try again later. Any time when it retries, it restores the error state.
Synchronization type change event. This event is fired only when manager starts synchronization process. The synchronizer has its own states.
Synchronization progress change event. This event is fired only when synchronizer is synchronizing categories or products and it reports the following information every time a single item have finished synchronizing (e.g. a synchronization of a single product was completed):
The total progress of synchronization (for categories or for products) in percent.
The status of the last updated item if it has failed or succeeded.
Each triggered event will also provide a copy of the current Connector manager state after that moment the event was triggered, e.g. with a new state. Each event will also provide the state/progress it had before the change and after the change.
The manager can report all information related to its current state. The managers current state has the following information:
Manager state.
Manager error state.
Manager synchronization state. Note, usable only when manager is in synchronization state.
Synchronization information.
Synchronization type.
Entity synchronization total progress in percent (including creations, updates and deletions).
The number of items found for creation.
The number of items found for update.
The number of items found for deletion.
The total number of succeeded items so far.
The total number of failed items so far.
Note, it has useful information only when the manager is in product or category synchronization state. Most of provided information is related to the entity, which is being synchronized at the moment, which can be either category or product.
Sleep information.
Time left until Connector wakes up.
Date when Connector is expected to wake up from sleeping.
Note, usable only when manager is in sleeping state.
ECommerce Data Mapper in Perfion
ECommerce data mapper is a special data structure in Perfion, which is used to map data from Perfion to ECommerce API. There are four requirements when setting up data in ECommerce mapper:
The ECommerce data structure must be installed in Perfion. This can be done from Perfion application. Refer to “ECommerce API” manual for more info.
The data in Perfion must be setup correctly so that one can use it via ECommerce API. For example product variants should be linked to products in a special way. Refer to “ECommerce API” manual for more info.
The ECommerce mapping settings should be set up correctly to be able to access product, variant, category, etc. data. Moreover, one must set up channels, image service location, file service location, image processing parameters, etc. Refer to “ECommerce API” manual for more info.
ECommerce mapping settings should be configured to support Ucommerce Connector. The ECommerce API is a universal API created to extract data from Perfion, which is suitable for most E-Commerce systems. The first three requirements in this list cover general setup required to link Perfion data to ECommerce API. The Ucommerce E-Commerce system requirements are more specific and Ucommerce Connector will be able to read data from ECommerce API correctly only if all data is defined exactly as required. It means that all parameters must have special names, types, all mandatory parameters must be specified, etc.
The following sections will show how to set Ucommerce Connector specific parameters. These parameters are configured in sub-features, defined under “ECommerce Features”. Ucommerce Connector specific parameters will be defined in “ECommerce Mapping” and “ECommerce Settings” features. Refer to Figure 2.
ECommerce Data Mapper – Settings
Settings are defined in “ECommerce Features” -> ”ECommerce Settings”. Settings are global parameters and will be valid for all data synchronized from Perfion to Ucommerce. The purpose of settings can be compared to Ucommerce Connector configuration file. The main difference is that any settings parameters defined in Perfion will be continuously updated in Ucommerce Connector without a need to restart the Connector’s manager. How often these settings will be updated in Ucommerce Connector users can define in these settings. When Connector is started for the first time, it will read these settings parameters and will determine when data has to be updated again based on parameter values. Settings parameters related to Ucommerce Connector are shown in the table below. There can also be defined other settings parameters, which are generic for ECommerce API and information on those parameters can be found in “ECommerce API” manual.
ECommerce Settings Parameter | Description |
VariantSupportEnabled | Enables product variants in ECommerce configuration. Parameter is optional. Default value: false Values (boolean type): True|False |
Languages | Comma separated values of Perfion language codes. Perfion will synchronize all multilingual data with Ucommerce and will create values for all languages, even if Ucommerce does not use those languages. In order to see multilingual data in Ucommerce, one has to set up the same languages in Ucommerce. Parameter is mandatory and minimum one language should be defined. |
SyncType | Comma separated synchronization types. Parameter is optional. Default value: <no value> (no synchronization) Values:
|
SyncMedia | Enabled or disabled binary data synchronization. Parameter is optional. Default value: false Values (boolean type): True|False |
ConfigurationUpdateFrequencyInMin | Time in minutes how often Ucommerce Connector manager will check for channel configuration changes. Parameter is optional. Default value: 0 (no update) Values (integer type): >= 0 |
SyncFrequencyInMin | Time in minutes how often synchronization should run. Parameter is optional. Default value: 0 (no synchronization) Values (integer type): >= 0 |
DataMaxAgeInMin | Time in minutes how often data has to be refreshed/resynchronized. Based on this parameter value, data for synchronization will be chosen using an extra condition, which will check if data is not older than specified value since the data was last synchronized. For example, if parameter value is set to one month and product was not modified in the last month, then synchronization will update it anyway to make sure that all items in Ucommerce has data, which is not older than one month. Parameter is optional. Default value: 0 (no data refresh) Values (integer type): >= 0 |
SyncPrices | Enables or disables product and variant price synchronization. Parameter is optional. Default value: false. Values: true|false |
UCommercePriceGroup_1 | Price group mappings. Price groups in Ucommerce are specified in Catalogs and there may be more than one. To be able to add prices for products and variants for each price group, one has to define all available price groups by using reserved format: “UCommercePriceGroup_<label>”, where “label” is a unique label to identify the price group. All price groups must be unique per channel. Parameter is optional, but there must be at least one price group definition if parameter SyncPrices is set to ‘true’. Default value: none Values: the exact name of price group from Ucommerce. Value min size is 1 char and max 128 chars. |
UCommercePriceGroup_2 | |
… | |
UCommercePriceGroup_N | |
SyncProductRelations | Enables or disables product relations synchronization. Parameter is optional. Default value: false. Values: true|false |
UCommerceProductRelationType_1 | Related product types mappings. Related products in Ucommerce are specified using product relation types and there may be more than one. These relations can be used with products to identify how one product is related to another. To be able to correctly identify product relation types from Perfion in Ucommerce, one must define all product relation types used with products by using reserved format: “UCommerceProductRelationType_<label>”, where “label” is a unique label to identify the product relation type. All product relation types must be unique per channel. Parameter is optional, but there must be at least one product relation type definition if parameter SyncProductRelations is set to ‘true’. Default value: none Values: the exact name of product relation type from Ucommerce. Value min size is 1 char and max 128 chars. Relation types can be specified using selectable, multivalue feature. The feature should be created under the product feature. Refer to Product Relation to Other Products Configuration in Perfion for more information. |
UCommerceProductRelationType_2 | |
… | |
UCommerceProductRelationType_N |
ECommerce Data Mapping
Mappings are defined in “ECommerce Features” -> ”ECommerce Mapping”. Mappings are related to actual product, variant, category, etc. data. Like settings parameters, mapping parameters will be continuously updated by Ucommerce Connector manager without a need to restart it. Mapping parameters related to Ucommerce Connector are shown in the tables below, based on entity type. There can also be defined other mapping parameters, which are generic for ECommerce API and information about those parameters can be found in “ECommerce API” manual.
Products and categories in Ucommerce are defined by using definitions. Variants have the same definition as their parent product. A definition in Ucommerce defines which data properties entity item will have, if it will have variants (if entity item is a product), etc. Each definition in Ucommerce defines an independent type of entity item.
For example, let’s say one has a book and a pencil. These two products will share fixed properties like ‘Name’, ‘Description’, ‘Price’, etc., but will also have custom properties, which may be usable only with one product type or another, e.g. book may have ‘Author’ and ‘NumberOfPages’ properties, while pencil may have ‘Color’ property. Each of those two products will have independent definition in Ucommerce to define an independent product type. When configuring entity mappings in Perfion, one will have to define definition name for each entity. Moreover, all definitions will share the common properties defined by Ucommerce and these properties are also permanently defined in Perfion mappings. For example, even if a book and a pencil have different definitions, they will share the ‘Name’ property, e.g. in ECommerce mappings it will be defined as a single mapping. All custom properties in ECommerce mappings can be defined independently, but user can share the same custom properties for multiple entities.
Regardless of how many types of entity items there are in Ucommerce, all must be mapped in a single configuration. It is like having one big configuration, which can be used to define all possible types of entities. So if there is a book and a pencil, then ECommerce product mappings must be defined so, that both products can be fully configured.
Regardless of how many ECommerce mappings there are in total, only the actual data will define which data will be sent via ECommerce API. All ECommerce mappings are only a configuration, but if there is no data for one or another configuration parameter, then that data will not be sent via ECommerce API. The concept of how this works is shown in the tables below. The first table shows a pseudo configuration for a book and a pencil products.
Mapping name | Type | Data type | Entity type |
Name | Fixed | Field | Product |
Definition | Fixed | Field | Product |
Author | Custom | Field | Product |
NumberOfPages | Custom | Field | Product |
Color | Custom | Field | Product |
This table shows the actual data for both products how it will be defined in Perfion:
Name | Definition | Author | NumberOfPages | Color |
Book 1 | FictionBook | Author A | 120 |
|
Book 2 | FictionBook | Author B | 56 |
|
Book 3 | Diary | Author C | 34 |
|
Pencil 1 | HardPencil |
|
| Black |
Pencil 2 | SoftPencil |
|
| Red |
Pencil 3 | SoftPencil |
|
| Blue |
The following two tables shows how the data for both types of products will be sent via ECommerce API. For book type products:
Name | Definition | Author | NumberOfPages |
Book 1 | FictionBook | Author A | 120 |
Book 2 | FictionBook | Author B | 56 |
Book 3 | Diary | Author C | 34 |
For pencil type products:
Name | Definition | Color |
Pencil 1 | HardPencil | Black |
Pencil 2 | SoftPencil | Red |
Pencil 3 | SoftPencil | Blue |
As one can see from this example, even though the ECommerce mappings have specifications for all types of products and their custom fields, the ECommerce API will send only the data, which is present. It will ignore all the data columns, which are not defined. One can imagine the ECommerce mappings as a white list for all possible property types and then the actual data for each product as options chosen to be sent from that possible property list.
The actual configuration for each mapping is more complex, but idea is the same and it is also valid for all types of entities, e.g. products, categories and variants will be defined in a similar way. Different types of mappings:
Mappings to configure ECommerce API properties, e.g. to define the context
Mappings to relate one entity to another, e.g. product to variants, categories to products, etc.
Mappings to control synchronization process, e.g. to save synchronization date, error messages, IDs, etc.
Mappings for actual data.
There can also be optional and mandatory parameters, different type parameters (image, text, number), etc.
Product Mapping Parameters
For all product related mapping parameters “ECommerce Entity” column value must be set to “Product”.
To | Output Kind | Mapping | Description |
@Context | Context | Product/-/ECommerceProductSearch | Product context. Parameter defines which feature in Perfion is used to define product and variant items. One can use specific search option, which will select only a subset of chosen feature’s data as the source for ECommerce setup. This is ECommerce API setup parameter. Parameter is mandatory. Refer to ECommerce API manual for more information how to define this parameter correctly. |
ECommerceType | ECommerceType | Name of Perfion feature (String type). Values: Product|Variant With products only ‘Product’ value can be used. | Parameter, which defines which feature will define the type of ECommerce entity, e.g. if the item is a product, then this feature will have value ‘Product’. If the item is a variant, then it will have value ‘Variant’. This is ECommerc API setup parameter. The parameter is required only if variants are used. Its primary task is to distinguish products from variants. In addition to this parameter, user must also appropriately set ‘VariantSupportEnabled’ parameter in ECommerce Settings. If this parameter is not specified, then all items will be assumed as products. |
Categories | RelatedCategory | Perfion feature for product category. The value should be set with the same feature name, which is used as base feature in Category Context definition. For example, if Category Context is defined as ”Website/-/ECommerceCategorySearch”, then “Website” will be the name of the base feature and should be used as value with this parameter. | This is a special parameter, which allows to specify product relation to category. Parameter is mandatory. Refer to “ECommerce API” manual for more information how it has to be set up. |
Key | KeyField | Name of Perfion feature (String type, not localizable). Values are of string type and must be unique for all product items. Variant items should not have any values. | Key will be used to link Perfion items to the same items in Ucommerce. Mandatory parameter. This is a Sync parameter.
|
SyncID | Field | Name of Perfion feature (String type, not Inheritable, not localizable). Values are of string type. | SyncID is used to link product ID defined by Key parameter to external ID of the same item in Ucommerce. Mandatory parameter. This is a Sync parameter. The parameter is updated by Ucommerce Connector after successful synchronization of each product item. |
SyncDate | Field
| Name of Perfion feature (String type, not Inheritable). Values are of string type. Date format: “yyyy-MM-dd HH:mm:ss” e.g. “2018-02-12 17:15:09”. | SyncDate is used to show the last synchronization date and it is also used to find out when data has to be synchronized next time. This parameter will be updated from Ucommerce Connector after successful product synchronization. If there was any error while synchronizing a product item, then date will not be updated. Mandatory parameter. This is a Sync parameter. |
SyncType | Field
| Name of Perfion feature (String type, not Inheritable, not localizable). Values are of string type. Allowed values:
Default value: “”. | Value defined for this parameter will allow to overwrite default synchronization settings for each product. Parameter is optional. This is a Sync parameter. If no value is specified, then a product will be synchronized using global synchronization settings. If value ‘NoUpdate’ is set, then this value will indicate, that product item should not be updated in Ucommerce. For example, this could be a temporary product, which is created in Perfion, but should not be updated yet. If the product already exist in Ucommerce, then it will be ignored, e.g. not updated and not deleted. If the product does not exist in Ucommerce, then it will not be created in Ucommerce. Example: Product variants have special prices, and has to be updated only when e.g. there is some event (black Friday, Christmas, etc.). All special products could be marked with “NoUpdate” SyncType value and then new prices can be added in Perfion without affecting data in Ucommerce. When the time for update comes, the products can be set back to original SyncType value to resume synchronization. |
SyncMsg | Field | Name of Perfion feature (Text type, not Inheritable, not localizable). Values are of string type. | SyncMsg will be used for synchronization failures reporting for each product. Mandatory field. This is a Sync parameter. |
SyncProduct | Field | String values true|false, or Perfion feature (String type). Values are of string type. Allowed values:
Default value: “false”. | Product synchronization status. Parameter is optional. This is a Sync parameter. If defined with ‘true’, the product will be synchronized with Ucommerce. If ‘false’, then the product will be treated as if it does not exist in Perfion. E.g. if Ucommerce has this product and value is set to ‘false’, then product will be removed from Ucommerce. |
SyncVariants | Field | String values true|false, or Perfion feature (String type, not localizable) Values are of string type. Allowed values:
Default value: “false”. | Product variant synchronization status. Parameter is optional. This is a Sync parameter. If set to ‘true’, Ucommerce Connector will sync variants. This will automatically add variants to the product. If set to ‘false’, then products in Ucommerce will not have any variants. If there was any existing variants in Ucommerce, they will be removed. |
SyncMedia | Field | String values true|false, or Perfion feature (String type, not localizable). Values are of string type. Allowed values:
Default value: “false”. | Product image synchronization status. Parameter is optional. This is a Sync parameter. If set to ‘true’, will use product images. If set to ‘false’, will remove all images from product. |
UCommerceProductDefinition | Field | String value or Perfion feature (Text type, not localizable). Values are of string type, cannot be empty and must match one of existing product definitions in Ucommerce. Min 1 char, max 512 chars. | Ucommerce product definition name. Parameter is mandatory. This is Ucommerce fixed parameter. |
Name | Field | String value or Perfion feature (Text type, not localizable). Values are of string type, and cannot be empty. Min 1 char, max 512 chars. | Name of the product. This parameter will be used for product identification, e.g. like product label. It is the same name, which will be used when products are shown in Ucommerce GUI. Parameter is mandatory. This is Ucommerce fixed parameter. |
DisplayName | Field | Perfion feature (Text type, localizable). Values are of string type. Min 0 char, max 512 chars. | Product display name. This parameter holds the actual product name. Parameter is mandatory. Default: empty string. This is Ucommerce fixed parameter. |
SKU | Field | String value or Perfion feature (String type, not localizable). Values are of string type, and cannot be empty. Min 1 char, max 30 chars. | Product SKU (Stock Keeping Unit). Parameter is mandatory. This is Ucommerce fixed parameter. |
AllowOrdering | Field | String values true|false, or Perfion feature (String type, not localizable). Values are of string type. Allowed values:
Default value: “false”. | Parameter defines if the product can be ordered. Parameter is optional. This is Ucommerce fixed parameter. |
DisplayOnWebSite | Field | String values true|false, or Perfion feature (String type, not localizable). Values are of string type. Allowed values:
Default value: “false”. | Parameter defines if the product should be shown on web site. Parameter is optional. This is Ucommerce fixed parameter. |
ShortDescription | Field | Perfion feature (Text type, localizable). Values are of string type. Default value: “” (empty string). | Short description about the product. Parameter is optional. This is Ucommerce fixed parameter.
|
LongDescription | Field | Perfion feature (Text type, localizable). Values are of string type. Default value: “” (empty string). | Long description about the product. Parameter is optional. This is Ucommerce fixed parameter.
|
UCommerceProductRelationType_<label1> | RelatedProduct | Perfion feature (String type, selectable, not localizable, multivalue). Refer to “In case a custom parameter is identified as invalid, the Connector will show warning and will keep the old value in Ucommerce. Product Relation to Other Products Configuration in Perfion” to see how to create features for product relations to other products in Perfion. Default value: no relations | Related products for different types of Ucommerce related product types. The “To” mapping should match one of the Ucommerce related product type mappings specified in ECommerce Settings for the same channel. All related products mappings must be unique per relation type (e.g. no duplicate related product keyword is allowed for product item for chosen channel). To use this parameter, one has to enable product relations synchronization in ECommerce Settings (SyncProductRelations parameter) and there should be at least one product relation type defined in ECommerce Settings. The parameter is optional. This is Ucommerce fixed parameter. |
UCommerceProductRelationType_<label2> | |||
… | |||
UCommerceProductRelationType_<labelN> | |||
UCommercePriceGroup_<label1> | Field | String value or Perfion feature (String or Number type, not localizable). Values are of decimal type. Default value: 0. | Prices for different price groups. The “To” mapping should match one of the price group mappings specified in ECommerce Settings for the same channel. All price group definitions must be unique (e.g. no duplicate price group keyword is allowed for product item for chosen channel). The parameter is optional. The value if defined as string should use a dot as decimal separator. This is Ucommerce fixed parameter. The product price will be saved in Ucommerce with Minimum Quantity parameter set to 1 if it is a new price. |
UCommercePriceGroup_<label2> | |||
… | |||
UCommercePriceGroup_<labelN> | |||
PrimaryImage | Image, Attachment | Perfion feature (Image or File type, not localizable, not multivalue). Default value: <none> (images will be removed from Ucommerce) | Product primary Image. Parameter is optional. This is Ucommerce fixed parameter. |
ThumbnailImage | Image, Attachment | Perfion feature (Image or File type, not localizable, not multivalue). Default value: <none> (images will be removed from Ucommerce) | Product thumbnail Image. Parameter is optional. This is Ucommerce fixed parameter. |
“Custom Image1” “Custom Image2” … “Custom ImageN” | Image, Attachment | Perfion feature (Image or File type, not localizable, not multivalue). Default value: <none> (images will be removed from Ucommerce) | Other product images. Product has two images by default, but one can have more images by using custom product fields of Image type in Ucommerce product definition. Each parameter may have a single image, which can be specified using one of the shown mappings. The name of image parameter should not match any of fixed Ucommerce or sync parameters. Parameter is optional. This is Ucommerce custom parameter. |
“Custom parameter 1” “Custom parameter 2” … “Custom parameter N” | Field | Perfion feature (Text/String/Number type, not multivalue). Default value: “” (empty string) Refer to Supported Ucommerce Data Types for Custom Parameters for more info. | One can add multiple custom parameters to mappings in order to extend the list of product parameters, but all those custom parameters must be also available in Ucommerce. One can add those custom parameters in Ucommerce by modifying product definition. The name of custom parameter should not match any of fixed Ucommerce or sync parameters. Parameter is optional. This is Ucommerce custom parameter. Parameter must be set up as localizable feature in order to use localizable values. If it is not set up as localizable feature, then only a single value will be used from default language. Default language is chosen as the first language from ECommerce Settings configurations. |
Synchronization parameters are used to determine the scope of synchronization, which items have to be synchronized, relate Perfion items to Ucommerce items, etc. Read more about how synchronization parameters are used in Overview of Synchronization Process Parameters.
Supported Ucommerce Data Types for Custom Parameters
Product, category and variant custom parameters support the following Ucommerce data types:
Ucommerce data type | Values | Description |
ShortText |
| The values sent from Perfion will not be converted or validated and directly saved in Ucommerce. |
LongText | ||
RichText | ||
Content | ||
EmailContent | ||
DatePicker | DateTime string | The values sent from Perfion will be checked if they are recognized as DateTime. |
DateTimePicker | ||
Number | Decimal number | Numbers data type parameters could be defined using string or number features. In case the number is defined using string feature, the number must have decimal number format and one must use a dot (.) as decimal separator. |
Boolean | True values: True, Yes, 1 False values: False, No, 0 | There is no boolean data type in Perfion, but one can map string and number types to Ucommerce Boolean data type by using values as shown in “Values” column. The values are case insensitive. |
In case a custom parameter is identified as invalid, the Connector will show warning and will keep the old value in Ucommerce.
Product Relation to Other Products Configuration in Perfion
In order to relate one product to other products one has to create a selectable multivalue sub-feature for the feature, which is selected as a base feature for product type entity in ECommerce mappings (the feature defined using Context ECommerce Output Kind) like shown in Figure 3. In the figure there are two different types of features added to a Product feature.
The new features will allow to add Product type feature items as selectable values, which can also be understood as adding links to other products.
Product Variant Mapping Parameters
For all variant related mapping parameters “ECommerce Entity” column value must be set to “Variant”.
Variants in Ucommerce are defined by specifying that product definition has at least one extra property, which is related to variant. Then product definition property “Product Family” is updated to ‘true’ and product becomes a product with variants. Products in Ucommerce can be with variants and also without variants. This can be defined for each product item.
Product variant is independent entity in Perfion like product, but in Ucommerce it has the same data as product, but not all fields are used. Therefore, the mappings for variant are similar to those of product mappings.
When Perfion synchronizes products, product variants comes together as part of product data. If anything in product data is modified and has to be updated, then all product data will be resynchronized. This means that variants do not have their own Ucommerce ID. Perfion will use product and variant SKUs to determine if incoming variant matches one of the existing variants and if the match is found, that variant will be updated. Any not matching variants will be deleted and all not existing variants will be created.
In order to be able to synchronize variants, the use of variants should be enabled in ECommerce Settings (parameter VariantSupportEnabled) and in ECommerce product mappings (parameter SyncVariants).
To | Output Kind | Mapping | Description |
VariantOfProduct | VariantOfProduct | Perfion feature (String type, not localizable). Values are of string type and should have key value of the product the variant belongs to. | The mapping is a special mapping to identify variant items in Perfion, which will be the same as Perfion product items. This is a special ECommerce API setup. The parameter is not mandatory from Perfion ECommerce mappings perspective, but it is mandatory in order to use variants. |
SyncVariant | Field | String values true|false, or Perfion feature (String type, not localizable) Values are of string type. Allowed values:
Default value: “false”. | Product variant synchronization status. If set to ‘false’, then variant will be treated as if it does not exist. Parameter is optional. This is a Sync parameter. |
SyncMedia | Field | String values true|false, or Perfion feature (String type) Values are of string type. Allowed values:
Default value: “false”. | Product variant image synchronization status. Parameter is optional. This is a Sync parameter. |
Name | Field | String value or Perfion feature (Text type, not localizable). Values are of string type, and cannot be empty. Min 1 char, max 512 chars. | Name of the variant. This parameter will be used for variant identification, e.g. like variant label. It is the same name, which will be used when variants are shown in Ucommerce GUI. Parameter is optional. This is Ucommerce fixed parameter. |
DisplayName | Field | Perfion feature (Text type, localizable). Values are of string type, and cannot be empty. Min 0 char, max 512 chars. | Variant display name. This parameter holds the actual variant name. Parameter is optional. This is Ucommerce fixed parameter. |
SKU | Field | String value or Perfion feature (String type, not localizable). Values are of string type, and cannot be empty. Min 1 char, max 30 chars. | Variant SKU (Stock Keeping Unit). Parameter is mandatory. This is Ucommerce fixed parameter. |
ShortDescription | Field | Perfion feature (Text type, localizable). Values are of string type. Default value: “” (empty string). | Short description about the variant. Parameter is optional. This is Ucommerce fixed parameter. |
LongDescription | Field | Perfion feature (Text type, localizable). Values are of string type. Default value: “” (empty string). | Long description about the variant. Parameter is optional. This is Ucommerce fixed parameter. |
InventoryOnHand | Field | String value or Perfion feature (String type, not localizable). Values are of integer type. Default value: 0. | A special parameter in Ucommerce to control the inventory count for variant. This parameter is not fixed, so in order to use it, user has to create it in Ucommerce as described here: Ucommerce Documentation Parameter is optional. This is Ucommerce custom parameter. If parameter is not in mappings, then it will be ignored, otherwise default value is 0. |
UCommercePriceGroup_<label1> | Field | String value or Perfion feature (String or Number type, not localizable). Values are of decimal type. Default value: 0. | Prices for different price groups. The “To” mapping should match one of the price group mappings specified in ECommerce Settings for the same channel. All price group definitions must be unique (e.g. no duplicate price group keyword is allowed for variant item for chosen channel). The parameter is optional. The value if defined as string should use a dot as decimal separator. This is Ucommerce fixed parameter. The variant price will be saved in Ucommerce with Minimum Quantity parameter set to 1 if it is a new price. |
UCommercePriceGroup_<label2> | |||
… | |||
UCommercePriceGroup_<labelN> | |||
“Custom Image1” “Custom Image2” … “Custom ImageN” | Image, Attachment | Perfion feature (Image or File type, not localizable, not multivalue). Default value: <none> (images will be removed from Ucommerce) | Other variant images. Variant has no images by default, but one can have some images by using custom variant fields of Image type in Ucommerce product definition. Each parameter may have a single image, which can be specified using one of the shown mappings. The name of image parameter should not match any of fixed Ucommerce or sync parameters. Parameter is optional. This is Ucommerce custom parameter. |
“Custom parameter 1” “Custom parameter 2” … “Custom parameter N” | Field | Perfion feature (Text/String/Number type, not multivalue). Default value: “” (empty string). Refer to Supported Ucommerce Data Types for Custom Parameters for more info. | One can add multiple custom parameters to mappings in order to extend the list of variant parameters, but all those custom parameters must be also available in Ucommerce. One can add those custom parameters in Ucommerce by modifying product definition. The name of custom parameter should not match any of fixed Ucommerce or sync parameters. Parameter is optional. This is Ucommerce custom parameter. If not in configuration, will be ignored. Parameter must be set up as localizable feature in order to use localizable values. If it is not set up as localizable feature, then only a single value will be used from default language. Default language is chosen as the first language from ECommerce Settings configurations. |
Synchronization parameters are used to determine the scope of synchronization, which items have to be synchronized, relate Perfion items to Ucommerce items, etc. Read more about how synchronization parameters are used in Overview of Synchronization Process Parameters.
Category Mapping Parameters
For all category related mapping parameters “ECommerce Entity” column value must be set to “Category”.
Category synchronization is mandatory, because they are required for product synchronization.
Categories may have hierarchy and Ucommerce Connector will create the same hierarchy in Ucommerce.
To | Output Kind | Mapping | Description |
Key | KeyField | Name of Perfion feature (String type, not localizable). Values are of string type and must be unique for all categories. | Key will be used to link Perfion items to the same items in Ucommerce. Mandatory parameter. This is a Sync parameter.
|
SyncID | Field | Name of Perfion feature (String type, not inheritable, not localizable). Values are of string type. | SyncID is used to link category ID defined by Key parameter to external ID of the same item in Ucommerce. Mandatory parameter. This is a Sync parameter. The parameter is updated by Ucommerce Connector after successful synchronization of each category item. |
SyncDate | Field
| Name of Perfion feature (String type, not inheritable). Values are of string type. Date format: “yyyy-MM-dd HH:mm:ss” e.g. “2018-02-12 17:15:09”. | SyncDate is used to show the last synchronization date and it is also used to find out when data has to be synchronized next time. This parameter will be updated from Ucommerce Connector after successful product synchronization. If there was any error while synchronizing a product item, then date will not be updated. Mandatory parameter. This is a Sync parameter. |
SyncType | Field
| Name of Perfion feature (String type, not inheritable, not localizable). Values are of string type. Allowed values:
Default value: “”. | Value defined for this parameter will allow to overwrite default synchronization settings for each category. Parameter is optional. This is a Sync parameter. If no value is specified, then a category will be synchronized using global synchronization settings. If value ‘NoUpdate’ is set, then this value will indicate, that category item should not be updated in Ucommerce. For example, this could be a temporary category, which is created in Perfion, but should not be updated yet. If the category already exist in Ucommerce, then it will be ignored, e.g. not updated and not deleted. If the category does not exist in Ucommerce, then it will not be created in Ucommerce. |
SyncMsg | Field | Name of Perfion feature (Text type, not inheritable, not localizable). Values are of string type. | SyncMsg will be used for synchronization failures reporting for each category. Mandatory field. This is a Sync parameter. |
SyncCategory | Field | String values true|false, or Perfion feature (String type, not localizable). Values are of string type. Allowed values:
Default value: “false”. | Category synchronization status. Parameter is optional. This is a Sync parameter. If set to ‘true’, the category will be synchronized with Ucommerce. If set to ‘false’, then the category will be treated as if it does not exist in Perfion. E.g. if Ucommerce has this category, then it will be removed from Ucommerce. |
SyncMedia | Field | String values true|false, or Perfion feature (String type, not localizable). Values are of string type. Allowed values:
Default value: “false”. | Category image synchronization status. Parameter is optional. This is a Sync parameter. If set to ‘true’, will use category images. If set to ‘false’, will remove all images from category. |
Name | Field | String value or Perfion feature (String type, not localizable). Values are of string type, and cannot be empty. Min 1 char, max 60 chars. | Name of the category. This parameter will be used for category identification, e.g. like category label. It is the same name, which will be used when categories are shown in Ucommerce GUI. Parameter is optional. This is Ucommerce fixed parameter. |
DisplayName | Field | Perfion feature (Text type, localizable). Values are of string type, and cannot be empty. Min 1 char, max 512 chars. | Category display name. This parameter holds the actual category name. Parameter is optional. This is Ucommerce fixed parameter. |
UCommerceCatalogGroupName | Field | String value or Perfion feature (Text type, not localizable). Values are of string type. Min 1 char, max 128 chars. Specified value must exist in Ucommerce. | Parameter to store Ucommerce Product Catalog Group name the category belongs to. Parameter is mandatory. This is Ucommerce fixed parameter. |
UCommerceCatalogName | Field | String value or Perfion feature (String type, not localizable). Values are of string type. Min 1 char, max 60 chars. Specified value must exist in Ucommerce. | Parameter to store Ucommerce Product Catalog name category belongs to. Parameter is mandatory. This is Ucommerce fixed parameter. The product catalog name in Ucommerce is unique per Product Catalog Group (Store). The product catalog defined by this parameter must be in product catalog group defined by UCommerceCatalogGroupName parameter. |
UCommerceCategoryDefinition | Field | String value or Perfion feature (Text type, not localizable). Values are of string type, cannot be empty and must match one of existing category definitions in Ucommerce. Min 1 char, max 512 chars. | Ucommerce category definition name. Parameter is mandatory. This is Ucommerce fixed parameter. |
IsDeleted | Field | String values true|false, or Perfion feature (String type, not localizable). Values are of string type. Allowed values:
Default value: “false”. | Field to tell if category is deleted or not. Can be treated as published/not published or active/not active flag. Parameter is optional. This is Ucommerce fixed parameter. |
DisplayOnWebSite | Field | String values true|false, or Perfion feature (String type, not localizable). Values are of string type. Allowed values:
Default value: “false”. | Parameter defines if the category should be shown on web site. Parameter is optional. This is Ucommerce fixed parameter. |
Description | Field | Perfion feature (Text type, localizable). Values are of string type. Default value: “” (empty string). | Category description. Parameter is optional. This is Ucommerce fixed parameter. |
Image | Image, Attachment | Perfion feature (Image or File type, not localizable, not multivalue). Default value: <none> (images will be removed from Ucommerce) | Category image. Parameter is optional. This is Ucommerce fixed parameter. |
“Custom Image1” “Custom Image2” … “Custom ImageN” | Image, Attachment | Perfion feature (Image or File type, not localizable, not multivalue). Default value: <none> (images will be removed from Ucommerce) | Other category images. Category has a single image by default, but one can have more images by using custom category fields of Image type in Ucommerce category definition. Each parameter may have a single image, which can be specified using one of the shown mappings. The name of image parameter should not match any of fixed Ucommerce or sync parameters. Parameter is optional. This is Ucommerce custom parameter. |
“Custom parameter 1” “Custom parameter 2” … “Custom parameter N” | Field | Perfion feature (Text/String/Number type, not multivalue). Default value: “” (empty string). Refer to Supported Ucommerce Data Types for Custom Parameters for more info. | One can add multiple custom parameters to mappings in order to extend the list of category parameters, but all those custom parameters must be also available in Ucommerce. One can add those custom parameters in Ucommerce by modifying category definition. The name of custom parameter should not match any of fixed Ucommerce or sync parameters. Parameter is optional. This is Ucommerce custom parameter. If not in configuration, will be ignored. Parameter must be set up as localizable feature in order to use localizable values. If it is not set up as localizable feature, then only a single value will be used from default language. Default language is chosen as the first language from ECommerce Settings configurations. |
Synchronization parameters are used to determine the scope of synchronization, which items have to be synchronized, relate Perfion items to Ucommerce items, etc. Read more about how synchronization parameters are used in Overview of Synchronization Process Parameters.
Ucommerce does not use variant options (dimensions), but one can use variant custom parameters to define various data, which could be used as variant options. Perfion supports variant options and Perfion product can be configured to have variant options, but this ECommerce API feature is not used with Ucommerce Connector. Instead, one can define an extra custom parameters for variants in ECommerce mappings, and then interpret this data in Ucommerce as variant options.
Overview of Synchronization Process Parameters
Some facts about synchronization process and parameters involved, which determine how data will be moved around:
Most of configurations for synchronization are controlled from Perfion, but they will be in different areas. The global parameters (ECommerce Settings) will define how synchronization will work for all data and then there will also be other parameters in data entity level (ECommerce Mapping), which will be used to determine how and when different data is synchronized.
Individual synchronization parameters in Perfion (ECommerce Mapping) will be related to the actual data, which is synchronized and will allow to control synchronization more precisely in lower (data) level. The data for Ucommerce synchronization will have product, variant and category data entities. Products and variants will be handled as a single entity, e.g. product will be synchronization item and any product creation, update or deletion will handle all product data including variants. This means that after changing any product related data, the entire product will be resynchronized. The synchronization will not check individual product data fields and will replace everything with new data from Perfion. Perfion categories are an independent data entity and will be handled separately as synchronization item.
Synchronization related parameters used with product and category:
Synchronization item key (Key) will be used to identify synchronization item in Perfion. The key can be Perfion ID or other unique value and will be used with products and categories.
Synchronization item synchronization ID (SyncID) will be used to identify synchronization item in Ucommerce. The SyncID is Ucommerce data entity ID and will be used with products and categories.
Date when synchronization item was last synchronized (SyncDate) will be used to control the age of each synchronization item. The date will be used together with global synchronization parameter DataMaxAgeInMin to determine when each synchronization item must be resynchronized. This parameter will be used with products and categories. Setting this parameter to empty value will be equivalent to telling synchronizer to synchronize this item immediately (e.g. when next synchronization will run). This parameter will be updated every time the item is synchronized. The parameter will not be updated after synchronization if some serious error happens during synchronization so that synchronization of that failed item can be repeated during next synchronization.
Synchronization type of synchronization item (SyncType). This parameter will be used with products and categories and will determine how individual items will be synchronized. This parameter allows to overwrite the global synchronization parameter for individual products/categories. If parameter is not set, then product/category will be handled normally. If parameter is set, then based on parameter value product/category can be ignored in synchronization.
Synchronization status information parameter (SyncMsg). This parameter will be used with products and categories. The parameter will show any warning or error messages related to given synchronization item. If item synchronization will fail, then this parameter will show why it happened. The information about synchronization status will be also written to Ucommerce Connector log file. The full log file cannot be accessed from Perfion, so this parameter allows to better understand what is happening with any synchronization item.
Each data entity may have extra synchronization related parameters, which may increase or decrease the scope of data used for synchronization. These Boolean type parameters will determine which parts of each entity will be synchronized.
Product: SyncProduct, SyncVariants, SyncMedia
Variant: SyncVariant, SyncMedia
Category: SyncCategory, SyncMedia
- 1 Prerequisites
- 2 Ucommerce Connector Configuration File
- 3 Ucommerce Connector as Windows Service
- 4 Ucommerce Connector as Console Application
- 5 Ucommerce Connector as Library for a Custom Application
- 6 ECommerce Data Mapper in Perfion
- 7 ECommerce Data Mapper – Settings
- 8 ECommerce Data Mapping
- 9 Overview of Synchronization Process Parameters