21 Extending the Domain with Oracle Real-Time Integration Business Insight

You can extend your domain to include Oracle Real-Time Integration Business Insight, an application designed for business users. The application enables users to model, collect, and monitor business-level metrics by using web-based dashboards, and reports.

This chapter includes the following sections:

• Variables Used When Configuring Business Insight
  As you perform the tasks in this chapter, refer to the directory variables that are listed in this section.
• Prerequisites for Adding Oracle Insight to the Domain
  Before you add Oracle Insight to your existing Oracle SOA Suite domain, you must ensure that the prerequisites are met.
• Roadmap for Adding Oracle Insight to the Domain
  Before you extend an SOA domain for Oracle Real-Time Integration Business Insight, familiarize yourself with the high-level steps that you must perform to extend the domain.
• Extending the SOA Domain to Include Oracle Real-Time Integration Business Insight
  This section provides instructions for extending the existing enterprise deployment SOA domain with the Oracle Real-Time Integration Business Insight.
• Propagating the Extended Domain to the Domain Directories and Machines
  After you have extended the domain with the Insight components, and you have restarted the Administration Server on SOAHOST1, you must then propagate the domain changes to the domain directories and machines.
• Starting and Validating Managed Servers after Adding Insight
  After you extend the domain with Insight, you must restart the servers, add the InsightAdmin Role to the administrators group, and then validate the access to Insight and the BAM URLs.
• Configuring the Web Tier for the Extended Domain
  Configure the web server instances on the web tier so that the instances route requests for both public and internal URLs to the proper clusters in the extended domain.
• Validating the Access to Oracle Insight Through the Hardware Load Balancer
  Verify that Oracle Insight URLs are successfully routing requests from the hardware load balancer to the Oracle HTTP Server instances to the Oracle Insight software in the middle tier.
• Adjusting JTA Values for Insight Models
  
• Backing Up the Configuration
  As a best practice, Oracle recommends you to create a backup after you successfully extended a domain or at another logical point. Create a backup after you verify that the installation done until the point at which you decide to create the backup is successful. A quick backup is used for the express purpose of immediate restoration if problems are encountered in later steps.

Variables Used When Configuring Business Insight

As you perform the tasks in this chapter, refer to the directory variables that are listed in this section.

The values for several directory variables are defined in File System and Directory Variables Used in This Guide.

• ORACLE_HOME

• ASERVER_HOME

• MSERVER_HOME

• WEB_DOMAIN_HOME

In addition, refer to the virtual IP (VIP) addresses that are defined in Physical and Virtual IP Addresses Required by the Enterprise Topology:

• ADMINVHN

The actions that are described in this chapter are performed on the following host computers:

• SOAHOST1

• SOAHOST2

• WEBHOST1

• WEBHOST2

• BAMHOST1

• BAMHOST2

Prerequisites for Adding Oracle Insight to the Domain

Before you add Oracle Insight to your existing Oracle SOA Suite domain, you must ensure that the prerequisites are met.

• About Installation Requirements for Adding Oracle Insight to the Domain
  
• About Database Schema Requirements for Oracle Insight
  
• Backing Up the Existing Installation
  

About Installation Requirements for Adding Oracle Insight to the Domain

This chapter assumes that you are configuring Oracle Real-Time Integration Business Insight in a domain that is already running Oracle SOA Suite (SOA, OSB, BPM, and BAM), as shown in Figure 3-2.

In the default Oracle SOA Suite and Oracle Real-Time Integration Business Insight topology, you target Oracle Insight to BAM Managed Servers. Insights agents are also deployed in SOA and OSB servers to collect business metrics. See Configuring the Oracle Real-Time Integration Business Insight Domain in Installing and Configuring Oracle SOA Suite and Business Process Management. It is assumed that Service Migration, JDBC stores, WebLogic Proxy Plugin, SOA servers, and the other recommended configuration best practices have been applied to the existing BAM servers.

See the following sections:

• Configuring Automatic Service Migration for Static Clusters.

• Using JDBC Persistent Stores for TLOGs and JMS in an Enterprise Deployment

• Configuring the WebLogic Proxy Plug-In

In the default topology, there is no need to install Oracle Insight because Oracle Insight is included in the Oracle SOA Suite and Oracle Business Process Management distribution. Oracle Insight is installed in the Oracle home directories when you install Oracle SOA Suite as illustrated in Understanding the SOA Enterprise Deployment Topology.

About Database Schema Requirements for Oracle Insight

The schemas required for Oracle Insight are created in the database when you run the Repository Creation Utility (RCU) to create the required Oracle BAM and SOA schemas. As a result, there is no need to run RCU specifically for Oracle Insight.

Backing Up the Existing Installation

If you have not yet backed up the existing Fusion Middleware Home and domain, back it up now.

To back up the existing Fusion Middleware Home and domain, see Performing Backups and Recoveries for an Enterprise Deployment.

Roadmap for Adding Oracle Insight to the Domain

Before you extend an SOA domain for Oracle Real-Time Integration Business Insight, familiarize yourself with the high-level steps that you must perform to extend the domain.

Step	Description	More Information
Run the Configuration Wizard to Extend the Domain in the Administration Server domain home	Extend the SOA domain to contain Oracle Insight components.	Extending the SOA Domain to Include Oracle Real-Time Integration Business Insight
Propagate the Domain Configuration to the Managed Server domain directories	Oracle Insight requires some updates to the WebLogic Server start scripts. Propagate these changes by using the pack and unpack commands.	Propagating the Extended Domain to the Domain Directories and Machines
Add the SOA Administrator role to the Oracle Insight Administration Group	This step allows you to use one set of credentials to access the various product-specific management utilities.	Adding the Enterprise Deployment Administration User to the Oracle Insight Administration Group
Start the involved Servers	Oracle Insight servers extend an existing domain. As a result, the Administration Server and the respective Node Managers are already running in SOAHOST1 and SOAHOST2.	Starting the Managed Servers
Validate the WLS_BAM Managed Servers	Verify that the server status is reported as Running in the Admin Console and access URLs to verify status of servers.	Validating the Managed Servers After Adding Insight
Update the Oracle HTTP Server for the WLS_BAM Managed Servers	To enable Oracle HTTP Server to route to Oracle Insight, add the required directives to the Oracle HTTP Server configuration files, and then set the WebLogicCluster parameter to the list of nodes in the cluster.	Configuring Oracle HTTP Server for the WLS_BAM Managed Servers
Configure the WebLogic Server Proxy Plugin	Enable the WebLogic Server Proxy Plugin for Oracle Insight	Configuring the WebLogic Proxy Plug-In
Validate the Access Through Oracle HTTP Server	Verify that the server status is reported as Running.	Validating the Access to Oracle Insight Through the Hardware Load Balancer

Extending the SOA Domain to Include Oracle Real-Time Integration Business Insight

This section provides instructions for extending the existing enterprise deployment SOA domain with the Oracle Real-Time Integration Business Insight.

Extending the domain involves the following tasks:

• Starting the Configuration Wizard
  
• Navigating the Configuration Wizard Screens for Oracle Insight
  

Starting the Configuration Wizard

Note:

If you have added any customizations directly to the start scripts in the domain, those customizations are overwritten by the configuration wizard. To customize server startup parameters that apply to all servers in a domain, create a file called setUserOverridesLate.sh and configure it. For example, add custom libraries to the WebLogic Server classpath, specify additional JAVA command-line options for running the servers, or specify additional environment variables. Any customizations you add to this file are preserved during domain upgrade operations, and are carried over to the remote servers when you use the Pack and Unpack commands.

To begin domain configuration:

1. From the WebLogic Server Console, stop any managed servers that will be modified by this domain extension. Managed Servers that are not effected can remain on-line.

   Note:

   This specific domain extension for Oracle Insight component modifies the WLS_BAMn, WLS_SOAn, and WLS_OSBn managed servers. Ensure that you shut down these servers.

2. Shut down the Administration Server to prevent any configuration locks, saves, or activations from occurring during the configuration of the domain.
3. Navigate to the following directory and start the WebLogic Server Configuration Wizard.

   ORACLE_HOME/oracle_common/common/bin 
   ./config.sh 

Navigating the Configuration Wizard Screens for Oracle Insight

In this step, you extend the domain created in Extending the Domain with Business Activity Monitoring to contain Oracle Real-Time Integration Business Insight components.

Domain creation and configuration include the following tasks:

• Task 1, "Selecting the Domain Type and Domain Home Location"

• Task 2, "Selecting the Configuration Template"

• Task 3, "Providing the GridLink Oracle RAC Database Connection Details"

• Task 4, "Testing the JDBC Connections"

• Task 5, "Selecting Advanced Configuration"

• Task 6, "Reviewing Your Configuration Specifications and Configuring the Domain"

• Task 7, "Writing Down Your Domain Home and Administration Server URL"

• Task 8, "Starting the Administration Server"

Task 1   Selecting the Domain Type and Domain Home Location

On the Configuration Type screen, select Update an existing domain.

In the Domain Location field, select the value of the ASERVER_HOME variable, which represents the complete path to the Administration Server domain home that you have created in Creating the Initial Infrastructure Domain for an Enterprise Deployment.

For more information about the directory location variables, see File System and Directory Variables Used in This Guide.

Tip:

For more information about the other options on this screen, see Configuration Type in Creating WebLogic Domains Using the Configuration Wizard.

Task 2   Selecting the Configuration Template

On the Templates screen, make sure that Update Domain Using Product Templates is selected, then select the following templates:

• Insight SOA Agent - 12.2.1.3.0 [soa]

• Insight Service Bus Agent - 12.2.1.3.0 [osb]

• Insight - 12.2.1.3.0 [soa]

Click Next.

Task 3   Providing the GridLink Oracle RAC Database Connection Details

All fields are pre-populated, because you already configured the domain to reference the Fusion Middleware schemas that are required for the domain. Insight uses the existing Datasources for SOA and no new Datasources need to be added to the domain.

Note:

Any custom datasources that were created before the extension (like LEASING datasources) will show up before this screen. Check the Datasources row and click Next. The test datasource screen will verify its validity. Click Next.

Task 4   Testing the JDBC Connections

On the Test JDBC Data Sources screen, confirm that all connections were successful.

The connections are tested automatically. The Status column displays the results. If all connections are not successful, click Previous to return to the previous screen and correct your entries.

Click Next when all the connections are successful.

Task 5   Selecting Advanced Configuration

Click Next to continue.

Task 6   Reviewing Your Configuration Specifications and Configuring the Domain

The Configuration Summary screen contains the detailed configuration information for the domain you are about to extend. Review the details of each item on the screen and verify that the information is correct.

If you need to make any changes, you can go back to any previous screen either by using the Back button or by selecting the screen in the navigation pane.

Click Update to execute the domain extension.

In the Configuration Progress screen, click Next when it finishes.

Tip:

More information about the options on this screen can be found in Configuration Summary in Creating WebLogic Domains Using the Configuration Wizard.

Task 7   Writing Down Your Domain Home and Administration Server URL

The Configuration Success screen will show the following items about the domain you just configured:

• Domain Location

• Administration Server URL

You must make a note of both items as you will need them later; the domain location is needed to access the scripts used to start the Administration Server, and the URL is needed to access the Administration Server.

Click Finish to dismiss the configuration wizard.

Task 8   Starting the Administration Server

Start the Administration Server to ensure the changes you have made to the domain have been applied.

Propagating the Extended Domain to the Domain Directories and Machines

After you have extended the domain with the Insight components, and you have restarted the Administration Server on SOAHOST1, you must then propagate the domain changes to the domain directories and machines.

The following table summarizes the steps required to propagate the changes to all the domain directories and machines.

Task	Description	More Information
Pack up the Extended Domain on SOAHOST1	Use the pack command to create a new template jar file that contains the new BAM Servers configuration. When you pack up the domain, create a template jar file called insightdomaintemplateExtBAM.jar.	Packing Up the Extended Domain on SOAHOST1
Unpack the Domain in the Managed Servers Directory on SOAHOST1*	Unpack the template jar file in the Managed Servers directory on SOAHOST1 local storage.	Unpacking the Domain in the Managed Servers Domain Directory on SOAHOST1
Unpack the Domain on SOAHOST2	Unpack the template jar file in the Managed Servers directory on the SOAHOST2 local storage.	Unpacking the Domain on SOAHOST2

*If you are configuring Oracle BAM on separate hosts, then you would unpack the domain on all nodes: BAMHOST1, BAMHOST2, SOAHOST1, and SOAHOST2.

Starting and Validating Managed Servers after Adding Insight

After you extend the domain with Insight, you must restart the servers, add the InsightAdmin Role to the administrators group, and then validate the access to Insight and the BAM URLs.

• Starting the Managed Servers
  After extending the domain, restarting the Administration Server, and propagating the domain to the other hosts, start the configured SOA, OSB, and BAM servers.
• Adding the InsightAdmin Role to the Administrators Group
  When the startup operation is complete and before you validate the Oracle Insight configuration on the Managed Server, add the InsightAdmin administration role to the enterprise deployment administration group (SOA Administrators).
• Validating the Managed Servers After Adding Insight
  

Starting the Managed Servers

After extending the domain, restarting the Administration Server, and propagating the domain to the other hosts, start the configured SOA, OSB, and BAM servers.

1. To display the Fusion Middleware Control login screen, type the following URL into a browser:

   http://ADMINVHN:7001/em
   

2. Log in to Fusion Middleware Control by using the Administration Server credentials.
3. In the Target Navigation pane, expand the domain to view the Managed Servers in the domain.
4. Select the SOA, OSB, and BAM Managed Servers, and click Start Up on the Oracle WebLogic Server toolbar.

   Note:

   BAM Servers depend on the policy access service to be functional, so the WSM-PM Managed Servers in the domain must be up and running and reachable before you start the BAM servers.

Adding the InsightAdmin Role to the Administrators Group

When the startup operation is complete and before you validate the Oracle Insight configuration on the Managed Server, add the InsightAdmin administration role to the enterprise deployment administration group (SOA Administrators).

To perform this task, see Configuring Roles for Administration of Oracle SOA Suite Products.

Validating the Managed Servers After Adding Insight

When the managed servers are started and the InsightAdmin Role is added to the Administrators Group, validate the access to Insight and BAM URLs.

Note:

If a front-end address was configured for the clusters, ensure that you have defined the required URLs in the Web Tier (OHS or OTD) for a successful Insight verification.

1. Navigate to the Domain home page and verify that the BAM, SOA, and OSB Managed Servers are up and running.
2. To verify that the Insight software is configured properly, enter the following URLs in the browser:

   http://SOAHOST1:9001/insight/
   http://SOAHOST2:9001/insight/

   If you have configured Oracle Insight on separate host computers, enter BAMHOST1 in the URL, rather than SOAHOST1.

   The login screen for Insights appears. Enter the weblogic_soa login credentials. The Insight screen appears.
3. For the verification of the Insight agents in the SOA and OSB servers, use the following URLs:
   1. Enter the following URLs in the browser:

      http://SOAHOST1:8001/insight-soa/
      http://SOAHOST2:8001/insight-soa/

      The message Welcome to procmon war appears.

   2. Enter the following URLs in the browser:

      http://SOAHOST1:8011/insight-osb/resources/application.wadl/
      http://SOAHOST2:8011/insight-osb/resources/application.wadl/

      Enter the weblogic_soa login credentials.

      Note:

      Use the port numbers appropriately, as assigned for your static or dynamic cluster. Dynamic clusters for which the Calculate Listen Port option is selected have incremental port numbers for each dynamic managed server that you create.

4. To verify BAM, access the equivalent URLs for WLS_BAM1 and WLS_BAM2:
   1. Enter the following URLs in the browser:

      http://SOAHOST1:9001/bam/composer
      http://SOAHOST2:9001/bam/composer

      The login screen for BAM composer appears. Enter the login credentials. The BAM composer menu is displayed.
   2. Enter the following URLs in the browser:

      http://SOAHOST1:9001/inspection.wsil
      http://SOAHOST2:9001/inspection.wsil

      Enter the weblogic_soa login credentials. A list of links is displayed.

   Note:

   If you configured Oracle BAM on separate host computers, enter BAMHOSTn in the URL, rather than SOAHOSTn.

Configuring the Web Tier for the Extended Domain

Configure the web server instances on the web tier so that the instances route requests for both public and internal URLs to the proper clusters in the extended domain.

For additional steps in preparation for possible scale-out scenarios, see Updating Cross Component Wiring Information.

• Configuring Oracle Traffic Director for the Extended Domain
  
• Configuring Oracle HTTP Server for the WLS_BAM Managed Servers
  Make the following modifications to the Oracle HTTP Server instance configuration files to ensure that the Oracle HTTP Server instances in the web tier routes Oracle Insight requests correctly to the Oracle Insight software on the Oracle SOA, OSB, and BAM clusters.

Configuring Oracle Traffic Director for the Extended Domain

If you have configured Oracle Traffic Director for this domain, you might be required to add additional origin server pools, virtual servers, or routes to the Oracle Traffic Director configuration. To understand the Oracle Traffic Director requirements for each Oracle Fusion Middleware product and for instructions on adding origin server pools, virtual servers, and routes, see Defining Oracle Traffic Director Virtual Servers for an Enterprise Deployment.

Configuring Oracle HTTP Server for the WLS_BAM Managed Servers

Make the following modifications to the Oracle HTTP Server instance configuration files to ensure that the Oracle HTTP Server instances in the web tier routes Oracle Insight requests correctly to the Oracle Insight software on the Oracle SOA, OSB, and BAM clusters.

These instructions assume that you are configuring Oracle BAM/Insight on the same host as Oracle SOA Suite. If you use separate hosts for Oracle BAM and Insight, you must modify the WebLogicCluster parameter in the Oracle HTTP Server configuration files to reference the BAMHOST computers, rather than the SOAHOST computers.

To enable Oracle HTTP Server to route requests to Oracle Insight:

1. Log in to WEBHOST1 and change directory to the configuration directory for the first Oracle HTTP Server instance (ohs1):

   cd WEB_DOMAIN_HOME/config/fmwconfig/components/OHS/ohs1/moduleconf
   

2. Add the following directives inside the <VirtualHost> tag in the soa_vh.conf file:

   Note:

   If BAM is configured on separate hosts, replace SOAHOST1 and SOAHOST2 with BAMHOST1 and BAMHOST2, respectively.

   <Location /insight >
     WLSRequest ON
     WebLogicCluster SOAHOST1:9001,SOAHOST2:9001
     WLProxySSL ON
     WLProxySSLPassThrough ON
   </Location>
   
   <Location /insight-soa>
     WLSRequest ON
     WebLogicCluster SOAHOST1:8001,SOAHOST2:8001
     WLProxySSL ON
     WLProxySSLPassThrough ON
   </Location>
   

3. Add the following directive inside the <VirtualHost> tag in the osb_vh.conf file:

   <Location /insight-osb/resources/>
     WLSRequest ON
     WebLogicCluster SOAHOST1:8011,SOAHOST2:8011
     WLProxySSL ON
     WLProxySSLPassThrough ON
   </Location>

4. Log in to WEBHOST2 and change the directory to the following location so that you can update the configuration file for the second Oracle HTTP Server instance (ohs2):

   cd WEB_DOMAIN_HOME/config/fmwconfig/components/OHS/ohs2/moduleconf
   

5. Open the soa_vh.conf file and add the directives to the <VirtualHost> tag.
6. Open the osb_vh.conf file and add the directives to the <VirtualHost> tag.
7. Restart the Oracle HTTP Server instances on WEBHOST1 and WEBHOST2.

Validating the Access to Oracle Insight Through the Hardware Load Balancer

Verify that Oracle Insight URLs are successfully routing requests from the hardware load balancer to the Oracle HTTP Server instances to the Oracle Insight software in the middle tier.

You can also use this procedure test the failover of the Managed Servers where Oracle Insight is configured.

To verify the URLs:

1. While the WLS_BAM1 Managed Server is running, stop the WLS_BAM2 Managed Server by using the Oracle WebLogic Server Administration Console.
2. Access the following URL and verify the HTTP response as indicated in Starting WLS_BAM1 Managed Server:

   https://soa.example.com/insight
   

3. Access the following URLs to ensure that the Insight agent is running as expected:

   • https://soa.example.com/insight-soa

     After you log in with your credentials, the following message appears:

     "Welcome to procmon war"

   • https://osb.example.com/insight-osb/resources/application.wadl

     After you log in with your credentials, the wadl content appears.

4. Start WLS_BAM2 from the Oracle WebLogic Server Administration Console.
5. Stop WLS_BAM1 from the Oracle WebLogic Server Administration Console.
6. Access the /insight URL again, and verify that the HTTP response is still valid, as indicated in Starting and Validating the WLS_BAM2 Managed Server.

Adjusting JTA Values for Insight Models

The activation of complex insight models involves XA operations that may be affected by the latency in accessing the database. XA exceptions such as java.sql.SQLException: XA error: XAResource.XAER_NOTA start() may show up in the Insight servers' logs. These exceptions indicate that the JTA timeout periods must be increased to accommodate the delay in completing the activation. Typically, increasing the timeout for the BamDataSource should suffice.

To increase the JTA timeout periods, follow these steps:

1. Log in to Weblogic Console.
2. Click the Data Sources link.
3. Select BamDataSource from the Data Sources shown in the table.
4. Navigate to the Transaction tab.
5. Enable Set XA Transaction Timeout.
6. Set XA Transaction Timeout to zero (0).

This procedure sets the BamDataSource JTA timeout to the same value as the domain timeout, which is 30 seconds by default. However, you may need to adjust the global domain and Distributed_Lock_Timeout in the database for appropriate behavior. As a generic rule, the database's Distributed_Lock_Timeout must be larger than the XA DS Timeout which in turn much be equal or larger than the domain's Global Transaction Timeout. For more details about processing transactions and manage transaction timeouts, see Introducing Transactions in Developing JTA Applications for Oracle WebLogic Server.

Backing Up the Configuration

As a best practice, Oracle recommends you to create a backup after you successfully extended a domain or at another logical point. Create a backup after you verify that the installation done until the point at which you decide to create the backup is successful. A quick backup is used for the express purpose of immediate restoration if problems are encountered in later steps.

The backup destination is the local disk. You can discard this backup when the enterprise deployment setup is complete. After the enterprise deployment setup is complete, you can initiate the regular deployment-specific Backup and Recovery process.

For information about backing up your configuration, see Performing Backups and Recoveries in the SOA Enterprise Deployments.