6 Configuring and Using Automated Harvesting in Design-time and Runtime Environments

This chapter describes how to get started with Harvester. The tool used to populate Oracle Enterprise Repository is called the Harvester. The Harvester reads metadata from Oracle products and standards-based files. This includes Oracle SOA Suite, Oracle Service Bus, composites generated by Oracle BPA, and standard BPEL, WSDL, XSD, XSLT, BPMN 2.0 and WS-Policy files.

The Harvester automatically creates assets, populates asset metadata, and generates relationship links based on the information in the artifact files. The files can be harvested at design-time, directly from the development environment.

The files can also be harvested as they are deployed to the runtime environment. The Harvester can be used from the command line, within IDEs including Oracle JDeveloper, and within Ant and the Weblogic Scripting Tool (WLST). See Section 10.2, "Configuring the Oracle Registry Repository Exchange Utility," for more information.

This chapter contains the following sections:

• Section 6.1, "Getting Started with Harvester"

• Section 6.2, "Configuring the Harvester"

• Section 6.3, "Harvesting of Artifacts"

6.1 Getting Started with Harvester

This section describes how to get started with Harvester and its use in various high level use cases.

This section contains the following topics:

• Section 6.1.1, "Prerequisites"

• Section 6.1.2, "Harvester Functionality"

• Section 6.1.3, "Artifacts/Products Version Matrix"

6.1.1 Prerequisites

Before using the Harvester, you must perform the following prerequisites:

• Import the Harvester Solution Pack, which includes the required Asset Types and Relationships, into Oracle Enterprise Repository. Import the repositoryxxx/core/tools/solutions/11.1.1.x.x-OER-Harvester-Solution-Pack.zip file from the Oracle Enterprise Repository installation home.

  For more information about importing the Oracle Enterprise Repository solution packs, see Oracle Fusion Middleware Installation Guide for Oracle Enterprise Repository.

  For more information about asset type inventory for the Harvester Solution Pack, see Section B.8, "Asset Type Inventory".

• If you wish to harvest from Oracle Service Bus, install Oracle Service Bus server (version 10.3.1.0) on the same machine as the harvester, or a shared file system accessible to the harvester.

  Note:

  If you wish to harvest any later versions of Oracle Service Bus 11g, then you have to use the corresponding Oracle Service Bus harvester version that is specifically developed for later versions of Oracle Service Bus 11g and is available as part of Oracle Service Bus 11g product installation.

• When harvesting assets from deployed applications such as Oracle SOA Suite or Oracle Service Bus, or Web Services, then the application must be deployed on WebLogic 10.3.1 or higher.

• For complete details about harvesting from Oracle Application Integration Architecture, see "How to Set Up Oracle AIA Content Harvesting" in Oracle Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack.

• Harvester requires Java SDK version 6 or higher.

6.1.2 Harvester Functionality

You can use the Harvester to:

• Publish standard SOA artifacts such as SCA Composites, BPEL, WSDL, XSD, and XSLT, BPMN 2.0 and WS-Policy (from Oracle and other vendors) to Oracle Enterprise Repository.

• Capture dependencies between the artifacts for impact analysis.

• Handle nested WSDL and XSD files.

• Create abstract Interface assets and concrete deployment / Endpoints.

• Capture BPEL partnerlink dependencies and relating them to Interfaces.

• Capture BPEL PM dependencies to Transformations.

• Store or reference artifact content in Oracle Enterprise Repository for reusability.

• Calculate Software File IDs (SFIDs) for artifacts for duplicate detection.

• Publish artifacts from nested directories, remote servers, zip files, jar files, SOA composites, or Oracle BPEL suitcases.

• Publish artifacts in a transactional fashion.

• Publish artifacts from command line, and from automated Ant build process using the Harvester Ant task.

• Publish Oracle Service Bus project artifacts such as Proxy Service, Business Service, XQuery, MFL, XSLT,WS-Policy.

• Integrate the harvesting process as part of WLST deployment scripts.

• Harvest into SSL enabled SOA server. For more information about how to enable SSL on SOA server, and export and import certificates into a client, see Oracle Fusion Middleware Security Guide.

Note:

For more information about importing/exporting certifications, see the Security Guides available at

http://download.oracle.com/docs/cd/E15523_01/index.htm

6.1.3 Artifacts/Products Version Matrix

Table 6-1 describes the version matrix of the artifacts/products that is supported with Harvester.

Table 6-1 Artifacts/Products Version Matrix

Artifact/Product	Version
BPEL	1.1 and 2.0
WSDL	1.1
SCA	0.95
JCA Adapter	1.5
XSD	1.0
XSLT	1.0
Oracle BPEL PM	10.1.3.4
JDeveloper	10.1.3 and 11.1.1
Oracle SOA Suite	10.1.3 and 11.1.1
WS-Policy	1.2
Oracle Service Bus	10.3 and 11.1.1
WebLogic Web Services	10.3
BPMN	2.0

6.2 Configuring the Harvester

This section describes how you can configure Harvester and use it within an integrated development environment.

This section contains the following topics:

• Section 6.2.1, "Obtaining the Harvester"

• Section 6.2.2, "Configuring the Harvester for the Command Line"

• Section 6.2.3, "Using Harvester within an Integrated Development Environment"

• Section 6.2.4, "Invoking the Harvester Using the Repository.Submit Ant Task"

• Section 6.2.5, "Invoking Harvester from WLST"

• Section 6.2.6, "Runtime Harvesting Details"

• Section 6.2.7, "Performing Optional Harvester Configuration"

• Section 6.2.8, "Configuring Logging for the Harvester"

• Section 6.2.9, "Transaction Handling in Harvester"

• Section 6.2.10, "Advanced Configuration"

6.2.1 Obtaining the Harvester

The Harvester is available in 11.1.1.x.x-OER-Harvester.zip, which is bundled with the Oracle Enterprise Repository 11g installation, at the following location:

<ORACLE_HOME>/repositoryXXX/core/tools/solutions/11.1.1.x.x-OER-Harvester.zip

This manual refers to the directory that you extract the 11.1.1.x.x-OER-Harvester.zip file to as the <Harvester Home> directory.

Table 6-2 describes the relationship matrix for the product and the corresponding version.

Table 6-2 Product and Version Matrix for Harvester

Product and Version	Harvest		IDE Search, Browse, and Consume
	Command Line	IDE
11g OSB	OSB 11g	Yes	Yes
10.3.1 OSB	OER 11g	Yes	Add Oracle Enterprise Repository 11g Harvester to Eclipse IDE. For more information, see Oracle Fusion Middleware Integration Guide for Oracle Enterprise Repository
SOA Suite 11g	OER 11g	Yes	Yes
SOA Suite 10g	OER 11g	Yes	No
AIA Foundation Pack 11g	AIA	No	No
Standards based artifacts (WSDL 1.1, XSD, BPEL, XSLT, BPMN 2.0)	OER 11g	Varies	Varies

parameter.properties Used by Harvester Solution Pack

The parameter.properties file determines the behavior of the Harvester Solution Pack during the Import operation into Oracle Enterprise Repository. You must not alter or modify this file in any way. The objects in the Solution pack are imported according to the behaviors mentioned in the list:

• Harvester Solution Pack's /META-INF/parameter.properties

  PreserveUUIDs=true
  Standard.saver.assettype.props.duplicate.handling=Merge
  Standard.saver.assettype.props.duplicate.matching=UUID
  Standard.saver.relationshiptype.props.duplicate.handling=Overwrite
  Standard.saver.metadata.props.duplicate.handling=ignore
  Standard.saver.metadataentrytype.props.duplicate.handling=ignore
  

• Summary of Harvester Solution pack behavior

  • Assets

    Assets, which already exist in Oracle Enterprise Repository, (same UUID) are merged.

    Assets are added with the UUID stated in the import bundle.

  • Asset Types

    Asset Types are considered duplicates if the UUID already exists in Oracle Enterprise Repository.

    If new elements and/or tabs have been added to an asset type in the solution pack, then these elements and tabs are added to the existing asset type in Oracle Enterprise Repository.

    New asset types in the import bundle are added to Oracle Enterprise Repository.

  • Relationship Types

    Relationship Types, which have the same name and direction, are replaced in Oracle Enterprise Repository with the information in the import bundle.

  • Categorization Types

    New categorization entries in Categorization Types, that have the same name as Categorization Types in Oracle Enterprise Repository, are added to that Type using the information in the import bundle.

    New Categorization Types are added to Oracle Enterprise Repository.

  • Acceptable Value Lists (AVLs)

    New values in AVLs that have the same name as AVLs in Oracle Enterprise Repository, are added to that AVL using the information in the import bundle.

    New AVLs are added to Oracle Enterprise Repository.

  • CMF Metadata Entry types

    Duplicate Metadata Entry types (same UUID) are ignored. (The entities that are in the solution pack are ignored.)

    New Metadata Entry Types are added to Oracle Enterprise Repository.

  • CMF Metadata Entries

    Duplicate Metadata Entries (same UUID) are ignored. (The entities that are in the solution pack are ignored.)

    New Metadata Entries are added to Oracle Enterprise Repository.

  For more information about parameter.properties, see "The parameter.properties File" section in the Oracle Fusion Middleware User's Guide for Oracle Enterprise Repository.

6.2.2 Configuring the Harvester for the Command Line

You can configure the Harvester from the command-line. Organizations can easily bootstrap their Enterprise Repository using the Harvester from the command-line. Command-line harvesting allows organizations to harvest:

• individual files

• directories of files

• remote files

• files residing in artifact stores

• files residing on Oracle MetaData Store (MDS)

This section describes the tasks you need to perform to configure the Harvester for the command-line:

• Section 6.2.2.1, "Setting Repository Connection Information for the Command Line"

• Section 6.2.2.2, "Selecting the Artifacts to Harvest for the Command Line"

6.2.2.1 Setting Repository Connection Information for the Command Line

Open the XML file HarvesterSettings.xml located at <Harvester Home> and modify the following XML to point the Harvester to an Oracle Enterprise Repository instance with the correct credentials:

<repository>
  <uri>http://localhost:7101/oer</uri>
  <credentials>
    <user>smith</user>
    <password>*****</password>
     //To ensure security, the password must be encrypted.
     //The password encryption tool (encrypt.bat/encrypt.sh), which is located in
<ORACLE_HOME>/repositoryXXX/core/tools/solutions/11.1.1.x.x-OER-PasswordTools.zip,
allows you to encrypt
     // the passwords that are stored in the Harvester configuration
     // (HarvesterSettings.xml) file.
  </credentials>
  <timeout>30000</timeout>
</repository>

Note:

It is recommended that you run the Harvester as a user with the Basic Access Settings for Assets - View, Edit, Accept, and Register.

Alternatively, the repository connection information can also be passed as parameters to the command line utility as follows:

C:\test\harvester> harvest -url http://localhost:7101/oer -user admin -password <password> -file c:\test\samples

6.2.2.2 Selecting the Artifacts to Harvest for the Command Line

The Harvester can be run from the command line using the harvest.bat utility. Before running harvest.bat or harvest.sh, ensure that the environment variables mentioned in Table 6-3 are set. In Windows, from a command window, you can type "set X" to see the value of the variable X, and "set X=abc" to set the value of X to "abc".

Table 6-3 Command Line Script

Environment Variable	Description
JAVA_HOME	Ensure that the JAVA_HOME environment variable points to an installed java runtime (JRE) or SDK. For Oracle Service Bus introspection, this must be Java version 6 or higher.
BEA_HOME	Ensure that the BEA_HOME environment variable points to the installation directory containing Oracle Service Bus server, only if you plan to harvest projects from Oracle Service Bus. For example, C:\bea.
JAVA_OPTS	Optionally, set your JAVA_OPTS parameter to add any additional java parameters that are necessary. For example, if you need to use an HTTP proxy server, set the value to -Dhttp.proxyHost=www-proxy.yourhost.com -Dhttp.nonProxyHosts= "*.yourhost.com |localhost" See Also: http://java.sun.com/javase/6/docs/technotes/guides/net/proxies.html

Table 6-4 shows the options that can be specified using the Harvester command line utility:

Table 6-4 Command Line Options for the Harvester

Harvester Options	Description
-settings<file>	Specifies the configuration settings XML file.
-mds_settings <file>	Specifies the location of an adf-config.xml file to initialize MDS. If omitted, defaults to the adf-config.xml file that comes with Harvester.
-url <URL>	Specifies the URL of Oracle Enterprise Repository.
-user <OER User Name>	Specifies the user name of the Oracle Enterprise Repository user.
-password <OER Password>	Specifies the password of the Oracle Enterprise Repository user. To ensure security, the password must be encrypted. The Oracle Enterprise Repository Web console has a tool to encrypt passwords: http://<host>:<port>/<domain>/diag/encryptstrings.jsp See Also: For more information about password encryption, see Chapter 5, "Diagnostics and Password Encryption".
-artifact_store	Specifies the name of Oracle Enterprise Repository artifact store to look in. The artifact store must be created beforehand in the Oracle Enterprise Repository Asset Editor. If specified, the -file argument is resolved relative to the artifact store URL. When specifying a URI relative to an Artifact Store, the URI must resolve to a file such as a .wsdl or .zip file. The URIs that point to directories are not supported. For more information about artifact stores, see Section 6.2.4.2, "Specifying Parameters as Nested Elements".
-file <filename or URL>	Specifies the file or directory to be harvested. This can be a filename or URL to the file.
-file_type <type>	Specifies the file type of the file to be harvested. If not specified, then the type is derived from the file extension. This must correspond to one of the filetypes in the config/plugins folder. By default, the following are supported: .bpel, .mfl, .policy, .wsdl, .xsd, .xquery, .xslt.
-remote_url <URL>	Specifies the running server from which to harvest the remote project, instead of from a file.
-remote_username <username>	Specifies the username to connect to the remote server.
-remote_password <password>	Specifies the password to connect to the remote server. To ensure security, the password must be encrypted. The Oracle Enterprise Repository Web console has a tool to encrypt passwords: http://<host>:<port>/<domain>/diag/encryptstrings.jsp
-remote_server_type <type>	Specifies the type of remote server. Remote server could include either of the following: SOASuite, OSB, WLS.
-remote_project <type>	Specifies the name of remote project to harvest, instead of a file. If omitted, all of the projects on the server are harvested. In the case of Oracle SOA Suite, this should be the name of the composite plus revision, for example, MyComposite_rev1. In the case of WLS, this should be the Application Name, as seen in the WebLogic Administration console and Enterprise Manager.
-deployment_status <status>	Specifies the deployment status that is set on the created assets. It takes either design-time or runtime value.
-version	Specifies the print version information.
-soa_partition <type>	Specifies the name of partition for Oracle SOA Suite and by default, it uses the soa "default" partition.
-preview	Specifies if the harvest can be run on a preview mode. If set to true, then runs harvester in preview mode. A detailed information about successes and failures are logged, and no changes are committed to Oracle Enterprise Repository. If set to false or no value is specified, then runs harvester in production mode. A detailed information about successes and failures are logged, and the changes are committed to Oracle Enterprise Repository.
-producing_project <project>	Will apply all assets created from the harvest to this producing project. The project must already exist in OER.
-help	Displays the online help for the Harvester command line utility.

An example of a remote harvest is as follows:

harvest.bat -remote_url mysoasuiteserver:8001 -remote_username weblogic -remote_password ****** -remote_server_type SOASuite -remote_project MyComposite_rev1.0 -soa_partition department1

To ensure security, the password must be encrypted. The Oracle Enterprise Repository Web console has a tool to encrypt passwords:

http://<host>:<port>/<domain>/diag/encryptstrings.jsp

Figure 6-1 shows the command line utility options and online help displayed by the harvest.bat -help command.

Figure 6-1 Harvest Command Line Utility Options

None of the command line options are required. They can be omitted.

If the options are omitted, then the Harvester uses the information in the HarvesterSettings.xml file in the <Harvester Home> directory, where harvest.bat resides. If options are specified on the command line, then these override the settings in HarvesterSettings.xml.

To point to the artifacts to be harvested using the HarvesterSettings.xml file in the <Harvester Home>, modify the following XML:

<query>
  <fileQuery>
     <rootDir>C:\samples</rootDir>
     <files>BPEL</files>
  </fileQuery>
</query>

or

<query>
  <fileQuery>
     <files>http://remote/server/my_generated_wsdl</files>
     <fileType>.wsdl</fileType>
  </fileQuery>
</query>

6.2.3 Using Harvester within an Integrated Development Environment

Harvester can be integrated with integrated development environments (IDEs) such as Oracle JDeveloper, Eclipse, and Visual Studio .NET.

Note:

Oracle Enterprise Repository promotes only services that have endpoints and hosted WSDL to Oracle Service Registry. In addition, only services with concrete WSDL can be consumed through JDeveloper. It is recommended that you harvest from the runtime environment to obtain the endpoints and WSDL location.

For more information about integrating the harvester with the IDEs, see Oracle Fusion Middleware Integration Guide for Oracle Enterprise Repository.

6.2.4 Invoking the Harvester Using the Repository.Submit Ant Task

You can invoke harvester as an Ant Task to ensure that all deployment information is stored in Oracle Enterprise Repository at deployment time. You can use the repository.submit Ant task provided with the Harvester to harvest and import metadata into Oracle Enterprise Repository. This task can be defined in the harvest-tasks.xml file, which is located in the <Harvester Home> directory (the directory into which you unzipped 11.1.1.x.x-OER-Harvester.zip).

This section contains the following topics:

• Section 6.2.4.1, "Specifying Parameters for the repository.submit Ant Task"

• Section 6.2.4.2, "Specifying Parameters as Nested Elements"

• Section 6.2.4.3, "Running the Harvester from Ant"

• Section 6.2.4.4, "Using the Third-Party Tasks"

6.2.4.1 Specifying Parameters for the repository.submit Ant Task

Table 6-5 shows parameters that can be specified for the repository.submit Ant task in the harvest-tasks.xml file:

Table 6-5 Parameters for the repository.submit Ant Task

Attribute	Description	Required
repositoryURL	Repository instance to connect to.	Yes, unless specified by a property.
repositoryUsername	Username to log into Oracle Enterprise Repository.	Yes, unless specified by a property.
repositoryPassword	Password to log into Oracle Enterprise Repository. To ensure security, the password must be encrypted. The Oracle Enterprise Repository Web console has a tool to encrypt passwords: http://<host>:<port>/<domain>/diag/encryptstrings.jsp	Yes, unless specified by a property.
timeout	Number of seconds before calls to Oracle Enterprise Repository will time out.	No. Defaults to 300 (5 minutes).
failOnError	Fails the entire build script if the Oracle Enterprise Repository operation results in an error.	No. Defaults to "true."
errorProperty	Name of the Ant property to set if the repository operation results in an error. This is only useful if failOnError is set to false. If there is an error, the specified property is set to true. Otherwise, the specified property will remain unset.	No.
debug	Display debug information from the Oracle Enterprise Repository task regardless of the Ant -debug setting. Debug information will also be displayed if you pass the -debug parameter to the Ant runtime.	No. Defaults to "true."
description	Harvester Description to associate with each asset created in Oracle Enterprise Repository. This is visible in the Harvester Properties. For more information about harvester properties, see Section B.10, "Harvester Properties".	No.
namespace	Namespace with which to prefix each asset created in Oracle Enterprise Repository.	No.
version	Harvester Version to associate with each asset created in Oracle Enterprise Repository. This is visible in the "Harvester Properties."	No.
beaHome	The BEA_HOME directory of an installed Oracle Service Bus server.	Yes, when harvesting Oracle Service Bus project jars.
settingsFile	Location of settings XML file. Must conform to BPEL_Harvester_Settings.xsd. This file configures what Harvester classes are mapped to which file types, and how entity and relationships are mapped to types in Oracle Enterprise Repository.Optionally, you can specify this attribute or the settingsURL attribute, but not both.	No. Defaults to settings XML that is bundled with the Ant task.
settingsURL	Location of settings XML file. Must conform to BPEL_Harvester_Settings.xsd. This file configures what Harvester classes are mapped to which file types, and how entity and relationships are mapped to types in Oracle Enterprise Repository.Optionally, you can specify this attribute or the settingsFile attribute, but not both.	No. Defaults to settings XML that is bundled with the Ant task.
preview	This option sets the Harvester to Preview mode. The Harvester displays all assets to be created or modified, however, no transaction is committed. To enable, set value to "true".	No. Defaults to false.

6.2.4.2 Specifying Parameters as Nested Elements

FileSet

FileSets are used to select sets of files to harvest. One or more fileSets must be specified.The Harvester examines all the files selected by the fileSet, including files in .zip format (including .zip, .jar., and .ear files, for example).In the Ant repository.submit task shown in Example 6-1, the Harvester examines all the files and directories under the fileSet directory (the /tmp/components directory) and imports them into Oracle Enterprise Repository.

URI

URI identifies a file to introspect. One or more uris can be specified.This can be an "http:" URL that points to a remote file, or a "file:" URL that points to a local file, or any other URL supported by java.This can point to a single file, or a file in zip format that includes zips, jars, ears, etc. This could include exported Oracle Service Bus project jars. Oracle Service Bus projects can be exported from Oracle Service Bus Workshop, using the Export|Oracle Service Bus|Configuration Jar command.The artifactStore attribute is the name of an Oracle Enterprise Repository artifact store to look in. The artifact store must be created beforehand in the Oracle Enterprise Repository Asset Editor. If specified, then the URI is resolved relative to the artifact store URL. When specifying a URI relative to an Artifact Store, the URI must resolve to a file such as a .wsdl or .zip file. The URIs that point to directories are not supported. The fileType attribute indicates the file type of the file to be harvested. If not specified, then the type is derived from the file extension. This must correspond to one of the file types in the config/plugins folder. By default, the following are supported: .bpel, .mfl, .policy, .wsdl, .xsd, .xquery, .xslt.

Example 6-1 Specifying the Files to Harvest with the Ant repository.submit Task

<repository.submit repositoryurl="http://server.example.com:8080/oer"
                   repositoryusername="myuser"
                   registrypassword="*****"
registrationStatus="Registered"
applyRegistrationStatusToExistingAssets="true"
     //To ensure security, the password must be encrypted.
     //The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt
     // the passwords that are stored in the Harvester configuration
     // (HarvesterSettings.xml) file.
                   settingsFile="../MyCustomSettings.xml">
  <fileset dir="/tmp/components/">
    <include name="**/*"/>
  </fileset>
<applyCategorization type="Classification" value="Raw"
applyToExistingAssets="false" />
<applyCategorization type="AssetFunction" value="XML Standards"
applyToExistingAssets="true" />
  <uri filetype=".wsdl">http://remote/server/my_generated_wsdl</uri>
</repository.submit>

Registration Status and Categorizations

You can specify the registration status for assets created from the Harvester. Acceptable values are:

• Unsubmitted

• Submitted - Pending Review

• Submitted - Under Review

• Registered

By default, a registration status is applied to newly created assets. You can also specify the registration status for assets that are created from a previous harvest of the same artifact. To enable, set applyRegistrationStatusToExistingAssets to true, as shown in Example 6-1.

You can apply categorizations to assets created from the harvest. This requires that you know the internal names of the categorization types, which are shown in the Configure Categorizations tab of the Asset Editor . The required value is Element Name.

1. Open the Asset Editor.

2. Select Actions -> Configure Categorizations.

3. Select the Categorization Type and select Edit. The Element Name field displays the value, see Example 6-2.

Figure 6-2 Edit Categorizations

Element Name refers to the field in the Configure Categorizations window in the Asset Editor. Use the value of that field in the HarvesterSettings.xml.

RemoteProject

RemoteProject specifies that the Harvester should read a project from a remote server rather than from a file. The uri attribute indicates the running server from which to harvest the remote project. The username and password attributes indicate login information for the remote server.

The serverType attribute indicates the remote server type, which could be either SOASuite or Oracle Service Bus or WebLogic Server. The projectName element indicates the name of remote project to harvest, instead of a file. If omitted, all of the projects on the server are harvested. In the case of Oracle SOA Suite, this should be the name of the composite plus revision, for example, MyComposite_rev1. In the case of WLS, this should be the Application Name, as seen in the WebLogic Administration console and Enterprise Manager.

Example 6-2 Specifying Parameters as Nested Elements - RemoteProject

<repository.submit repositoryurl="http://server.example.com:8080/oer"
                   repositoryusername="myuser"
                   registrypassword="*****"
     //To ensure security, the password must be encrypted.
     //The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt
     // the passwords that are stored in the Harvester configuration
     // (HarvesterSettings.xml) file.
                   settingsFile="../MyCustomSettings.xml">
  <remoteProjects uri="http://mywlsserver:7001" username="admin" password="*****"
 serverType="SOASuite" soaPartition="${partiton}">
     //To ensure security, the password must be encrypted.
     //The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt
     // the passwords that are stored in the Harvester configuration
     // (HarvesterSettings.xml) file.
     <projectName>MySOAComposite1_rev1.0</projectName>
     <projectName>MySOAComposite3_rev2.0</projectName>
  </remoteProjects>
</repository.submit>

Producing Projects

You can specify multiple projects tagged as producing projects for all assets that are created from the harvest. The projects must already exist in OER.

Within the <repository.submit> element, include:

• <producingProject name="MyProjectName"/>

• <producingProject name="MyOtherProjectName"/>

Producing projects may also be set within the HarvesterSettings.xml file, in the same way.

6.2.4.3 Running the Harvester from Ant

To import the Harvester Ant tasks, include a line, as follows, in your Ant XML:

<taskdef file=${harvester.dir}/harvest-tasks.xml/>

where harvester.dir is the <harvester home> directory to which you unzipped 11.1.1.x.x-OER-Harvester.zip.

When running from the command line, ensure that the Harvester libraries are available to Ant's classpath. Harvester includes a script called runant that sets up the ant classpath correctly. This script must be used to launch ant when using the harvester ant tasks. For example:

runant -f mybuild.xml

(where mybuild.xml is your ant build XML).

Any arguments passed to runant are passed along to ant. Before running harvest.bat or harvest.sh, ensure that the required environment variables are set. Refer to Table 6-6 for the list of environment variables that you need to set.

Table 6-6 Command Line Script

Environment Variable	Description
JAVA_HOME	Ensure that the JAVA_HOME environment variable points to an installed java runtime (JRE) or SDK. For Oracle Service Bus introspection, this must be Java version 6 or higher.
ANT_HOME	Ensure that the ANT_HOME environment variable points to an installation of Apache Ant, version 1.6.2 or higher. For Oracle Service Bus introspection, ensure that the Ant version is 1.6.5 or higher.
BEA_HOME	Ensure that the BEA_HOME environment variable points to the installation directory containing Oracle Service Bus server, if you plan to harvest projects from Oracle Service Bus. For example, C:\bea.
JAVA_OPTS	Optionally, set your JAVA_OPTS parameter to add any additional java parameters that are necessary. For example, if you need to use an HTTP proxy server, set the value to -Dhttp.proxyHost=www-proxy.yourhost.com -Dhttp.nonProxyHosts= "*.yourhost.com |localhost" See Also: http://java.sun.com/javase/6/docs/technotes/guides/net/proxies.html

6.2.4.4 Using the Third-Party Tasks

The runant script uses ant's old launcher: org.apache.tools.ant.Main. The new launcher uses a URIClassLoader interface, which interferes with the usage of custom URIStreamHandlers of the Oracle Service Bus.

The old ant launcher does not support automatic discovery of custom ant tasks in the ant/lib directory. When defining custom tasks with <taskdef>, you must specify a classpath attribute.

For example, the following is an example of how the <taskdef> should NOT be defined:

<taskdef id="ant-contrib" resource="net/sf/antcontrib/antcontrib.properties"/>

The following is an example of how the <taskdef> should be defined:

<taskdef id="ant-contrib" resource="net/sf/antcontrib/antcontrib.properties" classpath="${ant.home}\lib\ant-contrib.jar"/>

6.2.5 Invoking Harvester from WLST

WLST (WebLogic Scripting Tool) is a command-line scripting interface that system administrators can use to manage WebLogic Server instances. WLST supports Oracle Service Bus 10g and SOA Suite 11g. For more information about WLST, see Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.You can invoke harvester from WLST to ensure that all deployment information is stored in Oracle Enterprise Repository at deployment time. Perform the following steps to invoke harvester from WLST:

1. Copy the oer.py file from the harvester installation folder to the <BEA_HOME>\wlserver_10.3\common\wlst\lib directory.

2. In the command window, enter the following commands:

   • Initialize the WLST classpath: run <BEA_HOME>\wlserver_10.3\server\bin\setWLSEnv.cmd

   • Initialize the Harvester classpath: cd to the <harvester> folder and run <harvester>\setenv.bat

   • Invoke WLST: java weblogic.WLST<scriptname>

3. To invoke WLST from ant, perform the following steps:

   • In the command prompt, change to the <harvester> directory by using the cd command.

   • Enter runant.bat -f<antscriptname>, where the ant script invokes the weblogic.WLST java class using ant's <java> task.

   • The <java> task should set fork = true.

   • The <java> task should include the environment's CLASSPATH (runant.bat will set CLASSPATH to include the harvester classes)

   • The <java> task should also include on the classpath any libraries referenced by the WLST script.

   The sample ant script is as follows:

   <property environment="env"/> 
   <target name="harvest"> 
   <java classname="weblogic.WLST" fork="true">
   <arg line="${domain.import.script}"/>
   <arg line="${import.config.file}"/>
   <classpath refid="extra.class.path"/> <!--extra jars used by WLST script, e.g.
    OSB jars-->
   <classpath path="${env.CLASSPATH}"/>
   </java>
   </target>
   

   The oer.harvest() method takes one argument: a dictionary of command line parameters. These are the same parameters that are available from the harvester command line.

   For more information about using the harvester from command line, see Section 6.2.2.2, "Selecting the Artifacts to Harvest for the Command Line".

   A sample usage is as follows:

   argMap = {}
   argMap['-harvester_home'] = '.'
   argMap['-bea_home'] = 'c:/bea'
   argMap['-remote_url'] = 'http://mywlsserver:7001'
   argMap['-remote_username'] = 'admin'
   argMap['-remote_password'] = '*****'
   //To ensure security, the password must be encrypted.
   //The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt
   // the passwords that are stored in the Harvester configuration
   // (HarvesterSettings.xml) file.
   argMap['-remote_server_type] = 'SOASuite'
   argMap['-remote_project] = 'MySOAComposite_rev1.0'
   argMap['-soa_partition'] = 'department1'
   oer.harvest(argMap)
   

   The -harvester_home argument must point to the location of the harvester installation. The -bea_home argument is required for Oracle Service Bus harvesting.

6.2.6 Runtime Harvesting Details

As assets move from development to testing, staging, and production environments, you may want to harvest these assets into Oracle Enterprise Repository, so that Oracle Enterprise Repository has the most up-to-date endpoints. Oracle Enterprise Repository associates new endpoints to the existing assets in Oracle Enterprise Repository. If the WSDL is modified as the asset moves through its lifecycle, the updated WSDL is also associated with the existing asset in Oracle Enterprise Repository.

This section describes the runtime harvesting details for different servers. This section contains the following topics:

• Section 6.2.6.1, "Harvesting from Oracle SOA Suite Server"

• Section 6.2.6.2, "Harvesting Web Services from WebLogic Server"

• Section 6.2.6.3, "Harvesting Web Services from Oracle Service Bus"

6.2.6.1 Harvesting from Oracle SOA Suite Server

You need the following WLS security roles when harvesting from Oracle SOA Suite server:

• Admin

• Operator

• Monitor

The -remote_url parameter should point to the port of the soa-infra managed server. The default value of this in Oracle SOA Suite is 8001.

The soa-infra managed server must be up and running. Harvesting connects to the MDS database as part of the remote harvesting. The MDS database must be running and accessible from the machine where harvesting is taking place.

The SSL/HTTP protocol is supported. Harvester connects to the server MBeans via the t3 protocol.

The harvester automatically saves the value of -remote_url in the Deployment URI property, in the assets harvested from the runtime servers.

An example for harvesting from Oracle SOA Suite server is as follows:

harvest.bat -remote_url mysoasuiteserver:8001 -remote_username weblogic -remote_password <*****> -remote_server_type SOASuite -remote_project MyComposite_rev1.0 -soa_partition default

To ensure security, the password must be encrypted. The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt the passwords that are stored in the Harvester configuration (HarvesterSettings.xml) file. For more information about password encryption, see Chapter 5, "Diagnostics and Password Encryption".

The Oracle SOA Suite server has also implemented partitions to further categorize composites during runtime. This enables you to select the partition to use, along with the composite name, in the harvester. The parameter name in the HarvesterSettings.xml file is called soaPartition. A sample HarvesterSettings.xml file is as shown below:

<remoteQuery>
       <serverType>SOASuite</serverType>
       <projectName>MyComposite_rev1.0</projectName>
       <uri>http://remotehost:8001/</uri>
       <credentials>
         <user>weblogic</user>
         <password>password</password>
       </credentials>
       <soaPartition>partition_name</soaPartition>
</remoteQuery>

Note:

Partitions should be used only with SOA servers of version 11g R1 PS2 or later. You should comment the soaPartition element, if you are using a version earlier to PS2.

By default, the Harvester harvests using the partition_name option set to "default". If it is not specified, then partition "default" comes out-of-the-box by SOA deployments.

Harvesting SOA Suite Composites in a Cluster

The OHS server is deployed as a part of the WebTier label into the Middleware Home and is associated with the domains configured within this Middleware Home, as well.

There is a number of URI's that would normally be assigned to the OHS server's mod_wl_2x.so HTTP server module, some of which can be seen below (taken from the OHS mod_wl_ohs.conf file and modified in order to make it generic for external consumption):

LoadModule weblogic_module

"/opt/Oracle/Middleware/wlserver_10.3/server/plugin/linux/x86_64/mod_wl_22.so"
<IfModule weblogic_module>
    ConnectTimeoutSecs 10
    ConnectRetrySecs 2
    Debug ALL
    WLLogFile /tmp/weblogic.log
    DebugConfigInfo ON
    WLSocketTimeoutSecs 2
    WLIOTimeoutSecs 300
    Idempotent ON
    FileCaching ON
    KeepAliveSecs 20
    KeepAliveEnabled ON
    DynamicServerList ON
    WLProxySSL OFF
</IfModule>

<Location /soa-infra>
    SetHandler weblogic-handler
    WebLogicCluster slc01ese.example.com:23049,wls02.example.com:15980
</Location>
<Location  ~ "/bea_wls_internal/iiop/Client*">
    SetHandler weblogic-handler
    WebLogicCluster wls01.example.com:23049,wls02.example.com:15980
</Location>
<Location  ~ "/bea_wls_internal/HTTPClnt*">
    SetHandler weblogic-handler
    WebLogicCluster wls01.example.com:23049,wls02.example.com:15980
</Location>
<Location /console>
    SetHandler weblogic-handler
    WebLogicHost wls01.example.com
    WebLogicPort 19617
</Location>
<Location /em>
    SetHandler weblogic-handler
    WebLogicHost wls01.example.com
    WebLogicPort 19617
</Location>
<Location /bea_wls_internal>
    SetHandler weblogic-handler
    WebLogicHost wls01.example.com
    WebLogicPort 19617
</Location>
<Location /jndi>
    SetHandler weblogic-handler
    WebLogicHost wls01.example.com
    WebLogicPort 23049
</Location>
<Location /HTTPClnt>
    SetHandler weblogic-handler
    WebLogicHost wls01.example.com
    WebLogicPort 23049
</Location>

These special URI patterns allow for JMS and JMX requests to be routed through the OHS WebLogic module.

Other than any changes that you had applied to code, these are the only customizations that had been applied to the SOA clustered installation.

6.2.6.2 Harvesting Web Services from WebLogic Server

You do not need any WebLogic Server security roles when harvesting from WebLogic Server.

The -remote_url parameter should point to the port of the WLS admin server. The default value of this in Weblogic is 7001. The WLS admin server must be up and running. The SSL/HTTP protocol is supported. Harvester connects to the server MBeans via the t3 protocol.

The harvester automatically saves the value of -remote_url in the Deployment URI property, in the assets harvested from the runtime servers.

6.2.6.3 Harvesting Web Services from Oracle Service Bus

You need the Admin WLS security role when harvesting Web Services from Oracle Service Bus.

The -remote_url parameter should point to the port of the WLS admin server for the Oracle Service Bus domain. The default value of this in Weblogic is 7001. The WLS admin server must be up and running. The SSL/HTTP protocol is supported. Harvester connects to the server MBeans via the t3 protocol.

The harvester automatically saves the value of -remote_url in the Deployment URI property, in the assets harvested from the runtime servers.

An example of harvesting Web Services from Oracle Service Bus is as follows:

harvest.bat -remote_url myosbserver:7001 -remote_username weblogic -remote_password (******) -remote_server_type OSB -remote_project MyOSBProject

To ensure security, the password must be encrypted. The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt the passwords that are stored in the Harvester configuration (HarvesterSettings.xml) file. For more information about password encryption, see Chapter 5, "Diagnostics and Password Encryption".

6.2.7 Performing Optional Harvester Configuration

You can optionally modify these additional configuration settings in the XML file HarvesterSettings.xml in the <Harvester Home> directory:

• <harvesterDescription>: A description about the harvesting performed. This information is stored in the Harvester Properties of the assets created in Oracle Enterprise Repository

• <harvesterVersion>: A version of the harvesting performed. This information is stored in the Harvester Properties of the assets created in Oracle Enterprise Repository.

• <namespace>: A namespace that is added to abstract (non-artifact) Oracle Enterprise Repository assets that are created during harvesting. The namespace is used in duplicate detection. If left empty, then this is set based on information from Oracle SOA Suite and Oracle Service Bus projects when available.That is, generally, the best practice, so override this with caution.

• <workDir>: A temporary directory where the zip and jar files are unzipped. By default, the system temp directory is used.

• <triggerEvent>: The state of the Oracle Enterprise Repository events for use by Workflow. If true, then trigger Oracle Enterprise Repository events for use by Workflow.

For more information about the harvester properties, see Section B.10, "Harvester Properties".

6.2.7.1 Oracle Metadata Service URLs

Harvester supports reading files from Oracle's MDS (Metadata Service). MDS is used in SOA Suite 11g to store shared data such as SOA Suite framework schemas, shared policies, and deployed composites.

Oracle MDS files are referenced through the oramds: URL protocol. Harvester contains the adf-config.xml file, which is used to configure the connection to MDS. This file can point to a local MDS store, as used for framework schemas in JDeveloper. It can also point to a remote MDS store, to access deployed composites, shared policies, and framework schemas. The adf-config.xml file that ships with harvester contains examples of both usages.

For local MDS:, modify the metadata-path property in adf-config.xml and set it to match the location of your JDeveloper installation. For remote MDS:, comment the section marked file store (JDev) and uncomment the section marked "DB store (SOA Suite server)" in adf-config.xml. Also, modify the jdbc-url, jdbc-userid, and jdbc-password properties to point to the MDS database of your Oracle SOA Suite server.

You can also harvest from command line, as mentioned in the example below:

harvest.bat -file oramds:/policies/oracle/wsmtom_policy

Oracle JDeveloper 11g is a browser-based application that allows you to view the contents in MDS. In JDeveloper, click File, New. In the New Gallery dialog, click Connections and then SOA-MDS Connection to view the MDS connections.

Alternatively, harvester can be pointed to a different adf-config.xml file, through the <mdsSettingsFile> element in HarvesterSettings.xml or in the Harvester ant task.

For more information about configuring MDS, see Oracle ADF XML Files in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

6.2.7.2 Classpath URLs

Harvester supports reading files from the java classpath. These files are referenced through the classpath: URL protocol. These files are located inside any jar file or directory in Harvester's classpath. For example, classpath:/META-INF/wsdl/ServiceException.wsdl.

6.2.8 Configuring Logging for the Harvester

The Harvester uses log4j for logging the detailed tasks performed and the log file is placed in the <Harvester Home> directory. The logging options can be changed by updating the log4fl.properties file located in the <Harvester Home> directory.

6.2.9 Transaction Handling in Harvester

By default, the harvester makes all of its changes to Oracle Enterprise Repository in a single transaction. Transactional operations in the harvester function is based on the following rules:

• In 11g R1, the Oracle Enterprise Repository server only supports one transaction at a time. If a transaction cannot be started, then the harvester informs you about it.

• There is a set of timeouts associated with the transactions. These will terminate a harvester operation if the timeouts are exceeded.

  • The setting, cmee.extframework.impexp.monitor.rex.maxidle, specifies the maximum amount of time the transaction is kept alive if it loses connectivity with the client. This allows the transaction to be cancelled if the client-side harvester process is killed.

  • The setting, cmee.extframework.impexp.monitor.maxruntime, specifies the maximum amount of time that the entire transaction will take.

  It is possible that a single operation will exceed the cmee.extframework.impexp.monitor.rex.maxidle (maxidle) setting and cause all subsequent operations to fail. When this occurs, the last error in the log will state that 'An error occurred while attempting to rollback because a transaction has not been started.'. This is because the transaction automatically rolls back when the statement exceeds the maxidle and the transaction is no longer available when the client application attempts a forceful rollback, having detected errors. The result is that no data, from the harvester operation, is added to Oracle Enterprise Repository.

6.2.10 Advanced Configuration

This section contains the advanced configuration options for Harvester:

Adapters and Applications

Harvester contains a configuration file called adapters.xml, that governs which Adapter and Application assets are supported. It has the following structure:

• adapter

  <adapter name="AQ Adapter" 
   jcaSpecBinding="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec"/>
  <adapter name="AQ Adapter"
   jcaSpecBinding="oracle.tip.adapter.aq.outbound.AQEnqueueInteractionSpec"/>
  <adapter name="PeopleSoft Adapter" 
   jcaSpecBinding="com.ibi.afjca.cci.IWAFInteractionSpec"
   jcaCSAdapterName="PeopleSoft"/>
  <adapter name="PeopleSoft Adapter"
   namespace="http://xmlns.oracle.com/Enterprise/"/>
  <adapter name="PeopleSoft Adapter" namespace="http://peoplesoft.com/"/>
  

• adapterAsset

  <adapterAsset name="AQ Adapter">
  </adapterAsset>
  <adapterAsset name="PeopleSoft Adapter" applicationName="PeopleSoft
   Application">
  </adapterAsset>
  

  Each adapterAsset element must correspond to an Adapter asset and/or Application asset that exists in Oracle Enterprise Repository. The Harvester does not create Adapter assets or Application assets. These must be imported via an Oracle Enterprise Repository solution pack or created manually in Oracle Enterprise Repository. The 11.1.1.x.x-OER-Harvester-Solution-Pack.zip contains all of the Adapter and Application assets that are configured in the default adapters.xml file.Each adapter element indicates an Adapter Configuration and/or Application Deployment asset that is created. The name attribute must match the name of a corresponding adapterAsset element. Each adapter element must have either the jcaSpecBinding or namespace attribute present.

• jcaSpecBinding

  The jcaSpecBinding attribute corresponds to the fully-qualified classname of a JCA interactionSpec or activationSpec class, as appears in WSDLs created by Oracle SOA Suite. If jcaSpecBinding is present, then an Adapter Configuration asset is created.

  Note:

  An Application Deployment asset may also be created if the corresponding adapterAsset element has the applicationName attribute present.

• jcaCSAAdapterName

  The jcaCSAAdapterName attribute is optional. It may be specified if the JCA interactionSpec/activationSpec is not enough to distinguish the adapter type. If specified, then it must match the cs.AdapterName attribute in the jca:address section of the WSDL.

• namespace

  The namespace attribute corresponds to the targetNamespace of a WSDL created by Oracle SOA Suite, using the Oracle BSE framework. If namespace is present, then an Adapter Configuration asset will NOT be created, only an Application Deployment gets created.

  If an adapter or application has several possible JCA classes or XML namespaces, then multiple adapter elements can correspond to one adapterAsset. Each adapterAsset element indicates an adapter and/or application asset that is created. The name attribute must match the name of a corresponding adapter element. Only one adapter and/or application asset is created in Oracle Enterprise Repository for each adapterAsset element.

• applicationName

  The applicationName attribute, if present, indicates that an application asset should also be created. Each property element will result in the specified data being set in the Harvester Properties section for the adapter asset created.

For more information about the harvester properties, see Section B.10, "Harvester Properties".

6.3 Harvesting of Artifacts

This section describes how you can configure Harvester and use it within an integrated development environment.

This section contains the following topics:

• Section 6.3.1, "Harvesting Artifacts"

• Section 6.3.2, "Harvesting Oracle Business Process Analysis Projects"

• Section 6.3.3, "Harvesting Oracle Business Process Management 11g Projects"

• Section 6.3.5, "Harvesting Oracle Service Bus 10g Assets"

• Section 6.3.6, "Harvesting a SOA Project from JDeveloper"

• Section 6.3.7, "Harvesting Deployed Composites from JDeveloper"

• Section 6.3.10, "Detecting Duplicate Artifacts"

• Section 6.3.11, "Downloading Harvested Artifacts"

• Section 6.3.12, "Searching Harvested Assets"

• Section 6.3.13, "Previewing of the Created Assets in Harvester"

• Section 6.3.14, "Best Practices"

• Section 6.3.15, "Known Issues"

6.3.1 Harvesting Artifacts

The metadata can be submitted to Oracle Enterprise Repository either from the command line, from Oracle JDeveloper, or using an Ant task.

The Harvester scans for artifacts and harvests those artifacts to detect the dependencies that exist between them. The following sections describe the artifacts:

• Section 6.3.1.1, "BPEL"

• Section 6.3.1.2, "WSDL"

• Section 6.3.1.3, "XSD"

• Section 6.3.1.4, "XSL"

• Section 6.3.1.5, "Harvesting Oracle SOA Suite"

• Section 6.3.1.6, "JCA Adapters"

• Section 6.3.1.7, "Applications via Oracle BSE (WSDL/SOAP)"

• Section 6.3.1.8, "Proxy Service or Business Service"

• Section 6.3.1.9, "Oracle Service Bus (OSB) Project"

• Section 6.3.1.10, "BPMN"

The Harvester creates entities for these artifacts in Oracle Enterprise Repository and creates the relationships between them.

The artifacts created in Oracle Enterprise Repository are stored in the created asset's File Information. The locally stored harvested artifacts store the physical file in Oracle Enterprise Repository whereas for the remotely stored harvested artifacts (http://), Oracle Enterprise Repository points to the URL location of that artifact. Locally stored harvested artifacts, by default, will not be published to OSR by the Exchange Utility. Only remotely stored artifacts will be published.

Figure 6-3 shows the asset types created by the Harvester and the relationships between them and Figure 6-4 describes a sample Asset Model diagram.

Note:

Relationship role names are listed in the order of Primary role, then Secondary role.

In the diagrams which follow, the Primary role is at the tail of each arrow, and the Secondary role is at the head of each arrow.

Figure 6-3 Asset Types Created by the Harvester

Description of "Figure 6-3 Asset Types Created by the Harvester"

6.3.1.1 BPEL

When a BPEL artifact is submitted to Oracle Enterprise Repository, it will result in the following in Oracle Enterprise Repository:

• A Business Process asset (of type: Business Process:BPEL) is directly related to the artifact asset of type Artifact:BPEL.

• A BPEL artifact asset (of type Artifact:BPEL) is created that contains the BPEL artifact contents.

• The Business Process is related to a BPEL artifact asset using the "Defined by" relationship.

• For every partner link in the BPEL flow, the Business Process will also be related to interface assets (of type Interface).

• The BPEL artifact asset is related to WSDL and XSLT artifact (if a transformation is performed in the flow) assets. These are the WSDL that contain the definitions of the partnerlinks and the entry points for the Business Process.

Figure 6-4 Asset Model

6.3.1.2 WSDL

When a WSDL artifact is submitted to Oracle Enterprise Repository, it will result in the following in Oracle Enterprise Repository:

• If the WSDL contains a Service, a Service asset (of type: "Service") is created.

• An interface asset (of type: "Interfaces") is created for the port type.

• The Service is related to the Interface asset using the "Contains interface" relationship.

• An Endpoint asset is created for the port.

• The Service asset is related to the Endpoint asset using the "Deployed to" relationship.

• WSDL artifact asset (of type "Artifact:WSDL") is created that contains the WSDL artifact contents.

• If the WSDL artifact imports WSDLs and imports / includes XSDs, it is related to those WSDL and XSD artifact assets using the "References" relationship.

6.3.1.3 XSD

When a XSD artifact is submitted to Oracle Enterprise Repository, it will result in the following in Oracle Enterprise Repository:

• XSD artifact asset (of type "Artifact:XSD") is created that contains the XSD artifact contents.

• If the XSD artifact imports / includes XSDs, it is related to those XSD artifact assets using the "References" relationship.

6.3.1.4 XSL

When a XSL artifact is submitted to Oracle Enterprise Repository, it will result in the following in Oracle Enterprise Repository:

• XSL artifact asset (of type "Artifact:XSL") is created that contains the XSL artifact contents.

• If the XSL artifact references XSDs and WSDLs as source and target for the transformation, it is related to those XSD and WSDL artifact assets using the "References" relationship.

6.3.1.5 Harvesting Oracle SOA Suite

The section describes harvesting an Oracle SOA Suite 11g project.

• Composite: When an Oracle SOA Suite 11g project folder or its composite.xml file is introspected, it results in the following actions in Oracle Enterprise Repository:

  • Composite asset is created.

  • Any services exposed by the composite results in Composite Service assets in Oracle Enterprise Repository. These are related to the Composite by the Sync-ExposesService relationship.

  • Any references exposed by the composite results in Composite Reference assets in Oracle Enterprise Repository. These are related to the Composite by the Sync-ExposesReference relationship.

  • The composite.xml file becomes an asset of the Artifact: Composite type and relates to the Composite by the Sync-Defines relationship.

• Composite Deployment: When an Oracle SOA Suite 11g project folder or its composite.xml file is introspected, it results in the following actions in Oracle Enterprise Repository:

  • Composite Deployment asset is created.

  • Any services exposed by the composite deployment results in Composite Deployment Service assets in Oracle Enterprise Repository. These are related to the Composite Deployment by the Sync-ExposesService relationship.

  • Any references exposed by the composite will result in Composite Deployment Reference assets in Oracle Enterprise Repository. These are related to the Composite Deployment by the Sync-ExposesReference relationship.

  • The Composite Deployment are related to the Composite by the Deployment-Deploys relationship.

• Component-level Artifacts: The following components of the composite should be created and linked to the Composite by the Sync-Contains relationship:

  • Any BPEL process results in a Business Process:BPEL artifact.

    • It relates to an Artifact:BPEL artifact by the Sync-Defines relationship. This relates to any dependent artifacts, as described in Section 6.3.1.1, "BPEL".

  • Any Mediator should result in a Service asset, with the Service Type attribute set to MEDIATOR.

    • It relates to an Artifact:MPlan artifact by the Sync-Defines relationship. This relates to any dependent Artifact:XSLT artifacts by the Artifact-References relationship.

    
    

  • Any Human Task should result in a Human Task asset.

    • It relates to an Artifact:Task artifact by the Sync-Defines relationship. This relates to any dependent Artifact:XSD artifacts by the Artifact-References relationship.

      
      

  • Any Business Rule should result in a Business Rule asset.

    • It relates to an Artifact:Decs artifact by the Sync-Defines relationship. This relates to any dependent Artifact:Rules artifacts by the Artifact-References relationship. The Artifact:Rules artifacts are related to any dependent Artifact:XSD artifacts by the Artifact-References relationship.

      
      

  • Any Spring Context component should result in a Spring Context asset.

    • It is related to an Artifact:SpringBeans artifact by the Sync-Defines relationship. This is related to other Artifact:SpringBeans artifacts by the "Artifact-References" relationship.

      
      

• Component-level Relationships:

  • Any component services offered by a component results in an Interface asset. This is related to the component-level asset by the BPEL-Entry point relationship (except for Mediators, in which case it is related by the Service-Interface relationship).

    • In the case of <interface.ws> in the composite.xml, the Service is related to an Interface asset. In the case of <interface.java> in the composite.xml, the Service is related to an Interface with attribute Interface Type = Java.

    • If the component service is promoted to the composite level, the Service asset is related to the corresponding Composite Service asset by the Composite-Promotes relationship.

    • If the composite.xml defining that the component service uses the Web Service or WSIF binding, an Endpoint: Web Service asset is created. This will have the Binding Type attribute set to Web Service or WSIF. If the service is promoted, this is related to the Composite Deployment Service asset by the Composite-Promotes relationship.

    • If the composite.xml defining that the component service uses the EJB, or ADF binding, an Endpoint asset is created. This will have the Binding Type attribute set to ADF Service or EJB Service. If the service is promoted, this is related to the Composite Deployment Service asset by the Composite-Promotes relationship.

    • If the component service uses a JCA or B2B adapter, an Adapter Configuration asset is created. For JCA adapters, this is related to the corresponding Artifact: JCA asset. This is related to the corresponding Adapter asset. If the service is promoted, the Adapter Configuration is related to the Composite Deployment Service asset by the Composite-Promotes relationship.

  • Any non-promoted component references used by a component will result in an Interface asset. Any component reference will not have a new Service created for it. However, if the corresponding Service assets already exist in Oracle Enterprise Repository or in the current introspection, they are related to the Component Reference. This rule prevents duplicate Service assets from being created in the namespace of both the referring project and the project that exposes it. This is related to the component-level asset by the Partner-Link point relationship (except for Mediators, in which case it is related by the Service-Fronts relationship).

    • For a promoted component reference, if a corresponding Service asset is found in OER, the Service asset is related to the corresponding Composite Reference asset by the Composite-Promotes relationship.

    • For a deployed promoted component reference using the Web Service or WSIF binding, if a corresponding Endpoint: Web Service is found in OER, this is related to the Composite Deployment Reference asset by the Composite-Promotes relationship.

    • For a deployed promoted component reference using the ADF or EJB Binding, if a corresponding Endpoint is found in OER, this is related to the Composite Deployment Reference asset by the Composite-Promotes relationship.

    • For a deployed promoted component reference using the JCA or B2B adapter, if a corresponding Adapter Configuration asset is found in OER, this is related to the Composite Deployment Service asset by the Composite-Promotes relationship.

6.3.1.6 JCA Adapters

When a WSDL is harvested from Oracle SOA Suite or Oracle Service Bus, which uses JCA Adapter extensions, it will result in the following actions in Oracle Enterprise Repository:

• Harvester attempts to locate an Adapter asset in Oracle Enterprise Repository, as configured in the Harvester's adapters.xml file.

• An Adapter Configuration asset is created that contains the binding and connectivity information used by a specific service.

  • It is related to the Adapter asset.

  • It is related to the Service asset that is using the adapter configuration.

• Harvester attempts to locate an Application asset in Oracle Enterprise Repository, as configured in the Harvester's adapters.xml file.

  • Application assets are supported, by default, for all the following adapters:

    • Oracle Applications (a.k.a. E-Business Suite)

    • PeopleSoft

    • Siebel

    • SAP

    • JDE One World

• If the Service has an Endpoint, then an Application Deployment asset is created.

  • It is related to the Application asset.

  • It is related to the Endpoint asset.

  
  

6.3.1.7 Applications via Oracle BSE (WSDL/SOAP)

When a BPEL process or application is harvested that uses BSE (Business Service Engine) to connect to an external application, it results in the following actions in Oracle Enterprise Repository:

• Harvester attempts to locate an Application asset in Oracle Enterprise Repository, as configured in the Harvester's adapters.xml file.

• If the Service has an Endpoint, then an Application Deployment asset is created.

  • It is related to the Application asset.

  • It is related to the Endpoint asset.

    
    

6.3.1.8 Proxy Service or Business Service

When a Proxy Service or Business Service is submitted to Oracle Enterprise Repository, it will result in the following in Oracle Enterprise Repository:

• A Service asset is created, with Service Type= "Proxy Service" or "Business Service".

• The service is related to the Interface asset using the relationship 'Contains interface'.

• If the Proxy or Business Service is of type Web Service in Oracle Service Bus.

  • An "Interface" asset is created for the port type.

  • An "Endpoint" asset is created for the port.

    • This will have an EndpointURI property visible in the Overview section in the Oracle Enterprise Repository Web UI.

  • The Service asset is related to the "Endpoint" asset using the relationship "Deployed to".

  • A WSDL artifact asset (of type "Artifact: WSDL") is created that contains the WSDL artifact contents.

• If the Proxy or Business Service is not of type Web Service in Oracle Service Bus

  • An Interface asset is created for the port type.

  • An Endpoint asset is created for the port.

    • This will have an EndpointURI property visible in the Harvester Properties section in the Oracle Enterprise Repository Web UI. For more information about harvester properties, see Section B.10, "Harvester Properties".

  • The Service asset is related to the Endpoint asset using the relationship "Deployed to".

  • There is no WSDL associated with this service. So it will not be available to integrate with UDDI using the RR-XU utility. And the WSDL can not be consumed via the Oracle Enterprise Repository Web UI's "Use|Download" feature, or the "Service Consumption Framework" feature in Oracle Eclipse Workshop.

• If the WSDL artifact imports WSDLs and imports / includes XSDs, it is related to those WSDL and XSD artifact assets using the relationship 'References'.

• A Proxy Service is related to Business Services or Proxy Services that it fronts, via the "Fronts" relationship.

• A Business Service is related to external services and flows that it invokes, via the "Invokes" relationship.

• Artifacts that define the interface in Oracle Service Bus (Artifact:WSDL, Artifact:XSD, or Artifact:MFL) is related to the Interface asset via the "Defined by" relationship.

• Artifacts that are used to implement the service in Oracle Service Bus (Artifact:XQuery, Artifact:XSLT, Artifact:MFL, or Artifact:WS-Policy) is related to the Artifact:Proxy or Artifact:Biz asset via the "Artifact-References" relationship.

6.3.1.9 Oracle Service Bus (OSB) Project

An Oracle Service Bus project can be submitted to Oracle Enterprise Repository from the command line. The project must be exported from Oracle Service Bus Workshop, using the command Export|Oracle Service Bus: Configuration jar.

The harvester will handle Proxy Services, Business Services, and Flows. It will also handle artifacts such as BPEL, WSDL, XSD, XSLT, XQuery, WS-Policy and MFL, and harvest the artifacts to detect the dependencies that exist between these artifacts. The harvester will create entities in Oracle Enterprise Repository and create relationships between them.

Note:

When harvesting, use the harvesters that are more appropriate to the content being harvested. For example, when harvesting Oracle Service Bus projects, use the Oracle Service Bus harvester instead of the harvester supplied with the Oracle Enterprise Repository installation. Similarly, for harvesting AIA, use the AIA harvester.

6.3.1.10 BPMN

When you submit a BPMN artifact to Oracle Enterprise Repository, it will result in the following in Oracle Enterprise Repository:

• A Business Process asset (of type Business Process:BPMN) is directly related to the artifact asset of type Artifact: BPMN.

• A BPMN artifact asset (of type Artifact:BPMN) is created that contains the BPMN artifact contents.

• The Business Process is related to a BPMN artifact asset using the "Defined by" relationship.

6.3.2 Harvesting Oracle Business Process Analysis Projects

Oracle Enterprise Repository Harvester 11g supports harvesting of SOA Oracle Business Process Analysis (BPA) Projects if the BPA Projects are converted to SOA composites. The steps to perform are as follows:

Note:

Oracle JDeveloper 11g Release 1 (11.1.1.2.x) does not support importing of BPEL process from BPA server. You need to use 11g Release 1 (11.1.1.7) JDeveloper to import.

Step 1: Convert the BPA Project to SOA Composite

1. Design a BPA process using the BPA Architect.

2. Right-click the designer window, select SOA, and Transform Business Process into BPEL Process. Right-click the designer window, and select SOA, Share Blueprint with IT.

3. Open JDeveloper and create BPA server connection, if it is not already done.

4. Create a new application and then create a new SOA project.

5. In the Configure SOA Settings dialog, select Composite From Oracle BPA Blueprint, and then click Finish.

   For more information about creating a new application and a SOA project, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

6. Expand BPA Server and choose the required BPMN process, as shown in Figure 6-5. Click OK to create SOA project. For more information about BPA Server, see the BPA documentation at http://www.oracle.com/technology/software/products/bpa/index.html.

   Figure 6-5 Create BPA Blueprint Composite Dialog

   
   Description of "Figure 6-5 Create BPA Blueprint Composite Dialog"
   
   

7. Open BPEL Process and fix all compilation errors (if any). Close the Application.

Step 2: Harvest the Converted BPA Project

1. Harvest the Oracle SOA Suite project. For more information, see Section 6.3.14.9, "Harvesting SOA Projects".

2. Open JDeveloper 11g Release 1 (11.1.2). Open the above application and right-click and select Harvest Project option to harvest into Oracle Enterprise Repository.

6.3.3 Harvesting Oracle Business Process Management 11g Projects

Oracle Enterprise Repository Harvester 11g supports harvesting of Oracle Business Process Management (Oracle BPM) projects. As part of the Oracle SOA 11g, Oracle JDeveloper supports the design and development of Oracle BPM projects with the BPMN process. You can develop a project as a composite with the BPMN component, and then harvest the BPM project to Oracle Enterprise Repository. The steps to perform are as follows:

Step 1: Create BPM Project in JDeveloper

To create a BPM project:

1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.

2. Enter a name in the Application field and click Next. The Create Generic Application - Name your project page is displayed.

3. Enter a name for the BPM project in the Project Name field.

4. In the Available list under the Project Technologies tab, double-click BPM to move it to the Selected list, as shown in Figure 6-6.

   Figure 6-6 The Create Generic Application - Name your project Page

   
   

5. Click Finish.

Step 2: Design a BPM Process and Deploy to SOA Server

For more information on how to design a BPM process and deploy to SOA server, see "Creating a BPM Project from a BPA Project" in the Oracle Fusion Middleware Modeling and Implementation Guide for Oracle Business Process Management.

Step 3: Harvest the BPM Project to Oracle Enterprise Repository from JDeveloper and Deploy to Oracle SOA Server

• Open JDeveloper 11g Release 1 (11.1.2).

• Right-click and select Harvest Project option to harvest into Oracle Enterprise Repository.

6.3.4 Harvesting Oracle Service Bus 11g Assets

For more information about Harvesting Oracle Service Bus 11g assets see Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

6.3.5 Harvesting Oracle Service Bus 10g Assets

You can harvest Oracle Service Bus 10g assets into Oracle Enterprise Repository 11g. The following instructions cover Workspace Studio and Oracle Service Bus Eclipse, and work for Oracle Service Bus 10.3 and Oracle Service Bus 10.3.1.

The following steps assume that Oracle Service Bus 10.3.1 is installed in BEA_HOME and Oracle Enterprise Repository harvester is installed in HARVESTER_HOME:

1. Download com.bea.alsb.harvester.connector_1.0.200.zip, the Harvester Plugin, and unzip to the <BEA_HOME>\osb_10.3\eclipse\plugins directory.

2. Download and unzip 11.1.1.x.x-OER-Harvester.zip to the <dir> directory. The HARVESTER_HOME will be <dir>/harvester.

3. Edit <BEA_HOME>\workshop_10.3\workshop.ini. Add the following

   -Dharvester.home=HARVESTER_HOME

• To run from command line, use osb10harvest.sh for Linux and osb10harvest.bat for Windows.

• To run from ant, use osb10runant.sh for Linux and osb10runant.bat for Windows.

To Harvest from Oracle Service Bus Eclipse

1. Launch Oracle Workshop for WebLogic.

2. Import the Oracle Service Bus configuration jar file.

3. Right-click the Oracle Service Bus project, and then click Submit to Oracle Enterprise Repository. The Submit Assets to Oracle Enterprise Repository dialog is displayed.

4. Fill in the connection parameters and then click Submit.

See Section 6.3.1.9, "Oracle Service Bus (OSB) Project"for more information.

6.3.6 Harvesting a SOA Project from JDeveloper

You can harvest a SOA project to Oracle Enterprise Repository from Oracle JDeveloper. To harvest a SOA project, perform the following steps:

1. Open Oracle JDeveloper and create an Oracle Enterprise Repository Connection.

   1. Click the Resource Palette tab.

   2. Click New, New Connection, Oracle Enterprise Repository. The Create Oracle Enterprise Repository Connection dialog is displayed.

   3. Select IDE Connections.

   4. Enter a name for the Oracle Enterprise Repository connection in the Connection Name field.

   5. Enter the repository URL, for example, http://localhost:port/oer.

   6. Enter a valid username/password for the repository connection and click Test Connection. After a successful status is displayed in the Status pane, the Oracle Enterprise Repository connection appears under the IDE Connections tab.

2. In the Application Navigator, right-click the SOA project node and select Harvest Project. The Harvest SOA Project dialog is displayed.

3. Select the repository connection you created in Step 1 in the Repository Connection list.

4. Select Unsubmitted in the Registration Status list.

5. Enter a description for the harvesting in the Harvester Description field.

6. Click OK. This runs an ant script to harvest SOA composite to Oracle Enterprise Repository.

7. Similarly, you can also harvest a XSD or WSDL to Oracle Enterprise Repository. In the Application Navigator, right-click the appropriate node and select Harvest File. This runs an ant script to harvest the schema/wsdl to Oracle Enterprise Repository.

6.3.7 Harvesting Deployed Composites from JDeveloper

You can also harvest a deployed SOA composite to Oracle Enterprise Repository from Oracle JDeveloper. To harvest a deployed SOA composite from Oracle JDeveloper, perform the following steps:

1. Open JDeveloper that contains your deployed SOA composites.

2. Right-click the SOA composite node in the Application Server navigator and select Submit to Enterprise Repository. The Submit to Enterprise Repository dialog is displayed.

3. Enter the following details:

   • Repository Connection: Select the repository connection to which you want to submit the deployed composite.

   • Registration Status: Select the appropriate registration status from the list.

   • Composite Name and Revision: The name of the composite that you want to deploy is displayed in this field.

   • Partition Name: The default value is default.

   • Remote Server URL: Enter the URL of the remote server.

   • Show Debug Information: Select this option if you want to view the debug information.

You can also consume services, schemas, XSLTs, and events from Oracle Enterprise Repository. You must associate a JDeveloper application with Oracle Enterprise Repository project to enable usage tracking.

Note:

If you want to harvest individual assets such as WSDL/XSDs, then use the harvester from command line.

6.3.8 Associate JDeveloper Application with Oracle Enterprise Repository Project

1. Click Application Menu that appears to the right of the application in the Application Navigator.

2. Select Application Properties. The Application Properties dialog is displayed.

3. Click Repository in the left pane. The Repository page is displayed in the right.

4. In the Repository Connection list, select the Oracle Enterprise Repository connection that you want to use for usage tracking.

5. In the Repository Project list, select the Oracle Enterprise Repository project that you want to use for usage tracking.

6. Click OK.

6.3.9 Consume WSDL Services in Oracle Enterprise Repository from Jdeveloper

1. In JDeveloper, open the composite editor.

2. Drag and drop the Web Service component from the Component Palette to External References swim lane. The Create Web Service dialog is displayed.

3. Enter a reference name in the Name field.

4. Click the Find Existing WSDL icon at appears at the extreme right of the WSDL URL field. The SOA Resource Browser dialog is displayed.

5. Select Resource Palette from the list.

6. Click IDE Connections, Oracle Enterprise Repository, <Connection Name>, Asset Types, Service, and then select the service you want to invoke or consume.

   If the service has only one WSDL or UDDI key associated with it, then the same WSDL or UDDI key is used to create the reference. If service has more than one WSDL and/or UDDI key associated with it, then the Choose WSDL dialog is displayed. You need to select one of the URLs/UDDI keys to consume.

   For resolving UDDI keys in JDeveloper, you have to create a UDDI connection prior to creating the reference, without which you cannot select UDDI keys.

   Note:

   Follow the same procedure to browse for schemas (XSDs), events (EDL), transformations (XSLT), except that you will select the respective Artifacts instead of Service.

6.3.10 Detecting Duplicate Artifacts

The Harvester stores information about files such as WSDLs, BPELs, BPMNs, and XSDs as artifacts in Oracle Enterprise Repository. To avoid storing the same artifact file twice, the Harvester will calculate a Software File ID (SFID) for each artifact when it is stored. Before submitting a new artifact, the SFID can be compared against existing SFIDs in the repository to check for duplicates.

The SFID calculated is an MD5 hash. Some level of canonicalization is performed before calculating the SFID. In particular, if the artifact file is XML, it is canonicalized using the Canonicalizer class in the Apache XML Security library. This canonicalizes according to the W3C Canonical XML standard (see www.w3.org/TR/xml-c14n), which includes canonicalizing the text encoding, line breaks, whitespace, comments, and attribute ordering. Some extra canonicalization not specified in the W3C standard is performed, including normalizing of namespace prefixes, normalizing the order of the elements in WSDLs, removing documentation elements, and inlining any included/imported files.

6.3.11 Downloading Harvested Artifacts

The Harvester creates artifact bundles that may be downloaded from the Harvested Assets. The artifact bundles for these assets are stored in zip files. For example, for an Endpoint, a WSDL file and its associated XSD files are stored in relative locations within the zip payload.

When one artifact imports another artifact (for example, a WSDL imports a XSD), it always refers to the child artifact relative to the parent. For example, if MyWSDL.wsdl is located in c:\temp and if the child XSD that is being imported resides in c:\temp\schemas\MyXSD.xsd, the parent MyWSDL.wsdl imports the child using the relative path ./schemas/MyXSD.xsd. When the bundle is downloaded, the child artifact should be created in a folder called schemas relative to the parent so that the parent can resolve the child.

For more information about Using/Downloading Assets, see Oracle Fusion Middleware User's Guide for Oracle Enterprise Repository.

6.3.12 Searching Harvested Assets

You can search for harvested assets using either of the following two methods:

• Section 6.3.12.1, "Using Consumption Method"

• Section 6.3.12.2, "Using Metadata"

6.3.12.1 Using Consumption Method

You can search for harvested services based on a consumption method. In the Basic Search section, when you can select WSDL Ports from the Consumption Method list, as shown in Figure 6-7, the search returns the services that have a WSDL summary, an Endpoint defined in the WSDL, and a scope set to global. This list also can be used under the More Search Options.

Figure 6-7 Assets Pane - Consumption Method

Description of "Figure 6-7 Assets Pane - Consumption Method"

6.3.12.2 Using Metadata

The Harvester tags each asset with properties that can be used for querying.

Figure 6-8 shows how to query for Business Processes that invoke the Write operation. To get the search screen, click More Search Options in the main page of the Oracle Enterprise Repository Web console. In the More Search Options dialog, perform the following:

• Filter by Additional Criteria: Select the option.

• Select a Field: Choose internal.introspector.store from the list.

• Enter an XPath: Type "/" in the text field. A list of available fields is displayed.

Figure 6-8 Viewing the More Search Options Dialog in Oracle Enterprise Repository

Description of "Figure 6-8 Viewing the More Search Options Dialog in Oracle Enterprise Repository"

The following search criteria are available:

• Harvester Description

• Harvester Version

• Harvester Namespace

• Harvested by

• Invoked Operations of Business Processes

6.3.13 Previewing of the Created Assets in Harvester

You can use the Preview feature to view the created assets in harvester. You can use the Preview feature using either of the following methods:

Using Command Line

At the command line or in an ant task, if you add "-preview true", then the Harvester runs and displays a list of all of the assets that would be created, but it does not actually commit the changes.

Using the HarvesterSettings.xml File

You can also set the preview mode in the HarvesterSettings.xml file as follows:

<introspection preview="true">
       <reader>com.oracle.oer.sync.plugin.reader.file.FileReader</reader>
       <writer>com.oracle.oer.sync.plugin.writer.oer.OERWriter</writer>
</introspection>

6.3.14 Best Practices

This section describes best practices for the Harvester. It contains the following topics:

• Section 6.3.14.1, "Recommended Privileges for Harvesting"

• Section 6.3.14.2, "Do Not Override the Namespace Parameter"

• Section 6.3.14.3, "Namespaces in WSDL Files"

• Section 6.3.14.4, "Harvesting Completed Work"

• Section 6.3.14.5, "Harvesting and Maintenance Releases of XSD"

• Section 6.3.14.6, "Harvesting Metadata throughout the Asset Lifecycle"

• Section 6.3.14.7, "Downloading WSDL Artifacts"

• Section 6.3.14.8, "Harvesting Retired Endpoints"

• Section 6.3.14.9, "Harvesting SOA Projects"

• Section 6.3.14.10, "Harvesting from Oracle JDeveloper 11g"

• Section 6.3.14.11, "Harvesting a File in the Harvester Folder"

• Section 6.3.14.12, "Running Harvester and Exchange Utility on the Same Computer"

• Section 6.3.14.13, "Harvesting Composite Service WSDL"

6.3.14.1 Recommended Privileges for Harvesting

Only Registrars or individuals with the authority to view all the assets in Oracle Enterprise Repository should harvest assets. If individuals do not have permission to view all assets in the repository, they may harvest assets that already exist and unintentionally duplicate assets.

6.3.14.2 Do Not Override the Namespace Parameter

Harvester offers you with the ability to set the project namespace for the assets being harvested. The project namespace is used in detecting duplicate assets, as different namespaces will result in different assets. In most cases, you are recommended not to override this parameter.

However, harvester automatically sets the project namespace based on the Oracle SOA Suite or Oracle Service Bus project name when harvesting from those products, which is the recommended behavior.

This is especially important to follow, when you harvest the same project and revision from multiple sources ( JDev and runtime). Changing or overriding the namespace leads to duplicate assets in OER.

6.3.14.3 Namespaces in WSDL Files

In the WSDL files that you harvest, it is recommended that you use a unique namespace for each unique interface, service, and endpoint.

Correlation to existing assets in the Oracle Enterprise Repository is done through QNames, so if you make significant changes to interface, service, or endpoint assets and do not change the QNames, you will overwrite the existing asset with the modified asset.

Table 6-7 shows the correlation of Oracle Enterprise Repository assets with WSDL structure:

Table 6-7 Correlation of Oracle Enterprise Repository Assets with WSDL Structures

Repository Asset	WSDL Structure
Service	/definition/service/@name
Endpoint	/definition/service/port/@name
Interface	/definition/portType/@name

6.3.14.4 Harvesting Completed Work

It is recommended that you harvest only work that is completed or near completion. If you regularly harvest from a development environment, the Oracle Enterprise Repository can become cluttered with outdated versions of assets.

Oracle Enterprise Repository promotes only services that have endpoints and hosted WSDL to Oracle Service Registry. In addition, only services with concrete WSDL can be consumed through JDeveloper. It is recommended that you harvest from the runtime environment to obtain the endpoints and WSDL location.

6.3.14.5 Harvesting and Maintenance Releases of XSD

Some schema development patterns involve the maintenance release of schemas that fix defects or add minor structures but do not change the namespace of the schema. It should be recognized that subsequent harvesting of slightly modified schema artifacts can have the effect of creating a significant number of new artifact assets in the repository. Oracle Enterprise Repository correlates artifact assets based on a hash, or Software File ID (SFID), of the contents of the artifacts. The SFID is calculated over the contents of each artifact after all imports and includes have been inlined. Consequently, a change in an XSD that is imported by a WSDL will result in both a new XSD artifact and a new WSDL artifact.

This is particularly important to keep in mind when considering schemas that are widely used throughout the enterprise. For example, consider a low-level schema such as customer.xsd that is widely imported by other schemas, WSDLs, XSLTs, BPELs. A material change to customer.xsd, and a subsequent re-harvesting of all of an enterprise's artifacts (for example, some kind of regular batch harvesting) would result in a large number of similar artifact assets in the repository that reference customer.xsd either directly or indirectly.

6.3.14.6 Harvesting Metadata throughout the Asset Lifecycle

Harvester can be invoked from several places in the asset lifecycle and each invocation gathers artifacts and metadata from different sources. The following list describes the recommendation on how to use harvester during an asset's lifecycle to keep Oracle Enterprise Repository up to date:

1. Design/Development time

   After implementation, assets should be published to Oracle Enterprise Repository. Any policies associated with the assets will also be published to Oracle Enterprise Repository. The Oracle Enterprise Repository Governance process provides a means of verifying that the implementation aligns with the organization's policies before it is made available for reuse to the general consumer community.

   Recommended approach: Invoke the harvester from the IDE (JDeveloper, Oracle Service Bus Workshop, Eclipse or VS.NET).

2. Deployment time

   Immediately after deployment, assets should be published to Oracle Enterprise Repository. At deployment, the production endpoints are harvested and the asset's metadata is updated with the endpoint information. An organization may have multiple endpoints supporting their development, test, staging, and production environments. Endpoints, when harvested into Oracle Enterprise Repository, may also go through a governance process. For example, development and testing endpoints may be made available to the entire consumer community, but production endpoints may not be provided until a service provider and a service consumer negotiate a service contract.

   Recommended approach: Invoke the harvester from the deployment script (WLST, ant, or command-line).

   Invoke harvester at the end of deployment. Harvest the deployed artifacts from the running server, using the -remote_server argument.

3. Runtime

   Once the project is deployed and running, runtime metrics are harvested and associated with Oracle Enterprise Repository assets. There are several options available for harvesting runtime metrics. One alternative is the EM-Integration, which gathers runtime metrics from Enterprise Manager and updates Oracle Enterprise Repository. For more information, see Oracle Enterprise Manager Connectors Integration Guide.

   Another alternative is to rely upon third-party runtime monitoring tools that publish runtime metrics to UDDI registries. Once in the UDDI Registry, the metrics can be propagated back to Oracle Enterprise Repository using the Oracle Registry Repository Exchange Utility. For more information about Amberpoint integration, see "Chapter 5, Integration with Amberpoint" in Oracle Fusion Middleware Integration Guide for Oracle Enterprise Repository.

6.3.14.7 Downloading WSDL Artifacts

When consuming a WSDL artifact in Oracle Enterprise Repository, you have the ability to download the WSDL file. In many cases, the location of this file is on a remote location. Also, the URL for that file may end in ?wsdl. In these cases, when saving that WSDL, the browser may, by default, give the file the extension as .xml. Then, you should replace.xml with.wsdl. A WSDL file can be hosted on an HTTP/HTTPS or FTP server.

6.3.14.8 Harvesting Retired Endpoints

When endpoint is changed, either retired or moved to another location, then it is recommended to retire endpoint from Oracle Enterprise Repository and remove endpoint for Oracle Service Registry. Then, reharvest the same WSDL service with a new endpoint.

Note:

If you re-run the Exchange Utility publisher, it will not delete retired endpoint from Oracle Service Registry.

6.3.14.9 Harvesting SOA Projects

As a best practise for the SOA life cycle, it is recommended to harvest any SOA projects to Oracle Enterprise Repository, deploy to the SOA server, run the Exchange Utility to publish to Oracle Service Registry, and then consume published assets from Oracle Enterprise Repository or Oracle Service Registry.

6.3.14.10 Harvesting from Oracle JDeveloper 11g

It is not recommended to change namespace when harvesting from Oracle JDeveloper 11g.

Also, it is recommended not to harvest same composite from JDeveloper 11g using two different status, for example, registered and submitted.

6.3.14.11 Harvesting a File in the Harvester Folder

It is recommended not to harvest a file that is located within the unzipped Harvester folder, 11.1.1.x.x-OER-Harvester.zip. Currently, this is not supported.

6.3.14.12 Running Harvester and Exchange Utility on the Same Computer

When publishing a service to Oracle Service Registry, it is recommended that you run Exchange Utility and Harvester on the same computer so they resolve to the same URL. You can also run these on separate computers where the access points in a WSDL are not fully formed, but you must ensure that they resolve to the same URL on both computers. If the access points are resolved to different URL for Harvester and Exchange Utility, then the service fails to publish with error.

6.3.14.13 Harvesting Composite Service WSDL

It is recommended that a WSDL of exposed composite service should never be harvested separately by itself. It is always best to harvest as whole Composite Project to get the complete and correct SOA asset model in Oracle Enterprise Repository.

6.3.15 Known Issues

This section describes the following known Harvester issues:

• Section 6.3.15.1, "Asset Types Must be Present in the System"

• Section 6.3.15.2, "Two Versions of an Asset Type"

• Section 6.3.15.3, "Do Not Delete the Harvester-Specific Metadata Entries in a in a Harvested Asset"

• Section 6.3.15.4, "Supported Remote Server Types"

• Section 6.3.15.5, "Using Incorrect Encrypted Password"

• Section 6.3.15.6, "View in Repository Option"

6.3.15.1 Asset Types Must be Present in the System

As a prerequisite to using Harvester features, the asset types must be present in the system. The necessary asset types are installed with 11.1.1.x.x-OER-Harvester-Solution-Pack.zip.

6.3.15.2 Two Versions of an Asset Type

If some of the existing asset type names in your Oracle Enterprise Repository have the same names as the asset types installed with 11.1.1.x.x-OER-Harvester-Solution-Pack.zip, the asset type names for the Harvester will have a version number appended to them. This does not affect the functioning of the Harvester asset types and harvester refers to these asset types based on its UUID.

6.3.15.3 Do Not Delete the Harvester-Specific Metadata Entries in a in a Harvested Asset

When the Harvester creates assets during the harvesting process, it attaches metadata entries to the asset of metadata entry Type: internal.inspector.store and internal.harvester.manifest.store. Do not modify or delete these metadata entries. Doing so can cause the system to behave unpredictably.

Note that it is not possible to delete these metadata entries using Oracle Enterprise Repository user interface.

6.3.15.4 Supported Remote Server Types

Currently, the Harvester only supports connecting to the remote Oracle SOA Suite, Oracle Service Bus, and WebLogic Server projects that are running on WebLogic 10.x.

6.3.15.5 Using Incorrect Encrypted Password

If you configure the HarvesterSettings.xml file with incorrect encrypted password, then a long stack trace is displayed, which is as follows:

log4j:WARN No appenders could be found for logger
(org.apache.axis.i18n.ProjectResourceBundle).
log4j:WARN Please initialize the log4j system properly.
@ com.oracle.oer.sync.framework.MetadataIntrospectionException:
@ com.oracle.oer.sync.framework.MetadataIntrospectionException: Unable to read
plugin file:
C:\Drive-E\XU-harvest-tools\dec16\OER-Harvester\.\plugins\biz.introspector
        at
@ com.oracle.oer.sync.framework.MetadataManager.init(MetadataManager.java:308)
@         at com.oracle.oer.sync.framework.Introspector.<init>
Introspector.java:188)
        at
@ com.oracle.oer.sync.framework.Introspector.main(Introspector.java:395)
@ Caused by: com.oracle.oer.sync.framework.MetadataIntrospectionException:
Unable
to read plugin file:
C:\Drive-E\XU-harvest-tools\dec16\OER-Harvester\.\plugins\biz.introspector
        at
@ com.oracle.oer.sync.framework.impl.DefaultPluginManager.processIntrospector(De
faultPluginManager.java:127)
        at
@ com.oracle.oer.sync.framework.impl.DefaultPluginManager.<init>(DefaultPluginMa
nager.java:73)
        at
@ com.oracle.oer.sync.framework.MetadataManager.init(MetadataManager.java:306)
        ... 2 more
Caused by: java.lang.IllegalArgumentException: The char '0x12' in
'java.lang.Ill
egalArgumentException: The char '0x12' in 'E/?&#8597;?&#8597;H?rd' is not a
valid XML character.' is not a valid XML character.
        at
@ org.apache.axis.components.encoding.AbstractXMLEncoder.encode(Abstrac
tXMLEncoder.java:110)
        at org.apache.axis.utils.XMLUtils.xmlEncodeString(XMLUtils.java:131)
        at org.apache.axis.AxisFault.dumpToString(AxisFault.java:366)
        at org.apache.axis.AxisFault.printStackTrace(AxisFault.java:796)
        at
com.oer.log4j.spi.ThrowableInformation.getThrowableStrRep(Throw
ableInformation.java:42)
        at
com.oer.log4j.spi.LoggingEvent.getThrowableStrRep(LoggingEvent.java:217)
        at
com.oer.log4j.WriterAppender.subAppend(WriterAppender.java:298)
        at
com.oer.log4j.RollingFileAppender.subAppend(RollingFileAppender.java:294
)
        at com.oer.log4j.WriterAppender.append(WriterAppender.java:157)
        at
com.oer.log4j.AppenderSkeleton.doAppend(AppenderSkeleton.java:251)
        at
com.oer.log4j.helpers.AppenderAttachableImpl.appendLoopOnAppenders(Appen
derAttachableImpl.java:57)
        at com.oer.log4j.Category.callAppenders(Category.java:255)
        at com.oer.log4j.Category.forcedLog(Category.java:445)
        at com.oer.log4j.Category.log(Category.java:882)
        at
@ com.oracle.oer.sync.framework.logger.DefaultMetadataLogger.error(DefaultMetada
taLogger.java:98)
        at
@ com.oracle.oer.sync.plugin.writer.oer.OERConnectionCache.getAuthToken(OERCon
nectionCache.java:138)
        at
@ com.oracle.oer.sync.plugin.writer.oer.OERAssetQueries.getToken(OERAssetQueri
es.java:82)
        at
@ com.oracle.oer.sync.plugin.writer.oer.OERAssetQueries.assetTypeQueryByUUID(AL
ERAssetQueries.java:159)
        at
@ com.oracle.oer.sync.framework.MetadataManager.putAssetType(MetadataManager.jav
a:204)
        at
@ com.oracle.oer.sync.framework.impl.DefaultPluginManager.processIntrospector(De
faultPluginManager.java:104)
        ... 4 more

6.3.15.6 View in Repository Option

From Oracle JDeveloper 11g, when you click the View in Repository option, it opens up the asset details in JDeveloper, which is for read-only purpose and the links within this page will not work.

As a workaround, you need to login to Oracle Enterprise Repository console and click links for further information.