When building solutions using IBM BPM, each separate solution is contained within its own Process Application (Process App). The Process App is the literal unit of deployment to a Process Server for execution. This works great up until the the second separate solution is embarked upon. At that moment, one will realize that there are artifacts that were built in the first solution that can be reused in the second solution. One can always copy them from the first to the second but that will result in literal duplication. If improvements are made to one copy, they would either have to be redone in the second or else the two copies would drift out of synchronization with each other. A better notion would be the ability to have a single definition of an artifact and have it “leveraged” by both solutions. This results in a set of artifacts that are common between the applications.

IBM BPM supports exactly this concept through the notion of a “toolkit”. A toolkit is named collection of artifacts that differs from a process application in one crucial way which is that a toolkit is not a deployable entity. When a toolkit is created, other process apps (and indeed other toolkits) can declare that they have a dependency on the toolkit. Once done, the BPM designer of the solution can think of the artifacts contained within the dependent toolkit as being fully available within the solution itself. It is as though (but not actually) the artifacts had been copied into the solution at hand.

As with any human endevour, factoring artifacts into a toolkit can be done well or it can be done poorly. We will now start thinking about some suggestions on what is thought to work well and what isn’t.

Don’t clutter

When one creates a new artifact, it is tempting to put it directly into a toolkit. This is rarely the right thing to do. Instead, give careful thought on what you are saying when you do so. By putting an artifact into a toolkit you are saying “This is a very important item that others will want to reuse”. That isn’t always the case. If you are tempted to create a new toolkit artifact, pause and go talk to others. Ask them if they would reuse it in the form you are suggesting? If you yourself don’t have any plans to reuse it, the chances are high that neither will others.

Generic vs specific

Once you have decided that an artifact is a good candidate for a toolkit, next consider how generic vs how specific it should be. Generic artifacts, by their definition, are more consumable by others. Specific artifacts do have their place, but consider creating two artifacts. One being a generic instance and the other being a more specific instance building on the former. They me even be placed in two distinct toolkits with appropriate dependencies between them.

Document the hell out of it

A peeve of mine is that talented and skilled individuals expend their brain power on activities and build wonderful creations but then neglect to document how to use them or how to maintain them. The result is a toolkit containing something that would appear to be what I need but with no instructions on how to use it. At best, it can simply be frustrating and at worst causes the creation to be ignored after wasting time trying to decode it. Artifacts placed in a toolkit must be very well documented. This includes (at a minimum) the reason for their existence, how to use them, any setup, any pre-requisites, any cautions and who to contact for questions or problems. An artifact in toolkit without documentation is worse than useless and a pox be on the head of the author.

Toolkit contents developed by one team may be leveraged by many others, this means that not only the usage documentation has to be present but also the artifacts themselves may need to be examined and, in future, maintained by others beyond those who created them in the first place. Litter any code with comments and use the documentation areas provided by Process Designer.

Meaningful and consistent names

Artifacts in toolkits, like artifacts anywhere, have names associated with them. These artifacts should be named following your established naming conventions. It is poor show to start using artifacts such as business object definitions where their names start with lower case characters (eg. “address”) where your other business objects start with upper case characters (eg. “Customer”). Ensure that the names for terms are consistent throughout the environment. Creating services which expect a formal parameter called “customer” where other services expect a formal parameter called “client” just becomes confusing for no good reason.

Collaborate on toolkits

The IBM BPM product is designed for collaboration and toolkits are no exception. Don’t treat a toolkit as your own personal sandbox of artifacts that you will force others to leverage. A toolkit should not be considered a collection of “your” artifacts. Rather a toolkit should be a collection of “common function” artifacts. What this means in practices is to be prepared to share the creation of a toolkit with your colleagues. Building BPM solutions is not a solo activity. When you feel that a new artifact would be beneficial to be contained within a toolkit, consider that to be an important decision. Talk it through with your team and ensure that all are in agreement.

Version toolkits like you would version solutions

Just because artifacts are contained within a toolkit doesn’t mean that you are free to release new snapshots any more frequently than you would release solutions. In fact, it is often the case that you are much more conservative in releasing toolkit versions than solution versions. The creation of a new toolkit version that is a dependency on a solution may require the re-release of the solution version even though nothing at all has changed in the solution.

Provide a web based catalog

Sadly, IBM BPM does not natively integrate with any repositories to provide catalogs or searching for existing artifacts. The concept of “loosely coupled” function and reusability existed immediately after the first two cavemen programmers wrote their first lines of code but finding those artifacts remains one of the highest challenges. After having built and documented the toolkit, publicize it within the catalog of other toolkits in your environment. You will have to choose for yourself how this is achieved. Suggestions include Wikis and other web based communal tools but any indexable and searchable content management system may also be applied. At a minimum, create a Word document and send it around but communal repositories are by far the best. What you want to avoid is the situation where someone comes to you and says that they wrote their own toolkit simply because they didn’t know your’s existed or what it contained. Obviously, you won’t create a new toolkit in ignorance because you will already have performed all the necessary research to ensure that nothing similar already exists.