2 Deploying the Flat File Connector

The procedure to deploy the connector can be divided into various stages namely, preinstallation, installation, postinstallation, and upgrading the connector.

2.1 Preinstallation

Preinstallation for the Flat File connector involves performing certain procedures on Oracle Identity Manager and the enterprise target system.

2.1.1 Exporting Flat Files

From your enterprise target system, you must export the flat file that contains the records that you want to reconcile into Oracle Identity Manager.

Ensure to place the exported flat file at a location that is accessible from the computer hosting Oracle Identity Manager.

2.1.2 Understanding and Creating the Schema File

You must create the schema file to let the connector understand the structure of the flat file that the connector must parse.

This section contains the following topics:

2.1.2.1 Understanding the Schema File Format

The schema file is a .properties file which is used to represent the structure of the flat file that is to be parsed by the connector. It consists of name-value pairs.

It contains details such as datatypes, mandatory attributes, and uid attribute that are specific to the flat file. It is necessary to populate the schema file in the specified format, before using the connector. The schema file is used as an input to the metadata generation utility and is also a mandatory parameter in the IT Resource.

The format in which values must be specified for each property is mentioned in the following topics:

2.1.2.1.1 Understanding Account Qualifiers

These qualifiers are common for the entire flat file and describe certain attributes of an account.

  • FieldNames

    This is a mandatory qualifier. It is a comma separated list of values that must be fetched from the flat file. For example, in a CSV File, this corresponds to the CSV Header line or the name of the column where all the attribute names are present. All child form names, single-valued and multivalued attributes, including the attribute used for performing incremental reconciliation must be specified here. The procedure to configure the schema file for incremental reconciliation is described in Configuring the Connector for Incremental Reconciliation.

    The following is a sample value for the FieldNames qualifier: FieldNames=accountID,accountName,firstname,lastname,status,email,roles,privileges,LastUpdated

  • UidAttribute

    This is a mandatory qualifier. It refers to the name of the attribute that corresponds to the unique id of the account.

    For example: UidAttribute=accountID

  • NameAttribute

    This is a mandatory qualifier. This refers to the name of the attribute that corresponds to a descriptive name of the account.

    For example: NameAttribute=accountName

  • PasswordAttribute

    This is an optional qualifier. It refers to the name of the password attribute of the account.

    For example: PasswordAttribute=accountPwd

  • StatusAttribute

    This is an optional qualifier. It refers to the attribute which denotes the status of the account.

    Oracle Identity Manager requires the values to be true or false. However, if the column in the flat file contains a value other than true or false, then it has to be mapped to True or False. See the "True" or "False" field qualifiers in Configuring the Connector for Status Reconciliation for more information.

  • SystemDateFormat

    This is an optional qualifier. If there are date type fields in the flat file and are specified by a date format, then the format string can be specified in the SystemDateFormat qualifier. The connector will convert these strings to date according to the format.

    See Also:

    Configuring the Connector for Date Type

  • defaultEnableStatus

    Note:

    This qualifier is applicable only if you are using the 12.2.1.x version of the Flat File connector in the CI-based mode.

    This is a mandatory qualifier if your flat file does not contain an attribute which denotes the status of the account. If you do not include this qualifier, then the connector cannot re-enable a disabled account. Therefore, add this qualifier to set the default status for accounts.

    Permitted values for this qualifier are True or False.

    When you set defaultEnableStatus = True, the connector sets the status of all new or revoked accounts to Provisioned and sets the status of disabled accounts to Enabled.

    When you set defaultEnableStatus = False, the connector sets the status of all new or revoked accounts to Disabled and sets the status of enabled accounts to Disabled.

2.1.2.1.2 Understanding Field Qualifiers

These qualifiers are specific to each field and are usually specified in one of the following formats:

  • The following is the format for parent form fields:

    <FIELDNAME>.<FIELDQUALIFIER>=<VALUE>

    Example: accountID.Required=true

  • The following is the format for complex child form fields:

    <FIELDNAME>.<SUBFIELDNAME>.<FIELDQUALIFIER>=<VALUE>.

    Example: Roles.startdate.DataType=Date

The following are the field qualifiers for which values can be specified:

  • Required

    This field qualifier specifies if the mentioned attribute is mandatory. If the value of this qualifier is set to true, the parser will skip processing the records that do not contain this fieldname.

    For example: accountID.Required=true

  • Multivalued

    This field qualifier specifies if the mentioned attribute is a multivalued field.

    For example: Roles.Multivalued=true

  • DataType

    This field qualifier is used to specify the datatype of the field name. The possible values of this qualifier are:

    • String

    • Long

    • Character

    • Double

    • Float

    • Integer

    • Boolean

    • Byte

    • BigDecimal

    • BigInteger

    • Date

    For example: startDate.DataType=Date

    Note:

    You can load date values from a flat file either as Long or String datatype.

    • For loading date values as Long datatype: Set the DataType for the field that must be handled as Date to Long.

    • For loading date values as String datatype:

      1. From the computer hosting Oracle Identity Manager, obtain the value of the XL.DefaultDateFormat system property.

      2. In the schema file, ensure that the datatype of the field that must be handled as Date is set to String and the value of that date field is in String format.

      3. In the flat file, ensure that the string values are in the format obtained in Step 1.

      Irrespective of whether you are loading date values as Long or String, you must enter the date field name in the dateAttributeList entry of the FlatFileConfiguration.groovy file. See the dateAttributeList entry in Configuring the FlatFileConfiguration.groovy File for more information.

  • Subfields

    This field qualifier specifies the subfields in a multivalued attribute if they are present. The subfields must appear in the same order in the flat file as specified here.

    For example: Privileges.Subfields=name,description

  • EmbeddedObjectClass

    This field qualifier specifies the object class name of child forms that have more than one subfield. The value of this qualifier is used internally by ICF and is mandatory for all complex child forms.

    For example: privileges.EmbeddedObjectClass=Privileges

  • True

    If any field is marked as Boolean (such as, Field.DataType=Boolean), but contains a value other than true or false, the connector can convert the value to a Boolean. True and False qualifiers can take any value which the connector will convert to true and false respectively.

    For example: status.True=Active

  • False

    If any field is marked as Boolean (such as, Field.DataType=Boolean), but contains a value other than true or false, the connector can convert the value to a Boolean. True and False qualifiers can take any value which the connector will convert to true and false respectively.

    For example: status.False=Inactive

See Also:

Sample Schema Files for a sample ACME schema file

2.1.2.2 Configuring the Connector for Status Reconciliation

Perform this procedure to configure the connector for status reconciliation.

  1. Enter the StatusAttribute account qualifier and specify the name of the column in the flat file that contains the status of the record as its value.

    For example: StatusAttribute=status

  2. If the column in the flat file contains a value other than true of false, then map this value to the True or False field qualifiers as follows:

    1. For True:

      Enter FIELDNAME.True=STATUSVALUE

      Here, FIELDNAME is the name of the column in the flat file that contains the status of the record. STATUSVALUE is the value in the flat file which you want to map to the True field qualifier.

      For example: status.True=Enabled

    2. For False:

      Enter FIELDNAME.False=STATUSVALUE

      Here, FIELDNAME is the name of the column in the flat file that contains the status of the record. STATUSVALUE is the value in the flat file which you want to map to the False field qualifier.

      For example: status.False=Disabled

2.1.2.3 Configuring the Connector for Date Type

Perform this procedure to configure the connector for date type.

  1. Enter the DataType field qualifier and specify its value as Date.

    For example: startDate.DataType=Date

  2. Enter the SystemDateFormat account qualifier and specify the format string.

    For example: SystemDateFormat=dd-MM-yyyy

Note:

The value of the SystemDateFormat account qualifier must be specified according to the Java SimpleDateFormat pattern.

2.1.2.4 Creating a Schema File

You must create a schema file describing the structure of your flat file.

  1. Create a .properties file.
  2. Add entries in the schema file according to requirements of your environment.

    The following are the mandatory qualifiers that should be defined in the schema file:

    • FieldNames

    • UidAttribute

    • NameAttribute

  3. Provide values for each of the entries that you added. See Understanding the Schema File Format for more information about the format in which these values must be specified.
  4. Save the created .properties file.

2.1.3 Installing the Connector for a Connected Resource

Perform this instruction if you want to load entities into a resource for which a predefined connector is available.

Ensure that you have installed and configured the predefined connector properly.

2.1.4 Installing the Connector for a Disconnected resource

In scenarios where a predefined connector is not available and the Oracle Identity Manager artifacts need to be generated, perform the procedures described here to use the metadata generator utility to generate the connector installer.

This section contains the following topics:

2.1.4.1 Summary of steps to Generate the Connector Components

This is a summary of the steps to generate the connector components.

  1. Prepare the schema file that needs to be specified in the configuration parameter while configuring the FlatFileConfiguration.groovy file. See Preparing the Schema File for more information.
  2. Specify values for properties in the FlatFileConfiguration.groovy file to configure your flat file either as a trusted source or target resource. See Configuring the FlatFileConfiguration.groovy File for more information.
  3. Run the FlatFile Generator to generate the connector package. See Running the Flat File Generator for more information.
  4. Run the Connector Installer, which uses the XML file (located in the configuration directory of the connector package generated in Step 3) to install the connector that you generated per your requirements. See Installing the Connector Package for more information.

2.1.4.2 Preparing the Schema File

The schema file is used to represent the structure of the flat file that is to be parsed by the connector.

The schema file is used as an input to the metadata generation utility and is also a mandatory parameter in the IT resource. You must populate the schema file in the specified format, before using the connector. See Understanding and Creating the Schema File for more information.

2.1.4.3 Understanding Entries in the FlatFileConfiguration.groovy File

The FlatFileConfiguration.groovy file contains sample configurations (one each for trusted source, target resource, and disconnected resource) with default values for most of the entries.

Depending upon your requirements, specify or modify values for entries in this file or create custom configurations according to your requirements. The following are the predefined configurations in the FlatFileConfiguration.groovy file:

  • trusted

    You specify values for the entries in this configuration if you want to configure the flat file as a trusted source.

  • target

    You specify values for the entries in this configuration if you want to configure the flat file as a target resource.

  • disconnected

    You specify values for the entries in this configuration if you want to configure the flat file as a disconnected resource.

The following are the entries in the FlatFileConfiguration.groovy file:

Note:

  • Unless specified, all entries described here are common to both trusted source, target resource, and disconnected resource configurations.

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

  • itResourceDefName

    This is a mandatory entry. Enter the name of the IT resource type for the enterprise target system. Note that the value that you specify for this entry determines the name of the connector package, connector configuration file, and connector installer file. For example, if you specify ACME as the value of this entry, then the name of the connector package directory is ACME. See Running the Flat File Generator for the directory structure of the connector package.

    Note:

    It is recommended that the value specified for this entry must be unique for each connector that you create for your flat file, if you plan to install or use the connectors in the same Oracle Identity Manager environment.

    In addition, this value will be a part of the names for all connector components (defined in the connector configuration XML file, which is created after you run the Flat File Generator) such as lookup definitions, resource objects, process forms, and scheduled jobs.

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

  • itResourceName

    This is an optional entry. Enter the name of the IT resource for the flat file. By default, the value of this entry is the same as the value of the itResourceDefName entry.

    Sample value: FlatFile

  • trusted

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

  • disconnectedResource

    This is a mandatory entry and present only in the section for disconnected resource configuration. By default, the value of this entry is set to true. If you are generating the metadata for a disconnected resource, the do not modify the default value.

    If you set the value of this entry to true, the utility generates complete metadata for the disconnected resource. If you set the value of this entry to false, the utility generates complete metadata for the target or accounts.

  • connectorDir

    This is an optional entry. This entry is the name of the directory that contains the output of the connector. By default, the value of this entry is the same as the value of the itResourceName entry.

  • xmlFile

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

    IT_RES_DEF_NAME-ConnectorConfig.xml

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

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

  • configFile

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

    IT_RES_DEF_NAME-CI.xml

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

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

  • propertiesFile

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

    IT_RES_DEF_NAME-generator.properties

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

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

  • version

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

  • bundleJar

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

    Default value: ../../bundle/org.identityconnectors.flatfile-1.0.1115.jar

    Do not change the value of this entry.

  • config

    This is a mandatory entry in which you specify information about the connector configuration. This connector configuration contains information about the manner in which the connector must behave and connect to the flat file.

    This entry contains the schemaFile parameter, which is a mandatory configuration parameter. Enter the name and relative path of the schema file that you want to use. For more information about creating schema files, see Understanding and Creating the Schema File.

  • lookupAttributeList

    This is an optional entry and is present only in the sections for target resource and disconnected resource configuration. Enter the list of fully qualified attributes or column names in the flat file that must be handled as lookup fields.

    The connector creates a lookup field for each of the attributes specified in this entry and associates it with the corresponding lookup fields on the OIM User process form.

    If you want to create a lookup field for a single-valued or multivalued field, then enter the value in the following format:

    ['FIELD_NAME']

    In this format, replace FIELD_NAME with the name of the single or multivalued field.

    If you want create a lookup field for a multivalued field that is embedded then, enter the value in the following format:

    ['OBJ_CLASS.SUB_FIELD_NAME']

    In this format, replace:

    • OBJ_CLASS with the EmbeddedObjectClass name for the child form as specified in the schema file.

    • SUB_FIELD_NAME with the subfield name for the child form as specified in the schema file.

    The default value of this entry is:

    ['ROLES.ROLENAME','FirstName']

    In this value, ROLES.ROLENAME is a multivalued field that is embedded. In other words, ROLES is the EmbeddedObjectClass name for roles child form as specified in the schema file (that is, roles.EmbeddedObjectClass=Roles) and ROLENAME is one of the subfields for the roles child form as specified in the schema file (that is roles.Subfileds=ROLENAME). FirstName is a single-valued field.

    You can modify the default value to meet the requirements in your environment.

    For each of the attributes listed in the lookupAttributeList entry, the connector creates a lookup field and scheduled job in the following format:

    • Lookup field format:

      Lookup.${IT_RES_NAME}.${FIELD_NAME}

    • Scheduled job format:

      IT_RES_NAME FIELD_NAME Loader

      This scheduled job is used to load or reconcile lookup values from the flat file. See Scheduled Jobs for Lookup Field and Entitlement Synchronization for more information about the list of scheduled jobs for lookup fields and entitlement synchronization and their attributes.

    In both the formats, the connector replaces:

    • IT_RES_NAME with the value of the itResourceDefName entry.

    • FIELD_NAME with the name of the field for which the lookup field is created.

  • entitlementAttributeList

    This is also an optional entry and is present only in the sections for target resource and disconnected resource configuration. Enter the list of fully qualified attributes in the flat file that must be tagged as entitlements.

    The connector creates a lookup field for each of the attributes specified in this entry, assigns the lookup fields to a process form, adds all the required properties of entitlements, and then creates a scheduled job in the following format:

    IT_RES_NAME FIELD_NAME Entitlement Loader

    This scheduled job synchronizes the catalog with the entitlements automatically. See Scheduled Jobs for Lookup Field and Entitlement Synchronization for more information about this scheduled job.

    If you want to tag entitlements for multivalued fields, then enter the value in the following format:

    ["MULTIVALUED_FIELD_NAME"]

    If you want to tag entitlements for a multivalued field that is embedded, then enter the value in the following format:

    ["OBJ_CLASS.SUB_FIELD_NAME"]

    In this format, replace:

    • OBJ_CLASS with the EmbeddedObjectClass name for the child form as specified in the schema file.

    • SUB_FIELD_NAME with the subfield name for the child form as specified in the schema file.

    Default value: ["MyRoles.RoleId","__GROUPS__"]

    You can modify the default value based on your schema.

    In this value, MyRoles.RoleId is an embedded multivalued field and __GROUPS__ is a multivalued field.

  • dateAttributeList

    This is an optional entry. Enter the list of attributes that must be handled as date on the process form. Ensure that the data type of the attributes listed here is set to Long in the schema file.

    The connector creates a date editor for each of the attributes specified in this entry.

    If you want to handle single-valued or multivalued fields as date, then enter the value in the following format:

    ["FIELD_NAME"]

    In this format, replace FIELD_NAME with the name of the single or multivalued field.

    If you want to handle an embedded multivalued field as date, then enter the value in the following format:

    ["OBJ_CLASS.SUB_FIELD_NAME"]

    In this format, replace:

    • OBJ_CLASS with the EmbeddedObjectClass name for the child form as specified in the schema file.

    • SUB_FIELD_NAME with the subfield name for the child form as specified in the schema file.

    Default value: ["JoiningDate"]

    You can modify the default value to meet the requirements in your environment.

    The following is a sample value for handling embedded multivalued fields as date:

    ["MyRole.StartDate", "MyRole.EndDate"]

  • alias

    This is a mandatory entry. The FlatFile generator uses aliases to create relationships between the columns in the flat file and resource object field names in Oracle Identity Manager. In addition, the FlatFile generator uses aliases to shorten long database names to meet the character-length restrictions on form names and form field names in Oracle Identity Manager. Aliasing can be used on column name, form name, and form field name levels. Note that the flat file columns are represented as connector attributes.

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

    • For trusted source configuration

      In the trusted source configuration section, you use the alias entry to map connector attributes or column names in the flat file to the OIM User form field names. The mappings that you specify here are used to populate entries in the Recon Attribute map lookup definition for trusted source reconciliation.

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

      Display Name Internal Name

      Organization

      Organization Name

      Manager

      Manager Login

      E-mail

      Email

      The following is the default value of the alias entry:

      ['__NAME__':'User Login', 'LastName':'Last Name','Organization':'Organization Name', 'Employee Type':'Xellerate Type', 'Role':'Role']

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

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

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

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

      ['__ENABLE__':'Status', 'FirstName':'First Name', 'email':'Email', 'JoiningDate':'Start Date']

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

      ['CONN_ATTR1': 'OIM_FIELD1', 'CONN_ATTR2': 'OIM_FIELD2', . . . 'CONN_ATTRn': 'OIM_FIELDn']

      In this format:

      • CONN_ATTR is the connector attribute name.

      • OIM_FIELD is the name of the field on the OIM User form.

    • For target resource or disconnected resource configuration

      In the target source configuration and disconnected resource configuration sections, you use the alias entry for one or all of the following purposes:

      • To map connector attributes or column names in the flat file to fields of the process form. The mappings that you specify here are used to populate entries in the Recon Attribute map and Prov Attribute map lookup definitions for target resource reconciliation.

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

      • To specify a short name for a lengthy process form field name.

        When the number of characters in a process form is more than 11, the FlatFile Generator automatically truncates the process form name to 10 characters and then suffixes it with the digit 0. Subsequently, for every process form that results in the same name after truncating, the suffix is incremented by 1. The FlatFile Generator prevents any two process forms from having the same name by using autonumbering. To gain control over the autogenerated form name and to have meaningful form names, you can use an alias to specify a shortened process form name.

        This is illustrated by the following example:

        Assume that the resource name is FLAT and contains child data that is represented as USER_ROLES in the schema.

        When you run the FlatFile Generator, the process form is created and the form name is UD_FLAT_USER_ROLES. As the number of characters in this process form name is more than 11, the FlatFile Generator automatically truncates it to UD_FLAT_US0. The truncated form name, UD_FLAT_US0, is not meaningful.

        To avoid encountering such issues or forms with autogenerated names, you can use the alias entry to specify short and meaningful process form names.

      The following is the default value of the alias entry in both the target resource and disconnected resource sections:

      ['__UID__':'objectGUID', '__NAME__':'sAMAccountName']

      You cannot delete existing mappings in the default value as they are mandatory. However, you must modify the default value to match the values of the UidAttribute and NameAttribute qualifiers in the schema file. For example, in the schema file, if you have set the values of the UidAttribute and NameAttribute qualifiers to UID and UserId respectively, then you must set the value of the alias entry to the following:

      ['__UID__':'UID', '__NAME__':'UserId']

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

      The following is the default value of the alias + entry in both the target resource and disconnected resource sections:

      ['USERROLERELATIONSHIP':'USRROL', 'comments':'Description', 'Family Name':'Last Name', 'Visibility':'Status']

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

      ['CONN_ATTR1': 'ALIAS_FIELD1', 'CONN_ATTR2': 'ALIAS_FIELD2', . . . 'CONN_ATTRn': 'ALIAS_FIELDn']

      In this format:

      • CONN_ATTR is the connector attribute name.

      • ALIAS_FIELD is the alias corresponding to the connector attribute or column name in the flat file.

  • prepopulate

    This is an optional entry that is present only in the sections for target resource and disconnected resource. Specify a value for this entry if you want Oracle Identity Manager to prepopulate connector's process form fields from OIM User fields while provisioning a enterprise target system resource.

    The default value of this entry is as follows:

    ['__NAME__':'User Login', 'FIRST_NAME':'First Name', 'LAST_NAME':'Last Name', '__PASSWORD__':'Password']

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

    • User Login

    • First Name

    • Last Name

    • Password

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

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

    In this format:

    • CONN_ATTR is the connector attribute name.

    • COL_NAME is the column name in the flat file.

    • OIM_FIELD is the name of the field on the OIM User form.

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

2.1.4.4 Configuring the FlatFileConfiguration.groovy File

Use the FlatFileConfiguration.groovy file to specify the configuration properties of the Oracle Identity Manager metadata to be generated based on the target. In addition, use the FlatFileConfiguration.groovy file to generate the connector package specific to your flat file.

See Running the Flat File Generator for information about running the Flat File Generator and directory structure of the connector package.

To configure the FlatFileConfiguration.groovy file:

  1. In a text editor, open the FlatFileConfiguration.groovy file. This file is located in the FlatFile-RELEASE_NUMBER/metadata-generator/resources directory of the installation media.
  2. Specify values for entries in one of the following predefined configurations:

    • trusted - for configuring your flat file as a trusted source.

    • target - for configuring your flat file as a target resource.

    • disconnected - for configuring the flat file as a disconnected resource.

    Note:

  3. Save and close the FlatFileConfiguration.groovy file.

2.1.4.5 Running the Flat File Generator

After configuring the FlatFileConfiguration.groovy file, you must run the Flat File Generator to generate the connector package.

The FlatFile Generator is the FlatFileGenerator.cmd or FlatFileGenerator.sh file that is located in the FlatFile-RELEASE_NUMBER/metadata-generator/bin directory of the installation media.

To run the FlatFile Generator:

In a command window, change to the FlatFile-RELEASE_NUMBER/metadata-generator/bin directory and run one of the following commands depending on the operating system that you are using:

  • For Microsoft Windows:

    FlatFileGenerator.cmd CONFIG_FILE CONFIG_NAME

  • For UNIX:

    sh FlatFileGenerator.sh CONFIG_FILE CONFIG_NAME

In this command, replace:

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

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

The following is a sample command:

FlatFileGenerator.cmd ..\resources\FlatFileConfiguration.groovy target

If you encounter any errors while running the Flat File Generator, then you must fix it and then resume running the Flat File Generator.

2.1.4.6 Understanding the Generated Connector Package

The connector package is generated after running the FlatFile Generator.

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

CONNECTOR_PACKAGE/
         configuration/
                  IT_RES_DEF-CI.xml
         resources/
         xml/
                  IT_RES_DEF-ConnectorConfig.xml

In this directory structure:

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

  • resources/ is an empty directory. Resource bundles can be added to this directory for localization. For information about localizing form fields in UI, see Localizing Field Labels in UI Forms.

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

The IT_RES_DEF-CI.xml file that contains configuration information is used by the Connector Installer during installation of the connector for your enterprise target system.

The IT_RES_DEF-ConnectorConfig.xml file (also referred to as the connector configuration file) contains definitions for connector components such as IT resource, lookup definitions, scheduled jobs, process forms, and resource objects.

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

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

2.1.4.7 Installing the Connector Package

Before you can start using the connector, you must place the connector package (generated after running the Flat File Generator) in the OIM_HOME/server/ConnectorDefaultDirectory directory, unzip the generated connector package, and then run the connector installer for installing the connector package.

To run the connector installer, see Running the Connector Installer. After installing the connector, you must configure the IT resource, see Configuring the IT Resource for more information.

2.1.5 Prerequisites for the Target Resource

There are certain prerequisites for any target resource for it to work with the Flat File Connector. While most of the connected and disconnected resources already contain these prerequisites, there might be certain cases (such as GTC-based resources) where these steps can apply.

2.1.5.1 Understanding Mapping in the Recon Attribute Map Lookup Definition

The Recon Attribute Map lookup definition contains the mapping between the resource object reconciliation fields and the target system attributes.

In this connector, the target system attributes correspond to the field (or) column names in the flat file. If a Recon Attribute Map does not exist for the resource, one has to manually create this lookup definition. The Code Key column of this lookup definition must contain the resource object field names and the Decode column must contain the corresponding flat file attributes.

For multivalued fields, the Code Key column of the Recon Attribute Map lookup definition must be in the following format:

MULTIVALUED_RECON_FIELD_NAME~PROPERTY_FIELD_NAME

Sample value 1: lang~Languages

Sample value 2: roles~Rolename

Sample value 3: roles~StartDate

For complex child forms, the corresponding Decode column in the Recon Attribute Map lookup definition must be in the following format:

MULTIVALUED_RECON_FIELD_NAME~EMBEDDED_OBJECT_CLASS_NAME~SUBFIELD_NAME

In this format, replace:

  • MULTIVALUED_RECON_FIELD_NAME with the name of the multivalued reconciliation field.

  • EMBEDDED_OBJECT_CLASS_NAME with the EmbeddedObjectClass name for the child form as specified in the schema file.

  • SUBFIELD_NAME with one of the subfield names for the child form as specified in the schema file.

Sample value: roles~Roles~roleName

In this sample value:

  • 'roles' is the multivalued reconciliation field name.

  • 'Roles' is the EmbeddedObjectClass name for roles child form as specified in the schema file (that is, roles.EmbeddedObjectClass=Roles).

  • 'roleName' is one of the Subfields for roles child form as specified in the schema file (that is, roles.Subfields=roleName,startDate).

The following is a screenshot of the Lookup.ACMEApp.UM.ReconAttrMap lookup definition in which entries for multivalued fields are listed:

Description of recon_attr_map.png follows
Description of the illustration recon_attr_map.png

The following is a screenshot of the Reconciliation Fields tab for the ACME App User resource object that contains multivalued fields such as roles and langua:

Description of recon_fields.png follows
Description of the illustration recon_fields.png

2.1.5.2 Modifying the Reconciliation Field Name and Updating the Reconciliation Field Mapping

The IT Resource Reconciliation field of type 'IT Resource' for the target resource object must be called 'IT Resource Name'. If the name of this Reconciliation field is anything other than 'IT Resource Name', then it must be modified as follows:

  1. Log in to the Design Console.

  2. Expand Resource Management, and click Resource Objects.

  3. Click on the Object Reconciliation tab.

  4. Under Reconciliation Fields, search for the field of type IT Resource.

  5. If the field name of the reconciliation field is not IT Resource Name, then edit the field to rename the Field Name to IT Resource Name.

  6. Check the Required check box.

  7. Click Save.

  8. Update the reconciliation field mapping as follows:

    1. Expand Process Management, and click Process Definition.

    2. Search for and open the process definition of the target resource.

    3. Click the Reconciliation Field Mappings tab.

    4. Edit the IT Resource Field Mapping, and update the Field Name to IT Resource Name.

    5. Click Save.

Note:

You must create the Reconciliation Profile after performing the preceding procedure.

2.1.6 Configuring the Connector for Incremental Reconciliation

Perform this procedure to configure your connector for incremental reconciliation.

  1. In a text editor, open the schema file created in Understanding and Creating the Schema File.
  2. In the FieldNames qualifier, include the name of attribute that holds time stamp information. For example, LastUpdated.

    This attribute name is specified as the value of the Incremental Recon Attribute of the scheduled job. This scheduled job attribute is explained later in this guide.

  3. Set the datatype of the attribute that will be used during incremental reconciliation to Long. For example, LastUpdated.DataType=Long.
  4. In the flat file, ensure that the user or account record contains the incremental value in Long format.

2.1.7 Copying Custom Parser Libraries and Preprocess and Postprocess Handlers

If you are using preprocess or postprocess tasks, or a custom parser through the flat file connector, the Java class files that implement these customizations must be built as a jar and deployed before installing the connector.

See Configuring Preprocess and Postprocess Tasks and Configuring Custom Parsers for more information on preprocess and postprocess handlers, and custom parsers.

You must copy the custom jar files as follows:

  1. Create a directory named FlatFile-RELEASE_NUMBER under the following directory:

    OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/

    For example, if you are using release 11.1.1.6.0 of this connector, then create a directory named FlatFile-11.1.1.6.0 in the OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/.

  2. Copy the custom jar files created in Integrating the Custom Parser with the Flat File Connector and Integrating the Preprocess and Postprocess Tasks with the Flat File Connector to the OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/FlatFile-RELEASE_NUMBER.

    For example, if you have built a jar in the name xml-parser.jar, it has to be copied to OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/FlatFile-RELEASE_NUMBER directory.

2.2 Installation

Depending on where you want to run the connector code (bundle), the connector provides these installation options.

2.2.1 Installing the Connector on Oracle Identity Manager

Installing the connector involves performing these procedures.

2.2.1.1 Running the Connector Installer

To run the Connector Installer:

  1. Copy the contents of the connector installation media directory into the following directory:

    OIM_HOME/server/ConnectorDefaultDirectory

  2. If you have not already done so, create a directory in OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib with the same name as the connector package. For the flat file connector, this name is FlatFile-11.1.1.6.0. For example:

    OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/FlatFile-11.1.1.6.0

    Copy the external JAR files to this directory. See Copying Custom Parser Libraries and Preprocess and Postprocess Handlers for more information.

  3. Log in to Oracle Identity System Administration.

  4. In the left pane, under System Management, click Manage Connector.

  5. In the Manage Connector page, click Install.

  6. From the Connector List list, select FlatFile Connector RELEASE_NUMBER. This list displays the names and release numbers of connectors whose installation files you copy into the default connector installation directory in Step 1.

    If you have copied the installation files into a different directory, then:

    1. In the Alternative Directory field, enter the full path and name of that directory.

    2. To repopulate the list of connectors in the Connector List list, click Refresh.

    3. From the Connector List list, select FlatFile Connector RELEASE_NUMBER.

  7. Click Load.

  8. To start the installation process, click Continue.

    The following tasks are performed in sequence:

    1. Configuration of connector libraries

    2. Import of the connector XML files (by using the Deployment Manager)

    3. Compilation of adapters

    On successful completion of a task, a check mark is displayed for the task. If a task fails, then an X mark and a message stating the reason for failure are displayed. Depending on the reason for the failure, make the required correction and then perform one of the following steps:

    • Retry the installation by clicking Retry.

    • Cancel the installation and begin again from Step 1.

  9. If all three tasks of the connector installation process are successful, then a message indicating successful installation is displayed. In addition, a list of the steps that you must perform after the installation is displayed. These steps are as follows:

    1. Ensuring that the prerequisites for using the connector are addressed

      Note:

      At this stage, run the Oracle Identity Manager PurgeCache utility to load the server cache with content from the connector resource bundle in order to view the list of prerequisites. See Clearing Content Related to Connector Resource Bundles from the Server Cache for information about running the PurgeCache utility.

      There are no prerequisites for some predefined connectors.

    2. Configuring the IT resource for the connector

      Record the name of the IT resource displayed on this page. The procedure to configure the IT resource is described later in this guide.

    3. Configuring the scheduled jobs that are created when you installed the connector.

      Record the names of the scheduled jobs displayed on this page. The procedure to configure these scheduled jobs is described later in this guide.

When you run the Connector Installer, it copies the connector files to destination directories on the Oracle Identity Manager host computer. These files are listed in Table D-1.

2.2.1.2 Configuring the IT Resource

Depending on whether you have installed only the ready-to-use Flat File connector that is shipped with the connector installation media, or created the connector using the metadata generation utility, a set of IT resources are created.

If you have installed only the ready-to-use Flat File connector, then the following IT resources of type "Flat File" are available when the connector is installed:

  • Flat File Entitlements

    Configure this IT resource when you want to load lookups and entitlements from the flat file.

  • Flat File Users

    Configure this IT resource when you want to load users from the flat file and you have configured your enterprise target system as a trusted source.

  • Flat File Accounts

    Configure this IT resource when you want to load accounts from the flat file and you have configured your enterprise target system as a target resource.

If you have created the Flat File connector using the metadata generation utility, then depending on whether you have configured the flat file as a trusted source, target resource, or disconnected resource, the following IT resources of the type IT_RES_NAME FlatFile are available:

  • For trusted source configuration:

    IT_RES_NAME Users Configure this IT resource when you want to load users from the flat file.

  • For target resource or disconnected resource configuration:

    • IT_RES_NAME Accounts Configure this IT resource when you want to load accounts from the flat file.

    • IT_RES_NAME FieldName Configure this IT resource when you want to load lookups and entitlements from the flat file.

    ]

Figure 2-1 shows the IT resources of type Flat File when the ready-to-use Flat File connector is installed.

Figure 2-1 IT Resources of Type Flat File

Description of Figure 2-1 follows
Description of "Figure 2-1 IT Resources of Type Flat File"

Depending on the IT Resource that you want to configure, you must specify values for the parameters of the IT resources as follows:

  1. Log in to Oracle Identity System Administration.
  2. In the left pane, under Configuration, click IT Resource.
  3. In the IT Resource Name field on the Manage IT Resource page, enter the IT resource name (for example, Flat File Entitlements) and then click Search. Alternatively, from the IT Resource Type menu, select the name of the IT resource (for example, Flat File Entitlements), and then click Search.
  4. Click the Edit icon for the IT resource.
  5. From the list at the top of the page, select Details and Parameters.
  6. Specify values for the parameters of the IT resource (for example, Flat File Entitlements). Note that the parameters for all IT resources are the same. Table 2-1 describes each parameter of all the IT Resources.

    Table 2-1 Parameters of the IT Resources of Type Flat File for the Enterprise Target System

    Parameter Description

    Configuration Lookup

    Name of the lookup definition that contains the configuration information used during reconciliation.

    If you have configured your enterprise target system as a target resource, then enter Lookup.FlatFile.Configuration.

    If you have configured your enterprise target system as a trusted source, then enter Lookup.FlatFile.Configuration.Trusted.

    Default value: Lookup.FlatFile.Configuration

    Connector Server Name

    Name of the IT resource of the type "Connector Server." You create an IT resource for the Connector Server in Creating the IT Resource for the Connector Server.

    Note: Enter a value for this parameter only if you have deployed the Flat File connector in the Connector Server.

    Sample value: Flat File Connector Server

    schemaFile

    Absolute path of the schema file.

    Sample value: D:\flatfile\schema.properties

    Figure 2-2 shows the View IT Resource Details and Parameters page.

    Figure 2-2 View IT Resource Details and Parameters page for the Flat File Accounts IT Resource

    Description of Figure 2-2 follows
    Description of "Figure 2-2 View IT Resource Details and Parameters page for the Flat File Accounts IT Resource"
  7. To save the values, click Update.

2.2.2 Deploying the Connector in a Connector Server

You can deploy the Flat File connector either locally in Oracle Identity Manager or remotely in the Connector Server.

A connector server is an application that enables remote execution of an Identity Connector, such as the Flat File connector.

Note:

This procedure can be divided into the following stages:

2.2.2.1 Installing and Configuring the Connector Server

Connector servers are available in two implementations:

  • As a .Net implementation that is used by Identity Connectors implemented in .Net

  • As a Java Connector Server implementation that is used by Java-based Identity Connectors

The Flat File connector is implemented in Java, so you can deploy this connector to a Java Connector Server.

Use the following steps to install and configure the Java Connector Server:

Note:

Before you deploy the Java Connector Server, ensure that you install the JDK or JRE on the same computer where you are installing the Java Connector Server and that your JAVA_HOME or JRE_HOME environment variable points to this installation.

  1. Create a new directory on the computer where you want to install the Java Connector Server.

    Note:

    In this guide, CONNECTOR_SERVER_HOME represents this directory.

  2. Unzip the Java Connector Server package in the new directory created in Step 1. You can download the Java Connector Server package from the Oracle Technology Network.
  3. Open the ConnectorServer.properties file located in the conf directory. In the ConnectorServer.properties file, set the following properties, as required by your deployment.
    Property Description

    connectorserver.port

    Port on which the Java Connector Server listens for requests. Default is 8759.

    connectorserver.bundleDir

    Directory where the connector bundles are deployed. Default is bundles.

    connectorserver.libDir

    Directory in which to place dependent libraries.

    Default is lib.

    connectorserver.usessl

    If set to true, the Java Connector Server uses SSL for secure communication. Default is false.

    If you specify true, use the following options on the command line when you start the Java Connector Server:

    • -Djavax.net.ssl.keyStore

    • -Djavax.net.ssl.keyStoreType (optional)

    • -Djavax.net.ssl.keyStorePassword

    connectorserver.ifaddress

    Bind address. To set this property, uncomment it in the file (if necessary). The bind address can be useful if there are more NICs installed on the computer.

    connectorserver.key

    Java Connector Server key.
  4. Set the properties in the ConnectorServer.properties file, as follows:

    • To set the connectorserver.key, run the Java Connector Server with the /setKey option.

      Note:

      For more information, see Running the Connector Server.

    • For all other properties, edit the ConnectorServer.properties file manually.

  5. The conf directory also contains the logging.properties file, which you can edit if required by your deployment.

Note:

Oracle Identity Manager has no built-in support for connector servers, so you cannot test your configuration.

2.2.2.2 Running the Connector Server

To run the Java Connector Server, use the ConnectorServer.bat script for Windows and use the ConnectorServer.sh script for UNIX as follows:

  1. Make sure that you have set the properties required by your deployment in the ConnectorServer.properties file, as described in Installing and Configuring the Connector Server.
  2. Change to the CONNECTOR_SERVER_HOME\bin directory and find the ConnectorServer.bat script.

    The ConnectorServer.bat supports the following options:

    Option Description

    /install [serviceName]

    ["-J java-option"]

    Installs the Java Connector Server as a Windows service.

    Optionally, you can specify a service name and Java options. If you do not specify a service name, the default name is ConnectorServerJava.

    /run ["-J java-option"]

    Runs the Java Connector Server from the console.

    Optionally, you can specify Java options. For example, to run the Java Connector Server with SSL:

    ConnectorServer.bat /run "-J-Djavax.net.ssl.keyStore=mykeystore.jks" "-J-Djavax.net.ssl.keyStorePassword=password"

    /setKey [key]

    Sets the Java Connector Server key. The ConnectorServer.bat script stores the hashed value of the key in the connectorserver.key property in the ConnectorServer.properties file.

    /uninstall [serviceName]

    Uninstalls the Java Connector Server. If you do not specify a service name, the script uninstalls the ConnectorServerJava service.
  3. If you need to stop the Java Connector Server, stop the respective Windows service.

2.2.2.3 Installing the Connector on the Connector Server

See Also:

Using an Identity Connector Server in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for information about installing and configuring connector server and running the connector server

If you need to deploy the Flat File connector into the Java Connector Server, then follow these steps:

  1. Stop the Java Connector Server.

    Note:

    Ensure that you are using latest framework JARs of Oracle Identity Manager to keep the Connector Server consistent with your Oracle Identity Manager instance. To do so:

    Copy the framework JAR files, connector-framework.jar and connector-framework-internal.jar, from the OIM_HOME/server/ext/internal directory to the CONNECTOR_SERVER_HOME/lib/framework directory.

  2. Copy the connector bundle JAR file (org.identityconnectors.flatfile-1.0.1115.jar) from the installation media into the Java Connector Server CONNECTOR_SERVER_HOME/bundles directory.
  3. If you are using custom jars for parsers, preprocess and post process handlers, then copy the necessary jars to CONNECTOR_SERVER_HOME/lib directory.
  4. Start the Java Connector Server.

2.3 Postinstallation

Configuring the Oracle Identity Manager server involves performing procedures such as configuring Oracle Identity Manager, setting up Configuration lookup definitions, enabling logging and so on.

2.3.1 Configuring Oracle Identity Manager

You must create additional metadata such as a UI form and an application instance for the resource into which you want to load data by using the flat file connector.

These procedures are described in the following topics:

2.3.1.1 Creating and Activating a Sandbox

Create and activate a sandbox as follows. For detailed instructions, see Managing Sandboxes in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

  1. Log in to Oracle Identity System Administration.
  2. In the upper right corner of the page, click the Sandboxes link.

    The Manage Sandboxes page is displayed.

  3. On the toolbar, click Create Sandbox.
  4. In the Create Sandbox dialog box, enter values for the following fields:

    • Sandbox Name: Enter a name for the sandbox.

    • Sandbox Description: Enter a description of the sandbox.

  5. Click Save and Close.
  6. Click OK on the confirmation message that is displayed.

    The sandbox is created and displayed in the Available Sandboxes section of the Manage Sandboxes page.

  7. From the table showing the available sandboxes in the Manage Sandboxes page, select the newly created sandbox that you want to activate.
  8. On the toolbar, click Activate Sandbox.

    The sandbox is activated.

2.3.1.2 Creating a New UI Form

Create a new UI form as follows. For detailed instructions, see Managing Forms in Oracle Fusion Middleware Administering Oracle Identity Manager.

  1. In the left pane, under Configuration, click Form Designer. The Form Designer page is displayed.
  2. From the Actions menu, select Create. Alternatively, click Create on the toolbar. The Create Form page is displayed.
  3. On the Create Form page, enter values for the following UI fields:

    • Resource Type: Select the resource object that you want to associate the form with. For example, ACME User.

    • Form Name: Enter a name for the form.

  4. Click Create.

    A message is displayed stating that the form is created.

2.3.1.3 Creating an Application Instance

Create an application instance as follows. For detailed instructions, see Managing Application Instances in Oracle Fusion Middleware Administering Oracle Identity Manager.

  1. In the left pane of the System Administration console, under Configuration, click Application Instances. The Application Instances page is displayed.

  2. From the Actions menu, select Create. Alternatively, click Create on the toolbar. The Create Application Instance page is displayed.

  3. Specify values for the following fields:

    • Name: The name of the application instance.

    • Display Name: The display name of the application instance.

    • Description: A description of the application instance.

    • Resource Object: The resource object name. Click the search icon next to this field to search for and select ACME User.

    • IT Resource Instance: The IT resource instance name. Click the search icon next to this field to search for and select ACME Application.

    • Form: Select the form name (created in Creating a New UI Form).

  4. Click Save. The application instance is created.

  5. Publish the application instance to an organization.

    1. On the Organizations tab of the Application Instance page, click Assign.

    2. In the Select Organizations dialog box, select the organization to which you want to publish the application instance.

    3. Select the Apply to entitlements checkbox.

    4. Click OK.

    See Also:

    Managing Organizations Associated With Application Instances in Oracle Fusion Middleware Administering Oracle Identity Manager for detailed instructions

2.3.1.4 Publishing a Sandbox

You must publish the sandbox that you created in Creating and Activating a Sandbox.

  1. Close all the open tabs and pages.
  2. In the upper right corner of the page, click the Sandboxes link.

    The Manage Sandboxes page is displayed.

  3. From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you created in Creating and Activating a Sandbox.
  4. On the toolbar, click Publish Sandbox. A message is displayed asking for confirmation.
  5. Click Yes to confirm. The sandbox is published and the customizations it contained are merged with the main line.

2.3.2 Changing to the Required Input Locale

Changing to the required input locale (language and country setting) involves installing the required fonts and setting the required input locale.

You may require the assistance of the system administrator to change to the required input locale.

2.3.3 Clearing Content Related to Connector Resource Bundles from the Server Cache

When you deploy the connector, the resource bundles are copied from the resources directory on the installation media into the Oracle Identity Manager database. Whenever you add a new resource bundle to the connectorResources directory or make a change in an existing resource bundle, you must clear content related to connector resource bundles from the server cache.

To clear content related to connector resource bundles from the server cache:
  1. In a command window, switch to the OIM_HOME/server/bin directory.

    Note:

    You must perform Step 1 before you perform Step 2. An exception is thrown if you run the command described in Step 2 as follows:

    OIM_HOME/server/bin/SCRIPT_FILE_NAME
  2. Enter the following commands:

    Note:

    You can use the PurgeCache utility to purge the cache for any content category. Run PurgeCache.bat CATEGORY_NAME on Microsoft Windows or PurgeCache.sh CATEGORY_NAME on UNIX. The CATEGORY_NAME argument represents the name of the content category that must be purged.

    For example, the following commands purge Metadata entries from the server cache:

    PurgeCache.bat MetaData

    PurgeCache.sh MetaData

    • On Microsoft Windows: PurgeCache.bat All

    • On UNIX: PurgeCache.sh All

    When prompted, enter the user name and password of an account belonging to the SYSTEM ADMINISTRATORS group. In addition, you are prompted to enter the service URL in the following format:

    t3://OIM_HOST_NAME:OIM_PORT_NUMBER

    In this format:

    • Replace OIM_HOST_NAME with the host name or IP address of the Oracle Identity Manager host computer.

    • Replace OIM_PORT_NUMBER with the port on which Oracle Identity Manager is listening.

2.3.4 Setting up the Configuration Lookup Definition

Depending on the requirements in your environment, you can add one or more of the these additional configuration entries to the Lookup.FlatFile.Configuration and Lookup.FlatFile.Configuration.Trusted lookup definitions.

Table 2-2 Additional Configuration Entries for the Lookup.FlatFile.Configuration and Lookup.FlatFile.Configuration.Trusted Lookup Definitions

Code Key Decode

customConfigParams

Enter the custom configuration parameters required by the custom parser.

Sample Value: Type=DOM;Version=1.0

For more information about this entry, see Configuring Custom Parsers.

parserClassName

Enter the custom parser implementation class name. If this entry is not present, then by default, the CSV parser implementation is triggered.

Sample value: com.extension.parser.XMLParser

For more information about this entry, see Configuring Custom Parsers.

preProcessClassName

Enter the preprocess handler implementation class name.

Sample value: com.extension.parser.PreProcessHandler

For more information about this entry, see Configuring Preprocess and Postprocess Tasks.

postProcessClassName

Enter the postprocess handler implementation class name.

Sample value: com.extension.parser.PostProcessHandler

For more information about this entry, see Configuring Preprocess and Postprocess Tasks.

commentCharacter

Enter the character which denotes comment line.

Sample value: #

For more information about this entry, see Configuring the Connector to Ignore Comment Characters.

progressCheckPoint

Enter the number of successfully processed records after which you require the connector to log the information to denote the progress.

Sample Value: 100

encoding

Enter the basic encoding of the file. The default value is the default character set of JVM.

Sample value: UTF-8

Process Recon Event Batch Size

Batch size threshold limit for spawning new thread for processing and adding recon event.

Default value: 500

Process Recon Event Thread Pool Size

Maximum number of threads that can be created.

Default value: 5

2.3.5 Managing Logging

Oracle Identity Manager uses Oracle Java Diagnostic Logging (OJDL) for logging. OJDL is based on java.util.logger.

The following topics provide detailed information about logging:

2.3.5.1 Understanding Log Levels

When you enable logging, Oracle Identity Manager automatically stores in a log file information about events that occur during the course of provisioning and reconciliation operations.

To specify the type of event for which you want logging to take place, you can set the log level to one of the following:

  • SEVERE.intValue()+100

    This level enables logging of information about fatal errors.

  • SEVERE

    This level enables logging of information about errors that might allow Oracle Identity Manager to continue running.

  • WARNING

    This level enables logging of information about potentially harmful situations.

  • INFO

    This level enables logging of messages that highlight the progress of the application.

  • CONFIG

    This level enables logging of information about fine-grained events that are useful for debugging.

  • FINE, FINER, FINEST

    These levels enable logging of information about fine-grained events, where FINEST logs information about all events.

These log levels are mapped to ODL message type and level combinations as shown in Table 2-3.

Table 2-3 Log Levels and ODL Message Type:Level Combinations

Log Level ODL Message Type:Level

SEVERE.intValue()+100

INCIDENT_ERROR:1

SEVERE

ERROR:1

WARNING

WARNING:1

INFO

NOTIFICATION:1

CONFIG

NOTIFICATION:16

FINE

TRACE:1

FINER

TRACE:16

FINEST

TRACE:32

The configuration file for OJDL is logging.xml, which is located at the following path:

DOMAIN_HOME/config/fmwconfig/servers/OIM_SERVER/logging.xml

Here, DOMAIN_HOME and OIM_SERVER are the domain name and server name specified during the installation of Oracle Identity Manager.

2.3.5.2 Enabling Logging

To enable logging in Oracle WebLogic Server:

  1. Edit the logging.xml file as follows:

    1. Add the following blocks in the file:

      <log_handler name='flatfile-handler' level='[LOG_LEVEL]' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='logreader:' value='off'/>
     <property name='path' value='[FILE_NAME]'/>
     <property name='format' value='ODL-Text'/>
     <property name='useThreadName' value='true'/>
     <property name='locale' value='en'/>
     <property name='maxFileSize' value='5242880'/>
     <property name='maxLogSize' value='52428800'/>
     <property name='encoding' value='UTF-8'/>
   </log_handler>

      <logger name="org.identityconnectors.flatfile" level="[LOG_LEVEL]" useParentHandlers="false">
     <handler name="flatfile-handler"/>
     <handler name="console-handler"/>
   </logger>

    2. Replace both occurrences of [LOG_LEVEL] with the ODL message type and level combination that you require. Table 2-3 lists the supported message type and level combinations.

      Similarly, replace [FILE_NAME] with the full path and name of the log file in which you want log messages to be recorded.

      The following blocks show sample values for [LOG_LEVEL] and [FILE_NAME] :

      <log_handler name='flatfile-handler' level='NOTIFICATION:1' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='logreader:' value='off'/>
     <property name='path' value='F:\MyMachine\middleware\user_projects\domains\base_domain1\servers\oim_server1\logs\oim_server1-diagnostic-1.log'/>
     <property name='format' value='ODL-Text'/>
     <property name='useThreadName' value='true'/>
     <property name='locale' value='en'/>
     <property name='maxFileSize' value='5242880'/>
     <property name='maxLogSize' value='52428800'/>
     <property name='encoding' value='UTF-8'/>
   </log_handler>
 
<logger name="org.identityconnectors.flatfile" level="NOTIFICATION:1" useParentHandlers="false">
     <handler name="flatfile-handler"/>
     <handler name="console-handler"/>
   </logger>

    With these sample values, when you use Oracle Identity Manager, all messages generated for this connector that are of a log level equal to or higher than the NOTIFICATION:1 level are recorded in the specified file.

  2. Save and close the file.

  3. Set the following environment variable to redirect the server logs to a file:

    For Microsoft Windows:

    set WLS_REDIRECT_LOG=FILENAME

    For UNIX:

    export WLS_REDIRECT_LOG=FILENAME

    Replace FILENAME with the location and name of the file to which you want to redirect the output.

  4. Restart the application server.

2.3.6 Localizing Field Labels in UI Forms

Perform this procedure to localize field labels that are added to UI forms.

  1. Log in to Oracle Enterprise Manager.

  2. In the left pane, expand Application Deployments and then select oracle.iam.console.identity.sysadmin.ear.

  3. In the right pane, from the Application Deployment list, select MDS Configuration.

  4. On the MDS Configuration page, click Export and save the archive to the local computer.

  5. Extract the contents of the archive, and open one of the following files in a text editor:

    • For Oracle Identity Manager 11g Release 2 PS2 (11.1.2.2.0):

      SAVED_LOCATION\xliffBundles\oracle\iam\ui\runtime\BizEditorBundle_en.xlf

    • For releases prior to Oracle Identity Manager 11g Release 2 PS2 (11.1.2.2.0):

      SAVED_LOCATION\xliffBundles\oracle\iam\ui\runtime\BizEditorBundle.xlf

  6. Edit the .xlf file in the following manner:

    1. Search for the following text:

      <file source-language="en"  
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

    2. Replace with the following text:

      <file source-language="en" target-language="LANG_CODE"
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

      In this text, replace LANG_CODE with the code of the language that you want to localize the form field labels. The following is a sample value for localizing the form field labels in Japanese:

      <file source-language="en" target-language="ja"
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

    3. Search for the application instance code. This procedure shows a sample edit for ACME application instance. The original code is:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_ACME_LANGUAGE__c_description']}">
<source>Language</source>
</target>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.ACME.entity.ACMEEO.UD_ACME_LANGUAGE__c_LABEL">
<source>Language</source>
</target>
</trans-unit>

    4. Update the <target> element of trans-unit shown in Step 6.b with the localized string of the field name as follows:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_ACME_LANGUAGE__c_description']}">
<source>Language</source>
<target>\u8A00\u8A9E</target>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.ACME.entity.ACMEEO.UD_ACME_LANGUAGE__c_LABEL">
<source>Language</source>
<target>\u8A00\u8A9E</target>
</trans-unit>

    5. Repeat Steps 6.a through 6.d for all attributes of the process form.

    6. Save the file as BizEditorBundle_LANG_CODE.xlf. In this file name, replace LANG_CODE with the code of the language to which you are localizing.

      Sample file name: BizEditorBundle_ja.xlf.

  7. Repackage the ZIP file and import it into MDS.

    See Also:

    Deploying and Undeploying Customizations in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager, for more information about exporting and importing metadata files

  8. Log out of and log in to Oracle Identity Manager.

2.3.7 Configuring the Connector to Ignore Comment Characters

You can configure the connector to ignore the processing of lines that begin with certain characters like #, $, and so on.

These configurable characters are considered as comment characters, and sentences beginning with such characters are considered as comments. The connector implementation will skip the lines that start with the configured comment character.

To do so:

  1. Log in to the Design Console.
  2. Expand Administration, and then double-click Lookup Definition.
  3. Depending on whether you have configured your flat file as a target resource or a trusted source, search for and open one of the following lookup definitions:

    • For target resource: Lookup.FlatFile.Configuration

    • For trusted source: Lookup.FlatFile.Configuration.Trusted

  4. Click Add.
  5. In the newly added row, enter the following values:

    • Code Key: commentCharacter

    • Decode: Character that denotes a comment line.

      Sample value: #

  6. Click Save.

2.3.8 Creating the IT Resource for the Connector Server

You must create an IT resource for the Connector Server if you have deployed the connector bundle remotely in a Connector Server.

To create the IT resource for the Connector Server:

  1. Log in to Oracle Identity System Administration.

  2. In the left pane, under Configuration, click IT Resource.

  3. In the Manage IT Resource page, click Create IT Resource.

  4. On the Step 1: Provide IT Resource Information page, perform the following steps:

    • IT Resource Name: Enter a name for the IT resource.

    • IT Resource Type: Select Connector Server from the IT Resource Type list.

    • Remote Manager: Do not enter a value in this field.

  5. Click Continue. Figure 2-3 shows the IT resource values added on the Create IT Resource page.

    Figure 2-3 Step 1: Provide IT Resource Information

    Description of Figure 2-3 follows
    Description of "Figure 2-3 Step 1: Provide IT Resource Information"

  6. On the Step 2: Specify IT Resource Parameter Values page, specify values for the parameters of the IT resource and then click Continue. Figure 2-4 shows the Step 2: Specify IT Resource Parameter Values page.

    Figure 2-4 Step 2: Specify IT Resource Parameter Values

    Description of Figure 2-4 follows
    Description of "Figure 2-4 Step 2: Specify IT Resource Parameter Values"

    Figure 2-7 provides information about the parameters of the IT resource.

    Table 2-4 Parameters of the IT Resource for the Connector Server

    Parameter Description

    Host

    Enter the host name or IP address of the computer hosting the connector server.

    Sample value: RManager

    Key

    Enter the key for the Java connector server.

    Port

    Enter the number of the port at which the connector server is listening.

    Default value: 8759

    Timeout

    Enter an integer value which specifies the number of milliseconds after which the connection between the connector server and Oracle Identity Manager times out.

    Sample value: 300

    UseSSL

    Enter true to specify that you will configure SSL between Oracle Identity Manager and the Connector Server. Otherwise, enter false.

    Default value: false

    Note: It is recommended that you configure SSL to secure communication with the connector server. To configure SSL, run the connector server by using the /setKey [key] option. The value of this key must be specified as the value of the Key IT resource parameter of the connector server.

  7. On the Step 3: Set Access Permission to IT Resource page, the SYSTEM ADMINISTRATORS group is displayed by default in the list of groups that have Read, Write, and Delete permissions on the IT resource that you are creating.

    Note:

    This step is optional.

    If you want to assign groups to the IT resource and set access permissions for the groups, then:

    1. Click Assign Group.

    2. For the groups that you want to assign to the IT resource, select Assign and the access permissions that you want to set. For example, if you want to assign the ALL USERS group and set the Read and Write permissions to this group, then you must select the respective check boxes in the row, as well as the Assign check box, for this group.

    3. Click Assign.

  8. On the Step 3: Set Access Permission to IT Resource page, if you want to modify the access permissions of groups assigned to the IT resource, then:

    Note:

    • This step is optional.

    • You cannot modify the access permissions of the SYSTEM ADMINISTRATORS group. You can modify the access permissions of only other groups that you assign to the IT resource.

    1. Click Update Permissions.

    2. Depending on whether you want to set or remove specific access permissions for groups displayed on this page, select or deselect the corresponding check boxes.

    3. Click Update.

  9. On the Step 3: Set Access Permission to IT Resource page, if you want to unassign a group from the IT resource, then:

    Note:

    • This step is optional.

    • You cannot unassign the SYSTEM ADMINISTRATORS group. You can unassign only other groups that you assign to the IT resource.

    1. Select the Unassign check box for the group that you want to unassign.

    2. Click Unassign.

  10. Click Continue. Figure 2-5 shows the Step 3: Set Access Permission to IT Resource page.

    Figure 2-5 Step 3: Set Access Permission to IT Resource

    Description of Figure 2-5 follows
    Description of "Figure 2-5 Step 3: Set Access Permission to IT Resource"

  11. On the Step 4: Verify IT Resource Details page, review the information that you provided on the first, second, and third pages. If you want to make changes in the data entered on any page, click Back to revisit the page and then make the required changes.

  12. To proceed with the creation of the IT resource, click Continue. Figure 2-6 shows Step 4: Verify IT Resource Details page.

    Figure 2-6 Step 4: Verify IT Resource Details

    Description of Figure 2-6 follows
    Description of "Figure 2-6 Step 4: Verify IT Resource Details"

  13. The Step 5: IT Resource Connection Result page displays the results of a connectivity test that is run using the IT resource information. If the test is successful, then click Continue. If the test fails, then you can perform one of the following steps:

  14. Click Finish. Figure 2-8 shows the IT Resource Created page.

    Figure 2-8 Step 6: IT Resource Created

    Description of Figure 2-8 follows
    Description of "Figure 2-8 Step 6: IT Resource Created"

2.4 Configuring the Connector with the Target Resource

This section explains how the Flat File connector can be used with a target resource. A target resource can be either a connected resource or a disconnected resource. The Flat File connector will reuse the target connector's Resource Object and Recon Attribute Map for the reconciliation field mappings. This requires the existing connector's application instance name to be given in the scheduled job and pointing the Recon Attribute Map of the flat file connector to the Recon Attribute Map of the target resource.

The following are the prerequisites with respect to configuring the connector for a target resource:

  • Ensure that the connector for the target resource that you are using is installed.

  • Ensure that the Flat File connector is installed. See Running the Connector Installer for more information on installing the connector.

  • Create a form and an application instance for the target resource that you are using.

  • Ensure that the IT Resource for the Flat File connector has been configured. See Configuring the IT Resource for more information on configuring the IT Resource.

To configure the connector for a target resource:

  1. Update the Lookup.FlatFile.EntFieldMap lookup definition as follows:

    1. Log in to the Design Console.

    2. Expand Administration and then double-click Lookup Definition.

    3. Search for and open the Lookup.FlatFile.EntFieldMap lookup definition.

    4. The Code Key column of the target lookup definition is represented by the CODE entry in this lookup definition, which is mapped to NameAttribute (__NAME__) mentioned in the schema file. Edit this entry to point to any other field in the flat file.

    5. The Decode Key column of the target lookup definition is represented by the DECODE entry in this lookup definition, which is mapped to NameAttribute (__NAME__) mentioned in the schema file. Edit this entry to point to any other field in the flat file.

    6. Click Save.

  2. If you have configured your target resource as trusted source, then:

    1. Expand Administration and then double-click Lookup Definition.

    2. Search for and open the Lookup.FlatFile.UM.Configuration.Trusted lookup definition.

    3. Set the decode value of the Recon Attribute Map code key to the name of the lookup definition of the target resource that holds mappings between resource object fields and enterprise target system attributes.

      For example, if you are using Microsoft Active Directory as a target resource, then you must set the value of the decode value of the Recon Attribute Map code key to Lookup.ActiveDirectory.UM.ReconAttrMap.Trusted

    4. Add a new entry to this lookup definition as follows:

      Code Key: Recon Attribute Defaults

      Decode: Name of the lookup definition of the target resource that maps reconciliation fields to their default values. Sample Value: Lookup.ActiveDirectory.UM.ReconAttrMap.Trusted.Defaults

    5. Click Save.

  3. If you have configured your target resource as a target resource, then:

    1. Expand Administration and then double-click Lookup Definition.

    2. Search for and open the Lookup.FlatFile.UM.Configuration lookup definition.

    3. Set the decode value of the Recon Attribute Map code key to the name of the lookup definition of the target resource that holds mappings between resource object fields and enterprise target system attributes.

      For example, if you are using Microsoft Active Directory as a target resource, then you must set the value of the decode value of the Recon Attribute Map code key to Lookup.ActiveDirectory.UM.ReconAttrMap.

    4. Click Save.

2.5 Upgrading the Connector

Upgrading to this release of the connector from earlier releases is not supported.