Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Identity Manager
11g Release 1 (11.1.1)

Part Number E14309-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

17 Developing Identity Connectors

This chapter is a tutorial that walks through the procedures necessary to develop an identity connector using the Identity Connector Framework (ICF) and the Oracle Identity Manager metadata. It includes information about important ICF classes and interfaces, the connector bundle, the connector server, and code samples for implementing a flat file identity connector and creating Oracle Identity Manager metadata for user provisioning and reconciliation processes. It contains the following sections:

17.1 Developing a Flat File Connector

The procedure for developing a flat file connector is to develop an implementation of the Configuration interface followed by the implementation of the Connector class. Before beginning, you must prepare IO representation modules for all flat file connector operations. This might include all or some of the following:

This tutorial is focused on identity connector development, and therefore, these preparations are not discussed in detail.

Note:

The following supporting classes are used for file input and output handling during identity connector operations:

  • org.identityconnectors.flatfile.io.FlatFileIOFactory

  • org.identityconnectors.flatfile.io.FlatFileMetadata

  • org.identityconnectors.flatfile.io.FlatFileParser

  • org.identityconnectors.flatfile.io.FlatFileWriter

See "Supporting Classes for File Input and Output Handling" for the implementations of the input and output handling supporting classes.

To develop a flat file connector:

  1. Implement the configuration class for the Flat File Connector by extending the org.identityconnectors.framework.spi.AbstractConfiguration base class.

    Example 17-1 is a sample of this. See Section 16.3.1.2, "org.identityconnectors.framework.spi.Configuration" for more information.

    Example 17-1 Implementation of AbstractConfiguration

    package org.identityconnectors.flatfile;
    import java.io.File;
    import org.identityconnectors.flatfile.io.FlatFileIOFactory;
    import org.identityconnectors.framework.common.exceptions.ConfigurationException;
    import org.identityconnectors.framework.spi.AbstractConfiguration;
    import org.identityconnectors.framework.spi.ConfigurationProperty;
    /**
     * Class for storing the flat file configuration 
     */
    public class FlatFileConfiguration extends AbstractConfiguration {
    /*
     * Storage file name
     */
    private File storeFile;
    /*
     * Delimeter used
     */
    private String textFieldDelimeter;      
    /*
     * Unique attribute field name
     */
    private String uniqueAttributeName = ""; 
    /*
     * Change attribute field name. Should be numeric
     */
    private String changeLogAttributeName = "";
     
    public File getStoreFile() {
    return storeFile;
    }
     
    public String getTextFieldDelimeter() {
    return textFieldDelimeter;
    }
     
         public String getUniqueAttributeName() {
            return uniqueAttributeName;
        }
     
        public String getChangeLogAttributeName() {
            return changeLogAttributeName;
        }
     
        /**
         * Set the store file
         * @param storeFile
         */
        @ConfigurationProperty(order = 1, helpMessageKey = "USER_ACCOUNT_STORE_HELP", 
                displayMessageKey = "USER_ACCOUNT_STORE_DISPLAY")
        public void setStoreFile(File storeFile) {
            this.storeFile = storeFile;
        }
     
        /**
         * Set the text field delimeter
         * @param textFieldDelimeter
         */
        @ConfigurationProperty(order = 2, 
                helpMessageKey = "USER_STORE_TEXT_DELIM_HELP", 
                displayMessageKey = "USER_STORE_TEXT_DELIM_DISPLAY")
        public void setTextFieldDelimeter(String textFieldDelimeter) {
            this.textFieldDelimeter = textFieldDelimeter;
        }
     
        /**
         * Set the field whose values will be considered as unique attributes
         * @param uniqueAttributeName
         */
        @ConfigurationProperty(order = 3, helpMessageKey = "UNIQUE_ATTR_HELP", 
                displayMessageKey = "UNIQUE_ATTR_DISPLAY")
        public void setUniqueAttributeName(String uniqueAttributeName) {
            this.uniqueAttributeName = uniqueAttributeName;
        }
     
        /**
         * Set the field name where change number should be stored
         * @param changeLogAttributeName
         */
        @ConfigurationProperty(order = 3, helpMessageKey = "CHANGELOG_ATTR_HELP", 
                displayMessageKey = "CHANGELOG_ATTR_DISPLAY")
        public void setChangeLogAttributeName(String changeLogAttributeName) {
            this.changeLogAttributeName = changeLogAttributeName;
        }    
        @Override
        public void validate() {
            
            // Validate if file exists and is usable
            boolean validFile = (this.storeFile.exists() &&
                    this.storeFile.canRead() &&
                    this.storeFile.canWrite() &&
                    this.storeFile.isFile());
            
            if (!validFile)
                throw new ConfigurationException("User store file not valid");
            
            // Validate if there is a field on name of unique attribute field name        
            // Validate if there is a field on name of change attribute field name
            FlatFileIOFactory.getInstance(this);
            // Initialization does the validation
        }
        
        
    }
    
  2. Create connector class for the Flat File Connector by implementing the org.identityconnectors.framework.spi.Connector interface.

    Example 17-2 implements the CreateOp, DeleteOp, SearchOp and UpdateOp interfaces and thus supports all four operations. The FlatFileMetadata, FlatFileParser and FlatFileWriter classes are supporting classes. Their implementation is not shown as they do not belong to the ICF.

    Example 17-2 Implementation of PoolableConnector

    package org.identityconnectors.flatfile;
     
    import java.util.HashSet;
    import java.util.Iterator;
    import java.util.List;
    import java.util.Map;
    import java.util.Set;
     
    import org.identityconnectors.flatfile.io.FlatFileIOFactory;
    import org.identityconnectors.flatfile.io.FlatFileMetadata;
    import org.identityconnectors.flatfile.io.FlatFileParser;
    import org.identityconnectors.flatfile.io.FlatFileWriter;
    import org.identityconnectors.framework.api.operations.GetApiOp;
    import org.identityconnectors.framework.common.exceptions.AlreadyExistsException;
    import org.identityconnectors.framework.common.exceptions.ConnectorException;
    import org.identityconnectors.framework.common.objects.Attribute;
    import org.identityconnectors.framework.common.objects.AttributeInfo;
    import org.identityconnectors.framework.common.objects.AttributeInfoBuilder;
    import org.identityconnectors.framework.common.objects.ConnectorObject;
    import org.identityconnectors.framework.common.objects.ConnectorObjectBuilder;
    import org.identityconnectors.framework.common.objects.ObjectClass;
    import org.identityconnectors.framework.common.objects.OperationOptions;
    import org.identityconnectors.framework.common.objects.ResultsHandler;
    import org.identityconnectors.framework.common.objects.Schema;
    import org.identityconnectors.framework.common.objects.SchemaBuilder;
    import org.identityconnectors.framework.common.objects.Uid;
    import org.identityconnectors.framework.common.objects.filter.AbstractFilterTranslator;
    import org.identityconnectors.framework.common.objects.filter.FilterTranslator;
    import org.identityconnectors.framework.spi.Configuration;
    import org.identityconnectors.framework.spi.ConnectorClass;
    import org.identityconnectors.framework.spi.PoolableConnector;
    import org.identityconnectors.framework.spi.operations.CreateOp;
    import org.identityconnectors.framework.spi.operations.DeleteOp;
    import org.identityconnectors.framework.spi.operations.SchemaOp;
    import org.identityconnectors.framework.spi.operations.SearchOp;
    import org.identityconnectors.framework.spi.operations.UpdateOp;
     
    /**
     * The main connector class
     */
    @ConnectorClass(configurationClass = FlatFileConfiguration.class, displayNameKey = "FlatFile")
    public class FlatFileConnector implements SchemaOp, CreateOp, DeleteOp,
            UpdateOp, SearchOp<Map<String, String>>, GetApiOp, PoolableConnector {
     
        private FlatFileConfiguration flatFileConfig;
        private FlatFileMetadata flatFileMetadata;
        private FlatFileParser flatFileParser;
        private FlatFileWriter flatFileWriter;
        private boolean alive = false;
     
        @Override
        public Configuration getConfiguration() {
            return this.flatFileConfig;
        }
     
        @Override
        public void init(Configuration config) {
            this.flatFileConfig = (FlatFileConfiguration) config;
     
            FlatFileIOFactory flatFileIOFactory = 
                 FlatFileIOFactory.getInstance(flatFileConfig);
            this.flatFileMetadata = flatFileIOFactory.getMetadataInstance();
            this.flatFileParser = flatFileIOFactory.getFileParserInstance();
            this.flatFileWriter = flatFileIOFactory.getFileWriterInstance();
            this.alive = true;
            System.out.println("init called: Initialization done");
        }
     
        @Override
        public void dispose() {
            this.alive = false;
        }
     
        @Override
        public Schema schema() {
            SchemaBuilder flatFileSchemaBldr = new SchemaBuilder(this.getClass());
            Set<AttributeInfo> attrInfos = new HashSet<AttributeInfo>();
            for (String fieldName : flatFileMetadata.getOrderedTextFieldNames()) {
                AttributeInfoBuilder attrBuilder = new AttributeInfoBuilder();
                attrBuilder.setName(fieldName);
                attrBuilder.setCreateable(true);
                attrBuilder.setUpdateable(true);
                attrInfos.add(attrBuilder.build());
            }
            
            // Supported class and attributes
            flatFileSchemaBldr.defineObjectClass
              (ObjectClass.ACCOUNT.getDisplayNameKey(),attrInfos);
            System.out.println("schema called: Built the schema properly");
            return flatFileSchemaBldr.build();
        }
     
        @Override
        public Uid create(ObjectClass arg0, Set<Attribute> attrs,
                OperationOptions ops) {
     
            System.out.println("Creating user account " + attrs);
            assertUserObjectClass(arg0);
            try {
                FlatFileUserAccount accountRecord = new FlatFileUserAccount(attrs);
                // Assert uid is there
                assertUidPresence(accountRecord);
     
                // Create the user
                this.flatFileWriter.addAccount(accountRecord);
     
                // Return uid
                String uniqueAttrField = this.flatFileConfig
                        .getUniqueAttributeName();
                String uniqueAttrVal = accountRecord
                        .getAttributeValue(uniqueAttrField);
                System.out.println("User " + uniqueAttrVal + " created");
                
                return new Uid(uniqueAttrVal);
            } catch (Exception ex) {
     
                // If account exists
                if (ex.getMessage().contains("exists"))
                    throw new AlreadyExistsException(ex);
     
                // For all other causes
                System.out.println("Error in create " + ex.getMessage());
                throw ConnectorException.wrap(ex);
            }
        }
     
        @Override
        public void delete(ObjectClass arg0, Uid arg1, OperationOptions arg2) {
            final String uidVal = arg1.getUidValue();
            this.flatFileWriter.deleteAccount(uidVal);
            System.out.println("Account " + uidVal + " deleted");
        }
     
        @Override
        public Uid update(ObjectClass arg0, Uid arg1, Set<Attribute> arg2,
                OperationOptions arg3) {
            String accountIdentifier = arg1.getUidValue();
            // Fetch the account
            FlatFileUserAccount accountToBeUpdated = this.flatFileParser
                    .getAccount(accountIdentifier);
     
            // Update
            accountToBeUpdated.updateAttributes(arg2);
            this.flatFileWriter
                    .modifyAccount(accountIdentifier, accountToBeUpdated);
            System.out.println("Account " + accountIdentifier + " updated");
     
            // Return new uid
            String newAccountIdentifier = accountToBeUpdated
                    .getAttributeValue(this.flatFileConfig.getUniqueAttributeName());
            return new Uid(newAccountIdentifier);
        }
     
        @Override
        public FilterTranslator<Map<String, String>> createFilterTranslator(
                ObjectClass arg0, OperationOptions arg1) {
            // TODO: Create a fine grained filter translator
     
            // Return a dummy object as its not applicable here.
            // All processing happens in the execute query
            return new AbstractFilterTranslator<Map<String, String>>() {
            };
        }
     
        @Override
        public ConnectorObject getObject(ObjectClass arg0, Uid uid,
                OperationOptions arg2) {
            // Return matching record
            String accountIdentifier = uid.getUidValue();
            FlatFileUserAccount userAcc = this.flatFileParser
                    .getAccount(accountIdentifier);
            ConnectorObject userAccConnObject = convertToConnectorObject(userAcc);
            return userAccConnObject;
        }
     
        /*
         * (non-Javadoc)
         * This is the search implementation. 
         * The Map passed as the query here, will map to all the records with 
         * matching attributes.
         * 
         * The record will be filtered if any of the matching attributes are not
         * found
         * 
         * @see
         * org.identityconnectors.framework.spi.operations.SearchOp#executeQuery
         * (org.identityconnectors.framework.common.objects.ObjectClass,
         * java.lang.Object,
         * org.identityconnectors.framework.common.objects.ResultsHandler,
         * org.identityconnectors.framework.common.objects.OperationOptions)
         */
        @Override
        public void executeQuery(ObjectClass objectClass,
                Map<String, String> matchSet, ResultsHandler resultHandler,
                OperationOptions ops) {
     
        System.out.println("Inside executeQuery");
        
            // Iterate over the records and handle individually
            Iterator<FlatFileUserAccount> userAccountIterator = this.flatFileParser
                    .getAccountIterator(matchSet);
     
            while (userAccountIterator.hasNext()) {
                FlatFileUserAccount userAcc = userAccountIterator.next();
                ConnectorObject userAccObject = convertToConnectorObject(userAcc);
                if (!resultHandler.handle(userAccObject)) {
                    System.out.println("Not able to handle " + userAcc);
                    break;
                }
            }
        }
     
        private void assertUserObjectClass(ObjectClass arg0) {
            if (!arg0.equals(ObjectClass.ACCOUNT))
                throw new UnsupportedOperationException(
                        "Only user account operations supported.");
     
        }
     
        private void assertUidPresence(FlatFileUserAccount accountRecord) {
            String uniqueAttrField = this.flatFileConfig.getUniqueAttributeName();
            String uniqueAttrVal = accountRecord.getAttributeValue(uniqueAttrField);
     
            if (uniqueAttrVal == null) {
                throw new IllegalArgumentException("Unique attribute not passed");
            }
        }
     
        private ConnectorObject convertToConnectorObject(FlatFileUserAccount userAcc) {
            ConnectorObjectBuilder userObjBuilder = new ConnectorObjectBuilder();
            // Add attributes
            List<String> attributeNames = this.flatFileMetadata
                    .getOrderedTextFieldNames();
            for (String attributeName : attributeNames) {
                String attributeVal = userAcc.getAttributeValue(attributeName);
                userObjBuilder.addAttribute(attributeName, attributeVal);
     
                if (attributeName.equals(this.flatFileConfig
                        .getUniqueAttributeName())) {
                    userObjBuilder.setUid(attributeVal);
                    userObjBuilder.setName(attributeVal);
                }
            }
            return userObjBuilder.build();
        }
     
        @Override
        public void checkAlive() {
            if (!alive)
                throw new RuntimeException("Connection not alive");
        }
     
    }
    
  3. This connector supports only the ContainsAllValuesFilter operation. Implement the ContainsAllValuesFilter operation Example 17-3 illustrates the sample implementation of org.identityconnectors.framework.common.objects.filter.AbstractFilterTranslator<T> that defines the filter operation.

    Example 17-3 Implementation of AbstractFilterTranslator<T>

    package org.identityconnectors.flatfile.filteroperations;
     
    import java.util.HashMap;
    import java.util.Map;
     
    import org.identityconnectors.framework.common.objects.Attribute;
    import org.identityconnectors.framework.common.objects.filter.AbstractFilterTranslator;
    import org.identityconnectors.framework.common.objects.filter.ContainsAllValuesFilter;
     
    public class ContainsAllValuesImpl extends AbstractFilterTranslator<Map<String, String>>{
    @Override
    protected Map<String, String> createContainsAllValuesExpression(
    ContainsAllValuesFilter filter, boolean not) {
    Map<String, String> containsAllMap = new HashMap<String, String>();
    Attribute attr = filter.getAttribute();
    containsAllMap.put(attr.getName(), attr.getValue().get(0).toString());
    return containsAllMap;
    }
    }
    
  4. Create the connector bundle JAR. The MANIFEST.MF file must contain the following entries:

    • ConnectorBundle-FrameworkVersion

    • ConnectorBundle-Name

    • ConnectorBundle-Version

    Example 17-4 shows the contents of the MANIFEST.MF file:

    Example 17-4 The MANIFEST.MF File

    Manifest-Version: 1.0
    Ant-Version: Apache Ant 1.7.0
    Created-By: 14.1-b02 (Sun Microsystems Inc.)
    ConnectorBundle-FrameworkVersion: 1.0
    ConnectorBundle-Name: org.identityconnectors.flatfile
    ConnectorBundle-Version: 1.0
    Build-Number: 609
    Subversion-Revision: 4582
    
  5. Update the connector bundle JAR as created in step 4. To do so:

    1. Extract the connector bundle JAR into any desired location.

    2. Create a lib directory in the directory in which you extracted the JAR.

    3. Add the dependent third-party JARs into the lib directory.

    4. JAR the entire directory.

      Note:

      The MANIFEST.MF file must contain the entires listed in step 4.

17.1.1 Supporting Classes for File Input and Output Handling

This section shows the implementation of the following supporting classes for file input and output handling:

Example 17-5 shows the implementation of the FlatFileIOFactory supporting class:

Example 17-5 FlatFileIOFactory

package org.identityconnectors.flatfile.io;
 
import org.identityconnectors.flatfile.FlatFileConfiguration;
 
public class FlatFileIOFactory {
    
    private FlatFileMetadata flatFileMetadata;
    private FlatFileConfiguration flatFileConfig;
    
    /**
     * Provides instance of the factory
     * @param flatfileConfig Configuration bean for the flat file
     */
    public static FlatFileIOFactory getInstance(FlatFileConfiguration fileConfig) {
        return new FlatFileIOFactory(fileConfig);        
    }
    
    /**
     * Making it private to avoid public instantiation. Encouraging use of getInstance
     * @param fileConfig
     */
    private FlatFileIOFactory(FlatFileConfiguration fileConfig) {
        this.flatFileConfig = fileConfig;
        this.flatFileMetadata = new FlatFileMetadata(flatFileConfig);
        System.out.println("Metadata set");
    }
    
    /**
     * Returns the metadata instance
     * @return
     */
    public FlatFileMetadata getMetadataInstance() {
        return this.flatFileMetadata;
    }
    
    /**
     * Returns the FlatFileParser instance
     * @return
     */
    public FlatFileParser getFileParserInstance() {
        return new FlatFileParser(this.flatFileMetadata, this.flatFileConfig);
    }
    
    /**
     * Returns the FlatFileWriter instance
     * @return
     */
    public FlatFileWriter getFileWriterInstance() {
        return new FlatFileWriter(this.flatFileMetadata, this.flatFileConfig);
    }
}

Example 17-6 shows the implementation of the FlatFileMetaData supporting class:

Example 17-6 FlatFileMetadata

package org.identityconnectors.flatfile.io;
 
import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.StringTokenizer;
 
import org.identityconnectors.flatfile.FlatFileConfiguration;
 
/**
 * This class contains all the metadata related information Example: Ordering of
 * columns, Number of columns etc.
 * 
 * @author harsh
 * 
 */
public class FlatFileMetadata {
 
    private FlatFileConfiguration fileConfig;
 
    private List<String> orderedTextFieldNames;
 
    private String changeLogFieldName;
    private String uniqueAttributeFiledName;
 
    /**
     * Instantiates the class with the file configuration.
     * Making it package private to encourage instantiation from Factory class
     * @param fileConfig
     */
    FlatFileMetadata(FlatFileConfiguration fileConfig) {
        /*
         * Ideally you should not take connector specific configuration class in
         * flat file resource classes. Change if this has to go to production.
         * Probably make another configuration class for flat file with same
         * signatures.
         */
        this.fileConfig = fileConfig;
 
        initializeMetadata();
        validateConfigProps();
    }
 
    /**
     * Returns the text field names in the order of their storage
     * 
     * @return
     */
    public List<String> getOrderedTextFieldNames() {
        return this.orderedTextFieldNames;
    }
 
    /**
     * Returns the number of columns
     */
    public int getNumberOfFields() {
        int numberOfTextFields = this.orderedTextFieldNames.size();
        return numberOfTextFields;
    }
 
    /**
     * Specifies if number of tokens are matching with the standard length of metadata
     * @param countTokens
     * @return
     */
    public boolean isDifferentFromNumberOfFields(int countTokens) {
        return (getNumberOfFields() != countTokens);
    }
    
    /**
     * Reads the header line and sets the metadata
     */
    private void initializeMetadata() {
        // Read the file.
        File recordsStore = this.fileConfig.getStoreFile();
 
        try {
            BufferedReader storeFileReader = new BufferedReader(new FileReader(
                    recordsStore.getAbsolutePath()));
 
            // Read the header line
            String headerString = storeFileReader.readLine();
 
            // Tokenize the headerString
            StringTokenizer tokenizer = new StringTokenizer(headerString,
                    fileConfig.getTextFieldDelimeter());
 
            this.orderedTextFieldNames = new ArrayList<String>();
            while (tokenizer.hasMoreTokens()) {
                String header = tokenizer.nextToken();
                this.orderedTextFieldNames.add(header);
            }
            
            System.out.println("Columns read - " + this.orderedTextFieldNames);
        } catch (IOException e) {
            throw new RuntimeException("How can I read a corrupted file");
        }
 
        // Store the change log and unique attribute field names
        this.changeLogFieldName = fileConfig.getChangeLogAttributeName();
        this.uniqueAttributeFiledName = fileConfig.getUniqueAttributeName();
    }
 
    /**
     * Validate if the attribute names in config props object are present in the
     * column names
     * 
     * @throws RuntimeException
     *             if validation fails
     */
    private void validateConfigProps() {
        // Check if unique attribute col name is present
        if (!this.orderedTextFieldNames.contains(this.changeLogFieldName))
            throw new RuntimeException("Change log field name "
                    + this.changeLogFieldName + " not found in the store file ");
 
        // Check if change col name is present
        if (!this.orderedTextFieldNames.contains(this.uniqueAttributeFiledName))
            throw new RuntimeException("Unique attribute field name "
                    + this.uniqueAttributeFiledName
                    + " not found in the store file");
    }
}

Example 17-7 shows the implementation of the FlatFileParser supporting class:

Example 17-7 FlatFileParser

package org.identityconnectors.flatfile.io;
 
import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
 
import org.identityconnectors.flatfile.FlatFileConfiguration;
import org.identityconnectors.flatfile.FlatFileUserAccount;
import org.identityconnectors.flatfile.utils.AccountConversionHandler;
 
public class FlatFileParser {
 
    private File recordsStore;
    private FlatFileConfiguration fileConfig;
    private FlatFileMetadata metadata;
    private AccountConversionHandler accountConverter;
 
    /**
     * Instantiates the parser class. Making it package private to encourage
     * instantiation from Factory class
     * 
     * @param metadata
     * @param fileConfig
     */
    FlatFileParser(FlatFileMetadata metadata, FlatFileConfiguration fileConfig) {
        this.fileConfig = fileConfig;
        this.recordsStore = fileConfig.getStoreFile();
        this.accountConverter = new AccountConversionHandler(metadata,
                fileConfig);
        this.metadata = metadata;
    }
 
    /**
     * Returns all accounts in the file
     * 
     * @return
     */
    public List<FlatFileUserAccount> getAllAccounts() {
        try {
            BufferedReader userRecordReader = new BufferedReader(
                    new FileReader(recordsStore.getAbsolutePath()));
            String recordStr;
 
            // Skip headers
            userRecordReader.readLine();
 
            // Loop over records and make list of objects
            List<FlatFileUserAccount> allAccountRecords = new ArrayList<FlatFileUserAccount>();
            while ((recordStr = userRecordReader.readLine()) != null) {
                try {
                    FlatFileUserAccount accountRecord = accountConverter
                            .convertStringRecordToAccountObj(recordStr);
                    allAccountRecords.add(accountRecord);
                } catch (RuntimeException e) {
                    System.out.println("Invalid entry " + e.getMessage());
                }
            }
            userRecordReader.close();
 
            return allAccountRecords;
        } catch (IOException e) {
            throw new RuntimeException("How can I read a corrupted file");
        }
    }
 
    /**
     * Gets the account of matching account identifier
     * 
     * @param accountIdentifier
     * @return
     */
    public FlatFileUserAccount getAccount(String accountIdentifier) {
 
        /*
         * I know its not right to get all account details. Don't want to focus
         * on efficiency and scalability as this is just a sample.
         */
        // Iterate over all records and check for matching account
        Map<String, String> matchSet = new HashMap<String, String>();
        matchSet.put(fileConfig.getUniqueAttributeName(), accountIdentifier);
        for (FlatFileUserAccount userRecord : getAllAccounts()) {
            if (userRecord.hasMatchingAttributes(matchSet))
                return userRecord;
        }
 
        // Got nothing..
        return null;
    }
 
    /**
     * Returns all records with matching Attributes If more than attributes are
     * passed. it will check all the attributes
     * 
     * @param matchSet
     *            Checks if all provided attributes are matched
     */
    public List<FlatFileUserAccount> getAccountsByMatchedAttrs(
            Map<String, String> matchSet) {
        /*
         * I know its not right to get all account details. Don't want to focus
         * on efficiency and scalability as this is just a sample.
         */
        // Iterate over all records and check for matching account
        List<FlatFileUserAccount> matchingRecords = new ArrayList<FlatFileUserAccount>();
        for (FlatFileUserAccount userRecord : getAllAccounts()) {
            if (userRecord.hasMatchingAttributes(matchSet))
                matchingRecords.add(userRecord);
        }
 
        return matchingRecords;
    }
 
    /**
     * Returns the records that fall after the specified change number This
     * function helps in checking the function of sync
     * 
     * @param changeNumber
     *            the change number for the last search
     */
    public List<FlatFileUserAccount> getUpdatedAccounts(int changeNumber) {
        /*
         * I know its not right to get all account details. Don't want to focus
         * on efficiency and scalability as this is just a sample.
         */
        // Iterate over all records and check for matching account
        List<FlatFileUserAccount> matchingRecords = new ArrayList<FlatFileUserAccount>();
        String changeLogAttrName = fileConfig.getChangeLogAttributeName();
        for (FlatFileUserAccount userRecord : getAllAccounts()) {
            int recordChangeNumber = userRecord
                    .getChangeNumber(changeLogAttrName);
            if (recordChangeNumber >= changeNumber)
                matchingRecords.add(userRecord);
        }
        return matchingRecords;
 
    }
 
    /**
     * Returns an iterator that iterates over the records. This is provided for
     * dynamic retrieval of records
     * 
     * @param matchSet
     *            Filters the records by matching the given attributes. Use null
     *            or empty set to avoid filtering
     * @return
     */
    public Iterator<FlatFileUserAccount> getAccountIterator(
            Map<String, String> matchSet) {
        Iterator<FlatFileUserAccount> recordIterator = new FlatFileLineIterator(
                this.metadata, this.fileConfig, matchSet);
 
        return recordIterator;
    }
 
    /**
     * Gives the next change number. Logic is max of existing change numbers + 1
     * @return
     */
    public int getNextChangeNumber() {
        int maximumChangeNumber = 0;
 
        /*
         * I know its not right to get all account details. Don't want to focus
         * on efficiency and scalability as this is just a sample.
         */
        // Iterate over all records and check for matching account
        String changeLogAttrName = fileConfig.getChangeLogAttributeName();
        for (FlatFileUserAccount userRecord : getAllAccounts()) {
            int changeNumber = userRecord.getChangeNumber(changeLogAttrName);
 
            if (changeNumber >= maximumChangeNumber) {
                maximumChangeNumber = changeNumber + 1;
            }
        }
        return maximumChangeNumber;
    }
}

Example 17-8 shows the implementation of the FlatFileWriter supporting class:

Example 17-8 FlatFileWriter

package org.identityconnectors.flatfile.io;
 
import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;
 
import org.identityconnectors.flatfile.FlatFileConfiguration;
import org.identityconnectors.flatfile.FlatFileUserAccount;
import org.identityconnectors.flatfile.utils.AccountConversionHandler;
 
/**
 * Class for searching operations on files
 * 
 * @author Harsh
 */
public class FlatFileWriter {
 
    private File recordsStore;
    private FlatFileParser recordParser;
    private FlatFileConfiguration fileConfig;
    private AccountConversionHandler accountConverter;
 
    /**
     * Initializes the writer with the configuration Making it package private
     * to encourage use of Factory class for global instantiation
     * 
     * @param metadata
     * @param fileConfig
     */
    FlatFileWriter(FlatFileMetadata metadata, FlatFileConfiguration fileConfig) {
        this.fileConfig = fileConfig;
 
        this.recordsStore = fileConfig.getStoreFile();
        recordParser = new FlatFileParser(metadata, fileConfig);
        accountConverter = new AccountConversionHandler(metadata, fileConfig);
    }
 
    /**
     * Appends the user record at the end of
     * 
     * @param accountRecord
     */
    public void addAccount(FlatFileUserAccount accountRecord) {
        try {
            BufferedWriter userRecordWriter = new BufferedWriter(
                    new FileWriter(this.recordsStore.getAbsolutePath(), true));
 
            // Set the latest changelog number
            int latestChangeNumber = recordParser.getNextChangeNumber();
            accountRecord.setChangeNumber(fileConfig
                    .getChangeLogAttributeName(), latestChangeNumber);
 
            // Validate if same account id doesn't exist
            String accountUid = accountRecord.getAttributeValue(fileConfig
                    .getUniqueAttributeName());
            FlatFileUserAccount accountByAccountId = recordParser
                    .getAccount(accountUid);
 
            if (accountByAccountId != null)
                throw new RuntimeException("Account " + accountUid
                        + " already exists");
 
            // Put the user record in formatted way
            String userRecordAsStr = accountConverter
                    .convertAccountObjToStringRecord(accountRecord);
            userRecordWriter.write("\n" + userRecordAsStr);
 
            // Close the output stream
            userRecordWriter.close();
        } catch (IOException e) {// Catch exception if any
            throw new RuntimeException("How can I write on a corrupted file");
        }
    }
 
    /**
     * Removes the entry for respective account identifier
     * 
     * @param accountIdentifier
     */
    public void deleteAccount(String accountIdentifier) {
        String blankRecord = "";
        this.modifyAccountInStore(accountIdentifier, blankRecord);
    }
 
    /**
     * Updates the entry with respective account identifier
     * 
     * @param accountIdentifier
     * @param updatedAccountRecord
     * @return new accountIdentifier
     */
    public String modifyAccount(String accountIdentifier,
            FlatFileUserAccount updatedAccountRecord) {
 
        // Frame a record string and update back to file
        int nextChangeNumber = recordParser.getNextChangeNumber();
 
        String changeNumberFieldName = fileConfig.getChangeLogAttributeName();
        updatedAccountRecord.setChangeNumber(changeNumberFieldName,
                nextChangeNumber);
 
        String newRecordAsStr = accountConverter
                .convertAccountObjToStringRecord(updatedAccountRecord);
        // Update to the file
        this.modifyAccountInStore(accountIdentifier, newRecordAsStr);
 
        // Return new UID
        String uniqueAttrFieldName = fileConfig.getUniqueAttributeName();
        String newAccountIdentifier = updatedAccountRecord
                .getAttributeValue(uniqueAttrFieldName);
        return newAccountIdentifier;
    }
 
    /**
     * Returns the complete flat file as string.
     * 
     * @return
     */
    private String getCompleteFlatFileAsStr() {
        try {
            BufferedReader userRecordReader = new BufferedReader(
                    new FileReader(recordsStore.getAbsolutePath()));
            String recordStr;
 
            // Loop over records and make list of objects
            StringBuilder flatFileStr = new StringBuilder();
            while ((recordStr = userRecordReader.readLine()) != null) {
                if (!recordStr.isEmpty())
                    flatFileStr.append(recordStr + "\n");
            }
            userRecordReader.close();
 
            return flatFileStr.toString();
        } catch (IOException e) {
            throw new RuntimeException("How can I read a corrupted file");
        }
    }
 
    /**
     * Updates the account with the new record. this can also be used for delete
     * 
     * @param accountIdentifier
     * @param updatedRecord
     */
    private void modifyAccountInStore(String accountIdentifier,
            String updatedRecord) {
        try {
            // Load the complete flat file
            String completeFlatFile = this.getCompleteFlatFileAsStr();
 
            // Construct the string to be removed and replace it with blank
            FlatFileUserAccount accountToBeRemoved = recordParser
                    .getAccount(accountIdentifier);
            String updatableString = accountConverter
                    .convertAccountObjToStringRecord(accountToBeRemoved);
            String updatedFlatFile = completeFlatFile.replaceAll(
                    updatableString, updatedRecord);
 
            // Rewrite the file
            BufferedWriter userRecordWriter = new BufferedWriter(
                    new FileWriter(this.recordsStore.getAbsolutePath(), false));
            userRecordWriter.write(updatedFlatFile);
 
            /*** debug ***/
            System.out.println("Old string " + updatableString);
            System.out.println("New String" + updatedRecord);
            System.out.println("new file - " + updatedFlatFile);
 
            /******/
            // Close the output stream
            userRecordWriter.close();
        } catch (IOException e) {// Catch exception if any
            throw new RuntimeException("How can I write on a corrupted file");
        }
    }
}

17.2 Uploading the Identity Connector Bundle to Oracle Identity Manager Database

The identity connector bundle must be available to ICF in Oracle Identity Manager database. Follow the list of sections in order to integrate the ICF identity connector with Oracle Identity Manager. Some of the procedures include configuration by using the Oracle Identity Manager Design Console.

17.2.1 Registering the Connector Bundle with Oracle Identity Manager

The connector bundle must be available for the Connector Server local to Oracle Identity Manager. Following is the procedure to accomplish this:

  1. Copy the connector bundle JAR to the machine on which Oracle Identity Manager in installed.

  2. Run the following command to upload the JAR.

    $MW_HOME/server/bin/UploadJars.sh

    Note:

    In this chapter, DW_HOME represents $MW_HOME/Oracle_IDM1.

  3. Select ICFBundle as the JAR type.

  4. Enter the location of the connector bundle JAR.

  5. Press Enter.

17.2.2 Creating Basic Identity Connector Metadata

This metadata configuration is needed for both provisioning and reconciliation. The set of procedures in this section are completed by using the Oracle Identity Manager Design Console.

17.2.2.1 Creating the IT Resource Type Definition

An IT resource type definition is the representation of a resource's connection information. The configuration parameters in the IT resource type definition should be matched with the configuration parameters of the connector bundle. The values of the parameters in the IT resource will be set in the bundle configuration.

Note:

You may include parameters the bundle configuration is not using. They produce no negative effects on the bundle operations.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click IT Resource Type Definition under Resource Management.

  3. Create a new IT Resource Type Definition with the Server Type defined as Flat File.

  4. Add the following parameters as illustrated in Figure 17-1.

    • Configuration Lookup is the marker of the main configuration lookup for the resource. The name of the parameter must be Configuration Lookup. It is a good practice to add a value to Default Field Value.

    • textFieldDelimeter maps to the textFieldDelimeter parameter in the bundle configuration. The value of this parameter will be passed.

    • storeFile maps to the storeFile parameter in the bundle configuration. The value of this parameter will be passed.

    Figure 17-1 IT Resource Type Definition in Design Console

    Description of Figure 17-1 follows
    Description of "Figure 17-1 IT Resource Type Definition in Design Console"

17.2.2.2 Creating the Resource Object

The resource object is the Oracle Identity Manager representation of a resource. The connector bundle is tied to the resource object.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Resource Objects under Resource Management.

  3. Create a new resource object with the name FLATFILERO.

    As the resource object is a target resource don't check the Trusted Source box as illustrated in Figure 17-2.

    Figure 17-2 Resource Objects in Design Console

    Description of Figure 17-2 follows
    Description of "Figure 17-2 Resource Objects in Design Console"

17.2.2.3 Creating Lookups

Separate lookups have to be defined for different objects supported by the connector bundle. This lookup can contain provisioning and reconciliation related information for those objects. The Main Configuration Lookup is the root for object specific lookups as it contains the pointers to those lookups. The following sections contain information on how to create lookups.

17.2.2.3.1 Creating the Main Configuration Lookup

The Configuration Lookup (as defined in Section 17.2.2.1, "Creating the IT Resource Type Definition") holds connector bundle configurations that are not counted as connection information. If a configuration parameter is not found in the IT Resource Type Definition, Oracle Identity Manager will look in the Configuration Lookup. The main Configuration Lookup contains bundle properties and bundle configurations. Bundle Property parameters are mandatory as they are needed for identifying the correct bundle. Bundle configurations that are not defined as part of the IT resource type definition (discussed in Section 17.2.2.1, "Creating the IT Resource Type Definition") can be declared here.

Note:

The values for Code Key should match exactly as illustrated. The values for Decode are specific to the connector bundle.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Lookup Definition under Administration.

  3. Create a new lookup and add Lookup.FF.Configuration as the value for Code.

  4. Add the following Lookup Code Information as illustrated in Figure 17-3.

    • Add VERSION as the required Bundle Version.

    • Add org.identityconnectors.flatfile as the required Bundle Name.

    • Add org.identityconnectors.flatfile.FlatFileConnector as the required Connector Name.

    • Add AccountId as the value of uniqueAttributeName. AccountId is a unique string identifier that represents the account to be provisioned or reconciled. It is the name of the column in the flat file. AccountId is unique and is used to represent a user (account detail) uniquely.

    • Add ChangeNumber as the value of changeLogAttributeName. When an account is created, a number is attached to it indicating the total accounts created. This value is maintained in the variable called ChangeNumber.

    • OBJECT_TYPE_NAME Configuration Lookup is the configuration lookup for the particular object type. In this example, the object type is User as User Configuration Lookup is defined.

    Figure 17-3 Lookup Definition in Design Console

    Description of Figure 17-3 follows
    Description of "Figure 17-3 Lookup Definition in Design Console"

17.2.2.3.2 Creating Object Type Configuration Lookup

Object type configuration lookup contains the parameters specific to the particular object type. Object type is an entity over which an identity connector operates. It is mapped to ICF ObjectClass. In Section 17.2.2.3.1, "Creating the Main Configuration Lookup," User Configuration Lookup has been referenced so that User is the object type, in this case mapped to ObjectClass.ACCOUNT. (Roles and UserJobData are two other object types.) The object type name has to match with ObjectClass name supported by the identity connector bundle. The User object type is mapped to predefined ObjectClass.ACCOUNT, the Group object type is mapped to predefined ObjectClass.GROUP. If the identity connector supports multiple objects, then this step must be repeated for each.

Note:

Because these use cases cover only the basic functionality, the configuration is kept to the mandatory attribute.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Lookup Definition under Administration.

  3. Create a new Lookup and add Lookup.FF.UM.Configuration as the Code.

  4. Set the following attributes as illustrated in Figure 17-4.

    Note:

    This tutorial focuses on the minimum configurations needed to run an identity connector.

    • Provisioning Attribute Map takes a value of Lookup.FF.UM.ProvAttrMap. This lookup contains the mapping between Oracle Identity Manager fields and identity connector attributes. The mapping is used during provisioning.

    • Reconciliation Attribute Map takes a value of Lookup.FF.UM.ReconAttributeMap. This lookup contains the mapping between Oracle Identity Manager reconciliation fields and identity connector attributes. The mapping is used during reconciliation.

      Figure 17-4 Second Lookup Definition in Design Console

      Description of Figure 17-4 follows
      Description of "Figure 17-4 Second Lookup Definition in Design Console"

17.2.3 Creating Provisioning Metadata

The following sections should be followed in order to configure Oracle Identity Manager for flat file provisioning.

17.2.3.1 Creating a Process Form

A process form is used as the representation of object attributes on Oracle Identity Manager. This facilitates user input to set object attributes before passed to the connector bundle for an operation.

Attributes defined in the process form are not conventions. The form is a way to challenge the attributes that need to be passed to the identity connector. In general, define an attribute for each supported attribute in the identity connector.

Note:

It is good practice to have a one to one mapping on the identity connector attributes.

There should be a field for querying the IT resource that should be associated with the respective IT Resource Type Definition. Variable type of each field should map to the type of the object attribute.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Form Designer under Development Tools.

  3. Create a new form with the Table Name UD_FLAT_FIL as illustrated in Figure 17-5.

    Figure 17-5 Form Designer in Design Console

    Description of Figure 17-5 follows
    Description of "Figure 17-5 Form Designer in Design Console"

  4. Add the attributes defined in the connector schema, as listed in Table 17-1.

    Table 17-1 Form Designer Fields

    Name Variant Field Label Field Type

    UD_FLAT_FIL_FIRSTNAME

    String

    First Name

    TextField

    UD_FLAT_FIL_UID

    String

    Universal ID

    TextField

    UD_FLAT_FIL_CHANGENO

    String

    Change Number

    TextField

    UD_FLAT_FIL_MAILID

    String

    Email ID

    TextField

    UD_FLAT_FIL_SERVER

    long

    Server

    ITResource

    UD_FLAT_FIL_LASTNAME

    String

    Last Name

    TextField

    UD_FLAT_FIL_ACCOUNTID

    String

    Account ID

    TextField

    UD_FLAT_FIL_RETURN

    String

    Return ID

    TextField


    Note:

    The flat file column names are FirstName, ChangeNo, EmailID, Server, LastName, and AccountID.

  5. Click the Properties tab.

  6. Add the following properties to Server(ITResourceLookupField) as illustrated in Figure 17-6.

    • Required = true

    • Type = Flat File

    Figure 17-6 Properties of Form Designer in Design Console

    Description of Figure 17-6 follows
    Description of "Figure 17-6 Properties of Form Designer in Design Console"

  7. Save the form.

  8. Click Make Version Active.

17.2.3.2 Creating Adapters

An adapter has to be created for all operations supported by the connector bundle, including Create, Update, and Delete.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Adapter Factory under Development Tools.

  3. Create a new adapter and add FFCreateUser as the Adapter Name.

  4. Add Process Task as the Adapter Type.

  5. Save the adapter.

  6. Click the Variable List tab and add the following variables, as shown in Figure 17-7.

    • objectType with Type String and Mapped as Resolve at runtime.

    • processInstanceKey with Type long and Mapped as Resolve at runtime.

    • itResourceFieldName with Type String and Mapped as Resolve at runtime.

    Figure 17-7 Adapter Factory Variable List in Design Console

    Description of Figure 17-7 follows
    Description of "Figure 17-7 Adapter Factory Variable List in Design Console"

  7. Add a Java functional task to the adapter by following this sub procedure, as shown in Figure 17-8.

    1. Click the Adapter Tasks tab.

    2. Select the adapter and click Add.

    3. Select Java from the task options.

    4. Select icf-oim-intg.jar from the API source.

    5. Select oracle.iam.connetors.icfcommon.prov.ICProvisioninManager as the API Source.

    6. Select createObject as the method for the task.

    7. Save the configurations.

    8. Map the variables (previously added to the Variables List) against the appropriate method inputs and outputs.

    9. Map the configuration parameters against the appropriate method inputs and outputs.

      Database Reference maps to Database Reference (Adapter References) and Return Variable maps to Return Variable (Adapter Variables).

    Figure 17-8 Adapter Factory in Design Console

    Description of Figure 17-8 follows
    Description of "Figure 17-8 Adapter Factory in Design Console"

  8. Save and build the adapter.

17.2.3.3 Creating A Process Definition

Process Definition defines the behavior of the connector bundle for a particular operation. Every operation has a corresponding task associated with it. This procedure will configure the process definition and integration of the process task for the Create operation.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Process Definition under the Process Management tab.

  3. Create a new process definition and name it Flat File as illustrated in Figure 17-9.

    Figure 17-9 Process Definition in Design Console

    Description of Figure 17-9 follows
    Description of "Figure 17-9 Process Definition in Design Console"

  4. Select Provisioning as the Type of process.

  5. Provide the resource Object Name for the identity connector; in this example, FLATFILERO.

  6. Provide the process form Table Name; in this example, UD_FLAT_FIL.

  7. Add a process task and name it Create User.

  8. Double click Create User to edit as illustrated in Figure 17-10.

    Figure 17-10 Editing Task Screen in Design Console

    Description of Figure 17-10 follows
    Description of "Figure 17-10 Editing Task Screen in Design Console"

  9. Click the Integration tab.

  10. Click Add and select the FFCreateUser adapter from the list as illustrated in Figure 17-11.

    The adapter will be available only after it is compiled.

    Figure 17-11 Integration Tab in Design Console

    Description of Figure 17-11 follows
    Description of "Figure 17-11 Integration Tab in Design Console"

  11. Map the variables as follows to set the response code returned by the identity connector.

    • Adapter Return Variable – Response Code

    • Object Type – [Literal:String] User (Name of the object type)

    • Process Instance Key – [Process Data] Process Instance

    • IT Resource Field Name – [Literal:String] UD_FLAT_FIL_SERVER (Form field name that contains the IT resource information)

  12. Click the Responses tab and configure the responses as illustrated in Figure 17-12.

    • UNKNOWN can be described as Unknown response received with a status of R (Rejected).

    • SUCCESS can be described as Operation completed with a status of C (Completed).

    • ERROR can be described as Error occurred with a status of R.

    Figure 17-12 Configure Responses in Design Console

    Description of Figure 17-12 follows
    Description of "Figure 17-12 Configure Responses in Design Console"

  13. Click the Task to Object Status Mapping tab.

  14. Update the Object Status to Provisioned for Status C, as shown in Figure 17-13:

    Figure 17-13 Task to Object Status Mapping

    Description of Figure 17-13 follows
    Description of "Figure 17-13 Task to Object Status Mapping"

  15. Save the process task.

17.2.3.4 Creating a Provisioning Attribute Mapping Lookup

Provisioning Attribute Mapping Lookup contains mappings of Oracle Identity Manager fields to identity connector bundle attributes. In the Provisioning Attribute Mapping Lookup:

  • Code keys are Field Labels of the process form.

  • Decodes are identity connector bundle attributes.

  • Child form attributes can be configured as embedded objects in inputs.

  • The identity connector's provisioning operation returns the UID in response. This can be set in a form field by coding it against the identity connector bundle attribute.

Following is the procedure to create a Provisioning Attribute Mapping Lookup.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Lookup Definition under the Administration tab.

  3. Create a new lookup and name it Lookup.FF.UM.ProvAttrMap.

    The name of this lookup is referred from the object type configuration lookup. See Section 17.2.2.3.2, "Creating Object Type Configuration Lookup."

  4. Add the form Field Labels as the code keys and identity connector bundle attributes as the decode.

    • Return ID : __UID__

    • Account ID: AccountId

    • Change Number: ChangeNumber

    • First Name: FirstName

    • Last Name: LastName

    • Email ID: MailId

17.2.3.4.1 Field Flags Used in the Provisioning Attributes Map

For provisioning attributes mapping, the following field flags can be appended to the code key:

  • LOOKUP: This must be specified for all fields whose values are obtained by running a lookup reconciliation job. The values obtained from lookup reconciliation job have IT Resource Name/Key appended to it. Specifying this flag helps ICF integration to remove the appended value just before passing them onto the bundle. For example, the code key for a field with label Database whose value is obtained by running a lookup reconciliation job looks similar to Database[LOOKUP].

    Note:

    The LOOKUP flag can be specified for both Provisioning and Reconciliation Attribute Map. For provisioning, IT Resource Name/IT Resource Key prefix must be removed. For reconciliation, IT Resource Name/IT Resource Key prefix must be added.

  • IGNORE: This must be specified for all fields whose values are to be ignored and not sent to bundle. For example, the code key for a field with label Database whose value need not be sent to bundle looks similar to Database[IGNORE].

  • WRITEBACK: This must be specified for all fields whose values need to be written back into the process form right after the create or update operation. Adding this flag makes the ICF integration layer call ICF Get API to get values of attributes marked with the WRITEBACK flag. For example, the code key for a field with label Database whose value needs to be written back to the process form right after create/update looks similar to Database[WRITEBACK]. For this to work, the connector must implement the GetApiOp interface and provide an implementation for the ConnectorObject getObject(ObjectClass objClass,Uid uid,OperationOptions options) API. This API searches the target for the account whose Uid is equal to the passed in Uid, and builds a connector object containing all the attributes (and their values) that are to be written back to process form.

    Note:

    If the connector does not implement the GetApiOp interface, then the WRITEBACK flag does not work and an error is generated.

  • DATE: This must be specified for fields whose type need to be considered as Date, without which the values are considered as normal strings. For example, the code key for a field with label Today whose value needs to be displayed in the date format looks similar to Today[DATE].

  • PROVIDEONPSWDCHANGE: This must be specified for all fields that need to be provided to the bundle(target) when a password update happens. Some targets expect additional attributes to be specified on every password change. Specifying the PROVIDEONPSWDCHANGE flag, tells ICF integration to send all the extra fields or attributes whenever a password change is requested. For example, the code key for a field with label Extra Attribute Needed for Password Change whose value needs to be provided to bundle(target) while password update looks similar to Extra Attribute Needed for Password Change[PROVIDEONPSWDCHANGE].

17.2.4 Creating Reconciliation Metadata

This section contains the procedures to configure the reconciliation of records from the flat file. We will use the target reconciliation as an example; trusted reconciliation can also be configured in a similar fashion. Do the procedures in the listed order.

  1. Creating a Reconciliation Schedule Task

  2. Creating a Reconciliation Profile

  3. Setting a Reconciliation Action Rule

  4. Creating Reconciliation Mapping

  5. Defining a Reconciliation Matching Rule

17.2.4.1 Creating a Reconciliation Schedule Task

By default, reconciliation uses a Search operation on the connector bundle. This operation is invoked with a schedule task configured using Oracle Identity Manager. This procedure is comprised of the following sub procedures.

  1. Defining the Schedule Task

  2. Creating a Scheduled Task

17.2.4.1.1 Defining the Schedule Task

To define the scheduled task:

  1. Create a Deployment Manager XML file containing the scheduled task details as shown in Example 17-9. Make sure to update database value to your database.

    Example 17-9 Deployment Manager XML with Scheduled Task Details

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <xl-ddm-data version="2.0.1.0" user="XELSYSADM" database="jdbc:oracle:thin:@localhost:5524/estView.regress.rdbms.dev.us.oracle.com" exported-date="1307546406635" description="FF">
    <scheduledTask repo-type="MDS" name="Flat File Connector User Reconciliation" mds-path="/db" mds-file="Flat File Connector User Reconciliation.xml">
        <completeXml>
            <scheduledTasks xmlns="http://xmlns.oracle.com/oim/scheduler">
                <task>
                <name>Flat File Connector User Reconciliation</name>
                <class>oracle.iam.connectors.icfcommon.recon.SearchReconTask</class>
                <description>Flat File Connector User Reconciliation</description>
                <retry>0</retry>
                <parameters>
                  <string-param required="false" encrypted="false" helpText="Filter">Filter</string-param>
                  <string-param required="false" encrypted="false" helpText="Incremental Recon Date Attribute">Incremental Recon Date Attribute</string-param>
                  <string-param required="false" encrypted="false" helpText="IT Resource Name">IT Resource Name</string-param>
                  <string-param required="false" encrypted="false" helpText="Object Type">Object Type</string-param>
                  <string-param required="false" encrypted="false" helpText="Latest Token">Latest Token</string-param>
                  <string-param required="false" encrypted="false" helpText="Resource Object Name">Resource Object Name</string-param>
                </parameters>
              </task>
            </scheduledTasks>
        </completeXml>
    </scheduledTask>
    </xl-ddm-data>
    
  2. Save the file as Flat File Connector User Reconciliation.xml.

  3. Login into the Administrative and User Console. Click Import Deployment Manager File.

  4. Select the Flat File Connector User Reconciliation.xml file, and click Import.

  5. Complete the steps in the wizard.

17.2.4.1.2 Creating a Scheduled Task

This procedure explains how to create a scheduled task.

  1. Log in to the Oracle Identity Manager Advanced Administration.

  2. Click Scheduler under the System Management tab.

  3. Add a schedule task and add Flat File Connector User Reconciliation as the type as illustrated in Figure 17-14.

    Figure 17-14 Schedule Task Screen in Advanced Console

    Description of Figure 17-14 follows
    Description of "Figure 17-14 Schedule Task Screen in Advanced Console"

  4. Set the parameters as follows:

    • IT Resource Name takes a value of Flat File.

    • Resource Object Name takes a value of FLATFILERO.

    • Object Type takes a value of User.

  5. Click Apply.

17.2.4.2 Creating a Reconciliation Profile

A reconciliation profile defines the structure of the object attributes while reconciliation. The reconciliation profile should contain all the attributes that have reconciliation support.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Resource Objects under Resource Management.

  3. Open the FLATFILERO resource object.

  4. Click the Object Reconciliation tab as illustrated in Figure 17-15.

    Figure 17-15 Object Reconciliation in Design Console

    Description of Figure 17-15 follows
    Description of "Figure 17-15 Object Reconciliation in Design Console"

  5. Add following reconciliation fields:

    • First Name [String]

    • Universal ID [String]

    • Email ID [String]

    • IT Resource Name [String]

    • Last Name [String]

    • Account ID [String], Required

  6. Save the configuration.

17.2.4.3 Setting a Reconciliation Action Rule

A Reconciliation Action Rule defines the behavior of reconciliation. In this procedure, define the expected action when a match is found. This procedure assumes you are logged into the Oracle Identity Manager Design Console.

  1. Open the FLATFILERO resource object.

  2. Click the Object Reconciliation tab.

  3. Click the Reconciliation Action Rules tab in the right frame.

    Figure 17-16 Reconciliation Action Rules in Design Console

    Description of Figure 17-16 follows
    Description of "Figure 17-16 Reconciliation Action Rules in Design Console"

  4. Add an action rule defined as One Process Match Found (Rule Condition) and Establish Link (Action).

  5. Add an action rule defined as One Entity Match Found (Rule Condition) and Establish Link (Action).

  6. Click Create Reconciliation Profile.

  7. Click Save.

17.2.4.4 Creating Reconciliation Mapping

The reconciliation mapping has to be done in the process definition. This is to map the supported reconciliation fields (from resource object) to the process form fields. This mapping is needed only for configuring target reconciliation.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Click Process Definition under Process Management.

  3. Open the Flat File process definition.

  4. Click the Reconciliation Field Mappings tab as illustrated in Figure 17-17.

    Figure 17-17 Reconciliation Field Mapping in Design Console

    Description of Figure 17-17 follows
    Description of "Figure 17-17 Reconciliation Field Mapping in Design Console"

  5. Add mappings between the reconciliation profile fields and the process form fields.

    • First Name[String] = UD_FLAT_FIL_FIRSTNAME

    • Email ID[String] = UD_FLAT_FIL_MAILID

    • IT Resource Name[String] = UD_FLAT_FIL_SERVER

    • Last Name[String] = UD_FLAT_FIL_LASTNAME

    • Account ID [String] = UD_FLAT_FIL_ACCOUNTID <KEY>

      <KEY> sets Account ID as a key field.

  6. Save the configuration.

17.2.4.4.1 Field Flags Used in the Reconciliation Attributes Map

For reconciliation attributes mapping, the following field flags can be appended to the code key:

  • TRUSTED: This must be specified in the Recon Attribute Map for the field that represents the status of the account. This flag must be specified only for trusted reconciliation. If this is specified, then the status of the account is either Active or Disabled. Otherwise, the status is either Enabled or Disabled. For example, the code key for a field with label Status whose value needs to be either Active/Disabled must look similar to Status[TRUSTED].

  • DATE: In Recon Attribute Map, this must be specified for fields whose type need to be considered as Date. For example, the code key for a field with label Today whose value needs to be displayed in the date format must look similar to Today[DATE].

17.2.4.5 Defining a Reconciliation Matching Rule

A reconciliation matching rule defines the equation for calculating the user match.

  1. Log in to the Oracle Identity Manager Design Console.

  2. Open the Reconciliation Rules form under Development Tools.

  3. Click Add Rule.

    Figure 17-18 Adding Reconciliation Matching Rule

    Description of Figure 17-18 follows
    Description of "Figure 17-18 Adding Reconciliation Matching Rule"

  4. Select resource object FLATFILERO.

  5. Save and add the rule element.

    User Login from the user profile data equals the Account ID resource attribute.

  6. Save the rule.

17.3 Provisioning a Flat File Account

The flat file connector is ready to work so now the user needs to log in to Oracle Identity Manager and create an IT resource (target) using the following procedure.