Creating B2B Metadata Using Self Service API

The Self-service API for Trading Partners and Agreements creation

The primary way to manage trading partners in the Oracle Integration B2B product is through the web-based GUI. This GUI allows authorized users to create, update, delete and validate trading partners and agreements, and to create and deploy configurations. However, there frequently is a need to create trading partners and agreements “on the fly” i.e. programmatically. There also exist situations where a commandline-based way to create trading partners and agreements may be appropriate, such as when needing create trading partners in “bulk”, where it can get really tedious, if not downright impossible to create huge numbers of trading partners using the GUI.

The new Trading Partner self-service API was developed due to these needs, and is driven primarily through XML-based descriptors for Trading Partners and Agreements. This document details the formats of these XML Trading Partner and Agreement descriptors, the usage of the Trading Partner Self-Service API, its capabilities and restrictions, and also includes some samples.

The Trading Partner descriptor XML

A trading partner’s characteristics and capabilities are described through an XML file, whose format is defined by the XSD referenced in the appendix. In this section, we will look at the elements and attributes that make up this XML file.

TradingPartners: The root element that contains 1 or more TradingPartner profiles.
TradingPartnerProfile: This element contains all the information needed to create a Trading Partner and hence is the "root" for a single trading partner. There can be many such elements under the "TradingPartners" element.
Attribute TPName: This specifies the "Name" of the trading partner.
Attribute Description: An optional description for the TradingPartner is specified here.

TradingPartnerID: This element is used to specify zero or more trading partner IDs.
Attribute Type: Specifies the type of the Identification.
Attribute Value: Specifies the value for this type of identification.
Attribute Description: Provides an optional description for the TP ID type.

OperationalCapability: This element contains all the information that describes the operational capability of a trading partner.

SupportedBusinessAction: Describes a SupportedBusinessAction for the trading partner.
Attribute BusinessActionName: Specifies the name of the BusinessAction supported by this trading partner.
Attribute isInitiator: Specifies if the trading partner is the initiator of the business action.
Attribute isFunctionalAckReqd: Specifies if the functional ack is required.

DocumentType: This element is used to specify any DocumentTypeParameters that need to be different from the protocol default, as well as the DocumentDefinition.
Attribute Name: Name of the DocumentType
Attribute Protocol: The name of the document protocol.
Attribute Version: the version of the document protocol.

DocumentTypeParameter: Specifies zero or more DocumentTypeParameters and their values that need to be different from the defaults.
Attribute Name: The name of the Parameter
Attribute Value: The value of the Parameter

DocumentDefinition: Contains information pertaining to the DocumentDefinition.
Attribute Name: The name of the DocumentDefinition
Attribute Description: An optional description for the DocumentDefinition.
Attribute isTranslationEnabled: Indicates if translation should be performed.
Attribute isValidationEnabled: indicates if validation should be performed.
Attribute Definition: Specifies the full path to the file containing the definition (e.g. and XSD file).


CommunicationCapability: This element contains all information pertaining to the communication capbilities of a trading partner.

DeliveryChannel: This element contains information regarding a delivery channel for a trading partner.
Attribute ReceiptNonRepudiation: indicates whether non-repudiation of receipt is required.
Attribute OriginNonRepudiation: indicates whether non-repudiation of origin is required.
Attribute EncryptionEnabled: indicates whether encryption is enabled.
Attribute CompressionEnabled: indicates if compression is enabled.
Attribute TransportSecurityEnabled: indicates whether transport security is enabled. if this is enabled, an HTTP transport would be HTTPS, for example.
Attribute RetryCount: indicates the number of retries.
Attribute TimeToAcknowledge: specified the time window before which an ack is required.
Attribute Name: Specifies the name of the delivery channel; optional. If unspecified, a delivery channel name would be synthesized.

DocumentExchange: Specifies information relating to DocumentExchange for a trading partner.
Attribute Name: Specifies the name of the DocumentExchange; optional. If not specified, and name is synthesized.

ExchangeProtocolRevision: Specifies the ExchangeProtocol.
Attribute Name: Name of the Exchange protocol.
Attribute Version: Specifies the version of the ExchangeProtocol.

ExchangeProtocolParameter: Specifies the ExchangeProtocolParameters that need to be different from the defaults.
Attribute Name: The name of the Parameter
Attribute Value: The value of the Parameter.

Encryption: Contains information relevant to encryption, such as Certificate location.
Certificate: Contains certification information.
Attribute Name: Name of the certificate.
Attribute Location: Specifies the location of the certificate.

Non-Repudiation: Contains information relevant to non-repudiation.

Transport: Specifies the transport information for this Delivery Channel.
Attribute Name: Name of the transport, and is optional. If unspecified, a name will be synthesized.
Attribute URI: The URI/endpoint used by this transport.

TransportServer: Specifies the transport information for this Delivery Channel.
Attribute Name: Name of the transport server, and is optional. If unspecified, one will be synthesized.
Attribute Description: an optional description for the transport server
Attribute HostName: This is required if TransportServer needs to be created
Attribute IPAddress: IPAddress of the host, and is optional.
Attribute UserName: This is required for a new TransportServer. Specifies the username to use (for protocol such as FTP).
Attribute Password: This is required for a new transport server. Specifies the password to use (e.g. FTP).
TransportProtocol: This element identifies the Transport protocol (HTTP etc.)
Attribute Name: The name of the transport protocol.
Attribute Version: The version of the transport protocol.

TransportProtocolParameter: Specifies transport protocol parameters.
Attribute Name: Name of the Parameter.
Attribute Value: Value of the parameter.

The Agreement XML

The Agreement XML contains the following elements:

TPAgreements: Contains descriptions of one or more agreements.

Agreement: This element contains the description for an Agreement.
Attribute Name: The name of the agreement.
Attribute ID: The ID of the agreement.
Attribute Description: description of the agreement.
Attribute EffectiveFromDate: When the agreement is effective from
Attribute EffectiveToDate: Till when the agreement is effective.
Attribute InvocationLimit: Ceiling for the number of invocations.
Attribute ConcurrentConversations: The max number of concurrent instances of this Agreement.

BusinessActionParticipant: This element describes the participants in this business action.
InitiatingTP: Describes the TP initiating the business action.
Attribute TPIDType: The type of the TP ID used in the agreement.
Attribute TPIDValue: The value of the TP ID used in the agreement.

DeliveryChannel: Describes the delivery channel used in the agreement.
Attribute Name: Name of the delivery channel.

RespondingTP: Describes the responding TP in the business action.
Attribute TPIDType: The type of the TP ID used in the agreement.
Attribute TPIDValue: The value of the TP ID used in the agreement.

InternalDeliveryChannel: Describes the Delivery Channel used in the agreement.
Attribute Name: the name of the internal delivery channel used in the agreement.

CalloutUsage: Describes the call out usage in the agreement.
Attribute Name: Name of the callout usage.

Using the SelfService API

The self-service API can be used by clients programmatically to create Trading Partners and Agreements, or can be used in the command-line mode. To use it in the command line:

· java oracle.tip.adapter.b2b.selfservice.TradingPartnerManager
creates the Trading Partner profiles from the specified XML file.
· java oracle.tip.adapter.b2b.selfservice.AgreementManager creates agreements from the specified XML file.

The following code snippet shows how to use the SelfService API programmatically:
FileInputStream fis = new FileInputStream(tpFile);
InputSource is = new InputSource(fis);
TradingPartnerManager tpMgr = TradingPartnerManager.newInstance();
tpMgr.init();
if (args.length == 2) {
tpMgr.processTPProfiles(is, true);
} else {
tpMgr.processTPProfiles(is, false);
}
tpMgr.shutdown();
FileInputStream fis = new FileInputStream(tpFile);
InputSource is = new InputSource(fis);
AgreementManager agreementMgr = AgreementManager.newInstance();
agreementMgr.init();
agreementMgr.processAgreements(is);
agreementMgr.shutdown();

References

1. TPProfile.xsd
2. Agreements.xsd
3. TPProfile samples
4. Agreements samples.

and can be furnished upon request.