Oracle Identity Manager 11g: Developing Plug-ins

<Do not delete this text because it is a placeholder for the generated list of "main" topics when run in a browser>

Purpose

This example is used to demonstrate how to deploy supplied examples of Oracle Identity Manager 11g plug-ins contained in a Oracle JDeveloper 11g. The purpose of this tutorial is to execute an Ant command script that deploy custom plug-in sample code from a JDeveloper project to Oracle Identity Manager 11g. Thereafter, while verifying that the deployed plug-ins work, you examine the sample source code and associated metadata used to implement the plug-in functionality to gain a basic understanding of how you can develop your own plug-in components.

Note: The initial part of this tutorial covers the deployment of the plug-ins, and then you briefly explore the deployed plug-in code before you test its effects by performing actions in the Oracle Identity Manager 11g administration console. You can use the sample source code template for your own custom plug-in classes. Consult the Developing Plug-ins URL reference in the Resources section of this tutorial for more information.

Time to Complete

Approximately 45 minutes.

Overview

A plug-in is software that extends the functionality provided by Oracle Identity Manager 11g. The plug-in framework enables you to define, register, and configure plug-ins. Two types of plug-ins can be utilized at plug-in points:

A plug-in point is a specific point in the business logic where extensibility can be provided through an interface definition that accompanies the specific plug-in point. Users can extend the plug-in interface exposed for Oracle Identity Manager 11g based on the business requirements and register them as plug-ins. For more information on the interfaces that provide plug-in points refer to the Developing Plug-ins link in the Resources section of this tutorial for a link to the appropriate documentation.

For example, the plug-in framework provides Oracle Identity Manager 11g the following subset of capabilities:

Scenario (Optional)

Angel works as a system engineer for Mydo Main Corporation. She is responsible for integrating identity and access management systems within the company. One such task is extending the functionality of the Oracle Identity Manager via developing Oracle Identity Manager plug-ins. In order to do that, she decides to write simple Oracle Identity Manager plug-ins to get familiar with how to develop an Oracle Identity Manager plug-in.

Software and Hardware Requirements (Optional)

The following is a list of software requirements:

Prerequisites

Before starting this tutorial, the following tasks need to be completed:

.

The Oracle Database should be installed, configured, and started

.

The Oracle WebLogic Server should be installed, configured, and started

.

Oracle Identity Manager should be installed, configured, and started

.

Oracle JDeveloper should be installed

.

Apache Ant 1.7 or later should be installed

.

Java JDK 1.6 or later should be installed

In addition to the above numbered list, the following needs to be addressed:

Generating the wlfullclient.jar File

If the wlfullclient.jar is not already present in the WL_HOME/server/lib directory, then in a Terminal window to generate the file perform the following commands:

$ export MW_HOME=/opt/oracle/Middleware
$ export WL_HOME=$MW_HOME/wlserver_10.3
$ export JAVA_HOME=/usr/java/jdk1.6.0_24
$ export PATH=$JAVA_HOME/bin:$PATH

$ cd $WL_HOME/server/lib
$ java -jar $MW_HOME/modules/com.bea.core.jarbuilder_1.6.0.1.jar

The jarbuild*.jar command creates the wlfullclient.jar file in the current working directory. The version of the jarbuild*.jar file may be different on your system. However, if required and desired you can download, modify, and execute this genjar.sh script using the following command in the directory in which the file was saved:

$ chmod +x genjar.sh
$ ./genjar.sh 

Note: The genjar.sh script locates the jarbuilder*.jar file and checks to see if the file is already present and if not it creates the wlfullclient.jar file in the appropriate located based on the values on the environment variables in the script. Therefore, if you use the supplied genjar.sh script, then please first make sure you alter the environment variables to suit your installation.

Files of the Supplied Example

The developing_oim_plug_ins.zip file contains the following JDeveloper files:

If you wish to compile the supplied code in JDeveloper, then you must add the following libraries in the supplied JDeveloper project Libraries and Classpath Project Properties:

Note: Using JDeveloper to compile the supplied sources is not performed in this tutorial because you use a supplied Ant build.xml file to compile and build the source files. This tutorial sets OIM_ORACLE_HOME to the /opt/oracle/Middleware/Oracle_IDM1 directory path.

Building and Deploying the Plug-ins

The basic tasks needed for developing and implementing plug-ins are:

As listed in the Files of the Supplied Example section above, the JDeveloper project contains the source code for the following three type of plug-in examples:

  1. The request status changed plug-in
  2. The kernel event handler plug-in
  3. The scheduled task plug-in

The JDeveloper project also contains an Ant build.xml file that automates the generation of the executable code and deployment of the plug-in code to their target environment as defined by associated XML files that declare the plug-in value mappings and metadata.

To build and deploy all three plug-ins, perform the following steps:

.

Open a Terminal window, and execute the following Bash shell commands to defined environment variables:

$ export OIM_ORACLE_HOME=/opt/oracle/Middleware/Oracle_IDM1
$ export WL_HOME=/opt/oracle/Middleware/wlserver_10.3
$ export ANT_HOME=/opt/oracle/Middleware/jdeveloper/ant
$ export JAVA_HOME=/usr/java/jdk1.6.0_24
$ export PATH=$ANT_HOME/bin:$JAVA_HOME/bin:$PATH

Note: Set the values of these environment variables to the paths that are appropriate for your installation environment. Replace the export commands with the appropriate command for the shell language you are using. Consider downloading and modifying this setenv-plugins.sh script (for Bash shell interpreter) and source the file to set these environment variables. Use the source command or "." command to execute the supplied script in the current shell context. For example:

$ source setenv-plugins.sh

.

In the Terminal window, execute the following commands to extract the contents of the developing_oim_plug_ins.zip file you downloaded into the oim_plug_ins subdirectory:

$ cd $HOME
$ unzip developing_oim_plug_ins.zip -d oim_plug_ins

Note: You can create the oim_plug_ins subdirectory in any location you choose.

.

Launch Oracle JDeveloper from the desktop (if you have desktop icon) or use the following command:

$ /opt/oracle/Middleware/jdeveloper/jdev/bin/jdev & 

Note: Change the path for the JDeveloper executable to match your environment.

.

In the JDeveloper window, click Open Application.

.

On the Open Application(s) dialog box, browse to the $HOME/oim_plug_ins directory (where $HOME is represented by the path /home/oracle), select the OIMPluginSamples.jws file and click Open:

Note: If you are using a newer version of Oracle JDeveloper to the one used to create the JDeveloper workspace and project file and its sources, then when the Open Warning dialog box is displayed, to migrate the files into the new format compatible with the version of Oracle JDeveloper being used, click Yes. When the Migration Status dialog box is displayed, click OK.

.

To edit the Ant properties for the project, in the JDeveloper Application tabbed panel, in the OIMPluginSamples workspace: expand the Plugin > Resources node, and right-click on build.xml and select Open:

.

In the Source tab of build.xml, search for and modify the following Ant properties to provide the Oracle Identity Manger 11g:

  • OIM.Username for the administration username of Oracle Identity Manager 11g instance that required for registering the plug-ins
  • ServerURL for the URL of the host and port of the Oracle WebLogic managed server containing the Oracle Identity Manager 11g instance
  • WL.ServerName for the Oracle WebLogic managed server name on which Oracle Identity Manager 11g is running. For example, oim_server1 (as shown in the image below)
  • WL.Username for administration username of the Oracle WebLogic server

For example, the properties entries should look similar to these (change the value attributes to match your environment):

<property name="OIM.Username" value="xelsysadm"/>
<property name="ServerURL" value="t3://localhost:14000"/>
<property name="WL.ServerName" value="oim_server1"/>
<property name="WL.Username" value="weblogic"/>

Note: Save the changes to the build.xml file by click File > Save, and optionally close Oracle JDeveloper by selecting File > Exit.

.

In a Terminal window, to build and deploy the plug-ins to Oracle Identity Manager 11g execute the following commands:

$ cd $HOME/oim_plug_ins/Plugin
$ ant register

The Ant register action requires that you enter the passwords for the xelsysadm and the weblogic administration usernames. For each of the password prompts enter: Welcome1 (which is not echoed to the screen) or whatever passwords you have used for those administrative usernames. The following images show examples of the results you may see:

and the rest of the output looks like this:

Note: The Ant register command, executes the commands needed to register the plug-ins and upload the necessary metadata files needed for the plug-ins.

.

To ensure the deployed plug-ins are activated, restart the Oracle Identity Manager server by performing the following commands in a Terminal window:

$ export MW_HOME=/opt/oracle/Middleware
$ cd $MW_HOME/user_projects/domains/base_domain/bin
$ ./stopManagedWebLogic.sh oim_server1

Note: The command line syntax shown is Borne shell syntax, please use equivalent commands for your shell or command line environment. If you executed the setenv-plugins.sh script provided earlier the MW_HOME environment variable should already be define (provided you are executing these command in the same Terminal window used to source the script)

Wait for the Oracle Identity Manager WebLogic Managed Server instance to be shutdown, and then execute the following command to restart it.

$ cd $MW_HOME/user_projects/domains/base_domain/bin
$ ./startManagedWebLogic.sh oim_server1 &

Note: Wait until the Oracle Identity Manager 11g server instance is running. Remember to replace the usages of MW_HOME, base_domain, and oim_server1 with path or instance names that match your installation.

If you wish to remove the plug-ins from Oracle Identity Manager 11g environment, in a Terminal window you can execute the following commands:

$ cd $HOME/oim_plug_ins/Plugin
$ ant unregister

Note: You may wish to try the tests in the section titled Test Plug-in Functionality before you remove the plug-in examples. Remember to restart the Oracle Identity Manager 11g server instance after running the ant unregister command, which removes the plug-ins and the respective metadata files that were uploaded when executing the Ant register command. The output from the ant unregister command should be similar to the following image:

Test Plug-in Functionality

In this section, you use the Oracle Identity Manager 11g Administration console to initiate the actions performed by the plug-ins deployed in the previous section, and monitor the log messages written to the Oracle Identity Manager 11g command line console window to observe when the plug-ins are invoked.

Important Note: To view the messages produced by each plug-in deployed in the previous section, you should have started the Oracle Identity Manager 11g managed WebLogic Server instance in a terminal window so that you can see any messages written to the command line console window (as performed in the last step of the previous section).

Testing the Request Status Changed Plug-in

The request status changed plug-in is implemented by creating a Java class that implements the oracle.iam.request.plugins.StatusChangeEvent interface, requiring the followUpActions() method to be implemented. The following is the sample Java class implementation deployed for this plug-in.

package oracle.iam.sample.plugin;

import oracle.iam.request.plugins.StatusChangeEvent;

public class RequestFailedChangeEvent implements StatusChangeEvent {
  public void followUpActions(String reqId) {
    // Display a message when a request' status changes to "Request Failed"
    System.err.println("Request " + reqId + " failed.");
  }
}

The plug-in prints the message "Request <ReqId> failed." to the terminal window running the Oracle Identity Manager 11g managed server instance, where <ReqId> is replaced by the ID value of the request created. The following XML <plugins> elements added to the plugins.xml file used to ensure that the named class can be registered with the Oracle Identity Manager 11g plug-in framework when the plug-in code is deployed:

<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <plugins pluginpoint="oracle.iam.request.plugins.StatusChangeEvent">
    <plugin pluginclass="oracle.iam.sample.plugin.RequestFailedChangeEvent" 
     version="1.0" name="RequestFailedChangeEvent">
      <metadata name="status">
        <value>Request Failed</value>
      </metadata>
    </plugin>
  </plugins>
  :
</oimplugins>

To do test when the request status changed plug-in is activated, perform the following steps:

.

Because many requests, such as the Assign Roles request, is processed by sending the request to the SOA server, to created the "Request Failed" status condition for the plug-in message to be displayed in the Terminal console window of the Oracle Identity Manager managed WebLogic Server instance, in a separate Terminal window execute the following command to stop the SOA server instance:

$ export MW_HOME=/opt/oracle/Middleware
$ cd $MW_HOME/user_projects/domains/base_domain/bin
$ ./stopManagedWebLogic.sh soa_server1 

Wait for the SOA Server to be terminated.

.

in a Web browser enter the URL, such as http://localhost:14000/oim, to access the Oracle Identity Manager 11g administration console page.

On the Oracle Identity Manager 11g Sign In page, enter the Username xelsysadm and Password Welcome1, and click Sign In.

Note: Substitute the password with the one you assigned to the xelsysadm user in your environment.

.

On the Oracle Identity Manager - Self Service > Welcome > Dashboard tabbed page, in the Requests section click Create Request.

.

On the Requests > Create Request tabbed page, for the Select Request Beneficiary step select the Request for Others option, and click Next.

.

On the Requests > Create Request tabbed page, for the Select Request Template step, select Assign Roles from the Request Template drop-down box, and click Next.

.

On the Requests > Create Request tabbed page, for the Select Users step, click Search to populate the Available Users field, select a user such as weblogic (you can choose any user you feel is appropriate) and then click the single arrow icon (between the Available Users and Selected Users fields) to move the selection from the Available Users into the Selected Users field, and finally click Next.

.

On the Requests > Create Request tabbed page, for the Select Roles step, click Search to populate the Available Roles field, select a role such as SYSTEM CONFIGURATION ADMINISTRATORS (you can choose any role you feel is appropriate) and then click the single arrow icon (between the Available Roles and Selected Roles fields) to move the selection from the Available Roles into the Selected Roles field, and finally click Next.

.

On the Requests > Create Request tabbed page, for the Enter Justification step, click Finish.

Note: The fields for the Enter Justification step are optional. When you click Finish the Request tabbed page is updated to display the Request ID for the new request submitted.

.

On the Requests > Create Request tabbed page, take note of the Request ID value (for example 64 in this example), and click the My Requests tab.

.

On the Requests > My Requests tabbed page, click Search, if required scroll down to the last entry in the table to find the row with Request ID for the last submitted request (for example Request ID 64), and verify that the Status column contains the value Request Failed .

Note: Alternatively, before you click Search enter the Request ID value obtained from the previous step to find the specific Request ID.

.

Return to the Terminal window, in which the Oracle Identity Manager 11g managed WebLogic Server instance is running, and verify that the plug-in message "Request 64 failed" (substitute the value 64 in this example with the Request ID you observed when you submitted the request).

Note: The log messages displayed before the plug-in request failed message indicate that the Status Change plug-in is initiated prior to seeing the log message displayed by the custom plug-in.

.

In the Terminal window that was used to stop the SOA server instance, restart the SOA Server by executing the following commands:

$ export MW_HOME=/opt/oracle/Middleware
$ cd $MW_HOME/user_projects/domains/base_domain/bin
$ ./startManagedWebLogic.sh soa_server1 &

Wait for the SOA Server to be started.

Testing the Kernel Event Handler Plug-in

The kernel event handler plug-in is implemented by creating a Java class that implements the oracle.iam.platform.kernel.spi.FinalizationHandler interface and its required methods. The following is the sample Java class implementation deployed for this plug-in.

package oracle.iam.sample.eventhandler;

import java.util.HashMap;

import oracle.iam.platform.kernel.spi.FinalizationHandler;
import oracle.iam.platform.kernel.vo.BulkOrchestration;
import oracle.iam.platform.kernel.vo.Orchestration;

public class MyUserCreateFinalizationHandler implements FinalizationHandler {
   public void finalize(long processId, long eventId, Orchestration orchestration) {
     // Display a message during the finalization stage of a create user operation
     System.out.println("Finalizing a create user orchestration process with process ID: " + processId);
   }

  public void finalize(long processId, long eventId, BulkOrchestration bulkOrchestration) {
   // Display a message during the finalization stage of a create user operation
   System.out.println("Finalizing a create user bulk orchestration process with process ID: " + processId);
   }

  public void initialize(HashMap<String, String> parameters) {
  }
}

To test the above plug-in, simply create a new user and at the completion phase of the creation process the message "Finalizing a create user orchestration process ID: <processId>" should appear in the terminal window used to run the Oracle Identity Manager 11g managed server instance. The following XML elements are added to the plugins.xml file so that the class can be registered with the Oracle Identity Manager 11g plug-in framework when the plug-in code is deployed:

<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 :
 <plugins pluginpoint="oracle.iam.platform.kernel.spi.EventHandler">
   <plugin pluginclass="oracle.iam.sample.eventhandler.MyUserCreateFinalizationHandler"
version="1.0" name="MyUserCreateFinalizationHandler"/> </plugins>
: </oimplugins>

In the XML elements the pluginpoint describes where the plug-in is connected and the pluginclass specifies the fully qualified class name of the Java class that implements the logic for the plug-in. The event handler is configured with the following metadata found in the EventHandlers.xml file in the supplied JDeveloper project:

<?xml version="1.0" encoding="UTF-8"?>
  <eventhandlers xmlns="http://www.oracle.com/schema/oim/platform/kernel"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.oracle.com/schema/oim/platform/kernel orchestration-handlers.xsd">
  <finalization-handler class="oracle.iam.sample.eventhandler.MyUserCreateFinalizationHandler" 
   entity-type="User" operation="CREATE" name="MyUserCreateFinalizationHandler" order="1234"/>
 </eventhandlers>

Note: The XML namespaces used in the XML file for the plug-in metadata was updated for the Oracle Identity Manager 11g 11.1.1.5.0 release. The metadata content is loaded into the Oracle Identity Manager 11g runtime environment by executing the weblogicImportMetadata.py WebLogic Script Language (WLST) script in the register task action of the Ant build.xml file.

To do test when the kernel event handler plug-in is activated, perform the following steps:

.

If you are not already logged into the Oracle Identity Manager 11g administration console page, in a Web browser enter the URL, such as http://localhost:14000/oim. On the Oracle Identity Manager 11g Sign In page, enter the Username xelsysadm and Password Welcome1, and click Sign In.

Note: Replace the hostname and port in the URL to correspond with your environment, and supply the password you chose for the xelsysadm user.

.

If after signing into Oracle Identity Manager 11g administration console you see the Oracle Identity Manager - Self Service page, click the Administration link.


.

On the Administration > Welcome tabbed page, click Create User.

.

On the Administration > Create User tabbed page, enter or select any values in the required fields for Last Name, Organization, and User Type, and click Save. The example shows the use of the following fields and values:

  • First Name (optional): Samuel
  • Last Name: Stokol
  • Organization: Requests (which is selected from the search dialog box opened when you click the search icon to the right of this field)
  • User Type: Full-Time Employee (selected from the field drop-down box)


.

On the Administration > Samuel Stokol tabbed page (or the tab with the name of the user you created), verify that the message "The User has been created successfully." is displayed.

.

In the Terminal window running the Oracle Identity Manager 11g managed WebLogic Server instance, verify that you can see the log message "Finalizing a create user orchestration process with process ID: 368" appears, where the process ID value 368 is likely to be different on your machine.

Note: If you see the "Finalizing..." log message in the console Terminal window then you have successfully tested the deployed and implemented the kernel event handler plug-in.

Testing the Scheduled Task Plug-in

The scheduled task plug-in is implemented by creating a Java class that implements the oracle.iam.scheduler.vo.TaskSupport interface. The following is the sample Java class implementation deployed for this plug-in.

package oracle.iam.sample.scheduledtask;
  
import java.util.HashMap;
import oracle.iam.scheduler.vo.TaskSupport;

public class SampleScheduledTask extends TaskSupport {
  public void execute(HashMap hashMap) throws Exception {
    // Display a message when this scheduled task is run
    System.out.println("Running the OIM Sample Scheduled Task...");
  }
  
  public HashMap getAttributes() {
    return null;
  }
  
  public void setAttributes() {
  }
}

The following XML elements are inserted into the plugins.xml file so that the class can be registered with the Oracle Identity Manager 11g plugin framework when the plug-in code is deployed:

<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  :
  <plugins pluginpoint="oracle.iam.scheduler.vo.TaskSupport">
    <plugin pluginclass="oracle.iam.sample.scheduledtask.SampleScheduledTask" 
     version="1.0" name="SampleScheduledTask"/>
  </plugins>
</oimplugins>

In addition, the scheduled task is configured with the following XML metadata (located in the OIMSampleScheduledTask.xml file in the JDeveloper project) that is imported into the Oracle Identity Manager 11g runtime environment when the Ant build.xml script executes the the weblogicImportMetadata.py WLST script as part of the register task :

<?xml version="1.0" encoding="UTF-8"?>
<scheduledTasks xmlns="http://xmlns.oracle.com/oim/scheduler">
  <task>
    <name>OIMSampleScheduledTask</name>
    <class>oracle.iam.sample.scheduledtask.SampleScheduledTask</class>
    <description>OIM Sample Scheduled Task</description>
    <retry>5</retry>
  </task>
</scheduledTasks>

To do test when the scheduled task plug-in is activated, perform the following steps:

.

If you are not already logged into the Oracle Identity Manager 11g administration console page, in a Web browser enter the URL, such as http://localhost:14000/oim. On the Oracle Identity Manager 11g Sign In page, enter the Username xelsysadm and Password Welcome1, and click Sign In.

Note: Replace the hostname and port in the URL to correspond with your environment, and supply the password you chose for the xelsysadm user.

.

After signing in, on the Oracle Identity Manager - Self Service page, click the Advanced link.


.

On the Oracle Identity Manager - Advanced Administration page, click the System Management tab.


.

On the Oracle Identity Manager - Advanced Administration > System Management tabbed page, to create a new scheduled task click the icon in the Scheduler section under the Search Scheduled Jobs field:


.

On the Oracle Identity Manager - Advanced Administration > System Management > Create Job tabbed page, enter the following field values and then click Save and Run Now:

  • Job Name: Test
  • Task: Click the search icon and select the OIMSampleScheduledTask entry. Refer to the note below the following image for more information.
  • Start Date: Select the current date and time and make add five more minutes to the time.
  • Retries: 1
  • Schedule Type: Single

Note: To populate the Task field, click the search icon next to the Task field to display the Search and Select: Scheduled Task dialog box, in which you first perform the following steps to select the OIMSampleScheduledTask entry:

  • Click the arrow icon to the right of the Search field.
  • Scroll down the list of Schedule Task entries, select OIMSampleScheduledTask and click Confirm.

.

On the Oracle Identity Manager - Advanced Administration > System Management > Create Job tabbed page, after clicking Save and Run Now verify that you get a confirmation message with the text "Successfully created and triggered the job".


.

Return to the Terminal window running the Oracle Identity Manager 11g managed WebLogic Server instance, and verify that the log displays the scheduled task code message text "Running the OIM Sample Scheduled Task..."


Note: You have now completed all the tests that verify each of the three plug-in classes deployed in your Oracle Identity Manager 11g environment are working.

Summary

This tutorial has guided you through the steps to edit a build.xml file, with in Oracle JDeveloper or your preferred editor, to modify properties in the build.xml file provided with the Java source code used to create Oracle Identity Manager 11g plug-ins. You run the Ant command using the modified build.xml file to deploy the plug-in functionality.

In this tutorial, you have learned how to:

Resources

Credits (Optional)

Hardware and Software Engineered to Work Together Copyright © 2011, Oracle and/or its affiliates. All rights reserved