- The business has implemented business processes that have work items that are somehow related to each other. These business processes may be hierarchical in nature such as flight planning, trips and legs; or contains work items that are related together such as line items of a particular invoice or order.
- Business organizations wish to group tasks according to management oversight, region or by some other factor.
- The business wants to provide short-cuts to users so they don’t have to jump around to find related instances and have special UI requirements to provide this functionality. This functionality may require implementing special graphical UIs such as adobe FLEX or require jumping around from one particular work item to another. Going through the in-box view to open an instance each time is not desired or feasible .
WAPI provides an mechanism to launch into a particular instance from HTML using javascript or hidden forms. I have two versions of this code, one for BPM version 5.x and the other for 6.x. The two key components is the action URL link and the instance stamp.
BPM version 5.x:
<form method="post" action="<%= URLForAction.instanceProcess(request)%>" name="instanceActionsForm"> <input type="hidden" name="instanceStampId" /> <input type="hidden" name="nextInstanceStampId" /> <input type="hidden" name="actionId" /> </form>
BPM version 6.x:
function runTask(id) {
var baseUrl = "<%=UrlActions.runTask()%>";
var instanceStampId = id;
var itemId = 0;
var url = "<%=request.getContextPath()%>" + baseUrl + "&<%=UrlActions.INSTANCE_STAMP_ID%>" + "=" + encodeURIComponent(instanceStampId) + "&<%=UrlActions.ITEM_ID%>" + "=" + itemId;
window.open(url);
}
Getting a list of related instances and pulling the instanceStamp from the instances is complicated. I’ll have to address that later in a separate blog. It involves using BusinessProcess.getInstanceByActivity or BusinessProcess.getInstanceByFilter. There’s a lot to know about using these methods so I won’t go into it now. If you know how to use these methods then all you may need help on is creating an instance stamp. This can be done from the list of instances returned from these methods. To create the instance Stamp just use:
InstanceStamp instanceStamp =InstanceStamp.create(instanceId : instance.id, activityName : instance.activityName).getId();
Using WAPI to open instances can be dangerous. BPM keeps track of open instances. These open instances are locked. When you jump from instance to instance without closing out of the associated screen-flow you’ll lock up a bunch of instances. This will preventing people from gaining access to them later on. The way to avoid this is to submit or post to the open instance before you open another one. This creates problems if you can’t simply cancel out of the open instance.
If you can simply cancel the open instance and you can be sure the cancel will work in most all cases, then you simply need to submit to the form before you open the new instance. If you can’t be certain of this, then I recommend you use a simple AJAX method to do this. You just need to parse the return document to be sure the post worked before you open a new instance. Here’s some code you can use to do this:
postLoc = "<f:postResults/>";
function cancelScreenFlow() {
var xmlHTTP = new ActiveXObject("Microsoft.XMLHTTP");
xmlHTTP.open("POST",postLoc,false);
xmlHTTP.send();
var xslresponse = xmlHTTP.responseText;
}
Hopefully you find this blog useful. I'm not sure BPM product management realizes how common these use cases are. So please let me know if you have any interesting use cases and how WAPI was used to solve your problem. Solving certain BPM use cases with WAPI has been indispensable to me. I'm always excited to learn of similar situations as the ones I've identified here.