Configuring OPMN to Manage ODI Standalone Agents

<Do not delete this text because it is a placeholder for the generated list of "main" topics when run in a browser>

Purpose

This tutorial walks you through the steps needed to configure Oracle Process Manager and Navigation server (OPMN) to manage Oracle Data Integrator 11g (ODI) standalone agents. You learn what are the prerequisites, where to download OPMN if not already available, how to add an ODI 11g standalone agent to OPMN, how to start and stop an ODI standalone agent with OPMN, and issues that might arise and how to resolve them.

Time to Complete

Approximately 20 minutes

Overview

The ODI standalone agent is a standalone Java process that runs in a non-JEE environment. This agent can be used to execute ODI scenarios on predefined schedules or on demand.

This standalone agent is typically deployed locally on the source or target machines for optimal integration flow performances. Once the standalone agent has been defined in ODI Topology Manager, it can be started.

The ODI standalone agent can be started from a command line interface, or it can be controlled by a number of other methods. One of the alternative methods for controlling the ODI standalone agent is the use of OPMN. OPMN can help manage process control actions like start, stop, and restart of JEE and non-JEE applications. You can use OPMN to start, stop, and monitor the ODI standalone agent.

ODI 11g does not include a standalone version of OPMN. Fortunately, OPMN is included in the installation of several Oracle middelware products such as Oracle Enterprise Performance Management suite and Oracle Application Server. However, if OPMN is not already available in your environment via middleware, you can download OPMN separately. This OBE tutorial includes a section describing how to download OPMN separately by downloading a subset of Oracle Web Tier Utilities 11g.

Note: The steps to configure OPMN to manage ODI standalone agents are also outlined in the ODI 11g Installation Guide.

In this tutorial, you learn how to:

Scenario

You work as a database administrator for Global Enterprise. You are responsible for managing the execution of ODI scenarios. Until now, you have run scripts to start and stop the ODI standalone agents that execute ODI scenarios. You have learned that you can use OPMN as an alternative method of managing the ODI standalone agents. Although your workplace environment does not have the Oracle middleware products that include OPMN, you are willing to download OPMN and try using it to manage your agents.

This diagram shows three possible methods of managing an ODI standalone agent:

Of those three methods, this OBE tutorial focuses on the steps required for managing an ODI standalone agent using OPMN that is installed from the Oracle Web Tier Utilities 11g.

 

Software and Hardware Requirements

The following is a list of software requirements:

Prerequisites

Before you start the tasks, make sure that your system environment meets the following requirements:

.

You have installed Oracle Database 11g. If not done before, start the services and components for Oracle Database 11g.

.

You have installed Oracle Data Integrator 11g Release 1.

.

You have access to an existing OPMN installation that is part of your Oracle middleware environment, or you will download and install OPMN as part of the Oracle Web Tier Utilities 11g.

Downloading OPMN from the Oracle Web Tier Utilities 11g Installation Set

.

If you need to download OPMN, OPMN is included in any type of Oracle Application Server installation. However, we recommend obtaining OPMN from the Oracle Web Tier Utilities 11g package, as it allows you to choose to install OPMN only. 

Access the website for downloading Oracle Web Tier Utilities 11g from OTN, by clicking here.

.

Download Oracle Web Tier Utilities 11.1.1.2.0 (this is a full install).


.

Unzip and launch the installer. For example, click on the setup located under C:\ofm_webtier_win_11.1.1.2.0_32_disk1_1of1\Disk1\install\win32.


.

Check the check boxes for Oracle HTTP Server and Oracle Webcache only, at the installation wizard's Configure Components window. These two choices will install the OPMN components that you need.

 

.

Download Oracle Web Tier 11.1.1.3.0. (This is a patchset.)

 

.

Launch the installer, and patch Oracle Web Tier 11.1.1.2.0 to 11.1.1.3.0.

If you wish, you may consult the Oracle Web Tier installation guide.


Checking the Version of Java on Your Workstation

 

You may have an existing ODI standalone agent that you wish to add to OPMN. Otherwise, you can create an ODI standalone agent using the ODI Studio Topology Manager.

Before being added to OPMN, the existing or new ODI standalone agent needs to be tested to ensure it starts successfully (from the command prompt) on the machine on which it resides. This involves the following workflow:

  • Check the version of Java on your workstation.
  • Install the ODI 11g standalone Agent on the same host on which Oracle Web Tier is installed.
  • Define that agent in ODI, using ODI Topology Manager.
  • Enter Repository connection and java information in the odiparams.bat or odiparams.sh file.
  • Start the agent from the command prompt to ensure:
    •  The port is free.
    •  The agent host can connect to your ODI repositories.
    •  The Agent process can run with the java version provided.
  • Test the agent in ODI Topology Manager; if successful, stop the agent (we will use OPMN to start it later). If not successful, correct the issue and retry.

 

.

Let us address the first task in the workflow list, above. It is essential that you check the Java version in the DOS command shell of the workstation on which you are working. Checking for Java Development Kit (JDK) 1.6.0 or higher is essential; the script for adding an agent to OPMN, odi_opmn_addagent, requires the latest JDK 1.6 (for example JDK 1.6.0.23). Earlier versions of JDK will not support odi_opm_addagent.

To check the version of JDK on your workstation, open a command window and issue the following command:

java -version

If you need to install a recent version of JDK, click here for the Oracle Java download website. On that website, click the "Download JDK" button to download the Java SE Development Kit 6u23 for Linux or Windows, which will provide you a version of JDK 1.6.

.

Check the version of JDK in the PATH variable:
odi_opmn_addagent uses the Java version that appears first in the PATH variable. Therefore, go to My Computer>Properties>Advanced>Environment Variables>edit your PATH environment variable, add the path to JDK 1.6 to this variable, and remove any older version of JDK from the path.

Note: If you do not put the path to JDK 1.6 in your PATH environment, you will receive the following error:

Exception in thread "main" java.lang.UnsupportedClassVersionError: Bad version
number in .class file
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClass(ClassLoader.java:620)
at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:14)

 

Setting Up the Environment

.

Once you have an ODI standalone agent, either an existing one or newly created one, familiarize yourself with the files you will be using in this tutorial.
Go to the ODI_HOME/oracledi/agent/bin/ directory where the standalone agent has been installed.

The files that we will be focusing on in this tutorial are agentcreate.properties, odi_opmn_addagent.bat, odi_opmn_deleteagent.bat, and odiparams.bat.
( If you are using Unix, the files are appended with .sh instead of .bat.)

.

Make sure to set JAVA_HOME and ODI_JAVA_HOME in odiparams.bat to the JDK 1.6.

Note: The Java path should not have spaces; if it is does, try to use the DOS syntax ~ (for example C:\Progra~1\Java\jdk1.6.0_23 for C:\Program Files\Java\jdk1.6.0_23.)

Otherwise, when starting the Agent with opmnctl, it fails and the error below appears in the log file:

java.lang.NoClassDefFoundError: Files\Java\jdk1/6/0_23\lib\tools/jar
Caused by: java.lang.ClassNotFoundException: Files\Java\jdk1.6.0_23\lib\tools.jar
at java.net.URLClassLoader$1.run(URLClassLoader.java:202)

.

Set the environment variables in both the agentcreate.properties file and the odi_opmn_addagent.bat file. They need to be set so that the odi_opmn_addagent.bat file will be able to find its references to the jar or class files.

  • agentcreate.properties:
    • ORACLE_ODI_HOME expects the path where ODI 11g is installed.

    • COMPONENT_NAME expects the physical Agent name defined in Topology.

  • odi_opmn_addagent.bat:
    • ODI_HOME expects the path of the agent directory under your ODI 11g, for example:
      C:\WEBTIER_HOME\Oracle_WT1\odi_standalone\oracledi\agent
    • All environment variables in odi_opmn_addagent.bat are set this way, by default:
      • if "%INSTANCE_HOME%" == "" set INSTANCE_HOME=..
    • You need to set each variable explicitly, according to your environment; for example:
      • if "%INSTANCE_HOME%" == "" set INSTANCE_HOME=C:\WEBTIER_HOME\Oracle_WT1\instances\instance1
    • If the variables are not set correctly, for example the ODI_HOME variable, then odi_opmn_addAgent will fail with:

      Exception in thread "main" java.lang.NoClassDefFoundError: oracle/odi/AddAgentTo
      Opmn
      Caused by: java.lang.ClassNotFoundException: oracle.odi.AddAgentToOpmn
      at java.net.URLClassLoader$1.run(URLClassLoader.java:202)
      ...
      Could not find the main class: oracle.odi.AddAgentToOpmn. Program will exit.
      opmnctl reload: reconfiguring opmn.

.

After you verify each variable, you may still see the error below when running odi_opmn_addagent.bat:

Error reading file
Please provide the value forORACLE_ODI_HOME
while you have set ORACLE_ODI_HOME correctly in agentcreate file.

This is caused by odi_opmn_addagent.bat not finding the agentcreate.properties file that you provided. The name agentcreate.properties needs to be spelled correctly and with its extension .properties.

If you receive the error above, make sure that you use the correct command syntax to run odi_opmn_addagent.bat:

odi_opmn_addagent "agentcreate.properties"

 


Adding the ODI 11g Standalone Agent to OPMN

.

Launch OPMN and ohs1 from the Start menu.

  • Start>All Programs>Oracle Web Tier Instance-instance 1 >Start Oracle Process Manager
  • Start>All Programs>Oracle Web Tier Instance-instance 1 >Start Oracle HTTP Server-ohs1

Start a command prompt and cd to C:\WEBTIER_HOME\Oracle_WT1\instances\instance1\bin

Issue the following command to check if OPMN is running and ohs1 is alive:

opmnctl status



.

If you do not already have an existing ODI standalone agent to add to OPMN, your next step is to use the ODI Studio Topology Manager to create a standalone agent definition. To start Oracle Data Integrator: Start > Programs > Oracle ODI 11g-Home> Oracle Data Integrator > ODI Studio.

 

Note the Host field contains the Host name where the standalone Agent will be running. In this example, Name is local_agent, and port number is 20910.

For more details on adding an ODI standalone agent, see the OBE tutorial ODI11g: Setting up and installing an ODI agent..

.

Check the agentcreate.properties file to make sure each environment variable is set correctly. (You may save a copy of the original outside of the ODI Home.)

Example agentcreate.properties file content:

# Use / as path seperator to specify path in Unix as well as Windows.
ORACLE_ODI_HOME=/WEBTIER_HOME/Oracle_WT1/odi_standalone
INSTANCE_HOME=/WEBTIER_HOME/Oracle_WT1/instances/instance1
COMPONENT_TYPE=odiagent
COMPONENT_NAME=local_agent
ODI_MASTER_DRIVER=oracle.jdbc.OracleDriver
ODI_MASTER_URL=jdbc:oracle:thin:@localhost:1521:orcl
ODI_MASTER_USER=ODIM
ODI_MASTER_ENCODED_PASS=d1yaGzWPRiJEdE5KLDgdH5dp
ODI_SECU_WORK_REPO=WORKREP1
ODI_SUPERVISOR_ENCODED_PASS=fDyXsq.YMRuAn7hyx1Ds
PORTNO=20910
JAVA_HOME=/Progra~1/Java/jdk1.6.0_23
ORACLE_OPMN_HOME=/WEBTIER_HOME/Oracle_WT1
JMXPORTNO=21910

Note: COMPONENT_NAME and PORTNO values are identical to what you defined in Topology Manager in the previous step for Name and Port Number.
JMXPORTNO is, by default, the PORTNO + 1000, so in our example it is 21910.

 

.

Check the Environment Variables in odi_opmn_addagent.bat.

Example odi_opmn_addagent.bat content:

rem if "%ODI_HOME%" == "" set ODI_HOME=..
rem if "%OPMN_HOME%" == "" set OPMN_HOME=..
rem if "%INSTANCE_HOME%" == "" set INSTANCE_HOME=..

if "%ODI_HOME%" == "" set ODI_HOME=C:\WEBTIER_HOME\Oracle_WT1\odi_standalone\oracledi\agent
if "%OPMN_HOME%" == "" set OPMN_HOME=C:\WEBTIER_HOME\Oracle_WT1
if "%INSTANCE_HOME%" == "" set INSTANCE_HOME=C:\WEBTIER_HOME\Oracle_WT1\instances\instance1

set CLASSPATH=%ODI_HOME%\lib\odi-standalone-agent.jar;%OPMN_HOME%\opmn\lib\opmneditor.jar
java -classpath %CLASSPATH% oracle.odi.AddAgentToOpmn %*
CALL %INSTANCE_HOME%\bin\opmnctl reload
:ENDCOMMAND


.

Add the Agent to OPMN by issuing the following command under oracledi\agent\bin:

odi_opmn_addagent "agentcreate.properties"

 

.

Change directories to C:\WEBTIER_HOME\Oracle_WT1\instances\instance1\bin or equivalent where your Web Tier is installed.

Issue the following command to verify that the agent has been added:

opmnctl status

 

.

Now start the Agent using opmnctl and check its status again:

opmnctl.bat startproc ias-component=local_agent

 

.

Test the Agent in ODI Topology Manager now.

Note:

If the agent fails to start in the previous step, you may consult its log file located at
C:\WEBTIER_HOME\Oracle_WT1\instances\instance1\diagnostics\logs\OPMN\opmn\co nsole~local_agent~odiagent~1.log.

Fix the issue reported by the Agent log (it could be one of the error messages included in this OBE tutorial) then retry starting the agent.

 


How to Stop the Agent

.

Issue the following command:

opmnctl.bat stopproc ias-component=local_agent

 


Troubleshooting the Inability to Start the Agent Due to Backslashes

.

You may be unable to start the agent using OPMN when the JDBC URL to ODI repositories contains "//"

For example, with ODI rRepositories hosted on Microsoft SQL Server, starting the agent using OPMN fails.

Upon inspection, the OPMN diagnostic log located at
<WebTIER_HOME>\Oracle_WT1\instances\instance1\diagnostics\logs\OPMN\opmn\console~local_agent~odiagent~1.log

shows the following error:

Caused by: java.sql.SQLNonTransientConnectionException: [OWLS][SQLServer JDBC Driver]A value was not specified for a required property: serverName for datadirect driver

Caused by: java.sql.SQLException: No suitable driver for MS SQL server driver.


Further investigation in the OPMN diagnostic log reveals that OPMN is converting the slashes "//" in the JDBC URL to "\\" which is causing the connection to the master repository to fail.

By default, OPMN converts slashes in the data value string to be those of the directory path separator character for the system on which OPMN is running (on UNIX each '\' character is converted to '/' and on Windows each '/' is converted to '\'). Set this attribute to false to disable conversion.

To resolve this issue, edit the opmn.xml file to add process-conversion="false" as shown below.

<variable id="ODI_MASTER_URL" value="jdbc:sqlserver://rplewis-lap.idc.oracle.com:2213;databaseName=ODI11G_MASTER;selectMethod=cursor" process-conversion="false"/>

Please note there is a space before "process-conversion".

Restart OPMN and then try to start the ODI standalone agent using OPMN.

Additional References for OPMN config file is available here.

 

Summary

In this tutorial, you have learned how to:

Resources

 

Hardware and Software Engineered to Work Together About Oracle |Oracle and Sun | Oracle RSS Feeds | Careers | Contact Us | Site Maps | Legal Notices | Terms of Use | Your Privacy Rights