Using WebLogic Integration - Business Connect
|
 |
 |
|
|
 |
 |
The following topics are provided about the application program interface (API) capabilities of WebLogic Integration - Business Connect.
The application program interfaces (APIs) enable you to integrate with WebLogic Integration - Business Connect across three functional areas: document integration, event listening and profile management.
The APIs are accessed singly or by a combination of Java programs, Java message service (JMS) or Simple Object Access Protocol (SOAP). These APIs work with, but do not override, the standard document integration options that can set up by company. For details about the standard interfaces see Company Profile Integration Tab.
In the WebLogic Integration - Business Connect api/samplecode installation directory are sample client applications written in Java 2. 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.
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.
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.
If you want to compile or run any of the sample code or if you want to write your own code for the RMI document submission or event listener API, you need a Java 2 SDK version 1.3. For information about obtaining this, see http://java.sun.com/j2se/1.3/. Java 2 Runtime Environment (J2RE) version 1.3 is provided upon installing WebLogic Integration - Business Connect.
A SOAP implementation compatible with Apache SOAP 2.2 is required to directly use the profile management API. There is no requirement for Java for the profile management API; you can use another language.
If you try 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.
You need a JMS server to use the global JMS event integration API, the global JMS document integration API and the JMS document integration by company API.
It is incumbent on you to correctly write an API and properly configure WebLogic Integration - Business Connect for successful operation. You need the following knowledge and skills to use the APIs:
Technical documentation for the APIs is included in the WebLogic Integration - Business Connect API directory.
There are two types of documentation in the API directory:
index.html in api/documentation. The Java documentation defines the APIs. It defines all the entry points, parameters and return codes.
We recommend that you review this documentation before designing your own application.
Figure 15-1 Page from Java Documentation in api/documentation/index.html
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 RosettaNet and 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) in packaging documents. 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.
You can associate user-defined meta data 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 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. The following sections provide more details about outbound and inbound requirements.
The following code is the SOAP envelope portion of an example ebXML message that includes a #wildcard element structure for the user-defined meta data. WebLogic Integration - Business Connect creates the meta data elements for outbound messages and parses the meta data elements for inbound messages. The relevant meta data elements are in bold.
Listing 15-1 Example SOAP Envelope an ebXML Message
<?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.
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.
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=mpany2&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
The outbound meta data 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 directory.
Because inbound HTTP clients must supplement their solutions with an RMI-based event client, the inbound meta data 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 directory.
You can place any type of data you want in an MCD used for ebXML trading that is not otherwise defined in the MCD. You define the elements in a specific format in the MCD and then provide values for them.
Figure 15-2 shows the proper location of the user-defined meta-data elements after the end of the StatusInfo element. The meta-data are between the opening and closing cyclone-prop:Property elements. The user-defined data in this example are username and password and their values.
Figure 15-2 User-Defined Meta-Data Elements in ebXML MCD
The soap:mustUnderstand property in the first line can have a value of 0 or 1. A value of 0 means your partner's ebXML message service handler (MSH) is not required to understand the cyclone-prop:Property elements and the user-defined data. If the receiving system does not understand, it can ignore the elements and the data. A value of 1 forces your partner's trading software to understand the data or else reject the ebXML document and respond with a soap:mustUnderstand fault or an ebXML not supported error message. If your partner uses WebLogic Integration - Business Connect, use 1.
The following is an example from Figure 15-2 of a user-defined element and its value. You can define as many elements are you want.
<cyclone-prop:Property cyclone-prop:name="password">abcdefg</cyclone-prop:Property>
The following describe the attributes that are used for user-defined data. These are required and need to be used as-is.
The following attribute defines the cyclone-prop namespace prefix:
xmlns:cyclone-prop=http://www.cyclonecommerce.com/namespaces/properties attribute
The following attribute defines the SOAP namespace prefix:
xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
The following attribute points to the WebLogic Integration - Business Connect properties schema:
xsi:schemaLocation
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
To set HTTP or HTTPS ports for communications with an API client, see Preferences Ports Tab.
If you use the API HTTPS port for integration, you must generate or load a certificate for the HTTPS server using the certloader tool. See Certificate Tool (certloader).
Figure 15-3 API Authentication Window
The following describes the fields on the Preferences window API tab. The fields are described once for both HTTP and HTTPS.
The user name that you specify for the API HTTP or HTTPS server. The API client uses this to access the server.
The password that you specify for the API HTTP or HTTPS server. The API client uses this to access the server.
Select this check box only if the API HTTPS server will authenticate the client certificate. See Configuring the API Server to Authenticate an API Client.
|
|
|
