To learn about conversation definitions in WebLogic Integration 2.1 SP2, see Configuring Conversation Definitions in Administering B2B Integration at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wlintegration/v2_1/b2badmin/cfgtasks.htm#998395

To learn about conversation definitions in WebLogic Integration 7.0 SP2, see Configuring Conversation Definitions in Administering B2B Integration at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs70/b2badmin/cfgtasks.htm#1003805

To export your TPM configuration data, do the following:

If you are not using a keystore in your WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 B2B application, you must create one.

The WebLogic Integration 8.1 Trading Partner Management uses the keystore to manage trading partner's certificates. (Trading Partner Management holds only the entry of the certificate in the keystore). To learn about keystores, see WebLogic B2B Security Upgrade.

Export your WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 B2B repository information to an XML file using the Bulk Loader or the WebLogic Integration B2B Console export functions.

Note: If you are exporting repository information from a running system using the command-line Bulk Loader utility, you must use the -force option.

WebLogic Integration 2.1 SP2: To learn about exporting repository data from this version of WebLogic Integration, see the following documents:

• Working with the Bulk Loader in Administering B2B Integration at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wlintegration/v2_1/b2badmin/bulkload.htm.

• Exporting Repository Data in the Online Help for the WebLogic Integration B2B Console at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wlintegration/v2_1/b2bhelp/admncfg.htm#1000060.

WebLogic Integration 7.0 SP2: To learn about exporting repository information in this version of WebLogic Integration, see the following documents:

• "Exporting Data from the Repository" in the WebLogic Integration 7.0 Administering B2B Integration at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs70/b2badmin/bulkload.htm#1082771

• Exporting Repository Data in the Online Help for the WebLogic Integration B2B Console at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs70/b2bhelp/admncfg.htm#1000060

Transfer the exported TPM XML file to your target environment for the WebLogic Integration 8.1 application.
To import the TPM XML file into your WebLogic Integration 8.1 upgrade application, go to Upgrading TPM Configuration Data.

Upgrading TPM Configuration Data

This step applies only if you are upgrading B2B integration components.

WebLogic Integration 8.1 provides a TPM upgrade utility for upgrading Trading Partner Management (TPM) configuration data and its associated services and profiles from WebLogic Integration 2.1 SP2 and WebLogic Integration 7.0 SP2.

Note: The TPM upgrade utility upgrades configuration data, not run-time state data.

What the Trading Partner Management Upgrade Utility Does

The TPM upgrade utility upgrades the following:

• Trading Partner information:
• trading-partner and its attributes, including: name, description, notes, type, email, phone, fax, and username.
• address
• extended-property-set
• Trading partner's security certificate. See Exporting Trading Partner Management Configuration Data and WebLogic B2B Security Upgrade.
• ebxml-binding
• transport (under the <ebxml-binding> element)
• authentication (under the <transport> element)
• rosettaNet-binding
• Service information:
• service—For each conversation-definition where the business-protocol is either ebxml or rosettanet, there are two roles. For each role, two service elements are generated in the upgraded WebLogic Integration 8.1 repository XML file, one for the process-type service and the other for the control-type service.
• service-profile

Information Not Upgraded by the Utility

The following information is not mapped by the TPM upgrade utility:

• wlc/logic-plugin, wlc/business-protocol-definition—Replaced by B2B protocol data in WebLogic Integration 8.1.
• wlc/trading-partner/xpath-expression—Applied to XOCP which was deprecated in WebLogic Integration 7.0 SP2.
• wlc/conversation-definition/role/process-implementation—Does not apply in WebLogic Integration 8.1.
• update-count—Does not apply in WebLogic Integration 8.1.

Limitations

The TPM upgrade utility has the following limitations:

• Does not upgrade run-time state data.
• The deprecated XOCP and cXML business protocols related entries are not upgraded.
• Does not upgrade the B2B protocol stack, which is mostly static and provided with WebLogic Integration 8.1.
• The upgraded trading partner data is not formatted. If formatting is needed, use an editor such as XML SPY to format this data.

Warning Case

As mentioned in Exporting Trading Partner Management Configuration Data, if a value does not exist for the WLPI Template Name attribute in your B2B conversation-definition role, you may enter one (if applicable) before upgrading. If this value does not exist, you will receive the following warning:

<date and time> <Error> <Upgrade> <600001>
<Missing wlpi-templateattribute in the conversation-Definition/role
element. No workflow nor control service will be generated for this role.>

You can add this information after using the TPM upgrade utility with the WebLogic Integration Administration Console. To learn about importing, see "Trading Partner Management" in Managing WebLogic Integration Solutions at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/manage/tpm.html

Using the Trading Partner Management Upgrade Utility

Before you can use the TPM upgrade utility, you must first export this information to an XML file as described in Exporting Trading Partner Management Configuration Data.

To upgrade your TPM data using the TPM upgrade utility, do the following:

On a Windows system, open a command window.
In both Windows and UNIX, go to the following directory:

BEA_HOME/weblogic81/integration/upgrade

In the preceding line, BEA_HOME represents the WebLogic Platform home directory.

Execute the upgrade of B2B configuration data by entering:

Windows: upgradeTPM.cmd <sourceFileName> <targetFileName> [workflowPath] [ctrlPackage]

UNIX: upgradeTPM.sh <sourceFileName> <targetFileName> [workflowPath] [ctrlPackage]

Table 5-1 contains the command-line parameters for the upgradeTPM utility.

After the file is successfully transformed, the following message is displayed:

<date and time> <Info> <Upgrade> <600003> <Transformation Completed Successfully>

Transformation Completed Successfully

If the file is not successfully transformed, an error message is displayed.

Table 5-1 Command-Line Parameters for the upgradeTPM Utility


 

Command	Description
sourceFileName	The directory path and name of the TPM XML file to be upgraded.
targetFileName	The directory path and name of the upgraded TPM XML file.
workflowPath (Optional)	The path name of the workflow that uses the ebXML control, such as bea.myOrders. Note: If you know the workflow path, enter this parameter; otherwise, leave it blank. After the TPM data is loaded, you can add this parameter in the WebLogic Integration Administration Console—>Trading Partner Management—> Service Management—>Name field. See" Viewing and Changing Services" in Managing WebLogic Integration Solutions at the following URL: http://download.oracle.com/docs/cd/E13214_01/wli/docs85/manage/tpm.html
ctrlPackage (Optional)	The package name of the ebXML Control, such as bea.ebxmlCtrlPackage. Note: If you know the control package name, enter this parameter; otherwise, leave it blank. After the TPM data is loaded, you can add this parameter using the WebLogic Integration Administration Console—>Trading Partner Management—>Service Management—>Business Service Name field. See "Viewing and Changing Services" in Managing WebLogic Integration Solutions at the following URL: http://download.oracle.com/docs/cd/E13214_01/wli/docs85/manage/tpm.html


 

To verify the upgrade and add optional configuration data, import the upgraded file using the WebLogic Integration Administration Console. To learn about importing, see "Importing Management Data" in Managing WebLogic Integration Solutions at the URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/manage/tpm.html

If you are upgrading application integration components, go to Exporting Application Views and other AI Repository Artifacts; otherwise, go to Upgrading Workflows.

Exporting Application Views and other AI Repository Artifacts

This step applies only if you are upgrading application integration (AI) components.

Different utilities are needed to export Application Views and other AI repository artifacts from WebLogic Integration 2.1 SP2 and WebLogic Integration 7.0 SP2 to JARs that can be imported into your WebLogic Integration 8.1 upgrade application. These utilities export Application Views, connection factories schemas, and namespaces into a single JAR file. After exporting, transfer the JAR file to your target environment for the WebLogic Integration 8.1 application.

Note: Upgrading Application Views should be done only if you are using corresponding adapters in WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 and WebLogic Integration 8.1 (for example, WebLogic Adapter for RDBMS 7.1 and WebLogic Adapter for RDBMS for WebLogic Integration 8.1).

Exporting AI Repository Artifacts

Note: If you are exporting WebLogic Integration 2.1 SP2 repository artifacts, you must edit the aiExport21.cmd file to use the correct path for the setEnv.cmd, as described in Edit aiExport21. The aiExport21 utility is included in WebLogic Integration 8.1.

To export AI Repository Artifacts, do the following:

On a Windows system, open a command window.
In both Windows and UNIX, go to one of the following directories:

WebLogic Integration 2.1 SP2: BEA_HOME/weblogic81/integration/upgrade

WebLogic Integration 7.0 SP2: BEA_HOME/weblogic700/integration/bin

In the preceding paragraphs, BEA_HOME represents the WebLogic Platform home directory.

Execute the exporting of the repository artifacts.

WebLogic Integration 2.1 SP2

Usage for exporting:

aiexport21 <WLS URL> <user name> <password> <file>
[-codepage=<#>][-dump=< <namespace> | <'Root'> ] [-append]
< [-export [object name]*] >

Table 5-2 contains the command-line parameters for the aiexport21 utility.

WebLogic Integration 7.0 SP2

Usage for exporting:

aiimportexport <WLS URL> <user name> <password> <file>
[-codepage=<#>][-dump=< <namespace> | <'Root'> ] [-append]
< [-export [object name]*] >

Table 5-2 contains the command-line parameters for the aiimportexport and aiexport21 utilities.

Table 5-2 Command-Line Parameters for the aiExport21 and aiimportexport Utilities

Parameter	Description
WLS URL	URL of WebLogic Server.
user name	Your username for the specified WebLogic Server.
password	Your password for the specified WebLogic Server.
file	The JAR file exported from the WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 application.
-codepage	Optional. The codepage used when writing to console. It ensures that characters are displayed correctly. The default is Cp437 (United States).Other valid values include: Cp850 Multilingual (Latin I) Cp852 Slavic (Latin II) Cp855 Cyrillic (Russian) Cp857 Turkish Cp860 Portuguese Cp861 Icelandic Cp863 Canadian-French Cp865 Nordic Cp866 Russian Cp869 Modern Greek MS932 Japanese The value specified must match your console's codepage. Note: On Window systems the chcp command displays the console's codepage.
-dump	Prints a list of all objects within both the specified namespace and other namespaces nested within it. To print a list of objects for the entire directory structure, specify Root.
-append	Appends exported items to the file specified by file instead of overwriting it.
-export	Specifies an export operation and the name of the objects to be exported (namespaces and application views) and any objects they contain. These objects are stored into file. When specifying an object within a namespace use "." as the delimiter (for example, mynamespc.myappview). Note: To export the entire directory structure, include Root in the list of object names.


 

To upgrade WebLogic Integration 2.1 SP2 and WebLogic Integration 7.0 SP2 custom or third-party adapters, go to Repackaging Application Integration Adapters and Deploy.

To import Application Views and other AI repository artifacts, go to Importing Application Views and Other AI Repository Artifacts.

Repackaging Application Integration Adapters and Deploy

This step applies only if your are upgrading application integration (AI) components.

WebLogic Integration 8.1 provides a aiRepackageAdapter utility for upgrading WebLogic Integration 2.1 SP2 and WebLogic Integration 7.0 SP2 custom and third-party adapters. Specifically, this utility converts adapter EARs (Enterprise Archive file) to WebLogic Integration 8.1 EARs.

Note: Note, do not use the aiRepackageAdapter utility for upgrading BEA Adapters. You should use BEA WebLogic Adapters^TM 8.1. To learn about BEA adapters, see BEA WebLogic Adapters 8.1 at the following URL:

http://download.oracle.com/docs/cd/E13207_01/wladapters/docs81/index.html

What the aiRepackageAdapter Utility Does

Differences exist between the structure of WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 EAR files and WebLogic Integration 8.1 EAR files. Previous WebLogic Integration EARs contained a design-time WAR (Web Application file), a run-time RAR (Resource Adapter Archive), and an event router WAR, while the WebLogic Integration 8.1 EAR contains only a design-time WAR and a run-time RAR.

The aiRepackageAdapter utility performs the following functions:

• Removes the event router WAR and incorporates the event generator classes into the run-time RAR.
• Generates a ResourceAdapter implementation class using the init-param information from the event router WAR's web.xml and the other overview information in the run-time RAR's ra.xml file. This ResourceAdapter implementation takes the place of the event router for accepting event subscriptions and delivering events, and also acts as a container for connection factories.
• Updates the ADK JSP files that have changed and removes obsolete ADK JSP files. Updates design-time WAR's web.xml and weblogic.xml to refer to the new JSPs.
• Update the adapter properties file with new property information from the ADK.
• Provides new versions of all ADK and WLAI JARs.

Using the aiRepackageAdapter Utility

To repackage your adapters, do the following:

On a Windows system, open a command window.
In both Windows and UNIX, go to the following directory:

BEA_Home\weblogic81\integration\upgrade

In the preceding line, BEA_HOME represents the WebLogic Platform home directory.

Execute the repackaging of the adapter by entering (without the .EAR extension):

Windows: aiRepackageAdapter.cmd <parent_dir> <Adapter EAR File Name>

UNIX: aiRepackageAdapter.sh <parent_dir> <Adapter EAR File Name>

In the preceding paragraphs, parent_dir represents the parent directory of the WebLogic Integration 7.0 SP2 EAR file.

For example:

aiRackageAdapter.cmd d:\weblogic700\integration\adapters\dbms\lib BEA_WLS_DBMS_ADK

The repackaged adapter is named <adapter name>_8.1.ear and located in the parent directory.

Deploy the repackaged adapter in your WebLogic Integration 8.1 application. See Deploying WebLogic Integration Solutions at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/deploy/index.html.

Note: When you deploy, the application name should be the name of the adapter without the _81.ear suffix. If the suffix is used, the adapter cannot be used by WebLogic Integration 8.1. For example, the application name of a supplier_8.1.ear is supplier. The module (file) name can remain the same.

Importing Application Views and Other AI Repository Artifacts

This step applies only if you upgrading application integration (AI) components.

WebLogic Integration 8.1 provides an import-export utility for importing Application Views and other AI repository artifacts from a WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 AI repository. This utility can be executed from the command line, or incorporated into your code with the import-export API. The output of the utility is a JAR file.

What the Import-Export Utility Does

Upgrading your WebLogic Integration 7.0 SP2 AI repository is required because the WebLogic Integration 8.1 AI repository is contained in the directory structure of the application's local file system, while the repository for WebLogic Integration 7.0 SP2 is contained in a Relational DataBase Management System (RDBMS) database. Moreover, objects stored in the WebLogic Integration 8.1 repository have changed, as shown in the following list:

• Application View descriptor
• No longer has an Access Control List (ACL). All access control is defined in the WebLogic Integration Administration Console. See WebLogic Server Security Upgrade.
• Contains an imports section for importing adapter instances and connection factories for use in event delivery and service invocation.
• The Connection factory descriptor is no longer a top-level AI object. This object is now a child element of the new adapter descriptor.
• Adapter descriptor—This is a new object type in WebLogic Integration 8.1. This descriptor contains information about the adapter type and inbound messaging (event delivery), as well as zero or more connection factory descriptors.
• Schema descriptor—This descriptor is unchanged for 8.1.

Limitations

Shared connection factories—When an Application View that uses a shared connection factory is imported into WebLogic Integration 8.1, it will have an invalid adapter instance reference. When you are ready to test and publish the upgraded Application View, you need to correct the invalid reference. To make the correction, do the following:

In the Application Integration Design Console, select the Application View with the invalid adapter instance reference.
After the console page displays the Define Application View page, select the correct adapter from the Associated Adapter drop list.
Click Reuse Existing Connection.
Select an existing Adapter Instance for the Application View to use.

Note: To learn more about testing and publishing Application Views, see "Defining an Application View" in Using the Application Integration Design Console at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/aiuser/1usrntr.html

Namespace mismatch—Application Views upgraded to WebLogic Integration 8.1 using the import-export utility will have a namespace added to the request and response schema. If an XmlObject is used in the upgraded business process, such as in an XPath function, the upgraded files will not contain the namespace information. Subsequently, the XPath function will not work properly because of the namespace mismatch. The DTF (Data Transfer Format) file generated by the Upgrade Wizard must be edited to contain the namespace information. The DTF file is located in the HOME_BEA/weblogic81/<Upgrade Project>/<Upgrade Project>Web/process folder.

In the preceding paragraph, BEA_HOME represents the WebLogic Platform home directory.

For example, if a WebLogic Integration 7.0 SP2 document contains the following:

<RowsAffected>1</RowsAffected>

in WebLogic Integration 8.1, it is upgraded to look like this:

<ns0:RowsAffected xmlns:ns0="wlai/DemoDBMS_CreateCustomer_response"> 1 </ns0:RowsAffected>

The XPath function that is generated by the import-export utility is:

/**
     * Original xpath = "/RowsAffected/text()"
     * @dtf:transform xquery="string( $xmlInput/self::RowsAffected/text())"
     * 
     */
    abstract  public String xpath_2(XmlObject xmlInput);

You must manually add the namespace information so that the XPath function can work properly, as indicated by the bold text:

/**
* Original xpath = "/RowsAffected/text()"
* @dtf:transform xquery="declare namespace
ns0='wlai/DemoDBMS_CreateCustomer_response" string( $xmlInput/self::ns0:RowsAffected/text())"
*
*/
abstract public String xpath_2(XmlObject xmlInput);

Using the Import-Export Utility

To upgrade AI repository artifacts using the WebLogic Integration 8.1 import-export utility, complete the following steps:

Note: Before upgrading your repository, you must have created an application in WebLogic Workshop, as described in Creating an Application For Upgrade. By default a new application contains a project named "Schemas". If your application does not have a Schemas project, you must create one using WLI System Schemas as the project type. The project determines the location of the repository. To learn about creating a Schemas project, see How Do I: Create a Schemas Project Folder in the WebLogic Workshop Help at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/howdoI/howSchemasCreate.html

Note: Before you can use the import-export utility, you must first export this information to a JAR file as described in Exporting Application Views and other AI Repository Artifacts.

Using the WebLogic Integration 8.1 import-export utility, import the JAR into your applications project's Schemas folder. Detailed steps are provided in Invoking the Import-Export Utility from the Command Line.
(Optional) Create an event properties file. This file provides the properties needed for event generation within the adapter instance that is created for the named connection factory. BEA recommends that this file be named <adapter name>-eventProps.properties.
(Optional) Create an event properties file. The recommended name for this file is <adapter name>-eventProps.properties.

The event properties file represents the properties for an event connection that will be paired with a named connection factory in a newly generated adapter instance.

The event properties file is used to configure event delivery on the newly created adapter instance that wraps the existing WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 connection factory descriptors. This is only necessary when the generated adapter instance is used to support event delivery for Application Views that use events. If you do not specify the event properties file, and the Application Views that uses that connection factory has defined events, you will need to use the Application Integration Design Console to edit the event connection being used by the Application View to allow for event delivery on that Application View.

If you do not specify an event properties file when importing connection factories, you will have to edit your adapter instances using the Application Integration Design Console.

To learn more about specifying event properties, see "Defining an Application View" in Using the Application Integration Design Console at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/aiuser/1usrntr.html

Test and publish your imported Application Views and other AI repository artifacts.

Note: You must complete this step before upgrading your workflows, as described in Upgrading Workflows.

To learn more about testing and publishing Application Views, see "Defining an Application View" in Using the Application Integration Design Console at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/aiuser/1usrntr.html

Invoking the Import-Export Utility from the Command Line

The usage for importing with the import-export utility is:

Usage: aiimportexport <app name> <root dir> <file> <codepage>

-import [-publish]

[-eventProps=<connection factory name>,<properties file name>]*

For example:

aiimportexport UpgradeProcesses
c:bea\weblogic81\samples\integration\UpgradeProcesses
d:bea\weblogic81\integration\70exports\appvies.jar cp437
-import -publish
-eventProps=myFactory,myAdapter-eventProps.properties 

In the proceeding command, myFactory is the connection factory name within the JAR exported from the WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 repository.

Note: This usage is specific to importing JAR files that have been exported from WebLogic Integration 2.1 and WebLogic Integration 7.0 SP2 applications. For full usage, see "Importing and Exporting Application Views" in the Using the Application Integration Design Console at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/aisuer/imp_appx.html

The following table contains the command-line parameters for the import-export utility.

The following properties are typically found in a WebLogic Integration 7.0 SP2 EventRouter web.xml file. You can safely not include them in the event properties file.

• eventGeneratorClassName
• RootLogContext
• AdditionalLogContext
• LogConfigFile
• LogLevel
• MessageBundleBase
• LanguageCode
• CountryCode

Using the Import-Export API

You can invoke the import-export utility directly from the API. The class name for the import-export API is com.bea.wlai.client.ImportExport. The following code provides an example for importing.

Listing 5-1 Sample Code for Importing

String exportFilename = "myExportFile.jar";
String appName = "MyApp";
String appRootDir = "d:\\apps\\MyApp";
boolean overwrite = true;
boolean publish = true;
List errors = new LinkedList(); // List of Exception objects

Map eventPropsMap = new HashMap();
// Add properties file names (String) as the values keyed by the
// qualified names of the connection factories the properties are
// to be used with. This list can be null if you don't want any
// mappings applied.
eventPropsMap.put("Folder1.AppView1_connectionFactory",
                  "d:/myFiles/propsFor_Folder1.AppView1_connectionFactory");

ImportExport ie = new ImportExport(new File(exportFilename));

try
{
  ie.connect(appName, appRootDir);

  ie.importNamespaceObjects(overwrite, publish, eventPropsMap, errors);
}
catch (Exception e)
{
  System.err.println("Fatal errors encountered:\n");
  e.printStackTrace();
  return;
}

if (errors.size() > 0)
{
  System.err.println("Non-fatal errors encountered:\n");
  int pos = 1;
  Iterator i = errors.iterator();
  while (i.hasNext())
  {
    Exception e = (Exception) i.next();
    System.err.println("Error " + pos + ": " + e);
    e.printStackTrace(m_out);
    pos++;
  }
}

Upgrading Workflows

WebLogic Integration 8.1 provides an Upgrade Wizard for upgrading workflows and other application information developed in WebLogic Integration 2.1 SP2 and WebLogic Integration 7.0 SP2 to WebLogic Integration 8.1. This section contains the following topics:

• About the Upgrade Wizard
• What the Wizard Upgrades
• Upgrade Wizard Limitations
• Using the Upgrade Wizard

About the Upgrade Wizard

The Upgrade Wizard automatically upgrades most workflows, including business process templates that use Data Integration (DI), Application Integration (AI) and B2B plug-ins. Basically, the wizard takes an exported JAR file from WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 that contains workflows, business operations definitions, event keys, and data integration MFL, XSL, and XML files and transforms them into a business process file (.jpd), control files (.jcx), and extracted DI files. The Upgrade Wizard provides success, warning, error, and failure messages about the upgrade process and records this information to a log file.

The Upgrade Wizard optimizes the upgraded business processes as much as possible. However, upgraded processes may not be as optimal as if they were created in WebLogic Integration 8.1. Additionally, some processes cannot be fully upgraded, especially if they are extremely complex or improperly designed. These processes may require manual upgrading or redesign.

To learn about developing business processes, see the Guide to Building Business Processes in the WebLogic Workshop Help at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/wfguide/wfguideIntro.html

What the Wizard Upgrades

The following list provides an overview of what the Upgrade Wizard upgrades:

• Workflow (business process) definitions, including the following:
• Flow chart, start, task, branch, condition, join/or, and done.
• Process actions, such as assign task, post XML event, set variable, call sub workflow, and call business-operations.
• Process event subscription, such as event start and event resume.
• Data integration MFL, XSL, and XML files used by workflows.

Upgrade Wizard Limitations

As previously mentioned, the Upgrade Wizard cannot upgrade some components of particular workflows. You will need to manually upgrade these parts. The following list contains information on the Upgrade Wizard limitation and references to documents that can help you re-develop these components.

• Running applications—You cannot upgrade a production system.
• Unstructured parallel workflows—WebLogic Integration 8.1 supports only structured parallel business processes (All parallel paths coming out of a node should merge at the same Join node). If your WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 application contains unstructured parallel workflows (cross paths between potential threads and Join nodes as Task nodes), the Upgrade Wizard cannot upgrade these workflows and you will need to re-develop them.
• Workflows That Send Email—After upgrading a workflow that sends email, you must manually edit the SMTP server settings in the annotation for the email control in the upgraded business process. This is required because the SMTP server information is not contained in the original workflow, it is part of the domain configuration. To learn about editing the SMTP server settings, see Configuring an Email Control in the WebLogic Workshop at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/controls/controlsEmailConfig.html

• Run-time exception if output parameter is not initialized—In WebLogic Integration Studio, in the Variable Properties dialog box, if the Output parameter is checked, the callback to the client will include this variable as one of its arguments. However, if you do not initialize this variable, a run-time exception is thrown. Primitive type and String are exceptions to this rule, as they have a default value when declared.
• WebLogic Integration 7.0 SP2 DI plug-in binary event messages—The DI plug-in supports data translations between binary formats and XML using a message format language (MFL) document. The Upgrade Wizard upgrades workflows that can handle only XML based events even though the actual incoming event may consist of binary data. In this case, you need to do one of the following:
• If the receiving WebLogic Integration 8.1 business process can determine the MFL for transforming the binary data after it receives the incoming message, it will translate the data to XML. See Transforming Non-XML Data in the WebLogic Workshop Help at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/dtguide/dtguideNonXML.html

• If the receiving WebLogic Integration 8.1 business process cannot determine the MFL for transforming the incoming binary data, you can use Java or another business process to utilize MFL to convert the message to XML before sending the binary data. See the Guide to Building Business Processes in the WebLogic Workshop Help at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/wfguide/wfguideIntro.html

• Custom business operation classes—For upgrading workflows with business operations, you need to import any custom business operation classes into your upgrade project's HOME_BEA/weblogic81/<upgrade_project>/WEB-INF/classes folder or, for JAR files, the WEB-INF/lib folder, where BEA_HOME represents the WebLogic Platform home directory.
• Workflows using the same Application View service synchronously and asynchronously—You need to manually change the WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 workflow to make the service be used either synchronously or asynchronously before running the Upgrade Wizard.
• Multiple Start Nodes—The Upgrade Wizard cannot separate the different possible threads of workflow execution when multiple start nodes exist. You need to manually upgrade these workflows.
• Workflows node without inbound connection—Normally, the only workflow node that does not have an inbound connection is the Start node. If any other node in a workflow lacks an inbound connection, the workflow cannot be upgraded by the Upgrade Wizard, as shown in the following figure:




 
• Timeouts—During upgrade, timeouts are set to have a count of at least one second; any timeouts that are set to less than a second are reset to one second. If you require less than one second, use the sleep() function after upgrading.
• Session EJB and Entity EJB variables—Although WebLogic Integration 7.0 SP2 workflow variables of type Session EJB and Entity EJB are upgraded to WebLogic Integration 8.1 EJB controls, these variables cannot be passed between business processes in WebLogic Integration 8.1. In WebLogic Integration 7.0 SP2, these variables could be passed between workflows.
• Timed starts—When upgrading a workflow that uses a timed start, the upgraded business process contains a Subscription start node. Subscription start nodes start processes on receipt of a message from a Message Broker channel. Subsequently, you need to configure the channel to have a Timer event generator that publishes to the Subscription start node using the WebLogic Integration Administration Console. See "Event Generators" in Managing WebLogic Integration Solutions at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/manage/evntgen.html

• Transaction boundaries—To allow the transaction of the caller to propagate into subprocesses, the Upgrade Wizard introduces the Client Request with Return construct into any upgraded business process that has a called start. Other than this construct, the Upgrade Wizard does not deliberately set transaction boundaries in upgraded processes. However, transactional boundaries can sometimes be different in an upgraded business process for the following reasons:
• Whenever a parallel construct is found, boundaries change because each branch is its own transaction block.
• Called business processes have a Client Request with Return that gets as close as possible to the quiescent point in the original workflow and still maintains structured logic.
• Upgraded nodes are inherently different because WebLogic Integration 8.1 uses controls and WebLogic Integration 7.0 SP2 BPM uses actions. This incongruence may introduce slight transactional boundary changes.
• Addressed messaging—To enable upgrading of addressed messaging, you must add a comment in the original subscribing workflow's Notes field. To do this, include the word addressedTarget in the Notes field for either the workflow Notes (Right-click the template definition in the workflow tree in WebLogic Integration 7.0 SP2 Studio.) or the Event node (under the properties for the Event node). Enabling addressed messaging at the workflow level is the same as enabling it individually for every event node in the workflow.

Using the Upgrade Wizard

Before using the Upgrade Wizard, you must first export the workflows you created in WebLogic Integration 2.1 SP2 or WebLogic Integration 7.0 SP2 as described in Exporting Package File from WebLogic Integration BPM Studio.

To upgrade your workflows, do the following:

Start WebLogic Workshop and WebLogic Server, as described in How Do I: Start WebLogic Workshop? in the WebLogic Workshop Help at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/howdoI/howStartWorkshop.html

Open the Process Application for your upgrade that you created in Creating an Application For Upgrade.
From the WebLogic Workshop menu, choose Tools—>WebLogic Integration—>Upgrade Processes.

The Upgrade Wizard is displayed.

In Upgrade Wizard - Step1: Select Process:
In the Select a JAR File field, enter the JAR that contains a set of exported workflows from a previous version of WebLogic Integration. Alternatively, click Browse to navigate to the JAR.
In the Select Workflows to Upgrade field, select one or more workflows from the list of workflows.

Note: If multiple workflow template definitions exist, you must choose which template definition you want to upgrade. The Upgrade Wizard allows only a single definition to be used for creating the JPD.

In the Project drop list, select the project for your upgraded workflows. It should be the name of your application with Web appended. For example, UpgradeProcessesWeb. See the following figure.

Figure 5-3 Upgrade Wizard - Step 1: Select Process




 
In the Package Name field, enter the name "processes" (which is the location of the default.jpd).
Click Next.

The Upgrade Wizard - Step2: Upgrade is displayed, as shown in the following figure.

Figure 5-4 Upgrade Wizard - Step 2: Upgrade




 

If you do not want to use the default name for the upgrade log, enter a name in the Log file field.
Click Start Upgrade.

Messages indicating the status of the business process upgrade are displayed in the Upgrade Wizard. These messages indicate which steps in the upgrade process succeed and which steps fail; whether or not the JPD file is generated; the number or errors, warnings, and notices; and the type of errors, warnings, and notices, as shown in the following figure:

Figure 5-5 Upgrade Messages




 

Click Finish.

The Upgrade message field displays the results of the upgrade. The errors, warnings, failures, and notices are also recorded in the upgrade log. To learn more about using these messages, see Viewing the Upgrade Log.

A Design View of the generated business process is displayed and the upgraded workflows (now called business processes) are saved in the directory specified the Package Path field, as shown in the following figure.

Figure 5-6 Original Workflow and Upgraded Workflow




 

Note: Some nodes may not display properly.

To view the source code of the generated business process, select the Source View tab.

Note: Some nodes in business processes generated by the Upgrade Wizard may not display properly in the Design View. However, these parameters are visible in the source view.

Viewing the Upgrade Log

The upgrade log helps you with upgrading workflows. You can use the upgrade log to identify the workflows and parts of workflows that could not be upgraded by the Upgrade Wizard. The messages in the log provide guidance for fixing, redeveloping, and optimizing the upgraded business processes. In general, they provide the following:

• Notices indicate successful upgrade and identifies quiescent nodes.
• Warnings indicate success, but you may need to modify a part of a workflow or otherwise modify it to improve its functionality.
• Errors require minor to moderate fixes to the business process.
• Errors with a failure to produce a JPD file means you must fix the original workflow or redevelop it in WebLogic Integration 8.1.

The following steps will help you use the upgrade log most effectively:

To view the log, select upgrade.log in the Application pane. The log is in the Project/ProjectWeb/processes folder.
Examine the upgrade log and use it to identify the workflows and parts of workflows that could not be upgraded. The log also provides information about the upgraded business process that you can use to improve performance.
Consult the Upgrade Wizard Limitations section of the Upgrade Wizard for information about specific limitations and solutions.
If an entire workflow cannot be upgraded, you need to redevelop that workflow (business process) in WebLogic Integration 8.1.
If a part of a workflow cannot be upgraded, you can add the missing functionality to that workflow (business process) using WebLogic Integration 8.1.

To learn about creating and modifying business processes, see Building Integration Applications in the WebLogic Workshop Help at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/navIntegration.html

Running and Testing Upgraded Business Processes

To learn about running and testing business processes, see Running and Testing Your Business Process at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/wfguide/wfguideTest.html

Upgrading WebLogic Integration 7.0 SP2 Adapters Developed by ADK to WebLogic Integration 8.1 SP2

In WebLogic Integration 7.0 SP2, if you have code in the ADK DesignTimeRequestHandler that gets the ConnectionFactoryDescriptor from the Application View descriptor such as the following:

IconnectionFactoryDescriptor cfd = avd.getConnectionFactoryDescriptor();

This code will not work in WebLogic Integration 8.1 SP2 because connection factories are now part of the adapter instance.

You will need to replace the code to initialize cfd with the following:

IAdapterDescriptor svcAD = null;
IConnectionFactoryDescriptor cfd = null;
 
DesignTimeHelper dthelper = getDesignTimeHelper();
 
//get a reference to the Service Adapter Instance
IApplicationViewDescriptor.IAdapterInstance serviceAdapter =
        avd.getAdapterInstance(avd.getServiceAdapterInstanceName());
 
// Get a reference to the Adapter Descriptor from the AppViewDescriptor
svcAD = dthelper.getAdapterDescriptor(avd,avd.getServiceAdapterInstanceName());
 
if (svcAD != null)
{
//get the ConnectionFactoryDescriptor using the design time helper 
//method getConnectionFactoryDescriptor
    Cfd = dthelper.getConnectionFactoryDescriptor(avd,
                           avd.getServiceConnectionFactoryName(),svcAD);
}

JMS Bridge Interoperability

In some cases, messages may fail to be sent across a JMS bridge between clustered domains. This happens when each of the clustered domains contains different versions of WebLogic Server. For information about working around this problem, see "Upgrading from WebLogic Integration 8.1 to SP2" in the WebLogic Integration 8.1 SP3 Release Notes, which is available in PDF format in a ZIP file. Go to the "Download PDF Documentation for Previous Releases of WebLogic Integration 8.1" page, at http://download.oracle.com/docs/cd/E13214_01/wli/docs85/interm/prevreleases.html, then click "All WebLogic Integration 8.1 SP3 Documents."