18 B2B Command-Line Tools

B2B command-line tools are available for a number of tasks.

Notes:

Command-line tools are for administrator use only. No security or permission checks are performed to prevent the logged-in user from purging, importing, or exporting data.

Note:

All of the command-line tools can be run without any JNDI credentials. To restrict the command-line tools from anonymous use, provide the following information in the jndi.properties file:

java.naming.security.principal=weblogic
java.naming.security.credentials=weblogic_password

This chapter contains the following topics:

Section 18.1, "Prerequisites for Running the Command-line Tools"
Section 18.3, "Purging Data"
Section 18.4, "Importing Data"
Section 18.5, "Exporting Data"
Section 18.6, "Deploying Agreements"
Section 18.7, "Validating B2B Metadata"
Section 18.8, "CPP/CPA Templates"
Section 18.9, "CPP/CPA Import"
Section 18.10, "CPP/CPA Export"
Section 18.11, "Creating Oracle B2B Metadata Based on selfservice.xsd"
Section 18.12, "Resubmitting a Message"
Section 18.13, "Errors During Import"

18.1 Prerequisites for Running the Command-line Tools

Do the following before using the command-line tools:

Set ORACLE_HOME to your Oracle Fusion Middleware installation directory and then set the following environment variables:
- ```
ANT_HOME - $ORACLE_HOME/.../modules/org.apache.ant_1.7.0
```
- ```
JAVA_HOME - $ORACLE_HOME/.../jdk160_11
```

Create jndi.properties.

cd $ORACLE_HOME/bin
ant -f ant-b2b-util.xml b2bcreate-prop

Edit the jndi.properties file to include the weblogic password.

18.2 Archiving Data

Oracle B2B uses Oracle Data Pump as the archiving mechanism for Oracle B2B runtime instance data in Oracle database. Oracle B2B enables archiving functionality only when the Oracle B2B repository is Oracle database. You can configure start date, end date, and message state to archive and/or purge the runtime data.

In order to improve the performance and synchronize archive and purge activity, a new column (JOB_ID) is added in each runtime table - B2B_BUSINESS_MESSAGE, B2B_EXT_BUSINESS_MESSAGE, B2B_APP_MESSAGE, B2B_WIRE_MESSAGE and B2B_DATA_STORAGE.

Oracle B2B will mark the target runtime data (by start date, end date, and message state) with a unique JOB_ID. If you select to archive the runtime data, Oracle B2B will invoke Data Pump PL/SQL API with JOB_ID to export the runtime data. Oracle B2B will purge the runtime messages by JOB_ID if you also want to purge them.

After the runtime data is archived/exported, Oracle B2B can also use Oracle Data Pump to import the runtime data into an Oracle B2b repository.

Before archiving data, you must set up the permissions and the archival directory.

Note:

The b2b_archive utility only supports Oracle database. No other databases are supported.

To do initial setup:

On the machine running the database, create a directory in which to dump the archive file. For example:
```
mkdir /tmp/archive
```
Grant permissions to this directory so that the database process can write to it.
```
chmod 777 /tmp/archive
```
Log in to the database as sysdba.
```
sqlplus / as sysdba
```

Set up the B2B_EXPORT_DIR.

SQL> create or replace DIRECTORY B2B_EXPORT_DIR as '/tmp/archive'

If your SOA schema user is b2b_soainfra, the user needs to be granted permission for the export.

SQL> grant read, write on directory B2B_EXPORT_DIR to dev_soainfra;
SQL> grant exp_full_database  to dev_soainfra;

Note:

Make sure that the initial setup steps detailed above are performed before attempting to archive.

To archive data:

Execute the archive procedure. For example:

SQL> exec b2b_archive_procedure('21-JAN-2008', '28-JAN-2008', 'MSG_COMPLETE', 'JAN.dmp', 'N');

The signature of the procedure is

b2b_archive_procedure(fromDate, toDate, messageState, fileName, shouldPurge);

Table 18-1 Parameters for B2B Archive Procedure

Parameter	Description
fromDate	Starting date for archival
toDate	Ending date for archival
messageState	State of the business message
fileName	Name of the archive file to be created by the database. Verify that a file with this name does not exist in that directory.
shouldPurge	A value of `Y` will remove the rows that are archived.

18.3 Purging Data

Note:

Before purging data, exporting or archiving data is recommended. See Section 18.2, "Archiving Data."

No security or permission checks are performed to prevent the logged-in user from purging data.

The b2bpurge utility only supports Oracle database. No other databases are supported.

The following utility purges both design-time and run-time data and resets the environment to the installation time.

ant -f ant-b2b-util.xml b2bpurge

Table 18-2 lists the options for this utility.

Table 18-2 Options for ant -f ant-b2b-util.xml b2bpurge

Option	Description	Domain	Required
mode	Specifies purging design-time or run-time data. (see Note below)	DT RT	No^Foot 1
msgState	Deletes messages with the specified message state. Used for run-time data.	MSG_COMPLETE MSG_ERROR MSG_WAIT_TRANSMIT MSG_WAIT_FA MSG_WAIT_BATCH	No. If `msgstate` is present, then `start` and `end` must be used.
purgecontrolnumber	Deletes control numbers. Used for run-time data.	`true` `false` (default)	No
`fromdate`	Deletes all messages, which created on or after this date.	Date format dd-mm-yyyy hh:mm AM/PM	No
`todate`	Deletes all messages, which created on or before this date.	Date format dd-mm-yyyy hh:mm AM/PM	No
`tp`	Based on trading partner.		No
`direction`			No
`msgtype`	Type of the message		No
`agreement`	Name of the agreement		No
`idtype`			No
`idvalue`			No
`archive`	Should archive		Default value is `true`
`archivename`	File name of archived file		No

^Footnote 1The option -Dmode=RT is a mandatory argument for b2bpurge to delete only runtime records. This option must be set for every runtime record purge, otherwise purges all of the metadata and runtime data. (Example: ant -f ant-b2b-util.xml b2bpurge -Dmode=RT)

Note:

When only -Dmode=RT -Dtp=trading_partner_name options are used, this option deletes all records matching Trading Partner name with SenderName or in Receiver Name.

Example 18-1 Removes Design-Time Data

ant -f ant-b2b-util.xml b2bpurge -Dmode=DT

Example 18-2 Purges Run-Time Data

ant -f ant-b2b-util.xml b2bpurge -Dmode=RT

Example 18-3 Purges Run-Time Data, Including Control Numbers

ant -f ant-b2b-util.xml b2bpurge -Dmode=RT -Dpurgecontrolnumber=true

Example 18-4 Purges Messages with the Specified State Between the Specified Dates

ant -f ant-b2b-util.xml b2bpurge -Dmode=RT -Dstart=01-FEB-2009 -Dend=10-FEB-2009 -Dmsgstate=MSG_COMPLETE

Note:

When using archivename the value must be a unique file name. An existing file name used with archivename throws an exception.

18.4 Importing Data

Note:

No security or permission checks are performed to prevent the logged-in user from importing data.

The following utility imports a configuration ZIP file to the repository. Basic validation is performed, but it is not a complete validation as with deployment validation. No data is overwritten unless you use the overwrite option.

ant -f ant-b2b-util.xml b2bimport -Dlocalfile=true -Dexportfile="/tmp/export.zip"

Table 18-3 lists the options for this utility.

Table 18-3 Options for ant -f ant-b2b-util.xml b2bimport

Option Description Domain Required

Option	Description	Domain	Required
exportfile	Location of the export (ZIP) file	-	Yes
`overwrite`	Overwrites the existing business elements. For example, an existing delivery channel with the same trading partner name as a delivery channel in the import file is replaced if this option is set to `true`.	`true` `false` (default)	No
`localfile`	If the export file location exists on the server, then set this option to true to improve performance. The export file must be on the server on which B2B is running.	`true` `false` (default)	No

exportfile

Location of the export (ZIP) file

Yes

overwrite

Overwrites the existing business elements. For example, an existing delivery channel with the same trading partner name as a delivery channel in the import file is replaced if this option is set to true.

true

false (default)

localfile

If the export file location exists on the server, then set this option to true to improve performance. The export file must be on the server on which B2B is running.

true

false (default)

18.5 Exporting Data

Note:

No security or permission checks are performed to prevent the logged-in user from exporting data.

The following utility exports the entire repository (without policy details) if no other options are specified.

ant -f ant-b2b-util.xml b2bexport

Table 18-4 lists the options for this utility.

Table 18-4 Options for ant -f ant-b2b-util.xml b2bexport

Option	Description	Domain	Required
exportfile	Location of the ZIP file where the exported data is stored	`/tmp/export.zip` (default)	No
tpname	The trading partner name to be exported	Name of the trading partner	No
tpanames	One or more agreement names to be exported. If one agreement is exported, then the ZIP file contains the folder `/soa/b2b`. If multiple agreements are exported, then the ZIP file contains an individual ZIP file for each of the agreements.	Agreement names must be separated by a comma	No
active	Exports agreements that have been deployed and are in active state.	`true` `false` (default)	No
`policies`	Set to true to export the entire repository with user and role details, which is needed for the policy store. A warning is displayed to remind you to export the policy store also. See Section 10.2, "What Is Copied When You Import or Export from the Import/Export Tab," for more information.	`true` `false` (default)	No
`localfile`	Set to true for improved performance if the export file is on the same computer as Oracle B2B.	`true` `false` (default)	No

Example 18-5 Exports the Trading Partner Acme to /tmp/Acme.zip

ant -f ant-b2b-util.xml b2bexport -Dtpname="Acme" -Dexportfile="/tmp/Acme.zip"

Example 18-6 Exports an Agreement from Design-Time with Listening Channel Details to /tmp/acmeGc.zip

ant -f ant-b2b-util.xml b2bexport -Dtpanames="Acme_GC_Agreement1" -Dexportfile="/tmp/AcmeGc.zip"

Listening channels are deactivated while exporting and must be reactivated after you import data.

Example 18-7 Exports Multiple Deployed and Active Agreements to /tmp/export.zip

ant -f ant-b2b-util.xml b2bexport -Dtpanames="Acme_GC_Agreement1, GC_Acme_Agreement1" -Dactive=true

No listening channels are exported.

18.6 Deploying Agreements

The following utility validates and deploys all agreements in the repository. If an agreement is already deployed, then it is deployed again. The older version of the agreement is then in an inactive state. Turning off validation is useful when deploying large numbers of agreements, where you are certain that the data is valid. It requires a SOA Server restart. Validation can be turned off by setting the property b2b.deploy.validation to false.

ant -f ant-b2b-util.xml b2bdeploy

Table 18-5 lists the options for this utility.

Table 18-5 Options for ant -f ant-b2b-util.xml b2bdeploy

Options	Description	Domain	Required
tpanames	One or more names of agreements to be deployed	Agreement names must be separated by a comma	No

Example 18-8 Deploys the Agreements Acme_GC_Agreement1 and GC_Acme_Agreement1

ant -f ant-b2b-util.xml b2bdeploy -Dtpanames="Acme_GC_Agreement1,GC_Acme_Agreement1"

18.7 Validating B2B Metadata

The following utility validates B2B metadata, including agreements, trading partners, and documents. All agreements are validated if no options are specified.

ant -f ant-b2b-util.xml b2bvalidate

Table 18-6 lists the options for this utility.

Table 18-6 Options for ant -f ant-b2b-util.xml b2bvalidate

Options	Description	Domain	Required
args	File names of the trading partner, agreement, or document protocol	File names must be separated by a comma	Yes

Example 18-9 Validates All Agreements

ant -f ant-b2b-util.xml b2bvalidate

Example 18-10 Validates Agreement tpa_ID1234.xml

ant -f ant-b2b-util.xml b2bvalidate -Dargs="tpa_ID1234.xml"

Example 18-11 Validates Trading Partner tp_MyCompany.xml and Agreement tpa_ID1234.xml

ant -f ant-b2b-util.xml b2bvalidate -Dargs="tp_MyCompany.xml,tpa_ID1234.xml"

18.8 CPP/CPA Templates

The following utility creates a cpp_cpa.properties template file, which is used in the propfile option.

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

Table 18-7 lists the options for this utility.

Table 18-7 Options for ant -f ant-b2b-util.xml b2bcpaimport

Option	Description	Domain	Required
propfile	Property file that stores configuration details for `b2bcpaimport` and `b2bcpaexport`	-	Yes

Example 18-12 Creates a Property File Template That Is Used in the propfile Option

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

18.8.1 Properties of cpp_cpa.properties

The following properties can be configured as part of the cpp_cpa properties file:

CPA Import Properties
CPA Export Properties
Common Properties

18.8.1.1 CPA Import Properties

The CPA import properties are as follows:

```
oracle.tip.b2b.ebms.BPSSDocument (Optional Property)
```
This property holds the absolute path for the BPSS document, which is used to get the BPSS document details to be imported into the Oracle B2B repository. If the property does not exist, then the values are imported from the CPA document. Multiple BPSS documents are separated by ; (semi-colon).
```
oracle.tip.b2b.ebms.CPADocument (Required Property)
```
This property is used to get the absolute path of the CPA document to be imported into the Oracle B2B repository.
```
oracle.tip.b2b.ebms.xsdLocation (Optional Property)
```
This property is used to specify the absolute path of the schema file location. This schema file is used for document validation. It is used only when a BPSS document is specified.
```
oracle.tip.b2b.ebms.internalDeliveryChannel.protocol    (Optional Property)
```
The default internal delivery channel is an AQ queue. If you want to add a specific internal delivery channel (JMS/FTP/FILE/SFTP), then this property is used in Oracle B2B configuration. Specify all the required properties with respect to the specific transport protocol. Then use the specific channel to send messages to back-end applications.

18.8.1.2 CPA Export Properties

The CPA export properties are as follows:

```
oracle.tip.b2b.ebms.OutputFolder (Required Property)
```
This property is used to place the generated CPP/CPA files in the specified location.
```
oracle.tip.b2b.ebms.Host (Required Property)
```
This property is used to set the host trading partner.
```
oracle.tip.b2b.ebms.HostEndPoint (Required Property)
```
This property is used to set the host endpoint while generating the CPP/CPA export.
```
oracle.tip.b2b.ebms.HostCertificateAlias (Optional Property)
```
For secure message transfer, this property is used to get the host certificate details to the CPP/CPA export.
```
oracle.tip.b2b.ebms.TPCertificateAlias (Optional Property)
```
For secure message transfer, this property is used to get the trading partner certificate details to the CPP/CPA export.
```
oracle.tip.b2b.ebms.BPSSExport (Optional Property)
```
This Boolean property is used to generate the BPSS document.

18.8.1.3 Common Properties

The common properties are as follows:

oracle.tip.b2b.ebms.LogDirectory (Required Property)

This property is used to store the log files.

```
oracle.tip.b2b.ebms.LogLevel (Required Property)
```
This property is used to specify the mode of the logs, such as DEBUG, INFO, or ERROR.
```
oracle.tip.b2b.ebms.LogType (Required Property)
```
This property is used to specify whether the log file is stored as text or XML.

18.9 CPP/CPA Import

The following utility converts an ebXML standard cpa.xml file to an Oracle B2B metadata file, which must then be imported into Oracle B2B.

ant -f ant-b2b-util.xml b2bcpaimport

Table 18-8 lists the options for this utility.

Table 18-8 Options for ant -f ant-b2b-util.xml b2bcpaimport

Option	Description	Domain	Required
propfile	Property file that stores configuration details for `b2bcpaimport` and `b2bcpaexport`	-	Yes

Example 18-13 Converts CPA-Formatted XML to an Oracle B2B ZIP File

ant -f ant-b2b-util.xml b2bcpaimport -Dpropfile="/tmp/cpp_cpa.properties"

18.10 CPP/CPA Export

The following utility converts an Oracle B2B metadata file (data exported from Oracle B2B) to an ebXML standard cpa.xml file (a CPA-ready configuration).

ant -f ant-b2b-util.xml b2bcpaexport

Table 18-9 lists the options for this utility.

Table 18-9 Options for ant -f ant-b2b-util.xml b2bcpaimport

Option	Description	Domain	Required
propfile	Property file that stores configuration details for `b2bcpaimport` and `b2bcpaexport`	-	Yes

Example 18-14 Converts an Oracle B2B ZIP File to a CPA-Formatted XML File

ant -f ant-b2b-util.xml b2bcpaexport -Dpropfile="/tmp/cpp_cpa.properties"

18.11 Creating Oracle B2B Metadata Based on selfservice.xsd

The following utility creates the selfservice.xsd file, which is used to understand or create selfservice XML based on the XSD structure.

ant -f ant-b2b-util.xml b2bselfservicexsd

The following utility creates Oracle B2B metadata from the XML file that is created based on selfservice.xsd.

ant -f ant-b2b-util.xml b2bselfservice

See Appendix E or information about selfservice protocols, identifications, and security specifications.

Table 18-10 lists the options for these utilities.

Table 18-10 Options for ant -f ant-b2b-util.xml b2bselfservicexsd

Option	Description	Domain	Required
input	XML file absolute location	-	Yes
output	Location for Oracle B2B metadata stored as a ZIP file	-	No

Example 18-15 Converts b2bselfservicexsd-Generated XML to an Oracle B2B Metadata ZIP file (stored in /tmp/soa.zip)

ant -f ant-b2b-util.xml b2bselfservice -Dinput="/tmp/selfservice1.xml"

Example 18-16 Converts b2bselfservicexsd-Generated XML to an Oracle B2B Metadata ZIP file (stored in /tmp/as11b2b.zip)

ant -f ant-b2b-util.xml b2bselfservice -Dinput="/tmp/selfservice1.xml" -Doutput="/tmp/as11b2b.zip"

18.11.1 Using Selfservice to Batch Create Document Protocols, Trading Partners, and Agreements

When using a multiple file approach, you must make sure that the names of the selfservice XML files are in following order, otherwise, an error claiming that the referenced object does not exist might be thrown.

Document Protocols selfservice XML files.
Trading Partner selfservice XML files (HOST must be first in this list).
Trading Partner Agreement selfservice XML files.

For example:

doc_selfservice.xml to hold Document Protocols.
tp_selfservice.xml to hold Trading Partner details.
tpa_selfservice.xml to hold Agreements details.

Example 18-17 Converts Several b2bselfservicexsd-Generated XML Files Within a Folder to an Oracle B2B Metadata ZIP file (stored in /tmp/as11b2b.zip)

ant -f ant-b2b-util.xml b2bselfservice -Dinput="/folder" -Doutput="/tmp/as11b2b.zip"

18.11.2 Using Selfservice Samples

Selfservice XML samples are bundled along with its schemas and ECS files, which are together with the B2B metadata of B2B Samples configuration.

Selfservice Samples are found in $samples/selfservice folder.

Samples are not available for all of the document and exchange protocol combinations. However, by replacing the document protocol details and exchange protocol details in the existing samples, you can create new XML files.

Note:

Selfservice XML files can also be created using the XSD, which is useful for the advanced user who wants to start from scratch.

X12 Samples

The X12 samples are located in:

$samples/selfservice/x12/b2b-201-X12_4010_850_File/x12_ss.xml

The schemas are located in:

$samples/selfservice/x12/b2b-201-X12_4010_850_File/schemas

Use the following command:

ant -f ant-b2b-util.xml b2bselfservice -Dinput="$samples/selfservice/x12/b2b-201-X12_4010_850_File/x12_ss.xml"

Custom Samples

The Custom samples are located in:

$samples/selfservice/custom/b2b-101-Custom_1.0_orders_generic_file/custom_ss.xml

The schemas are located in;

$samples/selfservice/custom/b2b-101-Custom_1.0_orders_generic_file/schemas

Use the following command:

ant -f ant-b2b-util.xml b2bselfservice -Dinput="$samples/selfservice/ custom\b2b-101-Custom_1.0_orders_generic_file/custom_ss.xml"

ebMS Samples

The ebMS samples are located in:

$samples/selfservice/custom/ b2b-106-Custom_1.0_orders_ebMS/buyer_setup_selfservice/ ebms_buyer_ss.xml

The schemas are located in:

$samples/selfservice/custom/ b2b-106-Custom_1.0_orders_ebMS/buyer_setup_selfservice/schemas

Use the following command:

ant -f ant-b2b-util.xml b2bselfservice -Dinput="$samples/selfservice/custom/ b2b-106-Custom_1.0_orders_ebMS/buyer_setup_selfservice/ ebms_buyer_ss.xml"

18.12 Resubmitting a Message

The following utility resubmits an application message or a wire message for a selected business message.

ant -f ant-b2b-util.xml b2bresubmit

Note:

The resubmit functionality for payload rectification will only work for Outbound Message for AppMessage only. This is not valid for inbound cases.

ant -f ant-b2b-util.xml b2bresubmit -Dmsgsource=appMsg -Dmsgid=12345 -Dpayloadpath=/scratch/viramamo/fmwhome/AS11gR1SOA/bin/3a4_req.xml

Table 18-11 lists the options for this utility.

Table 18-11 Options for ant -f ant-b2b-util.xml b2bresubmit

Option	Description	Domain	Required
direction	The direction of the message	INBOUND OUTBOUND	Yes
msgsource	The message source	APPMSG WIREMSG	Yes
`msgid`	The message ID	-	Yes
`doctype`	Document Type
`msgstate`	Message State
`fromdate`	The `sendTimestamp` of the message	Date format to be provided within Double Quotes dd-mm-yyyy hh:mm AM/PM
`todate`	The `sendTimestamp` of the message
`agreement`	Agreement Name
`payloadpath`	This option is applicable for outbound application message resubmission, by providing the rectified file path.

Example 18-18 Resubmits an Outbound Message with Message ID 12345

ant -f ant-b2b-util.xml b2bresubmit -Ddirection=outbound -Dmsgsource=appMsg -Dmsgid=12345\

Other Examples

ant -f ant-b2b-util.xml b2bresubmit -Dmsgsource=appMsg -Ddoctype=850

ant -f ant-b2b-util.xml b2bresubmit -Dmsgsource=appMsg -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM"

ant -f ant-b2b-util.xml b2bresubmit -Dmsgsource=appMsg -Dagreement="Acme_GlobalChips_X12_4010_850_File" 

ant -f ant-b2b-util.xml b2bresubmit -Dmsgsource=wireMsg -Dmsgstate=MSG_ERROR

ant -f ant-b2b-util.xml b2bresubmit -Dmsgsource=appMsg -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM" -Ddirection=OUTBOUND

ant -f ant-b2b-util.xml b2bresubmit -Dmsgsource=appMsg -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM" -Ddirection=INBOUND

ant -f ant-b2b-util.xml b2bresubmit -Dmsgsource=appMsg -Dmsgid=12345 -Dpayloadpath="/tmp/850.xml"

18.13 Errors During Import

If you get the following broken pipe error, use Oracle WebLogic Server Administration Console to increase Maximum Message Size to 200000000.

[java] Exception in thread "main" java.lang.Exception: java.rmi.UnmarshalException: Broken pipe;
nested exception is:
[java]  java.net.SocketException: Broken pipe
[java] at oracle.tip.b2b.utility.B2BCommandLineUtility.upgradeRepository(B2BCommandLineUtility.java:548)
[java]  at oracle.tip.b2b.utility.B2BCommandLineUtility.main(B2BCommandLineUtility.java:601)
[java] Caused by: java.rmi.UnmarshalException: Broken pipe; nested exception is:
[java] java.net.SocketException: Broken pipe