Developing Workflows to OIM 11g - the basics

OIM & BPEL Working together? 

OIM 11g release brought us the powerful world of Oracle BPEL based workflows: from this release on, Oracle BPEL is the workflow engine to be used by OIM in all sorts of requests and their related approval processes. While this integration makes OIM workflows way more powerful and flexible when compared to OIM 9.x, the development process is quite different. The idea for this article is to provide tips for making the development process more straightforward.

First let’s take a look in the main development steps for having a new workflow:
1. Generating basic workflow: OIM provides an utility that can be used to generate a JDeveloper project that contains a basic BPEL Workflow process:

‘ant -f new_project.xml -f new_project.xml’

The ‘new_project.xml’ is located at $OIM_HOME/server/workflows/new-workflow.

You have to provide the application name (which will become the JDeveloper Applciation Name), the project name (which will become the JDeveloper project in the application) and the process name (which needs to be unique across applications and will be the BPEL process name).

The command line will generate a JDeveloper application and you can copy it to wherever your JDeveloper is installed and start working on your customizations.


2. Customizing the workflow: using JDeveloper you can customize the workflow generated in the previous steps and code the logic to achieve your business requirements.

This is the step where you do all your customizations in the BPEL workflow. You can use OIM APIs to get information back from OIM, you can make external calls to legacy systems to verify data, you can easily integrate with existing WebServices, and you can pretty much do whatever is needed to achieve your business requirements.

3. Deploying the workflow: once the customization is done, it is time to deploy the workflow to Oracle BPEL engine. You can do this in two different ways:

• Directly from JDeveloper: you have to create a WebLogic connection in JDeveloper.

• Using a command line:
  
  ‘ant -f ant-sca-deploy.xml’
  
  This script is located at $SOA_HOME/bin.
  
  You will have to provide SOA Server connectivity information (username, password and URL) and also the path to the ‘.sar’ file. The ‘.sar’ file is generated by JDelevoper when you deploy the workflow to a file.

4. Registering the workflow: after the deployment to the SOA Server, the BPEL process must be registered in OIM. There is another script to accomplish this task:

‘ant -f registerworkflows-mp.xml’

This script is located at $OIM_HOME/server/workflows/registration

You will have to provide OIM connectivity information (URL, administrator username and password),  and also a path to a properties files you must create. The properties file must contain the BPEL workflow process information like category, domain, version and others.

What now? Are you done with the development cycle? 

Probably not, in most cases, it is necessary to make changes to the BPEL workflow to either fix bugs or make corrections. And there is a sequence of steps for that:

1. Make the changes in JDeveloper
2. Disable the workflow process in OIM
3. Re-deploy the workflow to SOA Server
4. Enable the workflow in OIM

To accomplish these steps, you have to use the same scripts you used in steps 3 and 4 from when you first deployed your workflow.

Ok, now finally to the point!

You probably noticed the number of scripts and the number of times you will have to run them when developing BPEL workflows to OIM. So to make the development process easier, I created some scripts to run OIM scripts. Scripting scripts is a good approach to lower the number of parameters you have to provide:  instead of typing the same parameters every time you run the script, you just provide the ones that make the difference. The scripts below are for Linux platforms, but they can be easily translated to other Unix-like platforms and also to Windows.

First we need to set all the environment variables we need in one script (substitute the values between ‘<>’ by the values from your environment):

middleware.env - this script will be sourced in the other ones

export MIDDLEWARE_HOME=<middleware_home> export ANT_HOME=$MIDDLEWARE_HOME/modules/org.apache.ant_1.7.1 export JAVA_HOME=<PATH_TO_JDK> export PATH=$ANT_HOME/bin:$PATH export SOA_HOME=$MIDDLEWARE_HOME/<soa_folder> export OIM_HOME=$MIDDLEWARE_HOME/<iam_home> export WL_USER=<weblogic> export OIM_USER=<xelsysadm> export OIM_URL=t3://<hostname>:<port> export SOA_URL=http://<hostname>:<port>

Then we can use it in the ones that will actually do the work:

deployWorkflow.sh - deploys the workflow process to the BPEL server. To run this one all you have to provide is the WebLogic admin password and full path to the ‘.sar’ file.

#!/bin/sh . ./middleware.env cd $SOA_HOME/bin ant -f ant-sca-deploy.xml -DserverURL=$SOA_URL -Duser=$WL_USER -Dpassword=$1 -Doverwrite=true -DsarLocation=$2

disableWorkflow.sh - disables the workflow in OIM. You have to provide the OIM administrator password and the workflow process name.

#!/bin/sh . ./middleware.env cd $OIM_HOME/server/workflows/registration ant -f registerworkflows-mp.xml -DserverURL=$OIM_URL -Dusername=$OIM_USER -Dpassword=$1 -Dname=$2 -Ddomain=default -Dversion=1.0 disable

enableWorkflow.sh - enables the workflow in OIM. You have to provide the OIM administrator password and the workflow process name.

#!/bin/sh . ./middleware.env cd $OIM_HOME/server/workflows/registration ant -f registerworkflows-mp.xml -DserverURL=$OIM_URL -Dusername=$OIM_USER -Dpassword=$1 -Dname=$2 -Ddomain=default -Dversion=1.0 enable

Collateral Information

Product documentation will always be the primary source of information. You can find more information about how to work with OIM and BPEL at:

Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager

Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite