Using Generic Technology Connectors

11 Using Generic Technology Connectors

Generic Technology Connector is used to create custom connectors in a simple way.

If you are looking for a simple way to create your custom connector and do not need the customization features of the Adapter Factory, then you can create the connector by using the Generic Technology Connector (GTC) feature of Oracle Identity Manager.

This chapter describes how to use and maintain Generic Technology Connectors. It contains the following sections:

11.1 Overview of Generic Technology Connectors

Generic Technology Connectors can be developed by using providers or the programmatic options available with adapters.

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 Predefined Providers for Generic Technology Connectors.

If no suitable provider is available, you can develop a provider to fit your requirements.

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 Using the Adapter Factory.

11.2 Using the Generic Connection Pool Framework in Custom 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.

This section contains the following topics:

11.2.1 Basic Steps to Use Generic Connection Pool in Custom Connector

To use Generic Connection Pool in custom connector, provide an implementation for the ResourceConnection interface, define the additional fields in the ITResource definition, and invoke the Generic Connection Pool.

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.

11.2.2 Providing concrete implementation for ResourceConnection interface

The connection pool makes use of the concrete implementation of ResourceConnection to create and close connections, and to validate connections to the target. Therefore, you should ensure that this concrete implementation class is available as a jar file under the JavaTasks folder.

Table 11-1 describes key methods of ResourceConnection:

Table 11-1 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 `itResourceInfoMap` is available as parameter with ITResource values to this method. The method returns the `ResourceConnection` which is the actual physical connection to the target.
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 `true` or `false` to indicate whether the connection is still valid. The Generic Connection Pool invokes the method if "validate connection on borrow" is set to `true`. It is invoked for connections that have been in the pool for some time. If the method returns `false`, the pool will discard that connection, create a new connection, and return to the requester.

11.2.3 Defining Additional ITResource Parameters

Provide appropriate values for the additional ITResource parameters for using Generic Connection Pool framework in custom connectors.

Table 11-2 lists other ITResource parameters for which you should provide appropriate values:

Table 11-2 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 11-1 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`.	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: Min Pool Size = 0 Initial Pool Size = 0 Max Pool Size = 1 Recommended default is `false`	`true` if target can handle only one connection, `false` otherwise.
ResourceConnection class definition	The concrete implementation of the `ResourceConnection` class	`com.oracle.oim.ad.ADResourceConnectionImpl`
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 `Native`.	`com.oracle.oim.ad.ADNativePool`
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 `HashMap` parameter to the `createConnection` method.	`Recon TimeStamp,ADSync Enabled`

Note:

Updating the ITResource parameters from the Design Console does not refresh the pool. Update values through the Identity System Administration or through the APIs.
Avoid updating values when the pool is in use.

11.2.4 Getting and Releasing Connections from the Pool

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);

11.2.5 Using a Third-party Pool

Provide a concrete implementation of the GenericPool interface as a wrapper to the third-party pool.

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 11-3 lists the methods invoked for the GenericPool interface:

Table 11-3 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).

11.2.6 Example: Implementation of ResourceConnection

Implementation for the ResourceConnection interface is required for using the Generic Connection Pool in a custom connector.

This example demonstrates an implementation of the ResourceConnection interface. Key methods are highlighted.

/**
* 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;
               }
        }
}

11.3 Best Practices

Best practices of using Generic Technology Connectors are related to basic information, parameter values, modifying connector configuration, shared drive reconciliation transport provider, custom providers, connector objects, and modifying Generic Technology Connectors.

This section contains the following topics:

11.3.1 Working with the Provide Basic Information Page

Follow the guidelines of specifying a name of the generic technology connector in the Provide Basic Information page.

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 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 Identity System Administration for the same Oracle Identity Manager installation.

11.3.2 Working with the Specify Parameter Values Page

Follow the best practices of specifying the input in the Specify Parameter Values page.

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.

11.3.3 Working with the Modify Connector Configuration Page

Follow the best practices related to various types of fields, mappings, and data sets.

This section describes the best practices related to various types of fields, mappings, and data sets. It contains the following topics:

11.3.3.1 Names of Fields

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.

11.3.3.2 Password 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.

11.3.3.3 Password-Like Fields

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 Identity Self Service, Identity System Administration, or database.

11.3.3.4 Mappings

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.

11.3.3.5 Oracle Identity Governance Data Sets

Apply the following best practices while working with fields of the Oracle Identity Governance data sets:

For trusted source reconciliation, the following fields of the OIG – User data set must always hold values:
- User ID
- First Name
- Last Name
- Organization Name
- Xellerate Type
- Role
In addition, you can select other OIG – 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 OIG – User and OIG – 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 OIG - User data set fields.
Do not modify or delete attributes of OIG - Account data set fields in an existing generic technology connector.

11.3.4 Working with Shared Drive Reconciliation Transport Provider

Follow the guideline to ensure that the staging directory contains both parent data and child data files at the beginning of the reconciliation run.

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.

11.3.5 Working with Custom Providers

Follow the guideline to ensure that the provider returns the unique field value at the end of a Create User operation.

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.

11.3.6 Working with Connector Objects

Follow the guidelines of using connector objects that are created automatically during GTC creation.

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.
- 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 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.

11.3.7 Modifying Generic Technology Connectors

Follow the best practice of not modifying multiple generic technology connectors at a time.

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 Identity System Administration for the same Oracle Identity Manager installation.