Darwin-IT: December 2012

Introduction

At my previous customer, a Dutch energy infrastructure managing company, I worked on an implementation of AS2 (http://en.wikipedia.org/wiki/AS2) message exchanging with Oracle B2B (part of SOASuite 11g) The company needed to exchange information about energy delivery with other companies that supply and transport energy.

Problem

Since there are many companies in the enegery market that exchange messages with eachother, in our case, we needed to enter about 80 tradingpartners (TP's), that were very similar in message-exchange capabilities. Instead of entering those 80 TP’s in Oracle B2B by hand, which is a lot of error-prone work, I decided to see if it was possible to automate the process, by generating an export file that would serve as input property file for B2B. Hence, as a start I looked at the B2B selfservice scripts. With those (ANT) scripts you can generate an export file based on a set of definition input xml files. Afterwards this export file can be imported into B2B. This last step can be done manually, but you could even import (deploy) the generated export file and even deploy the agreements automatically.

Generating the export file from an addressing properties input Excel sheet

In our case we had two roles: shippers and suppliers. There are a few differences between the two tradingpartner roles, but all the shippers have the same capabilities as well as all the suppliers.
Hence, shippers and suppliers send and receive about the same set of messages.
Also, all the TP’s are identified in the same way, using a code. Furthermore, all the addressing properties were delivered in an Excel sheet. So I could generate a property file naming all the TP’s with all their properties and their roles. Based on the TP’s role I determined if the TP should be enabled or not: only suppliers and shippers had to be imported, the rest of the TP's I disabled in the property file.

Lets take a look in how this was done.

Initializing

For the scripting I have some base targets and a base property file.
The property file:

dev.mode=false
#dev.mode=true
demo.mode=false
#demo.mode=true

#Generic Environment variables
wl_home=${wn.bea.home}/wlserver_10.3
ant-contrib.jar=${wn.bea.home}/modules/net.sf.antcontrib_1.1.0.0_1-0b2/lib/ant-contrib.jar

# temp
tmp.output.dir=c:/temp
log.dir=${basedir}/logs
host.tpl=${basedir}/templates/Host_tpl.xml
doctypes=${basedir}/templates/DocTypes.xml
supplier.tpl=${basedir}/templates/Supplier_tpl.xml
shipper.tpl=${basedir}/templates/Shipper_tpl.xml
b2bselfservice.tpl.dir=${basedir}/b2bselfservice
b2bselfservice.exp.file=${basedir}/zip/B2BExport.zip


junit.output.dir=../../

jndi.props.tpl=${basedir}/jndi.properties.template
jndi.props=${oracle.home}/bin/jndi.properties

Then I have a library.xml with a LogMessage target:

<?xml version="1.0" encoding="windows-1252" ?>
<project name="library">
      <macrodef name="logMessage">
            <attribute name="message" default=""/>
            <attribute name="level" default="debug"/>
            <sequential>
                  <echo message="@{message}" level="@{level}"></echo>
                  <!-- <echo file="${log.file}" append="true"
                        message="@{message}${line.separator}" level="@{level}"></echo> -->
                  <echo file="${log.file}" append="true"
                        message="@{message}${line.separator}"></echo>
            </sequential>
      </macrodef>
</project>

Now and the start of my build.xml:

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- B2B Utilities
@author Martien van den Akker, Darwin-IT Professionals
@version 0.1, 2012-11-22
-->
<project name="B2BScripting" basedir=".">
    <property environment="env"/>
    <property name="deploy.basedir" value="${basedir}"/>
    <!-- Default environment property dir -->
    <property file="${basedir}/build.properties"/>
    <property file="${env.prop.dir}/tradingPartner.properties"/>
    <import file="${basedir}/library.xml"/>
    <taskdef resource="net/sf/antcontrib/antlib.xml">
        <classpath>
            <pathelement location="${ant-contrib.jar}"/>
        </classpath>
    </taskdef>
    <!-- Deploy Targets -->
    <!-- Clean Up logs -->
    <target name="clean">
        <echo>Delete log dir ${log.dir}</echo>
        <delete dir="${log.dir}"/>
    </target>
    <!-- initialize project -->
    <target name="init" depends="clean">
        <echo>Dev mode: ${dev.mode}</echo>
        <echo>Target environment: ${deployment.plan.environment}</echo>
        <echo message="Create log dir" level="debug"></echo>
        <mkdir dir="${log.dir}"/>
        <!-- Build time -->
        <tstamp>
            <format property="build.date" pattern="yyyy-MM-dd HH:mm:ss"/>
        </tstamp>
        <!-- Build number -->
        <condition property="build.number" value="${env.BUILD_NUMBER}">
            <isset property="env.BUILD_NUMBER"/>
        </condition>
        <buildnumber file="build.num"/>
        <property name="log.file"
                  value="${log.dir}/instance-${build.number}.log"/>
    </target>
    <!-- log env properties -->
    <target name="logEnvProps" depends="init">
        <echo>BEA Home: ${wn.bea.home}</echo>
        <echo>Oracle Home: ${oracle.home}</echo>
        <echo>Java Home: ${java.home}</echo>
        <echo>Log File: ${log.file}</echo>
    </target>

The templates

As a starting point for the scripts I used the documentation on the B2B Utilities, see: B2B Command-Line Tools. Also I found the blog of Anuj Dwivedi on this subject very usefull.

You can put all the definitions of DocumentTypes, Trading partners and agreements in one file. Or you can split them up in several files. Important is that the different files have to be ordered alphabetically, first the documenttypes, then the ones with the tradingpartners and then the agreements. I decided to have the documenttypes in one file named 1_docTypes.xml, the host trading partner named 2_tp_1234567000004.xml and then the different tradingpartners named 3_TP-<id>.xml. Where the <id> is expanded to the 18-digit code of the particular remote TP. And I put the agreements and the tradingpartner-definitions per tradingpartner in one file.

The documentypes

The documenttypes are defined as follows:

<?xml version="1.0" encoding="windows-1252" ?>
<SelfService xmlns="http://xmlns.oracle.com/integration/b2b/selfservice/profile">
  <DocumentProtocols>
    <DocumentProtocol name="Custom">
      <DocumentProtocolVersion name="MSGORG_V1.2">
        <!-- METER -->
        <DocumentType name="METERAcknowledgementDocType">
          <DocumentDefinition customFileType="true"
                              definitionFileName="../../../EnergyCieMDS/apps/MSGORG/xsd/v1.2/METERAcknowledgement_1p2.xsd"
                              name="METERAcknowledgement"
                              useDefaultDefinition="false">
            <ParameterValue name="IdentificationExpression"
                            value='/*[local-name()="METERAcknowledgementEnvelope"]'/>
          </DocumentDefinition>
        </DocumentType>
        <DocumentType name="METERNotificationDocType">
          <DocumentDefinition customFileType="true"
                              definitionFileName="../../../EnergyCieMDS/apps/MSGORG/xsd/v1.2/METERNotification_1p2.xsd"
                              name="METERNotification"
                              useDefaultDefinition="false">
            <ParameterValue name="IdentificationExpression"
                            value='/*[local-name()="METERNotificationEnvelope"]'/>
          </DocumentDefinition>
        </DocumentType>
      </DocumentProtocolVersion>
    </DocumentProtocol>
  </DocumentProtocols>
</SelfService>

You see that the main tag is "SelfService". This tag applicable for every selfservice-xml-file. So all the definitions should be contained within the "SelfService" tag.
The xsd that this xml implements can be generated using the SelfService ant utilities that are delivered with SOASuite as follows:

set BEA_HOME=D:\Oracle\Middleware\SOASuite11g
set ORACLE_HOME=%BEA_HOME%\Oracle_SOA1
set ANT_HOME=%BEA_HOME%\modules\org.apache.ant_1.7.1
set PATH=%ANT_HOME%\bin;%PATH%
set JAVA_HOME=%BEA_HOME%\jdk160_24 

ant -f %ORACLE_HOME%\bin\ant-b2b-util.xml  b2bselfservicexsd

This delivers an XSD that you can register in JDeveloper. Doing so, JDeveloper can help you edit the XML, since it knows what nodes and attributes come where.

The Host Tradingpartner

The host tradingpartner comes next in line, here's my sample template:

<?xml version="1.0" encoding="windows-1252" ?>
<SelfService xmlns="http://xmlns.oracle.com/integration/b2b/selfservice/profile">
  <TradingPartners>
    <TradingPartner hosted="true" name="${hostTp.name}">
      <!-- Host Trading Partner -->
      <Identification name="Name" value="${hostTp.name}"/>
      <Identification name="Generic" value="${hostTp.generic.name}"/>
      <Identification name="AS2 Identifier" value="${hostTp.AS2.id}"/>
      <DeliveryChannel ackMode="None" compressed="false" internal="true"
                       listening="false"
                       name="${hostTp.short}_AQ_IN_INT_Channel"
                       responseMode="None" retryCount="3" retryInterval="3">
        <ExchangeProtocolRef name="Generic-AQ"/>
        <TransportProtocolRef name="AQ">
          <ParameterValue name="queue_name" value="IP_IN_QUEUE"/>
          <ParameterValue name="datasource" value="jdbc/SOADataSource"/>
        </TransportProtocolRef>
      </DeliveryChannel>
      <SupportedDocumentDefinition docDefName="METERAcknowledgement"
                                   docProtocolName="Custom"
                                   docProtocolVersion="MSGORG_V1.2"
                                   docTypeName="METERAcknowledgementDocType"
                                   initiator="false"/>
      <SupportedDocumentDefinition docDefName="METERNotification"
                                   docProtocolName="Custom"
                                   docProtocolVersion="MSGORG_V1.2"
                                   docTypeName="METERNotificationDocType"
                                   initiator="true"/>
    </TradingPartner>
  </TradingPartners>
</SelfService>

So here you see that the name of the tradingpartner as well as the AS2 Identifier is filled with an ANT property that will come from a property file that I will give later on.
Since in our case the Tradingpartners where identified by 18-digit-numbers, I added a "Generic" identifier for a more human-readable name. After the identifications come the Delivery Channels, and after that the SupportedDocumentDefinitions: the capabilities. The Internal Delivery Channel I used was the AQ, which I think is the preferred.

The Remote TradingPartner

<?xml version="1.0" encoding="windows-1252" ?>
<SelfService xmlns="http://xmlns.oracle.com/integration/b2b/selfservice/profile">
  <TradingPartners>
    <TradingPartner hosted="false" name="${tp.name}">
      <Identification name="AS2 Identifier" value="${tp.AS2.id}"/>
      <Identification name="Name" value="${tp.name}"/>
      <Identification name="Generic" value="${tp.generic.name}"/>
      <DeliveryChannel listening="false"
                       name="${tp.name}_AS2_OUT_EXT_SNGENC_Channel"
                       internal="false">
        <ExchangeProtocolRef name="AS2"/>
        <TransportProtocolRef name="HTTP">
          <ParameterValue name="url" value="${tp.AS2.host}"/>
          <ParameterValue value="true" name="use_proxy"/>
        </TransportProtocolRef>
        <DigitalSecurity ackSigned="true" messageEncrypted="true"
                         messageSigned="true" transportSecured="true">
          <DigitalSignature securitySpecificationName="SMIME-3_0-SHA-RSA"
                            certAlias="${hostTp.cert.alias}"/>
          <DigitalEncryption securitySpecificationName="SMIME-3_0-DES"
                             certAlias="${tp.cert.alias}"/>
          <!--     <TransportSecurity securitySpecificationName="SSL"
                             certAlias="${tp.cert.alias}"/> -->
        </DigitalSecurity>
      </DeliveryChannel>
      <SupportedDocumentDefinition docDefName="METERAcknowledgement"
                                   docProtocolName="Custom"
                                   docProtocolVersion="MSGORG_V1.2"
                                   docTypeName="METERAcknowledgementDocType"
                                   initiator="true"/>
      <SupportedDocumentDefinition docDefName="METERNotification"
                                   docProtocolName="Custom"
                                   docProtocolVersion="MSGORG_V1.2"
                                   docTypeName="METERNotificationDocType"
                                   initiator="false"/>
     
    </TradingPartner>
  </TradingPartners>
  <Agreements>
    <!--METER-->
    <Agreement agreementId="${tp.name}_Custom_MSGORG_V1.2_METERAcknowledgementDocType_METERAcknowledgement_Inbound"
               name="${tp.name}_Custom_MSGORG_V1.2_METERAcknowledgementDocType_METERAcknowledgement_Inbound"
               effectiveFromDate="${agreement.effectiveFromDate}" >
      <SupportedDocumentType docProtocolName="Custom"
                             docProtocolVersion="MSGORG_V1.2"
                             docTypeName="METERAcknowledgementDocType"
                             docDefName="METERAcknowledgement">
        <InitiatingParticipant name="${tp.name}">
          <Identifications>
            <IdentificationRef name="Name" value="${tp.name}"/>
            <IdentificationRef name="AS2 Identifier" value="${tp.AS2.id}"/>
          </Identifications>
          <DeliveryChannels>
            <DeliveryChannelRef name="${tp.name}_AS2_OUT_EXT_SNGENC_Channel"/>
          </DeliveryChannels>
        </InitiatingParticipant>
        <RespondingParticipant name="${hostTp.name}">
          <Identifications>
            <IdentificationRef name="Name" value="${hostTp.name}"/>
            <IdentificationRef name="AS2 Identifier" value="${hostTp.name}"/>
          </Identifications>
          <DeliveryChannels>
            <DeliveryChannelRef name="${hostTp.short}_AQ_IN_INT_Channel"/>
          </DeliveryChannels>
        </RespondingParticipant>
      </SupportedDocumentType>
    </Agreement>
    <Agreement agreementId="${tp.name}_Custom_MSGORG_V1.2_METERNotificationDocType_METERNotification_Outbound"
               name="${tp.name}_Custom_MSGORG_V1.2_METERNotificationDocType_METERNotification_Outbound"
               effectiveFromDate="${agreement.effectiveFromDate}" >
      <SupportedDocumentType docProtocolName="Custom"
                             docProtocolVersion="MSGORG_V1.2"
                             docTypeName="METERNotificationDocType"
                             docDefName="METERNotification">
        <InitiatingParticipant name="${hostTp.name}">
          <Identifications>
            <IdentificationRef name="Name" value="${hostTp.name}"/>
            <IdentificationRef name="AS2 Identifier" value="${hostTp.name}"/>
          </Identifications>
          <DeliveryChannels/>
        </InitiatingParticipant>
        <RespondingParticipant name="${tp.name}">
          <Identifications>
            <IdentificationRef name="Name" value="${tp.name}"/>
            <IdentificationRef name="AS2 Identifier" value="${tp.AS2.id}"/>
          </Identifications>
          <DeliveryChannels>
            <DeliveryChannelRef name="${tp.name}_AS2_OUT_EXT_SNGENC_Channel"/>
          </DeliveryChannels>
        </RespondingParticipant>
      </SupportedDocumentType>
    </Agreement>

  </Agreements>
</SelfService>

The Remote trading partner is basically the same, except that I can have more of these and in stead of the AQ Delivery Channel, I have a AS2 Delivery channel. And of course the capabilities, the SupportedDocumentDefinitions are complementary to those of the Host. That means that where the host is Initiator, the Remote TP is not and vice versa.

Within each TP I also have agreements for each SupportedDocumentDefinition stating the correct Identifications and delivery channels.

And that's about it for the templates.

The Script

Propertyfile

First the property file of the tradingpartners. I named the file tradingpartner.properties:

tp.list=1234567000005,1234567000006,1234567000004 
hostTp.name=1234567000004
hostTp.short=NMI
hostTp.generic.name=NetManager Inc.
hostTp.AS2.id=1234567000004
hostTp.cert.alias=1234567000004netManager
agreement.effectiveFromDate=2012-11-27T00:00:00+01:00
#agreement.effectiveToDate=
# Trading Partner Props
#tp.enabled=true
#tp.name=
#tp.role=
#tp.generic.name=
#tp.AS2.id=
#tp.AS2.host=
#tp.cert.alias=
#tp.SSLcert.alias=
#
# 1234567000005 - SupplierCie
1234567000005.enabled=true
1234567000005.name=1234567000005
1234567000005.role=Supplier
1234567000005.generic.name=Supplier Cie
1234567000005.AS2.id=1234567000005
1234567000005.AS2.host=https://b2b-prd.SupplierCie.nl/as2-endpoint
1234567000005.cert.alias=1234567000005SupplierCie
#1234567000005.SSLcert.alias=
#
# 1234567000006 - ShipperCie
1234567000006.enabled=true
1234567000006.name=1234567000006
1234567000006.role=PV/shipper
1234567000006.generic.name=Shipper Cie
1234567000006.AS2.id=1234567000006
1234567000006.AS2.host=https://b2b-prd.ShipperCie.nl/as2-endpoint
1234567000006.cert.alias=1234567000006ShipperCie
#1234567000006.SSLcert.alias=
#
# 1234567000004 - NetManager Inc.
1234567000004.enabled=false
1234567000004.name=1234567000004
1234567000004.role=NNO
1234567000004.generic.name=NetManager Inc.
1234567000004.AS2.id=1234567000004
1234567000004.AS2.host=https://b2b.netmanager.com/b2b/httpreceiver
1234567000004.cert.alias=1234567000004NMI.cer
#1234567000004.SSLcert.alias=

Create All TP Definitions

The folllowing target is the main target for generating the trading partner definitions.
It starts with copying the doctype template to the folder where the selfservice files are gathered. Then the selfservice file for the host TP is generated based on the template explained above. At the end for each tradingpartner named in the tp.list in the tradingpartner property file the corresponding selfservice file is generated. The last step is calling the target that calls the selfservice api to generate the B2B export zip-file.

 <!-- Create All TP Definitions -->
    <target name="createAllTPDefinitions" depends="logEnvProps">
        <logMessage message="createAllTPDefinitions" level="info"/>
        <logMessage message="basedir ${basedir}" level="info"/>
        <logMessage message="date = ${build.date}" level="info"/>
        <logMessage message="build = ${build.number}" level="info"/>
        <logMessage message="environment = ${deployment.plan.environment}"
                    level="info"/>
        <logMessage message="List of TradingPartners = ${tp.list}"
                    level="info"/>
        <delete dir="${b2bselfservice.tpl.dir}"/>
        <delete file="${b2bselfservice.exp.file}"/>
        <mkdir dir="${b2bselfservice.tpl.dir}"/>
        <logMessage message="======> Copy ${doctypes}" level="info"/>
        <copy file="${doctypes}"
              tofile="${b2bselfservice.tpl.dir}/1_docTypes.xml"
              overwrite="true">
            <filterchain>
                <expandproperties/>
            </filterchain>
        </copy>
        <copy file="${host.tpl}"
              tofile="${b2bselfservice.tpl.dir}/2_tp_${hostTp.name}.xml"
              overwrite="true">
            <filterchain>
                <expandproperties/>
            </filterchain>
        </copy>
        <foreach list="${tp.list}" param="tradingPartner"
                 target="createTPDefinitions" inheritall="true"
                 inheritrefs="false"/>
        <!-- Create B2B Export -->
        <antcall target="b2bCreateExport"/>
    </target>

Create the Remote Trading Partner definitions

Below the target for the generation of the Remote TP definitions.
It does a copy of the properties form the selected trading partner to corresponding generic properties. These are used in the expansion of the properties in the tradingpartner template on copying the file to the selfservice file for the selected tradingpartner. Since there are two tradingpartner-types in our case (Shippers and Suppliers) you'll find an if on the tradingpartner role. Based on the role the specific template is being copied to the remote tradingpartner's selfservice file.

<!-- Create TradingPartner Definitions -->
    <target name="createTPDefinitions">
        <logMessage message="createTPDefinitions" level="info"/>
        <propertycopy name="tp.enabled" from="${tradingPartner}.enabled"/>
        <echo message="${tradingPartner} enabled:${tp.enabled}"></echo>
        <if>
            <equals arg1="${tp.enabled}" arg2="true"/>
            <then>
                <logMessage message="${line.separator}====>Create config for Tradingpartner ${tradingPartner}"
                            level="info"/>
                <propertycopy name="tp.name" from="${tradingPartner}.name"/>
                <propertycopy name="tp.role" from="${tradingPartner}.role"/>
                <propertycopy name="tp.generic.name"
                              from="${tradingPartner}.generic.name"/>
                <propertycopy name="tp.AS2.id" from="${tradingPartner}.AS2.id"/>
                <propertycopy name="tp.AS2.host"
                              from="${tradingPartner}.AS2.host"/>
                <propertycopy name="tp.cert.alias"
                              from="${tradingPartner}.cert.alias"/>
                <logMessage message="======> Name: ${tp.name}" level="info"/>
                <logMessage message="======> Role: ${tp.role}" level="info"/>
                <logMessage message="======> Generic Name: ${tp.generic.name}"
                            level="info"/>
                <logMessage message="======> AS2.id: ${tp.AS2.id}"
                            level="info"/>
                <logMessage message="======> AS2.host: ${tp.AS2.host}"
                            level="info"/>
                <logMessage message="======> cert.alias: ${tp.cert.alias}"
                            level="info"/>
                <if>
                    <equals arg1="${tp.role}" arg2="Supplier"/>
                    <then>
                        <logMessage message="======> Copy ${supplier.tpl} for ${tp.name}"
                                    level="info"/>
                        <copy file="${supplier.tpl}"
                              tofile="${b2bselfservice.tpl.dir}/3_tp_${tp.name}.xml"
                              overwrite="true">
                            <filterchain>
                                <expandproperties/>
                            </filterchain>
                        </copy>
                    </then>
                </if>
                <if>
                    <equals arg1="${tp.role}" arg2="PV/shipper"/>
                    <then>
                        <logMessage message="======> Copy ${shipper.tpl} for ${tp.name}"
                                    level="info"/>
                        <copy file="${shipper.tpl}"
                              tofile="${b2bselfservice.tpl.dir}/3_tp_${tp.name}.xml"
                              overwrite="true">
                            <filterchain>
                                <expandproperties/>
                            </filterchain>
                        </copy>
                    </then>
                </if>
            </then>
            <else>
                <logMessage message="${line.separator}====>Skip Tradingpartner ${tradingPartner}"
                            level="info"/>
            </else>
        </if>
    </target>

Create B2B Export

The above targets generate the document types, host-tradingpartner and remote tradingpartner definitions in files in a specific folder, denoted by the ${b2bselfservice.tpl.dir} property.
Based on the generated files in that folder the b2bexport zip can be generated, using the following target:

<target name="b2bCreateExport">
        <logMessage message="${line.separator}====>Create B2B Export"
                    level="info"/>
        <if>
            <equals arg1="${demo.mode}" arg2="false"/>
            <then>
                <ant antfile="${oracle.home}/bin/ant-b2b-util.xml"
                     inheritall="false" target="b2bselfservice">
                    <property name="input" value="${b2bselfservice.tpl.dir}"/>
                    <property name="output" value="${b2bselfservice.exp.file}"/>
                </ant>
            </then>
        </if>
    </target>

Conclusion

The export-file that is generated in the last target can then be imported to the target environment.
This import can be done with the import/export tooling under the administration tab within the b2bconsole. I found that somehow it only works with internet explorer. Using Firefox or Chrome I get an error-message stating that the Zip is not valid.
It is also possible to import the file using scripting like I explained above. But since this blog is already becoming a heavy one, I keep that for a following blog. Keeps me writing. And actually with the explanation above you should be able to figure that out...

Thursday, 6 December 2012

Generate Tradingpartners for Oracle B2B 11g with Ant