Generating the Database Application Tables Connector

To generate the DBAT connector, you must configuring the Groovy File and run the DBAT Generator to discover the schema.

The procedure to generate the Database Application Tables (DBAT) connector is divided into the following stages:

Overview of Configuring the Groovy File

The groovy file shipped with the connector can be used to specify values for properties that can store basic information about the target system schema.

This section includes the following topics:

About the Groovy File

The DBAT connector is shipped with a groovy file named DBATConfiguration.groovy. This file is located in the dbat-RELEASE_NUMBER/generator/dbat-generator-RELEASE_NUMBER directory of the connector installation ZIP. You use the DBATConfiguration.groovy file to specify values for properties that can store basic information about your target system schema. This file is used by the DBAT Generator to perform the following tasks:

  • Discover the schema

  • Configure the mode (trusted source or target resource) in which you want to run the connector

  • Generate the connector package specific to your target system

The procedure for running the DBAT Generator and directory structure of the generated connector package is discussed later in this chapter.

The DBATConfiguration.groovy file contains sample configuration (one each for trusted source and target resource) with pre-populated values for most of the entries. Depending upon your requirements, specify or modify values for entries in this file or create new sections for your configuration. The following are the predefined sections in the DBATConfiguration.groovy file:

  • trusted

    You specify values for the entries in this section if you want to configure the connector for the trusted source mode.

  • target

    You specify values for the entries in this section if you want to configure the connector for the target resource mode.

Configuring the DBATConfiguration.groovy File

To configure the DBATConfiguration.groovy file:

  1. Download the connector installation ZIP file from Oracle Technology Network.
  2. Extract the contents of the connector installation ZIP to any directory on the computer hosting OIM. This creates a directory named dbat-RELEASE_NUMBER. See Files and Directories in the Database Application Tables Connector for information about all the files and directories in the connector installation ZIP.
  3. Extract the contents of the dbat-RELEASE_NUMBER/generator/dbat-generator-RELEASE_NUMBER.zip file to any directory. This creates a directory named dbat-generator-RELEASE_NUMBER.
  4. In a text editor, open the DBATConfiguration.groovy file located in the dbat-generator-RELEASE_NUMBER/resources directory.
  5. Specify values for entries in one of the following predefined sections:

    • trusted - for configuring your target system as a trusted source.

    • target - for configuring your target system as a target resource.

    Note:

    The entries in these predefined sections are described later in this section.

  6. Save and close the DBATConfiguration.groovy file.

Entries in the Predefined Sections

This section describes the entries in the predefined sections, trusted and target, of the DBATConfiguration.groovy file.

Note:

  • Unless specified, all entries described here are common to both sections.

  • If you do not want to specify a value for any of the optional entries or attributes in the DBATConfiguration.groovy file, then comment out that entry or attribute by prefixing it with the double-slash symbol (//).

  • Some of the entries and properties in the DBATConfiguration.groovy file contain sample values such as USERINFO, USER_INFO, USER_GROUP, and so on. These sample values must be replaced with the actual table names present in your target system.

itResourceDefName

This is a mandatory entry. Enter the name of the IT resource type for the target system. Note that the value that you specify for this entry determines the name of the connector package, connector configuration file, and connector installer file. For example, if you specify DBAT as the value of this entry, then the name of the connector package directory is DBAT.zip. See Understanding the Generated Connector Package for the directory structure of the connector package.

itResourceName

This is an optional entry. Enter the name of the IT resource for the target system. If this entry is commented, then the IT resource name will be the same as the value of the ITResourceDefName entry.

Sample value: DBAT

Note:

The value of this entry must be unique for each connector that you create for your target system database. In addition, this value will be a part of the names for all connector components (defined in the connector configuration XML file, which is created after you run the DBAT Generator) such as lookup definitions, resource objects, process forms, and scheduled tasks.

For example, if you specify DBAT as the value of itResourceName entry, then after you deploy the connector, the configuration lookup definition is created and its name will be Lookup.Configuration.DBAT.

connectorDir

This is an optional entry. This entry is the name of the directory that contains the connector package that is generated when you run the DBAT Generator. By default, the value of this entry is the same as the value of the itResourceName entry.

xmlFile

This is an optional entry. Enter the name and relative path of the XML file that must contain definitions of the connector objects. If you do not specify a value for this entry, then the file name is generated in the following format:

IT_RES_DEF_NAME-ConnectorConfig.xml

In this format, IT_RES_DEF_NAME is the value of the itResourceDefName entry.

For example, if you have not specified a value for this entry and DBAT is the value of the itResourceDefName entry, then the name of the XML file that is generated is DBAT-ConnectorConfig.xml.

Note:

To easily identify files of a specific target system installation, it is recommended that the names of this generated XML file be prefixed with the name of the IT resource for the target system.

Sample value: DBAT-ConnectorConfig.xml

configFile

This is an optional entry. Enter the name and relative path of the XML file that contains the configuration information of the connector objects. If you do not specify a value for this entry, then the file name is generated in the following format:

IT_RES_DEF_NAME-CI.xml

In this format, IT_RES_DEF_NAME is the value of the itResourceDefName entry.

For example, if you have not specified a value for this entry and DBAT is the value of the itResourceDefName entry, then the name of the XML file that is generated is DBAT-CI.xml.

propertiesFile

This is an optional entry. Enter the name and relative path of the .properties file which contains the resource bundle translations. If you do not specify a value for this entry, then the file name is generated in the following format:

IT_RES_DEF_NAME-generator.properties

In this format, IT_RES_DEF_NAME is the value of the itResourceDefName entry.

For example, if you have not specified a value for this entry and DBAT is the value of the itResourceDefName entry, then the name of the properties file that is generated is DBAT-generator.properties.

version

This is an optional entry. Enter the release number of the connector.

trusted

This is a mandatory entry and present only in the section for trusted source configuration. Set the value of the entry to true, if you are configuring your target system as a trusted source.

provisionDatasetFile

This is an optional entry and present only in the section for target resource configuration. Specify a value for this entry only if you are using Oracle Identity Manager release 11.1.1.x and you want to generate request datasets to perform request-based provisioning operations.

Enter the name and relative path of the request dataset (an XML file) that specifies information to be submitted by the requester during a create user provisioning operation.

Note:

To easily identify files of a specific target system installation, it is recommended that the names of this generated XML file (for both provisioning and modification) be prefixed with the name of the IT resource for the target system.

Sample value: ProvisionResource_DBATUser.xml

modifyResourceDatasetFile

This is an optional entry and present only in the section for target resource configuration. Specify a value for this entry only if you are using Oracle Identity Manager release 11.1.1.x and you want to generate request datasets to perform request-based provisioning operations.

Enter the name and relative path of the request dataset (an XML file) that specifies information to be submitted by the requester during an update user provisioning operation.

Sample value: ModifyProvisionedResource_DBATUser.xml

requestDMDatasetsFile

This is also an optional entry present only in the section for target resource configuration. Specify a value for this entry only if you are using Oracle Identity Manager release 11.1.1.x and you want to generate request datasets that can be imported by using the Deployment Manager to perform request-based provisioning.

Enter the name and relative path of the request dataset (an XML file) that specifies information to be submitted by the requester during provisioning operations.

Sample value: Datasets.xml

bundleJar

This is a mandatory entry. Enter the name and relative path of the JAR file containing the ICF bundle that the DBAT generator will use.

Default value: ../lib/org.identityconnectors.databasetable-1.2.2.jar

Do not change the value of this entry.

config

This is a mandatory entry in which you specify information about the connector configuration. This connector configuration contains information about the manner in which the connector must behave and connect to the target system. Note that this connector can be configured to connect to the target system by using one of the following methods:

JDBC Driver Configuration

The following are the two ways in which the connector can be configured to connect to the target system by using JDBC driver configurations:

- Specify a value for the jdbcUrlTemplate property that contains wildcard values such as %h, %p, and %d. The wildcard values are replaced with the actual values specified for the host, port, and database properties. In this configuration method, specifying values for the host, port, and database properties are mandatory.

- Specify an exact URL template as the value of the jdbcUrlTemplate property. In other words, the URL template must not contain wildcard values. In addition, specify a value for the user property.

DataSource Configuration

In this configuration method, you must,

- Specify a value for the datasource property. In addition, specify a value for the jndiProperties property if the datasource is bound to JNDI entities.

- Ensure wlfullclient.jar and JDBC driver files exists in the lib directory of dbat generator directory along with other jars.

- Add Java property -Dweblogic.jdbc.remoteEnabled=true in Weblogic OIM Domain Environment script and restart Weblogic server.

Table 2-1 lists and describes the properties of the Config entry.

Table 2-1 Properties of the Config Entry

Property Type Required for JDBC Driver Configuration? Required for DataSource Configuration? Default Value Description

table

String

Yes

Yes

NA

Name of the parent table or view that contains user records.

keyColumn

String

Yes

Yes

NA

Name of the column that uniquely identifies each row in the parent table.

passwordColumn

String

No

No

NA

Name of the column in the parent table that holds the passwords of the target system records.

You must specify a value for this property if both the following conditions are true:

- There exists a column in the parent table that holds passwords of the target system records.

- You want to perform the reset account password provisioning operation.

user

String

Yes

No

NA

User ID of the database user account that Oracle Identity Manager will use to connect to the target system

password

String

Yes

No

NA

Password of the database user account that Oracle Identity Manager must use to connect to the target system. For security reasons, this property is commented by default. Therefore, do not uncomment this property. When you run the DBATGenerator.cmd file, you will be prompted to enter the password.

See Discover the Schema and Generate the Connector for more information about running the DBAT Generator.

jdbcUrlTemplate

String

Yes(%h, %p, and, %d)

No

NA

JDBC URL template of the target database with the %h, %p, and %d wildcards.

For IBM DB2: jdbc:db2://%h:%p/%d

For Microsoft SQL Server: jdbc:sqlserver://%h:%p;databaseName=%d

For MySQL: jdbc:mysql://%h:%p/%d

For Oracle Database: jdbc:oracle:thin:@%h:%p:%d

For Sybase Adaptive Server Enterprise: jdbc:sybase:Tds:%h:%p/%d

See Determining the Value for the jdbcUrlTemplate Property for more information.

jdbcDriver

String

Yes

Yes

NA

JDBC driver class name.

For IBM DB2: com.ibm.db2.jcc.DB2Driver

For Microsoft SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver

For MySQL: com.mysql.jdbc.Driver

For Oracle Database: oracle.jdbc.driver.OracleDriver

For Sybase Adaptive Server Enterprise: com.sybase.jdbc3.jdbc.SybDriver

relationTables

String

No

No

NA

If user data is spread across parent and child tables, then enter a comma-separated list of child table names.

Sample value: USER_ROLE, USER_GROUP

Note: In addition to a foreign key, if your child table does not contain any other column that is unique, not null, or primary, then generation of the XML file fails. See Discover the Schema and Generate the Connector for information about generating the XML file.

statusColumn

Boolean

No

No

NA

Name of the column in the target system that holds the status of a user record. You must specify a value for this attribute only if both the following conditions are true:

- You want to perform the enable user account or disable user account provisioning operations.

- There exists a column in the target system that holds the status of a user record.

enableValue

String

No

No

NA

Value used on the target system that depicts that a user record is in the enabled status.

disableValue

String

No

No

NA

Value used on the target system that depicts that a user record is in the disabled status.

database

String

Yes, when %d

No

NA

Name of the target system database. Used in place of the %d wild card in the jdbcUrlTemplate property.

host

String

Yes, when %h

No

NA

Host name or IP address of the computer hosting the target system. Used in place of the %h wild card in the jdbcUrlTemplate property.

port

String

Yes, when %p

No

NA

Port number at which the target system is listening. Used in place of the %p wild card in the jdbcUrlTemplate property.

datasource

String

No

Yes

NA

Name of the data source when the connector uses the datasource configuration to connect to the target system.

Sample Value: jdbc/operationsDB

jndiProperties

String

No

Yes

NA

Properties used to establish a connection with the target system by using JDBC drivers or look up a DataSource using JNDI.

Sample value: java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory, java.naming.provider.url=t3://acme.com:15000, java.naming.security.principal=weblogic, java.naming.security.credentials=weblogic1

customizedQuery

String

No

No

NA

A WHERE clause specifying the subset of newly added or modified records that you want to reconcile.

See Specifying a Value for the customizedQuery Parameter for more information on the customizedQuery property.

rethrowAllSQLExceptions

Boolean

No

No

false

If the value of this property is set to false, then SQL exceptions with a zero (0x00) error code are considered a success. In other words, SQL exceptions with the zero error code are caught and suppressed by the SQL statement.

If the value of this property is set to true, then all SQL exceptions with the zero error code result.

Note: No other exceptions SQL exceptions are influenced by this property.

allNative

Boolean

No

No

false

If the value of this property is set to false, then attribute data is converted to Strings by using the JDBC driver.

Set the value of this property to true to use the appropriate JDBC types and to force the connector to perform the conversion.

The dateFormat and TimestampFormat properties invalidate this setup.

validConnectionQuery

String

No

No

NA

If no value is specified for this property, then the connection is validated by switching the auto commit mode. For example, you might have the following query, which might be more efficient for some databases:

SELECT 1 FROM DUMMY

dateFormat

String

No

No

dd/MM/yyyy

Allows the user to format how date data is converted to strings. However, if you want to change the date format from text to a date editor, then you must set the value of the dateFormat IT resource parameter to the date format specified in the system configuration of Oracle Identity Manager.

Specifying a value for this property invalidates the allNative property.

timestampFormat

String

No

No

dd/MM/yyyy HH:mm:ss:SSS

Allows the user to format how timestamp data is converted to strings. Specifying this property invalidates the nativeTimestamps and allNative properties.

enableEmptyString

Boolean

No

No

false

Set the value of this property to true if you want to enable support for writing an empty string instead of a NULL value.

If the value of this property is set to false, then empty strings are written as NULL values.

Note: This property can be applied only to mandatory String attributes.

quoting

String

No

No

None

If you are using protected keywords as names of columns in your target system, then use quoting, which displays column names between quoting properties (such as single quotes, double quotes, and so on) in the generated SQL when accessing the database.

If you do not want to use quoting, then specify None.

If you want use to use quoting, then specify one of the following quoting properties:

- For DB2 running on IBM Mainframes: Single

- For DB2 running on MS Windows: Double

- For MS SQL Server: Brackets or Double

- For MySQL: Back

- For Oracle: Double

- For Sybase: Double

Note: Using the "WHERE" keyword as a column name is not supported.

changeLogColumn

String

No

No

NA

Optional name of the column where the last update-related number, non-decreasing, date or timestamp-based values are stored. Can also be a column name storing values that are not date or time stamp based (for example, numeric or strings).

The data type of this column can be any of the data types supported by the target system. However, if you are using Oracle Database, then data types such as BLOB, CLOB, and LONG are not supported. See About Supported Data Types for information about data types supported for your target system.

The values in this column are used during incremental reconciliation to determine the newest or most youngest record reconciled from the target system.

Note: You must specify a value for this property if you want to perform incremental reconciliation.

nativeTimestamps

Boolean

No

No

false

If the value of this property is set to false, then timestamp data is read as Strings by using the JDBC driver, which can cause a loss of time in milliseconds.

If the value of this property is set to true, then timestamp data is retrieved as java.sql.Timestamp type by the connector.

createScript

String

No

No

None

This property is present only in the section for target resource configuration.

Specify a value for this property only if you want to configure the connector to use custom stored procedures or SQL statements rather than default SQL statements for performing provisioning operations.

Enter the Groovy script or the file URL of the Groovy script created for the create user account provisioning operation. When this script is called, the parent form data is added.

You must enter the file URL in the following format:

file:///URL

Sample value: file:///home/jdoe/dbat/scripts/create_user.groovy

See Configuring the Connector for Stored Procedures and Groovy Scripts for more information on configuring the connector to use custom stored procedures.

updateScript

String

No

No

None

This property is present only in the section for target resource configuration.

Specify a value for this property only if you want to configure the connector to use custom stored procedures or SQL statements rather than default SQL statements for performing provisioning operations.

Enter the Groovy script or the file URL of the Groovy script created for the update user account provisioning operation. This script is called when you update the parent form, or enable or disable the user account.

You must enter the file URL in the following format:

file:///URL

Sample value: file:///home/jdoe/dbat/scripts/update_user.groovy

See Configuring the Connector for Stored Procedures and Groovy Scripts for more information on configuring the connector to use custom stored procedures.

deleteScript

String

No

No

None

This property is present only in the section for target resource configuration.

Specify a value for this property only if you want to configure the connector to use custom stored procedures or SQL statements rather than default SQL statements for performing provisioning operations.

Enter the Groovy script or the file URL of the groovy script created for the delete user account provisioning operation. This script is called when you remove or delete an account without child data.

You must enter the file URL in the following format:

file:///URL

Sample value: file:///home/jdoe/dbat/scripts/delete_user.groovy

See Configuring the Connector for Stored Procedures and Groovy Scripts for more information on configuring the connector to use custom stored procedures.

lookupScript

String

No

No

None

This property is present only in the section for target resource configuration.

Specify a value for this property only if you want to configure the connector to use custom stored procedures or SQL queries rather than default SQL queries to perform lookup field synchronization.

Enter the Groovy script or the file URL of the Groovy script created for lookup field synchronization.

You must enter the file URL in the following format:

file:///URL

Sample value: file:///home/jdoe/dbat/scripts/lookup_field_sync.groovy

See Configuring the Connector for Stored Procedures and Groovy Scripts for more information on configuring the connector to use custom stored procedures.

addMultiValuedAttributeScript

String

No

No

None

This property is present only in the section for target resource configuration.

Specify a value for this property only if you want to configure the connector to use custom stored procedures or SQL statements rather than default SQL statements for performing provisioning operations.

Enter the Groovy script or the file URL of the Groovy script created for the add multivalued attribute provisioning operation. This script is called when you add multivalued child attributes.

You must enter the file URL in the following format:

file:///URL

Sample value:

file:///home/jdoe/dbat/scripts/add_mulval_attr.groovy

See Configuring the Connector for Stored Procedures and Groovy Scripts for more information on configuring the connector to use custom stored procedures.

removeMultiValuedAttributeScript

String

No

No

None

This property is present only in the section for target resource configuration.

Specify a value for this property only if you want to configure the connector to use custom stored procedures or SQL statements rather than default SQL statements for performing provisioning operations.

Enter the Groovy script or the file URL of the Groovy script created for lookup field synchronization. This script is called while removing multivalued child attributes.

You must enter the file URL in the following format:

file:///URL

Sample value: file:///home/jdoe/dbat/scripts/remove_mulval_attr.groovy

See Configuring the Connector for Stored Procedures and Groovy Scripts for more information on configuring the connector to use custom stored procedures.

executeQueryScript

String

No

No

None

Specify a value for this property only if you want to configure the connector to use custom stored procedures or SQL queries rather than default SQL queries to perform reconciliation.

Enter the Groovy script or the file URL of the Groovy script created for reconciliation. The connector delegates the reconciliation operation to the Groovy script, which is responsible for passing the information (connector object) to the callback handler. This script is called while performing an account search (operations such as full and filtered reconciliation).

You must enter the file URL in the following format:

file:///URL

Sample value: file:///home/jdoe/dbat/scripts/recon_user.groovy

See Configuring the Connector for Stored Procedures and Groovy Scripts for more information on configuring the connector to use custom stored procedures.

syncScript

String

No

No

None

Specify a value for this property only if you want to configure the connector to use custom stored procedures or SQL queries rather than default SQL queries to perform incremental reconciliation.

Enter the Groovy script or the file URL of the Groovy script created for incremental reconciliation.

You must enter the file URL in the following format:

file:///URL

Sample value: file:///home/jdoe/dbat/scripts/increm_recon_user.groovy

See Configuring the Connector for Stored Procedures and Groovy Scripts for more information on configuring the connector to use custom stored procedures.

alias

The DBAT generator uses aliases to create relationships between the column or table names in the target system and resource object field names or process form field names in Oracle Identity Manager. In addition, the DBAT generator uses aliases to shorten long database names to meet the character-length restrictions on form names and form field names in Oracle Identity Manager. Aliasing can be used on column name, table name, form name, and form field name levels. Note that target system columns are represented as connector attributes.

Depending on the type of configuration, specify values for one of the following sections:

  • For trusted source configuration

    In the trusted source configuration section, you use the alias entry to map connector attributes or target system column names to OIM User form field names, including UDFs. The mappings that you specify here are used to populate entries in the Lookup.RESOURCE.UM.ReconAttrMap lookup definition for trusted source reconciliation.

    Note that some of the OIM User form field names do not have the same display name internally. For such fields, you must ensure that you map the connector attribute or target system column name to the internal name rather than the display name. The following table lists the names of the OIM User form display names and their corresponding internal names:

    Display Name Internal Name

    Organization

    Organization Name

    Manager

    Manager Login

    E-mail

    Email

    The following is the default value of the alias entry:

    ['__UID__':'User Login', '__NAME__':'Last Name', 'Organization':'Organization Name', 'Xellerate Type':'Xellerate Type', '__ENABLE__':'Status', 'Role':'Role']

    In the default value, note that the "Organization" connector attribute has been mapped to "Organization Name", which is the internal name.

    You cannot delete existing mappings in the default value. However, you can modify these mappings.

    The following is the format in which you must specify values for the alias entry:

    ['CONN_ATTR1 or COL_NAME1': 'OIM_FIELD1', 'CONN_ATTR2 or COL_NAME2': 'OIM_FIELD2', . . . 'CONN_ATTRn or COL_NAMEn': 'OIM_FIELDn']

    In this format:

    • CONN_ATTR is the connector attribute name.

    • COL_NAME is the target system column name.

    • OIM_FIELD is the name of OIM User field.

    See Table 4-12 for information about the __UID__ and __NAME__ attributes.

  • For target resource configuration

    In the target resource configuration section, you use the alias entry for one or all of the following purposes:

    • To set an alias for table names specified in the relationTables property.

    • To set an alias (a unique and shortened name) for the IT resource name specified in the itResourceName entry.

    • To map connector attributes or target system column names to fields of the process form. The mappings that you specify here are used to populate entries in the Lookup.RESOURCE.UM.ProvAttrMap and Lookup.RESOURCE.UM.ReconAttrMap lookup definitions. For all fields for which no alias is provided, a mapping is created based on the target system column names.

    By default, the DBATConfiguration.groovy file contains the following as the value of the alias entry:

    ['USER_ROLE':'RO', 'USER_GROUP':'GR']

    You can modify the default value to meet the requirements in your target system. For target system fields for which no alias is provided, will be created with the target attribute names

    If you want to add mappings for fields other than the ones already present in the alias entry, then you can add them either to the existing values in the alias entry, or add them to the alias + entry.

    The following is the default value of the alias + entry:

    ['__NAME__':'User ID']

    The following is the format in which you must specify values for the alias and alias + entry:

    ['CONN_ATTR1 or COL_NAME1': 'ALIAS_FIELD1', 'CONN_ATTR2 or COL_NAME2': 'ALIAS_FIELD2', . . . 'CONN_ATTRn or COL_NAMEn': 'ALIAS_FIELDn', . . . 'TABLE_NAME':'ALIAS','TABLE_NAME1':'ALIAS1','TABLE_NAME2':'ALIAS2', . . . 'TABLE_NAMEn':'ALIASn']

    In this format:

    • CONN_ATTR is the connector attribute name.

    • COL_NAME is the target system column name.

    • ALIAS_FIELD is the alias corresponding to the connector attribute or target system column name.

    • TABLE_NAME is the name of the table specified in the relationTables attribute.

    • ALIAS is the alias corresponding to the table name.

    See Table 4-10 for information about connectors attributes such as __NAME__.

    When you run the DBAT Generator (which is described later in this chapter), by using the information specified in the DBATConfiguration.groovy file, the connector package is created. The connector package contains an XML folder that in turn contains an XML file. This XML file contains definitions for connector objects such as IT resource type, IT resource, scheduled tasks, process forms, and adapters. The process form names are derived from the database table names, and then prefixed with UD_RESOURCE_NAME, where RESOURCE_NAME is replaced with the value of the itResourceName entry.

    The DBAT Generator automatically truncates a process form name if the number of characters in the process form name is more than 8. This might result in two forms having the same name, but the DBAT Generator prevents this from happening by using autonumbering. Therefore, you can specify an alias (a shortened name) to gain control over the autogenerated form name.

    This is illustrated by the following example:

    Assume that the resource name is DB and database table name is USER_ROLES. In addition, assume that Oracle Identity Manager contains a form by the name UD_DB_US.

    After you run the DBAT Generator, the process form is created and the form name is UD_DB_USER_ROLES. The number of characters in this process form name is 16. While importing the connector XML file into Oracle Identity Manager, the DBAT Generator truncates the process form name because it contains more than 8 characters. The truncated form name is UD_DB_US. Note that in Oracle Identity Manager, a form by the name UD_DB_US already exists.

    To avoid encountering such issues or forms with same names, specify a value for the alias attribute, as follows:

    alias = ['USER_ROLES':'RO']

    After you run the DBAT Generator, the process form name is UD_DB_RO, which contains 8 characters. Therefore, the process form name is not truncated.

prepopulate

This is an optional entry present only in the section for target resource configuration. Specify a value for this entry if you want Oracle Identity Manager to prepopulate OIM User fields while provisioning a target system resource.

By default, the value of this entry is as follows:

['USERID':'User Login', 'FIRSTNAME':'First Name', 'LASTNAME':'Last Name', 'EMAIL':'Mail Id', 'DESCRIPTION':'Description', 'SALARY':'Salary', 'JOININGDATE':'Join date']

This means that the groovy file is configured to prepopulate the following fields:

User Login

First Name

Last Name

Mail Id

Description

Salary

Join date

You can add fields to or remove fields from the preceding list. The following is the format in which you must specify values for the prepopulate entry:

['CONN_ATTR1 or COL_NAME1': 'OIM_FIELD1', 'CONN_ATTR2 or COL_NAME2': 'OIM_FIELD2', . . . 'CONN_ATTRn or COL_NAMEn': 'OIM_FIELDn']

In this format:

  • CONN_ATTR is the connector attribute name.

  • COL_NAME is the target system column name.

  • OIM_FIELD is the name of the OIM User field.

See Working with Prepopulate Adapters in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for more information about attaching and removing prepopulate adapters.

Configuring the DBATConfiguration.groovy File for a Target System with an Autoincrement Primary Key

In addition to configuring the DBATConfiguration.groovy file as discussed in Entries in the Predefined Sections, perform the following procedure if the key column of your target system has been configured with an autoincrement option:

  • For a target system that has been configured as a target resource:

    Ensure that the prepopulate entry of the DBATConfiguration.groovy file does not contain any mapping for the key column. Alternatively, do not provide the __NAME__ attribute mapping in the prepopulate entry.

    The same information has been discussed in the prepopulate entry of Entries in the Predefined Sections.

  • For a target system that has been configured as a trusted source:

    By default, the connector maps the key column of the table specified in the IT resource to the User Login field in Oracle Identity Manager. However, if the key column is configured with the autoincrement option, then in the alias entry, you can map the OIM User Login field to a different target system column.

    If you change the default mapping, then ensure that the __UID__ attribute is mapped to any corresponding field in Oracle Identity Manager.

    The same information has been discussed in the alias entry of Entries in the Predefined Sections.

Determining the Value for the jdbcUrlTemplate Property

This section discusses the jdbcUrlTemplate property. You apply the information in this section while performing the instructions described in Overview of Configuring the Groovy File.

The values that you specify for the jdbcUrlTemplate property depends on the target system:

jdbcUrlTemplate Property for IBM DB2

Enter the following component of the connection URL as the value of the jdbcUrlTemplate property:

jdbc:db2://[SERVER_NAME[\INSTANCE_NAME][:PORT_NUMBER]]/DATABASE_NAME

If you configure secure communication between Oracle Identity Manager and the target system, then enter the following as the value of the jdbcUrlTemplate property:

jdbc:db2://[SERVER_NAME[\INSTANCE_NAME][:PORT_NUMBER]]/DATABASE_NAME:sslConnection=true;sslTrustStoreLocation=LOCATION;sslTrustStorePassword=PASSWORD;

In both formats:

  • SERVER_NAME is the IP address (not the host name) of the target system host computer.

  • INSTANCE_NAME is the name of the target system database.

  • PORT_NUMBER is the port at which the target system database is listening.

  • DATABASE_NAME is the name of the database.

  • LOCATION is the full path and name of the trust store

  • PASSWORD is the password of the trust store location.

The following is a sample value for the jdbcUrlTemplate property:

jdbc:db2://192.168.16.76:50000/acmedb

jdbcUrlTemplate Property for Microsoft SQL Server

Enter the following component of the connection URL as the value of the jdbcUrlTemplate property:

jdbc:sqlserver://[SERVER_NAME[\INSTANCE_NAME][:PORT_NUMBER]];DATABASE=DATABASE_NAME

In this format:

  • SERVER_NAME is the IP address (not the host name) of the target system host computer.

  • INSTANCE_NAME is the name of the target system database.

  • PORT_NUMBER is the port at which the target system database is listening.

  • DATABASE_NAME is the name of the target system database

The following is a sample value for the jdbcUrlTemplate property:

jdbc:sqlserver://192.168.16.76:1433;Database=acmedb

jdbcUrlTemplate Property for MySQL

Enter the following component of the connection URL as the value of the jdbcUrlTemplate property:

jdbc:mysql://[SERVER_NAME][:PORT_NUMBER]/[DATABASE_NAME]

If you configure the connector to use custom stored procedures for performing provisioning operations and have specified a value for the updateScript property (see Table 2-1 for more information), then enter the following as the value of the jdbcUrlTemplate property:

jdbc:mysql://[SERVER_NAME][:PORT_NUMBER]/[DATABASE_NAME]?noAccessToProcedureBodies=true

If you configure secure communication between Oracle Identity Manager and the target system, then enter the following as the value of the jdbcUrlTemplate property:

jdbc:mysql://[SERVER_NAME][:PORT_NUMBER]/[DATABASE_NAME]?useSSL=true&trustCertificateKeyStoreType=KEYSTORE_TYPE&trustCertificateKeyStorePas
sword=PASSWORD&trustCertificateKeyStoreUrl=URL

In all the formats:

  • SERVER_NAME is the IP address (not the host name) of the target system host computer.

  • PORT_NUMBER is the port at which the target system database is listening.

  • DATABASE_NAME is the name of the target system database.

  • KEYSTORE_TYPE is the type of key store used for trusted certificates. The default is JKS.

  • PASSWORD is the password for the key store of trusted certificates.

  • URL is the URL to the key store of the trusted certificate.

The following is a sample value for the jdbcUrlTemplate property:

jdbc:mysql://192.168.1.251/mysql

jdbcUrlTemplate Property for Oracle Database

Enter the following component of the connection URL as the value of the jdbcUrlTemplate property:

jdbc:oracle:thin:@TARGET_HOST_NAME_or_IP_ADDRESS:PORT_NUM:sid

The following is a sample value for the jdbcUrlTemplate property:

jdbc:oracle:thin:@ten.mydomain.com:1521:cust_db

If you are using Oracle 12c PDB mode, specify the following as the jdbcUrlTemplate:

jdbc:oracle:thin:@//host:port/servicename

jdbcUrlTemplate Property for Oracle RAC

Enter the following component of the connection URL as the value of the jdbcUrlTemplate property:

Note:

The jdbcUrlTemplate property must not exceed 200 characters because of a restriction in the number of characters for the corresponding parameter in Oracle Identity Manager.

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=HOST1_NAME.DOMAIN)(PORT=PORT1_NUMBER))(ADDRESS=(PROTOCOL=TCP)(HOST=HOST2_NAME.DOMAIN)(PORT=PORT2_NUMBER))(ADDRESS=(PROTOCOL=TCP)(HOST=HOST3_NAME.DOMAIN)(PORT=PORT3_NUMBER)) . . . (ADDRESS=(PROTOCOL=TCP)(HOST=HOSTn_NAME.DOMAIN)(PORT=PORTn_NUMBER))(CONNECT_DATA=(SERVICE_NAME=ORACLE_DATABASE_SERVICE_NAME)))

The following is a sample value for the jdbcUrlTemplate property:

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST= host1.example.com)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST= host2.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME= srvce1)))

jdbcUrlTemplate Property for Sybase Adaptive Server Enterprise

Enter the following component of the connection URL as the value of the jdbcUrlTemplate property:

jdbc:sybase:Tds:SERVER_NAME:PORT_NUMBER/DATABSE_NAME

In this format:

  • SERVER_NAME is the IP address (not the host name) of the target system host computer.

  • PORT_NUMBER is the port at which the target system database is listening.

  • DATABSE_NAME is the name of the target system database.

The following is a sample value for the jdbcUrlTemplate property:

jdbc:sybase:Tds:172.21.109.62:9050/master

Discover the Schema and Generate the Connector

After configuring the DBATConfiguration.groovy file, you must run the DBAT Generator to discover the schema and generate the connector package.

Topics:

Running the DBAT Generator

The DBAT Generator is the DBATGenerator.cmd or DBATGenerator.sh file that is located in the dbat-generator-RELEASE_NUMBER/bin directory (created in Step 3 of Overview of Configuring the Groovy File).

To run the DBAT Generator:

  1. Copy the JDBC driver corresponding to your target system to the dbat-generator-RELEASE_NUMBER/lib/ directory. The JDBC drivers are listed in Table 1-1.
  2. In a command window, change to the dbat-generator-RELEASE_NUMBER/bin directory (for example, dbat-generator-11.1.1.6.0/bin) and run one of the following commands depending on the operating system that you are using:

    • For Microsoft Windows

      DBATGenerator.cmd CONFIG_FILE CONFIG_NAME

    • For UNIX

      DBATGenerator.sh CONFIG_FILE CONFIG_NAME

    In this command, replace:

    • CONFIG_FILE with the absolute or relative path name of the DBATConfiguration.groovy file.

    • CONFIG_NAME with the name of the configuration within the DBATConfiguration.groovy file, being used for the target system. The predefined configurations within this file are trusted and target. You can create additional custom configurations with different names depending on your requirements.

    The following is a sample command:

    DBATGenerator.cmd ..\resources\DBATConfiguration.groovy target

    In this command, "target" denotes the name of the section in the DBATConfiguration.groovy file for which values have been specified. In other words, the connector is being configured as a target resource.

  3. When prompted, enter a value for User Password, which is the password of the database user account that Oracle Identity Manager must use to connect to the target system.

If you encounter any errors while running the DBAT Generator, then you must fix it and then resume running the DBAT Generator. Missing JDBC drivers in the lib directory can lead to one of the most common errors encountered.

Understanding the Generated Connector Package

The connector package is a ZIP file that is generated in the /dbat-generator-RELEASE_NUMBER directory. For example, if you have specified ACME as the value of the itResourceDefName entry in the DBATConfiguration.groovy file, then the connector package ZIP (ACME.zip) file is generated in the /dbat-generator-11.1.1.6.0/directory. The directory structure of the connector package is as follows:

CONNECTOR_PACKAGE/
         bundle/
                  org.identityconnectors.databasetable-1.2.2.jar
         configuration/
                  IT_RES_DEF-CI.xml
         dataset/
         resources/
                  dbat-generator.properties
         xml/
                  IT_RES_DEF-ConnectorConfig.xml

In this directory structure:

  • CONNECTOR_PACKAGE is replaced with the name of the IT resource definition specified as the value of the itResourceDefName entry in the DBATConfiguration.groovy file.

  • IT_RES_DEF is replace with the name of the IT resource definition specified as the value of the itResourceDefName entry in the DBATConfiguration.groovy file.

The following behavior is observed after generation of the connector configuration XML file:

  • The length of a field (column) from the target system is not fetched into the process form. Therefore, except for the Unique ID and Password fields, the length of all other data fields (of the String data type) on the process form is always set to 255 characters. The length of the Unique ID and Password fields is set to 40 characters.

  • All columns in a database table that are not null are displayed as mandatory process form fields in Oracle Identity Manager.