2.2 Creating Adapter Definitions

The first step in creating a new adapter definition is to set up basic information about the adapter and the database connection. The Create Adapter Definition wizard steps through these initial steps.

To create an adapter definition:

  1. In the Explorer pane, expand the Administration root element > Adapters.

  2. Right-click Data Integrator, then select Create Definition to open the Create Adapter Definition dialog box:

  3. In the Create Adapter Definition dialog box, specify an Adapter Name and Description:

    Adapter Name: The name of the new adapter that is created when the definition is deployed. When deployed, this is the name that the user selects from the Adapter Type drop-down list in the Create Adapter dialog box to create an adapter instance.

    Description: Provides additional information about the definition. This description displays when the mouse cursor is hovered over the adapter definition name under the Adapters hierarchy.

  4. Click Forward to continue.

  5. Select the associated radio button to define a new connection, use an existing connection, or define a new connection from an existing connection:

    Define a new connection: Define a database connection that has not been used before with Data Integrator. Continue to step 5.

    Use an existing connection: Select an existing connection to use. Skip ahead to step 6.

    Define a new connection from an existing connection: Define a new database connection by modifying the properties of a current connection. Skip ahead to step 7.

  6. Click Forward to continue.

  7. Do one of the following:

    • If defining a new connection, specify a name for the database connection. Click Forward.

    • If using an existing connection, select the connection you wish to use from the Database drop-down list. Click Forward and skip to step 9.

    • If defining a new connection from an existing connection, do the following:

      1. Select the desired connection you wish to use from the Existing Connection drop-down list.

      2. In the New Connection Name field, specify the name of the new connection.

      3. Click Forward to continue.

  8. If using an existing connection or creating a new connection from an existing connection, modify the properties as required for connection.

    Hostname: The database server name. Applies to all connection types except JDBC.

    Port: The port number where the database listens for communications. Applies to all connection types except JDBC.

    Database: The database name (when defining a SQL Server, Sybase, or DB2 database connection). Applies to all connection types except JDBC.

    Server ID: The database name (when defining an Oracle database connection). Applies to all connection types except JDBC.

    JDBC Driver: The name of the class used to initiate a JDBC driver. Typically, the class name is in a format similar to com.product.Driver. You can later hide this setting by not publishing the value as an adapter property or allow the driver to be overwritten at deployment time. Applies only to JDBC connections.

    JDBC URL: Specifies how the driver connects to a JDBC database. Applies only to JDBC Connections.

    Time Stamp Query: At runtime, Data Integrator periodically queries the JDBC database for availability. This query setting specifies how the database is queried to ensure it is available and servicing requests. Applies only to JDBC Connections.

    User Name: The name of the user account.

    Password: The password associated with the user name.

    Windows Domain: The name of the Windows domain to use for Windows native authentication. Applies to JTDS and SQL Server connections.

    For information about configuring the server for Windows Authentication, see Section 2.2.6, Configuring the Server for Windows Authentication.

    Database Type: This value (Oracle, SQL Server, Sybase, DB2, and so on) is prefilled, based on the selected database tab. For information about using a nondefault database driver, see Section 2.2.5, Using a Different Database Driver for a Data Source.

    If you are creating or modifying a mySQL connection, see Section 2.2.1, Notes on Connecting to MySQL and Section 2.2.4, Signing a JDBC Driver.

    If you are creating or modifying a JDBC connection, see Section 2.2.3, Notes on Connecting to JDBC and Section 2.2.4, Signing a JDBC Driver.

    If you are creating or modifying an Oracle RAC connection, see Section 2.2.2, Notes on Connecting to Oracle RAC and Section 2.2.4, Signing a JDBC Driver.

  9. Click Finish to complete the process and automatically open the Data Integrator Definition Editor.

    A new adapter definition displays in the Explorer pane under Administration > Adapters > Data Integrator.

    For basic information regarding using the Definition Editor and user preferences, see Section 3.0, The Data Integrator Definition Editor. This section also contains information about changing development data source settings.

    For information regarding Groups, see Section 5.2, Defining Groups.

    For information regarding Database Elements, see Section 5.4, Defining Elements from Database Information.

    For information regarding Generators, see Section 5.3, Defining Dynamic Groups (Generator Elements).

    For information regarding alarms, see Section 5.5, Creating Alarms.

The following sections are referenced for additional information from some of the preceding steps:

2.2.1 Notes on Connecting to MySQL

The MySQL JDBC driver is Open Source GPL (General Public License). To use this driver, download it from http://dev.mysql.com/downloads/connector/j/3.1.html. The driver must be placed in the following two locations, and one copy of the driver must be signed for use in the Data Integrator:

  • The Operations Center server directory: /OperationsCenter_install_path/classes/ext. Place the distributed driver as unsigned (unmodified).

  • The Operations Center console deployment directory: /OperationsCenter_install_path/html/client/deploy. This copy must be signed by NetIQ for Operations Center. For more information, see Section 2.2.4, Signing a JDBC Driver.

2.2.2 Notes on Connecting to Oracle RAC

The following procedures describe various configuration information required to use Oracle RAC for either the design-time database or the adapter run-time database. While the use of the JDBC OCI provider is not required for the design-time connection, it is required for the run-time adapter.

To specify an Oracle RAC database to use while creating (design-time) the adapter definition:

  1. Perform configuration steps as required for Oracle RAC on the Operations Center server.

    While it is not necessary to have the OCI package installed, all connections require the ojdbc6.jar file to be manually deployed to the Operations Center server.

    For instructions, see Oracle RAC in the Operations Center 5.5 Server Configuration Guide.

  2. Define the database using the Generic JDBC Driver tab, and do the following:

    1. Specify the following value for the JDBC Driver:

      oracle.jdbc.driver.OracleDriver

    2. Do one of the following to specify the JDBC URL:

      • To use the JDBC thin driver to connect to the Oracle RAC server, specify:

        jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP) (HOST=host1_ipaddress)(PORT=host1_portnumber)) (ADDRESS=(PROTOCOL=TCP) (HOST=host2_ipaddress)(PORT=host2_portnumber)) (LOAD_BALANCE=yes) (CONNECT_DATA=(SERVER=DEDICATED) (SERVICE_NAME=service_domain_name) (FAILOVER_MODE=(TYPE=SELECT)(METHOD=BASIC) (RETRIES=180)(DELAY=5))))

      • If the OCI package is installed on the client machine, do one of the following:

        To use the JDBC OCI connection (supports FCF and Transparent Application Failover (TAF), specify:

        jdbc:oracle:oci:@racdb_configuration_name

        or, if the connection is not defined in the tsnnames.ora file, specify:

        jdbc:oracle:oci:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP) (HOST=host1_ipaddress)(PORT=host1_portnumber)) (ADDRESS=(PROTOCOL=TCP) (HOST=host2_ipaddress)(PORT=host2_portnumber)) (LOAD_BALANCE=yes)(CONNECT_DATA=(SERVER=DEDICATED) (SERVICE_NAME=service_domain_name)(FAILOVER_MODE=(TYPE=SELECT) (METHOD=BASIC)(RETRIES=180)(DELAY=5))))

    3. Specify the following query command for the Time Stamp Query:

      select systimestamp from dual

To specify an Oracle RAC database to use for the run-time adapter definition:

  1. Perform configuration steps as required for Oracle RAC on the Operations Center server.

    The default database properties of the run-time adapter must use the JDBC OCI provider.

    For instructions, see Oracle RAC in the Operations Center 5.5 Server Configuration Guide.

  2. Define the database using the Generic JDBC Driver tab, and do the following:

    1. Specify the following value for the JDBC Driver:

      oracle.jdbc.driver.OracleDriver

    2. Do one of the following to specify the JDBC URL:

      • If the service definition for the RAC connection is defined in the tsnnames.ora file, specify:

        jdbc:oracle:oci:@racdb_configuration_name

      • or, if the service definition for the RAC connection is not defined in the tsnnames.ora file, specify:

        jdbc:oracle:oci:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=host1_ipaddress)(PORT=host1_portnumber))(ADDRESS=(PROTOCOL=TCP) (HOST=host2_ipaddress)(PORT=host2_portnumber))(LOAD_BALANCE=yes)(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=service_domain_name) (FAILOVER_MODE=(TYPE=SELECT)(METHOD=BASIC)(RETRIES=180)(DELAY=5))))

    3. Specify the following query command for the Time Stamp Query:

      select systimestamp from dual

2.2.3 Notes on Connecting to JDBC

To install the generic JDBC driver, locate the appropriate driver on a product distribution disk or download it. The driver must be placed in the following two locations, and one copy of the driver must be signed for use in the Data Integrator:

  • The Operations Center server directory: /OperationsCenter_install_path/classes/ext. Place the distributed driver as unsigned (unmodified).

  • The Operations Center console deployment directory: /OperationsCenter_install_path/html/client/deploy. This copy must be signed by NetIQ for Operations Center. For more information, see Section 2.2.4, Signing a JDBC Driver.

2.2.4 Signing a JDBC Driver

The /OperationsCenter_install_path/html/client/Readme.txt file describes the subdirectories in the /OperationsCenter_install_path/html/client directory.

In the deploy directory, place patches or other .jar components that have been signed by Operations Center. This directory is not be renamed when upgrading Operations Center versions, so that its contents remain the same after upgrading.

Because of the tightened security model introduced by Oracle Java 7 Update 45, all .jar components, including those from third-parties, must be signed by NetIQ for Operations Center. Contact Support to have the content signed.

2.2.5 Using a Different Database Driver for a Data Source

If there are multiple database drivers available on a machine and you want to use a specific database driver, you can specify the exact driver to use in the Database Type connection parameter. However, if the database driver should be used in the run-time database connection, there is an additional step that must be completed.

To change the default database driver:

  1. When defining or editing a database connection, in the Database Type field, replace the value with:

    driver|url|timequery
    

    where:

    • driver is the driver’s class name

    • url is the JDBC URL string

    • timequery (for Oracle) is select sysdate from dual

    The pipe (|) characters are required.

  2. If the driver is to be used for the run-time database setting, in the database tab for top-level settings, insert the same string into the Database Type field.

    If the Add to Adapter Page check box is selected for the Database Type, the setting is seen as the default property value when using an instance of the adapter.

    For more information about the database properties and run-time database settings, see Section 4.6, Setting a Run-Time Database Connection.

2.2.6 Configuring the Server for Windows Authentication

If you are using a JTDS or SQL Server connection with Windows Authentication, you must configure the server for Windows Authentication.

To configure the server for Windows Authentication:

  1. Verify or configure the following requirements on the MSSQL Server:

    • Verify the server is configured to use Windows Authentication.

    • Verify the machine is on the domain.

    • Add an associated domain user with appropriate permissions.

    • If MSSQL is setup to use an instance name, you must turn on the SQL Server Browser Service. Then add the user to the instance's security group.

  2. To configure Operations Center for Windows Single Sign-On (SSO), do the following:

    1. Do one of the following to configure the Operations Center server:

      • On Unix: No native libraries required, but you must provide user, password.

      • On Windows:

        • Native libraries are optional. If you don't use the native library, you must provide user, password.

        • The domain user must be a member of the Windows Administrators group.

    2. If running Operations Center as a service, the service must use the same domain user account as the database.

      If you are receiving an NT AUTHORITY\ANONYMOUS LOGON exception, verify that the account used by the service and the database are the same.

    3. Leave the User and Password properties blank (empty) for Data Integrator.

    4. Leave the User, Password, and Domain adapter properties blank (empty).

    5. Copy the /OperationsCenter_install_path/html/classes/win32/ntlmauth32.jar or /OperationsCenter_install_path/html/classes/win64/ntlmauth64.jar file into the /OperationsCenter_install_path/classes/ext directory.

    6. Restart the Operations Center server.