Extending the Functionality of the EBS User Management Connector

6 Extending the Functionality of the EBS User Management Connector

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

6.1 Adding New Multivalued Attributes for Reconciliation and Provisioning

You can add new multivalued attributes for reconciliation and provisioning.

By default, the attributes listed in Attribute Mappings are mapped for reconciliation and provisioning between Oracle Identity Governance 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.

6.1.1 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:

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.
Update Oracle Identity Goernance metadata to include the new attribute as described in Extending Oracle Identity Manager Metadata.
Create a scheduled job to synchronize values in the target system attributes corresponding to the newly created multivalued attribute with values in Oracle Identity Governance as described in Creating Scheduled Jobs.
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.
Add APIs to Wrapper packages to enable provisioning operation on the newly added multivalued attribute as described in Adding APIs to Wrapper Packages.

6.1.2 Extending the Connector Schema

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

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

attr := attributelist();
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
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.
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);
```
Re-compile the wrapper package.

6.1.3 Extending Oracle Identity Manager Metadata

By default, the multivalued fields listed on the Schema page for your application in Identity Self Service are mapped for reconciliation between Oracle Identity Governance and the target system. If required, you can add new multivalued fields for target resource reconciliation.

To add new multivalued fields for reconciling users from a target application:

Log in to Oracle Identity System Administration and create a lookup that can hold the list of values for the multivalued field that you want to add.
Create a child form and add attributes as follows:
1. Log in to Identity Self Service.
2. Search for and open the application you created for your target system for editing.
3. On the Schema page, add a new child form and its attributes. For example, enter values for the Display Name and Target Attribute fields.
  Note:
  - Ensure to select the Recon Field option.
  - When you add attributes to the child form, from the Advanced Settings option, ensure to mark the newly added attribute as a Lookup.
  - In the List of values field, enter the name of the lookup created in Step 1.
4. Apply the changes.
Log in to Identity System Administration, create a new form and associate it with your application.

6.1.4 Creating Scheduled Jobs

You can either use these predefined jobs or edit them to meet your requirements. Alternatively, you can create custom reconciliation jobs. For information about editing these predefined jobs or creating new ones, see Updating Reconciliation Jobs in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

6.1.5 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:

Download the connector bundle (org.identityconnectors.ebs-1.0.11150.jar) file from the Oracle Identity Governance 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 Governance administrator, URL of the Oracle Identity Governance 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.
Extract the contents of the JAR file to any directory on the computer hosting Oracle Identity Governance.
In a text editor, open the search.properties file located in the configuration directory of the extracted JAR file.
In the first part of the search.properties file, add entries corresponding to the newly added attributes
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.

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

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.
Save and close the search.properties file.
In a text editor, open the Procedures.properties file located in the configuration directory of the JAR file extracted in Step 2.
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 About Provisioning Procedures for information about the format for adding entries to the Procedures.properties file.
Save and close the Procedures.properties file.
Re-create the connector bundle JAR file with the updated .properties files.
Run the Oracle Identity Governance Upload JARs utility to post the new connector bundle (updated in Step 12) to the Oracle Identity Governance database. This utility is copied into the following location when you install Oracle Identity Governance:

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 Governance administrator, URL of the Oracle Identity Governance 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.

6.1.6 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:

Open any SQL client. For example, SQL Developer.

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

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;

Save and close the file.
Rerun the scripts to compile the wrapper package.

6.2 Configuring the Connector for Multiple Installations of the Target System

You must create copies of configurations of your base application to configure it for multiple installations of the target system.

The following example illustrates this requirement:

The London and New York offices of Example Multinational Inc. have their own installations of the target system, including independent schema for each. The company has recently installed Oracle Identity Governance, and they want to configure it to link all the installations of the target system.

To meet the requirement posed by such a scenario, you must clone your application which copies all configurations of the base application into the cloned application. For more information about cloning applications, see Cloning Applications in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

6.3 Configuring Transformation and Validation of Data

Configure transformation and validation of user account data by writing Groovy script logic while creating your application.

You can configure transformation of reconciled single-valued user data according to your requirements. For example, you can use First Name and Last Name values to create a value for the Full Name field in Oracle Identity Governance.

Similarly, you can configure validation of reconciled and provisioned single-valued data according to your requirements. For example, you can validate data fetched from the First Name 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.

To configure transformation or validation of user account data, you must write Groovy scripts while creating your application. For more information about writing Groovy script-based validation and transformation logic, see Validation and Transformation of Provisioning and Reconciliation Attributes of Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

6.4 Configuring Action Scripts

You can configure Action Scripts by writing your own Groovy scripts while creating your application.

These scripts can be configured to run before or after the create, update, or delete an account provisioning operations. For example, you can configure a script to run before every user creation operation.

For information on adding or editing action scripts, see Updating the Provisioning Configuration in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.