Source Code Control (SVN) and Team Development with ALBPM and OBPM 10g
By user732634 on Dec 08, 2011
Source code control is essential to managing the life-cycle of an application. Plus, it facilitates a predictable deployment practice. This document discusses how to use the SVN code repository to manage ALBPM and OBPM 10g projects. This document concludes with a suggested procedure for allowing development teams to submit their changes to a source code repository, which can then be deployed by system administrators to the BPM engines.
Several BPM consultants have provided input to this document. And, it represents a compilation of their experiences.
BPM Studio Source Code Control Integration
Specific Source Code Control Systems
Because the old ALBPM and OBPM 10g Studio's were build on the Eclipse foundation, integration with a source code control system that has Eclipse plug-ins is usually pretty straight-forward. What follows in this section are steps to integrate Studio with some Specific source code control systems.
CVS and SVN
Aqualogic BPM v6 comes with built-in integration with CVS. Support for SVN is built into OBPM Studio 10g. To support SVN in v6, you must install the appropriate plug-in into Eclipse. Two of the available plug-ins are Subversive and Subclipse. The following link provides a walk-though on how to install Subversive into ALBPM Studio: (http://www.function1.com/site/2008/01/integrating-albpm-60-with-subv.html).
Rational Clear Case
Appendix A contains a detailed description on how to integrate Rational Clear Case with ALBPM and OBPM 10g Studio. Please note, that the latest releases of Rational Clear Case are not compatible with the old version of Eclipse that Studio requires. Make sure your version works with the Studio version of Eclipse before trying to install the Eclipse plug-in.
No Source Code Control Integration Possible?
Can't seem to get your Source Code Control (SCC) system to integrate with BPM Studio? Well here is a manual way you can get your BPM projects into without using Eclipse integration.
Generally, all of the subdirectories and their contents of a BPM project should be checked into the code repository with the exception of the “build” and “system” directories. But you may want to exclude some of the other directories and files listed below.
- /publication.xml -- This file keeps track of some objects published during local Studio testing.
- /component/Catalog/* -- Business objects in the catalog are good to keep in SCC. But introspected objects may not work out so well for reasons mentioned elsewhere in this document.
- /config/bam.xml and /config/engine.xml -- These files are updated when you run the Studio engine for testing.
- /config/organization/participant/* -- This folder contains all of the configured participant. These may change during testing. And, not everyone in the team may want the same participants.
- /config/externalResources/* -- Sometimes you may not want to have the External Resources in source control.
- /lib/* -- Depending upon the policy you are using, you may not want the jars in source code control.
Problems with Document Merge
There are known problems with the ability of source code control software (particularly SVN) to accurately merge BPM documents. It is best to avoid the scenarios where code merges occur. Usually, merges occur when two developers are working on the same document. The first developer commits his changes to the repository. Next, the other developer commits their changes. The source code control (SCC) software notices that the versions are different and attempts to merge the two documents. Most of the time the SCC is not optimized for the XML rich content of the BPM documents, and things go awry.
Here are some helpful strategies to avoid this scenario.
1. Developers either request edit permission, or lock the document in question before editing. Then, the developer releases the lock when editing is complete.
2. For SVN: change the MIME type in SVN of the OBPM document types to “octet/stream”. SVN will not try to merge what it thinks are binary file types.
3. Reduce the likelihood of developers needing to develop on the same document by decomposing your project into smaller, more reusable pieces.
a. Try not to write long blocks of PBL code. Alternatively, put smaller pieces into BPM Object methods. Also, consider using Procedure implementations.
b. Implement interactive activities with Screenflows.
c. Refactor large processes to call subprocesses. Divide the processes into reusable assets.
Problems with Re-introspecting Objects in the Component Catalog
Frequently, web service definitions change. This causes the developers to re-introspect the web service for OBPM Studio to recognize the changes. Unfortunately, the way that OBPM Studio refactors the project’s file system when web services are re-introspected will seriously confuse the Source Code Control . Recovering from this confusion can be very difficult.
Follow the procedures in Appendix B to avoid these problems.
Problems with Existing Installations of Tortoise SVN
The version of SVN installed with Tortoise SVN will conflict with the version of SVN installed with the Eclipse plug-in. It is best that Tortoise SVN be removed from computers in which OBPM Studio development (with SVN integration) will be performed.
Deploying BPM Projects from Source Code Control
The ultimate goal of good source code control is not just to facilitate team development. Ultimately you want to have a scripted and reliable compile and deployment process that does not involve a lot of human interaction. This section will describe how this can be achieved with BPM Studio.
Development Process With Source Control
Once the development team has integrated Source Code Control (SCC) with BPM Studio/Eclipse, they can proceed with the following procedure.
- Developers using OBPM Studio, with the SVN plug-in for Eclipse, keep their source-code in sync with the SCC repository.
- After testing, and ready to deploy to the target BPM system, the
developers compile and double check to insure there are no errors.
Note: I have other articles which cover unit testing of BPM processes on my personal web site:
- Unit testing ALBPM and OBPM: Unravelling PUnit, CUnit and PAPI JUnit Testing
- Automating ALBPM / OBPM 10g Interactive Forms in a JUnit Test
System Administrator Automated Deployment Process With Source Control
Most of the customer engagements I have been on, the System Administrators were using the Process Administrator UI to deploy BPM projects. While this process works well, it does not eliminate the possibility for user error. Also, you can never be sure that the process of deploying a particular project was performed exactly the same way between environments.
The Ant interface to the BPM Engine and Directory works really well. And, it solves these problems. Investing a little time in developing the scripts just right can make things much easier in the long run. Plus, as more projects get deployed, or they get more complex, ant scripts really help the System Administrators enforce architectural policies.
- The project is checked out of P&G’s SVN repository to a local Deployment folder.
- An Ant script is executed to deploy the project to the appropriate BPM engine.
- The BPM Ant API will deploy the project’s folder instead of an BPM Studio exported file (*.exp).
Appendix A: Rational ClearCase BPM Studio Integration
This section will guide you step by step with how to install ClearCase integration with ALBPM or OBPM 10g Studio. Note, the latest version of ClearCase is not compatible with BPM Studio.
1. In BPM Studio, select the menu items: Help | Software Updates | Available Software | Add Site.
2. Type "http://jautodoc.sourceforge.net/update/" in the "Location" field and click "OK".
3. Click "Install…", "Next" and read and accept the license agreement. Select "No" when it asks you if you want to restart.
4. Select the menu item: Help | Software Updates… | Available Software | Add Site… tab.
5. Type "http://pmd.sourceforge.net/eclipse" in the "Location" field, and click "OK".
6. Check "PMD for eclipse 3" and click "Install…" Select "No" when it asks you if you want to restart.
7. Restart Eclipse: File | Restart.
8. Click: Help | Software Updates… | Available Software | Add Site… tab.
9. Type "http://www3.software.ibm.com/ibmdl/pub/software/rationalsdp/clearcase/ccrc/701/update/" in the "Location" field and click "Install...".
10. In the "Unsupported Install" dialogue box select "Launch".
11. In the "Install/Update" window, select "Search for new features to Install" and click "Next".
12. In the "Updates sites to visit" window, select "New Remote Site…" and give a Name.
13. The URL field needs to be "http://www3.software.ibm.com/ibmdl/pub/software/rationalsdp/clearcase/ccrc/701/update/.". Click "OK".
14. In the "Updates" window, select "Rational ClearCase Remote Client for Eclipse" and click "Next".
15. Select "Install All in Feature".
16. Select "Install All in Feature Verification."
17. Restart Eclipse and open the ClearCase perspective.
Appendix B: Re-Introspecting a Web Service Under Source Code Control
When you re-introspect a resource into the Component Catalog, BPM Studio sometimes deletes files and folders, then recreates them. Source Code Control (SSC) systems keep track of differences of files. When the contents of a folder drastically change without the SSC knowing about it, bad things happen.
There are two strategies that I have seen that work to alleviate this problem.
1. Keep the Component Catalog folders which get frequently changed out of SCC. Each team member has to manually keep track of changes to the components and re-introspect them. Then just prior to testing/deploy, introspect them with studio. This is a manual approach, but I have seen it work. There is usually a lot of time wasted getting the external resources and components introspected just right when things change. Another disadvantage is that interface code is not in source code control.
2. Have one person manage re-introspections. When changes to interfaces or objects, this team member will follow the procedure outlined in this section to make sure the changes get put into source code control. Then, the other team members can update their projects. This is a cumbersome process. But it isolates time wasted to a single team member. And, interface code will be saved to source control. Plus, it is easier to automate testing and deployment.
The key concept is that the SCC needs to know when folders and files are getting deleted, so it doesn't try to change or merge documents. The procedure below shows how to do re-introspection of a Web Service. But this procedure can be used for other complex objects that are introspected. This procedure has been tested with ALBPM 6 with SVN. You will probably have to modify it to suit the SCC system you are using.
1. Ensure that ALL of your project code is checked into Source Code Control (SCC). You MUST completely remove the project in the course of these instructions and import it from SCC. This means that any code that is NOT checked into the SCC will be LOST.
2. Right click the Web Service in the “Project Navigator” pane of ALBPM Studio and select the “Recatalog Component” menu item.
3.Copy the WSDL address field to the clipboard. You’ll need this later. If necessary, paste it into a Notepad window.
4. Close ALBPM Studio.
5. In Windows Explorer, navigate to %ALBPM project home directory%]\componentCatalog\Custom\WebServices\" and select the web service that you need to re-introspect. In the right-hand pane of Windows Explorer, select and delete all of the files in that directory with the exception of the “.svn” sub-directory.
6. Re-open ALBPM Studio (note that the project will take a few minutes to recompile)
7. Commit the project from the top-most level in the “Project Navigator” pane. (This is where we tell the SCC that the files and folders have been deleted.)
8. Click on the “Select All” button and then the “OK” button.
9. Delete the Web Service you want to re-introspect in the “Project Navigator” pane of ALBPM Studio.
10. Commit the project from the top-most level in the “Project Navigator” pane. (See the screenshot for Step 7).
11. Click on the “Select All” button and then the “OK” button.
12. Right-click on the project name in the “Project Navigator” pane and select the “Remove from Workspace” menu item.
13. Close ALBPM Studio.
14. In Windows Explorer, delete project’s directory.
Yes, that's right. SSC systems like to store information in hidden files and folders. So does Studio/Eclipse for that matter. If you don't delete the project folder, you risk confusing the SSC into thinking that the re-introspected files and folders are the same ones. Then it will try to calculate differences and merge. In the end, it messes up the repository.
15. Open ALBPM Studio.
16. Select the menu item: File | Import…
Now we need to get the project from the SSC the way the SSC understands it, just like you would if you are just starting to work on the project. This gets us a nice clean version with no baggage from the deleted component catalog items.
17. Select the “Other / Checkout Projects” from SVN import source, then click the “Next >” button.
18. Select the existing repository location and click the “Next >” button.
19. Select the appropriate folder for the project and click the “Next >” button.
20. Click the “Next >” button.
21. Click the “Finish” button. (Allow code to download from SVN and for WorkSpace to recompile.)
22. Right click on the “Web Services” tree node in the “Project Navigator” and select “Catalog Component | Web Service” menu item.
Now we are introspecting the web service again. The SSC will think it is a new set of files and folders. And, it won't get confused.
23. Paste in the WSDL address that was copied to the clipboard in Step 4 into the “WSDL Address” field. (See the screenshot in Step 4).
24. Commit the project from the top-most level in the “Project Navigator” pane. (See the screenshot for Step 8).
25. Click on the “Select All” button and then the “OK” button.
26. Run any available unit tests against all re-instrospected Web Services to insure if they are functioning correctly.
About the Author
Floyd Walker has been helping companies implement BPM technologies for over six years. An expert in many different technologies, he has a passion to provide solutions and explore the new vistas of the software industry. Sometimes he posts interesting things on his blog http://www.floydwalker.com. While he works as a consultant for Oracle Corporation, he wishes to remind you that all contents of his blog posts are his own opinions and do not reflect the views and policies of Oracle. I hope you have enjoyed reading this article.