Oracle Enterprise Data Quality Address Verification Server Installation and Upgrade Guide, 12c (12.2.1.4.0)

1.1 Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Accessible Access to Oracle Support

Oracle customers who have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

1.2 Conventions

The following text conventions are used in this document:

Convention	Meaning
boldface	Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.
italic	Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.
`monospace`	Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1.3 Installing the Address Verification Server

This section describes the prerequisites for installing Address Verification Server, and how to install it on different EDQ Server environments.

1.3.1 Installing Prerequisites

EDQ AV requires version 9.0.10 or later of EDQ to be installed.

For more information about installing EDQ, see the Oracle Enterprise Data Quality Installation Guide for the release you want to install.

1.3.2 Additional Components You Can Install

The other components that can be selected during installation are:

Install Manager: installs the required data files, purchased separately from Loqate.
Batch Processor: allows standalone use of EDQ Address Verification
Demo Interface: allows EDQ Address Verification to be tested without an EDQ environment.

1.3.3 Obtaining the EDQ Address Verification Product

The EDQ Address Verification ZIP installation file can be downloaded from the Oracle Software Delivery Cloud. Use the following procedure:

Note:

Oracle may release new versions of EDQ Address Verification as bundle patches. Visit My Oracle Support (https://support.oracle.com/) to find the latest version.

Enter the Oracle Software Delivery Cloud URL into a web browser:

http://edelivery.oracle.com/
Click Sign-in/Register.

Note:

If you are not already logged in, the Oracle Single Sign-On page appears. Enter your Oracle user id and password and click Sign In.

The Terms & Restrictions page appears
Click the Oracle Software Delivery Cloud Trial License Agreement and the Export Restrictions check boxes, and then click Continue.

The Media Pack Search page appears.
On the Media Pack Search page, do the following:
1. Click the Select Product Pack drop-down list and select or Oracle Fusion Middleware from the Select a Product Pack drop-down list.
2. Click the Platform drop-down list and select the platform on which you are installing EDQ.
3. Click Go.
The Results list expands to show all available media packs that include your search criteria.
Select the Oracle Enterprise Data Quality Address Verification Server Media Pack option.
Click the Download button.
Browse to the directory where you want to save the file. Click Save to start the file download. A ZIP file is downloaded.
Extract the ZIP file to a temporary directory.

1.3.4 Installing Address Verification On a Windows Environment

Extract the EDQ Address Verification ZIP file to the chosen directory on your EDQ Server.
Navigate to the windows sub-directory of the extracted directory.
Right-click the installation file suited to your Windows environment and select Run as administrator:
- setup_win_x64_vs2005
  or
- setup_win_x64_vs2019
Specify the installation directory. The default is C:\Program Files\EDQAV\ though you can specify a different directory.
Select the C++ API, Java API, and Install Manager components for installation. The other components are optional.

The penultimate installer wizard window contains the path to the Install Manager component. Make a note of this path so you can run the Install Manager once the installation is complete and verified.
When the installation is complete, ensure that the av.properties file in the oedq_local_home/av directory of the EDQ installation points to the Address Verification Server installation location. See Configuring Address Verification Server for further details.
If you changed your av.properties file, then restart the EDQ Application Server.
Verify that the SYSTEM path variable has been added. For example:
1. On a Windows 7 operating system, open the Control Panel then double-click System, and then select Advanced system settings.
2. Select the Advanced tab
3. Click Environment Variables.
4. If the PATH variable does not contain the Address Verification installation path, add it manually using a semicolon to separate it from the other paths listed.
5. Restart your server.

1.3.5 Installing Address Verification On a Linux or UNIX Environment

To install the Address Verification Server onto a Solaris, AIX, or Linux environment use the following procedure:

Extract the EDQ Address Verification ZIP file to a temporary directory on your EDQ Server.
Go to the sub-directory relating to your server platform, aix, hpux, linux, or solaris.
Ensure that the permissions for the installer file allow you to run it or change them using the chmod command.

For example, for the Solaris installer the command would be:

chmod +x solaris_sparc_installer
Run the installer for your server platform. For example, ./linux_installer_x64.

For linux there are two installers:
- linux_installer_x64
  or
- linux_installer_x64-gcc7
For AIX the installers are:
- aix71_installer
  or
- aix72_installer
For hpux, the installer is hpux_installer.
Specify the installation directory. The default is /opt/edqav though you can specify a different directory.

The Address Verification components are displayed in a numbered list. The currently selected components are indicated by an asterisk to the left of the component.
Select 11 to continue the installation and install the default components.
The penultimate installer wizard window contains the path to the Install Manager component. Make a note of this path so you can run the Install Manager once the installation is complete and verified.
When the installation is complete, ensure that the av.properties file in config/av directory of the EDQ installation points to the AV Server installation location. See Configuring Address Verification Server for further details.
If the av.properties file has been changed, restart the EDQ Application Server.

1.3.6 Installing Published Processors

You can install these two published processors that summarize the results of the Address Verification processor:

The Summarize Address Verification processor is a published processor that summarizes the results of the Address Verification processor. It reads the av.AccuracyCode flag added by Address Verification and produces a number of results views that indicate how many records were verified, to which level, whether postal codes were modified or not, and other views.
The Summarize GeoCoding Results processor is a published processor that runs on the data after Address Verification where the geocoding option is enabled, and summarizes the GeoCoding results in terms of accuracy.

The processors are contained in a .dxi file in the additional processors directory of the extracted Address Verification ZIP file.

To install the processors:

Do one of the following to begin the installation:
- Start EDQ Director. Select File, then select Open Package File.... Go to the additional processors directory, and then double-click on the Summarize Address Verification.dxi or Summarize GeoCoding Results.dxi file.
- Start EDQ Director. Go to the additional processors directory and then drag the Summarize Address Verification.dxi and Summarize GeoCoding Results.dxi files into the Project Browser.
- Go to the additional processors directory then double-click one of the .dxi files to start EDQ Director.
Click and drag the Summarize Address Verification and Summarize GeoCoding Results processors into the Published Processor directory to complete installing these processors.

1.3.7 Installing the Global Knowledge Repository

The Global Knowledge Repository, comprising the data used by Address Verification, must be purchased directly from Oracle's partner, Loqate. The repository is installed by running the Install Manager, an Address Verification component which is added during installation.

You can execute the InstallManager utility either from the graphical user interface or command line. The install instructions are specific to purchased licenses. Follow the instructions to install the data that are pertaining to your purchased licenses. You will require a License Key from GBG Loqate. Ensure always to select the option to install the Knowledge Base data files. For detailed instructions on installing data files, refer to Data installation and update process.

Oracle recommends that you use the following directories when you install the Global Knowledge Repository data files:

Windows: C:\Program Files\EDQAV\data.
Solaris, AIX or Linux: /opt/edqav/data.

You must ensure that your installation directories are correctly specified in the av.properties file, see Configuring Address Verification Server for further information.

Note:

If you have multiple EDQ Servers that all require the use of Address Verification, both the Address Verification Server and data files can be mounted on a network file system and shared between multiple servers.

1.4 Upgrading EDQ Address Verification

This section describes how to upgrade the Address Verification Server and the Global Knowledge Repository.

You must upgrade both the Address Verification Server and the Loqate Global Knowledge Repository data files that it uses. Newer versions of the Address Verification Server will not work with old versions of the Global Knowledge Repository data files.

You must obtain the Global Knowledge Repository data files from Oracle's partner GBG Loqate.

1.4.1 Upgrading Your Address Verification Server

Use the following procedure to upgrade Address Verification Server:

Rename (or backup then delete) the current directory or directories containing your Address Verification Server and its data files.
Install the new version into the directory location where the previous version was installed. It is not necessary to change any system path variables, nor the av.properties file that EDQ uses to find the Address Verification Server.

1.4.2 Upgrading the Global Knowledge Repository

You can upgrade the Global Knowledge Repository without upgrading the Address Verification Server to ensure that you are using the most recent address data. You can use the Install Manager, which verifies the software version and provides only the data that is valid for the installed version. For more details, refer to Data installation and update process.

Alternatively, you can manually upgrade the Global Knowledge Repository using the following steps:

Stop the Address Verification Server.
Back up the contents of the existing data directory to another file location.

Tip:

You can delete these files when the upgrade is completed successfully.
Copy the new Global Knowledge Repository data files, that you obtained from Loqate, into the data directory.
Start your Address Verification Server.

1.5 Configuring Address Verification Server

After the EDQ Address Verification API and data files are installed, EDQ must be configured to use them. You must modify the av.properties file found in the av subdirectory of the EDQ local home directory.

This file must contain the correct paths to the installed Address Verification software and data, as defined in the following properties:

loqate.datadir: The location of the Loqate data.
loqate.libdir: The location of the EDQ Address Verification library files.
loqate.jar: The location of the Loqate JAR file.

The values of these properties vary depending on your installation environment. Oracle recommends the following:

Configuration Property	Suggested Windows Path	Suggested UNIX Path
`loqate.datadir`	`C:\\Program Files\\EDQAV\\data`	`/opt/edqav/data`
`loqate.libdir`	The DLL directory must be on the system path (this property is not required.)	The directory need not be on the system path. This property is used to set the location, for example: `loqate.libdir = /opt/edqav/`
`loqate.jar`	`C:\\Program Files\\EDQAV\\loqate.jar`	`/opt/edqav/loqate.jar`

Note the following:

On UNIX operating systems, the library directory must be set on the shared library path. On AIX, use LIBPATH; for all other UNIX operating systems, use LD_LIBRARY_PATH. This requirement does not apply to Linux operating systems.
If you edit the av.properties file, you must restart your EDQ Application Server.

1.6 Enabling Certified Address Verification Outputs

The EDQ Address Verification processor supports the output of certified data formats. The following certifications are supported:

SERP (for Canada)
CASS (for United States)
AMAS (for Australia)

CASS and AMAS use additional libraries which need to be installed in the same directory as the EDQ AV binaries. You need to ensure that the path to this directory is added to the LD_LIBRARY_PATH environment variable.

Each of the certified output formats requires the license of the appropriate data files from Loqate. Once a license that enables this data has been procured, the Loqate Install Manager is run to install the additional data files and in the case of CASS and AMAS, the additional libraries.

For more information, see section ”Support for certified Address Verification outputs (SERP, CASS and AMAS)” at http://www.oracle.com/technetwork/middleware/oedq/edq1221nf-2744179.pdf

1.7 Troubleshooting the Installation

This section describes common errors encountered when installing EDQ Address Verification, and how to resolve them.

1.7.1 Incomplete Installation

Error

A process containing the Address Verification processor is run, and all the output fields are blank except for av.Accuracy Code, which has a value of -1.0. Additionally, an error is recorded in the main EDQ server log file, oeqd_home/logs/main0.log, in the following format:

WARNING: [dd-MMM-yyyy hh:mm:ss: OAV Java API jar "[path to loqate.jar]" does not exist.

Cause

Address Verification was not installed in the path referred to in the av.properties file. Verify that the software has been installed and that the paths in this file are correct. At a minimum, the following API files must be installed:

Windows EDQ Server	Linux/Solaris/AIX EDQ Server
`lqtcr.dll`	`liblqtcr.so`
`loqate.jar`	`liblqtjava.so`
`lqtjava.dll`	`loqate.jar`

Resolution

Perform the installation process again.

1.7.2 Invalid Data Directory

Error

After installing EDQ Address Verification Server, the following error may be written to the main0.log file when EDQ starts:

WARNING: 29-Aug-2012 15:34:49: widget bean com.datanomic.director.widget.loqator.server.LoqatorBean reported as dead: OAV data directory "C:\Program Files\EDQAV\data" not found or invalid (Code: 247,002)

Cause

In order to load the Address Verification processor, EDQ requires a valid data directory containing the Loqate Global Knowledge Repository data files. Although the set of data files (.lfs files) that are installed may vary depending on the licensed regions or countries, there must be a valid data directory. During startup EDQ attempts to locate the loqate.ini file in the path stated in the loqate.datadir property in the av.properties file. If the loqate.ini file is not present in the defined location, this error occurs.

Resolution

Ensure that you have a valid loqate.ini file. This should be provided to you by Loqate as part of the delivery of the licensed Global Knowledge Repository data files. Ensure that this file is present in the directory defined by the loqate.datadir property.

1.7.3 Missing Required File in Solaris Installation

Error

After installing EDQ Address Verification Server on Solaris, the following error may be written to the main0.log file on startup of the EDQ Application Server:

WARNING: 21-Sep-2012 19:25:14: widget bean com.datanomic.director.widget.loqator.server.LoqatorBean reported as dead: Failed to load OAV JNI library lqtjava: /opt/EDQTool/edqav-12.1.2/liblqtjava.so: ld.so.1: java: fatal: liblqtcr.so: open failed: No such file or directory (Code: 247,005)

Cause

Typically, this error occurs because the liblqtcr.so file has a dependency on a file named, libstlport.so, provided as part of Oracle Solaris Sun Studio, which may or may not be installed. To test this, check the dependencies of liblqtcr.so by running the following command:

ldd liblqtcr.so

If the output indicates that the liblqtcr.so file is not found, it is either not installed or cannot be loaded.

Resolution

Add the libstlport.so file to your installation:

Download and unpack the latest version of Oracle Solaris Sun Studio from the Oracle Technology Network web site at

http://www.oracle.com/technetwork/server-storage/solarisstudio/overview/index.html
Add your Oracle Solaris Sun Studio location to your LD_LIBRARY_PATH, as in the following example:

/export/home/sullah/solarisstudio12.3/lib/stlport4/v9
Retest using the ldd liblqtcr.so command.

1.8 Related Documents

For more information about EDQ, see the Oracle Fusion Middleware documentation library.