Oracle Fusion Middleware - Integration B2B and Oracle Service Bus: 2012

Recently few customers contacted me to understand the Self-Service functionality of Oracle B2B 11g and hence I thought to post a blog on the same. In this blog, I will walk you through the creation of self-service XML file, its usage and its limitations.

Step#1- Prerequisite for Running the Command-line Tools

As you may already know, B2B has many command line tools including Self-Service. To invoke and use any command line tool, you need to set few environment variables appropriately. Following are the variables which need to be set for using B2B command line tools -

ORACLE_HOME – Set it to the Oracle SOA home

(for e.g. - D:\OFMW11g\PS3MWHome\Oracle_SOA1)

ANT_HOME – Set it to $MW_Home/modules/org.apache.ant_1.7.1

(for e.g. - D:\OFMW11g\PS3MWHome\modules\org.apache.ant_1.7.1)

JAVA_HOME – Set it to the Java installation directory

(for e.g. - D:\OFMW11g\PS3MWHome\jdk160_21)

PATH – Include the $ANT_HOME/bin directory into the PATH

(for e.g. - set PATH=%PATH%;D:\OFMW11g\PS3MWHome\modules\org.apache.ant_1.7.1\bin)

After setting all the above environment variables, navigate to $ORACLE_HOME/bin directory and run below command to generate jndi.properties file which is used for providing connection and authentication information to B2B command line tools -

ant -f ant-b2b-util.xml b2bcreate-prop

You should be able to see a message like “jndi.properties file successfully created” after running above command and you can find jndi.properties file in directory $ORACLE_HOME/bin

Now open the jndi.properties file in any text editor and edit the below properties –

java.naming.provider.url – Change the host and port information as per your domain’s configuration

java.naming.security.principal – Provide an admin user’s username here

java.naming.security.credentials – Provide the password of the admin user here

As an optional step, you may create a file with name ant_general.properties in directory

$ORACLE_HOME/bin with below content –

exitonerror=true

It will make sure that ANT will fail in case of any error while running any

command. By default irrespective of command’s result, ANT shows the returned

system code as “0” (build successful).

If you do not want ANT to fail for all the commands then do not create the

above file. You may add the parameter “-Dexitonerror=true” in any command (selectively)

if you want ANT to fail in case of that particular command run failure.

Step#2 – Generating selfservice.xsd

To create Oracle B2B metadata using Oracle B2B Self-Service API, you need to provide all configuration related information in XML format and that XML must adhere to the selfservice.xsd. You may generate selfservice.xsd by running below command –

ant -f ant-b2b-util.xml b2bselfservicexsd

Above command will generate file selfservice.xsd in directory $ORACLE_HOME/bin.

Step#3 – Creating selfservice.xml and generating B2B Metadata

You can generate a selfservice.xml file (template) from selfservice.xsd using any XML editor or JDeveloper and then you can edit it to add the desired values in it.

Remember that –

1. SelfService must be the root element in the self-service XML

2. SelfService root element may have three child elements –

DocumentProtocols

TradingPartners

Agreements

If all three elements are present in your XML then they must be in above order.

3. The first child element (TradingPartner) of TradingPartners element must have host TP information i.e. value of attribute hosted must be true(hosted="true”).

There are two ways by which you can provide data to Self-Service API to create B2B Metadata –

i) Provide all the data in one XML file

ii) Create separate files for DocumentProtocols, TradingPartners and Agreements

A) Providing all the data in single XML file

If you are providing data in single XML file then it must have DocumentProtocols information in it, which means you can create only document(s) using Self-Service XML but you cannot create only TradingPartner or only Agreement using it.

To create only trading partner, you have to include DocumentProtocols information in the self-service XML as well. Similarly, to create Agreements, you have to include DocumentProtocols and TradingPartners information in the self-service XML.

Below is a sample Self-Service XML to create a TP set-up –

<?xml version="1.0" encoding="UTF-8"?>
<SelfService xmlns="http://xmlns.oracle.com/integration/b2b/selfservice/profile">
 <DocumentProtocols>
  <DocumentProtocol name="Custom" custom="true">
          <DocumentProtocolVersion name="1.0">
      <DocumentType name="PurchaseOrder">
   <DocumentDefinition customFileType="true" startingXSDFilePath="PO_Interface.xsd" definitionFileName="PO_XSD.zip" name="PODocDef" useDefaultDefinition="false">
    <ParameterValue name="IdentificationExpression" value="/*[local-name()='PurchaseOrder']"/>
   </DocumentDefinition>
      </DocumentType>
  </DocumentProtocolVersion>
  </DocumentProtocol>
 </DocumentProtocols>
 <TradingPartners>
   <TradingPartner hosted="true" name="OracleServices">
   <Identification name="Generic" value="10.11.12.*"/>
                <SupportedDocumentDefinition docDefName="PODocDef"
    docProtocolName="Custom" docProtocolVersion="1.0"
    docTypeName="PurchaseOrder" initiator="false" />
  <SupportedDocumentDefinition docDefName="PODocDef" docProtocolName="Custom" docProtocolVersion="1.0" docTypeName="PurchaseOrder" initiator="true"/>
   
   </TradingPartner>
  <TradingPartner hosted="false" name="GlobalChips">
       <Identification name="Generic" value="11.12.13.*"/>
       <Identification name="Name" value="GlobalChips"/>
  <DeliveryChannel name="Gen_HTTP_Channel" internal="false" listening="false">
   <ExchangeProtocolRef name="Generic-HTTP" version="1.0">
   </ExchangeProtocolRef>
   <TransportProtocolRef name="HTTP">
    <ParameterValue value="https://11.12.13.14/b2b/transportServlet" name="url"/>
    <ParameterValue value="true" name="use_proxy"/>
   </TransportProtocolRef>
  </DeliveryChannel>
  <DeliveryChannel compressed="false" responseMode="None" ackMode="None" name="Gen_MAIL_Channel" internal="false" listening="false">
     <ExchangeProtocolRef name="Generic-Email" version="1.0">
     </ExchangeProtocolRef>
     <TransportProtocolRef name="Email">
      <ParameterValue value="localhost" name="host"/>
      <ParameterValue value="anuj@anuj.com" name="email-id"/>
      <ParameterValue value="PoP3" name="server"/>
     </TransportProtocolRef>
  </DeliveryChannel>
    <SupportedDocumentDefinition docDefName="PODocDef" docProtocolName="Custom" docProtocolVersion="1.0" docTypeName="PurchaseOrder" initiator="false"/>
   
 </TradingPartner>
 </TradingPartners>
 <Agreements>
 
                 <Agreement agreementId="POOutboundAgr" name="POOutboundAgr">
                        <SupportedDocumentType docDefName="PODocDef" docProtocolName="Custom" docProtocolVersion="1.0" docTypeName="PurchaseOrder">
                                <InitiatingParticipant name="OracleServices">
                                       <Identifications>
                                                <IdentificationRef name="Generic" value="10.11.12.*"/>
                                                <IdentificationRef name="Name" value="OracleServices"/>

                                        </Identifications>
                                </InitiatingParticipant>
                                <RespondingParticipant name="GlobalChips">
                                        <Identifications>

                                                <IdentificationRef name="Generic" value="11.12.13.*"/>
                                    <IdentificationRef name="Name" value="GlobalChips"/>
                                        </Identifications>
                                        <DeliveryChannels>
      <DeliveryChannelRef name="Gen_HTTP_Channel"/>
     </DeliveryChannels>
 
                                </RespondingParticipant>
                                <AgrDocTypeParameterValues>
                                        <ParameterValue name="validate" value="true"/>
                                </AgrDocTypeParameterValues>
                        </SupportedDocumentType>
                </Agreement>
          </Agreements>
</SelfService>

Run below ant command to create Oracle B2B metadata-

ant -f ant-b2b-util.xml b2bselfservice -Dinput="Self_Service_Path" -Doutput="B2B_Metadata_Path"

where-

Self_Service_Path is the absolute path of Self-Service XML file and

B2B_Metadata_Path is the absolute path of B2B Metadata file to created

So if you have stored above XML in directory /tmp with name selfservice.xml and you want to generate B2B metadata in same directory with name B2B_Export.zip, then run below command -

ant -f ant-b2b-util.xml b2bselfservice -Dinput="/tmp/selfservice.xml" -Doutput="/tmp/B2B_Export.zip"

B) Providing Document, Trading Partner and Agreement information in separate self-service XML’s

In case you want to create B2B metadata for huge number of partners, agreements and docs then this approach is useful. If you are following this approach then remember that –

1. You can define Documents, TradingPartners and Agreements in separate files but all XML’s should adhere to the Self-Service.xsd which means all of them must have root element as SelfService

2. For each document protocol, there can be ONLY one XML i.e. all Documents belonging to same protocol must be defined in same XML however for different Document Protocols you may have different XML's. For an example, you cannot create two separate self-service XML’s for Custom document however you may have separate self-service XML’s for each Custom, X12, EDIFACT etc.

3. All the self-service XML’s must reside in one directory

4. Naming of self-service XML’s must be done in such a manner that while listing in alphabetical order, they get listed in below sequence –

Document Protocol Self-Service XML’s (in any order)
Trading Partner Self-service XML having detail of Host TP
Trading Partner Self-service XML(s) having detail of Remote TP (s) in any order
Agreement Self-service XML’s in any order

For an example, you can name all Document Protocol self-service XMLs with prefix “doc_” and name host TP self-service XML with prefix “tp_host_” and name remote TP self-service XMLs with prefix “tp_remote_” and name agreement self-service XMLs with prefix “tpa_”

Run below ant command to create Oracle B2B metadata-

ant -f ant-b2b-util.xml b2bselfservice -Dinput="Self_Service_Dir" -Doutput="B2B_Metadata_Path"

where-

Self_Service_Dir is the absolute directory path where all self-service XML’s are stored and B2B_Metadata_Path is the absolute path of B2B Metadata file to created

For an example, suppose if all the self-service XML’s are present in directory /tmp/ss then command will be like -

ant -f ant-b2b-util.xml b2bselfservice -Dinput="/tmp/ss" -Doutput="/tmp/B2B_Export.zip"

You can find all parameters and their values (which you can add in self-service XML), in B2B user guide at below link –

http://docs.oracle.com/cd/E23943_01/user.1111/e10229/app_selfservice.htm#BABFCIAJ

Now go ahead and experiment more with it. In case of any issue/query, please raise a thread in Oracle B2B forum.

Oracle Fusion Middleware - Integration B2B and Oracle Service Bus

Friday, July 6, 2012

Generating Oracle B2B 11g metadata using Self-Service