Using WebLogic Integration - Business Connect
|
 |
 |
|
|
 |
 |
The following topics describe the WebLogic Integration - Business Connect profile management application program interface (API).
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 profile management API enables you to 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 format has a corresponding schema file.
The following summarizes the functionality of the profile management API:
All profile management functions require a client session object as a parameter to the SOAP method being invoked. All sessions used to communicate with the server are anonymous. The following topics describe how to create and end a client session:
You need to know two things to create a client session. The first is the name of the session authenticator to use. The second is the URL to the profile management server.
Because the server only uses anonymous authentication, the name of the authenticator is always Anonymous. This value is case-sensitive and must be used as shown or authentication will fail.
The URL consists of the protocol (HTTP or HTTPS) followed by the server, port and the resource. The resource is always api/servlet/rpcrouter. For example, to connect to the profile management server using a normal socket and with the server on a machine named pmapiserver and listening on port 5081, the URL is:
http://pmapiserver:5081/ api/servlet/rpcrouter
The ClientSesssion class contains a factory method that allows you to create a client session object to use in SOAP method calls. To create a client session, invoke the createSession method of the class.
ClientSession clientSession = ClientSession.createSession("Anoymous", url);
The sample code in api\samplecode\ConfigurationClient has examples of how to create a client session.
As previously explained, you create a client session for the purpose of invoking a SOAP method of the profile management server. After you have invoked a method, you should immediately terminate the session by invoking the close method of the ClientSession object. This allows the server to remove old conversations from its pool. If you need to make several SOAP call, it is best to create a new session each time and close the previous session. If you fail to close sessions, the server will close them after 30 seconds of inactivity.
The profile management API enables the following functions:
FindCompaniesFindPartnersGetCompanyProfilesGetPartnerProfilesSetCompanyProfilesSetPartnerProfilesRemoveCompanyProfilesRemovePartnerProfilesSetCompanyProfilesSetPartnerProfilesThere 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 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>
The important element in this example is bapi:Disposition, and the important attributes to this tag are id and title. For a table describing disposition codes, see Disposition Codes.
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 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 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>
The important element in this example is bapi:Disposition, and the important attributes to this tag are id and title. For a table describing disposition codes, see Disposition Codes.
The following tables and graphics show company and partner disposition codes and validation message schemas.
Disposition codes are returned when a client makes a set, get or remove request for a company or partner profile. If a profile does not pass the server validation (for example, a required field is missing or blank), the server also includes a validation message element with the disposition.
The following table provides company disposition codes and descriptions. If the client calls a request to create or update a company profile using the SetCompanyProfiles method, the server acknowledges the request with a disposition.
|
Company created successfully, but errors are present. The status has been set to inactive. |
|
|
Company updated successfully, but errors are present. The status has been set to inactive. |
|
Figure 17-1 shows the company validation message schema. The server returns a CompanyValdiationMessage element with the disposition when the server cannot validate a SetCompanyProfiles call from the client.
Figure 17-1 Company Validation Message Schema
The following table provides partner disposition codes and descriptions. If the client calls a request to create or update a partner profile using the SetPartnerProfiles method, the server acknowledges the request with a disposition.
|
Partner created successfully, but errors are present. The status has been set to inactive. |
|
|
Partner updated successfully, but errors are present. The status has been set to inactive. |
|
Figure 17-2 shows the partner validation message schema. The server returns a PartnerValdiationMessage element with the disposition when the server cannot validate a SetPartnerProfiles call from the client.
Figure 17-2 Partner Validation Message Schema
Figure 17-3shows a high-level view of the profile management API.
Figure 17-3 Profile Management Client Updates Server
Key to Figure 17-3
createSession method to authenticate and create a session with WebLogic Integration - Business Connect.createSession method assigns a unique ID to the client. The session ID must be passed back to WebLogic Integration - Business Connect in all subsequent calls.
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 Toolsreadme.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:
|
|
|