7 Integrating ICF with Oracle Identity Governance

The goal of Oracle Identity Governance is to manage the business logic of Identity administration, and delegate the execution of provisioning and reconciliation operations to Identity Connector Framework (ICF). ICF with Oracle Identity Governance unites all the scheduled tasks and the provisioning tasks for all ICF-based connectors.

This chapter contains conceptual information about integration between Oracle Identity Governance and ICF. It contains the following topics:

• ICF Common

• Integration Architecture

• Global Oracle Identity Governance Lookups

• About IT Resources for ICF Integration

• Provisioning Using ICF

• Concepts of Reconciliation in ICF Common

• Predefined Scheduled Tasks

• ICF Filter Syntax

7.1 ICF Common

OIM ICF Integration Layer is an implementation of ICF API on one side and invokes OIM APIs (icf-oim-intg.jar) on the other side.

This reduces the complexity of the connector developer as it provides API abstraction. It also support provisioning and reconciliation operations. See Provisioning Using ICF and Concepts of Reconciliation in ICF Common for more information about provisioning and reconciliation using ICF Common.

7.2 Integration Architecture

OIM-ICF connector development architecture lets you develop connector bundle using ICF SPI and integrate them with OIM.

Figure 7-1 is the ICF-OIM integration architecture.

Figure 7-1 OIM-ICF Connector Development Architecture

Description of "Figure 7-1 OIM-ICF Connector Development Architecture"

7.3 Global Oracle Identity Governance Lookups

Lookups are used to store Oracle Identity Manager configuration metadata.

This section describes the global Oracle Identity Manager lookup configuration. It contains the following topics:

• About Global Lookups

• Main Lookup Configuration

• User Management Configuration

• Recon Transformation Lookup (Lookup.CONNECTOR_NAME.UM.ReconTransformation)

• Recon Validation Lookup (Lookup.CONNECTOR_NAME.UM.ReconValidation)

• Optional Defaults Lookup

7.3.1 About Global Lookups

Lookups is used to store Oracle Identity Manager configuration metadata. IT Resource parameter Configuration Lookup points to main Configuration Lookup that encapsulates all the Oracle Identity Manager specific configuration information.

Based on the lookup configuration, you can classify your properties into the following three classes:

• IT Resource: connectivity properties: contains all properties that are used for making a connection to the target system.

• Main Configuration Lookup Configuration Properties: contains non-connectivity properties that alter the mode of reconciliation or provisioning, and are not required for connection. There is a thin line of difference between connectivity and configuration properties, therefore one property can be assigned to both of them.

• Object Type: specific lookups (for example, user management configuration), mapping lookups for specific object type (for example, User, Group, Organizational Unit).

  Note:

  LOADFROMURL flag can be used in IT Resource or Main Configuration Lookup in the code (key) field, for example, sampleProperty[LOADFROMURL]. For properties marked as this, the value (decode value) is a URL. ICF integration will read the contents of the file stored in the given URL and use it as the value of given property at runtime. This is useful for large values that cannot fit directly into a lookup.

Figure 7-2 illustrates the global Oracle Identity Manager lookups from which most of the Connectors use the User Management Lookups.

Figure 7-2 Oracle Identity Manager Connector Lookup Hierarchy

Description of "Figure 7-2 Oracle Identity Manager Connector Lookup Hierarchy"

7.3.2 Main Lookup Configuration

IT Resource parameter Configuration Lookup points to Main Configuration Lookup, which encapsulates all the Oracle Identity Manager specific configuration information.

Configuration lookup, denoted as Lookup.CONNECTOR_NAME.Configuration, is the top level entry that refers to subordinate lookups for reconciliation and provisioning. The configuration lookup has the structure shown in Table 7-1:

Table 7-1 Lookup Configuration for Connector

Configuration Key	Value	Description
Connector Name	org.identityconnectors.CONNECTOR_NAME.Connector	Identity Connector Main Class. This is the class that implements SPI operations of ICF framework.
Bundle Name	org.identityconnectors.CONNECTOR_NAME	Identity Connector bundle name
Bundle Version	11.1.1.5.x	Identity Connector bundle version
User Configuration Lookup Note: Other object types may be defined, for example, for Generic LDAP connector: Group Configuration Lookup, OU Configuration Lookup.	Lookup.CONNECTOR_NAME.UM.Configuration	Link to User specific configuration lookup. Note: User should be the object type. If you need to support any other object type, you can use OBJECT_TYPE Configuration Lookup as the key.

7.3.3 User Management Configuration

User Management Configuration lookups control the mapping for provisioning and reconciliation. In addition, these lookups might also configure transformation and validation.

This lookup contains the following keys:

• Before Create Action Language: This key if present in the Lookup.CONNECTOR_NAME.UM.Configuration, which informs ICF that there is a script whose language is the value of this key. The value of this key (Groovy/cmd ) informs the language of the script that needs to be executed by ICF before create operation.

• Before Create Action File: This key if present in the Lookup.CONNECTOR_NAME.UM.Configuration, informs ICF that a script represented by the value of this key needs to be executed by ICF before create action. This script must be accessible to Oracle Identity Manager Server.

• Before Create Action Target: This key if present in the Lookup.CONNECTOR_NAME.UM.Configuration, informs ICF that script as defined by previous two keys must be executed either on resource or on connector. Depending on this configuration the ICF API runScriptOnConnector or runScriptOnResource will be executed.

Table 7-2 describes the User Management lookup configuration.

Table 7-2 User Management Lookup Configuration for Connector

Configuration Key	Value	Mandatory Field Type	Description
Provisioning Attribute Map	Lookup.CONNECTOR_NAME.UM.ProvAttrMap	Y	This lookup contains the mapping between Oracle Identity Manager fields and identity connector attributes. The mapping is used during provisioning.
Recon Attribute Map	Lookup.CONNECTOR_NAME.UM.ReconAttrMap	Y	This lookup contains the mapping between Oracle Identity Manager reconciliation fields and identity connector attributes. The mapping is used during reconciliation.
Recon Attribute Defaults	Lookup.CONNECTOR_NAME.UM.ReconDefaults	N	This mapping contains the default values for Oracle Identity Manager attributes, that are substituted, if no value is provided by connector during reconciliation.
Recon Transformation Lookup	Lookup.CONNECTOR_NAME.UM.ReconTransformation	N	Lookup for Transformation by doing Reconciliation Task. Transformation is used in all Reconciliation Tasks except LookupReconTask.
Recon Validation Lookup	Lookup.CONNECTOR_NAME.UM.ReconValidation	N	Lookup used for Validation by running Reconciliation Task. Validation is used in all Reconciliation Tasks except LookupReconTask.
Recon Exclusion List	Lookup.CONNECTOR_NAME.UM.ReconExclusionList	N	Exclusion list is a way to address un-managed accounts for the connector. While reconciliation/provisioning. Any match from the exclusion list will not be processed by Oracle Identity Manager. There are two types of rules supported by the exclusion list: Matching rules Direct Matching Rule Code Key: Reconciliation field name Decode Key: Excluded field value Pattern Matching Rule Suffix with [PATTERN] tag to enable pattern matching Code Key: ReconFieldName[PATTERN] Decode Key: Exclusion pattern Exclusion patterns should follow the nomenclature defined in java.util.regex.Pattern See the Recon Exclusion List key in this table.
Provisioning Exclusion List	Lookup.CONNECTOR_NAME.UM.ProvExclusionList	N	In provisioning, code key is the Form label name, and decode key is the excluded value/pattern.
Provisioning Validation Lookup	Lookup.CONNECTOR_NAME.UM.ProvValidation	N	Lookup for Validation by Provisioning. ICF defines the concept of OperationOption, it is an extra parameter list, that can be sent to any operation. It is up to the connector implementation to define the use of these operation options.
Operation Options Map	Lookup.CONNECTOR_NAME.UM.OperationOptions	N	The code key is a constant Operation Options Map. The decode value name of lookup that will be used as a map of operation options. For example, in Lookup.Domino.UM.OperationOptions the code key is CACertifier[UPDATE,DELETE] and the decode value is CACertifier, which means that this attribute will be sent to calls of Update and Delete operations as an extra operation option. If you want to configure the action run, then you need to provide three parameters for scripting: Language File Target
Scripting Attributes			The triggering time of the script is controlled by these labels in your lookup key: Before After The provisioning operation type that the script is attached on is controlled by these labels: Create Update Delete
Before Create Action Language	SCRIPTING_LANGUAGE_NAME	N	Language of the Action which will be executed, for example, Groovy/cmd. If you want to configure the action run, then you need to provide three options, Language/File/Target You can configure Before/After actions for the following provisioning operations: Create/Update/Delete.
Before Create Action File	FILE_PATH	N	File containing script which needs to be executed. This file needs to be accessible to Oracle Identity Manager Server.
Before Create Action Target	Connector or Resource	N	Target of the action, can be Connector or Resource. Depending on this configuration the ICF API runScriptOnConnector or runScriptOnResource will be used.

7.3.4 Recon Transformation Lookup (Lookup.CONNECTOR_NAME.UM.ReconTransformation)

Transformation code is in an external Oracle Identity Manager Java Task, used in all Reconciliation Tasks except LookupReconTask. It is a Java class uploaded (transforming data coming from Target System during reconciliation) to Oracle Identity Manager repository.

The Java class performing transformation needs to have a method with the signature public Object transform(HashMap arg0, HashMap arg1, String arg2) implemented. ICF would look for this method with the exact signature.

Transform java class template is as follows:

public class MyTransformer implements oracle.iam.connectors.common.transform.Transformation {
  public Object transform(java.util.HashMap hmUserDetails, java.util.HashMap hmEntitlementDetails, String sField) {
    String sFirstName= (String)hmUserDetails.get("First Name");
    String sLastName= (String)hmUserDetails.get("Last Name");
    String sFullName=sFirstName+"."+sLastName;
    return sFullName;
  }
}

The name of lookup storing the Recon Transformation Lookup is defined in Main Configuration Lookup (Lookup.CONNECTOR_NAME.Configuration) as shown in Table 7-3.

Table 7-3 Reconciliation Transformation Lookup

Key	Value	Description
Recon Field Name	<transformationClassName> com.validationexample.MyTransform	Java class which performs transformation for this recon field.

7.3.5 Recon Validation Lookup (Lookup.CONNECTOR_NAME.UM.ReconValidation)

Validation code is in an external Oracle Identity Manager Java task, used for validating data coming from the target system during reconciliation. It is a Java class uploaded (transforming data coming from the target system during reconciliation) to Oracle Identity Manager repository.

The Java class performing validation needs to have a method with the signature public boolean validate (HashMap arg0, HashMap arg1, String arg2) implemented. ICF would look for this method with the exact signature.

The validation Java class template is as follows:

public class MyValidator implements oracle.iam.connectors.common.validate.Validator { 
  public boolean validate(java.util.HashMap hmUserDetails, java.util.HashMap hmEntitlementDetails,String sField) throws oracle.iam.connectors.common.ConnectorException {
    boolean isValid = false;
    // validation code goes HERE
    return isValid;
  }
}

The name of lookup storing the Recon Validation Lookup is defined in main configuration lookup (Lookup.CONNECTOR_NAME.Configuration) as shown in Table 7-4.

Table 7-4 Reconciliation Validation Lookup

Key	Value	Description
Recon Field Name	<transformationClassName> com.validationexample.MyValidator	Java class which performs validation for this recon field.

7.3.6 Optional Defaults Lookup

Missing values for reconciliation are substituted by default values defined in the following table. User Type is a required Oracle Identity Manager attribute, that typically is not contained on the target resource. You can set the default value in here.

For example, trusted reconciliation requires a set of attributes from the connector to have a non-empty value. However, not all resources can supply all of these attribute types, so you need to provide some default values. Table 7-5 lists all required attributes for reconciliation, and possible default values for them.

If connector can supply all attributes needed in reconciliation, then this table becomes optional.

Table 7-5 Lookup.CONNECTOR_NAME.UM.Recon.Defaults.Trusted Attriburtes

Key	Value
Last Name	CONNECTOR_DEPENDENT_VALUE
Organization	Xellerate users
User Type	End-User
Employee Type	Full-Time
First Name	CONNECTOR_DEPENDENT_VALUE

Note:

These default values are supported only for single valued fields, which means the multivalued or child table attributes are not supported.

7.4 About IT Resources for ICF Integration

IT Resource contains connectivity parameters for target system. These parameters are required for all the connectors using ICF integration.

Table 7-6 describes the common IT Resource parameters.

See Also:

The documentation for the connector you are deploying for information about the IT Resource parameters of the target system and the Connector Server

Table 7-6 IT Resource Parameter

Parameter	Description
Connector Server Name	IT Resource name of Connector Server. The IT Resource needs to be of type Connector Server. This field is a mandatory field, but the value is optional.
Configuration Lookup	Name of the main configuration lookup. This field is a mandatory field

7.5 Provisioning Using ICF

Provisioning using ICF is done by using the ICF Provisioning Manager.

The section describes provisioning by using ICF. It contains the following topics:

• ICF Provisioning Manager

• Provisioning Lookup

• Non-User Object Types

• Optional Lookups for Provisioning

• Provisioning Validation Lookup

• Optional Flags in Lookups for Provisioning Attribute Map

• Compound attributes in Provisioning Attribute Map

7.5.1 ICF Provisioning Manager

ICF Provisioning Manager unites the access to provisioning methods of connectors into one Java Task that serves all connectors.

The public methods are divided into four groups:

• APIs for Provisioning

• Account Related Operations

• Multivalued Operations

• Other operations

7.5.1.1 APIs for Provisioning

The following are the single-valued CRUD object types.

• createObject:

  Creates object of a specified type on the target resource, the values are taken from the current Form.

  Signature: public String createObject(String objectType)l

• deleteObject:

  Deletes object of a specified type on the target resource.

  Signature: public String deleteObject(String objectType)

• updateAttributeValue:

  Updates object on target resource, only the attribute with the provided label is updated.

  Signature: public String updateAttributeValue(String objectType, String attrFieldName)

• updatePassword:

  Use this method in Adapter ONLY if you need to provide old password value, currently there is no way to get the old value using the formAPI. If you don't need old password value to change the password, use #updateAttributeValue(String, String) method instead.

  Signature: public String updatePassword(String objectType, String pswdFieldLabel, String oldPassword)

7.5.1.2 Account Related Operations

The following are the account related provisioning operations:

• enableUser:

  Deprecated, use enableObject() instead.

  Signature: public String enableUser()

• disableUser:

  Deprecated, use disableObject() instead.

  Signature: public String disableUser()

• enableObject:

  Example usage for User: enableObject("User").

  Signature: public String enableObject(String objectType)

• disableObject:

  Signature: public String disableObject(String objectType)

7.5.1.3 Multivalued Operations

The following are the multivalued operations used in provisioning:

• updateAttributeValues:

  Use this method if there is a group update of fields. This will be useful when a set of attributes have to updated together.

  Signature: public String updateAttributeValues(String objectType, String[] labels) public String updateAttributeValues(String objectType, Map<String, String> fields) public String updateAttributeValues(String objectType, Map<String, String> fields, Map<String, String> oldFields)}}}

• addChildTableValue:

  Updates the target by adding the newly added row in child table.

  Signature: public String addChildTableValue(String objectType, String childTableName, long childPrimaryKey)

• removeChildTableValue:

  Updates the target by removing the row which was just deleted from child table.

  Signature: public String removeChildTableValue(String objectType, String childTableName, Integer taskInstanceKey)

• updateChildTableValue:

  Updates the target by removing the deleted row and adding the newly created row.

  Signature: public String updateChildTableValue(String objectType, String childTableName, Integer taskInstanceKey, long childPrimaryKey)

• updateChildTableValue:

  Updates values provided in child table on target resource.

  Signature: public String updateChildTableValues(String objectType, String childTableName)

7.5.1.4 Other operations

setEffectiveITResourceName is the other operation used in provisioning.

If the connector needs to use different IT Resource for provisioning operations, it can be set by this method.

Signature: public void setEffectiveITResourceName(String itResourceName)

7.5.2 Provisioning Lookup

Lookup.CONNECTOR_NAME.UM.ProvAttrMap contains basic attribute mapping for single-valued and multivalued attributes.

These are:

• Single valued attributes: simple string key + value pairs.

• Multivalued attributes (Child tables in Oracle Identity Manager): These are further divided by the depth of hierarchy:

  • Simple multivalued attributes: represent records of data stored in child table, see second row in Table 7-7.

  • Complex multivalued attributes: multiple levels of embedded objects, see last row in Table 7-7.

    Table 7-7 Provisioning Lookup Attributes

    Key	Value	Description
    Form Field Label	ConnectorAttributeName	This is a basic mapping type, simple Form Label Name to single value Connector Attribute Name
    Child Form Name>~<Child Form Field Label	ConnectorAttributeName	This maps child form field to multivalued ConnectorAttributeName
    Child Form Name>~<Child Form Field Label	ConnectorAttributeName>~<EmbeddedObjectClass>~<EmbeddedAttributeName	This maps child form field to EmbeddedAttribute of the embedded object, which object class is EmbeddedObjectClass and it is included in ConnectorAttributeName

7.5.3 Non-User Object Types

There are number of additional entities that can be provisioned, for example LDAP Organizational Unit (also called OU), or LDAP Group or Group.

In this case, you need to fill in the OBJECT_TYPE in the following examples:

• Main Configuration Lookup Lookup.CONNECTOR_NAME.Configuration

  Key	Value	Description
  objectType Configuration Lookup	Lookup.<ConnectorName>.<objectType>.ProvAttrMap
  Group Configuration Lookup	Lookup.LDAP.Group.ProvAttrMap	Example for LDAP Group

• Provisioning Lookup Lookup.CONNECTOR_NAME.OBJECT_TYPE.ProvAttrMap

  Key	Value	Description
  FORM_FIELD_LABEL_ON_THE_PROCESS_FORM	Target system attribute name	Attribute mapping between Oracle Identity Manager and the connector.

7.5.4 Optional Lookups for Provisioning

The optional lookups for provisioning are with keys FORM_FIELD_NAME and myField.

The following table lists the optional lookups for provisioning.

Key	Value	Description
FORM_FIELD_NAME [Create, Update, Delete]	ConnectorOperationOptionName	This field is used for generic definition. For example, where the field is mapped to operation option for CreateOp that is sent to connector named as myOperationOption.
myField[Create]	myOperationOption

7.5.5 Provisioning Validation Lookup

Validation code is in an external OIM Java Task. It is a Java class uploaded to Oracle Identity Manager repository.

The following is a validation java class template:

public class MyValidator implements oracle.iam.connectors.common.validate.Validator { 
  public boolean validate(java.util.HashMap hmUserDetails, java.util.HashMap hmEntitlementDetails,String sField) throws oracle.iam.connectors.common.ConnectorException {
    boolean isValid = false;
    // validation code goes HERE
    return isValid;
  }
}

The name of lookup storing the Recon Validation Lookup is defined in Main Configuration Lookup (Lookup.CONNECTOR_NAME.Configuration).

Key	Value	Description
Form Field Label	validatorClassName com.validationexample.MyValidator	Java class which performs validation for this recon field.

7.5.6 Optional Flags in Lookups for Provisioning Attribute Map

ICF-OIM Integration offers some advanced flags that modify the way provisioning is done.

The following is the example for formats of flags in the lookup key:

<key value>[<flag>]
<key value>[<flag1, flag2, flag3>]

Let us assume you have a Group OIM attribute that is mapped to UnixGroup Connector attribute. This OIM attribute is populated by a UI lookup. The correct row in Provisioning lookup will be:

nullLookup key: Group[LOOKUP] 
Lookup value: UnixGroup }}}

The following is the list of flags and their effects.

• Provisioning Lookup Flag: TRUSTED

  For some attributes (for example trusted reconciliation of __ENABLE__ attribute), you need to pass on different values for trusted and target mode of operation. For most of the connectors which support status Reconciliation use code key: Status[Trusted], and decode value: __ENABLE__.

• Provisioning Lookup Flag: IGNORE

  An attribute marked as IGNORE, will be ignored during provisioning.

• Provisioning Lookup Flag: WRITEBACK

  If a field has WRITEBACK property, then update of that form field is:

  1. update the value on the target system

  2. query the value back from the target system (in order to get a normalized value)

  3. update this normalized value on the user form.

• Provisioning Lookup Flag: DATE

  Use this flag to mark date fields. Oracle Identity Manager will apply the localized date format to these fields.

• Provisioning Lookup Flag: PROVIDEONPSWDCHANGE

  Use this flag to mark additional attributes that are needed for password change operation. By default only __PASSWORD__ attribute is sent, if no flag is applied.

7.5.7 Compound attributes in Provisioning Attribute Map

ICF Common enables to use Groovy expressions on the right hand side, so that provisioned attribute can be computed based on multiple fields.

For example, in Active Directory Connector, decode value for the name field is: .

__NAME__=CN=${Common_Name},${Organization_Name}

7.6 Concepts of Reconciliation in ICF Common

ICF Common leverages the definition and types of reconciliation defined by Oracle Identity Manager server.

IT Resource Name / Resource Object Name and Object Type are mandatory attributes reconciliation using ICF Common. Any target system attribute can be used as Latest Token Attribute.

This section contains the following topics:

• Types of Reconciliation

• List of Reconciliation Artifacts in Oracle Identity Governance

7.6.1 Types of Reconciliation

Reconciliation involves pulling identities from resource (also referred as target) to destination (Oracle Identity Manager).

This section describes the ICF common reconciliation parameters and the types of reconciliation. It contains the following topics:

• About Reconciliation Types

• ICF Common Reconciliation Parameters

• Target and Trusted Reconciliation

• Full, Incremental Reconciliation

• Advanced Incremental Reconciliation

• Delete Reconciliation

• Group Lookup Reconciliation

7.6.1.1 About Reconciliation Types

Reconciliation can be classified based on the following criteria:

• Destination type: trusted source reconciliation, target resouce reconciliation

• Scope: full reconciliation, incremental reconciliation

7.6.1.2 ICF Common Reconciliation Parameters

Table 7-8 illustrates the common reconciliation parameters.

Table 7-8 ICF Common Reconciliation Parameters

Parameter	Field Setting	Description
Filter	Optional	Filter to limit the number of reconciled accounts, or to select specific set of users.
IT Resource Name	Mandatory	Name of IT Resource instance to reconciliation.
Object Type	Constant	User object class
Resource Object Name	Constant	Determines what OIM Resource Object to use for reconciliation.

7.6.1.3 Target and Trusted Reconciliation

Scheduled task name include keywords such as trusted, target, to determine the type of destination. By choosing the scheduled task, it is determined whether trusted or target reconciliation is launched.

7.6.1.4 Full, Incremental Reconciliation

Full reconciliation involves reconciling all existing user records from the target system into Oracle Identity Manager. During Full Reconciliation, scheduled task is launched for the first time, it is run in full reconciliation mode and from next runs happen in incremental mode. It is possible to switch manually between full/incremental reconciliation modes by emptying the Latest Token field on the scheduled task.

If no value is supplied in Incremental Recon Date Attribute and Incremental Recon Attribute, reconciliation is considered as Target Recon.

The following scheduled tasks offer optional incremental reconciliation:

• Connector Target User Reconciliation

• Connector Trusted User Reconciliation

7.6.1.5 Advanced Incremental Reconciliation

The format of Latest Token is altered by setting the Recon Date Format scheduled task parameter. The formatting string needs to follow standard pattern used in Java. For more information about formatting string used in Java, see Java Doc on Oracle Technology Network.

By default the Latest Token is long value that holds Unix/POSIX time.

7.6.1.6 Delete Reconciliation

Some connectors supports both trusted and target reconciliation of deleted accounts. Target reconciliation evaluate which Oracle Identity Manager users have lost their account on the resource, and unassign this resource in Oracle Identity Manager. Trusted Delete Reconciliation goes further, and deletes the Oracle Identity Manager User.

7.6.1.7 Group Lookup Reconciliation

Some connectors may support reconciliation of Groups, or other object classes to Lookups.

Before the first use of provisioning with the connector, it is advised to launch Lookup reconciliation. This reconciliation populate the Lookup.CONNECTOR_NAME.ObjectType table with groups available on an IT Resource that is being reconciled. The reconciliation is performed by the Connector Lookup Reconciliation scheduled task.

You need to set the IT resource parameter name, the rest of the parameters are constant as shown in Table 7-8.

Table 7-9 illustrates the common reconciliation parameters.

Table 7-9 Common Group Lookup Parameters

Code Key	Decode Key	Object Type
Form field name	Connector attribute	Group, or other

For example, the list of names returned by the connector is used to populate the lookup for provisioning. When a new user is provisioned, the group field can display the list of available groups.

7.6.2 List of Reconciliation Artifacts in Oracle Identity Governance

The methods of control over reconciliation are lookups for reconciliation and scheduled tasks.

This section contains the following topics:

• Methods of Control Over Reconciliation

• Lookups for Reconciliation

• Example of Reconciliation With Child Table

7.6.2.1 Methods of Control Over Reconciliation

In Oracle Identity Manager, there are two methods of control over reconciliation:

• Lookups for Reconciliation: they define mapping, transformation of the attributes.

• Scheduled tasks - they define the way reconciliation is executed on connector side, or determine account/lookup mode of reconciliation.

7.6.2.2 Lookups for Reconciliation

Reconciliation Attribute Map Lookup is the lookup for reconciliation. The reconciliation attribute map contains the following pairs:

• Code key: Resource Object reconciliation field name

• Decode: Target system attribute name

Table 7-10 illustrates this mapping (Lookup.CONNECTOR_NAME.UM.ReconAttrMap ) used by Scheduled tasks that perform reconciliation.

Note:

Resource Objects are different for Trusted and Target mode of reconciliation.

Table 7-10 Attribute Mapping for Lookup.CONNECTOR_NAME.UM.ReconAttrMap

Key	Value	Description
Recon Field Name	ConnectorAttributeName	This is a basic mapping type, single value Connector Attribute Name to simple Recon Field.
Recon Field Name~Child Recon Field Name	ConnectorAttributeName	This maps multivalued ConnectorAttributeName to child recon field.
Recon Field Name~Child Recon Field Name	ConnectorAttributeName~EmbeddedObjectClass~EmbeddedAttribute	This maps embedded attribute to child recon field

7.6.2.3 Example of Reconciliation With Child Table

This section provides an example of Design Console updates to setup reconciliation with child table. It contains the following topics:

• Example Showing Design Console Updates to Setup Reconciliation with Child Table

• Setting Up Reconciliation With Child Tables

7.6.2.3.1 Example Showing Design Console Updates to Setup Reconciliation with Child Table

The following is the example showing Design Console updates to setup reconciliation with child table:

• Child table name: UD_FF_CHILD

• Column name: UD_FF_CHILD_ROLE

• Field label: Role

7.6.2.3.2 Setting Up Reconciliation With Child Tables

To set up reconciliation with the child table:

1. Open Resource Object under Resource Management.
2. Create a new Reconciliation Data field under Object Reconciliation tab.

   Note:

   While creating a new Reconciliation Data field, you must ensure that the field name be Roles and Field Type be Multi-Valued Attribute. This represents the child table as a whole UD_FF_CHILD.

3. Right click on the newly created Reconciliation Data Field and define a new property field as Role. This represents the actual column of the child table UD_FF_CHILD_ROLE.
4. Open Reconciliation Field Mapping under Process Definition.
5. Click on Add Table Map.
6. Select Field Name as Roles.
7. Select Table Name as UD_FF_CHILD.
8. Right click on the newly created field name Roles, click on Define proper field name.
9. Select Role for field name.
10. Select Process data field as UD_FF_CHILD_ROLE.
11. Update Lookup.CONNECTOR_NAME.UM.ReconAttrMap to include new lookup field with code key = Roles~Role and decode = Role (this should be connector side attribute name).
12. Go back to Resource Object and create reconciliation profile.
13. Clear cache.

7.7 Predefined Scheduled Tasks

The scheduled tasks for OIM-ICF integration are LookupReconTask, SearchReconTask, SearchReconDeleteTask, and SyncReconTask.

ICF-OIM integration provides the following list of predefined scheduled tasks that a connector supports:

• LookupReconTask

• SearchReconTask

• SearchReconDeleteTask

• SyncReconTask

7.7.1 LookupReconTask

LookupReconTask is based on ICF SearchOp-based reconciliation.

Oracle Identity Manager form field of type lookup stores a set of predefined values. These values originate from the connector's search query. The Code Key Attribute is the form field's name, and the Decode Attribute is the name of attribute on the target system (also called Connector).

Internally, this task invokes a search operation on the connector for the given Object Type that is translated to ICF Object Class eventually.

Table 7-11 Identity Connector Lookup Reconciliation Attributes

Key	Value
IT Resource Name	Specifies the name of the IT resource for target system installation.
Object Type	User
Lookup Name	This attribute holds the name of the lookup definition that maps each lookup definition with the data source from which values must be fetched.
Decode Attribute	Specifies the Decode Key column of the lookup definition.
Code Key Attribute	Specifies the Code Key column of the lookup definition.
Filter	Allows to create sophisticated filtration expressions in order to speed up/refine scheduled task execution.

7.7.2 SearchReconTask

SearchReconTask is used for ICF SearchOp-based reconciliation.

Table 7-12 Identity Connector Target Search Reconciliation Attributes

Key	Value
IT Resource Name	Specifies the name of the IT resource for target system installation.
Resource Object Name	Specifies the name of the Resource Object used for reconciliation.
Object Type	User
Filter	Allows to create sophisticated filtration expressions in order to speed up/refine scheduled task execution.
Latest Token	Used in Filter as one of the criteria in incremental reconciliation. Any target system attribute can be used as Latest Token Attribute. This value is calculated as follows: If a reconciliation has fetched 100 records and Timestamp is chosen as a Incremental Recon Attribute, then Latest Token = Max Timestamp of all 100 records. It is not the Schedule task execution end timestamp.
Incremental Recon Date Attribute (optional, type Date)	Attribute used to update Latest Token. Note: If no value is supplied in Incremental Recon Date Attribute, then reconciliation is considered as Target Reconciliation.
Incremental Recon Attribute (optional, type long)	Attribute used to update Latest Token. Note: If no value is supplied in Incremental Recon Attribute , then reconciliation is considered as Target Reconciliation.

7.7.3 SearchReconDeleteTask

SearchReconDeleteTask is used for ICF SearchOp-based reconciliation.

Table 7-13 Identity Connector Target Search Delete Reconciliation Attributes

Key	Value
IT Resource Name	Specifies the name of the IT resource for target system installation.
Resource Object Name	Specifies the name of the Resource Object used for reconciliation
Object Type	User
Filter	Allows to create sophisticated filtration expressions in order to speed up/refine scheduled task execution.

7.7.4 SyncReconTask

SyncReconTask is used for ICF SyncOP-based reconciliation. The Sync Token field persists the token of last synchronization.

Table 7-14 Identity Connector Target Sync Reconciliation Attributes

Key	Value
IT Resource Name	Specifies the name of the IT resource for target system installation.
Resource Object Name	Specifies the name of the Resource Object used for reconciliation
Object Type	User
Filter	Allows to create sophisticated filtration expressions in order to speed up/refine scheduled task execution.
Sync Token	Token of last synchronization.

7.8 ICF Filter Syntax

GroovyFilterBuilder allows to create sophisticated filtration expressions in order to speed up/refine scheduled task execution.

WARNING:

The GroovyFilterBuilder uses the connector attribute name for filtration. See Connector documentation for the attribute name.

This section contains the following topics:

• Filter Examples

• Definition in EBNF Format

• Keywords and Syntax for the Filter Attribute

7.8.1 Filter Examples

Filter examples can include limiting or filtering the number of reconciled accounts.

The following example could limit the number of reconciled accounts to only those, where account name starts with letter "a", this filter is denoted by the following expression:

startsWith('__NAME__', 'a')

Some more advanced search could require to filter only those account names, which end with "z" letter, therefore the filter is:

startsWith('__NAME__', 'a') & endsWith('__NAME__', 'z')

Figure 7-3 shows the graphical scheme of Filter Syntax.

Figure 7-3 Graphical Representation of Filter Syntax

Description of "Figure 7-3 Graphical Representation of Filter Syntax"

It is also possible to use a shortcut for and/or operators.

For example, <filter1> & <filter2> instead of and (<filter1>, <filter2>) , analogically replace or with |.

7.8.2 Definition in EBNF Format

The following is the Extended Backus–Naur Form (EBNF) description of the expression language used for Search Filters in reconciliation.

syntax = expression ( operator expression )* 
operator = 'and' | 'or' 
expression = ( 'not' )? filter 
filter = ('equalTo' | 'contains' | 'containsAllValues' | 'startsWith' | 'endsWith'  | 'greaterThan' | 'greaterThanOrEqualTo' | 'lessThan' | 'lessThanOrEqualTo' )  '(' 'attributeName' ',' attributeValue ')' 
attributeValue = singleValue  |  multipleValues
singleValue = 'value'
multipleValues = '[' 'value_1' (',' 'value_n')* ']' 

7.8.3 Keywords and Syntax for the Filter Attribute

Filter syntax can be for String filters, Equality or Inequality filters, and Complex filters.

Table 7-15 lists the filter syntax that you can use and the corresponding description and sample values.

Note:

Filters with wildcard characters are not supported.

Table 7-15 Keywords and Syntax for the Filter Attribute

Filter Syntax	Description
String Filters
startsWith('ATTRIBUTE_NAME','PREFIX')	Records whose attribute value starts with the specified prefix are reconciled. Example: startsWith('userPrincipalName','John') In this example, all records whose userPrincipalName begins with 'John' are reconciled.
endsWith('ATTRIBUTE_NAME','SUFFIX')	Records whose attribute value ends with the specified suffix are reconciled. Example: endsWith('sn','Doe') In this example, all records whose last name ends with 'Doe' are reconciled.
contains('ATTRIBUTE_NAME','STRING')	Records where the specified string is contained in the attribute's value are reconciled. Example: contains('displayName','Smith') In this example, all records whose display name contains 'Smith' are reconciled.
containsAllValues('ATTRIBUTE_NAME',['STRING1','STRING2', . . . ,'STRINGn'])	Records that contain all the specified strings for a given attribute are reconciled. Example: containsAllValues('objectClass',['person','top']) In this example, all records whose objectClass contains both "top" and "person" are reconciled.
Equality and Inequality Filters
equalTo('ATTRIBUTE_NAME','VALUE')	Records whose attribute value is equal to the value specified in the syntax are reconciled. Example: equalTo('sAMAccountName','Sales Organization') In this example, all records whose sAMAccountName is Sales Organization are reconciled.
greaterThan('ATTRIBUTE_NAME','VALUE')	Records whose attribute value (string or numeric) is greater than (in lexicographical or numerical order) the value specified in the syntax are reconciled. Example 1: greaterThan('cn','bob') In this example, all records whose common name is present after the common name 'bob' in the lexicographical order (or alphabetical order) are reconciled. Example 2: greaterThan('employeeNumber','1000') In this example, all records whose employee number is greater than 1000 are reconciled.
greaterThanOrEqualTo('ATTRIBUTE_NAME','VALUE')	Records whose attribute value (string or number) is lexographically or numerically greater than or equal to the value specified in the syntax are reconciled. Example 1: greaterThanOrEqualTo('sAMAccountName','S') In this example, all records whose sAMAccountName is equal to 'S' or greater than 'S' in lexicographical order are reconciled. Example 2: greaterThanOrEqualTo('employeeNumber','1000') In this example, all records whose employee number is greater than or equal to 1000 are reconciled.
lessThan('ATTRIBUTE_NAME','VALUE')	Records whose attribute value (string or numeric) is less than (in lexicographical or numerical order) the value specified in the syntax are reconciled. Example 1: lessThan('sn','Smith') In this example, all records whose last name is present after the last name 'Smith' in the lexicographical order (or alphabetical order) are reconciled. Example 2: lessThan('employeeNumber','1000') In this example, all records whose employee number is less than 1000 are reconciled.
lessThanOrEqualTo('ATTRIBUTE_NAME','VALUE')	Records whose attribute value (string or numeric) is lexographically or numerically less than or equal to the value specified in the syntax are reconciled. Example 1: lessThanOrEqualTo('sAMAccountName','A') In this example, all records whose sAMAccountName is equal to 'A' or less than 'A' in lexicographical order are reconciled. Example 2: lessThanOrEqualTo('employeeNumber','1000') In this example, all records whose employee numer is less than or equal to 1000 are reconciled.
Complex Filters
<FILTER1> & <FILTER2>	Records that satisfy conditions in both filter1 and filter2 are reconciled. In this syntax, the logical operator & (ampersand symbol) is used to combine both filters. Example: startsWith('cn', 'John') & endsWith('sn', 'Doe') In this example, all records whose common name starts with John and last name ends with Doe are reconciled.
<FILTER1> | <FILTER2>	Records that satisfy either the condition in filter1 or filter2 are reconciled. In this syntax, the logical operator | (vertical bar) is used to combine both filters. Example: contains('sAMAccountName', 'Andy') | contains('sn', 'Brown') In this example, all records that contain 'Andy' in the sAMAccount Name attribute or records that contain 'Brown' in the last name are reconciled.
not(<FILTER>)	Records that do not satisfy the given filter condition are reconciled. Example: not(contains('cn', 'Mark')) In this example, all records that does not contain the common name 'Mark' are reconciled.