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:

http://www.ibm.com/support/knowledgecenter/SS3JSW_5.2.0/com.ibm.help.manage_svcs_adpts.doc/CS_AboutAddingNewSvcToSI.html

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/Setup
• instance: Instance level parameters will be only specific for one instance of your service. They are configured in the dashboard under Deployment->Services->Configuration
• wfd: 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

/support/pages/node/1121811

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