Service Taxonomy and Requirements

Having seen how organizations can struggle with it, convinced me that before you start to capture the requirements of a serious amount of services, you rather have a proper classification scheme identified up-front. A service taxonomy as such a classification scheme is called, is important for a couple of reasons:

• The requirement attributes are likely to differ somewhat between classes, making that you might want to use different templates,
• A service taxonomy supports a proper positioning of services in the application and technical architecture,
  
• A service taxonomy supports a proper layering of services.

There is no single best taxonomy, as it depends on aspects like the number of services, and the nature of those services. However, a good starting point could be a classification like the following one.

First of all the following (more or less atomic) classes of services can be distinguished:

Business Services that are recognized as such by the business, like Retrieve Customer Profile, Print Order Confirmation.

Data Services that query or store data, like Retrieve Customer, Retrieve Customer Orders, Update Order.

Application Services, being all other services, like Print File and other 'utility' services.

The above classes concern atomic services, meaning that the services have a restricted, clear responsibility and therefore in principle are re-usable. When used in the context of use cases (or business processes) they typically will not cross steps.

Whenever applicable, you can also recognize Process Services as being the type of services that deal with service orchestration. Process services typically have a specific use case / business process as a scope. That use case can be a user-goal or summary use case (spanning multiple lower level use cases).

Batch Services are a specific kind of orchestration services that process multi-record messages in an asynchronous way.

Other Taxonomy Aspects

Your taxonomy can leverage more than one kind of classification, for example one that organizes business and process services by business domain.

Also different levels of services could be distinguished. This is where we talk about service granularity. For example, a higher level data service Retrieve Customer Data can consist of two lower level services Retrieve Customer and Retrieve Customer Address. The level of a service won't have much impact on the way you specify it functionally though. Also, specifying finer grained services is more likely to be the subject of analysis and design rather than requirements definition. The discussion about service granularity for requirements definition is likely to be that of user-goal versus summary use cases.

Be aware that the taxonomy you use during requirements does not necessarily need to be 1:1 with the one that is used for analysis and design. The meta-requirement for the taxonomy used during the requirements definition, is that it should be recognizable by business people. There should be a clear mapping to the taxonomy that you will use during analysis and design, though.

Generic Requirement Attributes

The requirement attributes of all service could consist of the following:

• name
• purpose (one, two sentences max)
• description (what does it functionally, i.e. without getting technical)
• type (within the taxonomy)
• triggering events
• pre-conditions
• post-conditions
• synchronous/asynchronous (request/response vs fire & forget)
• message format in
• message format out
• list of values (for attributes where applicable)
• transformation
• validation of incoming message
  
• list of (logical) errors that can be the result
• metrics
• business indicators (e.g. to collect BAM metrics)
  

Typical standard pre-conditions (that you might decide not to specify but capture as an architectural principle) are:

• consumer has been authenticated and authorized to use the service
  
• message format in complies to the XSD, meaning failing to do so will result in technical error

Message format in and out have the following sub-attributes:

• structure
• attribute names
• data type
• format mask
• mandatory

Attributes can also have a list of values that applies. List of values can be static (i.e. a list of fixed values, typically implemented in XSD) or dynamic (to be implemented with DB-query). Static list of values should not be captured in the service descriptions itself (for reasons of maintainability) but in a separate document.

Transformations typically are captured using a two-column-format, one column describing the "query" (just one source attribute, or multiple attributes with some operations), the other the target attribute.

The validations to specify concern checks that are not considered to be part of the pre-conditions.

Metrics can have the following sub-attributes:

• average calls/per time unit
• peak volumes
• max response time

A service can call one or more other services, each having their own message format in and out and transformations involved in that, which then also needs to be specified.

Specific Attributes

In case of Data Services also the following attributes can be applicable:

• data source (name of the database, or other)
• a (restricted) data model
• key attributes
• (logical) query, insert or update statement

Application and Batch Services typically also can have the following attribute:

• algorithm

Process Services also have a process orchestration that is described using an activity diagram (preferable using the BMPN notation) or a sequence diagram. Process Services often have a human interaction being involved.

Generic Supplemental Requirements

In case of asynchronous services you are likely to have a need for an "error hospital". Preferably you have some generic mechanism for that. For each individual service you then only need to specify how long and with what frequency a retry needs to be done, before it will end up in the error hospital. The requirements for the error hospital itself will be generic, describing how a systems or application administrator can cancel or retry the service (when possible).

Other generic supplemental requirements might concern:

• audit requirements
• logging
• security

Per service you only specify how the generic mechanisms apply.

Oracle BPM Enterprise 10gR3 for WebLogic on XP

Officially Oracle BPM Enterprise 10gR3 is not supported on Windows XP. When you try to install it using the default path, you probably will experience some exceptions like a ClassDefNotFound or an IllegalStateException. So what to do when you're bound to XP but want to juggle with BPM Enterprise nevertheless? This is how I did it. But remember it's not supported, so don't start complaining when it does not work for you.

What I did was to run the installer up to the point where it asks you to start the configuration wizard, and then quit. The configuration wizard offers the option to install a WebLogic Server (WLS) for you. However, I created a WLS domain myself, with only an admin server and no managed server, and called it OBPM (but you can call it DonaldDuck or whatever you like). Once successfully created, I started the server.

The OPBM Enterprise configuration wizard has an option that let's you choose to change an existing WLS domain rather than to create a new one, to deploy the process engine and web applications on. So I chose my OBPM domain.

The ClassDefNotFound error I prevented by not choosing to install the Oracle BPM transport provider. You can install it later, and perhaps when you concentrate on that, the ClassDefNotFound error can be tackled as well. I did not yet get that far. I explicitly configured the tablespaces of the engine and directory schema's, but had to key in the names in upper case (e.g. in my case USERS and TEMP, instead of users and temp), otherwise the installation of the schema's failed telling me that the tablespaces did not exist. Weird.

Anyway, using the installation path as I described above, resulted in a flawless installation on my XP Professional

Need to know more? Check out the Oracle BPM 10.3 Configuration Guide.

Dynamically Switching Rules Dictionary Versions

Suppose that you are using Oracle Business Rules in a Java application. And suppose you want to be able to change and test your rule set without bothering other people. Wouldn't it be nice to be able to work in a copy of a dictionary and activate that only for your user session? This can be achieved as follows.

I assume one dictionary of which there can be multiple versions. Of course the same principle can be applied to multiple dictionaries.

First implement some mechanism for storing the default version of the dictionary, and that will be retrieved every time before calling the rules repository. I use a properties file for that, because you can change a properties file dynamically. Then have some page from which the user can pick an available version from a list. Once a version has been chosen that differs from the default, that will be the version used for that user session.

Now how to get the versions of a dictionary from a repository? That can be done using the following Java code snippet, which is based on a WebDAV repository:


// repositoryURL is a String containing the URL to your repository
// rulesDictionaryName is a String containing the name of the dictionary

RepositoryType repositoryType =
RepositoryManager.getRegisteredRepositoryType("oracle.rules.sdk.store.webdav");
RuleRepository rulesRepository =
RepositoryManager.createRuleRepositoryInstance(repositoryType);
RepositoryContext repositoryContext = new RepositoryContext();
repositoryContext.setProperty("oracle.rules.sdk.store.webdav.url", repositoryURL);
rulesRepository.init(repositoryContext);

dictionaryVersions = rulesRepository.getMarkerNames(rulesDictionaryName);
for (int i=0; i < dictionaryVersions.size(); i++)
{
dictionaryVersions.set(i, ((String)dictionaryVersions.get(i)));
}


When the test was satisfactory, the chosen version can be stored in the properties file, making the default for every new user session.

Moving a WLS Domain

The following describes how to move your own sandbox kind of WebLogic Server domain. This method is not supported and should not be used to move any other kind of domain. It is also not guaranteed that any applications deployed on it, will move flawlessly with it. And it I tried it only on Windows.

So why describe it anyway? Well, just like me, you might have not payed attention when creating a domain and it therefore may have ended up in your product home directory. And you might, just like me, be too lazy to want to run the wizard and create a new one. Not that it is so much more work to do so. Finally, just like me you might be interested to know where WLS stores this kind of information.

Moving a domain can be done as follows:

• Copy the domain directory and everything under it, to the location where you want it to be
• Search all the files in the domain directory for the fully qualified path name where the domain was located (e.g. d:\oracle\product\bea\domains\MyDomain, and replace that by the fully qualified path name where you want the domain to be (e.g. d:\wls\domains\MyDomain). You will find a couple of files, among them .cmd files.
  
• Find the nodemanager.domains file (in my case in the d:\oracle\product\bea\wlserver_10.3\common\nodemanager\ folder). Find your domain in there and modify that manually (e.g. to d\:\\wls\\domains\\MyDomain)
• Finally, change the short-cuts to start and stop your domain to point to the correct locations.
  

That did it for me!