3 Implementation Configuration

This chapter provides information about configuring an implementation.

Data Import Spring Configurations

The system has been designed to support a pluggable model. The DIMP Controller, ImportTranslator, ImportController, ImportDAO, MessageLogger and scheduler are all designed to be configurable at deployment time. This is accomplished through the use of Spring as a deployment configuration framework. Each of these classes is only accessed through their interface. Therefore, any new implementations only need to support the interfaces to be used by the subsystem. Introducing an alternate implementation is done through updates to the Spring properties or context files. No additional code changes are necessary.

Table 3-1 includes the set of Spring bean IDs used for each of the pluggable components.

Note:

1 to 2⁶⁴ - 1 is the logical range of the batchSize, though database performance may require the upper limit to be much smaller than that. Only the implementation team will be able to determine what the actual upper limit should be based upon database performance.

Table 3-1 Spring Bean IDs Used for Each of the Pluggable Components

Spring Bean ID	Provided Implementation	Default Configuration
service_MerchandiseHierarchyImport Translator	oracle.retail.stores.commerceservices item.hierarchy.importdata. MerchandiseHierarchyImport Translator	batchSize=1000
service_StoreHierarchyImportTranslator	oracle.retail.stores.commerceservices store.hierarchy.importdata.Store HierarchyImportTranslator	batchSize=1000
service_TaxImportTranslator	oracle.retail.stores.commerceservices.tax. importdata.TaxImportTranslator	batchSize=100
service_EmployeeImportTranslator	oracle.retail.stores.commerceservices employee.importdata.Employee ImportTranslator	batchSize=1000
service_CustomerImportTranslator	oracle.retail.stores.commerceservices.customer.importdata.CustomerImportTranslator	batchSize=1000
service_ItemImportTranslator	oracle.retail.stores.commerceservices.item.item.importdata.ItemImportTranslator	batchSize=1000
service_PricingImportTranslator	oracle.retail.stores.commerceservices.pricing.importdata.PricingImportTranslator	batchSize=1000
service_CurrencyImportTranslator	oracle.retail.stores.commerceservices.currency.importdata.CurrencyImportTranslator	batchSize=1000
service_ScanSheetImportTranslator	oracle.retail.stores.commerceservices.scansheet.importdata.ScanSheetImportTranslator	batchSize=1000
service_ImportSequence	oracle.retail.stores.commerceservices.importdata.ImportSequence	NA
service_ImportInitiator	oracle.retail.stores.commerceservices.importdata.ImportInitiator	executeImport=false
service_TransformInitiator	oracle.retail.stores.commerceservices.importdata.TransformInitiator	executeTransform=false
service_ImportTranslatorMap	oracle.retail.stores.commerceservices.importdata.ImportTranslatorMap	NA
service_ImportIOAdapter	oracle.retail.stores.commerceservices.importdata.EEImportIOAdapter	NA
service_MessageBuilder	oracle.retail.stores.commerceservices.importdata.MessageBuilder	prefix=***DIMP:
DIMP_Scheduler	org.springframework.scheduling. quartz.SchedulerFactoryBean	triggers=service_ImportJobTriggerAutoStartup=true ApplicationContextSchedulerContext Key=applicationContextWaitForJobsTo CompleteOnShutdown=true

These setting can be found in the ServiceContext.xml file packaged in the config.jar under the /config/context package.

The web.xml in WEB-INF directory has the following configuration under the web-app section.

<context-param>
        <param-name>contextConfigLocation</param-name> 
        <param-value>/WEB-INF/DataImportScheduler.xml</param-value> 
</context-param>

The following servlet should also be configured to start up automatically. The servlet loads the context configuration files necessary for starting DIMP's bundle-polling mechanism. Because the DataImportScheduler.xml file is configured in the context, this file is loaded by the servlet. In the context, the SchedulerFactoryBean is configured to start on load; hence it is invoked and starts the scheduler timer. The timer intervals can be configured from spring.properties. See spring.properties.

<servlet>
        <servlet-name>context</servlet-name>
        <servlet-class>org.springframework.web.context.ContextLoaderServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
</servlet>

Table 3-2 includes additional sets of Spring bean IDs used for each of the pluggable components.

Table 3-2 Additional Spring Bean IDs Used for Each of the Pluggable Components

Spring Bean ID	Provided Implementation	Additional Configuration
persistence_ImportController	oracle.retail.stores.commerceservices.importdata.ImportController	batchSize=1000
persistence_MerchandiseHierarchyImport DAOTarget	oracle.retail.stores.commerceservices.item.hierarchy.importdata.dao. MerchandiseHierarchyImportDAO	dataSource=persistence_dataSource
persistence_StoreHierarchyImportDAOTarget	oracle.retail.stores.commerceservices.store.hierarchy.importdata.dao.StoreHierarchyImportDAO	dataSource=persistence_dataSource
persistence_TaxImportDAOTarget	oracle.retail.stores.commerceservices.tax. importdata.dao.TaxImportDAO	dataSource=persistence_dataSource
persistence_EmployeeImportDAOTarget	oracle.retail.stores.commerceservices. employee.importdata.dao.Employee ImportDAO	dataSource=persistence_dataSource
persistence_ItemImportDAO	oracle.retail.stores.commerceservices.item.item.importdata.dao.ItemImportDAO	dataSource=persistence_dataSource
persistence_PricingImportDAO	oracle.retail.stores.commerceservices.pricing.importdata.dao.PricingImportDAO	dataSource=persistence_dataSource
persistence_CurrencyImportDAO	oracle.retail.stores.commerceservices.currency.importdata.dao.CurrencyImportDAO	dataSource=persistence_dataSource
persistence_CustomerImportDAO	oracle.retail.stores.commerceservices.customer.importdata.dao.CustomerImportDAO	dataSource=persistence_dataSource
persistence_ScanSheetImportDAO	oracle.retail.stores.commerceservices.importdata.dao.ScanSheetImportDAO	dataSource=persistence_dataSource
persistence_ImportErrorHandler	oracle.retail.stores.commerceservices.importdata.ImportErrorHandler	dataSource=persistence_dataSource
persistence_PricingElementsLoader	oracle.retail.stores.commerceservices.pricing.importdata.PricingElementsLoader	NA
persistence_TaxElementsLoader	oracle.retail.stores.commerceservices.item.item.importdata.TaxElementsLoader	NA

These settings can be found in the PersistenceContext.xml file packaged in the config.jar under the /config/context package.

By default, the ImportController's batch size is set to 1000 and all the translators (except TaxImport) are also using the same. Each individual translator can be configured separately to optimize the import per the size of the data operation. Spring sets the batch size value onto the translator when instantiated using the propertyConfigurer. It is the responsibility of the translator to call setBatchSize(int) with that value onto the ImportController.

Note:

Although the application ships with a default batch size set to 1000, the optimum batch size for every deployment is unknown. Determining the optimum size will depend on critical factors only known at deployment including, but not limited to, application server and database sizing. DIMP will perform faster with fewer batches, for example, a higher batch size, but care must be taken not to raise the size too high and exceed the data transaction timeout controlled by the middleware.

Notice that the ID of the DAO beans end with Target. This is because the ID that is actually used by the application returns a Proxy Bean configured to intercept method calls to the DAO and associate transactions with them. Upon ImportExceptions thrown by those methods, the transaction is rolled back. This is an example of Aspect Orient Programming whereby Spring has provided the mechanism to handle the transaction management.

Several configuration files exist containing settings specific to DIMP. Properties are read when the server starts, so any changes require a server restart before they take effect.

spring.properties

Find spring.properties in the following location:

<INSTALL_DIR>\profiles\AppSrv01\properties

The following is an example spring.properties file:

####################################################
## Global settings (applicable to Oracle WebLogic  #
## Application Server)                             #
####################################################
 
# directory in which incoming data import bundles arrive
importdata.file.path=C:/temp/dataimport/incoming
 
# directory in which dimp bundles are archived after processing
importdata.archive.path=C:/temp/dataimport/archive
 
# true/false whether data import scheduler should scan importdata.file.path
execute.import=false

# schedule DIMP to check for new bundles every five minutes between 1:00 and 3:00 AM everyday.
 
# see http://en.wikipedia.org/wiki/CRON_expression for editing CRON expressions.
 
import.scheduler.cronexpression=0 0/5 1-3 * * ?

# name of the DIMP logger config file
logger.filename=dimplogger
 
# default import data batch size for ImportController
importdata.batchsize=1000
 
# Specific import type batch size to override the default size.
# When the attribute is set with a value of 0 then the default batch size is used.
# The attribute is mandatory to be mentioned along with a non null value. The value can be 0.

merchandisehierarchy.importdata.batchsize=${importdata.batchsize}
storehierarchy.importdata.batchsize=${importdata.batchsize}
tax.importdata.batchsize=100
currency.importdata.batchsize=${importdata.batchsize}
customer.importdata.batchsize=${importdata.batchsize}
employee.importdata.batchsize=${importdata.batchsize}
item.importdata.batchsize=${importdata.batchsize}
pricing.importdata.batchsize=${importdata.batchsize}
 
#KeyStore Encryption Properties
keyStoreEncryption.providerName=SunJCE
keyStoreEncryption.hashAlgorithmName=SHA-256
#keyStoreEncryption.jndiName=eis/keystoreconnector
keyStoreEncryption.jndiName=eis/keystoreconnector
keyStoreEncryption.implementationClassName=oracle.retail.stores.simkeystore.siminterface.SimKeyStoreEncryptionService

importdata.file.path and importdata.archive.path are file-system dependent. Windows systems would use paths such as:

C:/temp/dataimport/incoming

Linux systems would use paths such as:

/tmp/dataimport/incoming

Note:

Take care on systems that have more than one Back Office or Central Office or a combination of both: do not configure each to point to the same directory; they will race each other for the incoming bundles.

execute.import determines whether or not data imports execute in the environment. Its default is false. Set this to true to enable DIMP.

logger.filename points to another properties file containing the string values that can be customized for DIMP messages.

dimplogger.properties

This is the file referred to by the value, logger.filename, in spring.properties. It contains text values that can be customized to make DIMP messages easily distinguishable in the oracleretail log file.

Every DIMP message appears with the dimp.prefix. dimp.text1, dimp.text2 and dimp.text3 are used depending on how much information is supplied by the underlying system.

Archive File Format

The Archive File is of the following format:

        META-INF
               MANIFEST.MF
        ItemImport-12345-20032-007.xml
        PriceImport-12345-20032-007.xml
        StoreHierarchy.xml
        …..

The suggested file naming convention for the archive is as follows:

[arbitrary_portion]-[store_id]-[YYYYMMDD]-[NNN].jar

Where [arbitrary_portion] can be used by the implementation team for any value, and [NNN] is the batch ID in the range of 0 through 2^32-1, or 2,147,483,647 (because of the limitations of the XSD int datatype). This is a sequential number that is used to allow more than one bundle with the same [YYYYMMDD], if more than one exists on the server at a time. When more than one file does exist, the file creation time is used to determine the order in which they are processed. The date is only available for visual reference. If the file name is not formatted as above, the values in the manifest are used instead. However, if both the archive file name and the file names within the manifest contain a batch ID, the value in the archive file name takes precedence.

There is no restriction on the file names and they can be in any format. But the exact file names have to be listed in the MANIFEST.MF.

The format of the MANIFEST.MF is as follows:

Manifest-Version: 1.0
 
# This manifest describes the contents of an archive referred to as a
# bundle. The following two values list the ID of the batch that
# produced this bundle and the ID of the destination store to receive
# it. The BatchID should be numeric less than 2^32-1.
 
BatchID: <N>
StoreID: <NNNNN>
 
# The following section lists the files contained in this bundle archive.
# Each key should begin with "FileN" without quotes and N being a number.
# The value of the key consists of a bundle entry file name followed
# by hard brackets containing a list of files that should be processed
# before it.
#
# e.g. File1: ItemImport.xml[TaxImport.xml,StoreHierarchyImport.xml]
#
# The order of the files or their dependency list is not important.
 
File1: <filname1>[<optional dependencies>]
...
FileN: <filnameN>[<optional dependencies>]

With the exception of manifest.mf, path names should not be used when creating the manifest. In Figure 3-1, note that the path column is empty except for meta-inf, the path for manifest.mf.

Figure 3-1 Adding Files To a Jar

Note:

WinZip can be used to create a bundle, inspect the bundle, as well as add, delete, or modify the XML contents. Care should be taken to use text editors that will not corrupt the contents, as often happens when using Notepad. Alternately, use the following jar command line utility (from a Java Standard Development Kit) to create a bundle:

C:\temp\dataimport\archive>%JAVA_HOME%\bin\jar -cvfm test_coupon3.jar manifest_details.txt PricingImportSample_addCouponDiscount.xml ItemImportSample_addCoupon.xml

In Figure 3-2, note that the Save full path info option at the bottom is not selected.

Figure 3-2 Adding Files To A WinZip Archive

The following is an example of a manifest file:

Manifest-Version: 1.0
 
# This manifest describes the contents of an archive referred to as a
# bundle. The following two values list the ID of the batch that
# produced this bundle and the ID of the destination store to receive
# it. The BatchID should be numeric less than 2^32-1.
 
BatchID: 1
StoreID: 04241
 
# The following section lists the files contained in this bundle archive.
# Each key should begin with "FileN" without quotes and N being a number.
# The value of the key consists of a bundle entry file name followed
# by hard brackets containing a list of files that should be processed
# before it.
#
# e.g. File1: ItemImport.xml[TaxImport.xml,StoreHierarchyImport.xml]
#
# The order of the files or their dependency list is not important.
 
File1: TaxImport.xml[]
File2: MerchandiseHierarchyImport.xml[]
File3: ItemImport.xml[TaxImport.xml,MerchandiseHierarchyImport.xml,StoreHierarchyImport.xml]
File4: ItemImport2.xml[ItemImport.xml]
File5: PriceImport.xml[ItemImport2.xml]
File6: StoreHierarchyImport.xml[]
File7: EmployeeImport.xml[StoreHierarchyImport.xml]

Oracle Retail Merchandising System Configuration

If the retailer is integrating with Oracle Retail Merchandising System, it is assumed that the retailer is setting up items within Oracle Retail Merchandising System, and not using this feature in Back Office. If the retailer chooses to add or edit an item within Back Office, then that item data might be overridden by the next download from Oracle Retail Merchandising System.

Some data fields are defaulted to the values shown in Table 3-3.

Table 3-3 Oracle Retail Merchandising System Default Values in the Back Office Item Maintenance Screen

Back Office Data Field	Default Value when Integrating with Oracle Retail Merchandising System or Limitation
Cost	0
Class	Items belong to one class only
Manufacturer	Null
Planogram	Null
Labels/Tags Template Type	Default
Serialized	FALSE
Restocking Fee	FALSE
Activation Required	No
Registry Eligible	No
Employee Discount Eligible	Yes
Damage Discount Eligible	Yes
Size Entry Required	No
Authorized for Sale	Active
Item Department	The first department in the drop down list. If no Item Department is specified, then the value is defaulted to the first value in the drop down list.

Service items (non-merchandise items that are non-inventory) need to be loaded separate from the download process.

In Oracle Retail Merchandising System, differentiators 1 and 2 are sent as values and are mapped to COLOR and SIZE in Point-of-Service.

1 = COLOR
2 = SIZE

Oracle Retail Price Management Configuration

If the retailer is integrating with Oracle Retail Price Management, it is assumed that the retailer is managing items and pricing within Oracle Retail Price Management, and not using this feature in Back Office. If the retailer chooses to add or edit an item within Back Office, that item data might be overridden by the next download from Oracle Retail Price Management. Oracle does not provide support for using Back Office to manage items and pricing when in an integrated environment with Oracle Retail Price Management.

During this phase of the integration, some data fields are defaulted to the values shown in Table 3-4.

Table 3-4 Oracle Retail Price Management Default Values

Back Office Screen	Back Office Data Field	Default Value when Integrating with Oracle Retail Price Management or Limitation
Discount Rule	Accounting Method	Discount
Discount Rule	Deal Distribution	Target
Discount Rule	Target Quantity	1
Price Maintenance	Start Time	0:00
Price Maintenance	End Time	23:59:59
Price Maintenance	Status	This field is deprecated and no longer used. The status is determined from the effective and expiration dates.
Price Maintenance	Template Type	Default