Oracle Adaptive Case Management – Exposing the API – part 1

One of the most important building blocks of Adaptive Case Management is the ACM API. At one point or another you’re gonna need a way to get information (think about a list of stakeholders, available activities, milestones reached, etc.) out of the case. Since there’s no webservice available yet that exposes the internals of the case, your only option right now is the ACM API.

ACM evangelist Niall Commiskey has put some samples online to give you a good feeling of the power of the ACM API. The examples show how you can access the API by means of RMI. You first need to obtain a BPMServiceClientFactory that gives access to the important services you’ll mostly be needing, i.e. the IBPMUserAuthenticationService (needed for obtaining a valid user context) and the ICaseService (the service that exposes all important case information). Now, obtaining an instance of the BPMServiceClientFactory involves some boilerplate coding in which you’ll need the RMI url and user credentials:

Map<IWorkflowServiceClientConstants.CONNECTION_PROPERTY, String> properties =
new HashMap<IWorkflowServiceClientConstants.CONNECTION_PROPERTY, String>();
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.CLIENT_TYPE,
BPMServiceClientFactory.REMOTE_CLIENT);
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_PROVIDER_URL,
"t3://localhost:7001");
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS,
"weblogic");
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL,
"welcome1");
BPMServiceClientFactory ServiceClientFactory =
BPMServiceClientFactory.getInstance(properties, "default", null);

Now what if you need acces to the ACM API in the Case composite itself. One way to do it, is wrap all your ACM code in a java library and use embedded java to get to it. A better way to do it, is to expose this java library as a service. That’s what we’re gonna do in this blogpost series of 2. A very clean way to do this, is by making use of a Spring component to expose the library. For one thing this will relieve you of all the RMI boiler plating code nastiness.
In this blogseries we’ll show you how to fire a case user event via a service call. In the first blog we’ll build the necessary java code and convert it into a neat little library. In the second blog we’ll build our case composite and expose our library as s Spring service. For reference you can find both the projects used in this blog on GitHub.

Custom ACM API

First things first. Let’s build our library project CustomAcmApi. With the library we’ll expose the raiseCaseEvent method of the ICaseService service. The class diagram of our custom acm api is depicted below.

Custom ACM Api

(I)CredentialService

We’ll need a case user with sufficient privileges to get a valid IBPMContextfor getting access to the case internals. And for this we need credentials (username/password). That’s what this service implementation should provide. The implementation used in the example, is very basic and just returns weblogic/welcome1 as the user credentials. You should swap this class with something a little more flexible and secure. You could, for example, make use of the Credential Store Framework Weblogic provides. See this excellent Redheap blogpost to give you the pointers.

(I)AcmAPI

This is the public API and implementation which we’ll expose later on as a Spring Bean. The API in the example will have a raiseCaseEvent method for firing user events. This API is a good starting point. You can add more and more operations according to your needs. The services (ICredentialService, ICaseService and IBPMUserAuthenticationService) required by the bean are exposed via setter and constructor arguments and will be injected by the SOA container at runtime (for this we’re making use of Spring Dependency Injection).
By means of the injected CredentialService the credentials can be retrieved in the init method of the bean:

public void init() {
  this.credentials = credentialService.getCredentials();
}

All methods you’ll be exposing, will have the same setup. First get a handle on a valid IBPMContext (this context unfortunately times out after a while, so reusing it is not an option), next construct a CaseIdentifier based on the caseId and finally call the CaseService operation you’re interested in, and optionally transform the results into something you want to return from the method.

public void raiseCaseEvent(String caseId, String userEvent) throws AcmApiException {

  IBPMContext adminContext = null;

  try {
    // 1. get IBPMContext
    adminContext = bpmUserAuthenticationService.authenticate(this.credentials.getUsername(),   this.credentials.getPassword().toCharArray(), null);

    // 2. get CaseIdentifier
    CaseIdentifier caseIdentifier = CaseIdentifier.getCaseIdentifierBasedOnCaseId(caseId);

    // 3. call CaseService
    CaseEvent caseEvent = CaseEventFactory.createUserDefinedEvent(userEvent, null, null);
    caseService.raiseCaseEvent(adminContext, caseIdentifier, caseEvent);
  }
  catch (CaseServiceException e) {
    throw new AcmApiException(e);
  }
  catch (BPMException e) {
    throw new AcmApiException(e);
  }
  finally {
    try {
      bpmUserAuthenticationService.destroyBPMContext(adminContext);
    }
    catch (BPMException e) {
      throw new AcmApiException(e);
    }
  }
}

libraries

To get all this code to compile, you’ll need to wire a few libraries into your project:

• BPM Services
• Java EE 1.5 API

and a couple of jars (these I’ve bundled in a custom JDeveloper library which I’ve added to the example project on Github):

• oracle.bpm.bpm-services.interface.jar
• oracle.bpm.casemgmt.interface.jar

custom-acm-api.jar

Now if you’ve followed all steps carefully, the project can be deployed as a jar, which we’ll add to the SOA composite in the second blogpost.

Ook interessant?

Blog

24/05/2014

Oracle Adaptive Case Management – Exposing the API – part 2

Lees blog