Moving from Metastorm BPM Version 7 to Version 9
Metastorm BPM has been evolving since its very early days as an Oracle application. It has been a strong leader in the BPM area for over 12 years. It was a market leader in the Web Client arena, and has consistently kept up with and taken advantage of the ever changing technological landscape as it has grown.
Throughout these changes the fundamental ease of use and 'descriptive' Process Design that has made it a favourite of many for many years has been maintained.
The latest incarnation as a fully .Net application and code generator is yet another almost complete makeover, possibly as significant as its transition from Oracle. We've waited a long time for this, but the real question is, are we going to enjoy the same ease of process design and overriding clarity that we have come to rely on, and has been the main strength of the product to date.
In this and the articles to follow over the next few weeks we shall try to give you all the information you will need to answer that question, and, we hope, many others.
Jerome was one of the original development team of the Metastorm BPM product at Metastorm, and has been using it for over 12 years.
He has also written the Metastorm BPM Developer's Guide
Metastorm BPM version 9 has significant new restrictions on naming of elements. This is based on the architecture employed, since the many elements will become properties or functions of the same C# class. There are basic limitations to all names, as well, that are linked to C# syntax.
On top of this, there is the new ability to provide 'captions' to many components and elements. These are often also changeable to support different languages supported by the user's browser. Some we find are never used in the system at all, however.
There has also been a significant change in the way variables are referenced. Metastorm BPM is now strongly types, and the addition of Intellisense to all editing scenarios gives us the freedom to dispense with the awkward prefixes that abound in examples from earlier versions. We will certainly be very glad to see the back of these, although we are sure they will persist regardless in some quarters.
Because of these changes, we have developed a new set of naming conventions for Metastorm BPM. These conventions are designed to minimise the potential conflicts, and give us much greater ability to distinguish between items when no other indication is available (as it now is with variables).
These conventions are neither exhaustive nor fixed in stone, they are merely what we have come across that needs a convention, or indeed, that needs one being dropped!
We no longer need to prefix our variables with the type. This was been very often misused due to ignorance in any case, and the field type is often used instead of the data type (eg %drpText1 and %rgpText2 and %txtText3 when all three are text variables).
Take the above example. We have three variables, each with a different type.
When we reference them in the Formula editor with the '%' symbol, we have no way to tell what the variable type is. This can cause problems with erroneous conversions and the similar mistakes.
Now we move in to the (relatively) type-safe world of Metastorm BPM version 9.
When we try to assign values using the Formula Builder, we get a clear indication of the variable type.
When we select a value from any Business Object, we again have a clear indication of the variable type.
Even when we use Intellisense to find and select the variable, either in the Formula Builder or the C# editor, we get a clear indication of the variable type.
We can lay the variable prefix to rest at last.
The naming of Processes has been the bane of many a Metastorm BPM developer. Firstly, once it is set, it is set for good. This is one reason we work very hard to get it right first time. Unfortunately the business owners rarely understand the significance of getting it wrong. They then ask, months later, "can we change the title of this process" (most often not in those words). Groans ensue.
Well, it's all over. All of it! We can name the process anything the users want, even with symbols in it! This is because we now have 'Captions' for our Processes.
The upshot is that we can have what we have been requesting for a long time, namely a table name that is different from the Process Name. The facility has always been there, but never activated in the Designer. Look in the eMap table and you can see the eTableName field. This can be anything you like (we've hacked and it works).
What we now do is treat the Process name itself as a table name. Typically we group all tables for a particular system by prefixing the table with the initials of the system. When you have many systems on the same database, which we will always have, it makes it a great deal easier to see and select related tables.
In Metastorm BPM version 9 we have decided to do exactly the same with our Process names.
This has the added advantage that the Process Data Business Objects are much easier to identify in what inevitably becomes a rather large list.
When we define Solution Tables we employ the same naming conventions as we use in the Process Tables.
We do not, however, use the name eFolderId in Solution Tables that relate to Process tables using the Folder ID. If you do this, you end up with an extremely confusing schema that anyone who did not design the system cannot determine from the names alone.
We use a convention of Id for these fields, so that it is clearly not a Process Table, and the related table is clearly identifiable. Given the same table prefix, this is rarely difficult to work out at a glance.
Roles are another area where naming is important to allow identification.
All roles that relate to a specific Process are prefixed with the initials of the Process. This can be seen on the list above. In general these are dynamic Roles, although that is not always the case.
If possible, Roles relating to the Process itself may be prefixed with the system prefix. If the Role may be used outside the system, which is common, we dispense with this convention, however.
We arrange the roles in the following order:
* Default Metastorm Roles
* Process Specific Roles
* Other Roles
We also add both a Caption and a Description, although generally both are set the same. This is because the Caption is seemingly never written to the database, although the Description is. We happen to think this is the wrong way around. Both can have different translations, but these are seemingly never written to the database.
As you can see, we show this description in our standard 'Assign Users to Project Roles' form that we can use in any Project.
We find this a great deal easier than the default approach that ignores both the Caption and Description.
It also does not let you filter by Project, so making even a basic system a nightmare to administrate.
We find that generally the roles will then be easier to pick from the Toolbox. The few at the bottom are from Libraries, although not prefixed as such.
Now that forms are no longer associated with any particular Process, it is more important to find a naming convention that allows you to identify where they are used. We prefix the name with the initials of the Process they are associated with.
Forms that are not associated with any specific Process have no prefix.
The exception is Forms in Libraries where we may prefix them with a numbering system. This is purely because there is no longer any way to set the order of Forms in Libraries, the are in alphabetical order by default.
When we tend to add a large number of forms in one particular order, it saves a lot of time to ensure that the order is alphabetical.
Business Objects probably pose the most challenges when it comes to identification. As we have outlined elsewhere, there are a significant number of different usages for Business Objects. Each usage is potentially entirely different, and requires both different conditions and methods to employ the resulting Business Object.
The different usages of Business Objects we have identified are:
* Editable table
* Single editable record
* Single read-only record
* List of records
* Filtered list of records
Although some may appear to be very similar, they still need to be created differently and used differently. It is also possible for some types to be used as others, but there still remains these five unique possible different usages.
Accordingly, we have created a designated prefix for each of these types.
Admin Groups & Forms
There is little need to prefix Admin Form groups with anything. Nothing that the system creates will be relevant. Admin Form groups no longer even create a custom variable table.
If desired they can be prefixed with the system initials.
There also seems to be no real need to have any naming convention for Admin Forms.
In general, if naming conflicts occur a change of name is required. The Caption can remain as desired, of course.
Stages and Actions
There is a significant new restriction in the naming of Actions. No two Actions in the same Process can be the same. The restriction used to only apply to Actions from the same Stage.
However, the Caption can be anything you like, so this is not really a restriction that bothers us. In fact, you can now have three actions with exactly the same 'name' (Caption in reality) from the same Stage!
It is very important to make sure the name of Stages and Actions is edited, however. Most Process designers will happily edit the caption in place and ignore the actual name. This is not a good idea at all. As we have noted on our Forums, it can even lead to serious problems at a later date if they are renamed.
If you leave the defaults, you will end up with Stage1/2/3 and UserAction1/2/3 in the eEvent table. No auditor would find that acceptable. You can link to the Caption in the eStage / eAction tables (and we do), but it is easier in the long term to avoid the necessity.
Generally we try to keep the real name close to the Caption. To do this we enter the name without spaces or symbols, and then edit this in the Caption property to make it more friendly.
We do the same with Stages
Visual Script Activities
We deliberately do not change the naming of any Visual Script activity. We also leave the Container name as is, unless it causes a naming conflict (as described on our Forum).
What we try to achieve is to 'tell the story' of what the code is doing. This is roughly equivalent to comments in code, althou vastly easier to read, typically. You can see fairly clearly in the above example what is occurring in the Visual Script, we feel.
If we have additional comments to make that do not fit on the Caption of the Activity, we add this to the description. This is not seen until you hover the mouse over the Activity, so is less likely to be seen. It is a very useful place to add notes that may be pertinent to developers maintaining the system, for example, but that do not add to the overall documentation.
Oddly enough, this tooltip actually stays up until you move the mouse, unlike others that disappear after about five seconds. That means you can actually read this one!
Generally we name flags prefixed with the Project name. This allows us to more clearly identify their origin when examining the database or audit records, as well as during fault diagnosis.
Projects & Solutions
We do not have any naming conventions for Projects. They do not need a prefix, and as long as they are suitably descriptive, that is acceptable.
As Projects do not have any kind of 'Caption' that may be used for presentation, it is actually very important that the names of Projects are not garbled. It will not make the system more readable or understandable, and it can cause confusion.
Solutions can be named anything you like as long as it does not violate Windows file naming conventions, as far as we are aware. The Solution name is also not important like the Procedure name used to be in Version 7 and earlier. It is merely a container for the Project and Library files.