Perfion Ucommerce Cache Manager Setup
- Morten Lindequist Køhler
The Perfion Ucommerce Cache Manager is a pipeline task service in Ucommerce which allows resetting the cache in Ucommerce for the entities which were handled by Perfion Ucommerce Connector. The Cache Manager is an independent application which is not needed for Perfion Ucommerce Connector to work, but it can be useful if data synchronized with Perfion is not correctly refreshed in Ucommerce or cause other issues.
Overview
Perfion Ucommerce Connector is an independent app/service from Ucommerce installation and has no direct relation to it. Ucommerce, however, caches all data it handles and do not know anything about Perfion Ucommerce Connector and what it does. Even though Perfion Ucommerce Connector uses Ucommerce API for data synchronization, the Ucommerce API does not support Ucommerce cache handling. Practically the Perfion Ucommerce Connector will synchronize data directly with Ucommerce database without updating cache related to that data in Ucommerce. The Ucommerce may still keep the old data state cached in the memory which can lead to various data handling issues. For example, the data synchronized with Perfion will not show up in Ucommerce back-end or front-end until the cache is cleared and refreshed from the database. The data if modified from Ucommerce directly from the back-end can conflict with the data saved in the database, e.g. the Ucommerce back-end may try to update some data which no longer exist in Ucommerce, because the Perfion Ucommerce Connector have already removed that data.
The Cache Manager is integrated directly into Ucommerce as a pipeline task which runs during Ucommerce initialization sequence. Once executed it will run in a background task as long as Ucommerce is active.
Once started, the Cache Manager will request the data from Perfion about recently performed synchronizations and will clear the cache for those products and categories which were newly synchronized. The Cache Manager will clean cache not just for product and category, but also for all entities related to these entities, e.g. prices, descriptions, relations, product variants, etc.
The table below shows an example how the Cache Manager works. The example is provided given that Ucommerce Connector and Cache Manager were already initialized and are both running.
# | Perfion Ucommerce Connector | Perfion Ucommerce Cache Manager |
1 |
| Send request to Perfion via Ecommerce API to get data about synchronized entities. No new data found, wait predefined time interval until the next check. |
2 | A new product found for synchronization. Synchronize the product by updating its data in Ucommerce database. After synchronization is completed, write the status about product synchronization back to Perfion. |
|
3 |
| Send request to Perfion via Ecommerce API to get data about synchronized entities. New data found. Delete all cache related to the newly synchronized product from Ucommerce cache. |
Configuration File
Cache Manager uses a configuration file. The configuration file (Config.xml) is located in Cache Manager’s installation folder. All configuration file parameters are shown in the table below:
Parameter name | Description |
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. The format of log file name will be: <date>_CacheManager_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”. |
ECBaseURL | Base URL to Perfion API, e.g. where ECommerce API and Perfion API queries can be called from. |
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.
|
EntityUpdateCheckIntervalInSec | The time interval in seconds how often the Cache Manager should check if there are any newly synchronized entities. Default: 60 seconds Values (integer): > 0 |
UcommerceSessionProivder | The name (ID) of Ucommerce session provider. Default: <empty value> If no value is defined, then Cache Manager will try to get the default Ucommerce session provider. All session providers are defined in Ucommerce configuration files. By default it can be found in Core.config file which should be located in ‘ucommerce\Configuration’ folder. The session provider name which can be used in Cache Manager is the session provider service component ID in Ucommerce configuration file. |
Perfion Ucommerce Cache Manager Installation
Perfion Ucommerce Cache Manager can be installed in Ucommerce by copying its files from the Ucommerce Connector package to Ucommerce.
Copy the ‘Perfion.CacheManager’ folder from Perfion Ucommerce Connector package folder to the default Ucommerce application folder. By default it is in ‘ucommerce\Apps’ folder.
Change the Cache Manager parameters in ‘Config.xml’ file. The configuration file by default use the default configuration parameter values and has to be updated, e.g. one has to define the URL where the Ecommerce API web service is located.
Starting Perfion Ucommerce Cache Manager
The Cache Manager is design to start together with Ucommerce. If at the time of Cache Manager installation the Ucommerce is running, then the Ucommerce web service application pool in IIS must be recycled and then one must also open the Ucommerce admin page to trigger the Ucommerce initialization sequence.
NOTE: It is not necessary to login into Ucommerce admin in order to start Ucommerce initialization.
During Ucommerce initialization sequence it will also start the Cache Manager which will run in a background process until the Ucommerce is terminated.
Note that in case there are some errors and the Cache Manager cannot start for some reason, then one should look in Ucommerce log file for more information what is happening. The Ucommerce (or its parent CMS system) logs location will differ based on CMS type and its configuration.
Once the Cache Manager is up and running, then it will create its own log file which will be located in the folder specified in its configuration file.
The Cache Manager depends on Ucommerce, so if the Ucommerce process is stopped for some reason, then the Cache Manager will also be terminated. It was observed that in some cases Ucommerce process can stop automatically if, for example, the Ucommerce was not used for some time. In this case the Cache Manager may not run continuously. To make sure the Ucommerce and/or Cache Manager runs continuously, one may need to change Ucommerce configuration or to set up some keep alive service which would periodically activate Ucommerce. Even if the Ucommerce and the Cache Manager are stopped for some time, it should not cause any problems, because the Cache Manager will be re-activated as soon as Ucommerce comes online. There is also no need to clear any cache in Ucommerce if it is not running.
Stopping Perfion Ucommerce Cache Manager
The Perfion Ucommerce Cache Manager cannot be stopped manually. Once running it is dependent on Ucommerce and will terminate together with Ucommerce. So in order to stop the Cache Manager one has to stop the Ucommerce web service application pool instance in IIS.
Note that typically it can take up to a minute before the Cache Manager is stopped after the Ucommerce web service was terminated.
An alternative way to prevent the Cache Manager from doing any cache resets in Ucommerce without stopping the Ucommerce itself would be to decouple it from Ecommerce API. In this case it will still continue to run, but if it cannot receive any data from Perfion, then it will not do any synchronizations.
Perfion Ucommerce Cache Manager Workflow
The Cache Manager when it runs retrieves the information about all performed synchronizations from Perfion via Ecommerce API. Then it compares all received data with the data it has already processed. The previously processed data will be saved in ‘SyncData.xml’ file which is located in the Cache Manager folder. If the file is not found during the start of Cache Manager, then it will reset cache for all entities which are known to Perfion and will save this state by creating a new ‘SyncData.xml’ file.
The next time the Cache Manager performs a check it will compare the data which was processed in previous checks and will clear cache only for those entities which were actually updated by Ucommerce Connector (if there are any new). Any new changes to the current state will be continuously updated to the ‘SyncData.xml’ file so that the Cache Manager can be restarted at any time without losing its state.
Resetting Perfion Ucommerce Cache Manager
To change any of Cache Manager parameters one has to restart it. However, in order to restart the Cache Manager on has to recycle the Ucommerce web service. This may not be possible if Ucommerce is in use and cannot be stopped. Therefore, there was implemented a possibility to reset/update Cache Manager configuration parameters while it is running.
To reset parameters delete the ‘SyncData.xml’ file. Before each check the Cache Manager will check if this file is present. If not, then the Cache Manger will reset itself by reinitializing everything. This means that it will read in the ‘Config.xml’ file and apply any changes there might be as compared to the parameters it have started with. In addition, it will resynchronize all entities and will create a new ‘SyncData.xml’ file.
Disabling Perfion Ucommerce Cache Manager
The Cache Manager will always start with Ucommerce, but if there is a need to temporary disable it, then one can rename the folder of the Cache Manager by adding a ‘.disabled’ suffix to it, e.g. from ‘Perfion.CacheManager’ to ‘Perfion.CacheManager.disabled’. Any Ucommerce applications which are located in the folders with ‘.disabled’ suffix will be ignored during Ucommerce initialization.