Application Program Interface

The WebLogic Integration - Business Connect application program interface (API) enables you to programmatically exchange documents remotely or locally between WebLogic Integration - Business Connect and your application and pass WebLogic Integration - Business Connect status messages to your application.

You must have a Java 2 compiler with remote method invocation (RMI) API libraries to use the WebLogic Integration - Business Connect API or build sample programs.

The following topics are provided.

Concepts

Windows

API Overview

The WebLogic Integration - Business Connect APIs enable users to integrate with the application across three functional areas: document integration, event listening and profile management. Depending on the functional area, these APIs are accessed singly or by a combination of Java programs, Java message service (JMS) or Simple Object Access Protocol (SOAP). These APIs do not override the standard non-programmatic interfaces to the application. Rather, they work in conjunction with the standard non-programmatic interfaces; namely, the file system, FTP, JMS and MQSeries.

The following topics describe each of the three functional areas in detail:

Document Integration

The document integration API enables programmatic submission and reception of business documents between WebLogic Integration - Business Connect and a back-end business system. It supports synchronous and asynchronous interfaces for document submission. The document integration API is accessible by a local Java remote method invocation (RMI) client, a local HTTP or HTTPS client, or by the global JMS integration capability in the WebLogic Integration - Business Connect application.

The global JMS interface reads document meta-data from JMS properties for outbound documents and writes document meta-data into JMS properties for inbound documents. This enables a simple, rich and reliable JMS interface to the WebLogic Integration - Business Connect application. All documents sent via the global JMS interface are executed synchronously. Asynchronous document sending should be accomplished through an RMI-HTTP client or through the standard non-programmatic interfaces to the application (file system, FTP, JMS, MQSeries).

See the following related topics:

Java Document Integration

The following graphics show high-level views of the Java document integration API. For details open the file index.html in api/documentation in the WebLogic Integration - Business Connect installation directory.

Figure 14-1 Local Client Receives a Document from WebLogic Integration - Business Connect

JMS Global Integration for Documents

The default Administrator user can use the JMS Integration window Documents tab to configure WebLogic Integration - Business Connect to retrieve outbound documents from or direct inbound documents to a JMS queue. This affects inbound and outbound documents for all active company profiles, all partners and all document types: EDI, XML and binary.

To use the JMS Integration window Documents tab your organization must have JMS experience and a working JMS messaging system.

In addition to completing this tab, you must add the names of the JAR or class files or both in the server.ini or server.bat file in Windows or your environment file in UNIX so the Server application can locate the JMS and JNDI provider. The server.ini and server.bat files are located in the installation directory bin subdirectory. In some cases, you need to add the name of only one JAR file (for example, weblogic.jar), but you might have to include a series of jars or paths.

To display the JMS Integration window Documents tab, select Tools—>API—>JMS and click the Documents tab.

The following are related topics:

Global Versus Company JMS integration

WebLogic Integration - Business Connect enables JMS document integration globally for all companies, partners and document types, or by specific company, partner and document type combinations, or both. Global and company-level integration operate independently of each other.

With global JMS integration there is one inbound queue and one outbound queue for all companies, partners and document types. On the company level, a queue is required per company, partner and document type combination.

Parameters are required for documents WebLogic Integration - Business Connect retrieves from the JMS queue when global JMS integration is configured. These properties specify the sender, receiver, document type and other information. These parameters are passed to WebLogic Integration - Business Connect in a JMSMessage. If JMS integration is configured by company, however, the parameters are not required. This is because there is one queue per company, partner and document type combination and the parameter information already is established.

Regardless whether JMS integration is global or by company, WebLogic Integration - Business Connect provides values for the sender, receiver and document type parameters when passing inbound documents from partners to a JMS queue.

JMS Global Integration Details

This API is an input and output source for documents. This is how it works: WebLogic Integration - Business Connect registers as a listener with the JMS server for the designated inbound queue. This means that any JMSMessage placed in the queue by another process is passed to WebLogic Integration - Business Connect, which verifies that it is a BytesMessage (a type of JMSMessage). If verified, WebLogic Integration - Business Connect packages and sends it to the partner. Likewise, every document WebLogic Integration - Business Connect receives from a partner is unpackaged, converted to a BytesMessage and placed on the designated outbound queue.

The API requires that the JMS messages be in the format BytesMessage. WebLogic Integration - Business Connect does not process any other type of JMSMessage (such as ObjectMessage). WebLogic Integration - Business Connect performs routing decisions based on JMS message string parameters that must be appended to each BytesMessage sent to it. If the required parameters are omitted, WebLogic Integration - Business Connect does not process the message. WebLogic Integration - Business Connect also places the same parameters on each message that it sends to the outbound queue. The parameters WebLogic Integration - Business Connect uses are in the following table.

Figure 14-5 JMS Integration Window Documents Tab

The following describes the fields on the JMS Integration window Documents tab.

The fields are described once for inbound and outbound documents.

The Inbound Documents area is for configuring WebLogic Integration - Business Connect to place documents that have been received from partners and unpackaged on a back-end JMS queue.

The Outbound Documents area is for configuring WebLogic Integration - Business Connect to retrieve documents from a back-end JMS queue and then package and send the documents to partners.

Except for the user name and password, you can obtain the information needed to complete the tab from the JMS or JNDI provider's documentation. The information will vary depending on the provider. If you have questions, contact your JMS or JNDI provider.

Event Listening

The event listening API enables programmatic access to the WebLogic Integration - Business Connect event model. Events are accessible as Java objects in RMI call-backs or as Java objects persisted in a JMS topic. Document events contain the meta-data necessary to acquire the payload associated with the document event. System and document events are reported, as determined by the event logging level set on the General tab under Tools—>Preferences in Administrator.

See the following related topics:

Java Event Listening

The following graphic shows a high-level view of the Java event listening API. For details open the file index.html in api/documentation in the WebLogic Integration - Business Connect installation directory.

Figure 14-6 Local or Remote Client Listens to Server Events

JMS Integration for Events

The default Administrator user can use the JMS Integration window Events tab to configure the Server application to publish all events to your system's JMS server and locate the information by calling the JNDI provider in your JMS enterprise messaging system. This features enables persistent event logging to the JMS server.

To use this tab your organization must have JMS experience and a working JMS enterprise messaging system.

In addition to completing this tab, you must add the names of the JAR or class files or both in the server.ini or server.bat file in Windows or your environment file in UNIX so the Server application can locate the JMS and JNDI provider. The server.ini and server.bat files are located in the installation directory bin subdirectory. In some cases, you need to add the name of only one JAR file (for example, weblogic.jar), but you might have to include a series of jars or paths.

To display the JMS Integration window Events tab, select Tools—>API—>JMS and click the Events tab.

Figure 14-7 JMS Integration Window Events Tab

The following describes the fields on the JMS Integration window Events tab.

Java API Implementation Guidelines

Performance is enhanced if the Java RMI API client and server application run on the same computer, but this is not a requirement. An API client running on the same computer is referred to as a local client. An API client running on a different computer is referred to as a remote client. If you set up a remote client, it should run on the same side of a firewall as the Server application. Running a remote client on the opposite side of a firewall presents RMI protocol difficulties.

You also must copy the cyclone.jar and xerces.jar files to your client's machine and make them available by modifying the classpath environment variable. The cyclone.jar file is required to be able to interface with the Server application. The xerces.jar file is required to send XML files to and receive them from the Server application. If you intend to use JMS to interface with the Server application you still must include these two files into your classpath. However, you must also include jms.jar and jndi.jar in your classpath. All of these files are located in the WebLogic Integration - Business Connect lib directory.

You must have a Java 2 developer kit to customize the API for your organization's needs. It is incumbent on your organization to correctly write the API and properly configure WebLogic Integration - Business Connect for successful operation.

Profile Management

The profile management API enables programmatic access to the WebLogic Integration - Business Connect profile and certificate repository. Profiles can be created, deleted and modified via a SOAP interface. These APIs are a convenient mechanism for populating or updating the WebLogic Integration - Business Connect profile repository without using the interactive graphical user interface.

The following topics are provided about the profile management API:

Overview of the Profile Management API

The profile management API enables you to programmatically add, update, retrieve or remove company and partner profiles. The Server application must be running with an open Simple Object Access Protocol (SOAP) port to return various XML formats. Each of the functions exposed by the SOAP-based API must be supplied. Each format has a corresponding schema file.

The following summarizes the functionality of the profile management API:

Required Knowledge and Skills

People who implement a profile management API need the following knowledge and skills:

Required Tools

If you attempt to use Apache's Xerces, Xalan or SOAP JAR files, we suggest that you only use the versions of the JAR provided in the WebLogic Integration - Business Connect installation directory. This will help to minimize possible compatibility problems.

Profile Management Sample Code

A sample application using the profile management API is in api\samplecode\ConfigurationClient in the WebLogic Integration - Business Connect installation directory. The ConfigurationClient sample is a full-featured client application that works with pre-configured company and partner XML profiles. It implements all the API functionality.

The sample application presumes the SOAP port is 5081. In Administrator, check the HTTP API port setting on the Ports tab in Tools—>Preferences. The sample is configured to not delete the companies and partners it creates. For more information about the sample code, see the readme.txt file in api\samplecode\ConfigurationClient.

We also recommend that you review the company configuration and partner configuration XML schemas as well as the query. See the following files in the WebLogic Integration - Business Connect xmlschema directory:

Profile Management Functions

The profile management API enables the following functions:

There is a utility class named ConfigurationApiStub that encapsulates each of these functions and is recommended to be used to connect to the SOAP interface. We recommend that you review this class in the HTML documentation in api\documentation; open index.html. All of the methods in the class take a org.w3c.dom.Element object as a parameter and all return a result of org.w3c.dom.Element. All examples assume your code uses this class. The constructor of this class takes an instance of ClientSession located in the SOAP package. The purpose of this class is authentication and to maintain a session within the SOAP server in WebLogic Integration - Business Connect.

SetCompanyProfiles and SetPartnerProfiles

SetCompanyProfiles and SetPartnerProfiles must both be supplied an Element instance (org.w3c.dom.Element) of an XML document that conforms to each of their respective schemas. For example, InterchangeCompanyConfig for the SetCompanyProfiles function and InterchangePartnerConfig for the SetPartnerProfiles function. SetCompanyProfiles and SetPartnerProfiles are multipurpose functions that can be used for insert and update purposes.

When the server receives a request for either function, it compares the supplied routingid element value to the list of known IDs in the system. If the ID exists, the server treats the request as an update rather than as new. If the ID is not known, it inserts the data as a new company or partner.

If you insert a company into WebLogic Integration - Business Connect and do not specify the system directories, WebLogic Integration - Business Connect uses the default directories in the format installation_directory\data\companyID).

Updating works just like inserts. For example, if you submit a company configuration XML file with the following elements:

<XMLRoutings>
                <XMLRouting name="BizTalk">
                        <Sender>/:BizTalk/:Route/:From/@locationID</Sender>
                        <Receiver>/:BizTalk/:Route/:To/@locationID</Receiver>
                </XMLRouting>
        </XMLRoutings>

This would add BizTalk with its Xpaths for sender and receiver. If you then re-submit the XML file with only the following:

<XMLRoutings>
</XMLRoutings>

This tells WebLogic Integration - Business Connect to update the company with no XML routing information. If you had not included an XMLRoutings section in the XML document you submitted to WebLogic Integration - Business Connect, the BizTalk routings would have been unchanged.

If a client requests to create or update profiles using SetCompanyProfiles or SetPartnerProfiles, the server acknowledges the request with a disposition. The server response is an OrganizationDataOutputList that shows the status of the request. Each request contains a corresponding OrganizationDataOutput indicating the organization ID under the root element. Beneath each OrganizationDataOutput is a disposition indicating success or failure. The following is an example:

<OrganizationDataOutputList xmlns="http://www.cyclonecommerce.com/Schemas/2001/07/pmapi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <OrganizationDataOutput xmlns:bapi="http://www.cyclonecommerce.com/Schemas/2001/07/bapi" organizationId="edi3551">
                <bapi:Disposition id="000" title="Company created successfully."/>
        /OrganizationDataOutput>
</OrganizationDataOutputList>

FindCompanies and FindPartners

FindCompanies and FindPartners must both be supplied an Element instance (org.w3c.dom.Element) of an XML document that conforms to the ProfileQuery schema. This function returns all the company and partner IDs that match given criteria. If a large number of profile IDs can be returned, the client or the server can specify a maximum. The client specifies the limit by supplying the optional MaxProfiles attribute on the main ProfileQuery element.

There are three ways to search for partners and two ways to search for companies, as explained in the following table.

The following is an example that asks for all partners in the group Office Suppliers:

<ProfileQuery xmlns="http://www.cyclonecommerce.com/Schemas/2001/09/icapi">
        <SearchBy>
                <PartnerGroup>Office Suppliers</ PartnerGroup >
        </SearchBy>
</ProfileQuery>

If your query asks for more profile IDs than allotted in the MaxProfiles attribute, the server returns a Cursor (bapi:Cursor). The Cursor object only has value to the WebLogic Integration - Business Connect server, which means you should receive this element only when your query results exceed the MaxProfiles limit. This Cursor can be passed to any subsequent call to get the next set of IDs, which might in turn have only a subset of the remaining items, in which case the same scenario exists again. When called with a Cursor, the only other parameter the server uses is MaxProfiles; all others are ignored.

These functions must be in the form of the ProfileQuery schema, which can be located in the InterchangeConfigAPI.xsd file in the xmlschema directory. As these function only return IDs, you probably would use them with GetCompanyProfiles and GetPartnerProfiles.

GetCompanyProfiles and GetPartnerProfiles

GetCompanyProfiles and GetPartnerProfiles must both be supplied an Element instance (org.w3c.dom.Element) of an XML document that has an OrganizationIdList element containing any number of OrganizationId sub elements. This returns the entire organization data for each of the specified organizations in the XML format requested.

The following example is a client request to retrieve the profile for company ID Company1. In this example, the client only wants the profile for one partner. It could have requested multiple profiles by specifying multiple organization IDs in the request.

<OrganizationIdList xmlns="http://www.cyclonecommerce.com/Schemas/2001/07/bapi">
        <OrganizationId> Company1</OrganizationId>
</OrganizationIdList>

RemoveCompanyProfiles and RemovePartnerProfiles

RemoveCompanyProfiles and RemovePartnerProfiles remove an entire organization from the WebLogic Integration - Business Connect server. Companies and partners can be deleted regardless of their status. However, a binary relationship is established between companies and partners and you cannot delete a company until that relationship is dissolved.

The following example is a client request to remove the profile for company ID Company1:

<OrganizationIdList xmlns="http://www.cyclonecommerce.com/Schemas/2001/07/bapi">
        <organizationId>Company1</organizationId>
</OrganizationIdList>

If a client requests to create or update profiles using RemoveCompanyProfiles or RemovePartnerProfiles, the server acknowledges the request with a disposition. The server response is an OrganizationDataOutputList that shows the status of the request. Each remove request contains a corresponding OrganizationDataOutput indicating the organization ID under the root element. Beneath each OrganizationDataOutput is a disposition indicating success or failure. The following is an example of a response to a remove request:

<OrganizationDataOutputList xmlns="http://www.cyclonecommerce.com/Schemas/2001/07/pmapi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <OrganizationDataOutput xmlns:bapi="http://www.cyclonecommerce.com/Schemas/2001/07/bapi" organizationId=" duns6097">
                <bapi:Disposition id="002" title="Partner removed successfully."/>
        </OrganizationDataOutput>
</OrganizationDataOutputList>

Disposition Codes

The following tables provide disposition codes and descriptions used in the profile management API. Disposition codes are returned when a client makes a set, get or remove request for a company or partner.

User-Defined Metadata for ebXML

You can associate user-defined metadata with ebXML documents that go in and out of WebLogic Integration - Business Connect via an API client. This can be done in the following ways:

The following code is the SOAP envelope portion of an example ebXML message that includes a #wildcard element structure for the user-defined metadata. WebLogic Integration - Business Connect creates the metadata elements for outbound messages and parses the metadata elements for inbound messages. The relevant metadata elements are in bold.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xlink="http://www.w3.org/1999/xlink"
 xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
 xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
 http://ebxml.org/project_teams/transport/envelope.xsd">
<SOAP-ENV:Header xmlns:eb="http://www.ebxml.org/namespaces/messageHeader"
 xmlns:cyclone-props="http://www.cyclonecommerce.com/namespaces/properties"
 xsi:schemaLocation="http://www.ebxml.org/namespaces/messageHeader
 http://ebxml.org/project_teams/transport/messageHeaderv0_99.xsd">
<eb:MessageHeader SOAP-ENV:mustUnderstand="1" eb:id="7206985" eb:version="1.0">
<eb:From>
<eb:PartyId eb:type="Name">sender</eb:PartyId>
</eb:From>
<eb:To>
<eb:PartyId eb:type="Name">receiver</eb:PartyId>
</eb:To>
<eb:CPAId> </eb:CPAId>
<eb:ConversationId>1d0cc7b6c60217cd:e9ba867282:-8000</eb:ConversationId>
<eb:Service eb:type="string">FileTransfer</eb:Service>
<eb:Action>Receive</eb:Action>
<eb:MessageData>
<eb:MessageId>c509914e1d9a9e96:88c0:eb56e5e742:-8000</eb:MessageId>
<eb:Timestamp>2002-01-11T11:53:42.613Z</eb:Timestamp>
</eb:MessageData>
<eb:QualityOfServiceInfo eb:deliveryReceiptRequested="None"
 eb:deliverySemantics="OnceAndOnlyOnce"
 eb:messageOrderSemantics="NotGuaranteed"/>
</eb:MessageHeader>
<eb:Via SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next"
 SOAP-ENV:mustUnderstand="1" eb:ackRequested="Signed"
 eb:reliableMessagingMethod="ebXML" eb:syncReply="true" eb:version="1.0">
<eb:CPAId> </eb:CPAId>
</eb:Via>
<cyclone-props:Properties SOAP-ENV:mustUnderstand="1">
<cyclone-props:Property name="username">administrator</cyclone-props:Property>
<cyclone-props:Property name="password">0M8R4KGxGuEA</cyclone-props:Property>
</cyclone-props:Properties>
</SOAP-ENV:Header>
<SOAP-ENV:Body xmlns:eb="http://www.ebxml.org/namespaces/messageHeader"
 xsi:schemaLocation="http://www.ebxml.org/namespaces/messageHeader
 http://ebxml.org/project_teams/transport/messageHeaderv0_99.xsd">
<eb:Manifest SOAP-ENV:mustUnderstand="1" eb:id="584126810107752" eb:version="1.0">
<eb:Reference eb:id="4582781010775" xlink:href="cid:Test" xlink:type="simple"/>
</eb:Manifest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following sections provide more details about outbound and inbound requirements.

Outbound Integration via HTTP or HTTPS

For outbound document integration via the HTTP or HTTPS API, the additional user data is specified in the HTTP Post using form variables according to the following syntax:

USERKEY0=key name 0
USERDATA0=data value 0
USERKEY1=key name 1
USERDATA1=data value 1

USERKEYN=key value N
USERDATAN=data value N

USERKEYN provides the Nth key name and USERDATAN provides the value associated with the Nth key. The values for these variables must be URI-encoded according to RFC 2396. Thus, the values for key names and data values are limited to being simple strings. The maximums are 30 characters for key names and 128 characters for data values.

WebLogic Integration - Business Connect parses these variables in order (USERKEY0, USERKEY1, , USERKEYN) until the sequence is broken. If variables are posted as USERKEY0, USERKEY1, USERKEY5, then WebLogic Integration - Business Connect parses only USERKEY0 and USERKEY1; USERKEY5 is ignored.

For each USERKEYN variable successfully parsed, WebLogic Integration - Business Connect attempts to parse a corresponding USERDATAN. If values for USERKEYN and USERDATAN cannot both be parsed, the pair is ignored.

The following is an example URL for sending a document using the HTTP or HTTPS document submission API.

http://localhost:5082/InterchangeAPI?SENDERID=mpany1&SENDEREDIID=
Company1&SENDERTRUEID=Company1&SENDERNAME=Company1&RECEIVERID=
Company2&RECEIVEREDIID=Company2&RECEIVERTRUEID=Company2&RECEIVERNAME=
Company2&NAME=out.bin&ORIGINALNAME=out.bin&DOCTYPE=BINARY&CONTROLID=
NA&BACKUP=true&SYNCSEND=false&CORRID=API_CORRID_1017265620018&REFID=
NA&PACKAGINGTYPE=EBXML&PACKAGINGVER=1.0&USERKEY0=userDefinedKey2&USERDATA0=
someUserData2&USERKEY1=userDefinedKey1&USERDATA1=someUserData1

Outbound Integration via RMI

The outbound metadata functionality also is supported through the WebLogic Integration - Business Connect RemoteInterchangeServer interface.

The com.cyclonecommerce.cybervan.api.IntegrationDocument interface in this API includes a method for setting the user data.

The additional user data can be specified in the following method:

An example of this functionality is provided in the FullClient sample code in api\samplecode in the WebLogic Integration - Business Connect installation directory.

Inbound Integration via RMI

Because inbound HTTP clients must supplement their solutions with an RMI-based event client, the inbound metadata functionality is supported through the WebLogic Integration - Business Connect event listener API.

The com.cyclonecommerce.cybervan.api.IntegrationDocument interface in this API includes a method for obtaining the user data. (An IntegrationDocument is only available when a DocumentArrivalEvent is received). The signature of this method is the following:

java.util.Properties getUserData();

All user key-value data pairs are returned in a properties object. The value for any specific key can then be obtained via the getProperty() method.

The following provides more details about the method:

An example of this functionality is provided in the FullClient sample code in api\samplecode in the WebLogic Integration - Business Connect installation directory.

Technical Documentation

Technical documentation for the API is included in the API directory on the WebLogic Integration - Business Connect installation CD or the directory on the computer where the application is installed. It provides details of the methods and fields for the Java classes. The documentation can be viewed or printed using an HTML browser. To access the documentation open the index.html file in the installation_directory/api/documentation directory. It is recommended that you review this documentation before designing your own application.

There also are readme files that provide information about the sample API sample codes in api\samplecode. There is one readme file for each sample code.

Sample Programs

In api/samplecode in the installation directory are sample client applications written in Java 2. You can use all or portions of these samples as you want. There is a readme file for each sample that describes how the sample code works. The samples are described in the following table.

The sample applications demonstrate the various ways of interfacing with the Server application. The sample applications are in a source form only, and you must compile them with your Java compiler before using them. EventClient and FullClient also need to be compiled by the RMI compiler. More information is in the readme.txt file for each application.

If you intend to use FullClient or EventClient you must modify the Server application start-up file, depending on the invocation method and your operating system. The reason is when RMI compiles the class files for these applications, the compiler produces additional files that the Server application needs. If you intend to use these applications remotely, you must copy the stub files to Server and add it to the classpath environment variable.

Support for Correlation IDs

WebLogic Integration - Business Connect supports correlation IDs that are passed to it with documents from an API client, JMS queue or message control document (MCD). Correlation IDs, or conversation IDs, tie together documents as part of conversations. Use of correlation IDs are required in business protocols such as ebXML. Although WebLogic Integration - Business Connect generates correlation IDs for documents that do not have them, a back-end system must pass correlation IDs to WebLogic Integration - Business Connect and track them for correlation IDs to be used in the context of conversations.

Although correlation IDs are not apparent as such in the graphical user interface, they are used in a number of ways in WebLogic Integration - Business Connect. Correlation IDs are written to the database and to the server.log file with every document event. They are included in WebLogic Integration - Business Connect API events, document post-processing, JMS integration and MCDs.

Along with correlation IDs, WebLogic Integration - Business Connect supports reference to message IDs (RefToMessageId) for ebXML. A RefToMessageId is a unique ID of a message that spawned a reply. The RefToMessageId of the first message is contained in the database record of the reply.

API Authentication

The default Administrator user can use the API Authentication window to set a user name and password for the HTTP or HTTPS server that is built into WebLogic Integration - Business Connect for communicating with an API client.

Select Tools—>API—>Authentication in Administrator to open the API Authentication window.

Figure 14-8 API Authentication Window

The following describes the fields on the Preferences window API tab. The fields are described once for both HTTP and HTTPS.