Generating Oracle B2B 11g metadata using Self-Service

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.

Handling positional/delimited flat files with Oracle B2B 11g

After a long time I am blogging again and this time topic is “Handling positional/delimited flat files with Oracle B2B 11g”. From past couple of weeks, many B2B developers posted question on this topic and hence I thought of posting a blog on the same.

So this is what I will cover in this blog –

1. Modeling an ecs for a sample positional flat file
2. Configuring Oracle B2B for a PFF document
3. Testing the outbound and inbound transaction

Step#1 Modeling an ecs for a sample positional flat file:-

First of all we have to create an ecs for a sample positional flat file (PFF) document. I created below ecs for this blog –

I created this ecs for transferring personal information. I have added two records in this ecs with 5 fields. First record represents the headers and hence can occur once at max in the doc. Second record represents the data and hence can occur infinite times in a doc. 

To uniquely identify the document, I have added a tag value “SERIALNUM” for header field “SERIALNO” –

I will configure the same value in B2B to identify the document uniquely.

Now we need to perform the most important and unique step for PFF doc type – generating the parser schema for the ecs. To generate a parser schema for your ecs, open your ecs in B2B doc editor, go to Tools -> Generate Parser Schema, accept the defaults and provide the file name as well as location to save for ecs parser file –

Once you will click on “Save” it will automatically generate a parser schema for your ecs. Parser schema for my ecs looks like –

Once ecs and parser ecs is created, you need to export XSD (File -> Export -> Oracle B2B 2.0) out of it. Also generate test data out of ecs to test the inbound and outbound flows. This activity is same as what we do for any other type of document.

Step#2 Configuring Oracle B2B for a PFF document:-

Now we will configure Oracle B2B with the files we have generated in previous step. 

First of all copy the parser ecs file in the directory $Oracle_SOA_Home\soa\thirdparty\edifecs\XEngine\config\schema (for eg. - D:\OFMW11g\PS3MWHome\Oracle_SOA1\soa\thirdparty\edifecs\XEngine\config\schema)

And add an entry for this parser ecs in $Oracle_SOA_Home\soa\thirdparty\edifecs\XEngine\config\XERegistry.xml. To add this entry, edit the XERegistry.xml in a text editor and add an entry like below in “Positional flat parser schemas” list –

${XERoot}/config/schema/PARSER_ECS_NAME.ecs

Save the changes after adding entry, close the file XERegistry.xml and restart all the servers.

Now create a Document Protocol Version, Document Type and Document Definition under “PositionalFlatFile” on Oracle B2B console –

Use the XSD and transaction set ecs we created in step#1, while creating document definition.

In Identification tab, we will configure the following values to let B2B uniquely identify this document-

Identification Value = SERIALNUM

Identification Start Position = 1

Identification End Position = 9

Now configure both inbound and outbound agreement for same doc-def –

As you can see, I have kept validation and translation enabled in both the agreements. 

Validation option is used to indicate B2B to validate the incoming/outgoing native format document against the ecs configured in respective document definition. Translation option is used to indicate B2B to translate the incoming flat file to XML or to translate an outgoing XML to flat file.

Save, validate and deploy both the agreements.

Step#3 Testing the outbound and inbound transaction:-

Now first of all we will test an outbound case. Drop the XML file, generated from ecs using Document Editor’s Data Generator tool, into the directory of internal listening channel. Make sure that the XML contains the Internal Properties -

Go to Oracle B2B reports section and make sure that message state is “MSG_COMPLETE”. If transaction completes successfully, you will see a positional flat file on the remote trading partner side –

Similarly, to test an inbound flow, pass the positional flat file to B2B through an external listening channel. Go to Oracle B2B reports section and make sure that message state is “MSG_COMPLETE”. If transaction completes successfully, you will see a corresponding XML file on the host trading partner side (in internal delivery channel). You may check Application Message Report to see the content of translated XML.

Now go ahead and experiment more with it.