Technical Blog Post
Abstract
Writing Custom Services in IBM Sterling B2B Integrator
Body
How to write a custom service for IBM Sterling B2B Integrator
Disclaimer: Writing a custom service is nothing for the fainthearted. You need a reasonable amount of Java coding skills, a bit of XML as well. Since your code will run as a service you have to pay special attention to the fact that your code will run inside the ISBI virtual machine. This means that you have to pay special attention to prevent
- Memory Leaks
- Thread Leaks
- FileHandle Leaks
- Socket Leaks
If you do not pay attention there is a possibility to exhaust the ressources of the JVM and bring ISBI to a stop. If you are unsure do not hesitate to ask your sales rep for assistance by IBM Lab services.
Introduction
In this blog entry I would like to present a sample service that creates random numbers. The random numbers are generated just by the JVM so they are not perfectly random I assume. Please do not use this example for any cryptographic implementation or other mission critical applications. This sample should show you how a custom service can access values from the process data and how it can write a result back to process data.
The sample code for this can be found on GitHub: https://github.com/IBM-Commerce-B2B-Partner/randomService
There is also some documentation about custom services in the product documentation to be found:
A service in Sterling Integrator is at least one Java class that implements an interface from Sterling Integrator. In addition to that you have a deployment descriptor that tells the installer during runtime which service you are trying to install. It also tells the system the name of the class that is the entry point into your custom service. If needed, you can also add i18n/l10n files to make your service available in different languages. In the starting class you will have to have a method called processData(). The signature of this method comes from the com.sterlingcommerce.woodstock.services.IService
Interface. In that method you receive the com.sterlingcommerce.woodstock.workflow.WorkFlowContext
from the business process. It does contain references to the documents and you can access the process data elements.
Deployment Descriptor
The deployment descriptor is located in the servicedefs
subdirectory.
It defines the name of the service, it has a description and a label. The description and label are just references to the language property file that is located in the files/properties/lang/en/
directory. This allows you to have language property files for different languages. You can put different language files in different sub-directories and you will have an l10n. The deployment descriptor also has the name of the starting Java class in your custom code. Further on you will find the VARS sections. There are 3 VARS sections. They represent the hierarchy in which the variables are evaluated during runtime:
global
: This allow you to set values across all service instances of this type. They are configured in the dashboard in Deployment->Services->Installation/Setupinstance
: Instance level parameters will be only specific for one instance of your service. They are configured in the dashboard under Deployment->Services->Configurationwfd
: Here you define the kind of variables that you set during runtime the business process
The processData Method
The method processData is the main entry point into your service. In this method, you can use several different ways to access data from process data or documents. Some of them are explained in this blob post
See the example code to learn how you can access values from process data and how to write data back.
Sample Service Instance
In the base directory you will find a serviceinstances.xml
file. This file can be used to automatically create instances during the installation
Sample business process
In the directory structure you will find a subdirectory called bpml. All BPML files in this directory will be installed together with the service.
Inventory List
So let us summarize what you need to write a service in ISBI. This list contains all the necessary elements and will be explained in the following article.
- A working directory where you place all the files. It will have a mandatory filesystem layout that must be followed.
- An editor that can be used to edit java source files, text files and XML files.
- A Java JDK with compiler. Recommendation: Please use the exact same level of the JDK that you also use to run ISBI. If you develop/compile on the same box where ISBI is installed you might consider using the ISBI builtin JDK.
- A set of Jar files from your ISBI Installation. Since the custom service should run with your version of SI, you should also use ISBIs libs to compile against. It is a good practice to recompile the service, every time you apply a patch to ISBI
- Since building an service has quite a lot of steps, you might want to evaluate using a build tool that helps you with this process. This example will be based on ANT, but you can of course use other tools. The Ant file will give you an idea about how the resulting archive should look like
What to do next
- Check out the sample code from github and review the sample code.
- run the ant command to build it.
- Install it on a test system using InstallService.sh/cmd
UID
ibm11121403