JDBC PDF
JDBC PDF
Contents 3
Installing Microsoft SQL Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Installing MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Installing Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Installing PostgreSQL 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Installing PostgreSQL 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Installing Sybase Adaptive Server Enterprise (ASE). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Testing the Database Object Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4 Contents
Working with MapDB 3.0.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Understanding Identity Manager 4.7 Engine Support for Driver Versions . . . . . . . . . . . . . . . . . . . . . 98
Manually Removing the MapDB Cache Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Considerations for Upgrading the Driver With Different Identity Manager and MapDB Versions . . . . . . . . . 98
Upgrading the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Upgrading the
Installed
Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Updating the Driver Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Contents 5
Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Embedded SQL Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Token Substitution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Virtual Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Manual vs. Automatic Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Transaction Isolation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Statement Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
SQL Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Data Definition Language (DDL) Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Logical Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Implementing Password Set with Embedded SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Implementing Modify Password with Embedded SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Implementing Check Object Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Calling Stored Procedures and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Using Embedded SQL to Call Stored Procedures or Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Using the jdbc:call-procedure Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Using the jdbc:call-function Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6 Contents
Oracle OCI JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
PostgreSQL JDBC Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Sybase Adaptive Server Enterprise JConnect JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
MariaDB Connector/J JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Supported Third-Party JDBC Drivers (Not Recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Third-Party JDBC Driver Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
JDBC URL Syntaxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
JDBC Driver Class Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
IBM DB2 Universal Database JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Microsoft SQL Server 2008 JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Microsoft SQL Server 2008 R2 JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Deprecated Third-Party JDBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Other Third-Party JDBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
IBM Toolbox for Java/JTOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Minimum Third-Party JDBC Driver Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Considerations When Using Other Third-Party JDBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Security Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Contents 7
D FAQ 205
Can’t See Tables or Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Synchronizing with Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Processing Rows in the Event Log Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Managing Database User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Synchronizing Large Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Slow Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Synchronizing Multiple Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Encrypted Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Mapping Multivalue Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Synchronizing Garbage Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Running Multiple JDBC Driver Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
N Sybase Chain Modes and the Identity Manager JDBC driver 231
Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Procedures and Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Using Stored Procedure sp_proxmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Chained and Unchained Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Managing Transactions in a Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Useful Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
8 Contents
ECMAScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Global Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Global Configuration Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Global Configuration Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Managed System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Entitlements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Account Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Password Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
JDBC Fanout Common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Contents 9
10
About this Book and the Library
The Identity Manager Driver for Java Database Connectivity (JDBC) Implementation Guide provides
a generic solution for synchronizing data between an Identity Vault and relational databases. This
guide provides an overview of the driver’s technology as well as configuration instructions.
Intended Audience
This book provides information for individuals responsible for understanding administration concepts
and implementing a secure, distributed administration model.
We are a global, enterprise software company, with a focus on the three persistent challenges in your
environment: Change, complexity and risk—and how we can help you control them.
Our Viewpoint
Adapting to change and managing complexity and risk are nothing new
In fact, of all the challenges you face, these are perhaps the most prominent variables that deny
you the control you need to securely measure, monitor, and manage your physical, virtual, and
cloud computing environments.
Our Philosophy
Selling intelligent solutions, not just software
In order to provide reliable control, we first make sure we understand the real-world scenarios in
which IT organizations like yours operate—day in and day out. That's the only way we can
develop practical, intelligent IT solutions that successfully yield proven, measurable results. And
that's so much more rewarding than simply selling software.
Our Solutions
Identity & Access Governance
Access Management
Security Management
Systems & Application Management
Workload Management
Service Management
Worldwide: www.netiq.com/about_netiq/officelocations.asp
Email: [email protected]
Worldwide: www.netiq.com/support/contactinfo.asp
Email: [email protected]
The Identity Manager Driver for Java DataBase Connectivity (JDBC) provides a generic solution for
synchronizing data between Identity Manager and JDBC-accessible relational databases. The
principal value of this driver resides in its generic nature. Unlike most drivers that interface with a
single application, this driver can interface with most relational databases and database-hosted
applications.
You can connect to a single database using a single JDBC driver. To configure a single JDBC driver
to connect to multiple databases of the same type (for example, Oracle, MySQL, or PostgreSQL) use
the driver with the Fan-Out agent. For more information, see NetIQ Identity Manager Driver for JDBC
Fanout Implementation Guide.
“JDBC” on page 15
“Third-Party JDBC Driver” on page 16
“Identity Vault” on page 16
“Schema” on page 16
“Logical Database Class” on page 17
“XDS” on page 17
JDBC
Java DataBase Connectivity (JDBC) is a cross-platform database interface standard that Sun
Microsystems developed.
Most enterprise database vendors provide a unique implementation of the JDBC interface. Four
versions of the JDBC interface are available:
For example, ojdbc6.jar is one of the Oracle JDBC drivers. Different third-party JDBC drivers
implement different portions of the JDBC interface specification and implement the interface in a
relatively consistent manner.
The following illustration indicates the relationship between the Identity Manager JDBC driver and
third-party JDBC drivers.
Figure 1-1 Identity Manager JDBC Driver vs. Third-Party JDBC Drivers
Identity Vault
An Identity Vault is the data store that Identity Manager uses.
The Identity Vault is a persistent database powered by eDirectory and used by Identity Manager to
hold data for synchronization with a connected system. The vault can be viewed narrowly as a private
data store for Identity Manager or more broadly as a metadirectory that holds enterprise-wide
data.Data in the vault is available to any protocol supported by eDirectory, including the NetWare
Core Protocol (NCP), which is the traditional protocol used by iManager, and LDAP.
Schema
“Directory Schema” on page 17
“Application Schema” on page 17
“Database Schema” on page 17
“Synchronization Schema” on page 17
A database schema is a way to logically group objects such as tables, views, and stored procedures.
For example, the eDirectory User class and Given Name attribute are part of the eDirectory schema.
Application Schema
The application schema is the set of classes and attributes in an application.
Because databases have no concept of classes or attributes, the JDBC driver maps eDirectory
classes to tables or views, and maps eDirectory attributes to columns.
Database Schema
Database schema is essentially synonymous with ownership. A database schema consists of
database objects (for example, tables, views, triggers, stored procedures, and functions) that a
database user owns.
With the JDBC driver, schema is useful to scope the database (reduce the number of database
objects visible to the driver at runtime).
Ownership is often expressed by using a qualified dot notation (for example, indirect.usr, where
indirect is the name of the database user that owns the table usr). All of the database objects
owned by indirect constitute the indirect database schema.
Synchronization Schema
The synchronization schema is the database schema visible to the driver at runtime.
XDS
XDS format is the defined NetIQ subset of possible XML formats that Identity Manager can use.
XDS is the initial format for data coming from the Identity Vault. By modifying default rules and
changing the style sheets, you can configure the JDBC driver to work with any XML format.
Database Concepts
“Structured Query Language” on page 18
“Data Manipulation Language” on page 18
“Data Definition Language” on page 18
“View” on page 18
“Identity Columns/Sequences” on page 19
DML statements are essentially the same, regardless of the database that you use. The JDBC driver
is DML-based. It maps Identity Manager events expressed as XDS XML to standardized DML
statements.
DDL statements are proprietary and differ substantially between databases. Even though the JDBC
driver is DML-based, you can embed DDL statements in XDS events. For additional information, refer
to Chapter 12, “Embedded SQL Statements in XDS Events,” on page 133,
NOTE: Examples used throughout this guide are for the Oracle database.
View
A view is a logical table.
When queried by using a SELECT statement, the view is created by executing the SQL query supplied
when the view was defined. Views are a useful abstraction mechanism for representing multiple
tables of arbitrary structure as a single table or logical database class.
Identity Columns/Sequences
Identity columns and sequences are used to generate unique primary key values. Identity Manager
can associate with these values, among other things.
An identity column is a self-incrementing column used to uniquely identify a row in a table. Identity
column values are automatically filled in when a row is inserted into a table.
A sequence object is a counter that can be used to uniquely identify a row in a table. Unlike an
identity column, a sequence object is not bound to a single table. However, if it is used by a single
table, a sequence object can be used to achieve an equivalent result.
Transaction
A transaction is an atomic database operation that consists of one or more statements.
When a transaction is complete, all statements in the transaction are committed. When a transaction
is interrupted or one of the statements in the transaction has an error, the transaction is said to roll
back. When a transaction is rolled back, the database is left in the same state it was before the
transaction began.
Transactions are either manual (user-defined) or automatic. Manual transactions can consist of one
or more statements and must be explicitly committed. Automatic transactions consist of a single
statement and are implicitly committed after each statement is executed.
SET AUTOCOMMIT ON
INSERT INTO emp(lname) VALUES('Doe');
-- implicit commit
The Subscriber channel can use stored procedures or functions to retrieve primary key values from
rows inserted into tables, to create associations. Stored procedures or functions can also be invoked
from within embedded SQL statements or triggers.
The distinction between stored procedures and functions varies by database. Typically, both can
return output, but they differ in how they do it. Stored procedures usually return values through
parameters. Functions usually return values through a scalar return value or result set.
The following example illustrates a stored procedure definition that returns the next value of a
sequence object:
CREATE
PROCEDURE sp_idu( io_idu IN OUT INTEGER)
IS
BEGIN
IF (io_idu IS NULL) THEN
SELECT seq_idu.nextval INTO io_idu FROM DUAL;
END IF;
END sp_idu;
Trigger
A database trigger is programmatic logic associated with a table, which executes under certain
conditions. A trigger is said to fire when its execution criteria are met.
Triggers are often useful for creating side effects in a database. In the context of the JDBC driver,
triggers are useful to capture event publications. The following is an example of a database trigger on
the usr table.
-- t = trigger; i = insert
CREATE TRIGGER t_usr_i
AFTER INSERT ON usr
FOR EACH ROW
BEGIN
UPDATE usr SET fname = 'John';
END;
When a statement is executed against a table with triggers, a trigger fires if the statement satisfies the
conditions specified in the trigger. For example, using the above table, suppose the following insert
statement is executed:
Trigger t_emp_i fires after the insert statement is executed, and the following update statement is
also executed:
A trigger can typically be fired before or after the statement that triggered it. Statements that are
executed as part of a database trigger are typically included in the same transaction as the triggering
statement. In the above example, both the INSERT and UPDATE statements are committed or rolled
back together.
Instead-Of-Trigger
An instead-of-trigger is programmatic logic associated with a view, which executes under certain
conditions.
Instead-of-triggers are useful for making views writable or subscribeable. They are often used to
define what it means to INSERT, UPDATE, and DELETE from a view. The following is an example of an
instead-of-trigger on the usr table.
For example, using the above view, suppose the following insert statement is executed instead of the
original insert statement:
Rather than executing the original statement, instead-of-trigger t_view_usr_i fires and executes the
following statement:
JDBCShim.jar
JDBCUtil.jar
JDBCConfig.jar
In addition to these files, you need a third-party JDBC driver to communicate with every database.
Supported Databases
For information on supported databases, see“Supported Databases” on page 157.
Indirect Usually associated with tables Target database tables probably don’t match the
structure required by the driver. Therefore, it’s usually
necessary to create intermediate staging tables that
do match the structure that the driver requires.
Direct Usually associated with views Views provide the abstraction mechanism that best
facilitates integration with the target database tables.
The following sections describe how direct and indirect synchronization work on both the Subscriber
and Publisher channels.
Indirect Synchronization
Indirect synchronization uses intermediate staging tables to synchronize data between the Identity
Vault and a database. You can have one or more customer tables and intermediate staging tables.
Publisher Channel
Synchronization triggers update the intermediate staging tables when target database tables are
updated. Publication triggers then insert one or more rows into the event log table. The Publisher
channel then reads the inserted rows and updates the Identity Vault.
Depending on the contents of the rows read from the event log table, the Publisher channel
might need to retrieve additional information from the intermediate tables before updating the
Identity Vault. After updating the Identity Vault, the Publisher channel then deletes or marks the
rows as processed.
Direct Synchronization
Direct synchronization typically uses views to synchronize data between Identity Manager and a
database. You can use tables if they conform to the structure that the JDBC driver requires. You can
have one or more customer views or tables.
Subscriber Channel
Updates existing customer tables through a view in the synchronization schema.
Publisher Channel
When a target database table is updated, publication triggers insert rows into the event log table.
The Publisher channel then reads the inserted rows and updates the Identity Vault.
Depending on the contents of the rows read from the event log table, the Publisher channel
might need to retrieve additional information from the view before updating the Identity Vault.
After updating the Identity Vault, the Publisher channel then deletes or marks the rows as
processed.
Triggerless publication is particularly useful when support contracts forbid the use of triggers on
database application tables or for rapid prototyping.
However, triggerless publication is less efficient than triggered publication. With triggered publication,
what changed is already known. With triggerless publication, change calculation must occur before
events can be processed.
Triggerless publication, unlike triggered publication, does not preserve event order. It only guarantees
that, by the end of a polling cycle, objects in the database and the Identity Vault are in sync.
Triggerless publication, unlike triggered publication, does not provide historical data such as old
values. It provides information on the current state of an object, not the previous state.
If you move the driver without moving the state files, the driver must build up new state files by
resynchronizing. For information on this situation, see “State Directory” on page 59.
Installation Requirements
For information about installing the driver, see “Installing the Driver Files” on page 29.
By default, the JDBC driver files are installed on the Identity Manager server at the same time as the
Identity Manager engine. The installation program extends the Identity Vault’s schema and installs the
driver shim and a driver configuration file. It does not create the driver object in the Identity Vault (see
Chapter 5, “Creating a New Driver Object,” on page 43) or upgrade an existing driver’s configuration
(see Chapter 7, “Upgrading an Existing Driver,” on page 97).
The JDBC driver can either be located on the same server as the JDBC database or any other server.
The following sections explain what to do if the JDBC driver files are not on the JDBC database
server and how to install the third-party JDBC jar files that the driver uses to communicate with the
database:
For information about uninstalling the driver, see Appendix A, “Uninstalling the Driver,” on page 195.
On a local machine: Install the JDBC driver files on the Identity Manager server and connect to
the database by using the Provider URL (Connection Properties).
On a remote machine: Install the JDBC driver files on the Remote Loader.
For information on installing the Identity Manager server or the Remote Loader, see Considerations
for Installing Identity Manager Engine Components and Remote Loader in the NetIQ Identity Manager
Setup Guide for Linux or Planning to Install the Engine, Drivers, and Plug-ins in the.NetIQ Identity
Manager Setup Guide for Windows.
Windows novell\NDS\lib
Windows novell\RemoteLoader\lib
The Association utility normalizes associations of objects associated under the 1.0 or later versions of
the JDBC driver. It also provides several other features that simplify driver administration.
This version of the utility is compatible with the 1.0 and later versions of the JDBC driver, and
supersedes all previous versions.
Independent Operations
The Association utility supports seven independent operations:
It is malformed.
For example, the association is missing the schema RDN, missing
the table RDN, or the schema keyword is misspelled.
It contains database identifiers that do not map to identifiers in the
target database.
For example, an association includes a mapping to a table that
does not exist.
It maps to no row or multiple rows.
An association is broken if it doesn’t map to a row. Also,
associations aren’t unique if they map to more than one row.
The Association utility, like the driver, assumes that database identifiers are undelimited
(unquoted and contain no special characters).
Update all object associations related to a driver at the same time.
Updating associations at the same time is extremely important.
To see all of the objects associated with a particular driver, run the Association utility on the
Identity Manager server associated with a particular driver instance.
The LDAP search base must contain all of the objects associated with a particular driver.
To ensure complete containment, we recommend that you use your tree’s root container as the
search base.
Make sure that the JDBC URL of the target database supplied to this utility is the same as the
URL that the driver uses. Pointing this utility at a case-insensitive database when the database is
actually case-sensitive might result in associations being normalized to the wrong case.
Because the Association utility runs locally, it uses an unsecured connection. Therefore, the
Identity Vault LDAP server must be temporarily configured to accept clear text passwords.
Depending upon the third-party JDBC driver you are using, the database connection established
by this utility might not be secure.
We recommend changing the driver’s authentication password on the database after you run this
utility.
A properties file containing association utility parameters is provided for each supported database.
These files are in the install-dir\DirXMLUtilities\jdbc\util directory.
MySQL properties_my.txt
Oracle properties_ora.txt
PostgreSQL properties_pg.txt
The first value (for example, schema) in the parameter is the search criterion. The second value (for
example, old) is the replacement value. Under certain scenarios, you can use the wildcard character
* to generalize the search criterion or replacement value.
Replace the schema name Replace schema old with schema new. oldRDN: schema=old
Wildcards are supported on the right side newRDN: schema=new
only.
Replace the table name Replace table old with table new. oldRDN: table=old
Wildcards are not supported. newRDN: table=new
Replace the column name Replace column old with column new. oldRDN: old=*
Wildcards are required on the right side, newRDN: new=*
but they aren’t supported on the left side.
Objects
You need to install and configure database objects (for example, tables, triggers, and indexes) for
synchronization with the sample driver configuration. If you do not configure the database objects, the
sample configuration file will not work.
Windows c:\Novell\IdentityManager\NDS\DirXMLUtilities\jdbc\sql\
UNIX/Linux /opt/novell/eDirectory/lib/dirxml/rules/jdbc/sql/
For example, when the scripts are installed on a SUSE Linux Enterprise Server with eDirectory, the
DB2 scripts are found in opt/novell/eDirectory/lib/dirxml/rules/jdbc/db2_udb/install
directory.
All SQL scripts use the same conventions, regardless of the database.
The maximum size of a DB2 identifier is 18 characters. This least common denominator length
defines the upper bound of database identifier length across all SQL scripts. Because of this
restricted length, abbreviations are used. The following table summarizes identifier abbreviations and
their meanings:
Abbreviation Interpretation
idx_ index
trg_ trigger
_i on insert trigger
_u on update trigger
_d on delete trigger
Instead of proc_, the more common abbreviation is sp_. This prefix is reserved for system-stored
procedures on Microsoft SQL Server. Also, this prefix forces lookup of a procedure first in the master
database before evaluating any qualifiers (for example, database or owner). To maximize procedure
lookup efficiency, this prefix has been deliberately avoided.
The following table indicates identifier naming conventions for indexes, triggers, stored procedures,
functions, and constraints:
Other conventions:
Because the process to create user accounts differs between operating systems, Step 1 below is OS-
specific. These instructions are for a Windows NT operating environment. If you rerun the SQL
scripts, repeat only Step 2 through Step 4.
2 Adjust the file path to idm_db2.jar in the 1_install.sql installation script. The file path to
idm_db2.jar should reflect the location of this file on your client machine.
3 Execute the 1_install.sql script from the Command Line Processor (CLP.)
For example: db2 -f 1_install.sql
IMPORTANT: The scripts won’t execute in the Command Center interface beyond version 7.
The scripts use \ as the line continuation character. Later versions of the Command Center don’t
recognize this character.
Because the process of creating user accounts differs between operating systems, Step 1 below is
OS-specific. These instructions are for a Windows operating environment. If you rerun the SQL
scripts, you should repeat only Steps 2 through 4.
Installing MySQL
The directory context for MySQL SQL scripts is found in the
\products\IDM\windows\setup\drivers\jdbc\tools\sql\ directory on Windows. On Linux
platforms, the files are deployed at /opt/novell/eDirectory/lib/dirxml/rules/jdbc/sql when
novell-DXMLjdbc-4.1.0-0.noarch.rpm is installed.
1 From a MySQL client, such as mysql, log in as root user or another user with administrative
privileges.
For example, from the command line, execute
Installing Oracle
The directory context for Oracle SQL scripts is found in the install-
dir\DirXMLUtilities\jdbc\sql\oracle\install directory on Windows or install-dir/lib/
dirxml/rules/jdbc/sql/oracle/install directory on UNIX/ Linux platforms.
1 From an Oracle client, such as SQL Plus, log in as the SYSTEM user.
By default, the password for SYSTEM is MANAGER. If you execute scripts as a user other than
SYSTEM with password MANAGER, change all references to SYSTEM in the scripts prior to execution.
2 Execute the installation script 1_install.sql.
For example: SQL> @c:\1_install.sql
Installing PostgreSQL 8
The directory context for PostgreSQL scripts is found in the install-
dir\DirXMLUtilities\jdbc\sql\postgres\install directory on Windows or install-dir/lib/
dirxml/rules/jdbc/sql/postgres/install directory on UNIX/Linux platforms. The directory
context for executing PostgreSQL commands is postgres-install-dir/pgsql/bin.
5 Restart the PostgreSQL server to effect changes made to the pg_hba.conf file.
6 (Conditional) If you are using pgAdminIII, in the pg_hba.conf editor select the disk icon (save file)
in the toolbar. When prompted, press Yes.
Installing PostgreSQL 9
The directory context for PostgreSQL scripts is found in the install-
dir\DirXMLUtilities\jdbc\sql\postgres\install directory on Windows or install-dir/lib/
dirxml/rules/jdbc/sql/postgres/install directory on UNIX/Linux platforms. The directory
context for executing PostgreSQL commands is postgres-install-dir/pgsql/bin.
6 Restart the PostgreSQL server to effect the changes made to the pg_hba.conf file.
1 From a Sybase client, such as isql, log in as the sa user and execute the 1_install.sql
installation script.
For example, from the command line, execute:
isql -U sa -P -i 1_install.sql
By default, the sa account has no password.
Windows: install-
dir\DirXMLUtilities\jdbc\sql\db2_udb\test
Informix Dynamic Server UNIX/Linux: The test scripts are located in the following directories:
install-dir/lib/dirxml/rules/jdbc/sql/
informix_ids/test/log
install-dir/lib/dirxml/rules/jdbc/sql/
informix_ids/test/no_log
install-
dir\DirXMLUtilities\jdbc\sql\informix_ids\log\te
st
install-
dir\DirXMLUtilities\jdbc\sql\informix_ids\no_log
\test
Microsoft SQL Server UNIX/Linux: The test scripts are located in the following directories:
install-dir/lib/dirxml/rules/jdbc/sql/mssql/
3or4/test
install-dir/lib/dirxml/rules/jdbc/sql/mssql/5/
test
Windows: install-
dir\DirXMLUtilities\jdbc\sql\mssql\test
MySQL UNIX/Linux: The test scripts are located in the following directories:
install-dir/lib/dirxml/rules/jdbc/sql/mysql/
3or4/test
install-dir/lib/dirxml/rules/jdbc/sql/mysql/5/
test
Windows: install-
dir\DirXMLUtilities\jdbc\sql\mysql\test
Windows: install-
dir\DirXMLUtilities\jdbc\sql\oracle\test
Windows: install-
dir\DirXMLUtilities\jdbc\sql\postgres\test
Windows: install-
dir\DirXMLUtilities\jdbc\sql\sybase_ase\test
You should try the test scripts before starting the sample driver.
After the JDBC driver files are installed on the server where you want to run the driver object (see
Chapter 2, “Installing the Driver Files,” on page 29), you can create a driver object in the Identity
Vault. You do so by installing the driver packages and then modifying the driver configuration to suit
your environment. The following sections provide instructions:
NOTE: You should not create driver objects by using the Identity Manager 4.0 and later configuration
files through iManager. This method of creating driver objects is no longer supported. To create
drivers, you need to use the new package management features provided in Designer.
Before creating a driver object in Designer, you need to verify that you have all the required packages
already imported in the Package Catalog of Designer. Designer prompts you for importing the
required packages when it creates the driver object.
You can create packages based on the schema for your environment, keeping in mind the data
synchronization model (direct/indirect) and its dependent packages.
To verify you have the most recent version of the driver packages in the Package Catalog:
1 Open Designer.
2 In the toolbar, click Help > Check for Package Updates.
You can download the new packages from the Designer Auto-update site (http://cdn.novell.com/
cached/designer/packages/idm/updatesite1_0_0/).
6 Select any JDBC driver packages.
or
Click Select All to import all of the packages displayed.
By default, only the base packages are displayed. Deselect Show Base Packages Only to
display all packages.
7 Click OK to import the selected packages, then click OK in the successfully imported packages
message.
8 After the current packages are imported, continue with “Installing the Driver Packages” on
page 44.
IMPORTANT: The JDBC packages provide examples of the core functions of the JDBC driver.
These examples help you customize the driver for your environment. You can add new policies
and settings to the driver to meet your business requirements. The final implementation can be
packaged and deployed in Identity Manager.
5 (Conditional) If there are package dependencies for the packages you selected to install for this
driver, you must install them to install the selected package. Click OK to install the package
dependency listed.
6 (Conditional) If more than one type of package dependency must be installed, you are presented
with separate configuration pages for each package. Continue to click OK to install any
additional package dependencies.
7 (Conditional) The Common Settings page is displayed only if the Common Settings package is
installed as a dependency. On the Install Common Settings page, specify the common settings
for User and Group containers:
User Container: Select the Identity Vault container where the user accounts will be added in the
Identity Vault. This value becomes the default for all drivers in the driver set.
Group Container: Select the Identity Vault container where the groups will be added in the
Identity Vault. This value becomes the default for all drivers in the driver set.
8 Click Next.
When all dependencies are installed, the components must be configured.
9 On the Driver Information page, specify a name for the driver that is unique within the driver set,
then click Next.
10 On the Application Authentication page, fill in the following information for the connected
database:
Version: Specify the version of the connected database.
Synchronization Model: Specify the mode of data synchronization based on the selected
package.
Data Flow: Specify whether the authoritative source of data is the database, Identity Manager,
or bidirectional.
IMPORTANT: Ensure that you don’t change the setting for Synchronization Model and Data
Flow options that you selected earlier in the Package Configuration Wizard.
NOTE: Ensure that you don’t change the setting that you selected earlier in the Package
Configuration Wizard. If you change it after installing the package in a driver object, make sure
that you change the SyncModel in the Publication Mode GCV.
Object Class: This field is populated based on your selection in the Synchronization Model.
Specify the table or view in the connected database for which account tracking is enabled. By
default, the value is usr.
Realm: Specify the name of the realm that uniquely identifies the location of user accounts in the
connected database. For example, mysql.indirect.usr, where MySQL is the database name
with the indirect data synchronization model, and user is the table or view in the connected
database for which account tracking is enabled.
22 Click Next.
23 Review the summary of tasks that will be completed to create the driver, then click Finish.
24 After you have installed the driver object, you must change the configuration for your
environment. Proceed to “Configuring the Driver Object” on page 47.
2 In the Modeler, right-click the driver icon or the driver line, then select Live > Deploy.
3 If you are authenticated to the Identity Vault, skip to Step 5; otherwise, specify the following
information:
Host: Specify the IP address or DNS name of the server hosting the Identity Vault.
Username: Specify the DN of the user object used to authenticate to the Identity Vault.
Password: Specify the user’s password.
4 Click OK.
5 Read the deployment summary, then click Deploy.
6 Read the successful message, then click OK.
7 Click Define Security Equivalence to assign rights to the driver object:
The driver object requires rights to objects within the Identity Vault. The Admin user object is
most often used to supply these rights. However, you might want to create a DriversUser (for
example) and assign security equivalence to that user. For receiving events from the Identity
Vault, ensure that driver object’s Security Equals DN has the following rights in the Identity Vault:
Entry Rights: The rights to create entries in the Identity Vault.
Attributes Rights: The rights to modify the attributes in the Identity Vault.
7a Click Add, then browse to and select the object with the correct rights.
7b Click OK twice.
For more information about defining a Security Equivalent User in objects for drivers in the
Identity Vault, see “Establishing a Security Equivalent User” in the NetIQ Identity Manager
Security Guide.
8 Click Exclude Administrative Roles to exclude users that should not be synchronized:
You should exclude any administrative User objects (for example, Admin and DriversUser) from
synchronization.
8a Click Add, then browse to and select the user object you want to exclude.
8b Click OK.
8c Repeat Step 8a and Step 8b for each object you want to exclude.
8d Click OK.
9 Click OK.
1 If you are using the Remote Loader with the driver, make sure the Remote Loader driver
instance is running.
2 In Designer, open your project.
3 In the Modeler, right-click the driver icon or the driver line, then select Live > Start Driver.
4 Continue with “Activating the Driver” on page 49.
This integration module requires a separate activation. After purchasing the integration module, you
will receive activation details in your NetIQ Customer Center.
If you create a new JDBC driver in a driver set that already includes an activated driver from this
integration module, the new driver inherits the activation from the driver set.
If you create the driver in a driver set that has not been previously activated with this integration
module, the driver will run in the evaluation mode for 90 days. You must activate the driver with this
integration module during the evaluation period; otherwise, the driver will be disabled.
If driver activation has expired, the trace displays an error message indicating that you need to
reactivate the driver to use it. For information on activation, refer to Activating Identity Manager in the
NetIQ Identity Manager Overview and Planning Guide.
Setting Description
Driver name The name of the driver that you want to display in
the driver set.
Third-party JDBC The class of the third-party JDBC file specific to the
implementation database being synchronized with Identity Manager.
For more information, see “JDBC Driver Class
Names” on page 171.
Database port The port that the driver shim uses to communicate
with the database. If you don’t provide a port
number, the Driver Configuration Wizard provides a
default port number for the database that you
selected at install time.
Smart Configuration
The JDBC driver can recognize the supported set of third-party JDBC drivers and databases. Also,
the driver can dynamically and automatically configure the majority of driver compatibility parameters
so you don’t need to understand and explicitly set such parameters.
These features are implemented via the following four types of XML descriptor files, which describe a
third-party JDBC driver or database to the JDBC driver.
In addition to predefined descriptor files, you can create custom descriptor files for a database or
third-party JDBC driver.
Furthermore, custom nonimport descriptors cannot import reserved descriptor imports. For example,
if a custom third-party JDBC driver descriptor file named custom.xml tries to import a reserved third-
party JDBC driver descriptor named _reserved.xml, an error is issued. These limitations accomplish
the following:
Ensure that no dependencies exist between reserved and custom import files
Allow extension of existing reserved descriptor files in later versions of the driver
The following table identifies where to place descriptors within a descriptor .jar file:
Database com/novell/nds/dirxml/driver/jdbc/db/descriptor/db
Reserved descriptor files are located in the JDBCConfig.jar file. To ensure that these reserved files
are not overwritten when the JDBC driver is updated, place custom descriptors in a different .jar file.
Parameters and other information specified in a nonimportable descriptor file always have
precedence over information specified in descriptor import files. If a parameter or other information is
duplicated within a descriptor file, the first instance of the parameter or information takes precedence
over subsequent instances.
Among import files, precedence is determined by import order. Import files declared earlier in the
import list take precedence over those that follow.
Third-party JDBC driver Appendix H, “Third-Party JDBC Driver Descriptor DTD,” on page 219
Third-party JDBC driver Appendix I, “Third-Party JDBC Driver Descriptor Import DTD,” on page 221
import
Configuration Parameters
“Viewing Driver Parameters” on page 53
“Deprecated Parameters” on page 54
“Authentication Parameters” on page 54
connection-tester-class The driver now dynamically creates a connection tester class at runtime,
based upon information in XML descriptor files. This parameter is still
operable, to ensure backwards compatibility. Its continued use, however, is
discouraged.
connection-test-stmt The driver now dynamically creates a connection tester class at runtime,
based upon information in XML descriptor files. This parameter is still
operable, to ensure backwards compatibility. Its continued use, however, is
discouraged.
Authentication Parameters
After you import the driver, provide authentication information for the target database.
Authentication ID
An Authentication ID is the name of the driver’s database user/login account.The installation SQL
script for each database provides information on the database privileges required for this account to
authenticate to a supported database. The scripts are located in the install-
dir\DirXMLUtilities\jdbc\sql\abbreviated-database-name\install directory.
This value can be referenced in the Connection Properties parameter value via the token
{$username}. See “Connection Properties” on page 66.
Authentication Context
The authentication context is the JDBC URL of the target database.
URL format and content are proprietary. They differ among third-party JDBC drivers. However, they
have some similarities in content. Each URL, whatever the format, usually includes an IP address or
DNS name, port number, and a database identifier. For the exact syntax and the content
requirements of your driver, consult your third-party driver documentation.
For a list of JDBC URL syntaxes for supported third-party drivers, see “JDBC URL Syntaxes” on
page 171.
IMPORTANT: Changing anything in this value other than URL properties forces a resynchronization
of all objects when triggerless publication is used.
This value can be referenced in the Connection Properties parameter value via the token
{$password}. See “Connection Properties” on page 66.
Driver Parameters
The Driver Parameters section lets you configure the driver-specific parameters. When you change
driver parameters, you tune driver behavior to align with your network environment. The following
table summarizes all driver-level parameters and their properties:
1
One of these mutually exclusive parameters must be present if the Synchronization Filter parameter
is not present. See “Synchronization Filter” on page 61. 2 This default is derived dynamically at
runtime from descriptor files and database metadata. 3 This default is derived dynamically from
descriptor files at runtime.
Property Value
Required? yes
Case-Sensitive? yes
For a list of supported third-party JDBC driver classnames, see “JDBC Driver Class Names” on
page 171.
Time Syntax
The Time Syntax parameter specifies the format of time-related data types that the driver returns. The
format can be any of the following options:
“Return Database Time, Date, and Timestamp Values as 32-Bit Integers” on page 57
“Return Database Time, Date, and Timestamp Values as Canonical Strings” on page 58
“Return database Time, Date, and Timestamp Values in their Java String Representation as
Returned by the Method toString():java.lang.String” on page 58
eDirectory Time and Timestamp syntaxes are composed of unsigned, 32-bit integers that express the
number of whole seconds that have elapsed since 12:00 a.m., January 1st, 1970 UTC. The maximum
range of this data type is approximately 136 years. When interpreted as unsigned integers (as
originally intended), these syntaxes are capable of expressing dates and times to the second in the
range of 1970 to 2106. When interpreted as a signed integer, these syntaxes are capable of
expressing dates and times to the second in the range of 1901 to 2038.
Identity Vault Time and Timestamp syntaxes cannot express as large a date range as database
Date or Timestamp syntaxes.
Identity Vault Time and Timestamp syntaxes are granular to the second. Database Timestamp
syntaxes are often granular to the nanosecond.
Map the database Time, Date, and Timestamp values to eDirectory attributes of type Time or
Timestamp.
java.sql.Time HHMMSS
java.sql.Date CCYYMMDD
java.sql.Timestamp CCYYMMDDHHMMSSNNNNNNNNN
These fixed-length formats collate in chronological order on any platform in any locale. Even though
the precision of nanoseconds varies by database, the length of Timestamps does not.
Map the database Time, Date, and Timestamp values to attributes of type Numeric String.
Return database Time, Date, and Timestamp Values in their Java String
Representation as Returned by the Method toString():java.lang.String
The following table shows abstract database data types and their corresponding Java String
representations:
java.sql.Time hh:mm:ss
java.sql.Date yyyy-mm-dd
These fixed-length formats collate in chronological order on any platform in any locale. The precision
of nanoseconds, and therefore the length of Timestamps, varies by database.
Map the database Time, Date, and Timestamp values to attributes of type Case Ignore/Case Exact
String.
Property Value
Required? no
Schema-Dependent? True
State Directory
The State Directory parameter specifies where a driver instance should store state data. The state
data is currently used for both triggered and triggerless publication. For more information, see
Triggered Publication Parameters and Triggerless Publication Parameters. The state data might be
used to store additional state information in the future.
Each driver instance can have a maximum of four state files with a unique file format, such as:
jdbc_<driver instance guid> - Triggerless Publication (only used for Triggerless configured
drivers)
jdbc_<driver instance guid>_0 - Subscriber Query
jdbc_<driver instance guid>_1 - Publisher Query
jdbc_<driver instance guid>_2 - Subscriber Service Query
Defunct state files (those belonging to deleted drivers) in the state directory are deleted each time a
driver instance with the same state directory is started.
When you move your driver to a new server, the process includes creating a new driver object on the
new server. The newly created driver object will have its own GUID. Therefore, copying the state files
of the old driver to the new server does not work even if the driver versions are same (or have the
same state file extensions). In order to prevent resynchronization, ensure that Triggerless
Publication Legal Values 2 (process future changes only) option is set in the driver properties.
If more than two files exist in the specified state directory, you must look up the GUID to know which
files belong to the driver instance being moved. To identify a driver instance’s state files, you can use
DSTrace. For convenience, the Identity Manager engine traces each driver's GUID in DSTrace on
startup.
When a process is started, a default directory in the file system is assigned to it. The default directory
is the current directory. If you don't supply a value, the default State Directory is the current directory
(the one that the process is running in).
No data is lost when resynchronization occurs, although additional data might remain. For example,
because deletes are not captured, users that were deleted in the database during the move will not
be disabled/deleted (depending upon the policy).
Moving the driver is not to be undertaken whimsically. As a rule of thumb, don't move the driver
unless you must do so.
Properties
The following table lists the properties of the State Directory parameter:
Property Value
Required? no
Case-Sensitive? platform-dependent
Synchronization Filter
The Synchronization Filter parameter determines which database objects, such as tables and views,
are members of the synchronization schema (the set of tables/views visible to the driver at runtime).
With the addition of this parameter, the driver can now run in two modes: schema-aware or schema-
unaware.
Schema-Unaware Mode
When the Synchronization Filter parameter is present and set to empty (exclude all tables/views), the
driver is schema-unaware. It does not retrieve table/view metadata on startup. Therefore, no
metadata methods are required. See Appendix F, “java.sql.DatabaseMetaData Methods,” on
page 211.
When it is schema-unaware, the synchronization schema can be empty. Both the Schema Name and
Sync Tables/Views parameters are completely ignored. Neither is required. Both can be absent,
present, valued or valueless. See “Schema Name” on page 63 and “Table/View Names” on page 64.
In schema-unaware mode, the driver acts as a passthrough agent for embedded SQL. In this state,
standard XDS events (for example, Add, Modify, and Delete) are ignored. See Chapter 12,
“Embedded SQL Statements in XDS Events,” on page 133. Also, triggered or triggerless publication
no longer work.
Schema-Aware Mode
When the Synchronization Filter parameter is not present or set to a value other than empty (exclude
all tables/views), the driver is schema-aware. It retrieves table/view metadata on a limited number of
tables/views to facilitate data synchronization. You can cache metadata on all tables/views owned by
a single database user (include by schema membership), or cache metadata on an explicit list of
table/view names (include by table/view name). When schema-aware, the driver retrieves database
table/view metadata on startup. For a list of required metadata methods, see Appendix F,
“java.sql.DatabaseMetaData Methods,” on page 211.
When schema-aware, parameter Schema Name or Table/View Names must be present and have a
value. Because these two parameters are mutually exclusive, only one parameter can have a value.
See “Schema Name” on page 63 and “Table/View Names” on page 64.
The following table lists the parameters that require the driver to be schema-aware. When the driver
is schema-unaware, these parameters do not have any effect on driver behavior.
Parameter
Retrieval Timing
Disable Publisher?
Publication Mode
Allow Loopback?
Startup Option
Batch Size
The following table lists the properties of the Synchronization Filter parameter:
Property Value
Required? no
Case-Sensitive? no
Legal Values empty (exclude all tables/views), schema (include by schema membership),
list (include by table/view name)
When using this parameter instead of Table/View Names, names of database objects are implicitly
schema-qualified by the driver. As such, parameters referencing stored procedure, function, or table
names do not need to be schema-qualified unless they reside in a schema other than the one
specified here. In particular, Method and Timing (Table-Local) and Event Log Table Name are
affected. See “Table/View Names” on page 64, “Method and Timing (Table-Local)” on page 82, and
“Event Log Table Name” on page 89.
The following table lists the properties of the Schema Name parameter:
Property Value
Required? yes
When the Schema Name parameter is used without the Synchronization Filter parameter, the Table/
View Names parameter must be left empty or omitted from a configuration. See “Synchronization
Filter” on page 61 and “Table/View Names” on page 64.
Changing the value of the Schema Name parameter forces a resync of all objects when triggerless
publication is used.
The following table lists the properties of the Include Filter Expression parameter:
Property Value
Required? no
Case-Sensitive? yes
The following table lists the properties of the Exclude Filter Expression parameter:
Property Value
Required? no
Case-Sensitive? yes
Table/View Names
The Table/View Names parameter allows you to create a logical database schema by listing the
names of the logical database classes to synchronize. Logical database class names are the names
of parent tables and views. It is incorrect to list child table names.
This parameter is particularly useful for synchronizing with databases that do not support the concept
of schema, such as MySQL, or when a database schema contains a large number of tables or views
of which only a few are of interest. Reducing the number of table/view definitions cached by the driver
can shorten startup time as well as reduce runtime memory utilization.
When using this parameter instead of Schema Name, you probably need to schema-qualify other
parameters that reference stored procedure, function, or table names. In particular, the Method and
Timing (Table-Local) and Event Log Table Name parameters are affected. See “Schema Name” on
page 63, “Method and Timing (Table-Local)” on page 82 and “Event Log Table Name” on page 89.
The following table lists the properties of the Table/View Names parameter:
Property Value
Required? yes
When this parameter is used without the Synchronization Filter parameter, the Schema Name
parameter must be left empty or omitted from a configuration. See “Synchronization Filter” on
page 61 and “Schema Name” on page 63.
Changing anything in the Table/View Name parameter other than URL properties forces a
resynchronization of all objects when triggerless publication is used.
Connectivity Parameters
“Use Minimal Number of Connections?” on page 65
“Connection Initialization Statements” on page 66
“Connection Properties” on page 66
By default, the driver uses three connections: one for subscription, and two for publication. The
Publisher channel uses one of its two connections to query for events and the other to facilitate query-
back operations.
When this parameter is set to Boolean True, the number of required database connections is reduced
to two. One connection is shared between the Subscriber and Publisher channels. It is used to
process subscription and publication query-back events. The other is used to query for publication
events.
In previous versions, the driver was able to support bidirectional synchronization by using a single
connection. The publication algorithm was redesigned to increase performance, enable support for
future event processing, and to overcome limitations of the previous algorithm at the expense of
requiring an additional connection.
Property Value
Required? no
Schema-Dependent False
The Default Value property is derived dynamically from descriptor files at runtime. Otherwise, the
default value is Boolean False.
Property Value
Required? no
Delimiters semicolon
Schema-Dependent False
Connection Properties
The Connection Properties parameter specifies authentication properties. This parameter is useful for
specifying properties that cannot be set via the JDBC URL specified in the Authentication Context
parameter. See “Authentication Context” on page 54.
The primary purpose of this parameter is to enable encrypted transport for third-party JDBC drivers.
For a list of relevant connection properties, see “Sybase Adaptive Server Enterprise JConnect JDBC
Driver” on page 183 and “Oracle Thin Client JDBC Driver” on page 179.
Connection properties are specified as key-value pairs. The key is specified as the value to the left of
the “=” character. The value is the value to the right of the “=” character. You can specify multiple key-
value pairs, but each pair must be delimited by the “;” character.
If specified as connection properties, value tokens can be used as placeholders for the database
username specified in the Authentication ID parameter and the password specified in the Application
Password parameter. See “Authentication ID” on page 54 and “Application Password” on page 55.
For username, the token is {$username}. For password, the token is {$password}.
Property Value
Required? no
Delimiters semicolon
Schema-Dependent False
Each connection property is a key value pair. You can add any number of connection properties in the
driver configuration. You must append username and password (user={$username};
password={$password}) to the additional connection properties. Separate each connection property
using delimiters.
Compatibility Parameters
“JDBC Driver Descriptor Filename” on page 68
“Database Descriptor Filename” on page 68
“Use Manual Transactions?” on page 69
“Transaction Isolation Level” on page 69
“Reuse Statements?” on page 70
“Number of Returned Result Sets” on page 71
“Enable Statement-Level Locking?” on page 71
“Lock Statement Generator Class” on page 72
“Enable Referential Attribute Support?” on page 72
“Enable Meta-Identifier Support?” on page 73
“Force Username Case” on page 73
“Left Outer Join Operator” on page 74
“Retrieve Minimal Metadata” on page 74
“Function Return Method” on page 75
“Supports Schemas in Metadata Retrieval?” on page 75
Property Value
Required? no
Case-Sensitive? platform-dependent
Schema-Dependent False
Property Value
Required? no
Case-Sensitive? platform-dependent
Schema-Dependent False
This parameter is primarily used to enable interoperability with MySQL MyISAM table types, which do
not support transactions.
When set to Boolean True, the driver uses manual transactions. When set to Boolean False, each
statement executed by the driver is executed autonomously (automatically).
Property Value
Required? no
Case-Sensitive? no
Schema-Dependent False
The Default Value property is derived dynamically from descriptor files and database metadata at
runtime.
To ensure data integrity, set this parameter to Boolean True whenever possible.
unsupported
none
read uncommitted
read committed
repeatable read
serializable
Five of the values correspond to the public constants defined in the java.sql Interface Connection
(http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Connection.html).
Because some third-party drivers do not support setting a connection’s transaction isolation level to
none, the driver also supports the additional non-standardized value of unsupported. PostgreSQL
online documentation (http://www.postgresql.org/docs/current/static/transaction-iso.html) has one of
the better, concise primers on what each isolation level actually means.
We recommend using a transaction isolation level of read committed because it is the minimum
isolation level that prevents the driver from seeing uncommitted changes (dirty reads).
Property Value
Required? no
Case-Sensitive? no
Schema-Dependent False
The Default Value property is derived dynamically from descriptor files at runtime. Otherwise, the
default value is read committed.
Reuse Statements?
The Reuse Statements? parameter specifies whether one or more java.sql.Statement items are
active at a time on a given connection. See java.sql.Statement (http://java.sun.com/j2se/1.5.0/docs/
api/java/sql/Statement.html).
This parameter is primarily used to enable interoperability with “Microsoft JDBC Driver for SQL
Server” on page 175
When set to Boolean True, the driver allocates a Java SQL Statement once and then reuses it. When
set to Boolean False, the driver allocates/deallocates statement objects each time they are used,
ensuring that no more than one statement is active at a time on a given connection.
Property Value
Required? no
Case-Sensitive? no
Schema-Dependent False
The Default Vault is derived dynamically from descriptor files at runtime. Otherwise, the default value
is Boolean True.
This parameter is primarily used to avoid infinite loop conditions in “Oracle Thin Client JDBC Driver”
on page 179 when evaluating the results of arbitrary SQL statements.
Property Value
Required? no
Legal Values none, no (none) single, one (one) multiple, many, yes (multiple)
Schema-Dependent False
The Default Value property is derived dynamically from descriptor files at runtime. Otherwise, the
default value is multiple, many, or yes.
Property Value
Required? no
Schema-Dependent True
Property Value
Required? no
Schema-Dependent True
Th Default Value property is derived dynamically from descriptor files at runtime. Otherwise, the
default value is com.novell.nds.dirxml.driver.jdbc.db.lock.DBLockGenerator.
When set to Boolean True, foreign key columns are interpreted as referential. When set to Boolean
False, foreign key columns are interpreted as non-referential.
The primary purpose of this parameter is to ensure backward compatibility with the 1.0 version of the
driver. For 1.0 compatibility, set this parameter to Boolean False.
Property Value
Required? no
Schema-Dependent True
For example, when meta-identifier support is enabled, column pk_idu has an effective column name
of idu, prohibiting the existence of another column with the same effective name in the same view.
When meta-identifier support is disabled, column pk_idu has the effective column name of pk_idu,
allowing the existence of another column named idu. Furthermore, when meta-identifier support is
enabled, a view with a primary key named pk_idu would conflict with a table having a primary key
column named idu. When meta-identifier support is disabled, they would not conflict.
When set to Boolean True, view column prefixes are interpreted as metadata. When set to Boolean
False, view column name prefixes are interpreted as part of the column name proper.
The primary purpose of this parameter is to ensure backward compatibility with the 1.5 version of the
driver. For 1.5 compatibility, set this parameter to Boolean False.
Property Value
Required? no
Schema-Dependent True
The primary purpose of this parameter is to enable interoperability with the Informix JDBC Driver
when used against ANSI-compliant databases. See “Informix JDBC Driver” on page 174.
Property Value
Required? no
Legal Values lower (to lowercase), mixed (to mixed case), upper (to uppercase),
don’t force (default)
Schema-Dependent False
Property Value
Required? no
Schema-Dependent True
The Default Value property is derived dynamically from descriptor files at runtime. Otherwise, the
default value is LEFT OUTER JOIN.
Property Value
Required? no
Schema-Dependent True
The Default Value property is derived dynamically from descriptor files at runtime. Otherwise, the
default value is Boolean False.
Setting this value to Boolean True improves startup time and third-party JDBC driver compatibility at
the expense of functionality.
The primary purpose of this parameter is to enable interoperability with the Informix JDBC driver. See
“Informix JDBC Driver” on page 174.
When set to result set, function results are retrieved through a result set. When set to return
value, the function result is retrieved as a single, scalar return value.
Property Value
Required? no
Schema-Dependent False
The Default Value property is derived dynamically from descriptor files at runtime.
The primary purpose of this parameter is to enable interoperability with the Informix JDBC Driver
when used against ANSI-compliant databases. See “Informix JDBC Driver” on page 174.
When set to Boolean True, schema names are used. When set to Boolean False, they are not.
Property Value
Required? no
Schema-Dependent False
The Default Value property is derived dynamically from descriptor files at runtime. Otherwise, the
default value is Boolean True.
The primary purpose of this parameter is to enable interoperability with legacy databases, such as
DB2/AS400.
Sorting columns names by hexadecimal value ensures that if a driver instance is relocated to a
different server, it continues to function without modification. Sorting column names by platform or
locale string collation order is more intuitive, but might require configuration changes if a driver
instance is relocated to a different server. In particular, log table column order and compound column
name order might change. In the case of the latter, Schema-Mapping policies and object association
values might need to be updated. In the case of the former, log table columns might have to be
renamed.
It is also possible to specify any fully-qualified Java class name as long as the following occur:
Property Value
Required? no
Schema-Dependent True
IMPORTANT: After you set this parameter for a given configuration, don’t change the parameter.
The primary purpose of this parameter is to remove the unintentional trailing spaces from the field
names.
If the option is set to no, the trailing spaces are removed from the fields. Set the option to yes, if you
do not want to remove the trailing whitespaces.
Property Value
Required? yes
Default Value no
Schema-Dependent False
NOTE: When the Preserve white space in SQL statements? parameter is set to no, ensure that you
do not add trailing spaces, because extra spaces are removed while formatting.
Subscription Parameters
The following table summarizes Subscriber-level parameters and their properties:
Retrieval Timing (Table- key-gen-timing after (after row insertion) before (before no
Global) row insertion)
This default for the Add Default Values on Insert property is derived dynamically from descriptor files
at runtime.
Uncategorized Parameters
“Disable Subscriber?” on page 78
“Disable Statement-Level Locking?” on page 79
“Check Update Counts?” on page 79
“Add Default Values on Insert?” on page 79
Disable Subscriber?
The Disable Subscriber? parameter specifies whether the Subscriber channel is disabled.
When this parameter is set to Boolean True, the Subscriber channel is disabled. When the parameter
is set to Boolean False, the Subscriber channel is active.
Property Value
Required? no
Schema-Dependent False
When this parameter is set to Boolean True, database resources are explicitly locked. When this
parameter is set to Boolean False, database resources are not explicitly locked.
Property Value
Required? no
Schema-Dependent True
When set to Boolean True, update counts are checked. If nothing is updated, an exception is thrown.
When set to Boolean False, update counts are ignored.
When statements are redefined in before-trigger logic, set his parameter to Boolean False
When using Microsoft SQL Server, use the default value, because errors in trigger logic (that might
roll back a transaction) are not propagated back to the Subscriber channel.
Property Value
Required? no
Schema-Dependent True
The primary purpose of this parameter is to enable interoperability with Microsoft SQL Server 2000.
This database requires that view columns constrained NOT NULL have a non-NULL value in an INSERT
statement.
Property Value
Required? no
Schema-Dependent True
The Default Value property is derived dynamically from descriptor files at runtime.
When processing <add> events, which map to INSERT statements, the Subscriber channel uses
primary key values to create Identity Manager associations. These parameters specify how and when
the Subscriber channel obtains the primary key values necessary to construct association values.
How primary key values are obtained is the primary key generation/retrieval method. The retrieval
timing indicates when primary key values are retrieved.
Driver (Subscriber-generated) Y Y
(stored procedure/function) Y Y
1
The Subscriber channel automatically overrides this timing and changes it to before.
2 The Subscriber channel automatically overrides this timing and changes it to after.
When this parameter is set to none, primary key values are assumed to already exist in the
subscription event. When this parameter is set to driver, primary key values are generated by one of
the following:
For string column types, the Subscriber channel generates a value by using the return value of
System.CurrentTimeMillis(). Other data types are not supported.
When this parameter is set to auto, primary key values are retrieved via the
java.sql.Statement.getGeneratedKeys():java.sql.ResultSet method. The MySQL
Connector/J JDBC driver is the only supported third-party JDBC driver that currently implements this
method. See “MySQL Connector/J JDBC Driver” on page 178.
Property Value
Required? no
Schema-Dependent True
When this parameter is set to before, primary key values are retrieved before insertion. When this
parameter is set to after, primary key values are retrieved after insertion.
Property Value
Required? no
Legal Values before (before row insertion), after (after row insertion)
Schema-Dependent True
When using the Table/View Names parameter, you probably need to explicitly schema-qualify any
tables, views, stored procedures or functions referenced in this parameter’s value. When you use the
Schema Name parameter, then tables, views, stored procedures, or functions referenced in this
parameter’s value are implicitly schema-qualified with that schema name. If tables, views, stored
procedures, or functions referenced in this parameter’s value are located in a different schema than
the implicit schema, they must be schema-qualified.
“BNF” on page 82
“Generation or Retrieval Method” on page 82
“Retrieval Timing” on page 84
BNF
The BNF (Backus Naur Form (http://cui.unige.ch/db-research/Enseignement/analyseinfo/
AboutBNF.html)) notation for this parameter’s value is the following:
Assuming the existence of a table named usr and a view named view_usr where the Identity Vault is
the authoritative source of primary key values, this parameter’s value would be similar to the
following:
usr(none); view_usr(none)
When you use this method, we recommend mapping GUID rather than CN to a parent table or view’s
primary key column.
Driver: This method assumes that the driver is the authoritative source of primary key values for the
specified parent table or view.
When prototyping or in the initial stages of deployment, it is often desirable to have the Subscriber
channel generate primary key values before a stored procedure or function is written. You can also
use this method against databases that do not support stored procedures or functions. When you use
this method in a production environment, however, all SQL statements generated by an <add> event
should be contained in a serializable transaction. For additional information, refer to “Transaction
Isolation Level” on page 69.
Instead of making all transactions serializable, you can also set individual transaction isolation levels
by using embedded SQL attributes. For additional information, refer to “Transaction Isolation Level”
on page 140.
For any numeric column types, the Subscriber channel uses the following to generate primary key
values:
For string column types, the Subscriber channel generates a value by using the return value of
System.CurrentTimeMillis(). Other data types are not supported.
Assuming the existence of a table named usr and a view named view_usr, where the database is
the authoritative source of primary key values, this parameter’s value would be similar to the
following:
usr(driver); view_usr(driver)
When you use this method, we recommend that you omit primary key columns from Schema
Mapping policies and channel filters.
Auto: This method assumes that the database is the authoritative source of primary key values for
the specified parent table or view.
Some databases support identity columns that automatically generate primary key values for inserted
rows. This method retrieves auto-generated primary key values through the JDBC 3 interface method
java.sql.Statement.getGeneratedKeys():java.sql.ResultSet. The MySQL Connector/J
JDBC driver is the only supported third-party JDBC driver that currently implements this method. See
“MySQL Connector/J JDBC Driver” on page 178.
Assuming the existence of a table named usr and a view named view_usr, where the database is
the authoritative source of primary key values, this parameter’s value would be similar to the
following:
When you use this method, we recommend that you omit primary key columns from Schema
Mapping policies and channel filters.
Assuming
The existence of a table named usr with a primary key column named idu
A view named view_usr with a primary key values named pk_idu
The existence of a database function func_last_usr_idu and stored procedure
sp_last_view_usr_pk_idu that both return the last generated primary key value for their
respective table/view
usr("?=func_last_usr_idu()"); view_usr("sp_last_view_usr_pk_idu(pk_idu)")
In the previous examples, a parameter is passed to the stored procedure. Parameters can also be
passed to functions, but this is not usually necessary. Unlike functions, stored procedures usually
return values through parameters. For stored procedures, primary key columns must be passed as IN
OUT parameters. Non-key columns must be passed as IN parameters.
For both stored procedures and functions, parameter order, number and data type must correspond
to the order, number and data type of the parameters expected by the procedure or function.
When you use this method, we recommend that you omit primary key columns from Schema
Mapping policies and channel filters.
Retrieval Timing
The Retrieval Timing parameter specifies when primary key values are retrieved.
An <add> event always results in at least one INSERT statement against a parent table or view. This
portion of this parameter specifies when primary key values are to be retrieved relative to the initial
INSERT statement.
Before: This is the default setting. When this setting is specified, primary key values are retrieved
before the initial INSERT statement.
This retrieval timing is supported for all generation/retrieval methods except auto. Retrieval timing is
required for the none method.
After: When this setting is specified, primary key values are retrieved after the initial INSERT
statement.
This retrieval timing is supported for all generation/retrieval methods except none. Retrieval timing is
required for the auto method.
The following examples augment the previous ones by adding retrieval timing information:
Property Value
Required? no
Schema-Dependent True
Publication Parameters
The following table summarizes publisher-level parameters and their properties:
1
Required for triggered publication mode. 2 These parameters are mutually exclusive.
Uncategorized Parameters
“Disable Publisher?” on page 86
“Disable Statement-Level Locking?” on page 87
“Publication Mode” on page 87
“Enable Future Event Processing?” on page 87
Disable Publisher?
The Disable Publisher? parameter specifies whether the Publisher channel is disabled. When
disabled, the Publisher channel does not query for database events. Unlike the Disable Subscriber?
parameter, you can still issue database queries on the Publisher channel to facilitate alternative
publication algorithms.
When this parameter is set to Boolean True, the Publisher channel is disabled. When this parameter
is set to Boolean False, the Publisher channel is active.
Property Value
Required? no
Schema-Dependent True
When this parameter is set to Boolean True, database resources are explicitly locked. When this
parameter is set to Boolean False, database resources are not explicitly locked.
Property Value
Required? no
Schema-Dependent True
Publication Mode
The Publication Mode parameter specifies which publication algorithm is used.
When set to 1 (triggered), the Publisher channel polls the event log table for events. When set to 2
(triggerless), the Publisher channel searches all tables/views in the synchronization schema for
changes, and synthesizes events.
Property Value
Required? no
Schema-Dependent True
When this parameter is set to Boolean False, rows in the event log table are published by order of
insertion. When this parameter is set to Boolean True, rows in the event log table are published
chronologically.
Database local time is published as an attribute on each XDS event (for example, add, modify,
delete). The attribute name is jdbc:database-local-time, where the jdbc namespace prefix is
bound to urn:dirxml:jdbc. The format is the Java string representation of a java.sql.Timestamp:
yyyy-mm-dd hh:mm:ss.fffffffff. Depending upon the value of the Time Syntax parameter, the
value indicating when an event should be processed can be published as an integer, as a canonical
string, or as a Java string. See “Time Syntax” on page 57.
Regardless of the publication syntax, this value can be parsed and compared to the database local
time value. The following table maps the time syntax to the appropriate parse method.
After both time values are in a common Timstamp object representation, they can be compared by
using the following methods:
com.novell.nds.dirxml.driver.jdbc.db.TimestampUtil.before(java.sql.Timestamp,
java.sql.Timestamp):boolean
com.novell.nds.dirxml.driver.jdbc.db.TimestampUtil.after(java.sql.Timestamp,
java.sql.Timestamp):boolean
An example policy is provided in Appendix L, “Policy Example: Triggerless Future Event Processing,”
on page 227.
When this parameter is set to Boolean True, local database time is published with each event. When
this parameter is set to Boolean False, this information is omitted.
Property Value
Required? no
Schema-Dependent True
The table specified here must conform to the definition of Chapter 11, “The Event Log Table,” on
page 121.
When using “Table/View Names” on page 64, you should explicitly schema-qualify this table name.
When you use “Schema Name” on page 63, this table name is implicitly schema-qualified with that
schema name. If this table is located in a schema other than the implicit schema, it must be schema-
qualified.
Property Value
Required? no
Schema-Dependent True
When this parameter is set to a Boolean True, processed rows are deleted. When this parameter is
set to Boolean False, processed row’s status field values are updated.
To mitigate the performance hit caused when processed rows remain in the event log table, we
recommend periodically moving the rows into a history table. Do one of the following:
Call a clean-up stored procedure via the parameter “Post Polling Statements” on page 93.
Place a before-delete trigger on the event log table to intercept delete events executed against
the event log table and to move deleted rows to a history table before they are deleted from the
event log table.
Property Value
Required? no
Schema-Dependent True
Setting this parameter to Boolean False degrades publication performance unless processed rows
are periodically removed from the event log table.
Allow Loopback?
The Allow Loopback? parameter specifies whether events caused by the driver’s database user
account should be published.
When this parameter is set to Boolean True, loopback events are published. When this parameter is
set to Boolean False, loopback events are ignored.
Property Value
Required? no
Schema-Dependent True
Setting this parameter to Boolean True might degrade performance because extraneous events
might be published.
Setting Result
Property Value
Required? no
Legal Values 1 (resync all objects) 2 (process future changes only) 3 (process all
changes)
Schema-Dependent True
Changing anything in the Authentication Context parameter other than URL properties forces a
resynchronization of all objects when triggerless publication is used.
Changing the value of the Schema Name parameter or the Table/View Names parameter forces
a resynchronization of all objects when triggerless publication is used.
Changing the State Directory parameter value.
Moving or deleting state files. See “Changes That Can Force Triggerless Publisher
Resynchronization” on page 59.
Changing the table/view structure in the database (in particular, changing the position or type of
key columns).
Polling Parameters
“Polling Interval (In Seconds)” on page 92
“Publication Time of Day” on page 92
“Post Polling Statements” on page 93
“Batch Size” on page 93
“Query Limit (default 10000)” on page 94
“Heartbeat Interval (In Minutes)” on page 94
Property Value
Required? no
Schema-Dependent True
Property Value
Required? no
Sample Value (Multiple times) 13:00:00 (1 PM), 16:00:00 (4 PM), 20:00:00 (8PM)
Schema-Dependent True
This parameter overrides the parameter Polling Interval (In Seconds). See “Polling Interval (In
Seconds)” on page 92.
The primary purpose of this parameter is to allow cleanup of the event log table following publication
activity.
You should explicitly schema-qualify any database objects (for example, tables, stored procedures,
and functions) referenced in these statements.
Property Value
Required? no
Delimiters semicolon
Schema-Dependent True
Batch Size
The Batch Size parameter specifies how many events are sent in a single publication document.
Larger batches necessitate fewer trips across the network in both directions.
More events in a single document require fewer trips from the Publisher channel to the Identity
Manager engine (assuming that query-back events are not being used).
Larger batches minimize the number of trips from the Publisher channel to the database
(assuming that the third-party JDBC driver and database support batch processing).
Larger batches require fewer commits to state files in the local file system.
Commits can also be costly.
This parameter defines an upper bound. The Publisher channel might override the specified value
under certain conditions. The upper bound of 128 was chosen to minimize the likelihood of
overflowing the Java heap and to mitigate delaying termination of the Publisher thread on driver
shutdown.
Property Value
Required? no
Default Value 1
Schema-Dependent True
Property Value
Required? yes
Schema-Dependent False
Property Value
Required? no
Default Value 0
Schema-Dependent False
Level Description
1 Minimal tracing
2 Database properties
4 Verbose output
7 Third-party driver
The following table lists the recommended settings for maximum driver compatibility. These settings
are useful when you use an unsupported third-party driver during initial configuration.
Place the jar file in the specific directory path for the platform being used. For information on placing
the jar files, refer to “Supported Third-Party Jar File Placement” on page 172.
The following sections provide information to help you upgrade an existing driver:
What’s New
What’s New in Version 4.2.1.0
This version of the driver does not provide any new features.
Identity Manager 4.7 provides support for MapDB 3.0.5. To ensure that your driver works
correctly with Identity Manager 4.7 engine, see “Working with MapDB 3.0.5” on page 98.
The driver now supports the Subscriber Service channel. This channel enables you to separately
process the out-of-band queries without interrupting the normal flow of cached events. For
example, the Subscriber Service channel can separately process code map refresh, data
collection, and queries triggered from dxcmd. This helps to improve the performance of the
driver. For more information, see Improving Driver Performance Using Subscriber Service
Channel in the NetIQ Identity Manager Driver Administration Guide.
“Understanding Identity Manager 4.7 Engine Support for Driver Versions” on page 98
“Manually Removing the MapDB Cache Files” on page 98
where * is the name of the state cache file. For example, jdbc_<driver instance guid>_0 or
jdbc_<driver instance guid>_1.t
This action ensures that your driver works correctly with Identity Manager 4.7 engine.
NOTE: Prior to Identity Manager 4.x, the extension of driver state files was <tao number>.db or .lg.
Before starting the upgrade process, ensure that you have taken a back-up of the current driver
configuration.
2g Click Apply.
2h (Conditional) Fill in the fields with appropriate information to upgrade the package, then click
Next.
Depending on which package you selected to upgrade, you must fill in the required
information to upgrade the package.
2i Read the summary of the packages that will be installed, then click Finish.
2j Review the upgraded package, then click OK to close the Package Management page.
For detailed information, see the Upgrading Installed Packages in the NetIQ Designer for
Identity Manager Administration Guide.
1 Stop the driver instance by using iManager, Designer, or dxcmd by performing one of the
following actions:
If the driver is running locally, stop the driver instance and the Identity Vault.
If the driver is running with a Remote Loader instance, stop the driver and the Remote
Loader instance.
For example, go to a command prompt on Linux and run ndsmanage stopall
2 Download the driver patch file to a temporary folder on your server.
3 Extract the contents of the driver patch file.
As you work with the JDBC driver, there are a variety of management tasks you might need to
perform, including the following:
Because these tasks, as well as several others, are common to all Identity Manager drivers, they are
included in one reference, the NetIQ Identity Manager Driver Administration Guide.
High-Level View
The following table shows a high-level view of how the driver maps NetIQ Identity Vault objects to
database objects.
Tree Schema
Class Table/View
Attribute Column
The name of a logical database class is the name of the parent table or view.
Indirect Synchronization
In an indirect synchronization model, the driver maps the following:
Classes Tables
Attributes Columns
and
or
1 John Doe
idu=1,table=usr,schema=indirect
The case of database identifiers in association values is determined dynamically from database
metadata at runtime.
Parent table columns are implicitly prefixed with the schema name and name of the parent table. It is
not necessary to explicitly table-prefix parent table columns. For example, indirect.usr.fname is
equivalent to fname for schema mapping purposes.
Large binary and string data types should usually be mapped to parent table columns. To map to a
child table column, data types must be comparable in SQL statements. Large data types usually
cannot be compared in SQL statements.
Large binary and string data types can be mapped to child table columns if the following occur:
The following example shows the relationship between parent table usr and child tables usr_phone
and usr_faxno:
The first constrained column in a child table identifies the parent table. In the above example, the
constrained column in child table usr_phone is idu. The only purpose of this column is to relate
tables usr_phone and usr. Because constrained columns do not contain any useful information, omit
them from publication triggers and Schema Mapping policies.
The unconstrained column is the column of interest. It represents a single, multivalue attribute. In the
above example, the unconstrained columns are phoneno and faxno. Because unconstrained
columns can hold multiple values, they are ideal for mapping multivalue eDirectory attributes (for
example, mapping the multivalue eDirectory attribute Telephone Number to usrphone.phoneno).
idu phoneno
1 111-1111
1 222-2222
Like parent table columns, child table columns are implicitly schema-prefixed. Unlike parent table
columns, however, a child table column name must be explicitly prefixed with the child table name (for
example, usr_phone.phoneno). Otherwise, the driver implicitly interprets column phoneno (the parent
table column) as usr.phoneno, not the child table column usr_phone.phoneno.
Referential Attributes
You can represent referential containment in the database by using foreign key constraints.
Referential attributes are columns within a logical database class that refer to the primary key
columns of parent tables in the same logical database class or those of other logical database
classes.
The first constrained column in a child table determines which logical database class the child table
grp_member belongs to. In the above example, grp_member is considered to be part of logical
database class grp. grp_member is said to be a proper child of grp. The second constrained column
in a child table is the multivalue referential attribute.
In the following example, the order of the constrained columns has been reversed so that
grp_member is part of class usr. To more accurately reflect the relationship, table grp_member has
been renamed to usr_mbr_of.
In databases that have no awareness of column position (such as DB2/AS400), order is determined
by sorting column names by string or hexadecimal value. For additional information, see “Sort
Column Names By” on page 76.
In practice, when you synchronize User and Group classes, we recommend that you synchronize the
Group Membership attribute of class User instead of the Member attribute of class Group.
Synchronizing the group memberships of a user is usually more efficient than synchronizing all
members of a group.
Direct Synchronization
In a direct synchronization model, the driver maps the following:
Classes Views
Class View
The update capabilities of views vary between databases. Most databases allow views to be updated
when they are comprised of a single base table. (That is, they do not join multiple tables.) If views are
read-only, they cannot be used for subscription. Some databases allow update logic to be defined on
views in instead-of-triggers, which allow a view to join multiple base tables and still be updateable.
For a list of databases that support instead-of-triggers, see “Database Features” on page 158.
Instead-of-trigger logic can be simulated, regardless of database capability using embedded SQL.
See “Virtual Triggers” on page 138.
For example, to identify to the driver which fields to use when constructing association values, place
a primary key constraint on a parent table. The corollary to this for a view is to prefix one or more
column names with pk_ (case-insensitive).
The following table lists the constraint prefixes that can be embedded in view column names.
sv_ single-value
mv_ multivalue
The following example views contain all of these constraint prefixes. These are examples and not the
actual samples. Therefore, they should not be used in the driver implementation. The real samples
are bundled with the Identity Manager media.
BNF
The BNF (Backus Naur Form (http://cui.unige.ch/db-research/Enseignement/analyseinfo/
AboutBNF.html)) notation for view column meta-identifiers:
Normalized Forms
By default, all view column names are single-valued. Therefore, explicitly specifying the sv_ prefix in
a view column name is redundant. For example, sv_fname and fname are equivalent forms of the
same column name.
Database native form is the column name as declared in the database. This form is usually much
more verbose than schema mapping form, and contains all necessary meta information.
Schema mapping form
Schema mapping form is returned when the driver returns the application schema. This form is
much more concise than database native form because much of the meta information included
in database native form is represented in XDS XML and not in the identifier.
The referential prefixes pk_ and fk_ are the only meta information preserved in schema
mapping form. This limitation ensures backward compatibility.
pk_idu pk_idu
sv_fname fname
mv_phoneno phoneno
fk_mv__idg__mbr_of fk_mbr_of
Equivalent Forms
A view column name without meta information is called its “effective” name, which is similar to a
directory object’s “effective” rights. For the driver, view column name equivalency is determined
without respect to meta information by default. For example, pk_idu is equivalent to idu, and
fk_mv__idg__mbr_of is equivalent to mbr_of. Any variant form of a view meta column identifier can
be passed to the driver at runtime. For backward compatibility reasons, meta information can be
treated as part of the effective view column name. See “Enable Meta-Identifier Support?” on page 73.
Schema Mapping
Schema mapping conventions for views and view columns are equivalent to that used for parent
tables and parent table columns.
When the Identity Vault is the authoritative source of primary key columns, include the columns in the
Subscriber filter and Schema Mapping policies, but omit the columns from the Publisher filter and
publication triggers. Also, GUID rather than CN is recommended for use as a primary key. CN is a
multivalue attribute and can change. GUID has a single value and is static.
The driver implements the Most Recently Touched (MRT) algorithm with regard to single-value parent
table or view columns. An MRT algorithm ensures that the most recently added attribute value or
most recently deleted attribute value is stored in the database. The algorithm is adequate if the
attribute in question has a single value.
If the attribute has multiple values, the algorithm has some undesirable consequences. When a value
is deleted from a multivalue attribute, the database field it is mapped to is set to NULL and remains
NULL until another value is added. The preferred solution to this undesirable behavior is to extend the
eDirectory schema so that only single-value attributes are mapping to parent table or view columns.
For indirect synchronization, map each multivalue attribute to its own child table.
<modify> 1 parent table update statement for each single value <add-
value> or <remove-value> element.
1 child table insert statement for each multivalue <add-
value> element.
1 child table delete statement for each <remove-value>
element.
The event log table stores publication events. This section describes the structure and capabilities of
the event log table.
You can customize the name of the event log table and its columns to avoid conflicts with reserved
database keywords. The order, number, and data types of its columns, however, are fixed. In
databases that are unaware of column position, order is determined by the Sort Column Names By
parameter. See “Sort Column Names By” on page 76.
Events in this table can be ordered either by order of insertion (the record_id column) or
chronologically (the event_time column). Ordering events chronologically allows event processing to
be delayed. To order publication events chronologically, set the Enable Future Event Processing
parameter to Boolean True. See “Enable Future Event Processing?” on page 87.
record_id
The record_id column is used to uniquely identify rows in the event log table and order publication
events. This column must contain sequential, ascending, positive, unique integer values. Gaps
between record_id values no longer prematurely end a polling cycle.
table_key
Format values for this column are exactly the same in all triggers for a logical database class. The
BNF or Backus Naur Form (http://cui.unige.ch/db-research/Enseignement/analyseinfo/
AboutBNF.html) of this parameter is defined below:
For example, for the usr table referenced throughout this chapter, this column’s value might be
idu=1.
For the view_usr view referenced throughout this chapter, this column’s value might be pk_empno=1.
For a hypothetical compound primary key (one containing multiple columns), this column’s value
might be pkey1=value1+pkey2=value2.
If primary key values placed in the table_key field contain any of the special characters {, ; ' + " = \ <
>}, where { and } contain the set of special characters, delimit the value with double quotes. You also
need to escape the double quote character " as \" and the literal escape character \ as \\ when
they are contained inside a pair of double quotes.
For a hypothetical primary key containing special characters, this column’s value might be pkey=", ;
' + \" = \\ < >". (Note the double quotes and escaped characters.)
Differences in padding or formatting might result in out-of-order event processing. For performance
reasons, remove any unnecessary white space from numeric values. For example, idu=1 is
preferred over idu= 1.
status
The status column indicates the state of a given row. The following table lists permitted values:
N new
S success
W warning
E error
F fatal
To be processed, all rows inserted into the event log table must have a status value of N. The
remainder of the status characters are used solely by the Publisher channel to designate processed
rows. All other characters are reserved for future use.
event_type
Values in this column must be between 1 and 8. All other numbers are reserved for future use.
1 insert field
2 update field
4 delete row
For additional information on this field, see “Event Types” on page 124.
event_time
This column serves as an alternative ordering column to record_id. It contains the effective date of
the event. It must not be NULL. For this column to become the ordering column, set the Enable Future
Event Processing parameter to Boolean True. See “Enable Future Event Processing?” on page 87.
perpetrator
This column identifies the database user who instigated the event. A NULL value is interpreted as a
user other than the driver user. Rows with a NULL value or value not equal to the driver’s database
username are published. Rows with a value equal to the driver’s database username are not
published unless the Allow Loopback Publisher parameter is set to Boolean True. See “Allow
Loopback?” on page 90.
table_name
The name of the table or view where the event occurred.
column_name
The name of the column that was changed. This column is used only for per-field (1-3, 7-8) event
types. Nevertheless, it must always be present in the event log table. If it is missing, the Publisher
channel cannot start.
old_value
The field’s old value. This column is used only for per-field, non-query-back event types (1-3).
Nevertheless, it must always be present in the event log table. If it is missing, the Publisher channel
cannot start.
Event Types
The following table describes each event type:
1 insert field
2 update field
4 delete row
Event types are in four major categories. Some categories overlap. The following table describes
each category and indicates which event types are members:
Per-field (attribute) 1, 2, 3, 7, 8
Per-row (object) 4, 5, 6
Non-query-back 1, 2, 3, 4
Query-back 5, 6, 7, 8
Per-field, non-query-back 1, 2, 3
Per-field, query-back 7, 8
Per-row, non-query-back 4
Per-row, query-back 5, 6
In general, a combination of event types from each category yields the best trade-off in terms of
space, time, implementation complexity, and performance.
Query-back event types use less space but require more time to process than non-query-back event
types. Non-query-back event types use more space but require less time to process than query-back
event types.
Query-back event types take precedence over their non-query-back counterparts. Non-query-back
events are ignored if a query-back event is logged for the same field or object. For example, if an
event of type 2 (update-field, non-query-back) and 8 (update-field, query-back) are logged on the
same field, the type 2 event is ignored in favor of the type 8 event.
Furthermore, query-back row event types take precedence over query-back field event types. For
example, if an event type 8 (update field, query-back) and a event type 6 (update row query-back) are
logged on the same object, the type 8 event is ignored in favor of the type 6 event.
Query-back events are ignored by the Publisher if the database object no longer exists. They are
dependent upon the database object still being available at processing time. Therefore, logged query-
back adds and modifies (event types 5, 6, 7, 8) have no effect once the database object they refer to
is deleted.
The following table shows the basic correlation between publication event types and the XDS XML
generated by the Publisher channel.
insert <add>
update <modify>
delete <delete>
The following example illustrates XML that the Publisher channel generates for events logged on the
usr table for each possible event type.
The following table shows the initial contents of usr after a new row has been inserted:
The following table shows the current contents of usr after the row has been updated:
Insert Field
The table below shows the contents of the event log table after a new row is inserted into table usr.
The value for column photo has been Base64-encoded. The Base64-encoded equivalent of 0xAAAA
is qqo=.
<add class-name="usr">
<association>idu=1,table=usr,schema=indirect
</association>
<add-attr attr-name="fname">
<value type="string">Jack</value>
</add-attr>
<add-attr attr-name="lname">
<value type="string">Frost</value>
</add-attr>
<add-attr attr-name="photo">
<value type="octet">qqo=</value>
</add-attr>
</add>
Update Field
The following table shows the contents of the event log table after the row in table usr has been
updated. The values for column photo has been Base64-encoded. The Base64-encoded equivalent
of 0xBBBB is u7s=.
Delete Row
The table below shows the contents of the event log table after the row in table usr has been deleted.
<delete class-name="usr">
<association>idu=1,table=usr,schema=indirect
</association>
</delete>
The Publisher channel generates the following XML. The values reflect the current contents of table
usr, not the initial contents.
The Publisher channel generates the following XML. The values reflect the current contents of table
usr, not the initial contents.
<modify class-name="usr">
<association>idu=1,table=usr,schema=indirect
</association>
<modify-attr attr-name="fname">
<remove-all-values/>
<add-value>
<value type="string">John</value>
</add-value>
</modify-attr>
<modify-attr attr-name="lname">
<remove-all-values/>
<add-value>
<value type="string">Doe</value>
</add-value>
</modify-attr>
<modify-attr attr-name="photo">
<remove-all-values/>
<add-value>
<value type="octet">u7s=</value>
</add-value>
</modify-attr>
</modify>
The Publisher channel generates the following XML. The values reflect the current contents of table
usr, not the initial contents.
<add class-name="usr">
<association>idu=1,table=usr,schema=indirect
</association>
<add-attr attr-name="fname">
<value type="string">John</value>
</add-attr>
<add-attr attr-name="lname">
<value type="string">Doe</value>
</add-attr>
<add-attr attr-name="photo">
<value type="octet">u7s=</value>
</add-attr>
</add>
The Publisher channel generates the following XML. The values reflect the current contents of table
usr, not the initial contents.
Events
Embedded SQL allows you to embed SQL statements in XDS-formatted XML documents. You can
use embedded SQL statements along with XDS events or use them alone. When embedded SQL
statements are used alone, embedded SQL processing does not require that the driver know
anything about tables/view in the target database. Therefore, the driver can run in schema-unaware
mode. See “Synchronization Filter” on page 61. When using embedded SQL alone, you must
establish associations manually. The driver won’t establish them for you.
When used in conjunction with XDS events, embedded SQL can act as a virtual database trigger. In
the same way that you can install database triggers on a table and cause side effects in a database
when certain SQL statements are executed, embedded SQL can cause side effects in a database in
response to certain XDS events.
For examples of each, consult the User DDL Command Transformation style sheet on the Subscriber
channel in the example driver configuration.
Elements
SQL is embedded in XDS events through the <jdbc:statement> and <jdbc:sql> elements. The
<jdbc:statement> element can contain one or more <jdbc:sql> elements.
Namespaces
The namespace prefix jdbc used throughout this section is implicitly bound to the namespace
urn:dirxml:jdbc when referenced outside of an XML document.
You must use namespace-prefixed embedded SQL elements and attributes. Otherwise, the driver
does not recognize them. In all examples in this section, the prefix used is jdbc. In practice, the prefix
can be whatever you want it to be, as long as it is bound to the namespace value urn:dirxml:jdbc.
The following XML example illustrates how to use and properly namespace-prefix embedded SQL
elements. In the following example, the namespace declaration and namespace prefixes are bolded:
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr">
<add-attr name="lname">
<value>Doe</value>
</add-attr>
</add>
<jdbc:statement>
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' </jdbc:sql>
</jdbc:statement>
</input>
Because the Subscriber channel resolves <add> events to one or more INSERT statements, the XML
shown above resolves to:
Token Substitution
Rather than require you to parse field values from an association, the Subscriber channel supports
token substitution in embedded SQL statements. In the following examples, tokens and the values
they reference are bolded:
<input xmlns:jdbc="urn:dirxml:jdbc">
<modify class-name="usr">
<association>idu=1,table=usr,schema=indirect</association>
<modify-attr name="lname">
<add-value>
<value>DoeRaeMe</value>
</add-value>
</modify-attr>
</modify>
<jdbc:statement>
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' WHERE
idu = {$idu}</jdbc:sql>
</jdbc:statement>
</input>
Token placeholders must adhere to the XSLT attribute value template syntax {$field-name}. Also, the
referenced association element must precede the <jdbc:statement> element in the XDS document,
or must be present as a child of the <jdbc:statement> element. Alternatively, instead of copying the
association element as child of the <jdbc:statement> element, you could copy the src-entry-id of
the element containing the association element onto the <jdbc:statement> element. Both approaches
are bolded in the following examples:
</input>
<input xmlns:jdbc="urn:dirxml:jdbc">
<modify class-name="usr" src-entry-id="0">
<association>idu=1,table=usr,schema=indirect</association>
<modify-attr name="lname">
<add-value>
<value>DoeRaeMe</value>
</add-value>
</modify-attr>
</modify>
<jdbc:statement src-entry-id="0">
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' WHERE
idu = {$idu}</jdbc:sql>
</jdbc:statement>
</input>
The {$field-name} token must refer to one of the naming RDN attribute names in the association
value. The above examples have only one naming attribute: idu.
An <add> event is the only event where an association element is not required to precede embedded
SQL statements with tokens because the association has not been created yet. Additionally, any
embedded SQL statements using tokens must follow, not precede, the <add> event. For example:
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr">
<add-attr name="lname">
<value>Doe</value>
</add-attr>
</add>
<jdbc:statement>
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' WHERE
idu = {$idu}</jdbc:sql>
</jdbc:statement>
</input>
To prevent tracing of sensitive information, you can use the {$$password} token to refer to the
contents of the immediately preceding <password> element within the same document. In the
following example, the password token and the value it refers to are bolded:
Furthermore, you can also refer to the driver’s database authentication password specified by the
Application Password parameter as {$$$driver-password}. See “Application Password” on
page 55. Named password substitution is not yet supported.
Just as with association elements, the referenced password element must precede the
<jdbc:statement> element in the XDS document or must be present as a child of the
<jdbc:statement> element. Alternatively, instead of copying the password element as child of the
<jdbc:statement> element, you could copy the src-entry-id of the element containing the
password element onto the <jdbc:statement> element. Both approaches are bolded in the following
examples:
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr">
<password>some password</password>
<add-attr name="fname">
<value>John</value>
</add-attr>
<add-attr name="lname">
<value>Doe</value>
</add-attr>
</add>
<jdbc:statement>
<password>some password</password>
<jdbc:sql>CREATE USER jdoe IDENTIFIED BY
{$$password}</jdbc:sql>
</jdbc:statement>
</input>
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr" src-entry-id="0">
<password>some password</password>
<add-attr name="fname">
<value>John</value>
</add-attr>
<add-attr name="lname">
<value>Doe</value>
</add-attr>
</add>
<jdbc:statement src-entry-id="0">
<jdbc:sql>CREATE USER jdoe IDENTIFIED BY
{$$password}</jdbc:sql>
</jdbc:statement>
</input>
jdbc:transaction-type
jdbc:transaction-id
jdbc:transaction-type
This attribute has two values: manual and auto. By default, most XDS events of interest (<add>,
<modify>, and <delete>) are implicitly set to the manual transaction type. The manual setting
enables XDS events to resolve to a transaction consisting of one or more SQL statement.
By default, embedded SQL events are set to auto transaction type because some SQL statements,
such as DDL statements, cannot usually be included in a manual transaction. In the following
example, the attribute is in bold text.
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr" jdbc:transaction-type="auto">
<add-attr name="lname">
<value>Doe</value>
</add-attr>
</add>
<jdbc:statement>
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' WHERE
idu = {$idu}</jdbc:sql>
</jdbc:statement>
</input>
SET AUTOCOMMIT ON
INSERT INTO indirect.usr(lname) VALUES('Doe');
-- implicit commit
UPDATE indirect.usr SET fname = 'John' WHERE idu = 1;
-- implicit commit
jdbc:transaction-id
The Subscriber channel ignores this attribute unless the element’s jdbc:transaction-type attribute
value defaults to or is explicitly set to manual. The following XML shows an example of a manual
transaction. The attribute is in bold text.
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr" jdbc:transaction-id="0">
<add-attr name="lname">
<value>Doe</value>
</add-attr>
</add>
<jdbc:statement jdbc:transaction-type="manual"
jdbc:transaction-id="0">
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' WHERE
idu = {$idu}</jdbc:sql>
</jdbc:statement>
</input>
The custom attribute jdbc:isolation-level allows you to adjust the isolation transaction level if
necessary. The java.sql.Connection parameter defines five possible values in the interface. See
java.sql.Connection (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Connection.html).
none
read uncommitted
read committed
repeatable read
serializable
The driver’s default transaction isolation level is read committed unless overridden by a descriptor
file. In manual transactions, place the jdbc:isolation-level attribute on the first element in the
transaction. This attribute is ignored on subsequent elements. In the following example. the attribute
is in bold text.
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr" jdbc:transaction-id="0"
jdbc:isolation-level="serializable">
<add-attr name="lname">
<value>Doe</value>
</add-attr>
</add>
<jdbc:statement jdbc:transaction-type="manual"
jdbc:transaction-id="0">
<jdbc:sql>UPDATE indirect.usr SET fname = 'John'
WHERE idu = {$idu}</jdbc:sql>
</jdbc:statement>
</input>
Statement Type
The Subscriber channel executes embedded SQL statements, but it doesn’t understand them. The
JDBC 1 interface defines several methods for executing different types of SQL statements. The
following table contains these methods:
Some third-party drivers, particularly Oracle’s JDBC drivers, incorrectly implement the methods used
to determine the number of result sets that this method generates. Consequently, the driver can get
caught in an infinite loop leading to high CPU utilization. To circumvent this problem, you can use the
jdbc:type attribute on any <jdbc:statement> element to map the SQL statements contained in it to
the following methods instead of the default method:
java.sql.Statement.executeQuery(String query):java.sql.ResultSet
java.sql.Statement.executeUpdate(String update):int
The jdbc:type attribute has two values: update and query. For INSERT, UPDATE, or DELETE
statements, set the value to update. For SELECT statements, set the value to query. In the absence of
this attribute, the driver maps all SQL statements to the default method. If placed on any element
other than <jdbc:statement>, this attribute is ignored.
Recommendations:
The following XML shows an example of the jdbc:type attribute. The attribute is in bold text.
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr">
<add-attr name="lname">
<value>Doe</value>
</add-attr>
</add>
<jdbc:statement jdbc:type="update">
<jdbc:sql>UPDATE indirect.usr SET fname = 'John'
WHERE idu = {$idu}</jdbc:sql>
</jdbc:statement>
</input>
For example, assume that the table usr has the following contents:
1 John Doe
The XML document below results in an output document containing a single result set.
<input xmlns:jdbc="urn:dirxml:jdbc">
<jdbc:statement jdbc:type="query">
<jdbc:sql>SELECT * FROM indirect.usr</jdbc:sql>
</jdbc:statement>
</input>
<output xmlns:jdbc="urn:dirxml:jdbc">
<jdbc:result-set jdbc:number-of-rows="1">
<jdbc:row jdbc:number="1">
<jdbc:column jdbc:name="idu"
jdbc:position="1"
jdbc:type="java.sql.Types.BIGINT
<jdbc:value>l</jdbc:value>
</jdbc:column>
<jdbc:column jdbc:name="fname"
jdbc:position="2"
jdbc:type="java.sql.Types.VARCHAR>
<jdbc:value>John</jdbc:value>
</jdbc:column>
<jdbc:column jdbc:name="lname"
jdbc:position="3"
jdbc:type="java.sql.Types.VARCHAR>
<jdbc:value>Doe</jdbc:value>
</jdbc:column>
</jdbc:row>
</jdbc:result-set>
<status level="success"/>
</output>
SQL queries always produce a single <jdbc:result-set> element whether or not the result set
contains any rows. If the result set is empty, the jdbc:number-of-rows attribute is set to zero.
You can embed more than one query in a document. SQL queries don’t require that the referenced
tables/views in the synchronization schema be visible to the driver. However, XDS queries do.
If you are building an event to be sent via the Command Processor instead of part of the regular
event flow, you need to build the XML in a nodeset variable and use the Parse XML token before
issuing the command. For more information, see “XML Parse” in the NetIQ Identity Manager - Using
Designer to Create Policies.
NOTE: The queries on the Publisher channel with srcCommandProcessor are scheduled for
execution on the Subscriber channel and the script processing does not wait for the result to become
available.
For example:
Using the jdbc:transaction-id and jdbc:transaction-type attributes to group DML and DDL
statements into a single transaction causes the transaction to be rolled back on most databases.
Because DDL statements are generally executed as separate transactions, it is possible that the
insert statement in the above example might succeed and the create user statement might roll
back.
It is not possible, however, that the insert statement fails and the create user statement succeeds.
The driver stops executing chained transactions at the point where the first transaction is rolled back.
Logical Operations
Because it is not generally possible to mix DML and DDL statements in a single transaction, a single
event can consist of one or more transactions. You can use the jdbc:op-id and jdbc:op-type to
group multiple transactions together into a single logical operation. When grouped in this way, all
members of the operation are handled as a single unit with regard to status. If one member has an
error, all members return the same status level. Similarly, all members share the same status type.
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr" jdbc:op-id="0"
jdbc:op-type="password-set-operation">
<add-attr name="fname">
<value>John</value>
</add-attr>
<add-attr name="lname">
<value>Doe</value>
</add-attr>
<password>Doe{$idu}</password>
</add>
<jdbc:statement jdbc:op-id="0">
<jdbc:sql>CREATE USER jdoe IDENTIFIED BY {$$password}
</jdbc:sql>
</jdbc:statement>
</input>
The jdbc:op-type attribute is ignored on all elements except the first element in a logical operation.
<input xmlns:jdbc="urn:dirxml:jdbc">
<add class-name="usr" jdbc:op-id="0"
jdbc:op-type="password-set-operation">
<add-attr name="fname">
<value>John</value>
</add-attr>
<add-attr name="lname">
<value>Doe</value>
</add-attr>
<password>Doe{$idu}</password>
</add>
<jdbc:statement jdbc:op-id="0">
<jdbc:sql>CREATE USER jdoe IDENTIFIED BY {$$password}
</jdbc:sql>
</jdbc:statement>
</input>
The <add> event is logically bound to the CREATE USER DDL statement by the jdbc:op-id and
jdbc:op-type attributes.
The User DDL Command Transformation style sheet in the example.xml configuration file contains
sample XSLT templates that bind user account creation DDL statements to <add> events for all
databases that support them.
<input xmlns:jdbc="urn:dirxml:jdbc">
<modify-password jdbc:op-id="0"
jdbc:op-type="password-set-operation">
<password>new password</password>
</modify-password>
<jdbc:statement jdbc:op-id="0">
<jdbc:sql>ALTER USER jdoe IDENTIFIED BY {$$password}
</jdbc:sql>
</jdbc:statement>
</input>
NOTE: Some databases, such as Sybase Adaptive Server Enterprise and Microsoft SQL Server,
differentiate between user account names and login account names. Therefore, you might need to
supply the login name instead of the username.
The <modify-password> event is logically bound to the ALTER USER DDL statement by the jdbc:op-
id and jdbc:op-type attributes.
The User DDL Command Transformation style sheet in the example .xml configuration contains
sample XSLT templates that bind password maintenance DDL statements to <modify-password>
events for all databases that support them.
The example .xml configuration file stores database user account names in database fields.
NOTE: Some databases, such as Sybase Adpative Server Enterprise and Microsoft SQL Server,
differentiate between user account names and login account names. Therefore, you might need to
store two names, not just one.
To implement check object password, append a dest-dn attribute value to the <check-object-
password> event. In the following example, the dest-dn attribute is bolded:
<input xmlns:jdbc="urn:dirxml:jdbc">
<check-object-password dest-dn="jdoe">
<password>whatever</password>
</check-object-password>
</input>
</jdbc:statement>
The principle advantage of using the CallableStatement interface is that you do not need to know the
proprietary call syntaxes of each database vendor or JDBC implementation. Other advantages
include the following:
It's much easier to build procedure or function calls in the Policy Builder.
You can differentiate between Null and empty string parameter values.
You can call functions on all database platforms.
Oracle, for instance, doesn't support calling functions by using a statement.
You can retrieve Out parameter values from stored procedure calls.
Literals can be passed only to procedure parameters declared as In or In Out. Passed literals must be
type-compatible with declared procedure parameters.
<jdbc:call-procedure jdbc:name="schema.procedure-name">
<!-- the OUT param place -->
<jdbc:param/>
<!-- the IN param -->
<jdbc:param>
<jdbc:value>literal</jdbc:value>
</jdbc:param>
<jdbc:param>
Also, to facilitate correlation of procedure calls and output parameter values, Out parameters contain
the same event-ID value as the procedure call that generated them. This is particularly useful when
multiple calls are made in the same document.
<output>
<!-- no value element = OUT param returned null or IN param -->
<jdbc:out-parameters event-id="0" jdbc:number-of-params="1">
<jdbc:param/>
</jdbc:out-parameters>
<status event-id="0" level="success"/>
</output>
<output>
<!-- empty value element = returned empty string -->
<jdbc:out-parameters event-id="0" jdbc:number-of-params="1">
<jdbc:param>
<jdbc:value/>
</jdbc:param>
</jdbc:out-parameters>
<status event-id="0" level="success"/>
</output>
<output>
<!-- no-empty value element = returned literal value -->
<jdbc:out-parameters event-id="0" jdbc:number-of-params="2">
<jdbc:param>
<jdbc:value>literal<jdbc:value>
</jdbc:param>
</jdbc:out-parameters>
<status event-id="0" level="success"/>
</output>
Procedure Declaration
This procedure uses Oracle PSQL syntax.
Literals can be passed to function parameters declared as In. Passed literals must be type-
compatible with declared function parameters.
<output>
<jdbc:out-parameters event-id="0" jdbc:number-of-params="1">
<jdbc:param jdbc:name="return value"
Empty Set
Assuming that a function returns no results set or an empty result set, the following output is
generated:
<output>
<jdbc:result-set event-id="0" jdbc:number-of-rows="0"/>
<status event-id="0" level="success"/>
</output>
<output>
<jdbc:result-set event-id="0" jdbc:number-of-rows="1">
<jdbc:row jdbc:number="1">
<jdbc:column jdbc:name="SYSDATE"
jdbc:position="1
jdbc:type="java.sql.Types.TIMESTAMP">
<jdbc:value>2007-01-03 14:52:20.0</jdbc:value>
</jdbc:column>
</jdbc:row>
</jdbc:result-set>
<status event-id="0" level="success"/>
</output>
<output>
<jdbc:result-set event-id="0" jdbc:number-of-rows="0"/>
<jdbc:result-set event-id="0" jdbc:number-of-rows="0"/>
<status event-id="0" level="success"/>
</output>
jdbc:return-format
This attribute can be placed on the jdbc:call-function element to format the first row of a returned
results set as stored procedure Out parameters of the result.
<input>
<jdbc:statement>
<jdbc:call-function jdbc:name="schema.function-name"
jdbc:return-format="return value">
</jdbc:call-function>
</jdbc:statement>
</input>
jdbc:return-type
This attribute can be placed on the jdbc:call-function element to allow Oracle functions to return a
result set.
<input>
<jdbc:statement>
<jdbc:call-function jdbc:name="schema.function"
jdbc:return-type="OracleTypes.CURSOR">
</jdbc:call-function>
</jdbc:statement>
</input>
Function Declaration
This declaration is for Oracle PSQL syntax.
Best Practices
For performance reasons, it is better to call a single stored procedure/function that contains multiple
SQL statements than to embed multiple statements in an XDS document.
The syntax used to call stored procedures or functions varies by database. For additional information,
see “Syntaxes for Calling Stored Procedures and Functions” on page 160.
Database Interoperability
The Identity Manager Driver for JDBC is designed to inter-operate with a specific set of JDBC driver
implementations, instead of a specific set of databases. Consequently, the list of supported
databases is primarily driven by the capabilities of supported third-party JDBC drivers. A secondary
factor is testing resources.
Supported Databases
The following databases or database versions have been tested and are recommended for use with
this product:
Microsoft SQL Server 2008, 2008 R2, 2012, 2014, 2016, and 2017
5.6.x or later
9.5.x or later
9.6.x or later
10.x or later
9.6.3
MariaDB 10.2.13
Database Characteristics
“Database Features” on page 158
“Current Time Stamp Statements” on page 159
“Syntaxes for Calling Stored Procedures and Functions” on page 160
“Left Outer Join Operators” on page 160
“Undelimited Identifier Case Sensitivity” on page 161
“Supported Transaction Isolation Levels” on page 161
“Commit Keywords” on page 162
“IBM DB2 Universal Database (UDB)” on page 162
“Informix Dynamic Server (IDS)” on page 163
“Microsoft SQL Server” on page 164
“MySQL/MariaDB” on page 165
“Oracle” on page 166
“PostgreSQL” on page 167
“Sybase Adaptive Server Enterprise (ASE)” on page 167
Database Features
Table 13-2 Database Features
IBM DB2 Y Y Y N Y1 Y1 Y Y
UDB 9.x
Informix Y Y Y2 N Y3 Y Y Y
IDS 11.x
MS SQL Y Y Y N Y Y Y Y
2008,
2008 R2,
2012,
2014, and
2016
MySQL Y Y Y4 N Y Y Y N
5.5.x and
5.6.x
Oracle Y Y N Y Y Y Y Y
11g and
12c
Postgres Y Y Y5 Y Y Y Y6 Y6
8.4.x,
9.0.x, and
9.6.3
Sybase Y Y Y N Y N Y N
ASE 15.0
MariaDB Y Y Y4 N Y Y Y N
10.2.13
1
DB2 natively supports stored procedures or functions written in Java. To write procedures by using
the native SQL procedural language, install a C compiler on the database server.
2
The Informix identity column keyword is SERIAL8.
3 Informix stored procedures cannot return values through OUT parameters.
4 The identity column keyword is AUTO_INCREMENT for MySQL and MariaDB.
5
You can use a PostgreSQL sequence object to provide default values for primary key columns,
effectively simulating an identity column.
6
PostgreSQL has a native construct called rules. This construct can be used to effectively simulate
triggers and instead-of-triggers. It also supports the use of triggers or instead-of-triggers written in a
variety of procedural programming languages.
1
Oracle’s JDBC implementation does not support calling functions as a string.
Sybase ASE *= No
Database Case-Sensitive?
IBM DB2 No
UDB
Informix IDS No
MSSQL No
MySQL/ Yes
MariaDB
Oracle No
PostgreSQL No
1
This is the default isolation level for this database. 2 Can be set, but it is aliased to a supported
isolation level.
Commit Keywords
The following table identifies the commit keywords for supported databases:
MSSQL GO
MySQL/ COMMIT
MariaDB
Oracle COMMIT
PostgreSQL COMMIT
Sybase ASE GO
1 For logging and ANSI-compliant databases. Non-logging databases do not support transactions.
Property Value
Case-Sensitive? No
Dynamic Defaults
The following table lists database compatibility parameters that the JDBC driver implicitly sets at
runtime. Do not explicitly override these settings.
Known Issues
The timestamp format is proprietary. See “Known Issues” on page 168.
Property Value
Case-Sensitive? No
1 For logging and ANSI-compliant databases. Nonlogging databases do not support transactions.
Dynamic Defaults
The following table lists database compatibility parameters that the JDBC driver implicitly sets at
runtime. Do not explicitly overwrite these settings.
Known Issues
NUMERIC or DECIMAL columns cannot be used as primary keys unless the scale (the number of
digits to the right of the decimal point) is explicitly set to 0 when the table is created. By default,
the scale is set to 255.
DBAs cannot grant privileges to objects they don’t own.
Property Value
Case-Sensitive? No
Commit Keyword GO
Dynamic Defaults
The following table lists database compatibility parameters that the JDBC driver implicitly sets at
runtime. Do not explicitly overwrite these settings.
MySQL/MariaDB
“Database Properties” on page 165
“Dynamic Defaults” on page 166
“Known Issues” on page 166
Database Properties
Property Value
Case-Sensitive? Yes
Known Issues
TIMESTAMP columns, when they are updated after being initially set to 0 or NULL, are always set
to the current date and time. To compensate for this behavior, we recommend that you map
Identity Vault Time and Timestamp syntaxes to DATETIME columns.
Oracle
“Database Properties” on page 166
“Dynamic Defaults” on page 166
“Limitations” on page 167
Database Properties
Property Value
Case-Sensitive? No
Dynamic Defaults
The following table lists database compatibility parameters that the JDBC driver implicitly sets at
runtime. Do not explicitly overwrite these settings.
The default exclusion filter omits dropped tables from the synchronization schema.
Limitations
LONG, LONG RAW, and BLOB columns cannot be referenced in a trigger. You can’t reference columns of
these types by using the :NEW qualifier in a trigger, including instead-of-triggers.
PostgreSQL
“Database Properties” on page 167
“Known Issues” on page 167
Database Properties
Property Value
Case-Sensitive? No
Known Issues
PostgreSQL does not support <check-object-password> events. You control authentication by
manually inserting entries into the pg_hba.conf file.
Property Value
Case-Sensitive? Yes
Commit Keyword GO
Dynamic Defaults
The following table lists database compatibility parameters that the JDBC driver implicitly sets at
runtime. Do not explicitly overwrite these settings.
Known Issues
Padding and truncation of binary values.
To ensure ANSI-compliant padding and truncation behavior for binary values, make sure that
binary column types (other than IMAGE) meet the following criteria:
They are exactly the size of the eDirectory™ attribute that maps to them.
They are constrained NOT NULL.
They are added to the Publisher and Subscriber Creation policies.
If they are constrained NULL, trailing zeros, which are significant to eDirectory, are truncated. If
binary columns exceed the size of their respective eDirectory attributes, extra 0s are appended
to the value.
The recommended solution is to use only the IMAGE data type when synchronizing binary values.
DATETIME fractions of a second are rounded. Sybase Timestamps are at best accurate to 1/300th
of a second (approximately.003 seconds). The database server rounds to the nearest 1/300th of
a second as opposed to the nearest 1/1000th of a second (.001 seconds or 1 millisecond).
Timestamp formats are proprietary.
We strongly recommend that you use the third-party JDBC drivers supplied by major enterprise
database vendors whenever possible, such as those listed in “Supported Third-Party JDBC Drivers
(Recommended)” on page 170. They are usually free, mature, and known to interoperate well with
the JDBC driver and the databases they target. You can use other third-party drivers, but NetIQ does
not support them.
In general, most third-party drivers are backward compatible. However, even if they are backward
compatible, they are generally not forward compatible. Anytime a database server is upgraded, the
third-party driver used with this product should probably be updated as well.
Also, as a general rule, we recommend that you use the latest version of a third-party driver, unless
otherwise noted.
Driver Types
There are four types of third-party drivers:
Type 1: A third-party JDBC driver that is partially Java and communicates indirectly with a
database server through a native ODBC driver.
Because Identity Manager uses a directory as its datastore, and because databases are usually
significantly faster than directories, performance isn’t a primary concern. Stability, however, is an
issue. For this reason, we recommend that you use a type 3 or 4 third-party JDBC driver whenever
possible.
Because third-party code is being executed within the environment, it is recommended to always use
the Remote Loader to execute third-party code on its own to ensure the integrity of the directory
process. This also makes upgrades of the shim or third-party code simple and safe because the
directory does not need to be restarted.
Additional drivers are supported but not recommended. For a list of these drivers, see “Supported
Third-Party JDBC Drivers (Not Recommended)” on page 184.
Informix No No
Informix jdbc:informix-sqli://ip-address:1526/database-
name:informixserver=server-id
jTDS jdbc:jtds:sqlserver://ip-address/database-name
cdb - jdbc:oracle:thin:@ip-address:1521/<service>
PostgreSQL jdbc:postgresql://ip-address:5432/database-name
This information is used in conjunction with the Authentication Context parameter. For information on
this parameter, see “Authentication Context” on page 54.
Informix com.informix.jdbc.IfxDriver
jTDS net.sourceforge.jtds.jdbc.Driver
PostgreSQL org.postgresql.Driver
This information is used in conjunction with the JDBC Driver Class Name parameter. For information
on this parameter, see “Third-Party JDBC Driver Class Name” on page 57.
Windows novell\NDS\lib
Windows novell\RemoteLoader\lib
Type 4
or
file:///database-installation-directory/java
Unlike the type 3 driver, the type 4 driver has only a minimal set of defined error codes. This absence
inhibits the JDBC driver’s ability to distinguish between connectivity, retry, authentication, and fatal
error conditions.
Compatibility
The IBM DB2 driver is backward compatible. Database server updates are frequent. Driver updates
are infrequent.
Security
The IBM DB2 driver supports a variety of authentication security mechanisms but does not support
encrypted transport.
Known Issues
It’s very difficult to diagnose and remedy Java-related errors on the database server.
Numerous error conditions and error codes can arise when you attempt to install and execute user-
defined stored procedures and functions written in Java. Diagnosing these can be time consuming
and frustrating. A log file (db2diag.log on the database server) can often provide additional
debugging information. In addition, all error codes are documented and available online.
Driver Information
Type 4
Compatibility
The Informix driver is backward compatible. Database server updates and driver updates are
infrequent.
Security
The Informix driver does not support encrypted transport.
Known Issues
Schema names cannot be used to retrieve metadata against an ANSI-compliant database. Set
the driver compatibility parameter “Supports Schemas in Metadata Retrieval?” on page 75 to
Boolean False. The database objects available for metadata retrieval are those visible to the
database user who authenticated to the database. Schema qualifiers cannot be used to identify
database objects. Therefore, to avoid naming collisions (such as owner1.table1, owner2.table1),
give the database authentication user only SELECT privileges on objects being synchronized.
When used against ANSI-compliant databases, usernames must be in uppercase. Set the driver
compatibility parameter “Force Username Case” on page 73 to upper.
Supported Database Versions: Microsoft SQL Server 2012 Service Pack 3 and later, Microsoft SQL
Server 2014 Service Pack 2, Microsoft SQL Server 2016 Service Pack
1
Type 4
Filenames sqljdbc42.jar
Compatibility
The Microsoft JDBC driver works with all supported versions of Microsoft SQL Server.
Security
The Microsoft JDBC driver supports encrypted transport.
NOTE: For more information on SSL encryption, see Connection String Options page.
URL Properties
Delimit URL properties by using a semicolon (;).
The following table lists values for the integratedSecurity URL property for JDBC driver for SQL
Server.
Supported Database Versions: Microsoft SQL Server 2005 Service Pack 1 or later, 2008 and 2008 R2,
Sybase Adaptive Server Enterprise (ASE) 15 or later
jdbc:jtds:sybase://ip-address/database-name
Filenames jtds-<version>.jar
Limitations
The jTDS JDBC driver does not support views or stored procedures. NetIQ Corporation recommends
that you use the Microsoft 2000 JDBC driver when Subscribing to views.
Compatibility
The jTDS driver works with all versions of Microsoft SQL Server. It also supports all versions of
Sybase ASE, but it has not been tested by NetIQ against that database server yet. Driver updates are
infrequent.
Security
The jTDS driver supports encrypted transport.
URL Properties
Delimit URL properties by using a semicolon (;).
The following table lists values for the domain URL property for the jTDS driver.
<any-domain-name> When a domain name is specified, either NTLM or SSO authentication can be
used. NTLM authentication is selected when a username and password are
supplied. SSO authentication is selected when a username and password are
not supplied.
The following table lists values for the SSL URL property for the jTDS driver.
require SSL is required. An exception is thrown if the server doesn’t support it.
authenticate SSL is required. An exception is thrown if the server doesn’t support it. In
addition, the server’s certificate must be signed by a trusted certificate
authority.
Driver Information
Type 4
Download Instructions Download and extract. The jar file is located in the extract-dir/mysql-
connector-java-version directory.
Filename mysql-connector-java-version-bin.jar
Compatibility
The Connector/J driver is backward compatible. Database server updates are frequent. Driver
updates are infrequent.
Driver Information
Type 4
cdb - jdbc:oracle:thin:@ip-address:1521/<service>
Filenames For 11g, see the file names from Oracle Technology Network.
For 12c, see the file names from Oracle Technology Network.
Documentation URLs For more information on Oracle Advanced Security, see Stanford
University (http://www.stanford.edu/) page
Oracle releases thin client drivers for various JVMs. Even though all of them work with this product,
we recommend that you use the 1.6 version.
Security
The Thin Client driver supports Oracle Advanced Security encrypted transport.
Connection Properties
The following table lists important connection properties for this driver.
Property Significance
Known Issues
High CPU utilization triggered by execution of embedded SQL statements:
The most common problem experienced with this driver is high CPU utilitization. As a result, this
driver always indicates that more results are available from calls to method
java.sql.Statement.execute(String stmt), which can lead to an infinite loop condition.
This condition occurs only if all the following happen:
A value other than single, no, or one in the driver compatibility parameter “Number of
Returned Result Sets” on page 71 is being executed.
Type 2
Download Instructions The SQLNet infrastructure is the main requirement for OCI.
SQLNet can run on any platform that Oracle supports, not
just Linux.
Filenames For 11g, see the file names from Oracle Technology
Network.
Use the Instant Client, which bypasses unneeded components of the full version.
Download the full package from Oracle.
If the database is running on the same server as Identity Manager, you don’t need to install SQLNet
because SQLNet comes as standard on the database server.
The Oracle OCI driver is essentially the same as the Thin Client driver. See “Oracle Thin Client JDBC
Driver” on page 179. The OCI client differs in the following ways:
For information on setting up the Oracle OCI Client, see Appendix M, “Setting Up an OCI Client on
Linux,” on page 229.
Driver Information
Type 4
Compatibility
The latest builds of the PostgreSQL driver are backward compatible through server version 8.4.3.
Database server updates and driver updates are frequent.
Security
The PostgreSQL driver supports SSL-encrypted transport for JDBC 3 driver versions.
Driver Information
Type 4
Compatibility
The Adaptive Server driver is backward compatible. Database server updates and driver updates are
infrequent.
Security
The Adaptive Server driver supports SSL-encrypted transport. To enable SSL encryption, you must
specify a custom socket implementation via the SYBSOCKET_FACTORY connection property. For
additional information on how to set connection properties, see “Connection Properties” on page 66.
Connection Properties
The SYBSOCKET_FACTORY property can be used to specify the class name of a custom socket
implementation that supports encrypted transport.
Type 4
Download Instructions Download and extract. The jar file is located in the extract-dir/mysql-
connector-java-version directory.
Filename mariadb-java-client-version.jar
Security
The Connector/J driver supports JSSE (Java Secure Sockets Extension) SSL-encrypted transport.
For information about supported third-party drivers that are recommended, see “Supported Third-
Party JDBC Drivers (Not Recommended)” on page 184.
This information is used in conjunction with the Authentication Context parameter. For information on
this parameter, see “Authentication Context” on page 54.
Driver Information
Type 4 Driver
file:///database-installation-directory/java
Compatibility
The IBM DB2 driver can best be characterized as version-hypersensitive. It is not compatible across
major or minor versions of DB2, including FixPacks. For this reason, we recommend that you use the
file installed on the database server.
The IBM DB2 driver must be updated on the Identity Manager or Remote Loader server every time
the target database is updated, even if only at the FixPack level.
Security
The IBM DB2 driver does not support encrypted transport.
Known Issues
A version mismatch usually results in connectivity-related failures.
Driver Information
Filenames sqljdbc.jar
The filename, URL syntax, and classname differ (often subtly) from those of the 2000 driver.
Compatibility
The SQL Server 2008 driver works only with SQL Server 2005. Database server and driver updates
are infrequent.
Security
The SQL Server 2008 driver supports encrypted transport.
The following table lists values for the integratedSecurity URL property for the SQL Server 2005
driver.
Driver Information
Filenames sqljdbc.jar
The filename, URL syntax, and classname differ (often subtly) from those of the 2000 driver.
Compatibility
The SQL Server 2008 R2 driver works only with SQL Server 2008. Database server and driver
updates are infrequent.
Security
The SQL Server 2008 driver supports encrypted transport.
The following table lists values for the integratedSecurity URL property for the SQL Server 2008
driver.
Type 4
JTOpen (http://jt400.sourceforge.net)
Toolbox for Java/JTOpen (http://www-03.ibm.com/
servers/eserver/iseries/toolbox/downloads.html)
Filenames jt400.jar
For a current list of the required and optional java.sql.DatabaseMetaData method calls that the
JDBC driver makes, see Appendix F, “java.sql.DatabaseMetaData Methods,” on page 211.
Support other required JDBC methods
For a list of required JDBC methods that the JDBC driver uses, refer to Appendix G, “JDBC
Interface Methods,” on page 213. You can use this list in collaboration with third-party driver
documentation to identify potential incompatibilities.
To assist you in debugging third-party JDBC drivers, the JDBC driver supports the following:
Tracing at the JDBC API level (level 6)
Third-party JDBC driver (level 7) tracing
Stored procedure or function support is a likely point of failure.
You probably need to write a custom driver descriptor file.
Specifically, you need to categorize error codes and SQL states for the third-party driver that you
are using.
Security Issues
To ensure that a secure connection exists between the Identity Manager JDBC driver and a third-
party driver, we recommend the following:
If you cannot run the JDBC driver remotely, you might want to use a type 2 or type 3 JDBC driver.
These driver types often facilitate a greater degree of security through middleware servers or client
APIs unavailable to other JDBC driver types. Some type 4 drivers support encrypted transport, but
encryption is the exception rather than the rule.
“DirXML-Accounts Attribute Shows Incorrect Value When a User is Enabled or Disabled in the
Identity Vault on DB2 and Oracle Database Drivers” on page 191
“Password Changes for Users Are Not Synchronized from the Identity Vault for the Oracle
Database Driver” on page 191
“Modifying the Default Configuration for the Sybase Driver in Direct Mode” on page 192
“Driver Shim Is Irresponsive When a Connected Database Server Does Not Respond” on
page 192
“Recognizing Publication Events” on page 192
“Executing Test Scripts” on page 192
“Applying the Latest Driver Package Does Not Change the Default Setting of Enable Service
Channel ECV” on page 193
“Troubleshooting Driver Processes” on page 193
DB2 driver: When the Allow Loopback option is set to Yes on the Publisher channel in the Indirect
Triggered mode.
There is no workaround.
To workaround this issue, after upgrading the driver, delete the existing user from the Oracle
database and synchronize it from the Identity Vault.
When you change the value for the Method and timing option, you need to edit the sample
procedures appropriately. For example, if you set it to view_usr("indirect.proc_idu(pk_idu)");
view_grp("indirect.proc_idg(pk_idg)"), you must edit the indirect.proc_idu and
indirect.proc_idg procedures so that unique values are returned for the idg and idu columns
respectively.
Case 1: The driver tries to update a record that is currently being modified through another
database connection.
If you instruct the driver to update this record, the driver will wait to operate on it until the updated
record is committed to the database.
This is an expected behavior. The driver is designed to wait to eliminate the chances of
inconsistent results in such situations.
Case 2: When the transaction log in a database is filled. For example, Sybase database.
The database does not allow any operations until the transaction log is cleared.
It is the responsibility of the database administrator to clear the transactions log. When the log is
cleared, the database is unlocked for operations and the driver resumes processing without
issues.
This issue does not occur when you create a new driver.
NetIQ Corporation recommends that you install and uninstall preconfigured drivers and database
scripts as a unit. To prevent unintentional mismatching, database scripts and preconfigured drivers
contain headers with a version number, the target database name, and the database version.
To uninstall the Identity Manager JDBC driver on Windows, use Add or Remove Programs in the
Control Panel.
1 Drop the idm, indirect, and direct operating system user accounts.
2 If you haven’t already done so, change the name of the administrator account name and
password in the installation scripts.
3 Using the Command Line Processor (CLP), execute the uninstall.sql script.
For example: db2 -f uninstall.sql
This script won’t execute in the Command Center interface beyond version 7 because the script
uses the \ line continuation character. Later versions of the Command Center don’t recognize
this character.
4 Delete the idm_db2.jar file.
1 From a MySQL client, such as mysql, log on as user root or another user with administrative
privileges.
For example, from the command line execute mysql -u root -p
By default, the root user has no password.
2 Execute the uninstall.sql uninstallation script.
For example: mysql> \. c:\uninstall.sql
Don’t use a semicolon to terminate this statement.
Oracle Uninstallation
The directory context for Oracle SQL scripts is install-
dir\DirXMLUtilities\jdbc\sql\oracle\install.
PostgreSQL Uninstallation
The directory context for PostgreSQL scripts is install-
dir\DirXMLUtilities\jdbc\sql\postgres\install. The directory context for executing Postgres
commands is postgres-install-dir/pgsql/bin.
1 From a Postgres client such as psql, log on as user postgres to the idm database.
For example, from the UNIXC command line, execute ./psql -d idm postgres
By default, the Postgres user has no password.
2 From inside psql, execute the script uninstall.sql.
For example: idm=# \i uninstall.sql
3 Drop the database idm.
For example, from the UNIX command line, execute ./dropdb idm
4 Remove or comment out entries for the idm user in the pg_hba.conf file.
For example:
5 Restart the Postgres server to effect changes made to the pg_hba.conf file.
NetIQ Corporation strives to ensure that our products provide quality solutions for your enterprise
software needs. The following issues are currently being researched. If you need further assistance
with any issue, please contact Technical Support.
For information about known issues in previous versions of Identity Manager, see the Release Notes
for each version on the corresponding documentation page.
Known Issues
JDBC Driver
Identity Vault Time and Timestamp syntaxes are inadequate for expressing the range and
granularity of their database counterparts. This is a publication problem because database time-
related types typically have a wider range and greater degree of granularity (typically
nanoseconds). The converse is not true. For more information, see “Time Syntax” on page 57.
The JDBC driver is unable to parse proprietary database time stamp formats. Some databases,
such as Sybase and DB2, have proprietary time stamp formats that the java.sql.Timestamp
(http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Timestamp.html) class can’t parse. When
synchronizing time stamp columns from these databases, the JDBC driver, by default, assumes
that time stamp values placed in the event log table are in ODBC canonical format (that is, yyyy-
mm-dd hh:mm:ss.fffffffff). The recommended method for enabling the JDBC driver to
handle proprietary database time stamp formats is to implement a custom
DBTimestampTranslator class. This interface is documented in the JavaDoc Tool that ships
with the JDBC driver. Using this approach avoids the problem of reformatting time stamps in the
database before they are inserted into the event log table or reformatted in style sheets. The
JDBC driver ships with default implementations for the native DB2 time stamp format and the
Sybase style 109 time stamp format.
Statements executed against the database server might block indefinitely.
Typically, blocking is caused by a database resource being exclusively locked. Because the
locking mechanisms and locking SQL vary by database, the general solution to this problem is to
implement a custom DBLockStatementGenerator class. For additional information, see “Lock
Statement Generator Class” on page 72. The JDBC driver ships with a default implementation
for Oracle.
Many factors can cause blocking. To mitigate the likelihood of blocking, we recommend that you
do not set the Transaction Isolation Level parameter to a level greater than read committed.
The JDBC interface defines a method java.sql.Statement.setQueryTimeout(int):void (http://
java.sun.com/j2se/1.5.0/docs/api/java/sql/Statement.html) that allows a statement to time out
after a specified number of seconds. Unfortunately, implementations of this method between
third-party JDBC drivers range from not being implemented to having bugs. For this reason, this
method was deemed unsuitable as a general-purpose solution.
Limitations
The JDBC driver does not support the use of delimited (quoted) database identifiers (for
example, “names with spaces”).
JDBC 2 data types are not supported, with the exception of Large Object data types (LOBs) such
as CLOB and BLOB.
JDBC 3 data types are not supported.
PostgreSQL does not support <check-object-password> events. Authentication is controlled
by manually inserting entries into the pg_hba.conf file.
The following section lists important best practices for using the JDBC driver. You can find additional
information in Chapter 6, “Configuring the JDBC Driver,” on page 51.
1 Click the driver set that contains this driver and change the Java Maximum heap size to 256 MB.
This change will be applicable to all the drivers under this driver set.
2 Under the Driver Settings, change the Show the compatibility parameters? option to show to
display the Show backward compatibility parameters? option. Change it to show, then change
the Enable the Table Referential attribute support? to No.
3 Under the Publisher Settings, change the Show polling-related parameters? option to show to
display the Batch Size, then change it to 128.
Every table that contains a primary key constraint is considered as an object class. For example,
the following usr table created by the SQL code is considered as an object class by the driver
shim if the Schema Name is set to indirect.
The above table will contain two single-valued attributes; fname and lname. The driver will build
its associations based on the value of the column referenced in the primary key constraint, which
in this case is column idu.
Every table that only has a Foreign Key constraint is considered as a multi-valued attribute of
the class that holds the primary key pointed by the said foreign key constraint. In the following
example, if the driver parameter, Schema Name is set to indirect, then the usr_phone.phoneno
table is considered a multi-valued attribute belonging to the class usr.
NOTE: The child table usr_phone only has a foreign key constraint to the parent table usr. The
table usr is considered an object class since it has a primary key constraint.
DN-type references between the two objects will have different requirements based on whether
the reference points back to the same object class or to a different object class. DN-type
references also change depending on whether the DN attribute is single valued or multi-valued.
If the attribute is single-valued and points back to the same object class, then the table that
contains that class will have a foreign key constraint to itself and uses a local column to store the
value. An example is the manager attribute in eDirectory. In the example below, if the driver
parameter Schema Name is set to indirect, then the attribute manager will be a DN-type
attribute that points to another row inside the usr table.
If the attribute is multi-valued and points back to the same object class, then we need a child
table with columns, each having its own foreign key constraint to the same parent table. An
example is the directReports attribute in eDirectory. In the following example, if the driver
parameter Schema Name is set to indirect, then the attribute usr_directReports.repname will
be a DN-type attribute that points to one or more rows inside the usr table.
If the attribute is multi-valued and points to a different object class, then we need a child table
with two columns, each having a foreign key constraint to a different parent table. An example is
the Group Membership attribute in eDirectory. In the following example, if the driver parameter
Schema Name is set to indirect, then the attribute usr_mbr_of.idu will be a DN-type attribute
that points to a row inside the grp table. In this example, both the usr table and the grp table
represent object classes.
Security/Performance:
For performance and security reasons, run the driver remotely on the database server whenever
possible. Be sure to enable SSL encryption between the Identity Vault and the Remote Loader
service.
Other:
For direct synchronization, prefix one or more view column names with “pk_” (case-insensitive).
For both direct and indirect synchronization, use different primary key column names between
logical database classes.
Delimit (double-quote) primary key values placed in the event log table_key field if they contain
the following characters: , ; ' + = \ " < > This caution is usually an issue only if the primary key
column is a binary type.
When an Identity Vault is the authoritative source of primary key values, GUID rather than CN is
recommended for use as a primary key. Unlike CN, GUID is single-valued and does not change.
From publication triggers, omit foreign key columns that link child and parent tables.
If primary key columns are static (they do not change), do not include them in publication
triggers.
Place the jdbc:type="query" attribute value on all embedded SELECT statements. Place the
jdbc:type="update" attribute value on all embedded INSERT, UPDATE and DELETE statements.
To avoid issues that arise when you run a sql query that has a reserved word as a column name,
specify a fully qualified name for the column.
For example, when you use group as a column name under usr table, group being is a sql
keyword, your query might not be properly executed. To avoid this, specify a fully qualified name
such as usr.group (<Tablename>.<Columnname>) for the column.
By design, the driver doesn't allow primary keys on child tables in the Synch Schema mode. To
comply with standard database best practices, if you add a primary key on all tables including the
child tables containing multi-valued attributes, the driver doesn't work properly in this mode. You
must operate the driver in the Synch Tables/Views mode to allow primary keys on child tables.
The Synch Tables/Views mode prevents the driver from adding the child tables to the list of
synchronized tables.
Answer: The driver is capable of synchronizing only tables that have explicit primary key constraints
and views that contain one or more columns prefixed with “pk_” (case-insensitive). The driver uses
these constraints to determine which fields to use when constructing associations. As such, the driver
ignores any unconstrained tables. If you are trying to synchronize with tables or views that lack the
necessary constraints, either add them or synchronize to intermediate tables with the required
constraints.
Another possibility is that the driver lacks the necessary database privileges to see the tables.
Usually, visibility is determined by the presence or absence of the SELECT privilege.
FAQ 205
Processing Rows in the Event Log Table
Question: Why isn’t the driver processing rows in the Event Log Table?
1 Check the perpetrator field of the rows in question and make sure that the value is set to
something other than the driver’s database username.
The Publisher channel checks the perpetrator field to detect loopback events if the Publisher
channel Allow Loopback parameter is set to Boolean False (the default). See “Allow Loopback?”
on page 90.
When the Allow Loopback parameter is set to Boolean False, the Publisher channel ignores all
records where the perpetrator field value is equal to the driver’s database username. The
driver’s database username is specified by using the Authentication ID parameter. See
“Authentication ID” on page 54.
2 Ensure that the record’s status field is set to N (new).
Records with status fields set to something other than N will not be processed.
3 Make sure to explicitly commit changes.
Changes are often tentative until explicitly committed.
Answer: Yes. You can manage database accounts by using embedded SQL. For more information,
see Chapter 12, “Embedded SQL Statements in XDS Events,” on page 133.
Answer: Yes. Large binary and string data types can be subscribed and published. Publish large
binary and string data types by using query-back event types. For additional information, see “Event
Types” on page 124.
Slow Publication
Question: Why is publication slow?
Answer: If the event log table contains a large number of rows, index the table. Example indexes are
provided in all database installation scripts. By using trace level 3, you can view the statements that
the driver uses to maintain the event log.
You can further refine indexes in the installation scripts to enhance publication performance. Placing
indexes in a different tablespace or physical disk than the event log table also enhances publication
performance.
Furthermore, in a production environment, set the Delete Processed Rows parameter to Boolean
False, unless processed rows are being periodically moved to another table. See “Delete Processed
Rows?” on page 89.
206 FAQ
Synchronizing Multiple Classes
Question: Can the driver synchronize multiple classes?
Answer: Yes. However, primary key column names must be unique between logical database
classes. For example, if class1 is mapped to table1 with primary key column name key1, and class2
is mapped to table2 with primary key column name key2, then the name of key1 cannot equal key2.
This requirement can always be satisfied, no matter which synchronization model is employed.
Encrypted Transport
Question: Does the driver support encrypted transport?
Answer: No. How the driver communicates with a given database depends upon the third-party
driver being used. Some third-party drivers support encrypted transport, but others do not. Even if
encrypted transport is supported, no standardized way exists to enable encryption between third-
party JDBC drivers.
The general solution for this problem is to remotely run the JDBC driver and your third-party driver.
This method allows both the JDBC driver and the third-party driver to run locally on the database
server. Then all data traveling across the network between the Identity Manager engine and the
JDBC driver are SSL encrypted.
Another possibility is to use a type 3 or type 2 third-party JDBC driver. Database middleware and
client APIs usually provide encrypted transport mechanisms.
Answer: See “Mapping Multivalue Attributes to Single-Value Database Fields” on page 116.
Answer: The database and the third-party driver are probably using incompatible character
encoding. Adjust the character encoding that your third-party driver uses.
Answer: Use the Remote Loader to load each JDBC driver instance in a separate Java Virtual
Machine (JVM). When run locally in the same JVM, different versions of the same third-party classes
collide.
FAQ 207
208 FAQ
E Supported Data Types
E
The JDBC driver can synchronize all JDBC 1 data types and a small subset of JDBC 2 data types.
How JDBC data types map to a database’s native data types depends on the third-party driver.
Numeric Types:
java.sql.Types.BIGINT
java.sql.Types.BIT
java.sql.Types.DECIMAL
java.sql.Types.DOUBLE
java.sql.Types.NUMERIC
java.sql.Types.REAL
java.sql.Types.FLOAT
java.sql.Types.INTEGER
java.sql.Types.SMALLINT
java.sql.Types.TINYINT
String Types:
java.sql.Types.CHAR
java.sql.Types.LONGCHAR
java.sql.Types.VARCHAR
Time Types:
java.sql.Types.DATE
java.sql.Types.TIME
java.sql.Types.TIMESTAMP
Binary Types:
java.sql.Types.BINARY
java.sql.Types.VARBINARY
java.sql.Types.LONGVARBINARY
java.sql.Types.CLOB
java.sql.Types.BLOB
The following JDBC 1 methods are required only if the Synchronization Filter parameter is set to
something other than Exclude all tables/views:
dataDefinitionCausesTransactionCommit():boolean
dataDefinitionIgnoredInTransactions():boolean
getColumnPrivileges(String catalog, String schema, String table, String
columnNamePattern):java.sql.ResultSet
getDatabaseProductName():java.lang.String
getDatabaseProductVersion():java.lang.String
getDriverMajorVersion():int
getDriverMinorVersion():int
getDriverName():java.lang.String
getDriverVersion():java.lang.String
getExportedKeys(java.lang.String catalog, java.lang.String schema, java.lang.String
table):java.sql.ResultSet
getMaxStatements():int
getMaxConnections():int
getMaxColumnsInSelect():int
getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern,
String columnNamePattern):java.sql.ResultSet
getSchemas():java.sql.ResultSet
getTableTypes():java.sql.ResultSet
getUserName():java.lang.String
supportsColumnAliasing():bolean
supportsBatchUpdates():boolean
supportsGetGeneratedKeys():boolean
This section lists the JDBC interface methods (other than java.sql.DatabaseMetaData (http://
java.sun.com/j2se/1.5.0/docs/api/java/sql/DatabaseMetaData.html) methods) that the JDBC driver
uses. Methods are organized by class.
Often, third-party JDBC driver vendors list defects or known issues by method. You can use the
following methods in collaboration with third-party JDBC driver documentation to troubleshoot or
anticipate potential interoperability problems.
java.sql.DriverManager (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/DriverManager.html)
java.sql.CallableStatement (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/
CallableStatement.html)
java.sql.Connection (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Connection.html)
java.sql.PreparedStatement (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/
PreparedStatement.html)
java.sql.ResultSet (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ResultSet.html)
java.sql.ResultSetMetaData (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/
ResultSetMetaData.html)
java.sql.Statement (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Statement.html)
java.sql.Timestamp (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Timestamp.html)
setLogStream(java.io.PrintStream out):void 1 no
getBoolean(String parameterName):boolean 3 no
getByte(String parameterName):byte 3 no
getBytes(String parameterName):byte[] 3 no
getDate(String parameterName):java.sql.Date 3 no
getDouble(String parameterName):double 3 no
getFloat(String parameterName):float 3 no
getLong(String parameterName):long 3 no
getShort(String parameterName):short 3 no
getString(String parameterName):String 3 no
getTime(String parameterName):java.sql.Time 3 no
getTimestamp(String parameterName):java.sql.Timestamp 3 no
wasNull():boolean 1 yes
close():void 1 yes
commit():void 1 no
createStatement():java.sql.Statement 1 yes
getAutoCommit():boolean 1 no
getMetaData():java.sql.DatabaseMetaData 1 yes
getTransactionIsolation():int 1 no
getWarnings():java.sql.SQLWarning 1 no
isClosed():boolean 1 no
prepareCall(String sql):java.sql.CallableStatement 1 no
rollback():void 1 no
setAutoCommit(boolean autoCommit):void 1 no
setTransactionIsolation(int level):void 1 no
clearParameters() :void 1 no
execute():boolean 1 yes
executeQuery():java.sql.ResultSet 1 yes
executeUpdate():int 1 yes
close():void 1 yes
getMetaData():java.sql.ResultSetMetaData 1 no
getWarnings():java.sql.SQLWarning 1 no
getColumnCount():int 1 yes
getColumnName(int column):String 1 no
getColumnType(int column):int 1 no
addBatch(java.lang.String sql):void 2 no
clearBatch():void 2 no
clearWarnings():void 1 no
close():void 1 yes
executeBatch():int[] 2 no
getGeneratedKeys():java.sql.ResultSet 3 no
getMoreResults():boolean 1 no
getResultSet():java.sql.ResultSet 1 yes
getUpdateCount():int 1 no
getWarnings():java.sql.SQLWarning 1 no
getNanos():int 1 yes
getTime():long 1 yes
DTD
This section contains the DTD for third-party JDBC descriptor files.
Import DTD
This section contains the DTD for third-party JDBC descriptor import files.
This section contains the DTD for database descriptor import files.
Event Processing
The following example assumes that a “commence” attribute exists and does the following:
Holds the time stamp value indicating when an event should be processed
Contains an integer or Java string time stamp value. See “Time Syntax” on page 57.
<policy xmlns:Timestamp="http://www.novell.com/nxsl/java/java.sql.Timestamp"
xmlns:TimestampUtil="http://www.novell.com/nxsl/java/
com.novell.nds.dirxml.driver.jdbc.db.TimestampUtil"
xmlns:jdbc="urn:dirxml:jdbc">
<rule>
<description>Get commencement date from datasource.</description>
<conditions>
<and>
<if-xpath op="true">.</if-xpath>
</and>
</conditions>
<actions>
<do-set-local-variable name="commence">
<arg-string>
<token-src-attr class-name="User" name="commence"/>
</arg-string>
</do-set-local-variable>
</actions>
</rule>
<rule>
<description>Break if commencement date unavailable.</description>
<conditions>
<and>
<if-local-variable name="commence" op="equal"/>
</and>
</conditions>
<actions>
<do-break/>
</actions>
</rule>
<rule>
<description>Parse times.</description>
<conditions>
<and>
<if-xpath op="true">.</if-xpath>
</and>
</conditions>
<actions>
<do-set-local-variable name="dbTime">
<arg-object>
<token-xpath expression="Timestamp:valueOf(@jdbc:database-local-time)"/>
</arg-object>
</do-set-local-variable>
<do-set-local-variable name="eventTime">
<rule>
<description>Retry if future event.</description>
<conditions>
<and>
<if-local-variable name="after" op="equal">true</if-local-variable>
</and>
</conditions>
<actions>
<do-status level="retry">
<arg-string>
<token-text xml:space="preserve">Future event detected.</token-text>
</arg-string>
</do-status>
</actions>
</rule>
</policy>
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/oracle/client/lib
export TNS_ADMIN=/oracle/client/network/admin
export PATH=$PATH:/oracle/client/lib
The profile.local file is in the /etc folder. If the file doesn’t exist, create one. The file can
consist of only the three export lines.
The profile.local file extends the LD_LIBRARY_PATH, sets TNS_ADMIN, and extends the
PATH. This file is read when the server boots.
Sybase can execute stored procedures in two distinct modes: chained and unchained. Depending
upon the configuration of the Identity Manager JDBC driver and stored procedures in a database,
various problems can arise. This section can help you understand and resolve those problems.
Error Codes
“Error 226: SET CHAINED command not allowed within multi-statement transaction” on
page 231
“Error 7112: Stored procedure 'x' may be run only in chained transaction mode” on page 231
“Error 7113: Stored procedure 'x' may be run only in unchained transaction mode” on page 232
Sybase Chain Modes and the Identity Manager JDBC driver 231
Error 7113: Stored procedure 'x' may be run only in unchained
transaction mode
Effect: Throws the exception com.sybase.jdbc2.jdbc.SybSQLException with error code
7713 and an SQL state of ZZZZZ.
Cause: The stored procedure was created in unchained mode, or later altered to run in
unchained mode, but the driver is currently running in chained mode. The
probable cause is that the Use Manual Transactions? parameter is set to True.
Another possibility is that the transaction type has been overridden to manual in
policy.
Solution: Do one of the following:
The following example illustrates how to invoke the sp_procxmode procedure from the isql command
line:
Of course, not all customers are willing to alter stored procedure modes. Altering a procedure's mode
might alter its runtime behavior, which could alter the behavior of other applications that invoke the
procedure.
232 Sybase Chain Modes and the Identity Manager JDBC driver
Table N-1 Modes and Compatibility
Mode Compatibility
Sybase provides a third-party JDBC driver called jConnect. The default mode of jConnect is
unchained. Whenever the method Connection.setAutoCommit(boolean autoCommit):void is invoked,
jConnect switches modes. See java.sql Interface Connection (http://java.sun.com/j2se/1.4.2/docs/
api/java/sql/Connection.html).
Method Effect
If the Use Manual Transactions? parameter is set to False, the driver invokes
Connection.setAutoCommit(true). That is, the driver enters unchained mode. This is the normal
processing mode for SELECT statements and SQL embedded in a policy where the transaction type
is set to auto. See “Manual vs. Automatic Transactions” on page 139. When the driver is in this state,
any chained stored procedures invoked directly or indirectly by the driver yield the 7112 error.
If the Use Manual Transactions? parameter is set to True, the driver invokes
Connection.setAutoCommit(false). That is, the driver enters chained mode. This is the normal
processing mode for all statements except SELECT statements and SQL embedded in a policy
where the transaction type is set to manual. See “Manual vs. Automatic Transactions” on page 139.
When the driver is in this state, any unchained stored procedures invoked directly or indirectly by the
driver yield the 7113 error.
Useful Links
Transaction modes and stored procedures (http://manuals.sybase.com/onlinebooks/group-as/
asg1250e/sqlug/@Generic__BookTextView/55096;hf=0;pt=55096#X) in the Transact-SQL
User's Guide
Selecting the transaction mode and isolation level (http://manuals.sybase.com/onlinebooks/
group-as/asg1250e/sqlug/@Generic__BookTextView/53713;pt=53001) in the Transact-SQL
User's Guide
Sybase Chain Modes and the Identity Manager JDBC driver 233
234 Sybase Chain Modes and the Identity Manager JDBC driver
O Driver Properties
O
This section provides information about the Driver Configuration and Global Configuration Values
properties for the JDBC driver and the Fan-out driver. These are the only unique properties for
drivers. All other driver properties (Named Password, Engine Control Values, Log Level, and so forth)
are common to all drivers. Refer to “Driver Properties” in the NetIQ Identity Manager Driver
Administration Guide for information about the common properties.
The information is presented from the viewpoint of iManager. If a field is different in Designer, it is
marked with a Designer icon.
Driver Configuration
In iManager:
In Designer:
The Driver Configuration options are divided into the following sections:
Java: Use this option to specify the name of the Java class that is instantiated for the shim
component of the driver. This class can be located in the classes directory as a class file, or in the
lib directory as a .jar file. If this option is selected, the driver is running locally. Select this option to
run the driver locally.
Connect to Remote Loader: This option is not used for JDBC Fan-out driver. Used when the driver
is connecting remotely to the connected system.
Driver Object Password: Use this option to set a password for the driver object. If you are using the
Fan-out Agent, you must enter a password on this page. This password is used by the Fan-out Agent
to authenticate itself to the driver shim.
Authentication
The authentication section describes the parameters required for authentication to the connected
database.
Authentication ID: Specify a user application ID. This ID is used to pass Identity Vault subscription
information to the application. For example, Administrator.
Connection Information (Designer only): Specify the IP address or name of the server the
application shim should communicate with.
IMPORTANT: The Remote Loader options are not applicable for the JDBC Fan-out drivers. The Fan-
out drivers use the Fan-out Agent component to create multiple database instances.
Driver Cache Limit (kilobytes): Specify the maximum event cache file size (in KB). If it is set to
zero, the file size is unlimited. select Unlimited option to set the file size to unlimited in Designer.
Application Password: Use the Set Password option to set the application authentication
password.
Remote loader password: Use this option to update the remote loader password. This option is not
used for the JDBC Fan-out driver.
Startup Option
The Startup Option section allows you to set the driver state when the Identity Manager server is
started.
Auto start: The driver starts every time the Identity Manager server is started.
Manual: The driver does not start when the Identity Manager server is started. The driver must be
started through Designer or iManager.
Driver Parameters
The Driver Parameters section lets you configure the driver-specific parameters. When you change
driver parameters, you tune driver behavior to align with your network environment.
Driver Settings
Fanout transport related parameters: Select Show to view the transport related parameters for
Fan-out drivers.
Show Subscriber Event Queue parameters: Select Show to view the subscriber event parameters.
The options are:
SEND: The queue for sending the subscriber events to the Fan-out Agent.
RECV: The subscriber event receiving queue for receiving the subscriber events from Fan-out
Agent.
DELAYED RECV: The subscriber delayed event receiving queue is used for receiving the
delayed subscriber events from FanOut Agent.
Show Configuration Queue Parameters: Select Show to view the configuration queue parameters.
The options are SEND and RECV.
Show Query-in Queue Parameters: Select Show to view the query-in queue parameters. The
options are SEND and RECV.
Show Query-out Queue Parameters: Select Show to view the query-out queue parameters. The
options are SEND and RECV.
Configuration batch size: Specify the batch size for the Driver configuration document. The value
is from 1 - 99999.
Show Fanout Parameters: Select Show to view the fan-out connection related information such as
Fan-out Agent password, configuration information, Fan-out Agent shim password.
Fanout Shim Password: Specify the password for the fan-out driver shim. After successful
authentication, the FanOut Agent loads/creates the driver instances of the specified shim class
name.
Fanout Agent Password: Specify the password of Fan-out Agent you are connecting to. The
Fan-out Agent establishes connection only after a valid authentication.
Encryption Key: Specify the key to encrypt/decrypt the sensitive data before sending to the
message queue(s).
Subscriber Settings
Disable Subscriber: Select no (default) to allow flow of events from Identity Manager engine to the
connected database.
Show primary key parameters: Select Show if you want to configure the primary key parameters.
Disable statement-level locking: Select the appropriate option to disable statement locking. This
option determines if explicit locking or database resources are disabled on the Subscriber channel.
The value is set to no (default) by default.
Check update counts: Select yes (default) to enable the Subscriber channel to check for any
updates after any of the insert, update, or delete statements are executed against the tables. This
option ensures that the statements are resulting in updating the database. The value is set to yes
(default) by default.
Publisher Settings
Disable the Publisher Channel: Select yes (default) to ignore the flow of events from the
connected database to Identity Manager engine. The Fan-out driver implementation do not support
the Publisher channel. By default, this option is disabled for the Fan-out driver configuration.
ECMAScript
Displays an ordered list of ECMAScript resource files. The files contain extension functions for the
driver that Identity Manager loads when the driver starts. You can add additional files, remove existing
files, or change the order the files are executed.
Global Configuration
Displays an ordered list of Global Configuration objects. The objects contain extension GCV
definitions for the driver that Identity Manager loads when the driver is started. You can add or
remove the Global Configuration objects, and you can change the order in which the objects are
executed.
The REST driver includes several predefined GCVs. You can also add your own if you discover you
need additional ones as you implement policies in the driver.
2 Right-click the driver icon or line, then select Properties > Global Configuration Values.
or
To add a GCV to the driver set, right-clickthe driver set icon , then click Properties > GCVs.
JDBC connection URL format used: Specify the connection URL format used for the JDBC driver
to connect to the databases. Use '<HOST>','<PORT> and '<DB>' tokens to specify the location of
host's IP address, port and database/SID in the connection URL.
NOTE: The tokens are case-sensitive and angle-brackets are mandatory since they are used as
delimiters.
If you use the same fan-out driver to connect oracle pluggable database and oracle traditional
database, the url template of the databases should be separated using a comma. For example:
jdbc:oracle:thin:@<HOST>:<PORT>/<DB>, jdbc:oracle:thin:@<HOST>:<PORT>:<DB>
Synchronization model: Select the synchronization model. The synchronization options are: Direct
and Indirect. Direct synchronization uses views to synchronize directly to existing tables of arbitrary
structure. Indirect synchronization synchronizes to intermediate staging tables with a particular
structure.
UserName Column: Specify the exact column name of the usr table that store the usernames.
General Information
Name: Specify a descriptive name for the managed system.
System Ownership
Business Owner: Browse to and select the business owner in the Identity Vault for the connected
application. You must select a user object, not a role, group, or container.
Application Owner: Browse to and select the application owner in the Identity Vault for the
connected application. You must select a user object, not a role, group, or container.
Mission-Critical
Vital
Not-Critical
Other
If you select Other, you must specify a custom classification for the connected application.
Environment: Select the type of environment the connected application provides. The options are:
Development
Test
Staging
Production
Other
If you select Other, you must specify a custom classification for the connected application.
JDBC FanOut Instance Name: Specify the descriptive name of the new logical instance of the
managed system.
Show other configuration values: Select Show to display additional information related to the
FanOut instance. For more information, see “Managed System Information” on page 240.
Connection and miscellaneous information: Select Show to display the system options. The
options are:
Instance ID
Authentication IP Address
Authentication Port
Authentication ID
Database Schema
Type
NOTE: The connection information options are auto-generated and always set to hide.
Entitlements
Account Entitlement Value: Specify the entitlement value to assign for user account during the
account creation. Identity Applications display this value to the user during account provisioning.
Use Entitlements to Control DB Accounts: Select True to enable the driver to manage database
accounts based on the driver’s defined entitlements. Select False to disable management of
database accounts based on the entitlements.
Use Group Entitlement: Select True to enable the driver to manage group membership based on
the driver’s defined entitlements.
Allow Login Disabled in Subscriber Channel: Select True to enable the driver to control the flow
of Login Disabled attribute in the Subscriber Channel and only on a regular attribute change.
Advanced Settings: Entitlement options that allow or deny additional functionality like data
collection, role mapping, resource mapping, parameter format, and entitlement extensions. Leave
these settings as default.
Data Collection
Data collection enables Identity Report to gather information to generate reports. For more
information, see the Administrator Guide to NetIQ Identity Reporting.
Enable data collection: Select Yes to enable data collection for the driver through Data Collection
Service by the Managed System Gateway driver. If you are not going to run reports on data collected
by this driver, select No.
Allow data collection from user accounts: Select Yes to allow data collection by Data Collection
Service for the user accounts.
Allow data collection from groups: Select Yes to allow data collection by Data Collection Service
for groups.
Role Mapping
The Identity Manager Identity Applications allows you to map business roles with IT roles. For more
information, see Identity Applications Administration in the NetIQ Identity Manager - Administrator’s
Guide to the Identity Applications.
Enable role mapping: Select Yes to make this driver visible to Identity Applications.
Allow mapping of groups: Select Yes if you want to allow mapping of groups in Identity
Applications.
Resource Mapping
Identity Applications allow you to map resources to users. For more information, see the NetIQ
Identity Manager - User’s Guide to the Identity Applications.
Enables resource mapping: Select Yes to make this driver visible to Identity Applications.
Allow mapping of user accounts: Select Yes if you want to allow mapping of user accounts in
Identity Applications. An account is required before a role, profile, or license can be granted.
Allow mapping of groups: Select Yes if you want to allow mapping of groups in Identity
Applications.
Parameter Format
Format for Account entitlement: Specify the parameter format the entitlement agent must use
when granting the user account entitlement. The options are Identity Manager 4 and Legacy.
Format for Group entitlement: Specify the parameter format the entitlement agent must use when
granting the group entitlement. The options are Identity Manager 4 and Legacy.
Entitlements Extensions
User account extension: Specify the user account extension. The content of this field is added
below the entitlement elements in the EntitlementConfiguration resource object
Group extensions: Specify the group extensions. The content of this field is added below the
entitlement elements in the EntitlementConfiguration resource object
Account Tracking
The following controls the Account tracking is part of Identity Reporting. For more information, see the
Administrator Guide to NetIQ Identity Reporting.
Enable Account Tracking: Set this to True to enable account tracking policies for the JDBC Fan-out
driver. Set it to False if you do not want to execute account tracking policies.
Object class
Realm
Identifiers for Account
Status Attribute
Status active value
Status inactive value
Subscription default status
Publication default status
Application Accepts Passwords from Identity Manager: If this option is set to True, the driver
allows passwords to flow from the Identity Manager data store to the connected Office 365 server.
Identity Manager Accepts Passwords from the Application: If this option is set to True, it allows
passwords to flow from the connected system to Identity Manager.
Publish Passwords to NDS Password: Use the password from the connected system to set the
non-reversible NDS password in the Identity Vault.
Publish Passwords to Distribution Password: Use the password from the connected system to
set the NMAS Distribution Password used for Identity Manager password synchronization.
Require passwords policy validation before publishing passwords: Select True to apply NMAS
password policies when publishing passwords. Password is not written to the data store if it does not
comply.
Reset user’s external system password to the Identity Manager password on failure: If this
option is set to True, and the Distribution Password fails to distribute, attempt to reset the password in
the connected system by using the Distribution Password from the Identity Manager data store.
Notify the user of password synchronization failure via e-mail: If this option is set to True, notify
the user by e-mail of any password synchronization failures.
Connected System or Driver Name: Specifies the name of the connected system, application or
Identity Manager driver. This value is used by the e-mail notification templates to identify the source
of notification messages.
In Designer, you must click the icon next to a GCV to edit it. This displays the Password
Synchronization Options dialog box for a better view of the relationship between the different GCVs.
In iManager, to edit the Password management options go to Driver Properties > Global
Configuration Values, and then edit it in your Password synchronization policy tab.
Synchronize the first or the last replica value: Select the appropriate option to synchronize the
first or last replica value of multi-valued attributes mapped to single-valued columns. The options are:
First and Last.