4 Setting-up the Topology

This chapter describes how to set up the topology in Oracle Data Integrator. An overview of Oracle Data Integrator topology concepts and components is provided.

This chapter contains these sections:

4.1 Introduction to the Oracle Data Integrator Topology

The Oracle Data Integrator Topology is the physical and logical representation of the Oracle Data Integrator architecture and components.

This section contains these topics:

4.1.1 Physical Architecture

The physical architecture defines the different elements of the information system, as well as their characteristics taken into account by Oracle Data Integrator. Each type of database (Oracle, DB2, etc.), file format (XML, Flat File), or application software is represented in Oracle Data Integrator by a technology.

A technology handles formatted data. Therefore, each technology is associated with one or more data types that allow Oracle Data Integrator to generate data handling scripts.

The physical components that store and expose structured data are defined as data servers. A data server is always linked to a single technology. A data server stores information according to a specific technical logic which is declared into physical schemas attached to this data server. Every database server, JMS message file, group of flat files, and so forth, that is used in Oracle Data Integrator, must be declared as a data server. Every schema, database, JMS Topic, etc., used in Oracle Data Integrator, must be declared as a physical schema.

Finally, the physical architecture includes the definition of the Physical Agents. These are the Java software components that run Oracle Data Integrator jobs.

4.1.2 Contexts

Contexts bring together components of the physical architecture (the real Architecture) of the information system with components of the Oracle Data Integrator logical architecture (the Architecture on which the user works).

For example, contexts may correspond to different execution environments (Development, Test and Production) or different execution locations (Boston Site, New-York Site, and so forth.) where similar physical resource exist.

Note that during installation the default GLOBAL context is created.

4.1.3 Logical Architecture

The logical architecture allows a user to identify as a single Logical Schema a group of similar physical schemas - that is containing datastores that are structurally identical - but located in different physical locations. Logical Schemas, like their physical counterpart, are attached to a technology.

Context allow to resolve logical schemas into physical schemas. In a given context, one logical schema resolves in a single physical schema.

For example, the Oracle logical schema Accounting may correspond to two Oracle physical schemas:

  • Accounting Sample used in the Development context

  • Accounting Corporate used in the Production context

These two physical schemas are structurally identical (they contain accounting data), but are located in different physical locations. These locations are two different Oracle schemas (Physical Schemas), possibly located on two different Oracle instances (Data Servers).

All the components developed in Oracle Data Integrator are designed on top of the logical architecture. For example, a data model is always attached to logical schema, and data flows are defined with this model. By specifying a context at run-time, the model's logical schema resolves to a single physical schema, and the data contained in this schema in the data server can be accessed by the integration processes.

4.1.4 Agents

Oracle Data Integrator run-time Agents orchestrate the execution of jobs. These agents are Java components.

The run-time agent functions as a listener and a scheduler agent. The agent executes jobs on demand (model reverses, packages, scenarios, interfaces, and so forth), for example when the job is manually launched from a user interface or from a command line. The agent is also to start the execution of scenarios according to a schedule defined in Oracle Data Integrator.

Third party scheduling systems can also trigger executions on the agent. See Section 20.9.2, "Scheduling a Scenario or a Load Plan with an External Scheduler" for more information.

Typical projects will require a single Agent in production; however, Section 4.3.3, "Load Balancing Agents"describes how to set up several load-balanced agents.

Agent Lifecycle

The lifecycle of an agent is as follows:

  1. When the agent starts it connects to the master repository.

  2. Through the master repository it connects to any work repository attached to the Master repository and performs the following tasks at startup:

    • Clean stale sessions in each work repository. These are the sessions left incorrectly in a running state after an agent or repository crash.

    • Retrieve its list of scheduled scenarios in each work repository, and compute its schedule.

  3. The agent starts listening on its port.

    • When an execution request arrives on the agent, the agent acknowledges this request and starts the session.

    • The agent launches the sessions start according to the schedule.

    • The agent is also able to process other administrative requests in order to update its schedule, stop a session, respond to a ping or clean stale sessions. The standalone agent can also process a stop signal to terminate its lifecycle.

Refer to Chapter 20, "Running Integration Processes" for more information about a session lifecycle.

Agent Features

Agents are not data transformation servers. They do not perform any data transformation, but instead only orchestrate integration processes. They delegate data transformation to database servers, operating systems or scripting engines.

Agents are multi-threaded lightweight components. An agent can run multiple sessions in parallel. When declaring a physical agent, it is recommended that you adjust the maximum number of concurrent sessions it is allowed to execute simultaneously from a work repository. When this maximum number is reached, any new incoming session will be queued by the agent and executed later when other sessions have terminated. If you plan to run multiple parallel sessions, you can consider load balancing executions as described in Section 4.3.3, "Load Balancing Agents".

Standalone and Java EE Agents

The Oracle Data Integrator agents exists in two flavors: standalone agent and Java EE agent.

A standalone agent runs in a separate Java Virtual Machine (JVM) process. It connects to the work repository and to the source and target data servers via JDBC. Standalone agents can be installed on any server with a Java Machine installed. This type of agent is more appropriate when you need to use a resource that is local to one of your data servers (for example, the file system or a loader utility installed with the database instance), and you do not want to install a Java EE application server on this machine.

A Java EE agent is deployed as a web application in a Java EE application server (for example Oracle WebLogic Server). The Java EE agent can benefit from all the features of the application server (for example, JDBC data sources or clustering for Oracle WebLogic Server). This type of agent is more appropriate when there is a need for centralizing the deployment and management of all applications in an enterprise application server, or when you have requirements for high availability.

It is possible to mix in a single environment standalone and Java EE agents in a distributed environment.

Physical and Logical Agents

A physical agent corresponds to a single standalone agent or a Java EE agent. A physical agent should have a unique name in the Topology.

Similarly to schemas, physical agents having an identical role in different environments can be grouped under the same logical agent. A logical agent is related to physical agents through contexts. When starting an execution, you indicate the logical agent and the context. Oracle Data Integrator will translate this information into a single physical agent that will receive the execution request.

Agent URL

An agent runs on a host and a port and is identified on this port by an application name. The agent URL also indicates the protocol to use for the agent connection. Possible values for the protocol are http or https. These four components make the agent URL. The agent is reached via this URL.

For example:

  • A standalone agent started on port 8080 on the odi_production machine will be reachable at the following URL:

    http://odi_production:8080/oraclediagent.

    Note:

    The application name for a standalone agent is always oraclediagent and cannot be changed.
  • A Java EE agent started as an application called oracledi on port 8000 in a WLS server deployed on the odi_wls host will be reachable at the following URL:

    http://odi_wls:8000/oracledi.

4.1.5 Languages

Languages defines the languages and language elements available when editing expressions at design-time. Languages provided by default in Oracle Data Integrator do not require any user change.

4.1.6 Repositories

The topology contains information about the Oracle Data Integrator repositories. Repository definition, configuration and installation is covered in the Installation and Upgrade Guide for Oracle Data Integrator.

4.2 Setting Up the Topology

The following steps are a guideline to create the topology. You can always modify the topology after an initial setting:

  1. Create the contexts corresponding to your different environments.

  2. Create the data servers corresponding to the servers used by Oracle Data Integrator.

  3. For each data server, create the physical schemas corresponding to the schemas containing data to be integrated with Oracle Data Integrator.

  4. Create logical schemas and associate them with physical schemas in the contexts.

  5. Create the physical agents corresponding to the standalone or Java EE agents that are installed in your information systems.

  6. Create logical agents and associate them with physical agents in the contexts.

4.2.1 Creating a Context

To create a context:

  1. In Topology Navigator expand the Contexts accordion.

  2. Click New context in the accordion header.

  3. Fill in the following fields:

    • Name: Name of the context, as it appears in the Oracle Data Integrator graphical interface.

    • Code: Code of the context, allowing a context to be referenced and identified among the different repositories.

    • Password: Password requested when the user requests switches to this context in a graphical interface. It is recommended to use a password for critical contexts (for example, contexts pointing to Production data)

    • Check Default if you want this context to be displayed by default in the different lists in Designer Navigator or Operator Navigator.

  4. From the File menu, click Save.

4.2.2 Creating a Data Server

A Data Server corresponds for example to a Database, JMS server instance, a scripting engine or a file system accessed with Oracle Data Integrator in the integration flows. Under a data server, subdivisions are created in the form of Physical Schemas.

Note:

Frequently used technologies have their data server creation methods detailed in the Oracle Fusion Middleware Connectivity and Knowledge Modules Guide for Oracle Data Integrator.

4.2.2.1 Pre-requisites and Guidelines

It is recommended to follow the guidelines below when creating a data server.

Review the Technology Specific Requirements

Some technologies require the installation and the configuration of elements such as:

Refer to the documentation of the technology you are connecting to through the data server and to the Oracle Fusion Middleware Connectivity and Knowledge Modules Guide for Oracle Data Integrator. The connection information may also change depending on the technology. Refer to the server documentation provided, and contact the server administrator to define the connection methods.

Create an Oracle Data Integrator User

For each database engine used by Oracle Data Integrator, it is recommended to create a user dedicated for ODI on this data server (typically named ODI_TEMP).

Grant this user privileges to

  • Create/drop objects and perform data manipulation in his own schema.

  • Manipulate data into objects of the other schemas of this data server according to the operations required for the integration processes.

This user should be used as follows:

  • Use this user name/password in the data server user/password definition.

  • Use this user's schema as your Work Schema for all data schemas on this server.

4.2.2.2 Creating a Data Server

To create a Data Server:

  1. In Topology Navigator expand the Technologies node in the Physical Architecture accordion.

  2. Select the technology you want to create a data server for.

  3. Right-click and select New Data Server

  4. Fill in the following fields in the Definition tab:

    • Name: Name of the Data Server that will appear in Oracle Data Integrator.

      For naming data servers, it is recommended to use the following naming standard: <TECHNOLOGY_NAME>_<SERVER_NAME>.

    • ... (Data Server): This is the physical name of the data server used by other data servers to identify it. Enter this name if your data servers can be inter-connected in a native way. This parameter is not mandatory for all technologies.

      For example, for Oracle, this name corresponds to the name of the instance, used for accessing this data server from another Oracle data server through DBLinks.

    • User/Password: User name and password for connecting to the data server. This parameter is not mandatory for all technologies, as for example for the File technology.

      Depending on the technology, this could be a "Login", a "User", or an "account". For some connections using the JNDI protocol, the user name and its associated password can be optional (if they have been given in the LDAP directory).

  5. Define the connection parameters for the data server:

    A technology can be accessed directly through JDBC or the JDBC connection to this data server can be served from a JNDI directory.

    If the technology is accessed through a JNDI directory:

    1. Check the JNDI Connection on the Definition tab.

    2. Go to the JNDI tab, and fill in the following fields:

    Field Description
    JNDI authentication
    • None: Anonymous access to the naming or directory service
    • Simple: Authenticated access, non-encrypted

    • CRAM-MD5: Authenticated access, encrypted MD5

    • <other value>: authenticated access, encrypted according to <other value>

    JNDI User/Password User/password connecting to the JNDI directory
    JNDI Protocol Protocol used for the connection

    Note that only the most common protocols are listed here. This is not an exhaustive list.

    • LDAP: Access to an LDAP directory

    • SMQP: Access to a SwiftMQ MOM directory

    • <other value>: access following the sub-protocol <other value>

    JNDI Driver The driver allowing the JNDI connection

    Example Sun LDAP directory: com.sun.jndi.ldap.LdapCtxFactory

    JNDI URL The URL allowing the JNDI connection

    For example: ldap://suse70:389/o=linuxfocus.org

    JNDI Resource The directory element containing the connection parameters

    For example: cn=sampledb


    If the technology is connected through JDBC:

    1. Un-check the JNDI Connection box.

    2. Go to the JDBC tab, and fill in the following fields:

      Field Description
      JDBC Driver Name of the JDBC driver used for connecting to the data server
      JDBC URL URL allowing you to connect to the data server.

    You can get a list of pre-defined JDBC drivers and URLs by clicking Display available drivers or Display URL sample.

  6. From the File menu, click Save to validate the creation of the data server.

4.2.2.3 Creating a Data Server (Advanced Settings)

The following actions are optional:

Adding Connection Properties

These properties are passed when creating the connection, in order to provide optional configuration parameters. Each property is a (key, value) pair.

  • For JDBC: These properties depend on the driver used. Please see the driver documentation for a list of available properties. It is possible in JDBC to specify here the user and password for the connection, instead of specifying there in the Definition tab.

  • For JNDI: These properties depend on the resource used.

To add a connection property to a data server:

  1. On the Properties tab click Add a Property.

  2. Specify a Key identifying this property. This key is case-sensitive.

  3. Specify a value for the property.

  4. From the File menu, click Save.

Defining Data Sources

On the Data Sources tab you can define JDBC data sources that will be used by Oracle Data Integrator Java EE Agents deployed on application servers to connect to this data server. Note that data sources are not applicable for standalone agents.

Defining data sources is not mandatory, but allows the Java EE agent to benefit from the data sources and connection pooling features available on the application server. Connection pooling allows reusing connections across several sessions. If a data source is not declared for a given data server in a Java EE agent, this Java EE agent always connects the data server using direct JDBC connection, that is without using any of the application server data sources.

Before defining the data sources in Oracle Data Integrator, please note the following:

  • Datasources for WebLogic Server should be created with the Statement Cache Size parameter set to 0 in the Connection Pool configuration. Statement caching has a minor impact on data integration performances, and may lead to unexpected results such as data truncation with some JDBC drivers. Note that this concerns only data connections to the source and target data servers, not the repository connections.

  • If using Connection Pooling with datasources, it is recommended to avoid ALTER SESSION statements in procedures and Knowledge Modules. If a connection requires ALTER SESSION statements, it is recommended to disable connection pooling in the related datasources.

To define JDBC data sources for a data server:

  1. On the DataSources tab of the Data Server editor click Add a DataSource

  2. Select a physical Agent in the Agent field.

  3. Enter the data source name in the JNDI Name field.

    Note that this name must match the name of the data source in your application server.

  4. Check JNDI Standard if you want to use the environment naming context (ENC).

    When JNDI Standard is checked, Oracle Data Integrator automatically prefixes the data source name with the string java:comp/env/ to identify it in the application server's JNDI directory.

    Note that the JNDI Standard is not supported by Oracle WebLogic Server and for global data sources.

  5. From the File menu, click Save.

After having defined a data source for a Java EE agent, you must create it in the application server into which the Java EE agent is deployed. There are several ways to create data sources in the application server, including:

Setting Up On Connect/Disconnect Commands

On the On Connect/Dicsonnect tab you can define SQL commands that will be executed when a connection to a data server defined in the physical architecture is created or closed.

The On Connect command is executed every time an ODI component, including ODI client components, connects to this data server.

The On Disconnect command is executed every time an ODI component, including ODI client components, disconnects from this data server.

These SQL commands are stored in the master repository along with the data server definition.

Before setting up commands On Connect/Disconnect, please note the following:

  • The On Connect/Disconnect commands are only supported by data servers with a technology type Database (JDBC).

  • The On Connect and Disconnet commands are executed even when using data sources. In this case, the commands are executedwhen taking and releasing the connection from the connection pool.

  • Substitution APIs are supported. Note that the design time tags <% are not supported. Only the execution time tags <? and <@ are supported.

  • Only global variables in substitution mode (#GLOBAL.<VAR_NAME> or #<VAR_NAME> ) are supported. See "Variable Scope" for more information. Note that the Expression editor only displays variables that are valid for the current data server.

  • The variables that are used in On Connect and Disconnet commands are only replaced at runtime, when the session starts. A command using variables will fail when testing the data server connection or performing a View Data operation on this data server. Make sure that these variables are declared in the scenarios.

  • Oracle Data Integrator Sequences are not supported in the On Connect and Disconnet commands.

The commands On Connect/Disconnect have the following usage:

  • When a session runs, it opens connections to data servers. every time a connection is opened on a data server that has a command On Connect defined, a task is created under a specific step called Command on Connect. This task is named after the data server to which the connection is established, the step and task that create the connection to this data server. It contains the code of the On Connect command.

  • When the session completes, it closes all connections to the data servers. Every time a connection is closed on a data server that has a command On Disonnect defined, a task is created under a specific step called Command on Disconnect. This task is named after the data server that is disconnected, the step and task that dropped the connection to this data server. It contains the code of the On Disconnect command.

  • When an operation is made in ODI Studio or ODI Console that requires a connection to the data server (such as View Data or Test Connection), the commands On Connect/Disconnect are also executed if the Client Transaction is selected for this command.

Note:

You can specify whether or not to show On Connect and Disconnect steps in Operator Navigator. If the user parameter Hide On Connect and Disconnect Steps is set to Yes, On Connect and Disconnect steps are not shown.

To set up On Connect/Disconnect commands:

  1. On the On Connect/Disconnect tab of the Data Server editor, click Launch the Expression Editor in the On Connect section or in the On Disconnect section.

  2. In the Expression Editor, enter the SQL command.

    Note:

    The Expression Editor displays only the subsitution methods and keywords that are available for the technology of the data server. Note that global variables are only displayed if the connection to the work repository is available.
  3. Click OK. The SQL command is displayed in the Command field.

  4. Optionally, select Commit, if you want to commit the connection after executing the command. Note that if AutoCommit or Client Transaction is selected in the Execute On list, this value will be ignored.

  5. Optionally, select Ignore Errors, if you want to ignore the exceptions encountered during the command execution. Note that if Ignore Errors is not selected, the calling operation will end in error status. A command with Ignore Error selected that fails during a session will appear as a task in a Warning state.

  6. From the Log Level list, select the logging level (from 1 to 5) of the connect or disconnect command. At execution time, commands can be kept in the session log based on their log level. Default is 3.

  7. From the Execute On list, select the transaction(s) on which you want to execute the command.

    Note:

    Transactions from 0 to 9 and the Autocommit transaction correspond to connection created by sessions (by procedures or knowledge modules). The Client Transaction correspondsto the client components (ODI Console and Studio).

    You can select Select All or Unselect All to select or unselect all transactions.

  8. From the File menu, click Save.

You can now test the connection, see Section 4.2.2.4, "Testing a Data Server Connection" for more information.

4.2.2.4 Testing a Data Server Connection

It is recommended to test the data server connection before proceeding in the topology definition.

To test a connection to a data server:

  1. In Topology Navigator expand the Technologies node in the Physical Architecture accordion and then expand the technology containing your data server.

  2. Double-click the data server you want to test. The Data Server Editor opens.

  3. Click Test Connection.

    The Test Connection dialog is displayed.

  4. Select the agent that will carry out the test. Local (No Agent) indicates that the local station will attempt to connect.

  5. Click Detail to obtain the characteristics and capacities of the database and JDBC driver.

  6. Click Test to launch the test.

A window showing "connection successful!" is displayed if the test has worked; if not, an error window appears. Use the detail button in this error window to obtain more information about the cause of the connection failure.

4.2.3 Creating a Physical Schema

An Oracle Data Integrator Physical Schema corresponds to a pair of Schemas:

  • A (Data) Schema, into which Oracle Data Integrator will look for the source and target data structures for the interfaces.

  • A Work Schema, into which Oracle Data Integrator can create and manipulate temporary work data structures associated to the sources and targets contained in the Data Schema.

Frequently used technologies have their physical schema creation methods detailed in the Oracle Fusion Middleware Connectivity and Knowledge Modules Guide for Oracle Data Integrator.

Before creating a Physical Schema, note the following:

  • Not all technologies support multiple schemas. In some technologies, you do not specify the work and data schemas since one data server has only one schema.

  • Some technologies do not support the creation of temporary structures. The work schema is useless for these technologies.

  • The user specified in the data server to which the Physical Schema is attached must have appropriate privileges on the schemas attached to this data server.

To create a Physical Schema:

  1. Select the data server, Right-click and select New Physical Schema. The Physical Schema Editor appears.

  2. If the technology supports multiple schemas:

    1. Select or type the Data Schema for this Data Integrator physical schema in ... (Schema). A list of the schemas appears if the technologies supports schema listing.

    2. Select or type the Work Schema for this Data Integrator physical schema in ... (Work Schema). A list of the schemas appears if the technologies supports schema listing.

  3. Check the Default box if you want this schema to be the default one for this data server (The first physical schema is always the default one).

  4. Go to the Context tab.

  5. Click Add.

  6. Select a Context and an existing Logical Schema for this new Physical Schema.

    If no Logical Schema for this technology exists yet, you can create it from this Editor.

    To create a Logical Schema:

    1. Select an existing Context in the left column.

    2. Type the name of a Logical Schema in the right column.

      This Logical Schema is automatically created and associated to this physical schema in this context when saving this Editor.

  7. From the File menu, click Save.

4.2.4 Creating a Logical Schema

To create a logical schema:

  1. In Topology Navigator expand the Technologies node in the Logical Architecture accordion.

  2. Select the technology you want to attach your logical schema to.

  3. Right-click and select New Logical Schema.

  4. Fill in the schema name.

  5. For each Context in the left column, select an existing Physical Schema in the right column. This Physical Schema is automatically associated to the logical schema in this context. Repeat this operation for all necessary contexts.

  6. From the File menu, click Save.

4.2.5 Creating a Physical Agent

To create a Physical Agent:

  1. In Topology Navigator right-click the Agents node in the Physical Architecture accordion.

  2. Select New Agent.

  3. Fill in the following fields:

    • Name: Name of the agent used in the Java graphical interface.

    • Host: Network name or IP address of the machine the agent will been launched on.

    • Port: Listening port used by the agent. By default, this port is the 20910.

    • Web Application Context: Name of the web application corresponding to the Java EE agent deployed on an application server. For standalone agents, this field should be set to oraclediagent.

    • Protocol: Protocol to use for the agent connection. Possible values are http or https. Default is http.

    • Maximum number of sessions supported by this agent.

  4. If you want to setup load balancing, go to the Load balancing tab and select a set of linked physical agent to which the current agent can delegate executions. See Section 4.3.3.3, "Setting Up Load Balancing" for more information.

  5. If the agent is launched, click Test. The successful connection dialog is displayed.

  6. Click Yes.

4.2.6 Creating a Logical Agent

To create a logical agent:

  1. In Topology Navigator right-click the Agents node in the Logical Architecture accordion.

  2. Select New Logical Agent.

  3. Fill in the Agent Name.

  4. For each Context in the left column, select an existing Physical Agent in the right column. This Physical Agent is automatically associated to the logical agent in this context. Repeat this operation for all necessary contexts.

  5. From the File menu, click Save.

4.3 Managing Agents

This section describes how to work with a standalone agent, a Java EE agent and how to handle load balancing.

4.3.1 Standalone Agent

Managing the standalone agent involves the actions discussed in these sections:

Note:

The agent command line scripts, which are required for performing the tasks described in this section, are only available if you have installed the Oracle Data Integrator Standalone Agent. See the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for information about how to install the Standalone Agent.

4.3.1.1 Configuring the Standalone Agent

The odiparams file is a configuration script that contains the parameters for the Oracle Data Integrator standalone agent command line scripts. It contains the repository connection and credential information for starting the standalone agent. It is necessary to have this configuration done before starting a standalone agent.

This file is in the /agent/bin directory of the Oracle Data Integrator installation directory.

  • On UNIX system:

    odiparams.sh

  • On Windows system:

    odiparams.bat

This file can be edited with a text editor to set the configuration parameters.

Note:

The odiparams file is preconfigured if you have installed your standalone agent using Oracle Universal Installer and have selected to configure a repository connection during installation.

See Table 4-1 for the list of these parameters.

Table 4-1 Repository Connection Information

Parameter Description

ODI_MASTER_DRIVER

JDBC driver used to connect the master repository.

ODI_MASTER_URL

JDBC URL used to connect the master repository. This URL must be quoted if it contains one of the following characters:

  • semicolon (;)

  • backslash (\)

  • double quote (")

  • back quote (`)

  • dollar sign ($)

  • less than (<)

  • greater then (>)

ODI_MASTER_USER

Database account used to connect the master repository

ODI_MASTER_ENCODED_PASS

Database account password. The password must be encoded with the encode.[sh|bat] <password> command.

ODI_SECU_WORK_REP

Name of the work repository to connect to. This work repository is the default repository into which the scenarios are started. See Chapter 20, "Running Integration Processes" for more information.

ODI_SUPERVISOR

Name of an ODI SUPERVISOR user. This SUPERVISOR user is used by the agent to connect the master repository.

ODI_SUPERVISOR_ENCODED_PASS

This SUPERVISOR user's password. The password must be encoded with the encode.[sh|bat] <password> command.

ODI_USER

Name of an ODI user used to start scenarios. This user's credentials are used when starting a scenario from a command line. See Chapter 20, "Running Integration Processes" for more information.

ODI_ENCODED_PASS

This ODI user password

ODI_CONNECTION_RETRY_COUNT

The number of retries to re-establish the connection in the event of a repository connection failures. Default is 0. No retry is performed when the default value is not modified by the user.

Note that the RETRY parameters (ODI_CONNECTION_RETRY_COUNT and ODI_CONNECTION_RETRY_DELAY) allow the agent to continue sessions if the repository falls down and is made available shortly after. These parameters enable high availability (HA) recovery for a repository residing on an Oracle RAC database.

ODI_CONNECTION_RETRY_DELAY

Time in milliseconds between repository connection retries. Default is 7000.


4.3.1.2 Launching a Standalone Agent

The standalone agent is able to execute scenarios on predefined schedules or on demand.

To launch a standalone agent:

  1. Change directory to the /agent/bin directory of the Oracle Data Integrator Agent.

  2. Enter the following command to start the agent.

    • On UNIX system:

      ./agent.sh

    • On Windows system:

      agent.bat

The agent is then launched as listener. The agent can take the optional parameters listed in Table 4-2.

Agent Configuration Parameters

Table 4-2 lists the different parameters that allow the agent to be configured. The parameters are prefixed by the "-" character and the possible values are preceded by the "=" character. When entering the command, consider the operating system specific syntax of the delimiters.

Table 4-2 Agent Configuration Parameters

Parameters Description

-PORT=<port>

Port on which the agent is listening. Default value is 20910. This port should exactly match the port specified in the physical agent definition in the topology.

-NAME=<agent name>

This is the name of the physical agent used. This name should match the name of the physical agent as defined in the topology. If this parameter is not specified, the agent starts with the default name OracleDIAgent.

-JMXPORT=<jmx_port>

JMX agent port number. The agent listens on this port for JMX request to provide its metrics. Default value is the listening port + 1000. For example, if <port>=20910 then <jmx_port>=21910.


For example, on UNIX, the following command

./agent.sh -PORT=20300 -NAME=agent_001

launches the standalone agent declared in the repository as agent_001 on the port 20300.

WARNING:

On Windows platforms, it is necessary to "delimit" the command arguments containing "=" signs or spaces, by using double quotes. For example:

agent.bat "-PORT=20300" "-NAME=agent_001"

4.3.1.3 Stopping an Agent

You can stop a standalone agent by stopping the Java process of this agent.

You can stop a standalone agent remotely using the agentstop command.

To stop a standalone agent:

  1. Change directory to the /agent/bin directory of the Oracle Data Integrator Agent.

  2. Enter the following command to stop the agent.

    • On UNIX system:

      ./agentstop.sh

    • On Windows system:

      agentstop.bat

The listening agent is stopped.

Examples:

  • On Windows: agentstop "-PORT=20300" stops the agent on the port 20300.

  • On UNIX: ./agentstop.sh stops the agent on the default port.

AgentStop Command Parameters

The table below lists the different parameters for the command to stop the agent. The parameters are preceded by the "-" character and the possible values are preceded by the "=" character. When entering the command, consider the operating system specific syntax of the delimiters.

Parameters Description
-PORT=<port> This parameter is deprecated. It is used to stop a standalone agent on the same machine. It is a shortcut to -AGENT_URL=http://localhost:<port>/oraclediagent.

The default port is 20910.

-AGENT_URL=<agent_url> URL of the standalone agent to stop. This parameter has precedence over the AGENT_NAME and PORT parameters is deprecated.
-NAME=<agent name> If this parameter is specified, the physical agent whose name is provided is killed. This agent may be a local or remote agent, and must be declared in the master repository. This parameter has precedence over the PORT parameter.
-IMMEDIATE=<true(default)|false> If this parameter is set to yes then the agent is killed without waiting for completion of its running sessions. If it is set to no then the agent is killed after all its running sessions reach completion or after the MAX_WAIT timeout is reached. Default value is No.
-MAX_WAIT=<stop timeout in millis> This parameter can be used when IMMEDIATE is set to No. It defines a timeout in milliseconds after which the agent is killed regardless of the running sessions. Default is 0, meaning no timeout and the agent is killed after all its running sessions reach completion.

4.3.2 Java EE Agent

Managing a Java EE agent involves the actions discussed in the sections:

4.3.2.1 Deploying an Agent in a Java EE Application Server (Oracle WebLogic Server)

The easiest way for deploying an Oracle Data Integrator agent in Oracle WebLogic Server (WLS) is to generate a WLS template with Oracle Data Integrator. This template can directly be deployed into WLS Configuration Wizard.

To deploy an agent in a Java EE Application Server (Oracle Web Logic Server), follow the procedure in the following tasks.

4.3.2.1.1 Define the Java EE Agent in the Topology

Defining a Java EE agent consists of two tasks. First, you need to create the physical agent corresponding to your Java EE agent, then, a logical agent.

To create a physical agent:

  1. In Topology Navigator right-click the Agents node in the Physical Architecture accordion.

  2. Select New Agent.

  3. In the Definition tab, pay attention to the following parameters.

    • Name is the name of the Java EE agent.

    • Host must correspond to the WLS host name.

    • Port is the HTTP port of the Java EE Agent application.

    • Protocol: Protocol to use for the agent connection. Possible values are http or https. Default is http.

    • Web Application Context is name of the web application corresponding to the Java EE agent.

  4. Drag and drop the work repositories or data servers to be managed as Java EE data sources from the Repositories accordion in the Topology Navigator into the DataSources tab of this agent's Editor.

  5. Provide a JNDI name for these data sources.

  6. Drag and drop the source/target data servers that this agent will access from the Physical Architecture accordion in the Topology Navigator into the DataSources tab of this agent's Editor.

  7. Provide a JNDI name for these data sources.

  8. From the File menu, click Save to save the Physical Agent.

To create a logical agent:

  1. Create a Logical Agent for this Physical Agent as described in Section 4.2.6, "Creating a Logical Agent".

  2. Map the Logical Agent in the appropriate context.

4.3.2.1.2 Create an WLS template for the Java EE Agent

Oracle Data Integrator provides a WLS Template Generation wizard to help you create an WLS template for a run-time agent.

To open the WLS Template Generation wizard:

  1. From the Physical Agent Editor toolbar menu, select Generate WLS Template. This starts the Template Generation wizard.

  2. In the Agent Information step, review the agent information and modify the default configuration if needed.

    The Agent Information includes the following parameters:

    • General

      Agent Name: Displays the name of the Agent that you want to deploy.

    • Master Repository Connection

      JNDI Datasource Name: The name of the datasource used by the Java EE agent to connect to the master repository. The template can contain a definition of this datasource. Default is jdbc/odiMasterRepository.

    • Connection Retry Settings

      Connection Retry Count: Number of retry attempts done if the agent loses the connection to the repository. Note that setting this parameter to a non-zero value, enables a high availability connection retry feature if the ODI repository resides on an Oracle RAC database. If this feature is enabled, the agent can continue to execute sessions without interruptions even if one or more Oracle RAC nodes become unavailable.

      Retry Delay (milliseconds): Interval (in milliseconds) between each connection retry attempt.

    • Supervisor Authentication

      Supervisor Key: Name of the key in the application server credential store that contains the login and the password of an ODI user with Supervisor privileges. This agent will use this user credentials to connect to the repository.

  3. Click Next.

  4. In the Libraries and Drivers step, select from the list the external libraries and drivers to deploy with this agent. Only libraries added by the user appear here.

    Note that the libraries can be any JAR or ZIP file that is required for this agent. Additional JDBC drivers or libraries for accessing the source and target data servers must be selected here.

    You can use the corresponding buttons in the toolbar to select or deselect all libraries and/or drivers in the list.

  5. Click Next.

  6. In the Datasources step, select the datasources definitions that you want to include in this agent template. You can only select datasources from the wizard. Naming and adding these datasources is done in the Data Sources tab of the Physical Agent editor.

  7. Click Next.

  8. In Template Target and Summary step, enter the Target Template Path where the WLS template will be generated.

  9. Click Finish to close the wizard and generate the WLS template.

    The Template generation information dialog appears.

  10. Click OK to close the dialog.

The generated template can be used to deploy the agent in WLS using the WLS configuration wizard. Refer to the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for more information.

Declare the Supervisor in the WLS Credential Store

After deploying the template, it is necessary to declare the Supervisor into the WLS Credential Store. Refer to the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for more information.

4.3.2.2 Deploying Datasources from Oracle Data Integrator in WLS for an Agent

You can create datasources from the Topology Navigator into a WebLogic Server for which a Java EE agent is configured.

To deploy datasources in a Oracle WebLogic Server:

  1. Open the Physical Agent Editor configured for the WLS application server into which you want to deploy the datasources.

  2. Go to the Datasources tab.

  3. Drag and Drop the source/target data servers from the Physical Architecture tree in the Topology Navigator into the DataSources tab.

  4. Provide a JNDI Name for these datasources.

  5. Right-click any of the datasource, then select Deploy Datasource on WLS.

  6. Fill in the following fields:

    • Host: Host name or IP address of the WLS Admin Server.

    • Port: Port of the WLS Admin Server

    • User: WebLogic server user name.

    • Password: this user's password

    • Target: WLS Target into which this datasource will be deployed.

  7. Click OK.

Note:

This operation only creates the Datasources definition in WebLogic Server. It does not install drivers or library files needed for these datasources to work. Additional drivers added to the Studio classpath can be included into a WLS Agent Template. See Section 4.3.2.1.2, "Create an WLS template for the Java EE Agent" for more information.

WLS Datasource Configuration and Usage

When setting up datasources in WebLogic Server for Oracle Data Integrator, please note the following:

  • Datasources should be created with the Statement Cache Size parameter set to 0 in the Connection Pool configuration. Statement caching has a minor impact on data integration performances, and may lead to unexpected results such as data truncation with some JDBC drivers.

  • If using Connection Pooling with datasources, it is recommended to avoid ALTER SESSION statements in procedures and Knowledge Modules. If a connection requires ALTER SESSION statements, it is recommended to disable connection pooling in the related datasources, as an altered connection returns to the connection pool after usage.

4.3.3 Load Balancing Agents

Oracle Data Integrator allows to load balance parallel session execution between physical agents.

Each physical agent is defined with:

  • A maximum number of sessions it can execute simultaneously from a work repository

    The maximum number of sessions is a value that must be set depending on the capabilities of the machine running the agent. It can be also set depending on the amount of processing power you want to give to the Oracle Data Integrator agent.

  • Optionally, a number of linked physical agents to which it can delegate sessions' executions.

An agent's load is determined at a given time by the ratio (Number of running sessions / Maximum number of sessions) for this agent.

4.3.3.1 Delegating Sessions

When a session is started on an agent with linked agents, Oracle Data Integrator determines which one of the linked agents is less loaded, and the session is delegated to this linked agent.

An agent can be linked to itself, in order to execute some of the incoming sessions, instead of delegating them all to other agents. Note that an agent not linked to itself is only able to delegate sessions to its linked agents, and will never execute a session.

Delegation cascades in the hierarchy of linked agents. If agent A has agent B1 and B2 linked to it, and agent B1 has agent C1 linked to it, then sessions started on agent A will be executed by agent B2 or agent C1. Note that it is not recommended to make loops in agents links.

If the user parameter "Use new Load Balancing" is set to Yes, sessions are also re-balanced each time a session finishes. This means that if an agent runs out of sessions, it will possibly be reallocated sessions already allocated to another agent.

4.3.3.2 Agent Unavailable

When for a given agent the number of running sessions reaches its maximum number of sessions, the agent will put incoming sessions in a "queued" status until the number of running sessions falls below the maximum of sessions.

If an agent is unavailable (because it crashed for example), all its sessions in queue will be re-assigned to another load balanced agent that is neither running any session nor having sessions in queue if the user parameter Use the new load balancing is set to Yes. See Appendix B, "User Parameters" for more information.

4.3.3.3 Setting Up Load Balancing

To setup load balancing:

  1. Define a set of physical agents, and link them in a hierarchy of agents (See "Creating a Physical Agent" for more information.)

  2. Start all the physical agents corresponding to the agents defined in the topology.

  3. Run the executions on the root agent of your hierarchy. Oracle Data Integrator will balance the load of the executions between its linked agents.