Example: Creating a Service

A sample service is provided to illustrate how to write a basic service for Sterling B2B Integrator.

Files for the test service are contained in the installTestService.jar file. After you install the jar, you will have a custom service named BTI Service created. Make sure the file has the following structure:


META-INF
   MANIFEST.MF
testservice
   jars
      testservice
         1_0
            testservice.jar
   bpml
      testFileService.bpml.in
   servicedefs
      TestServices.xml
   TestFileService.java
   serviceinstances.xml

These files are explained in the following sections.

Service definition

The service definition defines the service. The TestServices.xml file contains the definition for the service.

It has important information like the implementation class of the service and the type of service. In this example, type=”Basic” defines it as a service, and not an adapter.

Service Instance

The service instance defines an instance of the service. The serviceinstances.xml file contains the service instance. It has information like the display name and the target of the service. Because you can manually define a service through the user interface, this file is optional.

Implementation of the service

The Test service is implemented in Java. It requires some JAR files delivered in Sterling B2B Integrator. For most services, including this one, the following JAR files are needed:.

  • install_foundation.jar
  • platform_afc.jar
  • platform_baseutils.jar
  • platform_ifcbase.jar
  • platform_security.jar
  • platform_asi.jar

These files are obtained from the Sterling B2B Integrator installation directory. For example, the platform_asi.jar file is located in the <Install_Diretory>/ jar/platform_asi/1_3 folder.

Class definition

The file testservice.jar provides the class definition. This JAR file contains one file namedcom/sterlingcommerce/wordstock/testservice/TestFileService.class. When installed, this file will be appended to the <Install_Directory>/dynamicclasspath.cfg file.

Details for the test service

The test service needs to implement an interface called IService. This is done with the line:

public class TestFileService implements IService {…}

At the start, the Test service calls method harnessRegister() in the WorkFlowContext.java file to register the thread for this service so we know that the workflow is executing this service. At the end, the service calls unregisterThread() to unregister the thread so we know that a workflow is not executing the service.

Other methods can also be called:

  • Call method getParm(..) to get the parameters passed to the workflow.
  • Call method Manager.getProperties(..) to get the properties in a property file.
  • Call method getPrimaryDocument() to get the primary document passed from the previous service,
  • Call method putPrimaryDocument(..) to make a document the primary document.
The test service can perform two functions, depending on the parameter action passed to the service from workflow.
  1. Action FS_EXTRACT is for writing the content in primary document to a file in disk.
  2. Action FS_COLLECT is for getting the content of a file in the disk and writing it to the document then making it a primary document.
For details, see the TestFileService.java file.

Workflow to test the Test service

The file testFileService.bpml.in is a test workflow for testing the service. When run, it gets the primary document from the user interface, and then writes to a file in the disk. Then it reads the newly generated file, writes to a document, and makes it the primary document.

Installing and using the Test service

  1. Use the InstallService.sh or Install Service.cmd file to install the installTestService.jar file. For information about the InstallService file, see bin Directory Files.

    A service called Simple Test File Service will be created. The new service has type TestFileService.

    A workflow (business process) called TestFileService will also be created.

  2. After installing the service, review the <Install_Directory>/documents/testFileService.txt file. Look at the details of each step to help understand the Test service.
  3. Run the TestFileService business process, and you will see that a document is created in the <install_dir>/documents folder.

Creating a custom service or adapter

To create your own custom service or adapter:

  • Use the sample files contained in the installTestService.jar file, as shown below, as your starting point and modify them as needed to meet your business purposes. 
    
META-INF
   MANIFEST.MF
testservice
   jars
      testservice
         1_0
            testservice.jar
   bpml
      testFileService.bpml.in
   servicedefs
      TestServices.xml
   TestFileService.java
   serviceinstances.xml
  • You can change the first level directory name testservice to another name that better describes your service or adapter.
    The following directory and file names can also be changed:
    • testservice (subdirectory of jars)
    • 1_0
    • testservice.jar
    • testFileService.bpml.in
    • TestServices.xml
    • TestFileService.java
    • serviceinstances.xml

    Do not change the file extensions.

  • Do not change the following directory names:
    • jars
    • bpml
    • servicedefs
  • When finished modifying the files, compress them into an appropriately named JAR file.

    The TestFileService.java file does not need to be located in the JAR file. In the sample Test service, it was added there for convenience.

  • Install and test your new service or adapter as needed.