Introduction

This tries to explain the import/export process for registering plug-in, schedulers, request datasets, etc.

The intended audience for this experiment is experienced OIM 9.x developers who are learning OIM 11.x.

The Setup

I am using

Component	Version
Operating System	Windows 2003 R2 (Enterprise x64 Edition)
Application Server	Weblogic 10.3.5
Database Server	Oracle 11gR2
OIM	11.1.1.5.0

Plug-ins

OIM 9.x had everything available from the design console when it came to developing workflows. But with OIM 11g a plug-in framework has been introduced. In OIM 9.x we had entity adapters to do this job, but now this plug-in framework is to supersede that. This plug-in framework allows us to register items that would be called at different stages of the processes like creation of user or an update of user. In OIM 9.x we did these operations using entity adapters, but now these adapters have been replaced by OIM plug-ins.

Meta Data

OIM 11g introduces a concept of metadata repository for components like schedulers, plug-ins, etc. A component like a scheduler would have a name, a set of parameters that it needs. All this is defined in XML (metadata) and needs to be uploaded into OIM’s metadata repository.

Creating a Plug-in

This has two steps:

1. Register your plug-in class

2. Upload metadata for this plug-in

Plug-in Structure

A plug-in composed of the following elements

1. plugin.xml

2. lib/plugin-name.jar

3. resources/something.properties

The resources folder is optional and is not always required.

Registration

OIM can hold the plug-in code in the database or on file system. The default plug-in folder is the plugins folder inside server. To load data into the OIM database, we have some script provided by OIM that will help us load those items.

How to Create a Plug-in

Creating plug-in may look cumbersome when you start off, but after a while it will be like second nature to you. Here are the steps:

1. Create the plug-in class

This is the most important step. After all you want to do something with this plug-in. The plug-in class needs to extend a plugin-point class. Some of the classes that you can extend are

Interface Class

oracle.iam.platform.kernel.spi.ActionHandler

oracle.iam.platform.kernel.spi.PreProcessHandler

oracle.iam.platform.kernel.spi.PostProcessHandler

oracle.iam.platform.kernel.spi.AuditHandler

oracle.iam.platform.kernel.spi.CancelledHandler

oracle.iam.platform.kernel.spi.CompensateHandler

oracle.iam.platform.kernel.spi.InvalidHandler

oracle.iam.platform.kernel.spi.ValidationHandler

oracle.iam.platform.kernel.spi.EntityPreviewer

oracle.iam.platform.kernel.spi.FailedHandler

oracle.iam.platform.kernel.spi.VetoHandler

Each of these classes will have some methods that are specific to the area where it will be used. For example, if it is a PreProcessHandler, you need to implement execute(), compensate() and cancel() method.

2. Create the plugin.xml

The plug-in xml is fairly same for all the above cases. It is structured as:

<plugin

pluginclass="oim.helloworld.plugin.user.CreateUserPreHandler"

version="1.0" name="CreateUserPreHandler" />

</plugins>

</oimplugins>

The pluginpoint will vary based on what item you are developing the plugin for.

3. Creating the jar

Code created for the plug-in needs to be bundled in a jar file.

4. Create the zip

OIM expects a zip file for the registration process. The structure is same as mentioned before. Inside the zip you should have plugin.xml and the lib folder always. The lib folder will contain the jar file

5. Use the registration script

Now that we have the zip file ready with us, navigate to the plugin_utility folder. This folder is located inside the OIM_HOME/server folder.

Edit the ant.properties file to set wls.home and oim.home. Example:

Run the following command

ant –f pluginregistration.xml register

The script will ask for oim username and password and the weblogic url which would be something like t3://localhost:14000. After this it will ask for the path of the zip bundle. While entering the path use forward slashes instead of backslashes if you are on windows. Example:

C:/tmp/plugin-helloworld.zip

Being Conventional

When I started developing plug-ins it took me at least a zillion tries before I got it working, but that surely does not mean that you would take the same time. Below are some items that I keep in mind while creating plug-ins:

1. One Plug-in Only

The plug-in xml allows us to put in multiple items together as a single XML. However I always register them as separate items. So if I have two items to register, I do them as two separate bundles.

2. Plug-in XML Naming convention

While creating the plug-in we have to give a name to the plug-in (name attribute in the plug-in tag). The name of the plug-in is always the class name of the plug-in class. Example:

<plugin pluginclass="oim.helloworld.plugin.user.CreateUserPreHandler"

version="1.0" name="CreateUserPreHandler" />

3. Plug-in JAR Naming convention

All the code that we create for a plug-in goes into the lib folder. In all the plug-ins, the name of the jar file is the name of the plugin zip. Example:

If these are the plug-in contents:

lib/helloworld.jar

plugin.xml

The zip bundle to be used for registering this plug-in would be helloworld.zip

4. XML Tags

Do have the XML header tag, something similar to

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

as the first line of your XML.

I use these rules when I create any plug-in, but these are not hard rules. You may have your own set of conventions, which may be quite different.

Creating MetaData

Now that we know how to create a plug-in and register it, we have to tell OIM how to use this plug-in. This process is again a XML based representation of the details. (Why do they have so many XMLs!)

MetaData Structure

The metadata is composed of one or more XML files. However as opposed to the plug-in registration, importing of these XMLs does not always work as expected if we import them at the wrong location. We will see more on this later.

Registration

Registration of metadata is similar to the plug-in registration process. Here are the steps:

1. Build the metadata XML

The metadata xml is specific to the item that is being registered. Example:

PreProcess Event Handler Metadata XML

Scheduler Metadata XML

Always use the same name as defined in the plug-in.

2. Configure weblogic.properties

This file is located in the server/bin directory. This contains information on where to look for metadata files. Configure the following items:

a. wls_servername

wls_servername is the weblogic servername where OIM is running. Example: oim_server1

b. application_name

application_name is the metadata that we need to import to. Set this to OIMMetadata

c. metadata_from_loc

metadata_from_loc is the directory from where it will pick up the metadata files

3. Put your metadata files in the import folder

The files that you want to import must be put in the metadata_from_loc folder which we configured in the last step.

However the xml needs to structured in a specific folder structure.

For schedulers, the structure should be something like /db/{SchedulerName}.xml

For plug-ins, the structure should be something like /metadata/abccorp/user/create/{PluginName}/EventHandlers.xml

For details on this refer the relevant documentation section in OIM.

4. Run the weblogicImportMetadata.sh or weblogicImportMetadata.bat (Linux/Windows)

During this process you will see a Transfer complete message in the OIM logs like this:

5. Run the PurgeCache.sh or PurgeCache.bat

6. Some items work directly after this like schedulers, but some require the OIM server to be restarted like pre-process plug-ins. Restart the server appropriately after this.

Being Conventional

The plug-in registration was almost painless, compared to the metadata registration. It took me more time to get this working, compared to the plugin registration process. Along the way, I made some rules to create metadata xmls and importing them. These conventions are:

1. One MetaData XML Import

If I have multiple XMLs to import, I separate them into separate batches. One XML was used in one import.

2. Directory naming convention

If I am creating a pre-process/post-process handler or related plug-in I used the following structure

/metadata/{projectORcompanyname}/{entity:user or resource,etc}/{operation}/{plugin-name}/EventHandlers.xml

Example: For a preprocess handler for create operation on resource MyApp it would be

/metadata/projectx/myapp/create/CreatePreHandler/EventHandlers.xml

Here when I registered the plug-in the plug-in name was CreatePreHandler

Dumping the MetaData

All the metadata XMLs that we imported can be easily retrieved back from OIM. We can utilize the weblogic scripting tool or wlst to export all the metadata xmls.

Here is how we can export all the metadata that OIM has: