Creating custom scheduled task for OIM 11.1.1.7

In this blog post, I'm going to demonstrate something that I learned recently during my OIM POC. It's called a custom scheduled task.

OIM or Oracle Identity Manager has several scheduled tasks that you can configure as jobs and make them trigger at specified intervals. However, you also get to write your own scheduled task and schedule that as a job.

So, let's get started.

For this tutorial kinda blog post, I'm using Fusion Middleware version 11.1.1.7.

Steps: 

1. Export task.xml file from MDS
2. Modify task.xml file
3. Import task.xml file into MDS
4. Write the plugin code
5. Package the plugin code
6. Register the plugin code using plugin utility
7. Schedule a job in OIM admin console
8. Trigger the job to see it work.

 Before you do any of these, please remember to do this:

Get to the {weblogic_home}/server/lib directory and execute this command:

java -jar wljarbuilder.jar

1)Export task.xml file from MDS

There are two ways we can add a custom schedule task in OIM. a) write our own xml file. b) modify the existing task.xml file and import it.

In this tutorial we're going to follow route (b).

To do this, open a shell prompt and get to this location /u01/app/oracle/Middleware_11.1.1.7/Oracle_IDM1/server/bin. This could be different as per your installation. In short, you need to get to ORACLE_HOME for IDM installation. Open the file weblogic.properties in a text editor and modify these(text in parenthesis are not to be typed in):

 wls_servername=oim_server1 (oim server instance name)

 application_name=OIMMetadata (this needs to be OIMMetadata for this purpose)

 metadata_from_loc=/u01/app/oracle/Middleware_11.1.1.7/MDS_LOC (where you want the task.xml file to be exported)

 metadata_to_loc=/u01/app/oracle/Middleware_11.1.1.7/MDS_LOC (this is where task.xml will be imported from, after modification)

 metadata_files=/db/task.xml (what metadata you want to export/import. /db/task.xml for us)

Save this file. Set OIM_ORACLE_HOME variable to point to IDM installation directory (e.g., /u01/app/oracle/Middleware_11.1.1.7/Oracle_IDM1).

Now execute this command  ./weblogicExportMetadata.sh . If all goes well, you'll have the task.xml file in the location you specified in the properties file.

2) Modify task.xml file

 Open the exported task.xml file in a text editor. You'll find that it has a lot of <task> tag. These represent each schedule task. We need to put our task definition in the same manner.

So add a task blog like this(don't use text within parentheses):

<task>

<name>Dummy Task</name> (task name)

<class>com.test.ScheduledTask</class> (the class name which is going to be invoked by the scheduler)

<description>Dummy Task to run as scheduled job </description> (a description for better understanding)

<retry>5</retry> (default retry count)

<parameters>

<string-param required="true" helpText="Dummy data param">Dummy Data</string-param> (this goes to the class as a Map with the value(Dummy Data) as key)

</parameters>

</task>

 Save the file.

 3)Import task.xml file into MDS

 Now, at a shell prompt, navigate to /u01/app/oracle/Middleware_11.1.1.7/Oracle_IDM1/server/bin, if you're not already there.

Execute the command: ./weblogicImportMetadata.sh. If all goes well, you'll get a confirmation that task.xml was imported to MDS successfully. 

 4)Write the plugin code

The java code for the custom scheduled task can be uploaded to OIM either through Upload Jar Utility or through plugin utility. In this tutorial we will see how we can import it as a plugin through plugin utility.

Open your favorite Java editor and start up a java project. You need to have /u01/app/oracle/Middleware_11.1.1.7/Oracle_IDM1/server/client/oimclient.jar in classpath.

This location could be different for your installation.

Now create a class  ScheduledTask in a package com.test. Remember that is exactly what we provided in the task.xml file.

Make this class extend oracle.iam.scheduler.vo.TaskSupport . This class is available in oimclient.jar.

Override the method public void execute(HashMap arg0) throws Exception in your class. 

For testing you can add a line like this: System.out.println( "Job sent: " + arg0.get("Dummy Data")); It will print the parameter passed to the job when it is triggered.

5) Package the Plugin Code

Create a file named plugin.xml and type in the following in it (don't type in things within parentheses):

<?xml version="1.0" encoding="UTF-8"?>

<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<plugins pluginpoint="oracle.iam.scheduler.vo.TaskSupport">

<plugin pluginclass= "com.test.ScheduledTask"

version="1.0.1" name="scheduler element"> (class name must be exactly the same one specified in task.xml)

</plugin>

</plugins>

</oimplugins>

 Make a jar of your java project and put it in a folder calld lib. 

So your directory structure should look like this. The jar should be inside the lib folder:

Now make a zip of it. And remember to keep it flat, i.e., DO NOT put the lib folder and plugin.xml file inside any directory.

 6) Register the plugin code using plugin utility

Open the  /u01/app/oracle/Middleware_11.1.1.7/Oracle_IDM1/server/plugin_utility/ant.properties file in a text editor. Your location may vary.

Modify these two lines:

wls.home=/u01/app/oracle/Middleware_11.1.1.7/wlserver_10.3

oim.home=/u01/app/oracle/Middleware_11.1.1.7/Oracle_IDM1/server

wls.home is your weblogic installation directory. oim.home is your oim installation directory suffixed with the server sub directory.

Save this file.

In a shell prompt, navigate to this location: /u01/app/oracle/Middleware_11.1.1.7/Oracle_IDM1/server/plugin_utility. Your plugin_utility location may vary. Set ANT_HOME and JAVA_HOME properly.

Now execute the command ant -f pluginregistration.xml register

This command will ask for four different information from you.

a) OIM admin login id. By default it is xelsysadm . 

b) Password for OIM admin login. 

c) OIM url. e.g., t3://myhost:14000 

d) Fully qualified path to the zip file containing the plugin.

Once you've provided all these info, if all goes well, the tool would register the plugin.

 7) Schedule a job in OIM admin console

Open Oim admin console in a web browser. e.g., http://myhost:14000/oim

Provide admin id and password to login.

Click on the Advanced link at the top right corner:

Click on System Management -> Schedule. Then from the Actions list, select Create:

Now, in the main screen choose a task. When choosing, you can use wildcard like *.  

Search for Dummy Task.

Fill up the remaining fields. You can choose any period like every 5 minutes or every hour etc. For testing, choose No pre-defined schedule then put some value against the parameter Dummy Data.

8) Trigger the job to see it work

Now on the same screen hit Save and Run Now.

If all goes well, you'll see Job Sent: Dummy Data printed in the oim console output. You can check oim managed server log for this as well.

If you're referring to any other jar from the plugin code, please make sure to keep that jar inside the lib folder within the OIM domain folder.

I hope you'll find this tutorial helpful. Please share your feedback in the comments section.

Detailed read:

MDS related document: http://docs.oracle.com/cd/E14571_01/doc.1111/e14309/utils.htm#BEIHDGCD

Plugin development document: http://docs.oracle.com/cd/E14571_01/doc.1111/e14309/plugins.htm#CJAJIABF

Using Upload Jar utility: http://docs.oracle.com/cd/E14571_01/doc.1111/e14309/uploadutil.htm#OMDEV3206