Web services

B2Bi exposes the following internal services through web service interfaces:

These web services have been tested with:

  • Java using Axis 1.2 and Axis 1.3
  • C# .Net 2003.

Message submit

The message submit web service is for exchanging messages between B2Bi and a back-end system.

The B2Bi trading engine can act as:

  • A message submit web service client, or a
  • A message submit web service server.

B2Bi acts in the server role when the back-end system sends a message to a trading partner. The backend posts messages to a URL in the following format: http://localhost:5080/services/MessageService.

The variable localhost is the fully qualified domain name or IP address of the computer running the trading engine. The default port is 5080, but this can be changed in the B2Bi user interface.

B2Bi acts in the client role when sending a message to the back-end system.

There are two ways to access the WSDL document that describes the requirements for both the server and the client:

  • Retrieve the sdk/wsdl/TradingEngineNodeServices/MessageService.wsdl file from the SDK directory tree, or
  • Set up a web services API server integration pickup exchange in The B2Bi trading engine and point a browser to http://localhost:5080/services/MessageService?wsdl.

Localhost is valid when the browser and B2Bi are on the same computer. Otherwise, use the fully qualified domain name or IP address of the computer running B2Bi.

When acting in the client role, The B2Bi trading engine calls the sendMessage method of the implementing web services server. B2Bi currently does not make use of any of the other methods defined in the WSDL.

Sample client implementations are in the SDK directory tree here:

  • sdk/java-src/examples/webservices/tradingenginenodeservices/messageservice
  • sdk/csharp-src/examples/webservices/tradingenginenodeservices/messageservice

Message resubmit

The message resubmit web service allows for messages in a final state to be resubmitted and processed again by the trading engine.

This web service works the same as resubmitting a message through Message Tracker in B2Bi user interface.

The WSDL can be found at http://localhost:6080/cyclone/services/MessageResubmitService?wsdl.

Localhost is valid when the browser and B2Bi are on the same computer. Otherwise, use the fully qualified domain name or IP address of the computer running B2Bi.

The WSDL also is in the SDK directory tree at sdk/wsdl/ControlNodeServices/MessageResubmitService.wsdl.

Sample client implementations are in the SDK directory tree here:

  • sdk/java-src/examples/webservices/controlnodeservices/messageresubmitservice
  • sdk/csharp-src/examples/webservices/controlnodeservices/messageresubmitservice

This web service requires an authenticated user session. See Authenticated user session.

Message query

The message query web service supports querying for messages and the related metadata. Retrieval of message payloads is not supported.

The web service's functionality is similar to the custom search functionality of B2Bi Message Tracker. Query criteria can be set to limit the number of messages returned. Paging of query results is supported to minimize resource use on the client and server side.

The WSDL can be found at http://localhost:6080/cyclone/services/MessageQueryService?wsdl.

Localhost is valid when the browser and B2Bi are on the same computer. Otherwise, use the fully qualified domain name or IP address of the computer running B2Bi.

The WSDL also is in the SDK directory tree at sdk/wsdl/ControlNodeServices/MessageQueryService.wsdl.

Sample client implementations are in the SDK directory tree:

  • sdk/java-src/examples/webservices/controlnodeservices/messagequeryservice
  • sdk/csharp-src/examples/webservices/controlnodeservices/messagequeryservice

This web service requires an authenticated user session. See Authenticated user session.

Authenticated user session

The message query and message resubmit web services require an authenticated user session.

A user session web service is provided for authenticating a username and password. A cookie is returned for each logic operation. A valid cookie must be passed with each message query or message resubmit operation.

The WSDL can be found at http://localhost:6080/cyclone/services/MessageQueryService?wsdl.

Localhost is valid when the browser and B2Bi are on the same computer. Otherwise, use the fully qualified domain name or IP address of the computer running B2Bi.

The WSDL is also in the SDK directory tree at sdk/wsdl/ControlNodeServices/MessageQueryService.wsdl.

Sample usage can be found in the examples directories for message query or message resubmit.

CPA add or remove

The ebXML CPA web service allows you to install or remove an ebXML CPA through an API. This is useful when a CPA is generated by a tool and sent to The B2Bi trading engine.

The WSDL can be found at http://localhost:6080/cyclone/services/CPAAPI?wsdl.

Localhost is valid when the browser and B2Bi are on the same computer. Otherwise, use the fully qualified domain name or IP address of the computer running B2Bi.

The WSDL also is in the SDK directory tree at sdk/wsdl/ControlNodeServices/CPAAPI.wsdl.

Sample client implementations can be found in the SDK directory tree:

  • sdk/java-src/examples/webservices/controlnodeservices/cpaapiservice
  • sdk/csharp-src/examples/webservices/controlnodeservices/cpaapiservice

Any valid trading engine user can call the importCPA or removeCPA operation.

The importCPA and removeCPA operations do not return a result, except for a SOAP fault (CPAAPIInvocationException) in case of failure. The fault includes a string, code, and details to identify the failure reason.

importCPA operation

The import CPA operation has three parameters:

  • Username of type string,
  • Password of type string, and
  • CPA of base 64 encoded string.

The username and password are required for authentication.

The CPA parameter is the actual CPA, encoded as a base 64 string. This is the CPA to be imported into the trading engine.

The return type is empty. In case of a failure, a WSDL fault is thrown back to the web service client. Below is an example of a SOAP fault:

<soapenv:Envelope>
    <soapenv:Body>
      <soapenv:Fault>
         <faultcode>nsl:Error Code.</faultcode>
        <faultstring>CPA API Invocation Error String.</faultstring>
          <detail>
          <ns2:CPAApiInvocationExceptionType/>
          <ns3:exceptionName>
&#160;&#160;&#160;&#160;&#160;com.cyclonecommerce.tradingengine.profile.cpaapi.
     webservice.types.common.CPAApiInvocationException
                </ns3:exceptionName>
                <ns4:hostname>coronation</ns4:hostname>
                <ns5:stackTrace>
                   java.io.FileNotFoundException: notPresentFile.txt (No
      such file or directory) at java.io.FileInputStream.open
      (Native Method) at java.io.FileInputStream.<init>
      (FileInputStream.java:103) at java.io.FileInputStream.
      <init>(FileInputStream.java:66) at java.io.FileReader.
      <init>(FileReader.java:41) ... more...
          </ns5:stackTrace>
           <ns6:reason>Error Reason.</ns6:reason>
         </detail>
  </soapenv:Fault>
 </soapenv:Body>
</soapenv:Envelope>

The faultstring and faultcode elements of the SOAP fault indicate the error. If there is a reason and a Java exception traceback, that is added to the detail element. The detail element has additional information, such as the exception name, which is always CPAAPIInvocationException.

Because the SOAP fault is caused by the web service, as opposed to a problem of the SOAP protocol, the Cyclone namespace is used. The namespace is http://cyclonecommerce.com/tradingengine/profile/cpaapi/webservice.

For the importCPA operation, the following error strings (faultstring) and error codes (faultcode) are used.

Code

Error string

Description

100

Authentication failed

The server could not authenticate the user for the execution of the called operation.

200

CPA validation error

The CPA has not passed the CPA validation procedure. A traceback is provided for further information.

300

No matching local party found

The system could not locate a local party in the trading engine matching any party in the CPA. Either a community is missing or the CPA references wrong parties.

500

Unsupported Cyclone ebCPA feature

The ebXML CPA makes use of an unsupported ebCPA feature.

510

Unsupported Cyclone ebMS feature

The ebXML CPA requires ebMS features that are not supported.

520

Unsupported Cyclone ebBP feature

The ebXML CPA requires ebXML business process features that are not required yet.

530

Unsupported Cyclone ebRR feature

The ebXML CPA requires ebXML registry or repository support that is not supported.

600

Other CPA Import Error

A CPA-related error occurred while importing the CPA. A traceback is provided for further information.

601

Other System Error

A system-related error occurred while importing the CPA. A traceback is provided for further information.

removeCPA operation

The removeCPA operation has three parameters:

  • Username of type string,
  • Password of type string, and
  • CPA ID of type string.

The username and password are required for authentication.

The third argument is the CPA ID of the CPA to be removed from B2Bi. The CPA ID is the cpaid attribute of the CollaborationProtocolAgreement element of the CPA file. The data type of the CPA ID is string.

For the removeCPA operation, the following error strings (faultstring) and error codes (faultcode) are used.

Code

Error string

Description

100

Authentication failed

The server could not authenticate the user for the execution of the called operation.

200

CPA to be removed not present in system

The corresponding CPA of the CPA ID cannot be located in the trading engine.

600

Other CPA remove error

A CPA-related error occurred while removing the CPA. A traceback is provided for further information.

601

Other system error

A system-related error occurred while removing the CPA. A traceback is provided for further information.

Web service examples

This section provides directions for running web service examples.

For more information about the example classes, see the Swagger API Javadoc.

To open Swagger and consult the Javadoc, open a browser and enter the URL https://<host>:<port>/apidocs/ui.

The following examples can be run in Windows. Set values for:

INTERCHANGE_JARS

Set the path to the trading engine jars directory. For example, <B2Bi_install_directory>/Interchange/jars.

INTERCHANGE_CORELIB

Set the path to the trading engine corelib directory. For example, <B2Bi_install_directory>/Interchange/corelib.

Message service

This example invokes the MessageService web service. It demonstrates the class MessageServiceClient2:

set INTERCHANGE_JARS=

set INTERCHANGE_CORELIB=

java -cp

clientexamples.jar;${INTERCHANGE_JARS}\haboob.jar;${INTERCHANGE_CORELIB}\jaxrpc.jar;${INTERCHANGE_CORELIB}\saaj-api.jar;${INTERCHANGE_CORELIB}\axis.jar;${INTERCHANGE_CORELIB}\wsdl4j-1.6.2.jar;${INTERCHANGE_CORELIB}\jakarta-commons-logging-1.1.1.jar;${INTERCHANGE_CORELIB}\commons-discovery.jar

examples.webservices.tradingenginenodeservices.messageservice.messageserviceclient2.MessageServiceClient2 [submit | send | status] endpointURL [MessageId] sendPayloadURL[true/false]

CPA web service

This example implements a web service client that calls the ebXML CPA web service:

set INTERCHANGE_JARS=

set INTERCHANGE_CORELIB=

java -cp

clientexamples.jar;${INTERCHANGE_JARS}\haboob.jar;${INTERCHANGE_CORELIB}\jaxrpc.jar;${INTERCHANGE_CORELIB}\saaj-api.jar;${INTERCHANGE_CORELIB}\axis.jar;${INTERCHANGE_CORELIB}\wsdl4j-1.6.2.jar;${INTERCHANGE_CORELIB}\jakarta-commons-logging-1.1.1.jar;${INTERCHANGE_CORELIB}\commons-discovery.jar

examples.webservices.controlnodeservices.cpaapiservice. TestClient <hostname> <port> <username> <password> [import <CPA file>|remove <CPA ID>]

Message query

This example demonstrates the simple SOAP client for the MessageQueryService:

set INTERCHANGE_JARS=

set INTERCHANGE_CORELIB=

java -cp

clientexamples.jar;${INTERCHANGE_JARS}\haboob.jar;${INTERCHANGE_CORELIB}\jaxrpc.jar;${INTERCHANGE_CORELIB}\saaj-api.jar;${INTERCHANGE_CORELIB}\axis.jar;${INTERCHANGE_CORELIB}\wsdl4j-1.6.2.jar;${INTERCHANGE_CORELIB}\jakarta-commons-logging-1.1.1.jar;${INTERCHANGE_CORELIB}\commons-discovery.jar

examples.webservices.controlnodeservices.messagequeryservice

. MessageQueryServiceClient <base-url> <username> <password>

[-rejected|-delivered|messageID]

Resubmit service

This example demonstrates the simple SOAP client for the MessageResubmitService:

set INTERCHANGE_JARS=

set INTERCHANGE_CORELIB=

java -cp

clientexamples.jar;${INTERCHANGE_JARS}\haboob.jar;${INTERCHANGE_CORELIB}\jaxrpc.jar;${INTERCHANGE_CORELIB}\saaj-api.jar;${INTERCHANGE_CORELIB}\axis.jar;${INTERCHANGE_CORELIB}\wsdl4j-1.6.2.jar;${INTERCHANGE_CORELIB}\jakarta-commons-logging-1.1.1.jar;${INTERCHANGE_CORELIB}\commons-discovery.jar

examples.webservices.controlnodeservices.messageresubmitservice. MessageResubmitServiceClient <base-url> <username> <password> <coreID(s)>

Related topic

Related Links