6 Installing the AIP Integration Components

In order to exchange information between AIP Online, RPAS, and RMS (or an external system), the interface portion of the AIP Online suite must be installed, which consists of the following steps:

Installing RETL (Retail Extract Transform and Load)
Extracting the AIP integration/database files
Configuring the environment

Installing RETL

Refer to the Oracle Retail Extract Transform and Load (RETL) Programmer's Guide for detailed installation instructions on this product. Following the successful installation of RETL, test the application to verify the environment was set up properly and the RETL binary was installed correctly.

log in to the UNIX server as the rfx user.
At the UNIX prompt, enter rfx. A command-line error appears if all environment variables are setup properly, as shown in the following example.

Example:
```
/u00/retl> rfxError: Flow file argument ('-f') required!
```

Verify that the RETL binary is installed properly and the database environment variables are correct by executing the verify_retl script. This script runs a series of validation steps and displays a confirmation message if the environment is set up correctly. Upon confirmation, the RETL environment is now ready to be configured.

Example:

/u00/retl> verify_retl -doracle
Checking RETL Environment...found ORACLE environment...passed!
Checking RETL binary...passed!
Running samples...passed!
 ____________________________________________________________________________
Congratulations! Your RETL environment and installation passed all tests.
See the programmer's guide for more information about how to further test your database installation (if applicable).
 ___________________________________________________________________________
Exiting...saving output in /tmp/verifyretl-1843208.log

Note:

The database parameter passed with the verify_retl script varies depending on the type of database to which RETL is configured. Refer to the Oracle Retail Extract Transform and Load (RETL) Programmer's Guide for the specific parameters permitted in this script.

Extracting AIP Integration Files

The integration files contain the necessary RETL flow and schema files that describe the integration process. In addition to the integration files, several batch shell scripts are required to transfer data between AIP Online, RPAS, and RMS (or an external system). The integration files must be extracted to the same server where RETL is installed. It is recommended that RETL and the integration files reside on the database server.

Both online integration files and batch scripts are configured and installed through the AIP Online Application Server Installer during the Integration steps.

If these files need to be moved to another server after completing the installation process, you need to perform the following:

Zip the contents of the AIP Online Integration directory specified during the Application Server Installer.
Move the zip file to the desired server.
Proceed to "Editing the .profile to Run cron_export.sh and cron_import.sh Scripts" and perform the necessary tasks.
Once the integration files have been installed, you can use the rfx or retail UNIX user account to run the integration/database scripts.

Configuring Your Environment

The AIP Online Application Server Installer configures the following configuration files, which are discussed in the following sections:

File	Description	Section
config.xml	RETL configuration file	"Configuring the config.xml File"
aip_env_online.sh	AIP configuration file	"Editing the aip_env_online.sh to Run cron_export.sh and cron_import.sh Scripts"

Configuring the config.xml File

This configuration file contains the database connection information for RETL for both import and export. Refer to the Oracle Retail Extract, Transform, and Load (RETL) documentation for detailed descriptions of element definitions. Essentially, the Oraread section describes the database for the export and Orawrite for the import; both would normally be the same. Databases can be local or remote, but if they are remote they must be reachable by normal means (that is, should be an entry in tnsnames.ora and reachable by SQLPlus). The database can be clustered or standalone. Config.xml file is created by AIP installer during installation.

The Oracle export arraysize needs to be set dynamically in the config.xml file depending on the server's capabilities. The recommended default arraysize value is 2000. Setting the value too high can cause an out of memory error. The value can be set up to 10,000 to maximize performance based on server capability.

The dbuseralias property should be set to the alias used for AIP database credentials in the RETL wallet. See Appendix B, "Appendix: Setting Up Password Stores with Oracle Wallet" for details on creating RETL database credentials

When installing to a RAC database, the property jdbcconnectionstring should be set using the description field of tnsnames.ora file.

The resulting saved value of this field in config.xml should look like Example 6-1:

Example 6-1 Saved Value from the Description Field of tnsnames.ora file

jdbc:oracle:thin:@(DESCRIPTION =(ADDRESS_LIST =(ADDRESS = (PROTOCOL = TCP)(HOST = mspvip92)(PORT = 1521))(ADDRESS = (PROTOCOL = TCP)(HOST = mspvip93)(PORT = 1521))(LOAD_BALANCE = yes ))(CONNECT_DATA =(SERVICE_NAME = qaolr13)))

Note:

The jdbcconnectionstring property is only required for RAC database and is not needed for non-RAC database.

Editing the aip_env_online.sh to Run cron_export.sh and cron_import.sh Scripts

In order for the cron_export.sh and cron_import.sh to function correctly, the AIPOnline Application Server Installer configures the aip_env_online.sh file with the following environment variable

Environment Variable	Description
ONL_SCHEMA_OWNER	This variable must be set to the owner of AIP online schema.
ONL_DB_ALIAS	This variable must be set to the Oracle Wallet alias used by AIP shell scripts to access the Oracle database.

The following environment variables are also set in aip_env_online.sh:

Environment Variable	Description
INTEGRATION_HOME	This is the path to the integration directory extracted earlier (where the cron_export.sh and cron_import.sh shell scripts reside). Refer to the Oracle Retail Advanced Inventory Planning Implementation Guide for information on the parameters to be set.
RETL_MAX_HEAP_SIZE	This parameter is used by the virtual machine. It is set to a default value of 700M. However, it can be changed dynamically to xxxM or yG to limit the memory usage by the virtual machine.
RETL_INIT_HEAP_SIZE	This parameter is used by the virtual machine. It is set to a default value of 200M. However, it can be changed dynamically to xxxM or yG to set the initial memory assigned to RETL.

Note:

A batch scheduler should be set up to run cron_export.sh and/or cron_import.sh.

Editing the .profile to Run cron_export.sh and cron_import.sh Scripts

In order for cron_export.sh and cron_import.sh scripts to run correctly, the following variables must be modified in the UNIX user .profile file. Refer to the Oracle Retail Advanced Inventory Planning Implementation Guide for further details on how these values are used.

Table 6-1 Variables for the cron_export.sh and cron_import.sh Scripts t

Variable	Description
RFX_HOME	This variable points to the RETL installation home.
RFX_TMP	This variable points to the tmp directory under RFX_HOME.
ORACLE_HOME	This variable points to the Oracle database home.
JAVA_HOME	This variable points to required JRE version for use by RETL.
TEST_ONL_INTEGRATION_HOME	This value should be the directory where cron_import.sh and cron_export.sh reside. The INTEGRATION_HOME variable in aip_env_online.sh references this externally-defined variable by default. Using this externally-defined variable allows multiple testers to use the same aip_env_online.sh while working in different test directories. If the INTEGRATION_HOME variable in aip_env_online.sh is changed to reference a hardcoded directory, this variable is not needed.
TEST_RETL_CONFIG_FILE	This value should contain the fully-qualified path and filename of a RETL configuration file containing database connection information. The RETL_CONFIG_FILE variable in aip_env_online.sh references this externally-defined variable by default. Using this externally-defined variable allows multiple testers to use the same aip_env_online.sh while referencing different RETL configuration files. If the RETL_CONFIG_FILE variable in aip_env_online.sh is changed to contain a hardcoded value, this variable is not needed.
TEST_AIPDOMAIN	This value should contain the fully-qualified path of the AIP RPAS global domain. The AIPDOMAIN variable in aip_env_online.sh references this externally-defined variable by default. Using this externally-defined variable allows multiple testers to use the same aip_env_online.sh while working with different test domains. If the AIPDOMAIN variable in aip_env_online.sh is changed to reference a hardcoded domain, this variable is not needed.

The source call to load the profile is to setup environment variables to enable programs to function correctly (for instance; setting ORACLE_HOME and paths so that sqlldr functions correctly).

Example:

The following sample code can be defined in user .profile file:

export RFX_HOME=<path from root>/rfx/rfx-13.1
export ORACLE_HOME=<path from root>/oracle/product/12.1.0.1
export JAVA_HOME=<path of required JRE version compatible with RETL version>
export TEST_ONL_INTEGRATION_HOME=<path to integration directory>
export TEST_RETL_CONFIG_FILE=<path and filename of RETL config file>
export TEST_AIPDOMAIN=<path of the AIP RPAS global domain>
export RFX_TMP=$RFX_HOME/tmp
 
export PATH=$RFX_TMP:$RFX_HOME/bin:$ORACLE_HOME/bin:$JAVA_HOME/bin:$JAVA_HOME/jre/bin:$PATH
export 
PATH=$TEST_ONL_INTEGRATION_HOME:<full PATH to BSA folder>:$TEST_ONL_INTEGRATION_HOME/scripts:$PATH