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! :-)

Thursday Jan 03, 2013

Searching BPM tasks by payload content: Flex Fields (Mapped Attributes)

Currently in Oracle BPM version 11gR1, the Workflow Services Java API does not allow to perform searches of BPM tasks by its payload content. This post describes the procesdure to enable this by using Flex Fields.

[Read More]

Thursday Apr 12, 2012

List all BPM Processes for a user


Happy to start contributing to this blog.. 

The title of the blog is probably deceptively simple and warrants an elaboration.

Customized BPM workspaces/user interfaces are a fairly common requirement. One of our marquee customers in the online stock trading business, envisioned this user interaction for their BPM application:

  1. User logs in to the internal portal
  2. Use will have list of roles which he is granted as a drop down list
  3. Once user selects the role, a list of processes which user is part of appear. Logged in user can be part of any swimlane role of the process
This can be a fairly common/reasonable user-UI interaction pattern. 1. and 2. are easily achievable and hence the subject matter of this blog is the requirement in 3.
Objective: Given a username and a role, list all the BPM processes that the user is part of, in any swimlane of any process.
Here is quick overview of the major steps/logic in the code:

  1. Intialize workflow/BPM  context as usual
  2. Get a handle on InstanceQueryService(getInstanceQueryService), InstanceManagementService,        ProcessMetadataService and ProcessModelService
  3. List all Processes for that bpmcontext (listProcessMetadataSumary) and get Granted roles to that user
  4. For each of the processes [method  getAccessibleProcesss(ProcessMetadataSummary, Set)]for each of the lanes in the process, check if the role granted to the user, matches the roleName for that swimlane. If so, add to output.


  • The usual caveats apply including BPM APIs are subject to change.
  •  JDeveloper method introspection is your better friend than API documentation :-)...

(I am going to try upload the source code  and if it doesnt work, will follow this blog up with the corresponding source code.)

Hope this helps. 

Ack: Yogesh K, BPM Dev team.

Editing the blog to include source code from


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


« June 2016