Hello everybody and welcome back to wm-explorer. This post intends to be the start of a series on how to write good, easy to read, maintainable, performant (FLOW) code in webMethods Integration Server.
For those of you who liked the web services discussions we had in the last 2 posts (here and here), don’t worry. The web services topics will come back to wm-explorer soon. We really cannot have too many discussions on what seems to be the preferred integration mean between applications.
It’s the start of the year and this brings back in my mind different starts: of a project, of a task, of working with webMethods IS. And like in every start, a reasonable amount of work has to be invested in setup.
People starting with webMethods IS can include this series of posts in their setup as it aims to help them reach the next level faster and less painful.
In the interest of full disclosure, the series is based on my experience and my years working with webMethods IS. It is not endorsed by SoftwareAG, although I hope they like what is written here.
OK, so before we get started, let’s ask ourselves if there is really the need for Coding Guidelines in Integration Server? I, for one, think there is. My reasons are the following:
- there is no comprehensive guide on this topic from SAG*
- people think that FLOW language is easy and no guide is needed**
- it is easier for everybody is guidelines are followed (especially for those that end up maintaining your code)
*I am sure they have something in regards to this in their PRIME methodology and tool offerings but that information is not available, as far as I know, for anyone just starting with webMethods.
**Blindly starting coding, even in the easiest languages, is not recommended. It might be suited for exercises, proof of concepts and getting to know the language but it will certainly not fly when you write productive code. Going on this path leads to bad programming and making some nasty mistakes that will make your code harder to read and maintain, not to say error-prone.
The moment has arrived to dive into the first part of the guidelines: Naming Conventions.
We will deal here with the rules for naming the IS artifacts (packages, folders, services, etc..).
There are some general rules that apply, so I will mention them just once:
- English should be the standard language for naming
- names should contain only alpha-numeric characters
Please note that all the rules are valid for the cases where the developer has the control over the creation of the artifacts. For the cases where the code is generated (web service descriptors, REST endpoint services), it is better to leave the names as they were generated.
Why? Because changing generated code is never a good idea. It involves a large amount of work that will be lost anyway when the code is regenerated.
Package naming conventions
Below you can find an example of how the folders within the package should look like (seen from the Service Development view):
- cached – contains cached services
- doc – contains the document types defined for this package
- init – contains the startup services (startup is also a good name for this folder)
- pub – contains the public API of the package, i.e the services that are used by other packages
- pub/scheduler – contains scheduled services; in this way, it is easy to identify them
- service – contains only adapter services
- shutdown – contains shutdown services
- util – contains utility services that are used only from this package; if the service needs to be used by other packages as well it should be moved to a common services package
- ws/provider – contains Web Service Providers and the related artifacts
- ws/consumer – contains Web Service Consumers and the related artifacts
Of course, the list above is not final nor exhaustive. If it makes sense you can add more folders. You might want to add a folder that holds the REST resources. It can be named rs or resources.
You might also want to remove some folders from what I have presented above if they are not used. There is no added value in keeping empty folders.
A package should contain services and other artifacts that belong together. It is wise to keep the ratio of interfaces/package low. This is important for deployment purposes because if one interface changes you will need to deploy the whole package (i.e all the interfaces).
Please follow the below rules for naming the packages:
- The package name should not contain the word Package or abbreviations of this word. It is clear that it is a package. Do not overkill.
- The package name should be camel case, starting with an uppercase character. Can contain underscore if really, really needed.
- Packages that hold connections or document definitions can be named accordingly. This means they can have the suffix Connection, respectively, Document.
- It is OK to prefix the package name with a prefix that identifies the organization that owns the package.
- Packages should not start with Wm because this usually identifies packages from the standard webMethods distribution (ex: WmPublic).
- Packages that contain tests or non-productive artifacts can be suffixed with something like _TEST and must not be deployed to the Production environments.
Root folder name
On this topic, I have seen two major ways of naming the root folder (i.e the folder just below the package).
- Root folder has the same name as the package
People who like this usage claim that it is easy to identify a certain service or asset within a package. If you have the fully qualified service name you can easily navigate to it without the need to search.
- Using the Java-like naming convention
In this case, you use a prefix folder structure across all packages in the IS. This structure should have maximum 2 levels of depth and should be the inverse domain name of the organization.
Your organization: Mystery Inc. (you saw Scooby-Doo, right?)
Your organization site: www.mystery.com (I hope this is not some sort of shady site)
Root folder structures: com.mystery.accounting, com.mystery.invoicing
I prefer the second option because it resembles best with the standard of other languages (ex: Java) and because it eases refactoring. By using this option there will be no namespace issues when moving code from one package to another.
So my recommendation would be to go with the Java-like naming convention. In this way, you will have the same folder prefix for all the packages in your IS and you will differentiate below this prefix.
You can check below how the rules look like for the specified example.
Other naming conventions
Folder names should have a clear name that reflects their content and should contain only lowercase letters. (The underscore character is accepted, but should be avoided).
Service names must be camel case and start with lowercase letters (just like standard Java methods). Exception: the REST resources which are generated (_get, _post, _put, _delete, etc.) and should not be changed.
Variable names must be camel case and start with a lowercase letter. This is valid for variable names in both document types and service signatures. Also, document reference variables should follow this rule.
Document type names must be camel case and start with an uppercase letter. The document types in IS are similar to JAVA POJO’s, so they should respect the same rules. Also, use underscore only if you must.
You know what, do no use underscore. Name the assets in such a way that using underscore is not needed. This rule will help you in the namings and will certainly help me because I had planned to repeat it a lot in this section.
Flat file names must be camel case and start with an uppercase letter. Same goes for schema names and connection names. For the latter, if you have multiple connections it is a good idea to suffix the name with _NTX, _LTX, and _XA.
Adapter names must be camel case and start with a lowercase letter. Same goes for trigger names and web service descriptors.
Now I do realize that IS has more asset types that are presented here. I listed the most frequently used. If you have problems naming other artifacts you can ask yourself 2 questions: “How are such artifacts named in other programming languages?” and “What would be a suitable naming convention based on what I know so far?”.
To be honest, if you consider the naming conventions to be the boring part of any Coding Guidelines, I do not blame you. It is not the most dynamic part of the guidelines.
That’s why I want to offer you a Thank you! for sticking with me until this point.
Next posts we will dive deeper into some general, as well as specific (performance, security) topics and things will get spicier and more animated.
See you next time,