Friday Feb 14, 2014

Managing BPM Roles through API

Oracle BPM 11g works with Application Roles as part of the possible assignees that can be used for the Human Tasks. The Application stripe used is OracleBPMProcessRolesApp, deployed by default along with the product.

There are at least two ways to manage those Application Roles (from now on, "BPM Roles") and the membership of each one. The most common one is through Oracle BPM Workspace application. An administrator user (e.g. weblogic) can click on the "Administration" task and then go to the "Roles" Administration Area.

You can also use the Fusion Middleware Control for managing the BPM Roles and membership. Again, as an admin user, open the "Applications Deployments" folder, search for the OracleBPMProcessRolesApp application, right click on it and go to "Security/Application Roles" menu. From there, click the "run" icon to perform the search. You can now create or edit an existing role.

These two methods are OK when you want a UI and need to perform just a few changes on the roles. However it's not very friendly when you need to do some bulk operations. Also, if you need to backup the existing BPM Roles setup or to restore it, or do a "test-2-production" operation, these consoles are useless.

There is a "test-2-production" ant script provided by Oracle SOA/BPM Suites named ant-t2p-worklist.xml and can be located under the $SOA_HOME/bin folder. Such script is well documented here. However I don't see that such script manages the "BPM Roles". 

Of course, Oracle BPM provides a full Java API to manage all these artifacts. The main interface to use is IBPMOrganizationService that is fully documented here.

Recently I had the need to replicate an environment and I didn't want to lose all the BPM Roles and membership. So after double checking my alternatives, I decided to go with the API alternative.

I then found a very interesting sample posted by David Read from Oracle Product Management organization, one of the best gurus you can find for Oracle BPM :-)

Based on that code I wrote a simple Java class to perform the following operations with the BPM Roles:

  • Export and Import the current BPM Roles organization to/from a single XML file
  • Delete one or multiple BPM Roles at once
  • Delete ALL existing BPM Roles (but the readonly one BPMProcessAdmin)

I have uploaded the complete source code and compiled JAR file to site. You can download it from here.

The ZIP file contains also a sample .sh file to execute the class, including the CLASSPATH needed to run it.

It's been developed and tested with Oracle BPM (PS6 release), although it should work with previous and future 11g releases.

From an API point of view, these are the key methods to use:

- Get connected to the server and obtain the context (connection details and credentials are previously set in a separate method):

BPMServiceClientFactory factory = getBpmServiceClientFactory();
IBPMServiceClient bpmSvcClient = factory.getBPMServiceClient();
IBPMOrganizationService bpmOrgSvc = bpmSvcClient.getBPMOrganizationService();
IBPMContext bpmCtx = (IBPMContext)factory.getWorkflowServiceClient().getTaskQueryService().authenticate(null, null, null);

- Export or Import the whole BPM organization (which includes Calendars, Roles, Organizational Units, etc):

Organization o = bpmOrgSvc.exportOrganization(bpmCtx); 

- I'm just interested in the Application Roles and their members:

ApplicationRoles ar = o.getApplicationRoles();
List<ApplicationRoleType> roleList = ar.getApplicationRole();
for (ApplicationRoleType role : roleList) {
    List<PrincipleRefType> memberList = role.getMember();
    for ( PrincipleRefType member : memberList) {

- The main operations: Create, Remove and Add or Remove members to them:

ApplicationContext appContext = new ApplicationContext();
bpmOrgSvc.createAppRole(bpmCtx, appContext, "MyRole", null, null);
AppRoleRefType r = new AppRoleRefType(); 
r.setType(ParticipantTypeEnum.USER); // For example, a participant of type USER
r.setName("jcooper"); // Our beloved James Cooper ;-) (warning, user/group/role must exist. If not you'll get an exception)
bpmOrgSvc.grantAppRoleToPrincipal(bpmCtx, appContext, "MyRole", new Participant(r));
bpmOrgSvc.removeAppRole(bpmCtx, appContext, "MyRole", true); // "true" to force the deletion

The export/import XML file used is based on an XSD contained in the JAR file. Feel free to unzip it and have a look. The JAR file also contains a sample XML file for import testing.

BTW, do not expect a good Java code. But it seems to work at least! :-)


Technical and in-depth articles and samples on BPM 11g.


« February 2014 »