Having recently helped a team fix an Oracle Data Integrator (ODI) Agent installation problem, and from the number of questions I see related to the ODI Agent, I thought a post that put most of the information related to the ODI Agent in a single place would be a valuable and productive topic to cover.
What is an ODI Agent, and why do you need one?
- One question to ask yourself is “Do I need one?”. The answer is “not necessarily”. If you are doing development on your own, you can run Local (No Agent) versus installing an Agent. In this case, the Oracle Data Integrator GUI is acting as the Agent. When first using the product, this choice is fine. However, when you start working with others on a project (and quite probably have to setup an Oracle Data Integrator shared team environment “in a hurry”), having knowledge about the Agent, and how to install and configure it will pay dividends. And when going into Test or Production, you will need one. The goal of this article is to help you understand the installation and configuration of the Agent so that you can avoid having the Agent become an obstacle to productivity and success for your development, test, and deployment teams.
- So – What is an ODI Agent? The Agent, which runs in a separate lightweight Java Virtual Machine (JVM), is the ODI component that orchestrates your ODI processes. Agents come in two flavors – Listener Agent, and Scheduler Agent. For the purpose of this article, we will be discussing Listener Agent unless otherwise noted. In addition to orchestrating processes, the Agent has the following additional responsibilities:
- Takes the information stored in Knowledge Modules and generates the appropriate SQL for the technology that will Extract, Load, or Transform data
- Connection Management with Sources and Targets
- Transmission of the generated code for Execution on the Source or Target
- Receive the response
- Populate the Repository with return code and processing statistics, updating the logs (note: these logs are in the Database, not Log4J logs) which can be viewed by the Operator module
How do I install an Agent?
The default Agent port is 20910. Make sure that port (or the non default port you choose) is not in use before getting started (you can do this by running “netstat -a” from a command line interface).
How do I run (start) an Agent?
Run agent.bat (or agent.sh) from a command line interface. Parameters are:
- -port=<port> The default port is 20910
- -help Prints help for the command
- -name=<agentname> You may wish to encode your lifecycle development phase and project name in the Agent name ( -name=DevelopmentMasterCustomerData )
- -v= Tracing output – specify a number from 1 to 5. You may wish to redirect output to a file ( agent.bat “-v=5″ > trace.txt ). Number 4 will trace the SQL queries executed
How do I stop an Agent?
Run agentstop.bat or agentstop.sh. If no port is specified, the default port (20910) is assumed.
Example: agentstop.bat “-PORT=20200″ on Windows.
When using the Windows operating system, how do I start an Agent as a Service?
When the Agent platform is Windows, it can be useful to automatically launch the Oracle Data Integrator Agent when rebooting Windows. To do that, you need to:
- Edit the /bin/odiparams.bat file. When the Agent is launched as a Windows Service, the service uses the agent startup parameters specified in odiparams.bat. To avoid complexity, you should setup/define your Master and Work Repository before modifying Windows to run the Agent as a Windows Service. In particular, eyeball the section of the file “Repository Connection Information” to make sure the information is correct.
- From a Command Prompt, go to the /bin sub-directory of the Oracle Data Integration installation folder
- Run agentservice.bat with the appropriate parameters to install the service
- Once the service is installed, you must go to Windows Service Manager to start / autostart the Service ( you can run this directly by typing services.msc in a command prompt or Run command )
Parameters for AgentService.bat are:
agentservice.bat -i|-r -a|-s [<agent_name> [<agent_port>
[<wrapper_configuration_file>]]]
You must specify two parameters: -i or -r, and -a or -s. The others are optional.
- -i installs the service, -r uninstalls the service
- -a installs the listener agent (uses the snpsagent.conf parameter file)
- -s installs the scheduler agent (uses the snpsagentscheduler.conf parameter file)
- agent_name is the agent name previously defined in Topology Manager (required if specifying -s above)
- agent_port is the listening port for the agent
- wrapper_configuration_file – outside the scope of this article
How many Agents do I need, and where do I install them?
- This answer is dependent on your understanding of Work Repositories. While the subject of Repositories is itself a separate article ( I hope to be publishing a comprehensive “Best Practices” article on ODI Topology Manager in the September issue of Select Journal ( published/sponsored by IOUG ) as part of their TIPS and Best Practices collection ), the recommendation is to have a Work Repository for each development lifecyle environment you have ( for example: Development, Test, QA, Pre-Production, Production ). The recommendation is to have one Agent for each Work Repository you have. In that example, you would have five Agents (and five Work Repositories that “talk to” a single Master Repository), one for each lifecycle environment. In summary, you have a Physical Agent for each development lifecycle environment, and for each Physical Agent, create a corresponding Logical Agent (make it obvious by incorporating the lifecycle process name in the Agent name ( for example, ProductionCustomerMasterDataAgent )
- The criteria used to decide on which servers (where) the ODI Agents should be installed, depend on the technical architecture, the precise requirements for Data Integration processes, and the environments used for the lifecycle development of your project.A general rule of thumb is to install ODI Agents on or close to the servers hosting your Target data servers. Reliable connectivity and low network latency from Agent to Target data servers are factors to consider. You do not want your ODI Agent installed in San Francisco when all of your frequently accessed Target data servers are in your New York Data Center. The speed of light is fast, but not that fast.
- The number of Agents is also influenced by whether you plan to do Load Balancing for Agents. That topic is outside the scope of this article, but when adding Load Balancing for Agents, there will be additional agents ( additional for each lifecycle environment where load testing will be validated for your project).
- When first starting to work in a project team development environment, have the developers use a single shared Agent installed on a commonly accessible server rather than each developer using an Agent that they have on their own laptop/workstation. This will resolve countless “well, it works when I run it on my machine” situations from arising.
I hope this information makes you more productive when working with Oracle Data Integrator Agents. Now you know what you need to know, and where to find it!