Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Lab 19: Event Handlers for User Entities
Disclaimer: The Virtual Machine Image and other software are provided for use only during the workshop. Please note that you are responsible for deleting them from your computers before you leave. If you would like to try out any of the Oracle products, you may download them from the Oracle Technology Network (http://www.oracle.com/technology/index.html) or the Oracle E-Delivery WebSite(http://edelivery.oracle.com)
OIM 11g R2 Workshop - Lab 19
2
Contents
I. Introduction
II. Content
2.1 Prerequisites for the sample
2.2 Create the Contractor ID field in the database and in the business tier
2.3 Create the Contractor ID field in the user interface
2.4 Define a database IT resource that will be used by the event handler
2.5 Build & Deploy the sample
2.6 Post deployment Unit testing Procedure
2.6.1 Test the Contractor on-boarding (event handler) via UI
2.6.2 Test the Contractor on-boarding (event handler) via Reconciliation
I . Introduction
If an employee is a Contractor, she/he must be registered in the Contractor Registration System, which is an external application. This application is a database application. The database has the following structure:
User ID Contractor ID First Name Last Name
After successful registration, her/his Contractor ID must be retrieved and updated in his OIM User Profile.
This use-case will be developed as a plug-in and deployed on Oracle Identity Manager 11g R2 environment.
The plug-in will be used for extracting “Contractor Id” or any configured column name from specified database table and update OIM User profile.
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
This event handler will be implemented as PostProcessHandler and registered for Create operation of User. It will be a conditional event handler, executing for only "Contractor" users. If the user type is Contractor then it will connect the external application to retrieve the Contractor Id (field name defined in DB.table.column.to.retrieve) based on the OIM user id (defined in DB.Matching.OIM.User.Field) and update the OIM User profile with contractor Id.
II Content
2.1 Prerequisites for the sample
Create Database table ”Contractor” using SQL
Column Name Data type
USERID varchar2(100) primary key
CONTRACTORID varchar2(100)
FIRSTNAME varchar2(100)
LASTNAME varchar2(100)
Open SQLDeveloper from Startup_Scripts of Desktop
OIM 11g R2 Workshop - Lab 19
4
Click FileOpen
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Open database script for contractor.sql file located in /app/dummydata/Lab 19
OIM 11g R2 Workshop - Lab 19
6
Select ‘OIM’ as DB connection in upper right of tool,then Click ‘Run Statement’ Button
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
You should see Contractor table and data have been created
OIM 11g R2 Workshop - Lab 19
8
Import “ContractorIDConfiguration_updated.xml” file located in /app/dummydata/Lab
19/ContractorIDEventHandlerPostProc/oim_objects. It will create the lookup table named
lookup.externalDatabase.configuration which will be used by the event handler.
To import the above file into OIM, login (xelsysadm / Oracle123) to the System Administration web console of OIM and click on Import in the System Management area as shown below (you may have to
unblock pop-ups in your browser):
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
The Import window should show up (if you get a warning that another import is in progress, select Start import anyway and click on Get Lock). Then select ContractorIDConfiguration_updated.xml and click
on Add File
Click on Import twice (the second time is a confirmation). Wait till the dialog window ”Import successful” opens and click on OK. You can close then the Import screen.
The current event handler has been developed considering a highly configurable design. Therefore, a lookup code has been introduced so that developers can tweak values of various parameters and change the behavior. By default, they have the optimum default values to make the event handler work as per the
OIM 11g R2 Workshop - Lab 19
10
environment set in the VM. To find out more details on what can be customized and configured better to your needs (and only if that is required), check the lookup code “lookup.externalDatabase.configuration” with the OIM System Administration web console which would have been already created by the DM file import. Click on Lookups in the Configuration area
Enter “lookup.externalDatabase.configuration” in the Meaning field and click on Search
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Follow the description below to understand how these parameters could be tweaked. By default, they have the
optimum default values to make the event handler work as per the environment set in the VM.
OIM 11g R2 Workshop - Lab 19
12
Code Key Decode Information
DB.Matching.OIM.User.Field UserID The OIM user field. This field value will be used to find matching record in DB column defined in the LKU key DB.table.column.to.retrieve
DB.ITResource ExternalContractorDatabase The IT resource pointing to the related database
DB.Table.Name Contractor The DB table name. This table will be used to retrieve column value defined in LKU: DB.table.field.to.retrieve
DB.Table.Column.To.Retrieve ContractorID The DB column name. This column name will be used to retrieve value from table defined in LKU key : DB.table.name
OIM.User.Field.To.Update ContractorId The OIM User field. This field value will be updated with corresponding DB table field value.
OIM.UserType.Event.Identifier Contractor The user type identifier. This must be same as OIM User Type as it will be used to match OIM User Type during the execution of event handler.
Close the Lookups window.
Contractor on-boarding process would use a flat file as a source of identities. In order to do so, a flat file Generic Connector named “HR_FILE_GTC_CONNECTOR” is already created in the VM
Steps used to create it: OIM System Administration console -> Configuration -> Generic Connector
Click on Create
Name: HR_FILE_GTC_CONNECTOR
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Reconciliation: Transport Provider: Shared Drive Format Provider: CSV Trusted Source Reconciliation: checked Click on Continue
Shared Drive: Staging Directory: /app/dummydata/Lab 19/ Archiving Directory: /app/dummydata/Lab 19/archive File Prefix: identities Specified Delimiter: | Design Parameters: File Encoding: Cp1251 Source Date Format: yyyy/MM/dd hh:mm:ss z Reconciliation Type: Full Click on Continue
Mapping(Note:The Data Type of Hiredate is Date)
Reconcilation Staging OIM USER
empID User Login (matching only)
firstName First Name
middleName Middle Name
lastName Last Name
Email Email
businessUnitID Organization
location Country
userType Role
OIM 11g R2 Workshop - Lab 19
14
XellerateType User Type
status Status
managerEmpID Manager
Hiredate(Data Type:Date) Hire Date Click Close and Save
2.2 Create the Contractor ID field in the database and in the business tier
Open The OIM System Administration web console
Create a Sandbox: Sandboxes -> Create Sandbox and name it “create_ContractorId”
Click on Save and Close
Click User link under System Entities
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19
16
Click on Create a Custom Field icon
Select Text field type and click on OK
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Enter:
Display Label Contractor ID
Name ContractorId
Searchable selected
OIM 11g R2 Workshop - Lab 19
18
Click on Save and Close
Select the Sandbox and click on Export Sandbox (it is a good habit to save a Sandbox in order to identify what
has been done during the customization)
A zip is downloaded:
Now publish the Sandbox selecting it and clicking on Publish Sandbox
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Confirm clicking on Yes
2.3 Create the Contractor ID field in the user interface
Open the Self Service web console
Create and activate a new Sandbox named create_ContratorId_UI
Click on Users
OIM 11g R2 Workshop - Lab 19
20
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Click on Search and on the first User Login link
Click on Customize and View -> Source
OIM 11g R2 Workshop - Lab 19
22
Click on panelFormLayout of the Basic Information
Confirm the modification of the UI clicking on Edit
Click on Add Content
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Click on Open of Data Component – Manage UsersCatalog
OIM 11g R2 Workshop - Lab 19
24
Formatted: Font color: Black
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Go to the bottom of the list and open userVO1 component
Formatted: Indent: First line: 0"
OIM 11g R2 Workshop - Lab 19
26
Formatted: Font color: Black
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Click on the refresh icon
Click on Add near the Contractor Id component,then Select ADF Output Text w/ Label
Formatted: Font:
OIM 11g R2 Workshop - Lab 19
28
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Click on Close in the “Add Content” window
You can eventually change the position of the Contractor ID field clicking on Edit again, selecting
“panelFormLayout” after the “Basic Information” entry
OIM 11g R2 Workshop - Lab 19
30
Click on “Child Components” and reorder the fields :
Click on OK.
Click on Close on the right top of the screen
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Close the “User Details” and “Users” tabs and publish the Sandbox (after exporting it if you wish).
Back to the “User Details” view screen you can see the added field:
OIM 11g R2 Workshop - Lab 19
32
2.4 Define a database IT resource that will be used by the event handler
Connectivity parameters to the Contractor database (table) are stored in an IT resource. To create this IT
resource from OIM System Administration web console follow the steps below:
Click on IT Resource in the Configuration area
Click on Create IT Resource
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Provide the information given in the table below. Please note that the IT Resource Type must be selected as
Database.
IT Resource Name ExternalContractorDatabase
IT Resource Type Database
OIM 11g R2 Workshop - Lab 19
34
Click on Continue
Specify IT Resource Parameter Values for the desired database:
DatabaseName OIM11gR2DB
Driver oracle.jdbc.OracleDriver
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Password Oracle123
URL jdbc:oracle:thin:@//identity.oracleads.com:1521/orcl
UserID dev_oim
OIM 11g R2 Workshop - Lab 19
36
Click on Continue
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Keep default value for the access permissions clicking on Continue
V
e
r
i
f
y
I
T
R
e
s
o
u
r
N
o
t
i
OIM 11g R2 Workshop - Lab 19
38
ce
Notice the success of the connection to the database and click on Create.
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Click on Finish
2.5 Build & Deploy the sample (JDeveloper 11.1.1.7 should be installed and the extension oim-customization-installer version 1.10 loaded; also check that the OS variable APPSERVER_TYPE is set to wls before starting JDeveloper)
OIM 11g R2 Workshop - Lab 19
40
Open ContractorIDEventHandlerPostProc.jpr in JDeveloper, which is available in /app/dummydata/Lab
19/ContractorIDEventHandlerPostProc
Right click the project and click on Project Properties from the context menu.
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Go to Libraries and Classpath section and drop the existing Oimclient.jar selecting the jar and clicking on
Remove:
OIM 11g R2 Workshop - Lab 19
42
Add the jar clicking on Add JAR/Directory and selecting oimclient.jar from
/app/Middleware/Oracle_IDM1/designconsole/lib
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Repeat the operation to register wlfullclient.jar from /app/Middleware/Oracle_IDM1/designconsole/ext
Cli
c
k
o
n
O
K
a
n
d
S
a
v
e
.
Select the project (ContractorIDEventHandlerPostProc) in the Application Navigator.
Go to Tools -> OIM Customization Installer -> Configure.
OIM 11g R2 Workshop - Lab 19
44
Enter the following parameters for the connection to the OIM application:
OIM User ID xelsysadm
OIM User Password Oracle123
Server URL t3://identity.oracleads.com:14000
Click on Test Connection
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Continue the configuration entering the parameters for the connection to the MDS database:
OIM MDS DB User ID DEV_MDS
DB User Password Oracle123
Connection URL jdbc:oracle:thin:@identity.oracleads.com:1521:orcl
Click on Test Connection
OIM 11g R2 Workshop - Lab 19
46
Click on Save
Select the project (ContractorIDEventHandlerPostProc) in the Application Navigator.
Go to Tools -> OIM Customization Installer -> Deploy.
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Click on Close on the successful dialog window
You can close JDeveloper (click on Yes if asked to save some updated files)
OIM 11g R2 Workshop - Lab 19
48
2.6 Post deployment Unit testing Procedure
Once the steps mentioned in "Deployment Procedure" are followed, the sample can be run against an existing OIM installation on the same host.
2.6.1 Test the Contractor on-boarding (event handler) via UI
Open OIM Self Service web console and create new user LeelahVIJAY of type “Contractor”.
Why Leelah? Because his name is in the Contractor table used to find its Contractor ID.
Click on Users and on Create
Enter the following data:
First Name Leelah
Last Name Drubld
Email [email protected]
Organization Xellerate Users
User Type Contractor
User Login LEELAH
Password Oracle123
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19
50
Click on Submit
You can check if you want in the database that the field USR_UDF_CONTRACTOR_ID has been updated:
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
Search the user that has been created:
OIM 11g R2 Workshop - Lab 19
52
Click on the User Login link from the search result, the Contractor ID gets updated in the user profile: NOT
YET!!
========== as of August 8, 2012 ===========================================
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
2.6.2 Test the Contractor on-boarding (event handler) via Reconciliation
1. Login to the OIM “System Administration” console and click on “Search Scheduled Jobs”.
2. Search for the scheduled job created while creating the generic connector. Enter the name of scheduled job as
HR_FILE_GTC_CONNECTOR_GTC in the text box and click on the search arrow button as shown below.
OIM 11g R2 Workshop - Lab 19
54
3. Click on the schedule job from the search result and then click on “Run Now”.
Formatted: Left
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
4. After clicking the Run Now below screen appears.
OIM 11g R2 Workshop - Lab 19
56
5. Click on the “Refresh” button.
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
6. Below screen appears.
OIM 11g R2 Workshop - Lab 19
58
7. Search for any one user that was present in the flat file.
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
8. Click on the User from the search result, the Contractor ID gets updated in the user profile.