I recently published an article on ALBPM and OBPM 10g source code control on a blog of a friend. I didn't want my fans to miss out. So here is the link:

Source Code Control with ALBPM and OBPM 10g on the Practical BPM Blog.

As always, Enjoy.

One of my previous posts demonstrated several ways to test your BPM processes with unit testing. The most flexible and useful by far is by mixing PAPI with Java JUnit test classes to automate specific test cases. This way you can exercise all the paths of your process and be sure everything works as expected. This article will show you how to do that.

This article explores a solution to a problem with that methodology. Namely, the JUnit tests on BPM processes with interactive forms can't be completely automated. You would have to pause the test for a bit, while you open up Workspace, find the instance and execute the form. This procedure is prone to human introduced variations in the test which can't be reliably reproduced.

The Problem
A BPM process deployed to either the Studio or Enterprise engine sends and receives data in many ways. The interaction can be done through database calls, webservice calls, JMS topics or queues, files, interactive forms, the list goes on.

When testing with JUnit/PAPI you can stub all of these out with local copies of files, and databases. JMS topics and queues can be filled with expected data via JUnit. Webservices can easily be mocked out with SOAPUI. Getting your test cases with reproducible and reliable test cases.

But as long as there are interactive forms in your process, you can't automate further. And, because you have to go through Workspace, no back-end, JMeter, or HTTP trickery can reliably interact with the forms to get and send data to the process.

The Solution: WAPI
To overcome these shortcomings, we can use WAPI to send the data we want directly to Workspace. Thus, our test cases can be completely automated with predictable data.

WAPI: ALBPM / OBPM 10g's Web API
What is WAPI? It is ALBPM / OBPM 10g's Web API. Meaning, you can interact with Workspace via HTTP calls. You can do things like executing Workspace tasks, getting and filling out forms, getting process diagrams and audit trails, and more. Unfortunately, there isn't much in the way of documentation on it. All that we really have to go on is a few examples provided for is in the <bpm_home>/studio/webapps/workspace/wapi/urlActionsExample.jsp file. This file shows you how to do a few things with WAPI. But that was enough to get me started. And now you have a fairly complete example of how to apply this technology to automate your JUnit test cases for your BPM projects.

But, WAPI is a Web Interface. Meaning it is meant to be called from a browser. Like Workspace, you have to provide valid login credentials in order to do anything interesting. In fact, WAPI is a part of the Workspace Java Application. So you may be wondering how Java and JUnit are able to use WAPI to provide form inputs for interactive activities.

I have done a bit of socket programming in my day. So I'm familiar with the HTTP web protocol and how browsers interact with servlets. So I wrote a few static methods that you can use to connect to workspace in Java using the normal login credentials, manage the session, and post form values over the HTTP protocol. To Workspace, it works just like a browser.

All of this is in static variables in the Tools.java class. To use this class, you just provide the HTTP POST values that are in the form you are presenting in the interactive activities. In the example projects, I got this working for the declarative forms, Object Presentations, and custom JSP's. The static methods should do most of the work for you. The tricky part will be properly formating the form post values.

Setting the Form Values
The form values are put in the config/*.properties file along with all of the other PAPI/WAPI settings. This allows you to store posts several different forms and several posts for the same forms to satisfy any test criteria you have.

I provided two sample .properties files in the config folder to show you how to connect to the Studio engine as well as a WLS engine using PAPI.

The form's values use the following syntax:
fieldName1=fieldValue1&fieldName2=FieldValue2&fieldName3=fieldValue3%20With%20Spaces&FieldN...

Notice the "%20" for the space. This is typical URL encoding, using hex values for special characters which would confuse parsers. The field names are the "name" attributes of the HTML INPUT tags. For example, the INPUT tag: "<INPUT type=text name=FieldName1 value=FieldValue1 />" the name is "FieldName1". For declarative forms and object presentations, this can be hard to decipher. I usually use this shortcut to generate the post-value strings I put in the .properties file. But to do this you need Firefox and the Firebug plugin.

1. Open Workspace in Firefox.
2. Open the form you want to automate.
3. Fill out the form.
4. Then, just before you submit, open the Firebug panel and select the "Net" tab.
5. If the "Net" tab is not enabled, enable it.

6. Click on the "Clear" button to get rid of any previous network traces.
7. Click on the "Persist" button to make sure the traces you want don't get cleared
8. Make sure the "All" button is depressed.
9. Press the button or link on the form that saves or closes the form and returns control to the screenflow or process.
10. In the Firebug Net panel, you should see some network traces appear. Look for the first "POST" line, and click on the plus button next to it.

11. Open the "Post" sub-tab, and scroll down until you see the "Source" section.
12. You will notice that the text in this section match the syntax I described above, URL encoding and everything. So, just select the entire text of the "Source" section and paste it where you like it in the .properties file.

This procedure makes it much easier to generate the test data for form posts. And it is less error-prone because it uses the actual data your form used to submit to Workspace.

Getting the Source
The working examples are available at the following links. The archives contain both the BPM project export and the Java source code.

• OBPM 10g - PAPI/WAPI/JUnit Example
• ALBPM 6.0 - PAPI/WAPI/JUnit Example

Using the Examples
After you uncompress the source code, you will need to provide the necessary ALBPM or OBPM 10g jar files to run the examples. These are your typical jar files you would use for any PAPI program you would write. They are available in your BPM Enterprise installation folder <BPM_HOME>/client/papi/lib folder. There is a text file in the lib folder of the example which lists explicitly the jar files I used to get the project working.

Second, if you are connecting to a BPM Enterprise engine, you will need to put that engine's directory.xml in the config folder. This file contains database connectivity information so the Java program will know where all of the BPM goodies are (the BPM Directory database). I usually get if from the <BPM_HOME>/webapps/workspace/WEB-INF folder of the J2EE installation.

Next, edit the .properties file you are going to use to suit your environment. Most of these values will be easy to decipher. But I will go over a few of the ones which might give you trouble. I provide two .proerties files. One for the typical connection to a J2EE Enterprise installation of BPM. Another for connecting to the BPM Studio engine.

The Studio engine connection does not need to know where the directory.xml file is located (fuego.directory.file). But it does need to know where the project is located (fuego.project.path). Also, Studio does not require passwords to connect. But the example code expects a value in "bpm_password". So it doesn't matter what you put in this value. It just has to be present.

The J2EE Enterprise connection does need a password. And because I just hate plain text passwords in text files, the example code expects the password in the .properties file to be encrypted. I provide a simple Java class to encrypt a password (com.floydwalker.crypto.CryptoLauncher). If you plan on connecting to BPM engines that handle sensitive data, you will of course change this to suit whatever security policy you have in place.

There are two sets of credentials. "bpm_user"/"bpm_password" are the PAPI engine connection credentials. "WorkspaceUser"/"WorkspacePassword" sets the participant login that is used to execute the interactive forms.

There are a few "Workspace..." settings that allow you to specify where Workspace is located. You can probably just change the hostname and port on these guys to get them working.

At the very bottom of the .properties file are the form post values for the interactive forms provided in the BPM project export.

Everyday Use
I have been using these techniques frequently to apply test-driven-development techniques to BPM Process design. It has made it much easier to find errors and bottlenecks in edge cases. I also like the convenience of proving that recent changes are viable. Using mocked servers and stubbing out other interfaces to external systems, it is easier to isolate whether or not bugs come from BPM or from the external systems.

It is my wish that this knowledge help you to develop better processes, faster. Enjoy.

The folks who have been using the WCI portal for a long time know about the old Plumtree Studio product and how it allowed you to easily create surveys and give them to the portal users. This product has been depreciated since ALUI v6. But the dream still lives.

While the Simple Survey portlet experiment does something similar to Plumtree Studio, it does not replace it.

How it Happened
For a long time, I wanted a portlet which would do something similar. Basically, allow a non-technical community owner to be able to create an HTML form which other users can use to post data. Then the community owner can then present the data however they like.

Sample Simple Survey Form

When I created the Simple Content portlet, I realized that this may easily be possible with a little more open source software, and a little elbow grease. I found the great JMForm plugin for TinyMCE JavaScript WYSIWYG editor used in the Simple Content portlet. This adds an additional toolbar to the WYSIWYG editor to allow the user to create and edit HTML form elements.

Sample Simple Community Preferences

I then created some JSP's to dynamically save the form data when the user submits the HTML form in the portlet.

Here is where I got a little crazy. I dynamically save the data to an XML file. The portlet automatically creates an XSL, XSD and DTD file when the first time the form data is posted after it has been edited. This allows the data to be easily consumed by other tools.

The Survey Results Portlet
Finally, I created another portlet which can use the XSL (or a modified version of it) to transform the XML data into HTML for the portlet presentation. The default XSL file (automatically created by the Simple Survey portlet) displays the submitted form data in an HTML table. It also provides a link to download the data to a Microsoft Excel spreadsheet.

Sample Simple Survey Results

This portlet has an Administrative Preference page to set the file location (on the remote server) of both the XML data file to show, and the XSL file used to transform it to HTML.

Form Options
The Administrative Preferences page for the Simple Survey portlet is very similar to the Simple Content portlet because it shares the same infrastructure to support allowing the user to maintain their WYSIWYG content. There are a few extra options to handle how form data.

Sample Simple Administrative Preferences

Existing form data from the same user and community page for this portlet can either be replaced or added to the data store.

Also, the existing data can be optionally loaded into the form from the data store.

A URL to an HTML file to be presented when the form has been submitted.

One of the options is to present the "done" form if the user/page/portlet already has data.

The Experiment Continues
There is still a lot of work to do on this portlet in order for it to be generally usable.
I would like the Results to be easier maintained by the community owner.
Storing data in XML like the portlet is doing is probably not performant.
Anytime you have dynamic forms creating data structures you are opening up a huge window for overrun attacks.
To name a few.

Nevertheless, this is an interesting portlet with moderate potential. If you want to take a look at this madness you can pick it up from this link.

Once you have the Oracle WCI or ALUI portal filled with documents and communities, it is sometimes nice to have a simple way to generate a link to some of these portal resources. Say, you have an HTML portlet which you want to reference a document or folder in the Knowledge Directory. Or, you have a community page which is not directly related to another community, but you want to have a link to another community's page.

Well, you guessed it, that is really all that this portlet does. It is just an HTML file that uses the portal's Adaptive Tags to allow a user to select a community or Knowledge Directory item from the portal's built-in object selector. The selection is then crafted into a JavaScript link. This link is then placed on the user's clipboard so they can paste the link into the href attribute of the anchor tag of their choice.

Get Portal Link, Initial Page Load

Selecting a Knowledge Directory Item

Selecting a Community

Get Portal Link, Portal Object Selected

The JavaScript link uses the portal's PTCommonOpener JavaScript object. So these links are only useful inside the portal. Here are some examples of the links:

Link to a Knowledge Directory Item/Document:

javascript:void(s=PTCommonOpener.openInNewWindow(PTCommonOpener.getOpenerURLOpenObjID(18, 306, '', 2), 
  'myWindow', 650, 425, true));

Link to a Knowledge Directory Folder:

javascript:void(s=PTCommonOpener.openInNewWindow(PTCommonOpener.getOpenerURLOpenObjID(17, 212, '', 2), 
  'myWindow', 650, 425, true));

Link to a Community:

javascript:void(s=PTCommonOpener.openInNewWindow(PTCommonOpener.getOpenerURLOpenObjID(512, 208, '', 2), 
  'myWindow', 650, 425, true));

Sample of how to put one of these links into an HTML anchor tag:

<a href="javascript:void(s=PTCommonOpener.openInNewWindow(PTCommonOpener.getOpenerURLOpenObjID(512, 208, '', 2), 
  'myWindow', 650, 425, true));">Link to a fun community</a>

These links can be changed a bit, if you know what you are doing. For example, if you know the id number for a page of a community you want to link to, you change the object type id to 514 as follows:

Link manually changed to open a Community Page:

javascript:void(s=PTCommonOpener.openInNewWindow(PTCommonOpener.getOpenerURLOpenObjID(514, 208, '', 2), 
  'myWindow', 650, 425, true));

If you want the link to open the link in the same page, you can alter the link text as follows:

Link manually changed to open in the same browser window as the link:

javascript:void(s=PTCommonOpener.openInSameWindow(PTCommonOpener.getOpenerURLOpenObjID(512, 208, '', 2), 
  'myWindow', 650, 425, true));

That's about it
The portlet is pretty basic. It is really just pulling several portal API's together into something somewhat useful. You can download it here if you like.

I have been up to my neck in Java and BPM stuff for a while, but nothing really exciting. So, since I haven't posted for a while, I thought I'd clean up an old .NET / WCI portal project I did and tell you guys about it.

The Story

The MooTools JavaScript library has an excellent set of validators that were developed by the guys at Clientcide. They are really elegant in both implementation and presentation. Once you load the MooTools library on the page, and add one line of JavaScript, you just add a class name for the validator you wish to use to the HTML form item you want to validate and BAM! that's it. If you want it to look pretty, just add a stylesheet. All of the effects are controlled through styles.

Here is a quick example to give you an idea: ( show code )

<link rel="stylesheet" type="text/css" href="http://www.floydwalker.com/files/MooControls/Demonstation.css" />
<script src="http://www.floydwalker.com/files/MooControls/clientcide-trunk-622.js" type="text/javascript"></script>
<form id="myForm" name="myForm" target="_self" action="SmallDemo.htm">
    <script  type="text/javascript">
    function bodyOnLoad() {
      var oFormValidator = new FormValidator('myForm');
    }
    </script>
    Required: <input class="required" id="MooTextBoxDemo1" name="MooTextBoxDemo1" />
    <br />
    Numeric: <input class="required validate-numeric" id="MooTextBoxDemo2" name="MooTextBoxDemo2" />
    <br />
    <input id="btSubmit" type="submit" value="Submit" name="btSubmit" />
</form>
<img src="http://www.floydwalker.com/files/MooControls/Blank.gif" border="0" style="display: none" onload="bodyOnLoad();"/>

More information about these validators can be found at the mootools.net site. Note

Now every good web developer should know by now that you can't rely on just JavaScript to insure you get valid data to the server. Plenty of people know how to hack the systems to submit unwanted data. That is where these custom .NET User Controls come in.

The MooControls complement the MooTools validators to insure that data validated on the client (with the MooTools validators) gets validated again on the server to insure data consistency. And, if the validation fails on the server, the form appears in the browser again just like it would if it failed the JavaScript validators. The user gets the flashy validators. The server is confident that it gets good data. And, the developer doesn't need to sweat about the details of the arrangement. Everybody wins!

In The Portal

While these controls work great in a standard ASP.NET web application, they are really designed specifically to run in an Oracle Web Center Interaction (WCI) portal.

Designing portlets for a WCI (aka. Aqualogic User Interaction (ALUI), aka. Plumtree) can be a bit daunting for junior developers. The Oracle .NET Application Accellerator makes things a bit easier by capturing post-backs and updating the portlet in-place. But, if you want to do fancy AJAX stuff like some of the MooControls do, then things get dicey. The Microsoft AJAX controls just don't play well with WCI.

The MooControls, combined with the Oracle WebCenter Application Accelerator for .NET makes creating nice, form-based WCI portlets much easier. Plus, there are a few tricks it can do to really make the portlets pop.

Don't have a WCI portal? Don't worry; the MooControls work fine in a regular ASP.NET application. One nice feature of the MooControls is that it can detect whether or not the application is being hosted in a portal or not. This makes debugging the UI outside of the portal a little easier.

The Controls

Each MooControl is a derivation of one of the standard .NET WebControls you are probably already know and love. The next table shows a list of the MooControls. The names of the controls and their base class should tell you what they do. If you need more information, check this page for details on each control and their attributes, methods and behaviors.

The MooControls and their ASP.NET Base Class Controls

First, the MooFormValidator control tells ASP.NET how and when to load the MooTools JavaScript library onto the form. It will initialize the JavaScript object and control all of your MooControls on the form. Consequently, you will need one of these guys on each form you use a MooControl.

The other "Simple Controls" behave exactly like their base control counterparts. They even appear in the ASP.NET Toolbox and look nice in the "Design" and "Split" views of the Visual Studio IDE.

To begin using the validator functions of the MooControls, you just need to specify two attributes:

1. The "MooFormValidatorID" needs to contain the Id given to the MooFormValidator control on the form you want the control to be asscociated with. (Yes, you can have more than one for a form.)
2. Type one or more validator names from this list into the "ValidatorTests" attribute. The validator names should be separated by a singe space.

The MooButton and MooLinkButton have been modified to insure that the client side MooTools validators validate the controls before executing their server side event code.

Dependent Controls

I implemented in the MooControls the idea of dependent controls. What this means is you can have a set of MooControls that are dependent upon one MooControl. These dependent controls either appear/disappear, enable/disable, validate/don't validate based upon the value of the master control.

This is useful for forms where you need additional information if a user selects a certain radio button or checkbox, or even puts a large value in a numeric textbox. Of course, you need to provide the test in JavaScript (for the browser) and then again on the server (in server side code). See the example project in the download if you want to see how it's done. It's really not that complicated.

Example use case: (Click on the "Yes" and "No" radio buttons.)

You don't want the "Please Explain" prompt to appear unless the user specifies "Yes" in the master MooRadioButtonList. The "Please Explain" label and associated MooTextBox are in a DIV element that specifies the container for the dependent controls. When the dependent controls are not visible, their validators are not active.

Other Features

The MooControls has a really neat date entry control in the MooDateTextBox (thanks to MooTools). It has really good date entry, selection, and validation. Plus, you can specify date range validation.

MooDateBox Sample

The MooTextBox control can insure you provide a specific number or a range in the number of characters entered. If it is a numeric MooTextBox, you can insure that the number is in a specified range.

These ranges and validators can be added, removed, turned off or on, in the client-side (JavaScript) code. You can specify where you want the validation messages to appear. You can change the validation text if you want. Custom validators aren't too difficult to create, especially if you know regular expression syntax (not required) and rudimentary JavaScript.

All of these features are demonstrated and documented in the sample project in the download.

The Complex Controls

The MooGridView control works like the out-of-the-box GridView conrol. But, it has a few extras added to allow the user to create a grid of MooControls. This is useful if you need to collect a series of zero or more instances of a data type. Say you need to have the user enter the beginning and ending employment dates and the name of the employer. Each row begins with a checkbox (for row selection), then two MooDateBox controls and a MooTextBox control, each with their own validators. At the bottom of the MooGridView is two buttons: "Add" and "Delete". This allows the user to add and remove rows in the collection.

MooGridView Sample

The MooGridView manages the dynamic creation and removal of the MooControls contained within the rows of the grid. The developer just needs to drop the controls in a template row, and bind them to the data source correctly. An example is in the download.

MooPopupView Sample

Next, the MooPopupView is just low-hanging fruit. MooTools provides what they call a StickyWin control. It is a very customizable modal DHTML window which can appear and disappear based on user interaction. Every bit of HTML that appears within the start and end tags of the MooPopupView control will appear inside a StickyWin window. It will appear as a modal, draggable window. The rest of the page will be "greyed-out" and disabled. And, the developer gets to select the buttons that appear at the bottom of the StickyWin. See the download project for an example and documentation.

The WCI Portal Controls

If you are going to use the MooControls in a WCI portlet, the MooPT control should be on every page that is hosted in a portlet. First, it detects whether or not the browser request is coming from the portal, or straight from the browser, then changes the script path accordingly. This is wonderful if you need to test your portlet outside of the portal a bit. When it is in the portal, it gets the MooTools JavaScript files from the Image Server. Otherwise, it will look for the files in the web application.

The second thing it does is drop the "pt:token" tag on the page, so you can make all of the names and Id's in the portlet page unique.

The MooPTImage tag behaves like the out-of-the-box Image control when the page request comes directly from the browser. But, if it comes from the portal's gateway, it will put the "pt://images/" prefix in front of the image URL. This insures that your images are served from the Image Server when the portlet is deployed. And, if you want to test your page outside of the portal, you don't need to change the URL's of your images.

The last of the portal MooControls is the MooPopupPortletContainer control. This control is also the most complex of them all. Setting it up requires a bit of orchestration. But once operational, the effect can be quite cool.
Here is the idea. You have one portlet on a portal page. In that portlet, you have a link or button that when pressed causes a form to appear in a modal style like the MooTools StickyWin or MooPopupView control. The difference is, post-backs occur in-place inside the modal window. When finished, the user clicks a button on the form, it posts-back to save the form data, then the modal window goes away and sends a result back to the parent portlet.

This is done by having a portlet page with the MooPopupPortletContainer in it. The control causes the portlet to disappear from the portal page. When a specific JavaScript function is called, the invisible portlet loads an ASPX page, becomes visible and changes it's dimensions so that it becomes a MooTools StickyWin. The Oracle WebCenter Application Accelerator for .NET handles the rest. When done, another JavaScript function is called, and MooPopupPortletContainer returns to its original, invisible state.

The End?

I am not actively maintaining this library. But, I did have a great deal of fun developing it. I really should update them to support some of the great things in the latest version of MooTools. Perhaps if I get really bored one day… I thought it was a really good idea. Especially since I really hate the out-of-the-box validators that Microsoft gave us with ASP.NET. And, the MooTools validators are very pretty.

I have included a demonstration project with the download. It not only shows you how to use the controls, but also contains a bit of documentation as well. Here they are, for your enjoyment:

Download MooControls for the WCI Portal (requires the Oracle WebCenter Interaction Development Kit (IDK) and the Oracle WebCenter Application Accelerator for .NET)

Download MooControls for regular ASP.NET development. (WCI Portal controls and features are disabled)