Oracle® Fusion Middleware Developer's Guide for Oracle Identity Manager 11g Release 1 (11.1.1) E14309-05 |
|
![]() Previous |
![]() Next |
This chapter explains how to create and maintain Generic Technology Connectors. It contains these sections:
Providers are the starting point for developing generic technology connectors. Oracle Identity Manager provides a standard set of providers that you can use as building blocks of your generic technology connectors. For details about these providers, see Chapter 15, "Predefined Providers for Generic Technology Connectors".
If no suitable provider is available, you can develop a provider to fit your requirements. For details, see Chapter 16, "Creating Custom Providers for Generic Technology Connectors".
Finally, if generic technology connectors do not meet your integration requirements, you can make use of the programmatic options available with adapters. For details, see Part IV, "Requests and Approval Processes".
This section explains how to create generic technology connectors.
The procedure to create a generic technology connector is composed of the following steps:
As mentioned in Chapter 15, "Predefined Providers for Generic Technology Connectors", the following providers can be used as the building blocks of the generic technology connectors you create:
Reconciliation Transport Provider
Reconciliation Format Provider
Provisioning Transport Provider
Provisioning Format Provider
Transformation Provider
Validation Provider
See Section 14.2, "Functional Architecture of Generic Technology Connectors" for the definitions of these providers. Then, based on your knowledge of the data formats and data transport mechanisms supported by the target system, identify the providers that must be included in the generic technology connector that you create. If the target system supports multiple data formats and data transport mechanisms, you must select a single combination of the transport and format providers discussed in the first chapter. You cannot include, for example, multiple reconciliation format providers in a single generic technology connector.
Identify the predefined providers that can be used to meet your provider requirements. See Chapter 15, "Predefined Providers for Generic Technology Connectors" for information about the predefined providers.
If all your provider requirements are addressed by the predefined providers, you need not create custom providers. You must create custom providers to address only the requirements that are not addressed by the predefined providers. See Chapter 16, "Creating Custom Providers for Generic Technology Connectors" for information about creating custom providers.
You must address the following prerequisites:
If you are creating the generic technology connector on a production server, enable the cache for the following cache categories:
GenericConnector
GenericConnectorProviders
See "Optimal Cache Configuration for a Production Environment" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for more information.
Testing connectivity between the target system server and the Oracle Identity Manager server
You must take steps to ensure that connectivity can be established between the target system server and the Oracle Identity Manager server. For example, in a UNIX environment, you must enter the fully qualified host name of the Oracle Identity Manager server in the /etc/hosts
file on the target system server.
Creating the user account to be used for creating the generic technology connector
All users belonging to the SYSTEM ADMINISTRATORS
group of Oracle Identity Manager can create generic technology connectors. Alternatively, members of a group to which you assign the required menu items and permissions can create generic technology connectors.
The required menu items are as follows:
Create Generic Technology Connector menu item
Manage Generic Technology Connector menu item
The required permissions are as follows:
Form Designer (Allow Insert, Write Access, Delete Access)
Structure Utility.Additional Column (Allow Insert, Write Access, Delete Access)
Meta-Table Hierarchy (Allow Insert, Write Access, Delete Access)
If these permissions are not correctly assigned to the group, an error is thrown when the user clicks the Create button on the final Administrative and User Console page for creating generic technology connectors.
To navigate to the first Administrative and User Console page for creating a generic technology connector, login to the Administrative and User Console, click Advanced, and under Configuration, click Create Generic Connector.
From this point onward, page-wise instructions are provided in the following sections:
To provide basic information about the generic technology connector that you want to create, use this page as follows
In the Name field, specify a name for the generic technology connector.
The following are guidelines related to selecting a name for the generic technology connector:
The name must not be the same as that of any other connector (predefined connector or generic technology connector) on this Oracle Identity Manager installation.
The name must not be the same as that of any other connector object (such as resource objects, IT resources, and process forms) on this Oracle Identity Manager installation.
Note: An error message is displayed if you specify a name that is the same as the name of an existing connector. However, an error message is not displayed if you specify a name that is the same as the name of an existing connector object. Therefore, you must ensure that the name you want to specify is not the same as the name of any existing connector object.See Section 14.4, "Connector Objects Created by the Generic Technology Connector Framework" for more information about connector objects that are automatically created as part of the generic technology connector creation process. |
The name must not contain non-ASCII characters, because Oracle Identity Manager does not support non-ASCII characters in connector names. However, you can include the underscore character (_) in the name.
See Also: Section 18.2.1, "Names of Generic Technology Connectors and Connector Objects" for information about limitations related to the names of generic technology connectors. |
If you want to use the generic technology connector for reconciliation, select Reconciliation and perform the following steps:
From the Transport Provider list, select the reconciliation transport provider that you want to use for this connector. This list displays the predefined reconciliation transport providers and the reconciliation transport providers that you create.
From the Format Provider list, select the reconciliation format provider that you want to use for this connector. This list displays the predefined reconciliation format providers and the reconciliation format providers that you create.
Note: If you select the shared drive reconciliation transport provider, you must also select the CSV reconciliation format provider because all the parameters of this provider are bundled with the parameters of the shared drive reconciliation transport provider. |
If you want to use the connector to perform trusted source reconciliation with the target system, select Trusted Source Reconciliation.
Note: If you select the Trusted Source Reconciliation check box, the Provisioning region of the page is disabled. This is because you cannot provision to a target system that you designate as a trusted source. You can only reconcile data from a trusted source. |
If you want to use the generic technology connector for provisioning, select Provisioning and perform the following steps:
Note: You can select only Reconciliation, only Provisioning, or both Reconciliation and Provisioning. |
From the Transport Provider list, select the provisioning transport provider that you want to use for this connector. This list displays the predefined provisioning transport providers and the provisioning transport providers that you create.
If you select the Web Services provisioning transport provider and if Secure Sockets Layer (SSL) is enabled for the target Web service, you must perform the procedure described in Section 15.4.1, "Configuring SSL Communication Between Oracle Identity Manager and the Target System Web Service".
From the Format Provider list, select the provisioning format provider that you want to use for this connector. This list displays the predefined provisioning format providers and the provisioning format providers that you create.
If you select the SPML provisioning format provider, you must also select the Web Services provisioning transport provider because the parameters of this provider are related to the parameters of the Web Services provisioning transport provider.
Click Continue.
Table 17-1 lists sample entries for the GUI elements on the Step 1: Provide Basic Information page.
Table 17-1 Sample Entries for the Step 1: Provide Basic Information Page
Label on the Step 1: Provide Basic Information Page | Sample Value or Action | Reference Information |
---|---|---|
Name field |
MyGTC2 |
NA |
Reconciliation check box |
Check box selected |
NA |
Transport Provider list |
Shared Drive |
shared drive reconciliation transport provider |
Format Provider list |
CSV |
CSV Reconciliation format provider |
Provisioning check box |
Check box selected |
NA |
Transport Provider list |
Web Services |
Web Services provisioning transport provider |
Format Provider list |
SPML |
SPML provisioning format provider |
Figure 17-1 shows the Step 1: Provide Basic Information page on which the entries described in Table 17-1 have been made.
Use this page to specify values for the parameters of the providers that you select on the Step 1: Provide Basic Information page.
On this page, the provider parameters are divided into two categories:
See Also: Chapter 15, "Predefined Providers for Generic Technology Connectors" for detailed information about the run-time parameters of predefined providers that you select on the Step 1: Provide Basic Information page |
Run-time parameters are input variables of the providers that you select on the previous page. A run-time parameter represents a value that is not constrained by the design of the provider. For example, the location of the directories containing the data files that you want to reconcile is a run-time parameter.
The parameters listed in this section are either design parameters of providers or reconciliation-specific parameters that are common to all generic technology connectors. A design parameter represents a value or set of values that is defined as part of the provider design.
See Also: Chapter 15, "Predefined Providers for Generic Technology Connectors" for detailed information about the design parameters of predefined providers that you select on the Step 1: Provide Basic Information page |
For example:
The format of data files that can be parsed by a format provider is a design parameter for that provider. While designing the provider, you define the set of formats the provider can parse. On the Step 2: Specify Parameter Values page, you specify the particular format (from the set of supported formats) that an instance of the format provider must parse.
The following are reconciliation-specific design parameters:
Note: If you do not select the Reconciliation option on the previous page, these reconciliation-specific design parameters are not displayed on this page. |
Use this parameter to specify a batch size for the reconciliation run. By using this parameter, you can break into batches the total number of records that the reconciliation engine fetches from the target system during each reconciliation run.
The default value of this parameter is All
.
During reconciliation, data from the reconciliation format provider is accepted as input by the validation provider. Some of the reconciliation data records may not clear the validation checks. You can use the Stop Reconciliation Threshold parameter to automatically stop reconciliation if the percentage of records that fail the validation checks to the total number of reconciliation records processed exceeds the specified value.
The following example illustrates how this parameter works:
Suppose you specify 20 as the value of the Stop Reconciliation Threshold parameter. This means that you want reconciliation to stop if the percentage of failed records to the total number of records processed becomes equal to or greater than 20. Suppose the second and eighth records fail the validation checks. At this stage, the number of failed records is 2 and the total number of records processed is 8. The percentage of failed records is 25, which is greater than the specified threshold of 20. Therefore, reconciliation is stopped after the eighth record is processed.
Note:
|
The default value of this parameter is None
. This default value specifies that during a reconciliation run, you want all the target system records to be processed, regardless of the number of records that fail the checks.
Stop Threshold Minimum Records
If you use the Stop Reconciliation Threshold parameter, there may be a problem if invalid records are encountered right at the beginning of the reconciliation run. For example, suppose you specify 40 as the value of the Stop Reconciliation Threshold parameter. When reconciliation starts, suppose the first record fails the validation checks. At this stage, the percentage of failed records to total records processed is 100. Therefore, reconciliation would stop immediately after the first record is processed.
To avoid such situations, you can use the Stop Threshold Minimum Records parameter in conjunction with the Stop Reconciliation Threshold parameter. The Stop Threshold Minimum Records parameter specifies the number of records that must be processed by the validation provider before the Stop Reconciliation Threshold validation is enabled.
The following example illustrates how this parameter works:
Suppose you specify the following values:
Stop Reconciliation Threshold: 20
Stop Threshold Minimum Records: 80
With these values, from the eighty-first record onward, the Stop Reconciliation Threshold validation is enabled. In other words, after the eightieth record is processed, if any record fails the validation check, the reconciliation engine calculates the percentage of failed records to total records processed.
The default value of this parameter is None
.
Note:
|
Use this parameter to specify whether you want the reconciliation engine to perform incremental or full reconciliation.
Note: The outcome of both full and incremental reconciliation is the same: target system records that are created or updated after the last reconciliation run are reconciled into Oracle Identity Manager. |
In incremental reconciliation, only target system records that are newly added or modified after the last reconciliation run are brought to Oracle Identity Manager. Reconciliation events are created for each of these records.
In full reconciliation, all target system records are brought to Oracle Identity Manager. The optimized reconciliation feature identifies and ignores records that have already been reconciled. Reconciliation events are created for the remaining records.
You must select incremental reconciliation if either one of the following conditions is true:
The target system time stamps or uniquely marks (in some way) files or individual data records that it generates, and the reconciliation transport provider can recognize records that have been time stamped or marked by the target system.
For example:
Suppose the target system can time stamp the creation of or modifications to user data records. If you can create a custom reconciliation transport provider that can read this time-stamp information, only new or modified data records will be transported to Oracle Identity Manager during reconciliation.
The target system provides only data records that are newly added or modified after the last reconciliation run.
If neither of these conditions is true, you must select full reconciliation.
Reconcile Deletion of Multivalued Attribute Data
Use this parameter to specify whether or not you want to reconcile into Oracle Identity Manager the deletion of multivalued attribute data (child data) on the target system.
The following example explains how this design parameter works:
There is an account for user John Doe
on the target system. This user is a member of two user groups, CREATE USERS
and REVIEW PERMISSIONS
, on the target system. This user account (along with the group membership information) also exists on Oracle Identity Manager.
On the target system, suppose this user is removed from the REVIEW PERMISSIONS
group. During the next reconciliation run, the action that will be taken in Oracle Identity Manager depends on whether or not you select the Reconcile Deletion of Multivalued Attribute Data check box:
If you select the check box, information about this user being a member of the REVIEW PERMISSIONS
group on the target system is removed from the Oracle Identity Manager database. All other changes made to this user account on the target system are also reconciled.
If you do not select the check box, information about this user being a member of the REVIEW PERMISSIONS
group on the target system is not removed from the Oracle Identity Manager database. However, all other changes made to this user account on the target system are reconciled.
Use this parameter to specify the format in which date values are stored in the target system.
The format that you specify is used to validate date values fetched during reconciliation and to convert the date values to the format used internally by Oracle Identity Manager.
The Validate Date Format provider is one of the predefined validation providers. During a reconciliation run, the Validate Date Format provider uses the source date format to validate date values fetched from the target system. Only date values that match the source date format are converted to the date format used by Oracle Identity Manager and reconciled. This format validation and conversion applies to all date fields (for example, Date of Birth and Hire Date) of the target system.
For information about the date formats that you can specify, see the following page on the Sun Java Web site:
http://java.sun.com/docs/books/tutorial/i18n/format/simpleDateFormat.html
Note: If you want the source date format to be used in date validation, while performing the procedure described in Section 17.2.4.3.1, "Adding or Editing Fields in Data Sets", you must:
|
The default value of the Source Date Format parameter is the date format specified as the value of the XL.DefaultDateFormat
system property. If you do not specify a value for the Source Date Format parameter, the default date format is used for date validation during reconciliation.
See Also: "System Properties in Oracle Identity Manager" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for information about the system properties of Oracle Identity Manager |
The following example illustrates how the Source Date Format parameter is used:
Suppose the following are date values in the target system:
Date 1: 05/04/2007 06:25:44 PM
Date 2: 05/06/2007 07:31:44 PM
Date 3: Thu, Apr 9, '98
Date 4: 07/03/2008 02:15:55 PM
Scenario 1:
While creating the connector, you had entered the following as the value of the Source Date Format parameter:
MM/dd/yyyy hh:mm:ss a
During a reconciliation run, the record containing the Date 3 value is not reconciled because it does not conform to the specified source date format.
Scenario 2:
While creating the connector, you had not entered a value for the Source Date Format parameter. Therefore, during a reconciliation run, all four records are validated against the date format specified as the value of the XL.DefaultDateFormat
system property.
The following is a provisioning-specific design parameter:
Note: If you do not select the Provisioning option on the previous page, this provisioning-specific design parameter is not displayed. |
Use this parameter to specify the format in which you want to send date values to the target system during provisioning operations.
During a provisioning operation, date values are converted to the format that you specify as the value of the Target Date Format parameter. This format conversion applies to all date fields (for example, Date of Birth and Hire Date) that are used in the provisioning operation.
For information about the date formats that you can specify, see the following page on the Sun Java Web site:
http://java.sun.com/docs/books/tutorial/i18n/format/simpleDateFormat.html
If you do not specify a date format, the following date format is used as the default value of this parameter:
yyyy/MM/dd hh:mm:ss z
The following example illustrates how the Target Date Format parameter is used:
During a provisioning operation, any date value that you enter will be in the yyyy/MM/dd hh:mm:ss z
format.
Scenario 1:
While creating the connector, you had entered the following as the value of the Target Date Format parameter:
yyyy.MM.dd G 'at' hh:mm:ss z
During a provisioning operation, an Oracle Identity Manager date value (for example, 2007/05/04 06:25:44 IST) will be converted into the target date format (for example, 2007.05.04 AD at 06:25:44 IST) and sent to the target system.
Scenario 2:
While creating the connector, you had not entered a value for the Target Date Format parameter. During a provisioning operation, date values are sent to the target system in the (default) yyyy/MM/dd hh:mm:ss z
format.
After you specify values for the run-time and design parameters, click Continue.
Table 17-2 lists sample entries for the Step 2: Specify Parameter Values page. The GUI elements displayed on this page are based on the entries made on the Step 1: Provide Basic Information page.
Table 17-2 Sample Entries for the Step 2: Specify Parameter Values Page
Label on the Step 2: Specify Parameter Values Page | Sample Value or Action | Reference Information |
---|---|---|
Run-Time Parameters of the Shared Drive Reconciliation Transport Provider |
Section 15.1, "Shared Drive Reconciliation Transport Provider" |
|
Staging Directory (Parent Identity Data) field |
D:\gctestdata\commaDelimited\parent |
NA |
Staging Directory (Multivalued Identity Data) field |
D:\gctestdata\commaDelimited\child |
NA |
Archiving Directory field |
D:\gctestdata\commaDelimited\archive |
NA |
File Prefix field |
file |
NA |
Specified Delimiter field |
, |
NA |
Tab Delimiter check box |
Check box not selected |
NA |
Fixed Column Width field |
NA |
|
Unique Attribute (Parent Data) field |
UserIDTD |
NA |
Run-Time Parameter of the Web Services Provisioning Transport Provider |
Section 15.4, "Web Services Provisioning Transport Provider" |
|
Web Service URL field |
http://acme123:8080/spmlws/services/HttpSoap11 |
NA |
Run-Time Parameters of the SPML Provisioning Format Provider |
Section 15.3, "SPML Provisioning Format Provider" |
|
Target ID field |
target |
NA |
User Name (authentication) field |
xelsysadm |
NA |
User Password (authentication) field |
NA |
|
Design Parameters of the Shared Drive Reconciliation Transport Provider |
Section 15.1, "Shared Drive Reconciliation Transport Provider" |
|
File Encoding field |
Cp1251 |
NA |
Design Parameters of the Web Services Provisioning Transport Provider |
Section 15.4, "Web Services Provisioning Transport Provider" |
|
Web Service SOAP Action field |
http://xmlns.oracle.com/OIM/provisioning//processRequest |
NA |
Design Parameters of the SPML Provisioning Format Provider |
Section 15.3, "SPML Provisioning Format Provider" |
|
WSSE Configured for SPML Web Service? check box |
Check box not selected |
NA |
Custom Authentication Credentials Namespace field |
http://xmlns.oracle.com/OIM/provisioning |
NA |
Custom Authentication Header Element field |
OIMUser |
NA |
Custom Element to Store User Name field |
OIMUserId |
NA |
Custom Element to Store Password field |
OIMUserPassword |
NA |
SPML Web Service Binding Style (DOCUMENT or RPC) field |
RPC |
NA |
SPML Web Service Complex Data Type field |
NA |
|
SPML Web Service Operation Name field |
processRequest |
NA |
SPML Web Service Target Namespace field |
http://xmlns.oracle.com/OIM/provisioning |
NA |
SPML Web Service Soap Message Body Prefix field |
NA |
|
ID Attribute for Child Dataset Holding Group Membership Information field |
NA |
|
Generic Design Parameters |
NA |
|
Target Date Format field |
yyyy-MM-dd hh:mm:ss.fffffffff |
NA |
Batch Size field |
All |
NA |
Stop Reconciliation Threshold field |
None |
NA |
Stop Threshold Minimum Records field |
None |
NA |
Source Date Format field |
yyyy/MM/dd hh:mm:ss z |
NA |
Reconcile Deletion of Multivalued Attribute Data check box |
Check box selected |
NA |
Reconciliation Type list |
Incremental |
NA |
Figure 17-2 shows the first section of the Step 2: Specify Parameter Values page on which the entries listed in Table 17-2 have been made.
Figure 17-3 shows the second section of the Step 2: Specify Parameter Values page on which the entries listed in Table 17-2 have been made.
Figure 17-4 shows the third section of the Step 2: Specify Parameter Values page on which the entries listed in Table 17-2 have been made.
Use this page to define data sets and mappings between the fields of the data sets. In other words, you use this page to specify the user data fields that you want to:
Propagate from the target system to Oracle Identity Manager during reconciliation
Propagate from Oracle Identity Manager to the target system during provisioning
In the generic technology connector context, the term metadata refers to the set of identity fields that constitute the user account information on the target system.
First Name, Last Name, Hire Date, and Department ID are examples of user data fields that constitute metadata. The values assigned to these fields constitute the user data on the target system. For example, the identity information of user John Doe on the target system can be composed of the following fields:
First Name: John
Last Name: Doe
Hire Date: 04-December-2007
Department ID: Sales
. . .
After you click the Continue button on the Step 2: Specify Parameter Values page, the metadata displayed on the Step 3: Modify Connector Configuration page depends on the following factors:
Input provided on the Step 1: Provide Basic Information and Step 2: Specify Parameter Values pages
Availability of sample target system data
Oracle Identity Manager performs the following steps while attempting to detect metadata:
The reconciliation transport provider and reconciliation format provider try to fetch and parse metadata from the target system.
Together, the shared drive reconciliation transport provider and CSV reconciliation format provider can detect metadata from the target system. If you want custom providers to perform the same function, you must ensure that:
The Java code for the reconciliation transport provider contains an implementation of the getMetadata()
method of the ReconTransportProvider
interface.
The Java code for the reconciliation format provider contains an implementation of the parseMetadata()
method of the ReconFormatProvider
interface.
If these providers successfully fetch and parse metadata from the target system, Oracle Identity Manager uses information returned by them to display metadata and the following step is not performed.
If the reconciliation transport provider and reconciliation format provider cannot fetch and parse metadata from the target system, the provisioning transport provider and provisioning format provider try to perform this function.
The Web Services provisioning transport provider and SPML provisioning format provider cannot detect metadata from the target system. If you want custom providers to be able to detect metadata, you must ensure that:
The Java code for the provisioning transport provider contains an implementation of the defineMetadata()
method of the ProvisioningTransportProvider
interface.
The Java code for the provisioning format provider contains an implementation of the parseMetadata()
method of the ProvisioningFormatProvider
interface.
If the provisioning transport provider and provisioning format provider successfully fetch and parse metadata from the target system, Oracle Identity Manager uses information returned by these providers to display metadata. If these providers are not successful, only the default fields defined for any of the provisioning-specific providers that you select are displayed. For example, the ID
field of the OIM - Account data set and the objectClass
and containerID
fields of the provisioning staging data set are displayed by default. These data sets and fields are discussed later in this guide.
Figure 17-5 shows the Step 3: Modify Connector Configuration page for the sample entries listed at the end of the "Step 1: Provide Basic Information Page" and "Step 2: Specify Parameter Values Page" sections.
The data sets displayed on the Step 3: Modify Connector Configuration page are categorized as follows:
The Source data sets are displayed only if you select the Reconciliation option on the first page, regardless of whether or not you select the Provisioning option.
The reconciliation staging data sets are displayed only if you select the Reconciliation option on the Step 1: Provide Basic Information page, regardless of whether or not you select the Provisioning option.
The Oracle Identity Manager data sets are always displayed, regardless of the options you select on the Step 1: Provide Basic Information page. However, the OIM - Account data set and its child data sets are not displayed if you select the Trusted Source Reconciliation option on the Step 1: Provide Basic Information page.
The fields displayed in the OIM - User data set are predefined for the Oracle Identity Manager User. You can show or minimize the full list of OIM - User data set fields by clicking the arrow icon at the top of the data set. The following fields are displayed in the minimized state of the data set:
User ID
Password
First Name
Last Name
Note: If you select the Trusted Source Reconciliation option on the Step 1: Provide Basic Information Page, all the fields of the OIM - User data set are displayed and you cannot use the arrow icon to minimize the display. |
These fields constitute the minimum set of Oracle Identity Manager User fields for which values must be defined. You can designate some or all of the remaining OIM - User data set fields as mandatory Oracle Identity Manager User fields for your Oracle Identity Manager installation. You do this by ensuring that these fields always hold values when the Oracle Identity Manager User is created.
Note: Data set and field names that take up more than a certain amount of space are truncated and dots are displayed after the truncated part of the names. For example, the Deprovisioning Date field of the OIM - User data set is displayed as follows:
To view the full name of a field, you can click the edit icon for that field or the field to which that field is mapped. In the pop-up window, the field name that you want to view is on either the first page or the second page, depending on the data set to which the field belongs. |
You can add user-defined fields (UDFs) to the list of predefined Oracle Identity Manager User fields by using the Design Console. These UDFs are displayed in the OIM - User data set on the Step 3: Modify Connector Configuration page.
Depending on the options that you select on the Step 1: Provide Basic Information page, some fields are displayed by default on the Step 3: Modify Connector Configuration page:
ID
field
The ID
field is displayed by default in the OIM - Account data set, regardless of whether or not you select the Reconciliation option or Provisioning option on the Step 1: Provide Basic Information page. When an account is created, this field is used to store the value that uniquely identifies the account in Oracle Identity Manager and in the target system. For a particular user, this unique field is used to direct other operations, such as modify, delete, enable, disable, and child data operations.
Every target system would have a unique field for tracking the creation of and updates made to a user account. While creating a custom provisioning transport provider, you must ensure that the provider retrieves this unique field value from the target system at the end of a Create User operation. This value must be used to populate the ID
field of the OIM - Account data set.
During reconciliation, the value of the ID
field must come from the corresponding unique field of the reconciliation staging data set. To set this up, you must create a mapping between the two fields. The procedure to create a mapping is discussed later in this section.
Caution: If you select both the Provisioning and Reconciliation options while creating a generic technology connector and if you do not create a mapping between the ID field and the unique field of the target system, records that are linked through reconciliation cannot be used for provisioning operations (such as modify, delete, enable, disable, and child data operations). This is because the ID field is not populated in the linked records. |
The objectClass
field is displayed by default in the OIM - Account data set and provisioning staging data set only if you select the SPML provisioning format provider on the Step 1: Provide Basic Information page.
The containerID
field is displayed by default in the OIM - Account data set and provisioning staging data set only if you select the SPML provisioning format provider on the Step 1: Provide Basic Information page.
The provisioning staging data sets are displayed only if you select the Provisioning option on the first page, regardless of whether or not you select the Reconciliation option.
The display of data sets on the Step 3: Modify Connector Configuration page depends on the input that you provide on the Step 1: Provide Basic Information page and Step 2: Specify Parameter Values page. The display of fields within the data sets depends on whether or not metadata detection has taken place.
Note: Metadata detection does not take place if any of the following conditions are true:
|
This is illustrated by the following example:
Suppose you select only the Reconciliation option on the Step 1: Provide Basic Information page. In addition, metadata detection has not taken place. Under these conditions, the display of data sets and fields on the Step 3: Modify Connector Configuration page can be summarized as follows:
The following data sets are displayed:
Source
Reconciliation Staging
Oracle Identity Manager
The fields that constitute the data sets are not displayed.
In addition, if you had selected the Trusted Source Reconciliation option on the Step 1: Provide Basic Information page, the OIM - Account data set and its child data sets are not displayed.
In Table 17-3, Scenario 1 shows the outcome of this set of input conditions. The rest of the scenarios in this table describe the display of data sets and fields under the combination of input conditions listed in the first row and first column of the table.
Table 17-3 Display of Data Sets and Fields Under Various Input Conditions
Only Reconciliation Option Selected | Both Reconciliation and Provisioning Options Selected | Only Provisioning Option Selected | |
---|---|---|---|
Metadata detection has not taken place |
Scenario 1 The following data sets are displayed:
The fields that constitute the data sets are not displayed. If you select the Trusted Source Reconciliation option on the Step 1: Provide Basic Information page, the OIM - Account data set and its child data sets are not displayed. |
Scenario 2 The following data sets are displayed:
The fields that constitute the data sets are not displayed. |
Scenario 3 The following data sets are displayed:
The fields that constitute the data sets are not displayed. |
Metadata detection has taken place |
Scenario 4 The following data sets are displayed:
The fields that constitute the data sets are displayed. If you select the Trusted Source Reconciliation option on the Step 1: Provide Basic Information page, the OIM - Account data set and its child data sets are not displayed. |
Scenario 5 The following data sets are displayed:
The fields that constitute the data sets are displayed. |
Scenario 6 The following data sets are displayed:
The fields that constitute the data sets are displayed. |
See Also: Section 18.1.2, "Multi-language Support" for information about limitations related to the display of non-ASCII characters on this page |
Each flow line displayed on the Step 3: Modify Connector Configuration page represents a mapping (link) between two fields of different data sets. A mapping serves one of the following purposes:
Establishes a data flow path between fields of two data sets, for either provisioning or reconciliation
A mapping of this type forms the basis for validations or transformations to be performed on data.
Creates a basis for comparing (matching) field values of two data sets
The following are examples of matching-only mappings:
Mappings created between fields of the reconciliation staging data set and the OIM - User data set form the basis of a reconciliation rule.
A mapping between the unique field of the reconciliation staging data set and the ID
field of the OIM - Account data set helps identify the key field for reconciliation matching. Along with the ID field, other fields of the OIM - Account data set can be (matching-only) mapped to corresponding fields of the reconciliation staging data set to create a composite key field for reconciliation matching.
You can perform the following actions on the Step 3: Modify Connector Configuration page:
Identity fields detected through metadata detection are displayed on the Step 3: Modify Connector Configuration page. You can modify these fields and the mappings between them. If required, you can also add new fields on this page and create mappings between them.
The following is a summary of the actions that you can perform while adding or editing fields on the Step 3: Modify Connector Configuration page:
Note: These actions are described in detail in the procedure that follows this list. The procedure also describes the conditions that must be fulfilled before you can perform some of these actions. |
Default attributes (such as the data type and length) are assigned to the fields displayed through metadata detection. You must edit these fields to set the required attributes for them.
Note: Oracle Identity Manager can recognize date values fetched during reconciliation only if you set the Date data type for fields of the reconciliation staging data sets. In addition, if you have specified a value for the Source Date Format parameter on the Step 2: Specify Parameter Values page, you must map date fields of the Source data sets to the corresponding date fields of the reconciliation staging data sets.The Source Date Format parameter is described in Section 17.2.4.2, "Step 2: Specify Parameter Values Page". |
You can create transformation mappings between fields by using a transformation provider. While performing this action, you can use the predefined concatenation transformation provider or translation transformation provider, or a custom transformation provider that you have created.
You can create matching-only mappings between fields of the reconciliation staging data set and Oracle Identity Manager data sets. Matching-only mappings that you create between the reconciliation staging data set and the OIM - User data set forms the reconciliation rule. Matching-only mappings that you create between the reconciliation staging data set and the OIM - Account data set identifies the key field for reconciliation matching.
You can add a child data set to an existing data set.
You can encrypt the value of a field, both in the process form and in the database.
You can designate a field as a lookup field and select an input source for the field. The input source can be a lookup definition or a combination of columns from Oracle Identity Manager database tables.
You can configure user account status reconciliation.
If you want to configure user account status reconciliation, refer to the "Configuring Account Status Reconciliation" section.
To add or edit a field in a data set:
Note: The display of the GUI elements and pages described in the following steps depends on the data set in which you are adding or editing a field. For example, the Required and Encrypted check boxes are not displayed if you are adding or editing a field in a Source data set. |
Depending on whether you want to add or edit a field, click the Add icon for the data set or the edit icon for the field.
On the Step 1: Field Information page, specify values for the following GUI elements:
See Also: Section 17.2.4.3, "Step 3: Modify Connector Configuration Page" for information about validations applied to the names of fields |
Field Name: If you are adding a field, specify a name for the field. The field name that you specify must contain only ASCII characters, because non-ASCII characters are not allowed.
Mapping Action: Select the type of mapping that you want to create with this field as the destination field of the mapping. You can select one of the following mapping actions:
Select Create Mapping Without Transformation if you only want to create a one-to-one mapping between a source (input) field and the field that you are adding or editing, and you do not want to use a transformation provider.
Select the Remove Mapping option if you are editing the field and you want to remove the mapping for which this field is the destination field. The procedure to remove a mapping is covered in detail in the Removing Mapping Between Fields section.
The transformation mapping options displayed in the Mapping Action list are based on the predefined transformation providers and the custom transformation providers that you create. The following menu options correspond to the predefined transformation providers:
* Create Mapping With Concatenation
* Create Mapping With Translation
See Also: Section 15.5, "Transformation Providers" for information about these predefined transformation providers |
Apply the following guidelines while selecting a transformation mapping:
You can create transformation mappings only between fields of the following data sets:
- Source and Reconciliation Staging
- Oracle Identity Manager and Provisioning Staging
This means that, for example, you cannot create transformation mappings between a field in a reconciliation staging data set and a field in an Oracle Identity Manager data set.
You cannot create a 1-to-2 mapping with the following source and destination fields:
Source field: Unique field of the reconciliation staging data
Destination fields: User ID
field of the OIM - User data set and ID
field of the OIM - Account data set
This mapping is not supported. Instead, you must create a one-to-one mapping between the unique field of the reconciliation staging data and either the User ID
field (of the OIM - User data set) or the ID
field (of the OIM - Account data set).
Ensure that all the fields of provisioning staging data sets are mapped to corresponding fields of OIM - User and OIM - Account data sets.
When you create a mapping that has any field of the OIM - User data set as the source or destination field, the display of the OIM - User data set fields list is frozen in the position it was in (expanded or minimized) when the mapping was created. To unfreeze the display of the OIM - User data set so that you are able to use the arrow icon, you must remove all mappings that have any OIM - User data set field as the source or destination field.
A literal field can be used as one of the input fields of a transformation field. If you select the Literal option, you must enter a value in the field. You must not leave the field blank after selecting it.
See Section 17.2.4.3, "Step 3: Modify Connector Configuration Page" for information about limitations related to creating transformation mappings.
Matching Only: Select this check box if the field is to be used as the destination field of a matching-only mapping. As mentioned earlier in this document, you can create the following types of matching-only mappings:
Note: You must create matching-only mappings for both parent and child data sets. |
To create the reconciliation rule, you create matching-only mappings between fields of the reconciliation staging data set and the OIM - User data set. Each mapping represents a reconciliation rule element. If there are child data sets, you must ensure that the names of fields of the reconciliation staging data set that are input fields for the matching-only mappings are not used in any of the reconciliation staging child data sets.
To specify the key field for reconciliation matching, you create a matching-only mapping between the unique field of the reconciliation staging data set and the ID field of the OIM - Account data set. Along with the ID field, other fields of the OIM - Account data set can be (matching-only) mapped to corresponding fields of the reconciliation staging data set to create a composite key field for reconciliation matching.
Caution: If the name of a reconciliation staging field used in a matching-only mapping were to be reused as the name of a field in a reconciliation staging child data set, matching would not take place during a reconciliation run.This known issue is explained in the Modify Connector Config Page section . |
Create End-to-End Mapping: If you are adding a field, select this check box if you want the same field to be added in all the data sets that are displayed to the right of the data set in which you are adding the field.
Multi-Valued Field: Select this check box if you want to add a child data set. If you select this check box, the name that you specify in the Field Name field is used as the name of the child data set.
Note: If you select the Trusted Source Reconciliation check box on the Step 1: Provide Basic Information page, this check box (in selected or deselected state) is ignored. This is because the reconciliation of multivalued (child) data is not supported in trusted source reconciliation. |
Data Type: Select the data type of the field.
After metadata detection, the String data type is applied by default to all the fields of the reconciliation staging and OIM - Account data sets. Where required, you must use the Data Type list to specify the actual data type of each field.
Length: Specify the character length of the field.
Required: Select this check box if you want to ensure that the field always contains a value.
Encrypted: Select this check box if the value of the field must be stored in encrypted form in the Oracle Identity Manager database.
Password Field: Select this check box if the value of the field must be encrypted on the process form. Values of fields for which this check box is selected are displayed as asterisks (*) on the process forms.
Note: If you select the Encrypted and Password Field check boxes, see Section 17.5.3.3, "Password-Like Fields" for information about guidelines that you must follow. |
Lookup Field: Select this check box if you want to make the field a lookup field.
Click Continue.
If you select the Lookup Field check box on the Step 1: Field Information page, the Step 2: Lookup Properties page is displayed. On this page, you can select and specify values for any combination of the lookup properties described in Table 17-4.
Table 17-4 Lookup Properties
Lookup Property | Value |
---|---|
Column Names |
In the Property Value field, enter the name of the database column containing the values that must be displayed in the lookup window. If required, you can enter multiple database column names separated by commas. Note: If you select the Lookup Column Name property, you must also select the Column Names property, which is described later in this table. After you enter a value in the Property Value field, click Submit. The following SQL query can be used to illustrate how the Column Names and Lookup Column Name properties are used: SELECT USR_FIRST_NAME, USR_LOGIN, USR_LAST_NAME FROM USR Suppose you set the following as the values of the two properties: - Column Names: - Lookup Column Name: When the user selects a particular |
Column Captions |
In the Property Value field, enter the name of the column heading that must be displayed in the lookup window. If multiple columns are going to be displayed in the lookup window, enter multiple column captions separated by commas, for example, Organization Name, Organization Status. After you enter a value in the Property Value field, click Submit. |
Column Widths |
In the Property Value field, enter the character width of the column that must be displayed in the lookup window. This must be the same as the maximum length of the underlying field or column from which data values are drawn to populate the lookup field. If the lookup window is going to display multiple columns, enter multiple column widths separated by commas. After you enter a value in the Property Value field, click Submit. |
Lookup Query |
To specify a value for the Lookup Query property:
To correctly display the data returned from a query, you must add a For example, consider the following SQL query: SELECT usr_status FROM usr To view the data returned from the query, you must add the following entry to the lookupfield.header.users.status=User Status If the The syntax for a
lookupfield.header.column_code=display value
The By default, the following entries for lookup field column headers are already available in the lookupfield.header.lookup_definition.lookup_code_information .code_key=Value lookupfield.header.lookup_definition.lookup_code_information .decode=Description lookupfield.header.users.manager_login=User ID lookupfield.header.organizations.organization_name=Name lookupfield.header.it_resources.key=Key lookupfield.header.it_resources.name=Instance Name lookupfield.header.users.user_id=User ID lookupfield.header.users.last_name=Last Name lookupfield.header.users.first_name=First Name lookupfield.header.groups.group_name=Group Name lookupfield.header.objects.name=Resource Name lookupfield.header.access_policies.name=Access Policy Name |
Lookup Code |
In the Property Value field, enter the lookup definition code name. This code must generate all information pertaining to the lookup field, including lookup values and the text that is displayed with the lookup field when a lookup value is selected. The classification type of the lookup definition code must be of Lookup Type (that is, the Lookup Type option on the Lookup Definition form must be selected). To enter a lookup code, open the Lookup Definition form, query for the required code, and copy the code into the Property Value field. After you enter a value in the Property Value field, click Submit. Note: The Lookup Code property can be used to replace the combination of the Column Captions, Column Names, Column Widths, Lookup Column Name, and Lookup Query properties. In addition, the information contained in the Lookup Code property supersedes any values set in these five lookup properties. If you want to implement lookup fields reconciliation, create a scheduled task that populates the lookup code. |
Lookup Column Name |
In the Property Value field, enter the name of the database column containing the value that must be stored corresponding to the Column Names value selected by the user in the lookup window. If required, you can enter multiple database column names separated by commas. Note: If you select the Column Names property, you must also select the Lookup Column Name property. See the "Lookup Column Name" row in this table for more information about how these two properties are used. After you enter a value in the Property Value field, click Submit. |
Auto Complete |
If you enter If you do not want to let users filter the display of values in the lookup field, enter The default value of the Auto Complete property is After you enter a value in the Property Value field, click Submit. |
If you want to edit the value of a property that is displayed in the table on the Step 2: Lookup Properties page, select the edit option for that property and click Edit. If you want to remove a property that is displayed in the table, select the delete option for that property and click Delete.
After you specify properties for the lookup field, click Continue.
If you select a transformation option from the Mapping Action list on the Step 1: Field Information page, the Step 3: Mapping page is displayed. Use this page to define the transformation function that you want to perform on the input data to the field that you are adding. The steps to be performed depend on the transformation provider option (concatenation, translation, or custom transformation provider) that you select on the previous page:
If you select a predefined transformation provider (transformation, concatenation or translation), see Transformation Providers for detailed information about the procedure to specify parameter values for the predefined transformation provider. That section also provides detailed information about configuring user account status reconciliation.
You must use the translation transformation provider if you want to configure the reconciliation of user account status information. This procedure is described in Section 15.5.2, "Translation Transformation Provider".
After you specify values for the transformation provider, click Continue.
If required, select a validation check for the field and click Add. In other words, select the validation provider that you want to use.
The validation options displayed in this list are based on the predefined validation Providers and any custom validation Providers that you create.
Click Continue, and click Close.
If you do not want to perform any other action on the Step 3: Modify Connector Configuration page, click the Close button that is displayed at the top of the page. You must perform the previous step before you click this Close button.
To remove a field from a data set:
Click the Delete icon for that field.
If you do not want to perform any other action on the Step 3: Modify Connector Configuration page, click the Close button that is displayed at the top of the page.
To remove a mapping:
Click the edit icon for the destination field of the mapping that you want to remove.
Note: If the destination field itself is the source field for another mapping, that mapping is not removed. |
On the Step 1: Field Information page, select Remove Mapping from the Transformation list.
Click Continue.
On the last page, click Close.
If you do not want to perform any other action on the Step 3: Modify Connector Configuration page, click the Close button that is displayed at the top of the page.
To remove a child data set:
Click the Delete icon for the data set.
If you do not want to perform any other action on the Step 3: Modify Connector Configuration page, click the Close button that is displayed at the top of the page.
Figure 17-6 shows the Step 3: Specify Connector Configuration page after the MyField
field was added to the OIM - Account and provisioning staging data sets.
Use this page to specify form names for the process forms corresponding to the OIM - Account data set and its child data sets.
Note: If you select the Trusted Source Reconciliation option on the Step 1: Provide Basic Information page, the OIM - Account data set and its child data sets are not created. Therefore, this page is not displayed if you select the Trusted Source Reconciliation option. |
The generic technology connector framework automatically creates certain objects after you submit all the information required to create a generic technology connector. Parent and child process forms corresponding to the OIM - Account data sets are examples of objects that are automatically created. Each process form on a particular Oracle Identity Manager installation must have a unique name.
On the Step 4: Verify Connector Form Names page, the generic technology connector framework displays default names for these process forms based on the names of the corresponding data sets. You must verify and, if required, change the names of these forms to ensure that they are unique for this installation of Oracle Identity Manager. While changing the name of a form, you must use only ASCII characters. An error message is displayed if you specify non-unique form names or if any name contains non-ASCII characters.
Note: You cannot revisit this page, so ensure that the form names that you specify meet all the requirements before you click Continue. |
After you specify the form names, click Continue.
Instead of clicking Continue, you can click Back to return to the Step 2: Specify Parameter Values page. However, metadata detection does not take place if you make changes on this page and click the Continue button. This is to ensure that any customization in the data set structure and mappings made during the first pass through this page does not get overwritten. You can manually add or edit fields and mappings on the Step 3: Modify Connector Configuration page.
Figure 17-7 shows that Step 4: Verify Connector Form Names page on which the entries listed at the end of Section 17.2.4.1, "Step 1: Provide Basic Information Page" and Section 17.2.4.2, "Step 2: Specify Parameter Values Page" and the changes described at the end of Section 17.2.4.3, "Step 3: Modify Connector Configuration Page" have been made.
Use this page to review information that you have provided up to this point for creating generic technology connectors. The following is a page-wise explanation of the changes that are permitted on the earlier pages:
Step 1: Provide Basic Information page
You can use either the View link or Back button to reopen and view the information provided on the Step 1: Provide Basic Information page. You cannot change the information displayed on this page, because any change in this information would amount to creating a new generic technology connector.
Step 2: Specify Parameter Values page
You can use either the Change link or Back button to reopen this page. You can change parameter values on this page. However, metadata detection does not take place when you submit the changed values. This is to ensure that any customization in the data set structure and mappings made during the first pass through this page does not get overwritten. You can manually add or edit fields and mappings on the Step 3: Modify Connector Configuration page.
Step 3: Modify Connector Configuration page
You can use the Change link to reopen this page and add or edit fields and mappings.
Step 4: Verify Connector Form Names page
You cannot revisit this page.
After you verify all the information displayed on the Step 5: Verify Connector Information page, click Create.
At this stage, the generic technology connector framework creates all the standard connector objects on the basis of the information that you provide. The list of these objects includes the connector XML file, which is created and imported automatically into Oracle Identity Manager. Except for the form names, the names of the connector objects are in the GTCname
_GTC
format.
For example, if you specify DB_conn
as the name of a generic technology connector that you create, all (except the forms) the connector objects are named DB_CONN_GTC
.
At the end of the process, a message stating that the connector has been successfully created is displayed on the page.
Note: If the creation process fails, objects that are created are not automatically deleted. This point is also mentioned in Section 18.1.1, "Creation Issues".See Section 18.2.3, "Errors During Connector Creation" for a listing of error messages related to the creation process. |
Figure 17-8 shows the first section of the Step 5: Verify Connector Information page on which the entries listed at the end of Section 17.2.4.1, "Step 1: Provide Basic Information Page" and Section 17.2.4.2, "Step 2: Specify Parameter Values Page" and the changes described at the end of Section 17.2.4.3, "Step 3: Modify Connector Configuration Page" have been made.
Figure 17-9 shows the second section of the Step 5: Verify Connector Information page on which the entries listed at the end of Section 17.2.4.1, "Step 1: Provide Basic Information Page" and Section 17.2.4.2, "Step 2: Specify Parameter Values Page" and the changes described at the end of Section 17.2.4.3, "Step 3: Modify Connector Configuration Page" have been made.
Note: If you select only the Provisioning option on the Step 1: Provide Basic Information page, you can skip this section because you need not configure reconciliation. |
A reconciliation scheduled task is created automatically when you create the generic technology connector. To configure and run this scheduled task, follow the instructions in the "Creating and Managing Scheduled Tasks" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager.
Note: The name of the scheduled task is in the following format:
For example, if the name of the generic technology connector is |
Note: If you select only the Reconciliation option on the Step 1: Provide Basic Information page, you can skip this section because you need not configure provisioning. |
A process definition is one of the objects that are automatically created when you create a generic technology connector. The name of the process definition is in the following format:
GTC_name
_GTC
For example, if the name of the generic technology connector is WebConn
, the name of the process definition is WebConn_GTC
.
The process tasks that constitute this process definition can be divided into two types:
System-defined process tasks
System-defined process tasks are included by default in all newly created process definitions.
Provisioning-specific process tasks
Provisioning-specific process tasks are included in the process definition of a generic technology connector only if you select the Provisioning option on the Step 1: Provide Basic Information page, regardless of whether or not you select the Reconciliation option.
The following are provisioning-specific process tasks:
Create User
Delete User
Enable User
Disable User
Updated Field_Name (this task is created for each field of the OIM - Account data set, except the ID
field)
For mappings created between fields of the OIM - User data set and the provisioning staging data set, the following process tasks are created:
Change User_data_set_field_name
Edit Provisioning_Staging_field_name
For example, suppose you create a mapping between the Last Name field of the OIM - User data set and the LName field of the provisioning staging data set. The following process tasks are automatically created along with the rest of the provisioning-specific process tasks:
Change Last Name
Edit LName
In addition, the following provisioning-specific process tasks are created for each child data set of the OIM - Account data set:
Child Table Child_Form_Name row Inserted
Child Table Child_Form_Name row Updated
Child Table Child_Form_Name row Deleted
All provisioning-specific process tasks have the following default assignments:
Target Type: Group User With Highest Priority
Group: SYSTEM ADMINISTRATORS
User: XELSYSADM
If required, you can modify these default assignments by following the instructions given in "Modifying Process Tasks".
Note: This is an optional step. Perform the procedure discussed in this section only if you want to enable logging for the generic technology connector. |
See "Enabling System Logging" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for information about enabling logging in Oracle Identity Manager.
The generic technology connector framework offers features that enable you to modify a generic technology connector. In addition, you can export or import a generic technology connector by using the Deployment Manager.
This section contains these topics:
Caution: The Design Console can be used to modify connector objects that are automatically created at the end of the generic technology connector creation process. If you use the Manage Generic Technology Connector feature to modify a generic technology connector whose connector objects have been customized by using the Design Console, all the customization work done using the Design Console would get overwritten. Therefore, Oracle recommends that you to follow one of the following guidelines:
See Section 14.4, "Connector Objects Created by the Generic Technology Connector Framework" for information about connector objects that are created automatically by the framework. In addition, you can modify only one connector at a time. If you try to use the Modify pages for two different connectors at the same time on the same computer, the Modify features would not work correctly. Appendix 18, "Troubleshooting Generic Technology Connectors" discusses both these points. |
To modify a generic technology connector:
Login to the Administrative and User Console.
Click Advanced.
Under Configuration, click Manage Generic Connector.
Search for the connector that you want to modify. To simplify your search, you can use a combination of the search criteria provided on this page. Alternatively, to view all the generic technology connectors that have been created on this Oracle Identity Manager installation, click Search connectors without specifying any search criteria.
In the results that are displayed, click the generic technology connector that you want to modify.
Click Edit Parameters. The Step 2: Specify Parameter Values page of the connector creation process is displayed. From this point onward, follow the procedure described in the Step 2 section .
Caution: If you modify attributes of fields of the OIM - Account data set or its child data sets, corresponding changes are not made in the Oracle Identity Manager database entries for these data sets. At the same time, no error message is displayed.Therefore, for this release of Oracle Identity Manager, Oracle recommends that you do not modify the fields or child data sets of the OIM - Account data set. This point has also been discussed in Section 18.2.2, "Step 3: Modify Connector Configuration Page". |
You can export the XML file of a generic technology connector. This XML file contains definitions for all the objects that are part of the connector. If you want to use the same generic technology connector on a new Oracle Identity Manager installation, you must first export the XML file and import it into the new Oracle Identity Manager installation.
To export the connector XML file:
In the Oracle Identity Manager Advanced Administration, under System Management, click Export Deployment Manager File.
On the first page of the Deployment Manager Wizard, select Generic Connector from the list and click Search.
In the search results, select the generic technology connector whose XML file you want to export.
Click Select Children.
For the selected generic technology connector, select the child entities that you want to export and click Select Dependencies.
Select the dependencies that you want to export, and click Confirmation.
After you verify that the elements displayed on the page cover your export requirements, click Add for Export.
Click Exit wizard and show full selection, and click OK.
To copy a generic technology connector to a different Oracle Identity Manager installation:
If the connector uses custom providers, you must copy the files created during provider creation to the appropriate directories on the destination Oracle Identity Manager installation.
See Also: "Chapter 16, "Creating Custom Providers for Generic Technology Connectors" for more information about these provider files and the directories into which you must copy them |
Export the connector XML file on the source Oracle Identity Manager installation.
Import the connector XML file on the destination Oracle Identity Manager installation.
Caution: You must ensure that the names you select for a generic technology connector and its constituent objects on a staging server do not cause naming conflicts with existing connectors and objects on the production server.The following scenario explains why you must follow this guideline: Suppose you create a generic technology connector on a staging server, and want to import the connector to a production server. While creating the generic technology connector on the staging server, you would have ensured that the names of the generic technology connector and the connector objects are unique on that server. At the same time, you must also ensure that the names are not the same as the names of connectors and connector objects on the production server. If any of the names happen to be the same, the old objects would be overwritten by the new objects when you import the connector XML file from the staging server to the production server. No message is displayed during the overwrite process, and the process would lead to eventual failure of the affected connectors. This is also mentioned inSection 18.2.1, "Names of Generic Technology Connectors and Connector Objects" To ensure that you are able to revert to a working state in the event that an object is overwritten, you must create a backup of the destination Oracle Identity Manager database before you import a connector XML file. |
To import the connector XML file:
In the Oracle Identity Manager Advanced Administration, under System Management, click Import Deployment Management File. A dialog box for locating files is displayed.
Locate and open the connector XML file from the directory into which you copy it.
Click Add File.
Click Next, Next, and Skip.
Click View Selections.
The contents of the connector XML file are displayed on the Import page. You may see a cross-shaped icon along with some nodes. These nodes represent Oracle Identity Manager entities that are redundant. Before you import the connector XML file, you must remove these entities by right-clicking each node and selecting Remove.
Click Import. The connector file is imported into Oracle Identity Manager.
After you import the connector XML file, you must update the run-time parameters of the generic technology connector.
Note: These values are not copied in the connector XML file when you export it. |
To update the values of the run-time parameters, follow the procedure described in Section 17.5.7, "Modifying Generic Technology Connectors".
Custom connectors can choose to use the Generic Connection Pool framework (sometimes referred to as the GCP) for any connection pooling needs.
Internally, the Generic Connection Pool framework uses Oracle Universal Connection Pool (UCP) as the default connection pooling mechanism.Basic steps to use the Generic Connection Pool in a custom connector include:
Provide a concrete implementation for the ResourceConnection
interface.
The implementation should also have a default constructor with no parameters.
Define the additional fields in the ITResource definition.
Invoke the Generic Connection Pool to obtain and release connections from the pool.
Topics in this section include:
The connection pool makes use of the concrete implementation of ResourceConnection
to create and close connections, and to validate connections to the target. Thus, you should ensure that this concrete implementation class is available as a jar file under the JavaTasks
folder.
Table 17-5 describes key methods of ResourceConnection
:
Table 17-5 Methods of ResourceConnection
Method | Description |
---|---|
Create Connection |
This method is called while initializing the pool (to create initial number of connections) and for pool life-cycle events as needed. A hashmap named The method returns the |
Close Connection |
The pool invokes this method when it needs to close a connection in the course of pool life-cycle events. |
Heartbeat |
This method is used to maintain the TCP heartbeat (or TCP keepalive) of the connection to the target. The method keeps the TCP connection alive, so that the connection does not time out from the target side. |
Validate |
This method returns The Generic Connection Pool invokes the method if "validate connection on borrow" is set to If the method returns |
Table 17-6 lists other ITResource
parameters for which you should provide appropriate values:
Table 17-6 ITResource Parameters
Field | Description | Sample Value and Notes |
---|---|---|
Abandoned connection timeout |
Connection timeout for abandoned connections in seconds. After the timeout elapses, the connection is reclaimed. |
900 |
Connection wait timeout |
Wait time in seconds for a connection to establish. |
60 |
Inactive connection timeout |
Connection timeout, in seconds, for inactive connections in the pool that are idle. Note: These are not borrowed connections. |
300 |
Initial pool size |
Initial number of connections in the pool. |
3 |
Max pool size |
Maximum number of connections that the pool can create. |
30 |
Min pool size |
Minimum number of connections that the pool must maintain. |
2 |
Validate connection on borrow |
Indicates if connections should be validated. See Table 17-5 for a detailed explanation. |
true or false |
Timeout check interval |
Frequency, in seconds, at which to check timeout properties. |
30 |
Pool preference |
Denotes the preferred pooling mechanism. Default pool implementation is UCP. |
"Default" (for UCP). "Native" (for Native implementation) |
Connection pooling supported |
Denotes whether pooling is supported. If pooling is not supported, returned connections will not be pooled connections. Recommended default is |
true or false. |
Target supports only one connection |
Denotes whether the target system supports only one connection at a time. When set to true, irrespective of other properties, the following pool parameters are used:
Recommended default is |
|
ResourceConnection class definition |
The concrete implementation of the |
|
Native connection pool class definition |
The wrapper to the native pool mechanism that implements the GenericPool. Set a value only if the pool preference is set to |
|
Pool excluded fields |
Comma-separated list of fields not needed for creating a connection. When any of the specified fields are updated, the GCP pool is not refreshed. Note: Fields in this list are not available as part of the |
|
Note the following:
Updating the ITResource
parameters from the Design Console does not refresh the pool. Update values through the Administrative and User Console or through the APIs.
Avoid updating values when the pool is in use.
Consumers of the Generic Connection Pool can invoke the ConnectionService to get pooled connections to the target, and also to return connections back to the pool.
This example code gets a connection from the pool and returns it based on ITResource Name:
import com.oracle.oim.gcp.exceptions.ConnectionServiceException; import com.oracle.oim.gcp.pool.ConnectionService; import com.oracle.oim.gcp.resourceconnection.ResourceConnection; public class ConnectionPoolClient { public void testConnection(String itResName) { try{ //Request for connection from the connection pool ConnectionService service = new ConnectionService(); ResourceConnection myConnection = service.getConnection(itResName); //"myConnection" is the connection //use the connection... //Release connection back to the connection pool //Connections should always be returned this way. service.releaseConnection(myConnection); } catch(ConnectionServiceException e) { //handle } }
You can also request connections to the target using ITResource Key. Here is an example:
ConnectionService service = new ConnectionService(); ResourceConnection myConnection = service.getConnection(itResourceKey);
As mentioned earlier in the section, you can use any third-party pool for your custom connector. However, in addition to the steps described earlier, you must provide a concrete implementation of the GenericPool interface as a wrapper to the third-party pool.
Note: It If the custom connector does not wish to use the UCP pool, it can choose to use GCP with the Native option, though there are no significant advantages to this. With the Native pool preference, the responsibility of maintaining and implementing the pool rests with the custom connector. |
Table 17-7 lists the methods invoked for the GenericPool interface:
Table 17-7 Methods of the GenericPool Interface
Method | Purpose |
---|---|
initializePool(PoolConfiguration poolConfig) |
To initialize the pool. The PoolConfiguration data object contains all pool-related parameters. |
borrowConnectionFromPool() |
To request a connection. |
returnConnectionToPool(ResourceConnection resConn) |
To return a connection to the pool. |
refreshPool(PoolConfiguration newPoolConfig) |
To refresh the pool with updated values. |
destroyPool() |
To remove the pool (for example when ITResource is deleted). |
This example demonstrates an implementation of the ResourceConnection
interface. Key methods are highlighted.
Example 17-1 An Example of ResourceConnection Implementation
/** * Sample implementation for Socket Connections: */ import java.io.IOException; import java.net.InetSocketAddress; import java.net.Socket; import java.net.SocketException; import java.net.UnknownHostException; import com.oracle.oim.gcp.exceptions.ResourceConnectionCloseException; import com.oracle.oim.gcp.exceptions.ResourceConnectionCreateException; import com.oracle.oim.gcp.exceptions.ResourceConnectionValidationxception; import com.oracle.oim.gcp.resourceconnection.ResourceConnection; public class SocketResourceConnectionImpl extends Socket implements ResourceConnection { public SocketResourceConnectionImpl() { super(); } /** * Sample: Concrete implementation for closing a socket connection */ public void closeConnection() throws ResourceConnectionCloseException{ if(!this.isClosed()){ try { this.close(); } catch (IOException e) { throw new ResourceConnectionCloseException("[Client ResourceConnection implementation] Failed to close socket connection! "); } } } /** * Sample : Concrete implementation for creating a socket connection. * The return value is the actual physical socket connection * */ public ResourceConnection createConnection(HashMap itResInfoMap) throws ResourceConnectionCreateException { ResourceConnection r = null; SocketResourceConnectionImpl i = new SocketResourceConnectionImpl(); try { //HashMap has all ITResource related information that is needed //for connecting to target. String serverAddress= ((String) itResInfoMap.get ("Server Address")).trim(); //utility method getIntValue returns an int for a String int port = getIntValue(((String)itResInfoMap.get("Port")).trim()); System.out.println("Connecting to Socket with IP Address " + serverAddress+" at port "+ port); InetSocketAddress inet = new InetSocketAddress(serverAddress,port); i.connect(inet); if(!i.isConnected()){ throw new ResourceConnectionCreateException (" Failed to create socket: connection failure"); } r = (ResourceConnection)i; } catch (UnknownHostException e) { throw new ResourceConnectionCreateException(" [Client ResourceConnection implementation] Failed to create socket connection!", e); } catch (IOException e) { throw new ResourceConnectionCreateException(" [Client ResourceConnection implementation] Failed to create socket connection! ",e); } return r; } /** * Sample : Concrete implementation for heartbeat of a socket connection */ public void heartbeat() throws ResourceConnectionValidationxception { try { this.setKeepAlive(true); } catch (SocketException e) { throw new ResourceConnectionValidationxception ("[Client ResourceConnection implementation] Failed to set heartbeat "); } } /** * Sample: Concrete implementation for validating connection */ public boolean isValid() { if(this.isBound()){ return true; }else{ return false; } } }
This section contains these topics:
Apply the following guidelines while specifying a name for a generic technology connector:
Summary:
Ensure that the name contains only ASCII characters. You can include the underscore (_) character, but do not include any other non-ASCII character in the name.
Description:
For most of the connector objects that are automatically created at the end of the connector creation process, the name of the generic technology connector is part of the name of the object itself. For example, if the name of the generic technology connector is WebConn
, the name of its scheduled task is WebConn_GTC
.
In the Oracle Identity Manager database, there is no provision for storing objects with names in non-ASCII characters. Therefore, an error message is displayed if you enter non-ASCII characters while specifying the name of a generic technology connector.
Ensure that the name is not the same as the name of any connector or connector object on the Oracle Identity Manager installation.
If you plan to create the generic technology connector on a staging server and move it to a production server, ensure that the name of the generic technology connector does not cause naming conflicts with existing connectors or connector objects on the production server.
Before you import a generic technology connector created on a staging server to a production server, create a backup of the destination Oracle Identity Manager database to ensure that you are able to revert to a working state in the event that a connector object is overwritten.
If you select the shared drive transport provider, you must select the CSV format provider.
If you select the SPML provisioning format provider, you must select the Web Services provisioning transport provider.
If you select the shared drive reconciliation transport provider, ensure that there is data in the prescribed format on at least the first two lines of the parent and child data files provided by the target system for reconciliation. The prescribed form of data is discussed in Section 15.1, "Shared Drive Reconciliation Transport Provider" .
If you select the shared drive reconciliation transport provider, ensure that the required permissions are set on the staging and archiving directories before reconciliation begins. The required permissions are discussed in the "Permissions to Be Set on the Staging and Archiving Directories" section .
Do not try to create more than one generic technology connector at a time, even from different sessions of the Administrative and User Console for the same Oracle Identity Manager installation.
This section describes the following known issues related to the input that you specify on the Step 2: Specify Parameter Values page:
Summary:
If you use the shared drive reconciliation transport provider, :
Do not specify the same path for the staging and archiving directories. Existing files in the archiving directory are deleted if you specify the same path for both directories.
Ensure that the names of files in the staging directory are different from the names of files in the archiving directory. If the file names happen to be the same, existing files in the archiving directory are overwritten at the end of a reconciliation run.
Description:
When you use the shared drive reconciliation transport provider, after each reconciliation run, data files are moved from the staging directory to the archiving directory. The files moved to the archiving directory are not time-stamped or marked in any way. Therefore, when you use the shared drive transport provider, bear in mind the following guidelines:
The archiving directory path and name that you specify must not be the same as the staging directory path and name. If you specify the same path and name, the existing files in the archiving directory are deleted at the end of the reconciliation run.
During the current reconciliation run, if data files with the same names as the files used in the last reconciliation run are placed in the staging directory, the existing files in the archiving directory are overwritten by the new files from the staging directory. This can be illustrated by the following example:
Suppose that at the end of the last reconciliation run, the following files were moved automatically from the staging directory to the archiving directory:
usrdataParentData.csv usrdataRoleData.csv usrdataGroupMembershipData.txt
For the current reconciliation run, you place the following files in the staging directory:
usrdataParentData.csv usrdataRoleData_04Feb07.csv usrdataGroupMembershipData_04Feb07.txt
At the end of the current reconciliation run, these files are moved to the archiving directory. When this happens, the old usrdataParentData.csv
file is overwritten by the new one.
Therefore, if you want to ensure that files in the archiving directory are not overwritten at the end of a reconciliation run, you must ensure that the names of files in the staging directory are not the same as the names of files in the archiving directory.
Summary:
Metadata detection does not take place a second time if you go back to the Step 2: Specify Parameter Values page. Therefore, if required, you must manually make changes in the fields and field mappings displayed on the Step 3: Modify Connector Configuration page.
Description:
Suppose you want to change a value that you provide on the Step 2: Specify Parameter Values page. You can return to this page from the Step 4: Verify Connector Form Names or Step 5: Verify Connector Information page. However, metadata detection would not take place a second time when you click the Continue button after changing the provider parameter value. This functionality is aimed at preserving changes that you may have manually made on the Step 3: Modify Connector Configuration page.
As an extension of this functionality, metadata detection does not take place even when you modify an existing generic technology connector.
This section discusses best practices related to the following areas:
Note that the following validations are applied when you specify a field name while adding or editing fields:
Two fields that belong to the same data set (parent or child) cannot have the same name.
Two child data sets of the same parent data set cannot have the same name.
The name of a field in a parent data set cannot be the same as the name of one of its child data sets.
Two different child data sets can have fields that have the same name, regardless of whether or not the child data sets belong to the same parent data set. For example, the GroupMembership
data set and Role
data set can each have a field with the name UsrID
.
Two different parent data sets can have fields that have the same name. Similarly, these data sets can also have child data sets that have the same name.
The name of a child data set can be the same as that of one of its fields.
To ensure the security of passwords, password information must not be reconciled through a generic technology connector. In other words, you must ensure that the Source and reconciliation staging data sets do not contain the Password field. In addition, you must not map any field of the reconciliation staging data sets to the Password field of the OIM - User data set.
A password-like field is a field to which you set the Encrypted and Password Field attributes (by selecting the Encrypted and Password Field check boxes). You can create a password-like field by setting these two attributes to a field that you add to the OIM - Account data set.
To secure the contents of password-like fields, bear in mind the following guidelines while adding or editing these fields:
You can use the Password Field and Encrypted check boxes to secure the display and storage of password information in Oracle Identity Manager. However, when you map password-like fields to fields of the provisioning staging data set, you must take all necessary precautions to secure the data propagated in these fields. For example, you must ensure that this data is not stored in a plain-text file on the target system at the end of a provisioning operation.
Oracle recommends creating only one-to-one mappings between the password field of the OIM - Account data set and the provisioning staging data set. In other words, this password field must not be used as an input field for a transformation mapping with a provisioning staging field. The same precaution must be taken for the Password field of the OIM - User data set.
As mentioned earlier, the Password field is one of the predefined fields of the OIM - User data set. The Password Field and Encrypted attributes are set for this field. By using the Design Console, you can set the Password Field and Encrypted attributes for a UDF that you create. This would give the newly created UDF the same properties as the existing Password field. However, the generic technology connector framework treats this field the same as any other text field (with the String data type) and the contents are not encrypted in the Administrative and User Console or database.
See also Section 18.1, "General Issues for Generic Technology Connectors".
Apply the following best practices while working with fields of the Oracle Identity Manager data sets:
Summary:
If you select the translation transformation provider to create a mapping, specify the name of a lookup definition in the Lookup Code Name region. If you specify a data set name and field in the Lookup Code Name region, translation would fail during actual reconciliation or provisioning operations.
Description:
If you select the translation transformation provider while creating a mapping, the Step 2: Mapping page displays options for selecting a field from a data set and specifying a literal. Because you are using the translation transformation provider, you must select the Literal option and enter the name of the lookup definition that contains the Code Key and Decode values for the translation. You must not select a data set name and field in the Lookup Code Name region. Although there is no validation to stop you from selecting a data set name and field, the translation operation would fail during actual reconciliation or provisioning operations.
Create a mapping between the ID field of the OIM - Account data set and the field that uniquely identifies records of the reconciliation staging data set.
Along with the ID field, other fields of the OIM - Account data set can be (matching-only) mapped to corresponding fields of the reconciliation staging data set to create a composite key field for reconciliation matching.
Create mappings between all fields in provisioning staging data sets and corresponding fields in Oracle Identity Manager data sets.
To create a reconciliation rule, you create matching-only mappings between fields of the reconciliation staging data set and the OIM - User data set. If there are child data sets, ensure that the names of fields of the reconciliation staging data set that are input fields for the matching-only mappings are not used in any of the reconciliation staging child data sets. If you do not follow this guideline, reconciliation would fail.
This has also been mentioned in the section "Step 3: Modify Connector Configuration Page".
A literal field can be used as one of the input fields of a transformation mapping. If you select the Literal option, you must enter a value in the field. You must not leave the field blank after selecting it.
Apply the following best practices while working with fields of the Oracle Identity Manager data sets:
For trusted source reconciliation, the following fields of the OIM – User data set must always hold values:
User ID
First Name
Last Name
Organization Name
Xellerate Type
Role
In addition, you can select other OIM – User fields that must be populated when a user account is created through reconciliation. For each of these fields, you must create mappings with the corresponding fields of the reconciliation staging data sets. During a reconciliation run, you must ensure that the fields of the target system that serve as the source for these fields always hold values.
For provisioning, you can select fields of the OIM – User and OIM – Account data sets whose values must be propagated to the target system. After you identify these fields, create mappings between them and their corresponding fields in the provisioning staging data sets. During a provisioning operation, you must enter values for each of these fields.
If required, add user-defined fields (UDFs) to the list of predefined OIM - User data set fields. See "Configuring User Attributes" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for details.
Do not modify or delete attributes of OIM - Account data set fields in an existing generic technology connector.
Summary
If parent records and child data records are created and linked in both the target system and Oracle Identity Manager, you must ensure that the staging directory contains both parent data and child data files at the start of each reconciliation run.
Description
Suppose there are parent data records with associated child data records in the target system. To reconcile these records into Oracle Identity Manager, you place the parent and child data files containing these records in the staging directory. During the reconciliation run, the child data records are linked to their corresponding parent data records. Before the start of any subsequent reconciliation run, if you remove the child data files from the staging directory, reconciliation events are not created for this form of child data record deletion. If you want to remove child data records for specific parent data records, you must remove the child data records from the child data file. You must ensure that the child data file is placed in the staging directory for each reconciliation run, even if there are no child data records (from the third line onward) in the files.
Apply the following guideline while working with custom providers:
When you develop code for a custom provisioning transport provider, ensure that the provider returns the unique field value at the end of a Create User operation. This functionality is implemented by the sendData
method of the provisioning transport provider. See "Role of Providers During Provisioning" for more information.
Apply the following guidelines while working with connector objects created automatically during generic technology connector creation:
Summary:
Do not attempt to use for provisioning the resource object created automatically for a reconciliation-only generic technology connector.
Description:
Suppose you select only the Reconciliation option while creating a generic technology connector. At the end of the creation process, a resource object is one of the objects created automatically for this generic technology connector. However, you cannot provision this resource object to any user because a generic adapter is not created for a reconciliation-only generic technology connector.
Summary:
Do not attempt to provision generic technology connector resource objects to organizations defined in Oracle Identity Manager.
Description:
A resource object is one of the connector objects that get created automatically during generic technology connector creation. This resource object can be provisioned only to Oracle Identity Manager Users. You must not attempt to provision it to organizations defined in Oracle Identity Manager.
This has also been mentioned in the Connector Objects section .
You can use the Design Console to customize connector objects that are automatically created during generic technology connector creation. After you customize connector objects, if you perform a Manage Generic Technology Connector operation, all the customization done on the connector objects would be overwritten. Therefore, Oracle recommends that you to apply one of the following guidelines:
Do not use the Design Console to modify generic technology connector objects.
The exception to this guideline is the IT resource. You can modify the parameters of the IT resource by using the Design Console. However, if you have enabled the cache for the GenericConnector
and GenericConnectorProviders
categories, you must purge the cache either before or after you modify IT resource parameters. See "Purging the Cache" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for more information.
If you use the Design Console to modify generic technology connector objects, do not use the Manage Generic Technology Connector feature to modify the generic technology connector.
This has also been mentioned in Section 17.5.6, "Working with Connector Objects".
Prepopulate adapters are not part of the set of connector objects that are created automatically when you create a generic technology connector. However, while creating a generic technology connector, you can map provisioning input to literals and user data fields. Although this feature cannot be used to prepopulate the User Defined Form, it can be used to prepopulate the provisioning data packet.
Apply the following best practice while modifying generic technology connectors:
Do not try to modify more than one generic technology connector at a time, even from different sessions of the Administrative and User Console for the same Oracle Identity Manager installation.