Extending the Functionality of the Connector

You can extend the functionality of the connector to address your specific business requirements.

This chapter contains the following sections:

Adding New Attributes for Reconciliation and Provisioning

You can add new attributes such as Customer Id to the existing set of attributes. For this, you need to add new parameters to wrapper procedure and then update the reconciliation query to include the new attribute.

By default, the attributes listed in Table 3-3 are mapped for reconciliation and provisioning between Oracle Identity Manager and the target system. If required, you can map additional single-valued attributes for reconciliation and provisioning.

The following sections describe the procedures to be performed for adding new single-valued attributes:

Summary of Steps to Add New Attributes for Reconciliation and Provisioning

The following is a summary of high-level steps to be performed to add a new attribute for reconciliation and provisioning:

  1. Update the DB wrapper package to include the new single-valued attribute in the get_schema() stored procedure as described in Extending the Connector Schema.
  2. Update the connector artifacts to include the new attribute as described in Updating Connector Artifacts.
  3. Update the connector bundle to include the new attribute in the search.properties file as described in Updating the search.properties File.
  4. Update the connector bundle to include the new attribute in the Procedures.properties file as described in Updating the Procedures.properties File.

Extending the Connector Schema

You must extend the connector schema to include new attributes for reconciliation and provisioning. This section discusses the following topics:

Understanding Connector Schema Extension

You can extend the connector schema by adding new attributes to the get_schema() stored procedure in the OIM_FND_USER_TCA_PKG.pck wrapper package. Extending the connector schema requires you to understand the following concepts:

  • Attribute initialization

    The following initialization statement reserves an internal array that holds attribute definitions of the connector schema:

    attr.extend(NUM);

    Here, NUM defines the size of the array that is to be initialized. The size of the array must always be greater than or equal to the number of attributes defined. For example, the initialization statement attr.extend(20); reserves an internal array of 20 attributes for initialization.

  • Attribute definition

    After initialization, you define the information for each attribute by adding a statement in the following format:

    attr (ORD_NO) := attributeinfo(ATTR_NAME,ATTR_TYPE,CREATE_FLAG,UPDATE_FLAG,REQUIRED_FLAG,READ_FLAG);

    In this format:

    • ORD_NO is the order of the attribute in the array. This is mandatory.

    • ATTR_NAME is the name of single-valued attribute.

    • ATTR_TYPE is the SQL datatype of the single-valued attribute.

    • CREATE_FLAG is a flag to represent whether the attribute is required during a create provisioning operation.

    • UPDATE_FLAG is a flag to represent whether the attribute can be updated.

    • REQUIRED_FLAG is a flag to represent whether the attribute is mandatory.

    • READ_FLAG is flag to represent whether the attribute can be read.

    A value of 1 or 0 for each flag denotes True or False, respectively. For example, a value 1, 0, 1, 0 for the flags means that the attribute is a mandatory attribute and must be considered during create provisioning operations.

  • Attribute array extension

    You can increase the array size post initialization by including the following statement:

    attr.extend;

    Each inclusion of this statement increments the array size by 1.

Adding New Attributes to the Connector Schema

You must extend the connector schema by updating the DB wrapper package to include the new attribute for reconciliation and provisioning as follows:

  1. Open any SQL client (for example, SQL Developer) and connect to the target system database using the apps user.

  2. Open the body of the OIM_FND_USER_TCA_PKG.pck wrapper package.

  3. Select the get_schema() stored procedure. The list of attributes defined in the stored procedure is displayed.

  4. If the number of attributes defined exceeds the number of attributes initialized, then:

    1. Add the following attribute initialization statement:

      attr.extend;

    2. Enter the definition for the new attribute that you want to add in the following format:

      attr (ORD_NO) := attributeinfo(ATTR_NAME,ATTR_TYPE,CREATE_FLAG,UPDATE_FLAG,REQUIRED_FLAG,READ_FLAG);

      For example, if you are adding a new attribute to hold the customer Id for a user account, then include the following statements:

      attr.extend;
attr (28) := attributeinfo('CUSTOMER_ID','varchar2',1,1,0,1);

      In this example, a value of 1,1,0,1 for the flags means that the CUSTOMER_ID attribute is required during create provisioning operations, it can be updated and read.

  5. If the number of attributes defined does not exceed the number of attributes initialized then add only the definition for the new attribute. For example, attr (28) := attributeinfo('CUSTOMER_ID','varchar2',1,1,0,1);

  6. Re-compile the wrapper package.

Updating Connector Artifacts

You must update the connector artifacts to include the new single-valued attribute added in Extending the Connector SchemaUpdating connector artifacts involves performing the following procedures:

Creating a Process Form Field

You must add the new single-valued attribute as a field on the process form as follows:

  1. Expand Development Tools, and then double-click Form Designer.
  2. Search for and open the UD_EBS_UM process form.
  3. Click Create New Version to create a version of the form.
  4. In the Label field, enter the version name. For example, version#1.
  5. Click the Save icon.
  6. Select the current version created in Step 4 from the Current Version list.
  7. Click Add to create a new field for the single-valued attribute, and provide the values for that attribute.

    For example, if you are adding the Customer Id attribute, then enter the following values in the Additional Columns tab:

    Field Value

    Name

    UD_EBS_UM_CUSTOMER_ID

    Variant Type

    String

    Length

    100

    Field Label

    Customer Id

    Field Type

    TextField

    Order

    25
  8. Click the Save icon.
  9. Click Make Version Active.

Updating the Oracle EBS User Management Resource Object

Update the resource object to add a reconciliation field corresponding to the new single-valued attribute created in Creating a Process Form Field as follows:

  1. Expand the Resource Management folder, and then double-click Resource Objects.
  2. Search for and open the Oracle EBS User Management resource object.
  3. On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.
  4. In the Field Name field, enter the name of the attribute. For example, Customer Id.
  5. From the Field Type list, select a data type for the field. For example, String.
  6. If you want to designate the attribute as a mandatory attribute, then select the check box.
  7. Click the Save icon and close the dialog box.

Updating the Oracle EBS UM User Process Definition

Create a reconciliation field mapping for the single-valued attribute in the process definition as follows:

  1. Expand Process Management and then double-click Process Definition.
  2. Search for and open the Oracle EBS UM User process definition.
  3. On the Reconciliation Field Mapping tab, click Add Field Map.
  4. From the Field name list in the Add Reconciliation Field Mapping dialog box, select the name that you have assigned to the attribute created in the resource object. For example, select Customer Id.
  5. Double-click the Process Data field, and from the pop-up that appears, select the newly added field created in Creating a Process Form Field.

    The following screenshot shows the Add Reconciliation Field Mapping dialog box in which the Field Name list and Process Data Field are set:

    Description of add_recon_field_map.jpg follows
    Description of the illustration add_recon_field_map.jpg
  6. Click the Save icon and close the dialog box.

Updating the Lookup Definition for Reconciliation Attribute Mapping

Add an entry for the attribute in the lookup definition for reconciliation attribute mapping as follows:

  1. Expand the Administration folder, and then double-click Lookup Definition.
  2. Search for and open the Lookup.Oracle EBS UM.UM.ReconAttrMap lookup definition.
  3. To add a row, click Add.
  4. In the Code Key column, enter the name that you have set for the attribute in the resource object. For example, enter Customer Id.
  5. In the Decode column, enter the name of the column name that is returned by the SQL query. For example, enter CUSTOMER_ID.

    The following screenshot shows the Lookup.Oracle EBS UM.UM.ReconAttrMap lookup definition with the newly added entry:

    Description of recon_attr_map.jpg follows
    Description of the illustration recon_attr_map.jpg
  6. Click the Save icon.

Updating the Lookup Definition for Provisioning Attribute Mapping

Add an entry for the attribute in the lookup definition for provisioning attribute mapping as follows:

  1. Expand the Administration folder, and then double-click Lookup Definition.
  2. Search for and open the Lookup.Oracle EBS UM.UM.ProvAttrMap lookup definition.
  3. To add a row, click Add.
  4. In the Code Key column, enter the name that you have set for the attribute in the resource object. For example, enter Customer Id.
  5. In the Decode column, enter the name of the column name that is returned by the SQL query. For example, enter CUSTOMER_ID.
  6. Click the Save icon.

Creating a Reconciliation Profile for the Oracle EBS User Management Resource Object

Create a reconciliation profile to copy all the changes made to the resource object (in the earlier section) into MDS:

  1. Expand the Resource Management folder, and then double-click Resource Objects.
  2. Search for and open the Oracle EBS User Management resource object.
  3. On the Object Reconciliation tab, click Create Reconciliation Profile.
  4. Click the Save icon.

Enabling Provisioning Operations on the New Attribute

Update the process definition by creating process tasks for handling provisioning operations on the newly added single-valued attribute as follows:

  1. Expand Process Management, and then double-click Process Definition.
  2. Search for and open the Oracle EBS UM User process definition.
  3. On the Tasks tab, click Add.

    The Creating New Task dialog box is displayed.

  4. In the Task Name field, enter the name of the process task. For example, enter Customer Id Updated.
  5. In the Task Description field, enter a description for the task. For example, enter Task for Customer Id updation.
  6. In the Task Properties region, select the properties to suit your requirement. For example, perform the following actions in the Task Properties region:

    • Select the following checkboxes:

      Conditional

      Allow Cancellation while Pending

      Allow Multiple Instances

    • From the Task Effect list, select No Effect.

    The following is a screenshot of the Creating New Task dialog box with relevant details filled in:

    Description of create_customer_id_task.jpg follows
    Description of the illustration create_customer_id_task.jpg
  7. Click the Save icon.
  8. On the Integration tab, click Add to assign an adapter for the process task created in the preceding steps.
  9. In the Handler Selection dialog box, select the Adapter option.
  10. From the list of adapters displayed in the Handler Name region, select the adapter that you want to assign to the process task. For example, select the adpEBSUMUPDATESINGLEATTRIBUTE adapter.
  11. Click the Save icon and close the dialog box.
  12. On the Integration tab, from the table in the Adapter Variables region, select the variable that you want to map. For example, select the fieldName variable.
  13. Click Map.
  14. In the Edit Data Mapping For Variable dialog box, create the adapter variable mapping as per your requirement. For example, create the following mapping:

    • Variable Name: fieldName

    • Map To: Literal

    • Qualifier: String

    • Literal Value: UD_EBS_UM_CUSTOMER_ID

  15. Click the Save icon and close the dialog box.
  16. Perform Steps 12 through 15 for the remaining variables listed in the Adapter Variables region. The following table lists sample values that you can select from the Map To, Qualifier, and Literal Value lists for each variable:
    Variable Map To Qualifier Literal Value

    fieldOldValue

    Process Data

    Customer Id, Old Value:select

    NA

    AdapterReturnCode

    Response Code

    NA

    NA

    objectType

    Literal

    String

    User

    ItResourceFieldName

    Literal

    String

    UD_EBS_UM_IT_RESOURCE_NAME

    fieldValue

    Process Data

    Customer Id

    NA

    processInstanceKey

    Process Data

    Process Instance

    NA
  17. Click the Save icon on the Process Definition form.
  18. On the Responses tab, click Add to add the SUCCESS response code, with Status C. This ensures that if the custom task is successfully run, then the status of the task is displayed as Completed. Similarly, add the CONNECTION_FAILED response code, with Status R.
  19. Click the Save icon and close the dialog box, and then save the process definition.

Updating the search.properties File

Update the search.properties file to include the newly added single-valued attribute as follows:

  1. Extract the contents of the org.identityconnectors.ebs-1.0.1115.jar file into a directory of your choice.
  2. In a text editor, open the search.properties located in the configuration directory.
  3. Search for the SQL query that must include the column name corresponding to the newly created attribute. For example, search for the UM_USER_RECON query.
  4. If the SQL query already contains the column name corresponding to the newly added attribute, then you can skip the rest of the steps mentioned in this section.
  5. If the SQL query does not include information about the newly added column name, then modify it to include the newly added column.

    See Sample SQL Queries Updated to Include Single-Valued Attributes for a sample query that includes the CUSTOMER_ID column in the UM_USER_RECON query.

  6. Repeat Steps 3 through 5 to update the remaining SQL queries such as UM_USER_SYNC, if applicable. For example, modify the UM_USER_SYNC SQL query to include PAPF.CUSTOMER_ID AS CUSTOMER_ID in the select query.
  7. Save the changes and close the file.
  8. Verify the updated queries.
  9. Update the connector bundle (org.identityconnectors.ebs-1.0.1115.jar) by running the following command:

    jar -cvfm org.identityconnectors.ebs-1.0.11150.jar META-INF/MANIFEST.MF *

  10. Run the Oracle Identity Manager Update JARs utility to update the new connector bundle (updated in Step 9) to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/UpdateJars.bat

    For UNIX:

    OIM_HOME/server/bin/UpdateJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 4 as the value of the JAR type.

Updating the Procedures.properties File

In order to support the newly added attribute (Customer Id) during create and update provisioning operations, you must update the stored procedure that is invoked in the Procedures.properties file. To do so:

  1. In a text editor, open the Procedures.properties file for editing.

  2. Search for and determine the names of wrapper packages and stored procedures used for invoking the create person and update person provisioning operations. For example, OIM_FND_USER_TCA_PKG.CREATEUSER and OIM_FND_USER_TCA_PKG.UPDATEUSER are the wrapper packages and stored procedures used for the create user and update user provisioning operations.

  3. Update the stored procedures determined in the earlier step as follows:

    1. Open any SQL client (for example, SQL Developer) and connect to the target system database using the apps user.

    2. Open the wrapper package and add the newly added attribute (for example, Customer Id) to the create user and update user stored procedures. For example, open the OIM_FND_USER_TCA_PKG package and add the newly added attribute to the CreateUser and UpdateUser stored procedures.

      The following screenshot highlights the stored procedures that must be updated in the OIM_FND_USER_TCA_PKG package to include the newly added attribute:

      Description of stored_proc_modify.jpg follows
      Description of the illustration stored_proc_modify.jpg

    3. Select the CreateUser stored procedure and update the input parameters to include the newly added attribute.

      The following screenshot highlights the newly added attribute (customer_id) in the CreateUser stored procedure:

      Description of stored_proc_input_param1.jpg follows
      Description of the illustration stored_proc_input_param1.jpg

    4. Select the UpdateUser stored procedure and update the input parameters to include the newly added attribute.

      The following screenshot highlights the newly added attribute (customer_id) in the UpdateUser stored procedure:

      Description of stored_proc_input_param2.jpg follows
      Description of the illustration stored_proc_input_param2.jpg

    5. Open OIM_FND_USER_TCA_PKG Body and select the CreateUser stored procedure.

    6. Update the CreateUser API call in the procedure with the newly added attribute.

      The following screenshots that show the updated CreateUser API:

      Description of update_api_call.gif follows
      Description of the illustration update_api_call.gif

    7. Repeat Steps 3.3.c through 3.3.f to update the UPDATEUSER stored procedure to include the newly added attribute.

    8. Re-compile the wrapper package.

    This completes the procedure to add a new single-valued attribute for reconciliation and provisioning.

Adding New Multivalued Attributes for Reconciliation and Provisioning

You can add new multivalued attributes for reconciliation and provisioning.

By default, the attributes listed in Table 3-3 are mapped for reconciliation and provisioning between Oracle Identity Manager and the target system. If required, you can map additional multivalued attributes for reconciliation and provisioning. The following sections describe the procedures to be performed for adding new multivalued attributes. The Security Attributes multivalued attribute has been used as an example to illustrate these procedures.

Summary of Steps to Add New Multivalued Attributes for Reconciliation and Provisioning

The following a summary of high-level steps to be performed to add a new multivalued attribute for reconciliation and provisioning:

  1. Update the DB wrapper package to include the new multivalued attribute. You must include the parent attribute in the main attribute list of the get_schema procedure and then create an attribute list with all the child attributes as described in Extending the Connector Schema.
  2. Update Oracle Identity Manager metadata to include the new attribute as described in Extending Oracle Identity Manager Metadata.
  3. Create a scheduled job to synchronize values in the target system attributes corresponding to the newly created multivalued attribute with values in Oracle Identity Manager as described in Creating Scheduled Jobs.
  4. Update the connector bundle to include the new multivalued attribute in the search.properties and Procedures.properties file as described in Updating the Connector Bundle.
  5. Add APIs to Wrapper packages to enable provisioning operation on the newly added multivalued attribute as described in Adding APIs to Wrapper Packages.

Extending the Connector Schema

You must extend the connector schema to include a new multivalued attribute for reconciliation and provisioning. To do so:

  1. Open any SQL client and connect to database using APPS user.
  2. Open the body of the OIM_FND_USER_TCA_PKG.pck wrapper package.
  3. Select the get_schema() stored procedure.
  4. Declare the new multivalued attribute. The syntax for declaring the new multivalued attribute is as follows:

    attr := attributelist();

  5. Initialize the attribute list by specifying the number of child attributes that the new multivalued attribute must contain in the following format:

    attr.extend(NUM);

    Here, NUM is the number of child attributes. Internally, an array for the specified number of child attributes is created.

    Sample value: attr.extend(4);

    You can also initialize the attribute list or increase the number of child attributes in the list by 1 by using the following statement for each child attribute to be added:

    attr.extend;

    See Also:

    Sample Code Snippets for Extending the Connector Schema for sample code snippets

  6. Define each child attribute to include information such as the attribute name, datatype, and permission flags in the following format:

    attr (ORD_NO) := attributeinfo(ATTR_NAME,ATTR_TYPE,CREATE_FLAG,UPDATE_FLAG,REQUIRED_FLAG,READ_FLAG)

    In this format:

    • ORD_NO is the order of the attribute in the list. This is mandatory.

    • ATTR_NAME is the name of the child attribute.

    • ATTR_TYPE is the SQL datatype of the child attribute.

    • CREATE_FLAG is a flag to represent whether the attribute is required during a create provisioning operation.

    • UPDATE_FLAG is a flag to represent whether the attribute can be updated.

    • REQUIRED_FLAG is a flag to represent whether the attribute is mandatory.

    • READ_FLAG is flag to represent whether the attribute can be read.

    A value of 1 or 0 for each flag denotes True or False, respectively. For example, a value 1, 0, 1, 0 for the flags mean that the attribute is a mandatory attribute and must be considered during create provisioning operations.

  7. End the new multivalued attribute definition and schema by using the following statements: 
    schemaout.extend;
schemaout(ORD_NO) := schema_object('ATTR_NAME', attr)

    In this statement, ORD_NO is the order of the multivalued attribute in the connector schema and ATTR_NAME is the name of the multivalued attribute being added. The following are sample statements:

    schemaout.extend;
schemaout( 4 ) := schema_object('__SECURITY_ATTRS__',attr);
  8. Re-compile the wrapper package.

Extending Oracle Identity Manager Metadata

You must extend the metadata of Oracle Identity Manager to include the new attribute added in Extending the Connector Schema. Extending Oracle Identity manager metadata involves performing the following procedures:

Creating Lookup Definitions

You must create lookup definitions for the new attribute, added in Extending the Connector Schema, as follows:

  1. Log in to the Design Console.
  2. Expand the Administration folder, and then double-click Lookup Definition.
  3. In the Code field, enter the name of the lookup definition. For example, enter Lookup.Oracle EBS UM.SecAttrNames.
  4. Select the Lookup Type option to specify that the look up definition represents a lookup field.
  5. In the Group field, enter the name of the form on which the lookup definition is displayed. For example, enter EBS UM.
  6. Click the Save icon.

    The lookup definition is created. The associated lookup field will be displayed in the form you specified.

  7. Repeat Steps 2 through 6 for creating the Lookup.Oracle EBS UM.SecAttrTypes lookup definition.

Creating Child Process Form

Create a child process form for the newly added attributes as follows:

  1. Expand Development Tools, and then double-click Form Designer.
  2. In the Table Name field, enter the name of the database table that is associated with the form. For example, enter UD_UM_SEC.
  3. In the Description field, enter explanatory information about the form. For example, enter Form for UM security attributes.
  4. Select the Process option. This is because the form is assigned to a provisioning process.
  5. Click the Save icon.

    The form is created. The words Initial Version are displayed in the Latest Version field.

  6. On the Additional Columns tab, click Add.

    A blank row is displayed.

  7. Enter values for columns such as Name, Variant Type, Length, Field Label and so on for all the attributes that you want to add to the form.
  8. Repeat Steps 6 and 7 for each attribute that you want. The following table provides a list of sample attributes that you can add:
    Name Variant Type Length Field Label Field Type Order

    UD_UM_SEC_APP_ID

    String

    200

    Application Name

    Lookup Field

    1

    UD_UM_SEC_ATTR_NAME

    String

    200

    Security Attribute Name

    Lookup field

    2

    UD_UM_SEC_ATTR_VALUE

    String

    200

    Security Attribute Value

    TextField

    3

    UD_UM_SEC_ATTR_TYPE

    String

    200

    Security Attribute Type

    Lookup Field

    4
  9. Click the Save icon.
  10. On the Properties tab, select the data field to which you want to add a property and property value, and then click Add Property. For example, select the Application Name data field and the click Add Property.
  11. In the Add Property dialog box, select the Property Name and then enter the property value. For example, from the Property Name list, select Lookup Code and in the Property Value field, enter Lookup.Oracle EBS UM.Applications.
  12. Click the Save icon and close the dialog box.
  13. Repeat Steps 10 through 12 for each field to which you want to add a property and property value. The following table lists the sample data fields and the corresponding property values:
    Column Name Column Type Property Name Property Value

    Security Attribute Name

    Lookup field

    Lookup Code

    Lookup.Oracle EBS UM.SecAttrNames

    Security Attribute Type

    Lookup field

    Lookup Code

    Lookup.Oracle EBS UM.SecAttrTypes
  14. Click the Save icon.
  15. Click Make Version Active. Accept any confirmation message that is displayed.

Updating the Parent Process Form

Update the parent process form of the newly added attribute as follows:

  1. Expand Development Tools, and then double-click Form Designer.
  2. Search for and open the UD_EBS_UM process form.
  3. Click Create New Version to create a version of the form.
  4. In the Label field, enter the version name. For example, version#2.
  5. Click the Save icon.
  6. Select the current version created in Step 4 from the Current Version list.
  7. On the Child Table(s) tab, click Assign to assign the child table to the form.
  8. From the Assign Child Table(s) dialog box, select the newly created child form and click the right arrow. For example, select UD_UM_SEC.
  9. Click OK.

    The selected child table is assigned to the form.

  10. Click the Save icon.
  11. Click Make Version Active.

Updating the Lookup Definition for Reconciliation Attribute Mapping

Add an entry for the new attribute in the lookup definition for reconciliation attribute mapping as follows:

  1. Expand the Administration folder, and then double-click Lookup Definition.
  2. Search for and open the Lookup.Oracle EBS UM.UM.ReconAttrMap lookup definition.
  3. To add a row, click Add.
  4. In the Code Key and Decode columns, enter values corresponding to the newly added child attributes. The Code Key and Decode values must be in the following format:

    Code Key: MULTIVALUED_FIELD_NAME~CHILD_FORM_FIELD_NAME[LOOKUP]

    In this format:

    • MULTIVALUED_FIELD_NAME is the name field on the parent process form.

    • CHILD_FORM_FIELD_NAME is the name of the field on the child process form.

    • [LOOKUP] is a flag denoting that the field is a lookup field.

    Decode: Corresponding target system attribute.

  5. Repeat Steps 3 and 4 for every newly added child attribute. The following table lists the sample entries you can add:
    Code Key Decode

    SecAttrs~Application Name[LOOKUP]

    __SECURITY_ATTRS__~__SECURITY_ATTRS__~SECURITY_APP_ID

    SecAttrs~Security Attribute Name[LOOKUP]

    __SECURITY_ATTRS__~__SECURITY_ATTRS__~SECURITY_ATTR_NAME

    SecAttrs~Security Attribute Value

    __SECURITY_ATTRS__~__SECURITY_ATTRS__~SECURITY_ATTR_VALUE

    SecAttrs~Security Attribute Type[LOOKUP]

    __SECURITY_ATTRS__~__SECURITY_ATTRS__~SECURITY_ATTR_TYPE
  6. Click the Save icon.

Updating the Lookup Definition for Provisioning Attribute Mapping

Add an entry for the attribute in the lookup definition for provisioning attribute mapping as follows:

  1. Expand the Administration folder, and then double-click Lookup Definition.
  2. Search for and open the Lookup.Oracle EBS UM.UM.ProvAttrMap lookup definition.
  3. To add a row, click Add.
  4. In the Code Key and Decode columns, enter values corresponding to the newly added child attributes. The Code Key and Decode values must be in the following format:

    Code Key: CHILD_FORM_NAME~CHILD_FIELD_LABEL[LOOKUP]

    In this format:

    • CHILD_FORM_NAME specifies the name of the child form.

    • CHILD_FIELD_NAME specifies the name of the field on the child form.

    • [LOOKUP] is a flag denoting that the field is a lookup field.

    Decode: Corresponding target system attribute.

  5. Repeat Steps 3 and 4 for every newly added child attribute. The following table lists the sample entries you can add:
    Code Key Decode

    UD_UM_SEC~Application Name[LOOKUP]

    __SECURITY_ATTRS__~__SECURITY_ATTRS__~SECURITY_APP_ID

    UD_UM_SEC~Security Attribute Name[LOOKUP]

    __SECURITY_ATTRS__~__SECURITY_ATTRS__~SECURITY_ATTR_NAME

    UD_UM_SEC~Security Attribute Value

    __SECURITY_ATTRS__~__SECURITY_ATTRS__~SECURITY_ATTR_VALUE

    UD_UM_SEC~Security Attribute Type[LOOKUP]

    __SECURITY_ATTRS__~__SECURITY_ATTRS__~SECURITY_ATTR_TYPE
  6. Click the Save icon.

Updating the Oracle EBS User Management Resource Object

In the resource object, add the reconciliation field corresponding to the new attribute as follows:

  1. Expand the Resource Management folder, and then double-click Resource Objects.
  2. Search for and open the Oracle EBS User Management resource object.
  3. On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.
  4. In the Field Name field, enter the name of the attribute. For example, SecAttrs.
  5. From the Field Type list, select a data type for the field. For example, select Multi-Valued Attribute.
  6. If you want to designate the attribute as a mandatory attribute, then select the Required check box.
  7. Click the Save icon and close the dialog box.
  8. Right-click the newly created field (for example, SecAttrs) and select Define Property Fields.

    For example, in the Field Name field, enter Application Name and select String from the Field Type list.

  9. Click the Save icon and close the dialog box.
  10. Repeat Steps 8 and 9 for adding all the child fields. The following table lists the sample field names and field types that you can add:
    Field Name Field Type

    Security Attribute Name

    String

    In addition, select the Required checkbox to designate this attribute as mandatory

    Security Attribute Value

    String

    Security Attribute Type

    String
  11. Click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.

Updating the Oracle EBS UM User Process Definition

Create a reconciliation field mapping for the newly added attribute in the process definition as follows:

  1. Expand Process Management and then double-click Process Definition.
  2. Search for and open the Oracle EBS UM User process definition.
  3. On the Reconciliation Field Mapping tab, click Add Table Map to map the newly created multivalued field.
  4. In the Add Reconciliation Table Mapping dialog box, from the Field Name list, select the multivalued field on the target system that you created in the resource object in Updating the Oracle EBS User Management Resource Object. For example, select SecAttrs.
  5. From the Table Name list, select the child table process form created in Creating Child Process Form.For example, select UD_UM_SEC.
  6. Click the Save icon and close the dialog box.
  7. Right-click the multivalued field you just mapped, and select Define Property Field Map from the menu that is displayed. For example, right-click the SecAttrs multivalued field and the select Define Property Field Map.
  8. From the Field Name list, select child field you want to map. For example, select Application Name.
  9. Double-click the Process Data Field field, select the correct mapping from the Lookup dialog box and click OK. For example, double-click Process Data Field field, and then select UD_UM_SEC_APP_ID.
  10. Repeat Steps 7 through 9 for each child field defined on the multivalued field. The following table lists sample field names and process data fields that you can add:
    Field Name Process Data Field

    Security Attribute Name

    _UM_SEC_ATTR_NAME

    In addition, select the Key Field for Reconciliation Matching check box.

    Security Attribute Value

    UD_UM_SEC_ATTR_VALUE

    Security Attribute Type

    UD_UM_SEC_ATTR_TYPE
  11. Click the Save icon.

Replicating Form Designer Changes to a New UI Form

Replicate all the changes made to the Form Designer of the Design Console to a new UI form as follows:

  1. Log in to Oracle Identity System Administration.
  2. Create and active a sandbox. See Creating and Activating a Sandbox for more information.
  3. Create a new UI form to view the upgraded fields. See Creating a New UI Form for more information about creating a UI form.
  4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form (created in the previous step), and then save the application instance.
  5. Publish the sandbox. See Publishing a Sandbox for more information.

Enabling Provisioning Operations on the New Attribute

Update the process definition by creating process tasks for handling provisioning operations on the newly added attribute as follows:

  1. Expand Process Management, and then double-click Process Definition.
  2. Search for and open the Oracle EBS UM User process definition.
  3. On the Tasks tab, click Add.

    The Creating New Task dialog box is displayed.

  4. In the Task Name field, enter the name of the process task. For example, enter Add Attributes.
  5. In the Task Description field, enter a description for the task. For example, enter Task to add security attributes.
  6. In the Task Properties region, select the properties to suit your requirement and click the Save icon. For example, perform the following actions in the Task Properties region:

    • Select the following checkboxes:

      Conditional

      Allow Cancellation while Pending

      Allow Multiple Instances

    • From the Child Table list, select the child table name, UD_UM_SEC.

    • From the Trigger Type list, select Insert.

  7. On the Integration tab, click Add to assign an adapter for the process task created in the preceding steps.
  8. In the Handler Selection dialog box, select the Adapter option.
  9. From the list of adapters displayed in the Handler Name region, select the adapter that you want to assign to the process task. For example, select the adpEBSUMADDCHILDDATA adapter.
  10. Click the Save icon and close the dialog box.
  11. On the Integration tab, in the table in the Adapter Variables region, click the variable that you want to map. For example, click the objectType variable.
  12. In the Edit Data Mapping For Variable dialog box, create the adapter variable mapping as per your requirement. For example, create the following mapping:

    Variable Name: objectType

    Map To: Literal

    Qualifier: String

    Literal Value: User

  13. Click the Save icon and close the dialog box.
  14. Perform Steps 11 through 13 for the remaining variables listed in the Adapter Variables region. The following table lists sample values that you can select from the Map To, Qualifier, and Literal Value lists for each variable:
    Variable Map To Qualifier Literal Value

    procInstanceKey

    Process Data

    Process Instance

    NA

    itResourceFieldName

    Literal

    String

    UD_EBS_UM_EBS_ITRES

    childTableName

    Literal

    String

    UD_UM_SEC

    childPrimaryKey

    Process Data

    Child Primary Key

    NA

    Adapter return value

    Response Code

    NA

    NA
  15. Click the Save icon on the Process Definition form.
  16. Repeat Steps 3 through 15 to create process tasks for Update and Delete provisioning operations.
  17. On the Responses tab, click Add to add at least the SUCCESS response code, with Status C. This ensures that if the custom task is successfully run, then the status of the task is displayed as Completed.
  18. Click the Save icon and close the dialog box, and then save the process definition.

Creating Scheduled Jobs

Note:

Perform the procedure described in this section for lookup schedule job that is used for any lookup attribute that can be a parent attribute or a child attribute.

You must create scheduled jobs for synchronizing values in the target system attributes (corresponding to the newly created multivalued field) with the lookup definitions created Creating Lookup Definitions. To do so:

  1. Log in to the Oracle Identity System Administration Console.
  2. In the left pane, under System Configuration, click Scheduler. The Advanced Administration is displayed with the Scheduler section in the System Management tab active.
  3. On the left pane, from the Actions menu, select Create. Alternatively, you can click the icon with the plus (+) sign beside the View list.
  4. On the Create Job page, enter values in the following fields under the Job Information section:

    • Job Name: Enter a name for the job. For example, enter Oracle EBS UM Target Security Attributes Lookup Reconciliation.

    • Task: Specify or select the name of the scheduled task that runs the job. For example, select Oracle EBS UM Target Connector Lookup Reconciliation.

    • Enter values for the remaining fields such Start Date, Retries, and Schedule Type.

  5. In the Parameters section, enter values for all the parameters of the scheduled job. For example, the following are the scheduled job parameters and their values:

    • Code Key Attribute: Code

    • Decode Attribute: Decode

    • IT Resource Name: Oracle EBS UM

    • Lookup Name: Lookup.Oracle EBS UM.SecAttrNames

    • Object Type: __SECURITY_ATTR_NAMES__

  6. Click Apply.
  7. Repeat Steps 2 through 6 to create scheduled jobs for any remaining multivalued fields. For example, repeat these steps to create a scheduled job for reconciling values into the Lookup.Oracle EBS UM.SecAttrTypes lookup definition with the __SECURITY_ATTR_TYPES__ object type.

Updating the Connector Bundle

You must update the connector bundle (org.identityconnectors.ebs-1.0.1115.jar) to include all the updates made in the earlier sections. To do so:

  1. Download the connector bundle (org.identityconnectors.ebs-1.0.11150.jar) file from the Oracle Identity Manager database by running the Download JARs utility. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/DownloadJars.bat

    For UNIX:

    OIM_HOME/server/bin/DownloadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 4 as the value of the JAR type.

  2. Extract the contents of the JAR file to any directory on the computer hosting Oracle Identity Manager.
  3. In a text editor, open the search.properties file located in the configuration directory of the extracted JAR file.
  4. In the first part of the search.properties file, add entries corresponding to the newly added attributes
  5. In the first part of the search.properties file, add entries corresponding entries for the newly added attribute by defining the object name, type of reconciliation operation, and the SQL query name. For example, add the following entries: 
    __SECURITY_ATTR_NAMES__.lookup=LOOKUP_SECATTR_NAME_QUERY
__SECURITY_ATTR_TYPES__.lookup=LOOKUP_SECATTR_DATATYPE_QUERY

    In this example:

    • __SECURITY_ATTR_NAMES and __SECURITY_ATTR_TYPES__ are the object names

    • lookup specifies that the query in this qntry will be used for performing lookup field synchronization.

    • LOOKUP_SECATTR_NAME_QUERY and LOOKUP_SECATTR_DATATYPE_QUERY are the SQL query names.

  6. In the second part of the search.properties file, add the SQL query corresponding to the SQL query name specified in Step 5. For example, add the following entries: 
    LOOKUP_SECATTR_DATATYPE_QUERY= select datatype as CODE, datatype as DECODE from ( select distinct(DATA_TYPE) as datatype from AK_ATTRIBUTES)

LOOKUP_SECATTR_NAME_QUERY= select sa.ATTRIBUTE_CODE as CODE, (CONCAT(fa.application_short_name || '~', sa.ATTRIBUTE_CODE)) AS DECODE FROM fnd_application fa, AK_ATTRIBUTES sa where fa.application_id=sa.attribute_application_id
  7. Update the SQL queries of UM_USER_RECON and UM_USER_SYNC to include information about the newly added attributes. For example, update both the UM_USER_RECON and UM_USER_SYNC SQL queries with the SQL query in Sample SQL Queries Updated to Include Multivalued Attributes.
  8. Save and close the search.properties file.
  9. In a text editor, open the Procedures.properties file located in the configuration directory of the JAR file extracted in Step 2.
  10. Add entries to corresponding to the newly added attributes. For example, add the following entries: 
    __SECURITY_ATTRS__.add=OIM_FND_USER_TCA_PKG.ADDUSERSECURITYATTRIBUTE
__SECURITY_ATTRS__.remove=OIM_FND_USER_TCA_PKG.DELETEUSERSECURITYATTRIBUTE

    See Provisioning Procedures for information about the format for adding entries to the Procedures.properties file.

  11. Save and close the Procedures.properties file.
  12. Re-create the connector bundle JAR file with the updated .properties files.
  13. Run the Oracle Identity Manager Upload JARs utility to post the new connector bundle (updated in Step 12) to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 4 as the value of the JAR type.

Adding APIs to Wrapper Packages

You must add APIs to Wrappers packages to enable the connector to perform provisioning operations on the newly added attribute. To do so:

  1. Open any SQL client. For example, SQL Developer.
  2. Open specification of the OIM_FND_USER_TCA_PKG package and then add entries that define the methods and their input parameters for performing provisioning operations. For example, add the following methods for the newly added attribute: 
    procedure addUserSecurityAttribute(user_id in number, SECURITY_ATTR_NAME in varchar2, SECURITY_APP_ID varchar2,SECURITY_ATTR_VALUE varchar2,SECURITY_ATTR_TYPE varchar2);
procedure deleteUserSecurityAttribute(user_id in number, SECURITY_ATTR_NAME in varchar2, SECURITY_APP_ID varchar2,SECURITY_ATTR_VALUE varchar2,SECURITY_ATTR_TYPE varchar2);
  3. Open the OIM_FND_USER_TCA_PKG package body and add the implementation of methods defined in the preceding step. For example, add the following implementation for the newly added attribute: 
    procedure addUserSecurityAttribute(user_id in number, SECURITY_ATTR_NAME in varchar2, SECURITY_APP_ID varchar2,SECURITY_ATTR_VALUE varchar2,SECURITY_ATTR_TYPE varchar2)
    IS
          x_return_status VARCHAR2(2000);
          x_msg_count NUMBER;
          x_msg_data VARCHAR2(2000);
  l_varchar2_value varchar2(2000);
  l_date_value date;
  l_number_value NUMBER;
    begin
    if SECURITY_ATTR_TYPE = 'NUMBER' then
l_number_value := SECURITY_ATTR_VALUE;
elsif SECURITY_ATTR_TYPE = 'DATE' then
    l_date_value := SECURITY_ATTR_VALUE;
else
l_varchar2_value := SECURITY_ATTR_VALUE;
end if;
        icx_user_sec_attr_pub.create_user_sec_attr(
           p_api_version_number   => 1,
           p_return_status        => x_return_status,
           p_msg_count            => x_msg_count,
           p_msg_data             => x_msg_data,
           p_web_user_id          => user_id,
           p_attribute_code       => SECURITY_ATTR_NAME,
           p_attribute_appl_id    => SECURITY_APP_ID,
           p_varchar2_value       => l_varchar2_value,
           p_date_value           => l_date_value,
           p_number_value         => l_number_value,
           p_created_by           => -1,
           p_creation_date        => sysdate,
           p_last_updated_by      => -1,
           p_last_update_date     => sysdate,
           p_last_update_login    => -1);
    end addUserSecurityAttribute;

procedure deleteUserSecurityAttribute(user_id in number, SECURITY_ATTR_NAME in varchar2, SECURITY_APP_ID varchar2,SECURITY_ATTR_VALUE varchar2,SECURITY_ATTR_TYPE varchar2)
    IS
          x_return_status VARCHAR2(2000);
          x_msg_count NUMBER;
          x_msg_data VARCHAR2(2000);
  l_varchar2_value varchar2(2000);
  l_date_value date;
  l_number_value NUMBER;
    begin
    if SECURITY_ATTR_TYPE = 'NUMBER' then
l_number_value := SECURITY_ATTR_VALUE;
elsif SECURITY_ATTR_TYPE = 'DATE' then
    l_date_value := SECURITY_ATTR_VALUE;
else
l_varchar2_value := SECURITY_ATTR_VALUE;
end if;
        icx_user_sec_attr_pub.Delete_User_Sec_Attr(
           p_api_version_number   => 1,
           p_return_status        => x_return_status,
           p_msg_count            => x_msg_count,
           p_msg_data             => x_msg_data,
           p_web_user_id          => user_id,
           p_attribute_code       => SECURITY_ATTR_NAME,
           p_attribute_appl_id    => SECURITY_APP_ID,
           p_varchar2_value       => l_varchar2_value,
           p_date_value           => l_date_value,
           p_number_value         => l_number_value
    );
    end deleteUserSecurityAttribute;
  4. Save and close the file.
  5. Rerun the scripts to compile the wrapper package.

Configuring Transformation of Data During User Reconciliation

You can configure transformation of reconciled single-valued account data according to your requirements.

Note:

This section describes an optional procedure. Perform this procedure only if you want to configure transformation of data during reconciliation.

You can configure transformation of reconciled single-valued data according to your requirements. For example, you can use email to create a different value for the Email field in Oracle Identity Manager.

To configure transformation of data:

  1. Write code that implements the required transformation logic in a Java class.

    The following sample transformation class creates a value for the Email attribute by using values fetched from the EMAIL_ADDRESS column of the target system:

    package oracle.iam.connectors.common.transform;
 
import java.util.HashMap;
 
public class TransformAttribute {
 
      /*
      Description:Abstract method for transforming the attributes
      
      param hmUserDetails<String,Object> 
 
      HashMap containing parent data details
 
      param hmEntitlementDetails <String,Object> 
 
      HashMap containing child data details 
      
      */
      public Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails,String sField) {
      /*
       * You must write code to transform the attributes.
       Parent data attribute values can be fetched by 
       using hmUserDetails.get("Field Name").
       *To fetch child data values, loop through the
       * ArrayList/Vector fetched by hmEntitlementDetails.get("Child          Table")
       * Return the transformed attribute.
       */
      String sEmail= "trans" + (String)hmUserDetails.get(sField);
      return sEmail;
      }
}

  2. Create a JAR file to hold the Java class.

  3. Run the Oracle Identity Manager Upload JARs utility to post the JAR file to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 1 as the value of the JAR type.

  4. Create a lookup definition for transformation and add an entry to it as follows:

    1. Log in to the Design Console.

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

    3. In the Code field, enter Lookup.Oracle EBS UM.UM.ReconTransformation as the name of the lookup definition.

    4. Select the Lookup Type option.

    5. On the Lookup Code Information tab, click Add.

      A new row is added.

    6. In the Code Key column, enter the name of the resource object field into which you want to store the transformed value. For example: Email.

    7. In the Decode column, enter the name of the class that implements the transformation logic. For example, oracle.iam.connectors.common.transform.TransformAttribute.

    8. Save the changes to the lookup definition.

  5. Add an entry in the Lookup.Oracle EBS UM.UM.Configuration lookup definition to enable transformation as follows:

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

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

    3. Create an entry that holds the name of the lookup definition used for transformation as follows:

      Code Key: Recon Transformation Lookup

      Decode: Lookup.Oracle EBS UM.UM.ReconTransformation

    4. Save the changes to the lookup definition.

Configuring Validation of Data During Reconciliation and Provisioning

You can configure validation of reconciled and provisioned single-valued data according to your requirements.

For example, you can validate data fetched from the Email attribute to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the First Name field on the process form so that the number sign (#) is not sent to the target system during provisioning operations.

For data that fails the validation check, the following message is displayed or recorded in the log file:

oracle.iam.connectors.icfcommon.recon.SearchReconTask : handle : Recon event skipped, validation failed [Validation failed for attribute: [FIELD_NAME]]

To configure validation of data:

  1. Write code that implements the required validation logic in a Java class.

    The following sample validation class checks if the value in the Email attribute contains the number sign (#):

    package com.validate;
import java.util.*;
public class MyValidation {
public boolean validate(HashMap hmUserDetails,
              HashMap hmEntitlementDetails, String field) {
            /*
         * You must write code to validate attributes. Parent
         * data values can be fetched by using hmUserDetails.get(field)
         * For child data values, loop through the
         * ArrayList/Vector fetched by hmEntitlementDetails.get("Child Table")
         * Depending on the outcome of the validation operation, 
         * the code must return true or false.
         */
         /*
         * In this sample code, the value "false" is returned if the field
         * contains the number sign (#). Otherwise, the value "true" is
         * returned.
         */
            boolean valid=true;
            String sEmail=(String) hmUserDetails.get(field);
            for(int i=0;i<sEmail.length();i++){
              if (sEmail.charAt(i) == '#'){
                    valid=false; 
                    break;
              } 
            }
            return valid;
      }
}

  2. Create a JAR file to hold the Java class.

  3. Run the Oracle Identity Manager Upload JARs utility to post the JAR file to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 1 as the value of the JAR type.

  4. If you created the Java class for validating a process form field for reconciliation, then:

    1. Log in to the Design Console.

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

    3. In the Code field, enter Lookup.Oracle EBS UM.UM.ReconValidation as the name of the lookup definition.

    4. Select the Lookup Type option.

    5. On the Lookup Code Information tab, click Add.

      A new row is added.

    6. In the Code Key column, enter the resource object field name. For example, Email.

    7. In the Decode column, enter the class name. For example, com.validate.MyValidation.

    8. Save the changes to the lookup definition.

    9. Search for and open the Lookup.Oracle EBS UM.UM.Configuration lookup definition.

    10. Create an entry with the following values:

      Code Key: Recon Validation Lookup

      Decode: Lookup.Oracle EBS UM.UM.ReconValidation

    11. Save the changes to the lookup definition.

  5. If you created the Java class for validating a process form field for provisioning, then:

    1. Log in to the Design Console.

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

    3. In the Code field, enter Lookup.Oracle EBS UM.UM.ProvValidation as the name of the lookup definition.

    4. Select the Lookup Type option.

    5. On the Lookup Code Information tab, click Add.

      A new row is added.

    6. In the Code Key column, enter the process form field name. In the Decode column, enter the class name.

    7. Save the changes to the lookup definition.

    8. Search for and open the Lookup.Oracle EBS UM.UM.Configuration lookup definition.

    9. Create an entry with the following values:

      Code Key: Provisioning Validation Lookup

      Decode: Lookup.Oracle EBS UM.UM.ProvValidation

    10. Save the changes to the lookup definition.