15 API for Creating Trading Partners and Agreements

With the trading partner self-service API, you can create trading partners and agreements "on the fly" (programmatically) or use the command line utility, particularly to create many trading partners at once. The API uses XML-based descriptors for trading partners and agreements.This chapter details the formats of the XML trading partner and agreement descriptors, describes how to use the trading partner self-service API, and references example files.

This chapter contains the following topics:

• The Trading Partner Descriptor XML

• The Agreement Descriptor XML

• Using the Self-service API

• Example Files

See the following for information on how to create trading partners and trading partner agreements using the OracleAS Integration B2B user interface.

• Chapter 9, "Creating Trading Partners"

• Chapter 12, "Creating and Managing Trading Partner Agreements"

Note: Only creating trading partners and agreements is supported, not updating or deleting. Also, RosettaNet collaborations are not supported in the API.

15.1 The Trading Partner Descriptor XML

The characteristics and capabilities of a trading partner are described through an XML file, whose format is defined by the XSD provided in the example file OrclTPProfilesV2-6.xsd. See "Example Files" for the location of the file.

Table 15-1 lists the elements and attributes of the trading partner XML file.

Table 15-1 Trading Partner Descriptor XML File

Elements	Description and Attributes
TradingPartners	The root element that contains one or more trading partner profiles.
TradingPartnerProfile	Contains all the information needed to create a trading partner, and therefore is the root for a single trading partner. The TradingPartners element can have many such elements under it. Attributes: TPName—Specifies the name of the trading partner. Description—Specifies an optional description for the trading partner.
TradingPartnerID	Specifies zero or more trading partner IDs. Attributes: Type—Specifies the type of the identification. Value—Specifies the value for this type of identification. Description—Provides an optional description for the TP ID type.
OperationalCapability	Contains all the information that describes the operational capability of a trading partner.
SupportedBusinessAction	Describes a supported business action for the trading partner. Attributes: BusinessActionName—Specifies the name of the business action supported by this trading partner. isInitiator—Specifies if the trading partner is the initiator of the business action. isFunctionalAckReqd—Specifies if a functional acknowledgment is required.
DocumentType	Specifies any document type parameters that need to be different from the protocol default, as well as the document definition. Attributes: Name—Specifies the name of the document type. Protocol—Specifies the name of the document protocol. Version—Specifies the version of the document protocol.
DocumentTypeParameter	Specifies zero or more document type parameters and their values that need to be different from the defaults. Attributes: Name—Specifies the name of the parameter. Value—Specifies the value of the parameter.
DocumentDefinition	Contains information pertaining to the document definition. Attributes: Name—Specifies the name of the document definition. Description—Specifies an optional description for the document definition. isTranslationEnabled—Indicates if translation must be performed. isValidationEnabled—Indicates if validation must be performed. Definition—Specifies the full path to the file containing the definition (for example, an XSD file).
CommunicationCapability	Contains all information pertaining to the communication capabilities of a trading partner.
DeliveryChannel	Contains information regarding a delivery channel for a trading partner. Attributes: ReceiptNonRepudiation—Indicates if nonrepudiation of receipt is required. OriginNonRepudiation—Indicates if nonrepudiation of origin is required. EncryptionEnabled—Indicates if encryption is enabled. CompressionEnabled—Indicates if compression is enabled. TransportSecurityEnabled—Indicates if transport security is enabled. If enabled, the HTTP transport could be HTTPS, for example. RetryCount—Specifies the number of retries. TimeToAcknowledge—Specifies the time window before which an acknowledgment is required. Name—Specifies the name of the delivery channel (optional). If unspecified, a delivery channel name is synthesized.
DocumentExchange	Specifies information relating to document exchange for a trading partner. Attributes: Name—Specifies the name of the document exchange (optional). If unspecified, a name is synthesized.
ExchangeProtocolRevision	Specifies the exchange protocol. Attributes: Name—Specifies the name of the exchange protocol. Version—Specifies the version of the exchange protocol.
ExchangeProtocolParameter	Specifies the exchange protocol parameters that must be different from the defaults. Attributes: Name—Specifies the name of the parameter. Value—Specifies the value of the parameter.
Encryption	Contains information relevant to encryption, such as the certificate location.
Certificate	Contains certification information. Attributes: Name—Specifies the name of the certificate. Location—Specifies the location of the certificate.
Non-Repudiation	Contains information relevant to nonrepudiation.
Transport	Specifies the transport information for this delivery channel. Attributes: Name—Specifies the name of the transport (optional). If unspecified, a name is synthesized. URI—Specifies the URI/endpoint used by the transport.
TransportServer	Specifies the transport information for this delivery channel. Attributes: Name—Specifies the name of the transport server (optional). If unspecified, a name is synthesized. Description—Specifies an optional description for the transport server. HostName—Required if a transport server must be created. IPAddress—Specifies the IP address of the host (optional). UserName—Required for a new transport server. Specifies the username to use (for a protocol such as FTP). Password—Required for a new transport server. Specifies the password to use (for example, FTP).
TransportProtocol	Identifies the transport protocol (HTTP for example). Attributes: Name—Specifies the name of the transport protocol. Version—Specifies the version of the transport protocol.
TransportProtocolParameter	Specifies transport protocol parameters. Attributes: Name—Specifies the name of the parameter. Value—Specifies the value of the parameter.

15.2 The Agreement Descriptor XML

The characteristics and capabilities of an agreement are described through an XML file, whose format is defined by the XSD provided in the example file Agreements.xsd. See "Example Files" for the location of the file.

Table 15-2 lists the elements and attributes of the agreement XML file.

Table 15-2 Agreement Descriptor XML File

Elements	Description and Attributes
TPAgreements	Contains descriptions of one or more agreements.
Agreement	Contains the description for an agreement. Attributes: Name—Specifies the name of the agreement. ID—Specifies the ID of the agreement. Description—Describes the agreement. EffectiveFromDate—Specifies the beginning date when the agreement is effective. EffectiveToDate—Specifies the end date when the agreement is effective InvocationLimit—Specifies the ceiling for the number of invocations. ConcurrentConversations—Specifies the maximum number of concurrent instances of this agreement.
BusinessActionParticipant	Describes the participants in this business action.
InitiatingTP	Describes the trading partner initiating the business action. Attributes: TPIDType—Specifies the type of the trading partner ID used in the agreement. TPIDValue—Specifies the value of the trading partner ID used in the agreement.
DeliveryChannel	Describes the delivery channel used in the agreement. Attributes: Name—Specifies the name of the delivery channel.
RespondingTP	Describes the responding trading partner in the business action. TPIDType—Specifies the type of the trading partner ID used in the agreement. TPIDValue—Specifies the value of the trading partner ID used in the agreement.
InternalDeliveryChannel	Describes the Delivery Channel used in the agreement. Attributes: Name—Specifies the name of the internal delivery channel used in the agreement.
CalloutUsage	Describes the callout usage in the agreement. Attributes: Name—Specifies the name of the callout usage.

15.3 Using the Self-service API

Clients can use the self-service API programmatically to create trading partners and agreements, as shown in the following example:

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();

You can also use the command line utility of the API.

To create trading partner profiles from the specified XML file:

java oracle.tip.adapter.b2b.selfservice.TradingPartnerManager <TPData.xml>

To create agreements from the specified XML file:

java oracle.tip.adapter.b2b.selfservice.AgreementManager <AgreementData.xml>

15.4 Example Files

For the following files, go to

Oracle_Home/ip/samples/TPSelfService

• Agreements.xml

• OrclAgreements.xsd

• OrclTPProfilesV2-6.xsd

• TPProfileSampleInstance-7.xml

• TPProfileSampleInstance-8.xml