It is often useful to simultaneously spawn multiple work item instances in a process based on the contents of individual items in an array. One example of how this might be useful is when you need to send many people notifications simultaneously and you want each individual to receive their own work item instance to acknowledge.
Those of you who have used Oracle BPM 10g and earlier versions know that this was accomplished using a Split-N or Multiple activity. Although Oracle BPM 11g does not have a Split-N activity, this functionality can be achieved using a Subprocess activity with its “Loop Characteristics” property set to “MultiInstance”.
The purpose of this post is to document step-by-step how to do this and how to work around a pre-11.1.1.5 feature pack bug associated with this feature. If you are using 11.1.1.5 with the feature pack, this bug has been fixed and you can learn how to use this feature by going to Mark Nelson’s excellent blog post at http://redstack.wordpress.com/2011/10/19/building-a-job-dispatcher-in-bpm-or-iterating-over-collections-in-bpm/.
Subprocess Activity
Shown below is a process with a subprocess activity. Click here to download the 11.1.1.5 Oracle BPM project described in this blog.
Note the three vertical bars (|||) at the bottom of the fully expanded subprocess. This means that based on an incoming array of information, work item instances are created for each item in the array. Because the bars are shown vertically, you immediately know that this is a subprocess activity that bursts the instances out simultaneously (vs. sequentially) for every item in the incoming array.
Array Process Variable
This example assumes that you have a process variable created that is an array. In this example, a BPM Object was created called “TaskToDoObject” and then another BPM Object called “TasksToDoObject” was created that is an array of these objects.
A process variable called “tasks” was then created using the “TasksToDoObject” BPM Object. This tasks variable will be used to iterate through to create the individual instances in the subprocess activity.
Define the Subprocess Activity as “MulitInstance”
Double click anywhere in the subprocess’s grey background to bring up its properties. Click the Loop Characteristics tab.
As shown above, click the MultiInstance radio button. For the Loop Characteristics section, set this to iterate through each item in the array coming into the subprocess. In this example, the XPath expression using the “tasks” array and the count method was used to determine the number of items in the array. Uncheck the Is Sequential checkbox.
Leave the Arguments tab untouched. In theory, you would think that only the item in the array being iterated through would need to be sent into the subprocess as an argument. There is a bug that you have to work around if you do not have the 11.1.1.5 feature pack installed. If you were to click the “Use Associations” radio button and click the Edit button, in theory you should be able to build an expression that uses the “loopCounter” variable here to just pass a single object into the subprocess. There is a bug that prevents “loopCounter” from appearing when building the expression. As a result, work around the bug by refering to the entire array inside the subprocess.
Define a Subprocess Variable
Here is the trick to getting this to work. Double click the Script activity. Click Implementation. Click the edit icon beside the Use Associations checkbox. To work around a bug in Oracle BPM 11g (pre-11.1.1.5 feature pack), the Subprocess needs to have a variable that represents a single occurrence of the array.
As shown above, right mouse click the name of your subprocess (“Subprocess” in this example), click Add, name the subprocess variable (“task” was used in this example), and give it the type that represents a single occurrence of the BPM Object that the array was based on.
Your subprocess variables should appear as shown below. Drag this new variable into the list for the Script activity.
Using the “loopCounter” variable, set this variable using the “tasks” array variable as shown below.
The syntax in this example is “tasks.listOfTasks[loopCounter]”. The “loopCounter variable is a predefined variable that automatically keeps track of the iteration number for the MulitInstance Subprocess as instances are being created. Deploy your process and initiate it.
Based on the number of items in your array, you should see a work item instance automatically created for each one.