SBI SOAP Series Part 1: Setting up Sterling B2B Integrator as a Web Service Provider

Body

The Sterling B2B Integrator documentation does a good job of outlining what each SOAP service does within the application. However, there really isn't a great resource for showing how to fit all of the pieces together. Throughout this multi-part series, I'll take a step by step approach to accomplish the following tasks:

1. Configuring SBI as a Web Service Provider and testing an SBI Web Service with external tools, such as soapUI.
2. Limiting the response to the client through the use of schemas.
3. Configuring SBI to consume a web service automatically based on a WSDL with Dynamic Services.
4. Configuring an SBI Web Service client to manually create and post a SOAP Request.

The topic of web services is quite large and far-ranging, so we will start with the basic setup, and then build upon our resources throughout the series. I'll try to keep external resources out of the picture, so that my examples can be easily implemented if you are trying to follow along in your test instance.

Let's start with a basic Web Service Provider. The first thing we will need is a business process that will take some input and provide some output based on the SOAP request. This requires us to determine what data will be provided by the client, how we are going to interpret that data, and the format that we provide the data back to the customer. Let's say our web service will take a customer ID as input, and return a Prefix, First Name and Last Name that matches up with the customer ID. Generally, this would be a quick external database call with the Lightweight JDBC adapter, but rather than implement the external database connection and LWJDBC, I'll fake it with some assigns. Keep in mind that the BP must run quickly and be able to generate the results before the SOAP client times out, so don't try to do too much. My dummy BP fits that criteria well! For now, we will ignore namespaces and assume that there will be no collisions in the response provided to the consumer.

Here's the BP I will use. It also is a good example of using a single AssignService to make multiple simple assigns in one step. It just needs to be checked in to the system before configuring the Web Service.

<process name="BSWS_NameLookup">

<sequence>

<operation name="AssignService">

<participant name="AssignService"/>

<output message="AssignOutputMessage">

<assign to="." from="*"/>

<assign to="Prefix">Mr.</assign>

<assign to="FirstName">Brian</assign>

<assign to="LastName">Sak</assign>

</output>

<input message="AssignInputMessage">

<assign to="." from="*"/>

</input>

</operation>

</sequence>

</process>

Now, to create the Web Service.

Go to Deployment → Web Services → Manager

1. Click Create a Web Service Configuration. I'm calling it BSWS_ProvideName. I generally check the Use Legacy WS settings, but this will depend on requirements. Click Next.
2. Select Use HTTP as SOAP Transport. This means that the generated WSDL for this web service will be pointing at the SOA Http Server Adapter by default.
3. We will pass over Security Settings. That is a topic unto itself. Keep clicking Next until you reach "Assign Business Processes". Here, select BSWS_NameLookup, move it to the right side, and click Next.
4. Do not assign any Service Instances. Just click Next.
5. Now, we are on the Assign Consumers page. Do not assign any consumers at this time. If you were to assign consumers, the SOAP Request would have to include a valid SBI account name and password to authenticate before a SOAP response would be returned. It is important to note that this is NOT HTTP basic authentication, which is provided in an HTTP Header. This would actually be part of the SOAP structure and is unrelated to HTTP protocol. We will discuss this more later in the series.
6. Click Next until you reach the end of configuration and save the web service.

Now, go to Web Services → Manager and let's take a look at the WSDL that was generated.

When you click that View WSDL link next to the newly created web service, notice two things:

1. A new tab opens with the address http://servername:soap_port/wsdl?configName=BSWS_ProvideName. This is a URI based on entries in the soa.properties file. You'll also see a similar URI specified for the endpoint of the web service. If you want to use a different HTTP Server Adapter than the default, you'd have to modify those properties, but it would be a global change affecting all hosted web services.
2. A Business Process kicks off to provide the wsdl when this particular URI is hit. It kicks off SOA_ServiceInfo, and that is the mechanism which pulls the WSDL from the database and provides it back over HTTP.

Save that WSDL to your file system. We are going to use it to test the Web Service with soapUI (http://www.soapui.org/). If you don't have it, download the free version. It can do everything that we will need it to.

Once soapUI is started up, create a new project with File → New soapUI project. Choose a project name, point to the WSDL you saved for Initial WSDL/WADL, and make sure the Create Requests checkbox is checked. Then click OK.

Go to your new project tree and expand down to Request1 and double-click on it. You should see something similar to the following appear:

There is no input schema currently defined, so we have the most skeletal of skeletons for our request. Let's add some data. Modify the request so it appears as so:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Header/>

<soapenv:Body>

<mesa:BSWS_NameLookup xmlns:mesa="http://www.sterlingcommerce.com/mesa">

<ID>123456</ID>

</mesa:BSWS_NameLookup>

</soapenv:Body>

</soapenv:Envelope>

The ID tag is just some dummy data. I also moved the xmlns namespace declaration for mesa prefix to where it is first used in the body. The explanation for that is found in this article:

http://www-01.ibm.com/support/docview.wss?uid=swg21636761

Now, post the request. If you have no connectivity issues to the endpoint, you should get a response like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Body>

<mesa:processData xmlns:mesa="http://www.sterlingcommerce.com/mesa">

<ProcessData>

<b2b-protocol>http</b2b-protocol>

<transport-instance-id>MESAHttpServerAdapter_HttpServerAdapter_node1</transport-instance-id>

<transport-session-id>Thu Jul 24 10:59:31 EDT 2014:5</transport-session-id>

<http-request-uri>/soap</http-request-uri>

<service>BSWS_ProvideName</service>

<SyncModeBP>false</SyncModeBP>

<xport-doc-on-error>true</xport-doc-on-error>

<incomingSOAPTransportMode>http</incomingSOAPTransportMode>

<PipeLineTimeout>600</PipeLineTimeout>

<messageMode>1</messageMode>

<wsConfig name="BSWS_ProvideName">

<certID/>

<verificationCertID/>

</wsConfig>

<SOARequiredSignature>false</SOARequiredSignature>

<EXPECT_SECURITY_HEADER>false</EXPECT_SECURITY_HEADER>

<SOAP_URI>/soap</SOAP_URI>

<SOAPEnvNSPrefix>soapenv</SOAPEnvNSPrefix>

<SOAPEnvNSURI>http://schemas.xmlsoap.org/soap/envelope/</SOAPEnvNSURI&gt;

<soapenv:ReceivedSOAPHeaders/>

<PrimaryDocument SCIObjectID="oxnard:node1:14768e1780e:109717"/>

<mesa:BSWS_NameLookup>

<ID>123456</ID>

</mesa:BSWS_NameLookup>

<serviceMode>0</serviceMode>

<typeName>BSWS_NameLookup</typeName>

<FirstName>Brian</FirstName>

<LastName>Sak</LastName>

<Prefix>Mr.</Prefix>

<ADD_SOAP_ENVELOPING>false</ADD_SOAP_ENVELOPING>

<INSERT_SECURITY_HEADER>false</INSERT_SECURITY_HEADER>

</ProcessData>

</mesa:processData>

</soapenv:Body>

</soapenv:Envelope>

Great! We got a response, and it contains the values that we want. In fact, it has WAY more data being sent back then we really want to send. Most of this will mean nothing to the client. Let's examine how that happened.

Go to Sterling B2B Integrator application and look up the SOA_MessageHandler process that ran at the time you posted your SOAP request from soapUI.

Step 0 contains the following document received by the SOA Http Server Adapter (system name is MESAHttpServerAdapter).

Connection:close

Accept-Encoding:gzip,deflate

Content-Type:text/xml;charset=UTF-8

SOAPAction:"sii:BSWS_NameLookup"

Content-Length:288

Host:XX.XX.XX.XX:16040

User-Agent:Apache-HttpClient/4.1.1 (java 1.5)

URI:/soap

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Header/>

<soapenv:Body>

<mesa:BSWS_NameLookup xmlns:mesa="http://www.sterlingcommerce.com/mesa">

<ID>123456</ID>

</mesa:BSWS_NameLookup>

</soapenv:Body>

</soapenv:Envelope>

You can see that soapUI added the correct SOAPAction header according to the operation that we are trying to execute from the WSDL.

The next few steps do some assigns and decisions, and then the SOA_RequestHandler is invoked inline. Eventually we reach the SOA Inbound Service which strips the SOAP envelopes from the document, leaving only the payload as PrimaryDocument:

<mesa:BSWS_NameLookup xmlns:mesa="http://www.sterlingcommerce.com/mesa">

<ID>123456</ID>

</mesa:BSWS_NameLookup>

This is why we moved the xmlns declaration for "mesa", so we would still have a valid XML document after the envelope was stripped.

The BP then moves on, and a few steps later, calls the business process we configured earlier (BSWS_NameLookup) to run inline, and that is what puts our desired values into ProcessData.

After that, some Outbound SOA services run. The SOAResponseBuilder_Instance puts values from ProcessData into PrimaryDocument. The SOAOutbound Service wraps that document in SOAP envelopes, and the HTTP Respond service returns that document to the client.

So, we get ALL of ProcessData as the response. Obviously, this is not ideal. You CAN limit the amount of data returned, though, through the use of schemas and schema mappings. That will be the topic of the next article in this series. If you'd like a headstart, search the internet for the term WebservicesResponseNode. See you next time!