Java Business Service (JBS) Tutorial

As promised in the last article, this is a tutorial for Siebel professionals wanting to implement a JBS.

The full source code is available from my LinkedIn Group:Impossible Siebel, for those who want to start running quickly without the usual fiddling around with a new area of configuration.

The Siebel documentation provides some good high level information on the basics of a JBS, but there is no step by step details on how to implement it.

There are a lot of missing pieces that you just have to figure out yourself, and to make things harder, there is little chance we can get it running without Java knowledge.

This is illustrated by one customer who raised the following SR (ID: 490022.1), and asked all the right questions, but the explanation still didnt connect the dots, the author was obviously on a high plane, co-incidently the author who replied to this SR, is one of my favourite engineers on Support Web, Mr Pascal Kitaeff.

Complement of information about Java Business Service [ID 490022.1]

[JBS for Dummies]

Assuming that Siebel professionals dont speak Java, i'll attempt to translate.

Firstly why use a JBS? Using a JBS allows us to implement features that are not available out of the box. We can leverage all of the open source software that already been built and tested, and just plug and play in Siebel.

[Solution Overview]

1) Setup up the Java Subsystem
2) Implement a specialised eScript BS
3) Build a Java Class
4) Implement the program logic in Java

[Pre-requisites]

1. Download and install the Java SDK from http://developers.sun.com/downloads

Dont install this for fun, otherwise it will eat up valuable profile space on space restricted enterprise connected machines.

2. Download and install a JAVA IDE

Eclipse seems to be the most popular www.eclipse.org

or Netbeans, if you want to go for the Sun product
www.netbeans.org


[Setup up the Java Subsystem]

This is the easiest part. Go to your Client CFG file and create the following section
[JAVA]
DLL = <Program path>\jvm.dll
CLASSPATH = <Siebel Tools path>\CLASSES\Siebel.jar;<Siebel Tools path>\CLASSES\ImposSiebelXSLT.jar
VMOPTIONS = -Xrs -Djava.compiler=NONE


This can also be implemented as a Server profile configuration, see bookshelf for more information, but most developers will want to try this out on the local machine.

[eScript BS]

1. Create a BS based on the class: "CSSJavaBusinessService"
2. Call it "ImposSiebelXSLT Business Service"
3. Create a BS user property with the following values

Name: @class
Value: ImposSiebelXSLT

This BS will be barebones and just pass the method down into the Java class, where the real work will happen.

[Java Class]

If you havn't already done so, you need to have your SDK and IDE installed at this point.

1. Create a new project of type "Java Class Library" called "ImposSiebelXSLT"
2. Link the Siebel.jar file to your project libraries
3. Create a new class called "ImposSiebelXSLT"
4. Add the following code to import the required Clases

import com.siebel.data.SiebelPropertySet;
import com.siebel.eai.SiebelBusinessServiceException;
import java.io.*;
import javax.xml.transform.stream.*;
import javax.xml.transform.*;


5. Add the following code to inherit from the Siebel Business Service class

public class ImposSiebelXSLT extends com.siebel.eai.SiebelBusinessService {
    public void doInvokeMethod(String methodName, SiebelPropertySet input, 
                SiebelPropertySet output) throws SiebelBusinessServiceException {


6. Add the following code to perform the XSLT transformation

            StreamSource xmlSource      = new StreamSource(new StringReader(input.getValue()));
            StreamSource xsltSource     = new StreamSource(new StringReader(input.getProperty("XSLTBuffer")));
            Writer outWriter            = new StringWriter();
            StreamResult result         = new StreamResult( outWriter );
            TransformerFactory transFact = TransformerFactory.newInstance();
            javax.xml.transform.Transformer trans;
            trans = transFact.newTransformer(xsltSource);
            trans.transform(xmlSource, result);
            output.setValue(result.getWriter().toString());
            output.setProperty("ErrorMessage", ErrMsg);


7. Compile and place the Jar file into your classpath as defined in your configuration file above.

[Usage]

Now we can call the JBS like any other eScript business service, by passing in input and output property sets.

BS: ImposSiebelXSLT Business Service

[Input Property]
<Value>: XML String
XSLTBuffer: XSLT String

[Output Property]
<Value>: Transformed XML String

[Final thoughts]

Taking the the leap into JBS and using a entirely new XSLT parser can be a risky undertaking, it means that your entire application needs to be regression tested. This is the same problem Siebel would have to face, if it replace its XSLT engine.

So what should we do?

If you dont have any problems with your "EAI XSLT Service", it is best to leave it alone.

Customers who are affected by the 30 namespace problem have a few options as highlighted in the last article.

JBS's arent the solution to everything, but it provides a door to the open source community.

The Java package for this article can be downloaded from LinkedIn: Impossible Siebel

In the final article in this series, i'll look at implementing XSLT 2.0 in Siebel.

User Question: How to use an OR condition in a WF decision step

[Possible Siebel?]



A reader from Texas, US, asked "How to use an OR condition in Siebel workflow decision point".

[Answer]
By default, every WF condition is binded to the 'AND' operator.

To perform an 'OR' condition, compose a condition using the following values

Compare To: Expression
Operation: <Use the default>
Object: <Blank>
Field: <Blank>
Values: Enter your 'OR' expression in here

Eg.

Ultra browser script generator

This tool hardly needs an introduction; I'm talking about Siebel's "Genbscript.exe", which is a simple command line tool that allows us to generate browser scripts for our application. This is an indespensible tool for every developer and environment specialist.

A generic implementation is shown below

genbscript.exe <your config file> <browser script output directory> <language>

The problem with the above method is if there is an existing directory, genbscript.exe will not run, unless you first delete the existing directory.

When this happens you have to goto the browser script folder..



Find the duplicate folder among all the previous versions of the browser script directory, and delete it, which is more frustrating than it sounds.

Genbscript.exe is a black box command line utility, which has no visible hooks, but never to be one, to settle for standard features, i created some automation that got around the limitations of this tool.

I really had to stretch my batch scripting muscles to its limits for this exercise.

The result is "Ultra GenB", which is an enhanced batch program that will detect wether you've got a previous version of the browser script folder, deletes the folder in question, and, regenerates your browser scripts, all with 1 click.

There are only 3 parameters that you need to set.


::##############################################################################
::CONFIG
::##############################################################################
SET BSCRIPT_EXE=<Siebel folder>\Client\BIN\genbscript.exe
SET CFG_FILE=<Config file>.cfg
SET OUTPUT_DIR=<Siebel folder>\Client\PUBLIC\enu


I spent a whole day, just generating browser scripts over and over, so i guarantee your inner geek will have endless hours of fun with this tool.





The tool is free and is provided without any warranty, and can be downloaded from my LinkedIn Group: Impossible Siebel

Does anyone want to see a progress screen that actually shows you the working progress, and not just a blinking cursor?

EAI XSLT Service namespace limitation

If you've ever tried to use EAI XSLT Service to transform a XML message with more than 30 namespaces, you will get the following dreaded error.

"(xsltransform.cpp (564)) SBL-EAI-04267: XSLT Processing Exception: SAXParseException: An exception occurred! Type:RuntimeException, Message:The buffer manager cannot provide any more buffers"

Googlers will find this information useful, because this error is not documented on Support web, and unless XML is prolific in your Enterprise, you are not likely to run into this problem.

[Root Cause]

Since Siebel is a packaged software, it is not well known that it uses the Xalan 1.5 engine to transform our XML, but this fact can be verified by the existence of xalan-c_1_5_0.dll in the Siebel Tools/BIN folder.

A quick search of the web seem to yield no problems with namespaces with this XSLT engine, so its up to us to dig further into this problem.

If we start by isolating the Xalan component, and see if we perform the XSLT transformation directly using the Xalan DLL, we can test for this namespace limitation and determine if this is a Siebel or Xalan problem.

You can still find the Xalan 1.5 engine on the web; if you want to try it out, go over to the Apache website and download it from the archives.

http://archive.apache.org/dist/xml/xalan-c/binaries/

Finding a Xerces parser compatabile with this engine was more of a challenge, since Xalan 1.5 is obsolete, no archive is kept of the parser.

After 15 minutes of fruitless searching, it occurred to me, that i can use the Xerces DLL from the Siebel directory.

[XSLT transformation with Xalan]

1. Download the Xalan 1.5 binary from Apache.Org
2. Extract the ZIP into any directory
3. Goto your Siebel Tools/BIN folder and copy the xerces-c_2_2_0.dll to the Xalan release folder
4. Supply a XML file with more than 30 namespaces
5. Supply a XSLT file
6. Run the transformation

If you've followed the above steps, you should get the following error.



Bingo!, its the exact same error that we recieved in Siebel.

This is very interesting, so does the problem still occur with the latest version of Xalan?

I used Oxygen 8.2 which comes with the latest Xalan 2.7, and it passed the 30 namespace test.

So we can confirm that this defect is caused by the Xalan 1.5 engine (Oracle engineers take note).

But since this engine is a core part of the product, dont bet on it being upgraded any time soon. Defects in the core Siebel product cannot be easily fixed, so what options does the hapless customer have?

1. [Reduce namespaces in XML]

You can try requesting for your Enterprise to reduce the number of namespaces that is sent to your Application, although this is out of your control, it is worth trying.

2. [Strip out the unused namespaces before transformation]

The idea is that you pass your incomming XML message to a BS utility to strip out the un-needed namespaces, and pass it to the EAI XLST Service for transformation, ensuring that it has less than 30 namespaces.

The above two methods have the following advantages
1. Can be implemented quickly
2. Has very little impact to testing

but it has the following disadvantages.
1. Not scalable
2. Namespaces can change adding to maintenance
3. All namespaces may be needed
4. Different namespaces may be needed for different messages

3. [Use external transformation engine]

An alternative is to replace the default Siebel Xalan engine and use an external transformation engine.

This allows us to bypass the limitations of the standard EAI XSLT Service, and it also provides us access to a more modern XSLT parser.

To achieve this, Siebel provides us with a few mechanisms to extend vanilla functionality by calling on external code.

1. SElib.dynamicLink
2. EAI DLL Transport
3. Java Business Service (JBS)

Although we can use any of the above, methods to call external code. I'll look specifically at using a the JBS option to workaround this product defect, because all the tools and software needed are free and open source.

Using a JBS to call a more modern XSLT parser, will allow our transactions to be more efficient, as well as offering the latest methods available in the XSLT standard.

This is exciting stuff so put that holiday on hold, until this comes out.