8 Configuring and Using Automated Harvesting

8.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) allows you to encrypt
     // the passwords that are stored in the Harvester configuration
     // (HarvesterSettings.xml) file.
  </credentials>
  <timeout>30000</timeout>
</repository>

8.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 or harvest.sh utilities.

The harvest.bat and harvest.sh utilities can be run from the server to which Oracle Enterprise Repository is installed. If you want to run the harvester from a different client, obtain the 12.1.3.0.0-OER-Harvester.zip file from the <FMW_HOME>/oer/modules/tools/solutions directory and extract the zip to any client that has a valid JAVA_HOME environment variable set, as discussed in Table 8-3.

The osb-harvest.bat and osb-harvest.sh utilities can be run from the server to which Oracle Enterprise Repository is installed. If you want to run the harvester from a different client:

• Install Oracle Service Bus into a <FMW_HOME> directory on the client machine.

• Ensure that the JAVA_HOME environment variable is set on the client machine, as shown in Table 8-3.

• Obtain the 12.1.3.0.0-OSB12c-Harvester.zip file from the <FMW_HOME>/oer/modules/tools/solutions directory on the machine to which Oracle Enterprise Repository is installed. Extract the file to the <FMW_HOME>/oer/tools directory on the target machine. The full path to the harvester after extracting the files should be <FMW_HOME>/oer/tools/osbharvester. The OSB Harvester must be installed into the same FMW_HOME to which OSB 12c is installed.

Before running harvest.bat, harvest.sh, osb-harvest.bat, or osb-harvest.sh, ensure that the environment variables mentioned in Table 8-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 8-4 shows the options that can be specified using the Harvester command line utility:

An example of a remote harvest is as follows:

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

To ensure security, passwords are not passed via the command line and they must be encrypted. The only way to set passwords for Oracle Enterprise Repository and remote servers is by storing them in the Harvester configuration (HarvesterSettings.xml) file. The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt the passwords that are stored in the file. For more information about password encryption, see Chapter 12, "Password Encryption".

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

Figure 8-1 Harvest Command Line Utility Options

Description of ''Figure 8-1 Harvest Command Line Utility Options''

Command line options are required only when harvesting from an Oracle SOA Suite 11g server; the -remote_server_type SOASuite11g option must be included if this is the case. See Section 8.2.5.1, "Harvesting from Oracle SOA Suite Server" for more information.

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>

8.2.3.1 Specifying Parameters for the repository.submit Ant Task

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

8.2.3.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 8-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.

<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 in the HarvesterSettings.xml file. 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 8-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 8-2.

Figure 8-2 Edit Categorizations

Description of ''Figure 8-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.

Registration Status and Categorizations can also be applied at the command line. The command line parameters are -registration_status, -apply_registration_status_to_existing_assets, -categorization_type, and -categorization.

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.

<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.

8.2.3.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 12.1.3.0.0-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 8-6 for the list of environment variables that you need to set.

8.2.3.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"/>

8.2.5.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 12c server is as follows:

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

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

harvest.bat -remote_url mysoasuiteserver:8001 -remote_username weblogic -remote_server_type SOASuite11g -remote_project MyComposite_rev1.0 -soa_partition default

To ensure security, passwords are not passed via the command line and they must be encrypted. The only way to set passwords for Oracle Enterprise Repository and remote servers is by storing them in the Harvester configuration (HarvesterSettings.xml) file. The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt the passwords that are stored in the file. For more information about password encryption, see Chapter 12, "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>

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.

8.2.5.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.

8.2.5.3 Harvesting Web Services from Oracle Service Bus

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

You must use the OSB Harvester to harvest web services from an Oracle Service Bus 12c server. The OSB harvester is installed in the <FMW_HOME>/oer/tools/osbharvester directory.

The OSB Harvester can be run from the command line using the osb-harvest.bat or osb-harvest.sh utilities. See Section 8.2.2, "Configuring the Harvester for the Command Line" for information about configuring the OSB Harvester.

You can use the harvester that ships with Service Bus 11g to harvest non-simple assets from Service Bus 11g servers. The following note describes the process for harvesting simple model API assets (resulting from setting the simple_model property, as described in Table 8-4) from a Service Bus 11g server.

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:

osb-harvest.bat -remote_url myosbserver:7001 -remote_username weblogic -remote_server_type OSB -remote_project MyOSBProject

To ensure security, passwords are not passed via the command line and they must be encrypted. The only way to set passwords for Oracle Enterprise Repository and remote servers is by storing them in the Harvester configuration (HarvesterSettings.xml) file. The password encryption tool (encrypt.bat/encrypt.sh) allows you to encrypt the passwords that are stored in the file. For more information about password encryption, see Chapter 12, "Password Encryption".

8.2.5.4 Harvesting Deployed Services

In addition to harvesting APIs from SOA Suite and Service Bus, you can also harvest deployed services using a URL to a deployed WSDL file. The example below will harvest a Weather service from the internet:

./harvest.sh -file "http://example.com/WeatherWebService/Weather.asmx?WSDL"

This method can be used to harvest secure endpoints from Oracle API Gateway (OAG). To get the WSDL URL from OAG, make sure the OAG Policy Studio publishes its WSDL to clients by checking "Allow the Gateway to publish WSDL to clients" checkbox on the WSDL tab in the Service Handler for the web service.

8.2.6.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.

8.2.6.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.

8.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 8-4 Asset Model

Description of ''Figure 8-4 Asset Model''

8.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.

8.3.1.3 WADL

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

• If the WADL 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.

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

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

8.3.1.4 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.

8.3.1.5 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.

8.3.1.6 Harvesting Oracle SOA Suite

The section describes harvesting an Oracle SOA Suite project.

• Composite: When an Oracle SOA Suite 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 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 8.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.

    
    Description of the illustration ''img_mediator.gif''
    
    

  • 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.

      
      Description of the illustration ''img_hutask.gif''
      
      

  • 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.

      
      Description of the illustration ''img_busrule.gif''
      
      

  • 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.

      
      Description of the illustration ''img_spring.gif''
      
      

• 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.

8.3.1.7 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.

  
  Description of the illustration ''img_adap.gif''
  
  

8.3.1.8 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.

    
    Description of the illustration ''img_soap.gif''
    
    

8.3.1.9 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 A.7, "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.

8.3.1.10 Oracle Service Bus (OSB) Project

An Oracle Service Bus project can be submitted to Oracle Enterprise Repository from the command line. See Section 8.2.5.3, "Harvesting Web Services from Oracle Service Bus" for information about harvesting from OSB.

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.

8.3.1.11 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.

8.3.4.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 8-5, 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 8-5 Assets Pane - Consumption Method

Description of ''Figure 8-5 Assets Pane - Consumption Method''

8.3.4.2 Using Metadata

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

Figure 8-6 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 8-6 Viewing the More Search Options Dialog in Oracle Enterprise Repository

Description of ''Figure 8-6 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

8.3.6.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.

8.3.6.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. Changing or overriding the namespace leads to duplicate assets in OER.

8.3.6.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 8-7 shows the correlation of Oracle Enterprise Repository assets with WSDL structure:

8.3.6.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.

8.3.6.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.

8.3.6.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. 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.

2. 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.

8.3.6.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.

8.3.6.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.

8.3.6.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.

8.3.6.10 Harvesting a File in the Harvester Folder

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

8.3.6.11 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.

8.3.6.12 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.

8.3.6.13 Understanding Versioning of Assets

When defining a harvesting strategy, it is important to understand that different harvesters yield different results, for example:

• Using OER harvester on a running SOA infra or SOA composite (MDS), gets complete composite and relationships

• Using OSB harvester on OSB gets relationships between proxy and back end business services

When harvesting a service multiple times, OER will attempt to determine is the service is the same as the last time it was harvested. In Oracle Enterprise Repository 12c, two entities are determined to be the same in the following ways:

• Composites are determined to be the same they have the same name/version pair (may add new relationships, deployments, etc for same composite).

• Services are determined to be the same if they share the same QName, as identified in WSDL that is introspected (version number specified in the WSDL has no effect).

• WSDLs, XSDs, composite.xml files, and other file types are considered the same artifact if they have the same SFID ”fingerprint” (SFID is calculated on cannonicalized artifact).

If OER finds a match in harvesting, it assumes that it already has the entity (and it may overwrite description, and add relationships to other entities to preserve the latest). If OER does not find a match, it assumes that the entity is a distinct, new entity (If artifacts have same name, but different content, it may append "-1" to make new asset name unique).

If your objective is to "refresh" the same asset, for example, for minor bug fixes or enhancements, it is recommended that you:

• Keep the endpoint address the same or add PortType for new interface on same service

• Keep the QName of the service the same in the WSDL

• Keep the Name/Version pair for composites the same (and do not issue a new composite revision in SOA Suite)

If your objective is to "version" an asset by issuing a new asset with a new version number, it is recommended that you:

• Optionally add PortType for new interface on same service.

• Optionally create previous/next relationship.

• Optionally enable notification on previous/next relationship.

• Run side-by-side until consumers have migrated; then inactivate and retire the old asset.

The recommended best practice is to do a mixture of both refreshing and versioning, depending on the expectations you set with your asset consumers.

8.3.7.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 12.1.3.0.0-OER-Harvester-Solution-Pack.zip.

8.3.7.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 12.1.3.0.0-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.

8.3.7.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.

8.3.7.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 11g or 12c.

8.3.7.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

8.3.7.6 View in Repository Option

From Oracle JDeveloper , 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 may not work.

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