View Only

Configuring Business Process as a Service (BPaaS) in Sterling B2B Integrator Certified Containers

By Connor McGoey posted Tue January 07, 2025 04:05 PM

Like

Configuring Business Process as a Service (BPaaS) in Sterling B2B Integrator Certified Containers

Introductory Notes

Products

IBM Business-to-Business Integrator (B2Bi) "streamlines complex B2B and electronic data interchange (EDI) processes across partner communities within a unified gateway".

IBM Sterling File Gateway (SFG) is a file transfer consolidation system that provides scalability and security. SFG can intelligently monitor, administer, route and transform high volumes of inbound and outbound files.

Intent

The purpose of this blog is to provide non-production details on how to configure BPaaS in B2Bi/SFG certified containers and provide simple use cases for BPaaS. Unless IBM documentation is referenced, each step covers all information necessary to deploy with this configuration. If your deployments need specific information not covered in this blog or if you wish to learn more about some of the installation steps, refer to the Resources subsection for additional resource links.

This blog will cover configuring different APIs for two separate business partners:

- - Two unique APIs, one for each business partner, both of which will map to the same Business Process Validation_Sample_BPML_Sync.
  - A third API that will map to a Business Process HelloWorld_Sync and be accessible to both business partners, but with different HTTP request method permissions for each partner.

Presumptions

Prior to following the installation steps in this blog, it is important to note that the environment and resulting deployments should not be used to replicate and/or produce a production environment for B2Bi/SFG. Additionally, a few presumptions are made with regards to these installations and their steps:

- - A SFG or B2Bi deployment to exist and be accessible from your cluster. In my case, I will use the SFG deployment I previously deployed in my blog "Installing IBM Sterling File Gateway and ITX / ITXA on Red Hat OpenShift Using Certified Container"
  - These instructions were developed on an OpenShift cluster running in the IBM Cloud. However, kubectl commands have also been provided and the instructions should work in Kubernetes as well.
  - While this blog is focused on containers, BPaaS also works in a non-containerized deployment, i.e., the instructions in this blog pertaining to configuring BPaaS within a preexisting B2Bi/SFG would still work.

Configuration Order

Business Processes that will be mapped to a BPaaS API are required to adhere to two rules:

- - The Business Process must be defined to run synchronously. That is, it should have the option Use BP Queuing unchecked in its options.
    - This means that all APIs exposed by BPaaS will run synchronously and will wait for a response from the Business Process before returning. However, the Business Process invoked by BPaaS could be set to return a Business Process identifier of some child Business Process spawned by the BPaaS Business Process which would get put onto the Business Process queue. This is out of scope for this blog.
  - The Business Process must be enabled.

The Business Processes that BPaaS will map to must exist prior to mapping them via a Helm upgrade. The order for configuration is as follows:

1. 1. Configuring Synchronous Business Processes
  2. Configuring the BPaaS property files in the Helm chart
  3. Performing a Helm upgrade
  4. Providing necessary user permissions to the BPaaS APIs

Helm

This blog uses Helm v3.14.3 but will work with any Helm version >= 3.13.x. With regards to B2Bi or SFG, using a different/older version of Helm may change how the charts should be handled. For issues regarding Helm, refer to the Helm documentation on how to install Helm and the commands available to you via the Helm CLI. IBM's B2Bi version 3.0.1 Helm chart and SFG version 3.0.1 Helm chart are available under the Resources subsection. For the purposes of this blog, Helm allows for automating the containerized upgrades of B2Bi or SFG when used in conjunction with a provided and configurable YAML file and Helm chart. The YAML file is used to define relative configuration for the charts. The key here is to ensure that the file properly defines the necessary deployment configurations that fit your needs.

A Note on BPaaS Business Processes

This blog will use two built in Business Processes (Validation_Sample_BPML and HelloWorld) and update them to work with BPaaS by making them run synchronously.

All BPaaS Business Process can optionally make use of custom request and response headers. The Business Processes used in this blog will not cover these topics. For more information on these features and how to configure BPaaS and the Business Processes to use request and response headers, refer to the BPaaS documentation.

Configuring Synchronous Business Processes

Because this is a development environment, I will be using two Business Processes that come preconfigured in B2Bi/SFG. These two Business Processes are Validation_Sample_BPML and HelloWorld. Validation_Sample_BPML is a sample Business Process that is used to validate that B2Bi was properly installed. The HelloWorld Business Process is another "do nothing" Business Process I am using for demonstration purposes.

However, both Validation_Sample_BPML and HelloWorld are predefined to run asynchronously. Since BPaaS requires synchronous Business Processes, I will create near-identical copies of the two, only changing the queuing options.

First, within my B2Bi/SFG user interface I will navigate to Business Processes > Manager under the Administration Menu sidebar. I'll then search for the Validation_Sample_BPML Business Process:

I will then click on the Validation_Sample_BPML Process Name which opens a popup window with the BPML definition. I'll copy the BPML code to a file on my local machine called Validation_Sample_BPML_sync.bpml. B2Bi Business Processes require the process name tag to match the name given in its definition within B2Bi/SFG. So, in the file I'll change the name of the process from Validation_Sample_BPML to Validation_Sample_BPML_Sync. The resulting BPML file is below:

<process name = "Validation_Sample_BPML_Sync"> 
  <sequence>
    <operation name="File System Adapter">
      <participant name="FS_InstallValidation"/>
      <output message="FileSystemInputMessage">
        <assign to="Action">FS_COLLECT</assign>
        <assign to="appendOnExtract">true</assign>
        <assign to="deleteAfterCollect">false</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>

    <operation name="File System Adapter">
      <participant name="FS_InstallValidation"/>
      <output message="FileSystemInputMessage">
        <assign to="Action">FS_EXTRACT</assign>
        <assign to="appendOnExtract">false</assign>
        <assign to="deleteAfterCollect">true</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>

  </sequence>
</process>

I then repeat the same steps with the HelloWorld Business Process, creating a file named HelloWorld_sync.bpml and renaming the process with the BP to HelloWorld_Sync. The resulting BPML file is below:

<process name = "HelloWorld_Sync"> 
  <sequence>
    <operation>
      <participant name="XMLTransformer"></participant>
      <output message="parseRequest">
        <assign to="xml-document-text">
          <![CDATA[<data>Hello World!</data>]]>
        </assign>
      </output>
      <input message="parseResponse">
        <assign to="data" from="xml-document/data/node()"></assign>
      </input>
    </operation>
    
    <operation name="XSLT Service">
      <participant name="XSLTService"/>
      <output message="XSLTServiceTypeInputMessage">
        <assign to="input_pd_xpath">/</assign>
        <assign to="xml_input_from">ProcData</assign>
        <assign to="xml_input_validation">NO</assign>
        <assign to="xslt_name">HelloWorld</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
  
    <operation name="HttpRespond">
      <participant name="HttpRespond"/>
      <output message="HttpRespondInputMessage">
        <assign to="doc-has-headers">false</assign> <!-- Implying non-raw mode by default. --> 
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
  </sequence>
</process>

I then create the two copy Business Processes. Starting with Validation_Sample_BPML_Sync, I navigate to Business Processes > Manager > Create > Process Definition > Go!. I will give the name I provided inside of the BPML file (Validation_Sample_BPML_Sync) and click the Business Process Text Editor option for defining the process. The description I give is "Synchronous copy of Validation_Sample_BPML". Then, in the box below I copy the contents of Validation_Sample_BPML_sync.bpml:

I then click Next which brings me to the Process Levels page. Here, I change the Use BP Queuing (recommended) option from checked to unchecked, this will make the Business Process run synchronously and must be done to make it compatible with BPaaS:

I then continue clicking Next until I am brought to the Confirm page, where I ensure that beside Start Mode I see sync:

I then click Finish to create the Business Process.

After creating the Validation_Sample_BPML_Sync Business Process, I repeat the steps above with my HelloWorld_Sync Business Process.

Configuring BPaaS Property Files

I now need to make two property files and place them inside my B2Bi/SFG Helm chart within the /config folder. The /config folder is in the first level of the chart. The two files that need to be placed inside of the Helm chart are bpaas.properties and bpaasmapping.properties.

bpaas.properties

This properties file is used to configure the overall BPaaS configuration. I will leave everything default which means I will copy the contents of the bpaas.properties file provided in the B2Bi/SFG docs and place it inside my config folder (/config/bpaas.properties).

Throttling / Rate Limiting

Within the bpaas.properties file there is a workerthreads property. This property is used to determine how many threads each BPaaS server will allocate for running Business Processes:

"If all the threads are busy, any request to run the BP is rejected and a 503 error code is sent to the client. Therefore, you must configure the workerthreads parameter based on the maximum number of BP executions expected at any point of time."

In other words, there can only be up to {workerthreads} (30 by default) Business Processes triggered by BPaaS running at once.

Note: The Business Process limit is shared across all APIs.

It is also important to note that if the Business Processes are long running, it will be easy for the available threads to fill up.

bpaasmapping.properties

The second file that I need to place into my /config folder within the B2Bi/SFG Helm chart is bpaasmapping.properties which maps API endpoints to a Business Process. A mapping in this file has the following format:

<API Name>.mapping=<Business Process Name>,<Version>

All Business Processes are versioned using integers starting with 1 from the creation of the Business Process and incremented with every new definition. You can find the Business Process versions by locating your Business Process under Administration Menu > Manager, searching for the Business Process, and then clicking the "Info" button next to the version. You will see the version of the Business Process in the top right of the popup window:

If no version is specified for the Business Process in your bpaasmapping.properties, then the default version will be used.

In addition to mapping Business Processes, each API defined has the following optional properties:

- - .disablehttpmethods - specify HTTP methods that you want to be disabled (ex. PUT, DELETE) for a given API.
  - .skiprequestheaders - specify any request headers sent by an API request that will not be forwarded to the Business Processes' instance data. If not specified, the default from bpaas.properties will be used.
  - .bpexecutiontimeout - specify the timeout for a Business Process execution in milliseconds. If not specified, the default from bpaas.properties will be used.

For example, if I wanted to create an API with an endpoint of myexampleapi, map it to a Business Process I defined called MyExampleBusinessProcess, give it a timeout of 80000 milliseconds, and disable the DELETE HTTP method, I would add the following three lines to my bpaasmapping.properties file:

myexampleapi.mapping=MyExampleBusinessProcess

myexampleapi.bpexecutiontimeout=80000

myexampleapi.disablehttpmethods=DELETE

For my environment I will create three different APIs in the properties file and leave out the optional disablehttpmethods, skiprequestheaders, and bpexecutiontimeout properties.

The three API definitions map to the two synchronous Business Processes Validation_Sample_BPML_Sync and HelloWorld_Sync from previous steps. I'll add the following three lines to the file and save it:

somepartnervalidation.mapping=Validation_Sample_BPML_Sync

someotherpartnervalidation.mapping=Validation_Sample_BPML_Sync

helloworld.mapping=HelloWorld_Sync

After saving the two property files in the Helm chart, I am now ready to perform a Helm upgrade.

Performing a Helm Upgrade

To perform the Helm upgrade, I navigate to the chart I used to install B2Bi/SFG (and the same chart I placed the /config/bpaas.properties and /config/bpaasmapping.properties files in) and ensure that the override.yaml is properly set for an upgrade by changing the following values:

dataSetup.enabled: false

env.upgradeCompatibilityVerified: true

setupCfg.dbCreateSchema: false

Once done, I run the following command :

helm upgrade <SFG/B2Bi Release Name> --namespace <SFG/B2Bi Namespace> --timeout 90m0s -f override.yaml <Path to Helm Chart>

Where <SFG/B2Bi Release Name> is the name of my existing B2Bi/SFG release, <SFG/B2Bi Namespace> is the namespace it is in, override.yaml is the same YAML file I used to do the initial install (or most recent upgrade), and <Path to Helm Chart> is the path to the chart which could be . if you are running the command from within the Helm chart.

Providing BPaaS API User Permissions

To use the BPaaS APIs users will pass their B2Bi/SFG username and password as basic authentication during the API call. Users need permissions in B2Bi/SFG to be authorized to use these APIs.

By default, no users aside from B2Bi/SFG super users have permission to call any BPaaS API as each new BPaaS API requires its own set of custom permissions, i.e., all BPaaS APIs (and therefore all its HTTP methods) are locked by default to all users except for user assigned to the Sterling B2B Integrator Admin group. So, unless more users are added to the Sterling B2B Integrator Admin group, only the admin and fg_sysadmin will have access to the BPaaS APIs.

Note: All users belonging to the Sterling B2B Integrator Admin group are automatically given all preexisting and new permissions defined in B2Bi/SFG.

The following steps assume you have two business partner user accounts in your B2Bi/SFG server. In my case these will be referred to as partner1 and partner2.

Note: In a production environment these user accounts partner1 and partner2 would be accounts mapped to business partners in your network.

The permissions take the format of <API Name>/<Permission> where <API Name> is the name of the API given in bpaasmapping.properties and <HTTP Method> is one of:

- VIEW - maps to the GET HTTP method
- CREATE - maps to the POST HTTP method
- DELETE - maps to the DELETE HTTP method
- UPDATE - maps to the PUT HTTP method

In my configuration I will provide the following permissions:

- partner1: GET access to the somepartnervalidation API, and both GET and PUT access to the helloworld API.
- partner2: GET access to the someotherpartnervalidation API and only GET access to the helloworld API.

So, I will create these permissions:

- somepartnervalidation/VIEW
- someotherpartnervalidation/VIEW
- helloworld/VIEW
- helloworld/UPDATE

To accomplish this, I navigate to the Permissions page under the Accounts subsection in the Administration Menu. Here I will click the Go! option next to Create a new Permission. I'll then create four new permission definitions in B2Bi/SFG. For simplicity I'll give the Permission ID and Permission Name the same value and select Other as the Permission Type.

Below is the definition for somepartnervalidation/VIEW, which I will repeat for the other three:

Making and Validating BPaaS API Calls

To make API calls to the BPaaS APIs I have configured, I will need to obtain the route for BPaaS which was created by Helm during the upgrade. To obtain the route I can run either of the following commands from within my B2Bi/SFG namespace:

oc get routes -o wide | grep /bpaas

kubectl get routes -o wide | grep /bpaas

For me, the URL is api.us-south.containers.appdomain.cloud/bpaas/v1.

BPaaS API URL format is <BPaaS URL>/<API Name>. This means that my BPaaS API URLs are:

- api.us-south.containers.appdomain.cloud/bpaas/v1/somepartnervalidation
- api.us-south.containers.appdomain.cloud/bpaas/v1/someotherpartnervalidation
- api.us-south.containers.appdomain.cloud/bpaas/v1/helloworld

To test the BPaaS APIs, I will use cURL commands. However, you can use any other platform to call your BPaaS APIs such as Postman or Insomnia.

Partner 1

Recall that partner1 can make GET requests to somepartnervalidation, GET requests to helloworld, and PUT requests to helloworld. However, partner1 does not have any access to someotherpartnervalidation as it is only for partner2.

First, I will make a GET request to somepartnervalidation (Note: the -i flag is used to include the HTTP response headers in the response):

curl -X GET -i -u "partner1:<partner1 Password>" http://api.us-south.containers.appdomain.cloud/bpaas/v1/somepartnervalidation

In the response headers I see the HTTP/1.1 200 OK code which tells me it was successful. Below are some more requests that return a 200 OK response due to proper configuration and permission:

curl -X GET -i -u "partner1:<partner1 Password>" http://api.us-south.containers.appdomain.cloud/bpaas/v1/helloworld

curl -X PUT -i -u "partner1:<partner1 Password>" http://api.us-south.containers.appdomain.cloud/bpaas/v1/helloworld

However, the following return a 403 Forbidden error:

curl -X PUT -i -u "partner1:<partner1 Password>" http://api.us-south.containers.appdomain.cloud/bpaas/v1/somepartnervalidation

curl -X GET -i -u "partner1:<partner1 Password>" http://api.us-south.containers.appdomain.cloud/bpaas/v1/someotherpartnervalidation

curl -X DELETE -i -u "partner1:<partner1 Password>" http://api.us-south.containers.appdomain.cloud/bpaas/v1/helloworld

The above requests also return an error message "error":"User does not have permission on API" which indicates partner1 does not have permission to make those HTTP requests to those APIs. This aligns with my configuration.

Partner 2

Similarly, partner2 can make GET requests to its validation API someotherpartnervalidation but only GET requests to helloworld. partner2 does not have any access to somepartnervalidation as it is only for partner1.

First, I will make a GET request to someotherpartnervalidation:

curl -X GET -i -u "partner2:<partner2 Password>" http://api.us-south.containers.appdomain.cloud/bpaas/v1/someotherpartnervalidation

In the response headers I see the HTTP/1.1 200 OK code which tells me it was successful. Below is the only other API request that returns a 200 OK response because of the permission limitations given previously:

curl -X GET -i -u "partner2:<partner2 Password>" http://api.us-south.containers.appdomain.cloud/bpaas/v1/helloworld

Like partner1, partner2 cannot make any other request to the APIs that are not configured for via the APIs and permissions. This includes any request to somepartnervalidation which is strictly for partner1.

Validating in B2Bi/SFG

Within your B2Bi/SFG API pod you will find the BPaaS log file bpaas.log. In my configuration this file is in the /ibm/trace/logs/node1 directory. The file contains logs pertaining to BPaaS API calls which confirms that the service is receiving the requests, authenticating, authorizing, and running the APIs as they were configured:

[2024-12-12 18:14:46.902] INFO [BPaaS.Audit] partner1 isAuthenticated:true
[2024-12-12 18:14:46.929] INFO [BPaaS.Audit] partner1 isAuthorized:true
[2024-12-12 18:14:46.931] INFO [BPaaS.Audit] execution of API helloworld called by user partner1 started
[2024-12-12 18:14:46.980] INFO [BPaaS.Audit] execution of API helloworld called by user partner1 finished. Total time taken: 50ms
[2024-12-12 18:14:52.314] INFO [BPaaS.Audit] partner1 isAuthenticated:true
[2024-12-12 18:14:52.342] INFO [BPaaS.Audit] partner1 isAuthorized:false
[2024-12-12 18:38:42.557] INFO [BPaaS.Audit] partner2 isAuthenticated:true
[2024-12-12 18:38:42.601] INFO [BPaaS.Audit] partner2 isAuthorized:false
[2024-12-12 18:38:46.214] INFO [BPaaS.Audit] partner2 isAuthenticated:true
[2024-12-12 18:38:46.236] INFO [BPaaS.Audit] partner2 isAuthorized:true
[2024-12-12 18:38:46.238] INFO [BPaaS.Audit] execution of API someotherpartnervalidation called by user partner2 started
[2024-12-12 18:38:46.335] INFO [BPaaS.Audit] execution of API someotherpartnervalidation called by user partner2 finished. Total time taken: 96ms
[2024-12-12 18:38:48.683] INFO [BPaaS.Audit] partner2 isAuthenticated:true
[2024-12-12 18:38:48.711] INFO [BPaaS.Audit] partner2 isAuthorized:true
[2024-12-12 18:38:48.713] INFO [BPaaS.Audit] execution of API helloworld called by user partner2 started
[2024-12-12 18:38:48.754] INFO [BPaaS.Audit] execution of API helloworld called by user partner2 finished. Total time taken: 41ms

A Note on BPaaS Configuration

The examples above demonstrate how the different levels of BPaaS configuration (API-level and permission-level) can allow partners to access the same APIs with different authorization levels or their own APIs altogether. Additionally, the examples show how each API can be mapped to its own unique Business Process or even have the same Business Process mapping as another API.

Resources

Helm Charts

B2Bi Version 6.2.0.1

SFG Version 6.2.0.1

Installation Document References

Business Process as a Service (BPaaS)

Considerations for Configuring BPaaS

Configuring BPaaS in Certified Containers

BPaaS Configuration Properties

BPaaS Auditing

Acronyms

OCP: OpenShift Container Platform
B2Bi: Sterling Business to Business Integrator
SFG: Sterling File Gateway
BPaaS: Business Process as a Service

0 comments

9 views

IBM Sterling Data Exchange

Connect: Network, learn, and share with experts in Sterling Data Exchange

IBM Sterling Data Exchange

Connect: Network, learn, and share with experts in Sterling Data Exchange

Sterling Data Exchange