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) Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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 2 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.
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 USERID CONTRACTORID FIRSTNAME LASTNAME Data type varchar2(100) primary key varchar2(100) varchar2(100) varchar2(100) Open SQLDeveloper from Startup_Scripts of Desktop Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Click File Open 4
Open database script for contractor.sql file located in /app/dummydata/lab 19 Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Select OIM as DB connection in upper right of tool,then Click Run Statement Button 6
You should see Contractor table and data have been created Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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): 8
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 Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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 10
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. Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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 12
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 empid firstname middlename lastname Email businessunitid location usertype OIM USER User Login (matching only) First Name Middle Name Last Name Email Organization Country Role Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 XellerateType status managerempid Hiredate(Data Type:Date) User Type Status Manager 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 14
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Click on Create a Custom Field icon Select Text field type and click on OK 16
Enter: Display Label Name Searchable Contractor ID ContractorId selected Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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 18
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 Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
20 OIM 11g R2 Workshop - Lab 19
Click on Search and on the first User Login link Click on Customize and View -> Source Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Click on panelformlayout of the Basic Information Confirm the modification of the UI clicking on Edit Click on Add Content 22
Click on Open of Data Component Manage UsersCatalog Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Formatted: Font color: Black 24
Go to the bottom of the list and open uservo1 component Formatted: Indent: First line: 0" Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Formatted: Font color: Black 26
Formatted: Font: Click on the refresh icon Click on Add near the Contractor Id component,then Select ADF Output Text w/ Label Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
28 OIM 11g R2 Workshop - Lab 19
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 Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Click on Child Components and reorder the fields : Click on OK. Click on Close on the right top of the screen 30
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: Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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 32
Provide the information given in the table below. Please note that the IT Resource Type must be selected as Database. IT Resource Name IT Resource Type ExternalContractorDatabase Database Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Click on Continue Specify IT Resource Parameter Values for the desired database: DatabaseName Driver OIM11gR2DB oracle.jdbc.oracledriver 34
Password URL UserID Oracle123 jdbc:oracle:thin:@//identity.oracleads.com:1521/orcl dev_oim Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Click on Continue 36
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 Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 ce Notice the success of the connection to the database and click on Create. 38
Click on Finish 2.5 Build & Deploy the sample (JDeveloper 11.1.1.7 should be installed and the extension oimcustomization-installer version 1.10 loaded; also check that the OS variable APPSERVER_TYPE is set to wls before starting JDeveloper) Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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. 40
Go to Libraries and Classpath section and drop the existing Oimclient.jar selecting the jar and clicking on Remove: Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Add the jar clicking on Add JAR/Directory and selecting oimclient.jar from /app/middleware/oracle_idm1/designconsole/lib 42
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. Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Enter the following parameters for the connection to the OIM application: OIM User ID OIM User Password Server URL xelsysadm Oracle123 t3://identity.oracleads.com:14000 Click on Test Connection 44
Continue the configuration entering the parameters for the connection to the MDS database: OIM MDS DB User ID DB User Password Connection URL DEV_MDS Oracle123 jdbc:oracle:thin:@identity.oracleads.com:1521:orcl Click on Test Connection Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Click on Save Select the project (ContractorIDEventHandlerPostProc) in the Application Navigator. Go to Tools -> OIM Customization Installer -> Deploy. 46
Click on Close on the successful dialog window You can close JDeveloper (click on Yes if asked to save some updated files) Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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 Last Name Email Organization User Type User Login Password Leelah Drubld Leelah.Keighley@oracle.com Xellerate Users Contractor LEELAH Oracle123 48
Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Click on Submit You can check if you want in the database that the field USR_UDF_CONTRACTOR_ID has been updated: 50
Search the user that has been created: Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 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 =========================================== 52
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. Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 Formatted: Left 3. Click on the schedule job from the search result and then click on Run Now. 54
4. After clicking the Run Now below screen appears. Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 5. Click on the Refresh button. 56
6. Below screen appears. Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class
OIM 11g R2 Workshop - Lab 19 7. Search for any one user that was present in the flat file. 58
8. Click on the User from the search result, the Contractor ID gets updated in the user profile. Oracle Proprietary - Restricted to Personal Use in an Oracle partner training class