5 Installing Services Gatekeeper Reporting and Portal Support

This chapter describes how to use the Oracle Communications Services Gatekeeper extension installer to install Services Gatekeeper reporting and portals support.

Installation Prerequisites

Before installing Services Gatekeeper reporting and portal support, you must first install Oracle Business Intelligence (OBI) to host the reporting functionality and Oracle WebCenter Portal (OWP) 11.1.1.6 to host the portal functionality. In addition, you must install a separate database to serve as the analytics staging repository.

See the following sections for a general overview on installing OBI and OWP:

Installing and Configuring OBI
Installing and Configuring OWP

Note:

Detailed installation instructions are not provided for OBI and OWP since those platforms require planning and setup that may be specific to your environment.

Installing and Configuring OBI

A general procedure for installing OBI involves:

Completing installation planning requirements to ensure that your system environment is capable of hosting OBI.
Installing a database and populating that database with the required schemas using the Repository Creation Utility (RCU) tool.
Downloading and running the OBI installer.
Completing configuration of OBI.

For comprehensive installation instructions, see Oracle Fusion Middleware Installation Guide for Oracle Business Intelligence 11g Release 1.

Note:

After you have installed OBI, use the OBI administration console to set the following configuration permissions to Denied:

See privileged errors
See SQL issued errors

To set these permissions:

Access the Oracle BI Presentation Services console using a supported web browser.
Select Administration.
In the Security section, select Manage Privileges.
In Admin: General, select the BI Administrator Role permissions link for each permission listed above.
Set the permission to Denied.
Click OK.

Creating an Analytics Repository Database and User

Once you have installed and configured OBI, you must create a database user with access to the analytics staging data. You can use the same database that supports OBI, or, depending upon your requirements, you can use a separate database instance. The database user should have the following permissions:

connect
resource
create any table
create job

Refer to your database documentation for information on creating database users and granting permissions.

Configuring the Services Gatekeeper RPD File

You must configure a binary format OBI repository (RPD) file containing the data storage schema for Services Gatekeeper using the Oracle BI Administration Tool (admintool.exe).

An RPD file for Services Gatekeeper is installed with Services Gatekeeper in the following location: Middleware_Home/ocsg_5.1/ext/analytics/edr.rpd. The default password of the included file is Orcl123456. For security reasons, use the Oracle BI Administration Tool to change the password.

You must also edit the database connection information in the Services Gatekeeper RPD file before transferring that file to the machine hosting your OBI installation. Use the Oracle BI Administration Tool to edit both the orcl and blockInit database connection, username and password properties in the RPD file to reference your database.

For instructions on configuring RPD files, including changing the password and setting database connection information, see "Importing Metadata and Working with Data Sources" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

Gathering Required OBI System Information

Gather the following information from your OBI installation required when running the Services Gatekeeper analytics installer file (ocsg510_generic_ext.jar):

The OBI admin console URL
The OBI admin console login name
The OBI admin console login name password
The analytics database hostname
The analytics database port
The analytics DBMS/Service
The analytics database username
The analytics database username password
The file path to the configured Services Gatekeeper RPD file
The password for the Services Gatekeeper RPD
The OBI ORACLE_INSTANCE path from your OBI installation

Installing and Configuring OWP

A general procedure for installing OWP involves:

Verifying your environment meets the OWP system requirements.
Installing and configuring a supported database.
Using the RCU tool to create the necessary OWP schemas.
Installing Oracle WebLogic Server.
Downloading and installing OWP.
Configuring an OWP domain.

For comprehensive installation instructions, see Oracle Fusion Middleware Installation Guide for Oracle WebCenter Portal 11g Release 1.

Gathering Required OWP System Information

Gather the following information from your OWP installation, which will be required when running the Services Gatekeeper portal installer file (ocsg510_generic_ext.jar):

The OWP admin console URL
The OWP admin console login name
The OWP admin console login name password
The OWP managed server name
The OWP home path from your OWP installation

Installation Platforms and Modes

You install Services Gatekeeper reporting and portal support using the following generic installer:

ocsg510_generic_ext.jar

The generic installer only supports GUI mode.

Creating an Installation Log

To create an installation log, add the following option to any of the commands that invoke the installer:

-log=logfilename

where logfilename is a name that you assign to the log file.

For example, the following command runs the Linux 32-bit Services Gatekeeper extension installer and creates a log file named install_log containing the installation's output.

java -jar ocsg510_generic_ext.jar -log=install_log

Installing Services Gatekeeper Reporting Support

This section contains instructions for installing Services Gatekeeper reporting support. You must complete the following procedures:

Installing Reporting Support
Modifying OBI Behavior Settings
Configuring the Services Gatekeeper Domain
Accessing Services Gatekeeper Reports

Caution:

Before continuing, make sure that all of the components of both your OBI installation are up and running. That includes administration servers, database servers, and any associated domains.

Installing Reporting Support

To run the installer:

Copy the installer, ocsg510_generic_ext.jar, to the system that is hosting OBI.
If you are installing on a 64-bit system, ensure that a 64-bit JDK, or a hybrid 32/64-bit JDK, is installed on the target machine.

If it is not installed, install one. See "Supported Configurations" for information about supported JDK versions.
Run the java -version command, or java -d64 -version command on platforms using a 32/64-bit hybrid JDK to ensure that the JAVA_HOME environment variable is set to a 64- bit JDK.

If JAVA_HOME is not correctly set, set it to point to the correct JDK.
Add the bin directory of the appropriate JDK (which you have installed separately) to the beginning of the PATH variable definition on the target system. For example:
```
PATH=$JAVA_HOME/bin:$PATH
export PATH
```
Here, JAVA_HOME represents the full path to the JDK directory.
Change to the directory where you downloaded the installation program.
To start the generic installer, do one of the following:
- To start the generic installer on a system that uses a 32/64-bit hybrid JDK, such as the HP-PA, HPIA, and Solaris64 platforms, enter:
```
java -d64 -jar ocsg510_generic_ext.jar [-log=logfilename]
```
- To start the generic installer on a system that uses the Solaris_SPARC 64-bit JDK, enter:
```
java -Xmx1024m -jar ocsg510_generic_ext.jar [-log=logfilename]
```
- To start the generic installer on a 32-bit system, enter:
```
java -jar ocsg510_generic_ext.jar [-log=logfilename]
```
  After the installer starts, the Welcome window appears.
  
  You can cancel the installation at any time by clicking Exit.
In the Welcome window, click Next to proceed with the installation.

The Choose Middleware Home Directory window appears.
Select Use an existing Middleware Home and choose the Middleware home where your OBI domain is located.
Click Next.

The Choose Products and Components window appears.
In the Choose Products and Components window, select only the Analytics checkbox.
Click Next.

The OBIEE Admin Console Parameters window appears.
In the OBIEE Admin Console Parameters window, enter the following information:
- URL: The Listen Address and Listen Port of the administration console for your OBI installation. For example, 127.0.0.1:7001.
- Login Name: The OBIEE WebLogic domain administrator account name.
- Password: The password for the OBIEE WebLogic domain administrator.
Click Next.

The Analytics Database Parameters window appears.
In the Analytics Database Parameters window, enter the following information:
- Host Name: The host name of the database server to be used for analytics data.
- Port: The numeric port on which the database host is listening.
- DBMS/Service: The name of the database or service hosting the analytics data.
- Username: The username that will access the analytics database.
- Password: The password for the database user.
Click Next.

The Analytics Parameters window appears.
In the Analytics Parameters window, enter the following information:
- RPD File Path: The local path to the updated Services Gatekeeper RPD file including the name of the RPD file. For example:
  
  /export/home/oracle/edr.rpd
  
  See "Configuring the Services Gatekeeper RPD File" for information on configuring the included RPD file.
- RPD File Password: The password used to access the analytics repository. The default Services Gatekeeper RPD file password is Orcl123456. Use the Oracle BI Administration Tool to change this password for security reasons.
- OBIEE ORACLE_INSTANCE Path: The Oracle instance location, defined when OBIEE is installed. For example:
  
  Middleware_Home/instances/instance1
  
  where Middleware_Home is the WebLogic home directory of the OBI installation.
Click Next.

The Product Installation Directories window appears.
In the Product Installation Directories fields, enter the directory in which you want to install the Services Gatekeeper extension software.
Click Next.

The Installation Summary window appears.
Make sure that the Installation Summary reflects that you are installing the Analytics package. You can click the Previous button to navigate back so you can make changes.
Click Next to start the installation.

A progress bar indicates the status of the installation process.
When the Installation Complete window appears, click Done.

The installer exits.
Check the WebLogic administration console log for errors.
Restart your OBI instance for the changes to take effect.
Complete the procedures in "Modifying OBI Behavior Settings" and "Configuring the Services Gatekeeper Domain".

Modifying OBI Behavior Settings

Once you have installed Services Gatekeeper reporting support, you must make the following modifications to your OBI installation:

Enable OBI write-back support for parameter/value-related reports.
Enable OBI Iframe support to support portal integration.

Note:

These configuration changes must be made on every OBI server in a clustered environment.

You will also have to make the following updates to your Services Gatekeeper configuration:

Configure the analytics staging database.

Enabling OBI Write-back and Iframe Support

To enable OBI write-back support:

Copy the write-back template located in your Services Gatekeeper installation at Services_Gatekeeper_Home/ext/analytics/write_back.xml, where Services_Gatekeeper_Home is the Services Gatekeeper installation directory, to the following location:

ORACLE_INSTANCE/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obipsn/analyticsRes/customMessages

where ORACLE_INSTANCE is the OBI instance path and n is replaced by the OBI instance number. For example:

/export/u01/home/obi/instances/instance1
Open the file, instanceconfig.xml, located at ORACLE_INSTANCE/config/OracleBIPresentationServicesComponent/coreapplication_obipsn where ORACLE_INSTANCE is the OBI instance path and n is replaced by the OBI instance number.
Locate the ServerInstance element within which you must add the LightWriteback element.

Include the element and its ancestor elements as appropriate, as shown in the following example:

<WebConfig>
   <ServerInstance>
      <LightWriteback>true</LightWriteback>
   </ServerInstance>
<WebConfig>

Next, within the security element, add the InIFrameRenderingMode element:

<Security>
   <InIFrameRenderingMode>allow</InIFrameRenderingMode>
   <!--This Configuration setting...-->
   <ClientSessionExpireMinutes>210</ClientSessionExpireMinutes>
</Security>

Save your changes and close the file.
Restart OBI.
Access the Oracle BI Presentation Services web console using a supported browser. The default address is http://OBI_domain_server:9704 where OBI_domain_server is the OBI host.
In the Oracle BI Presentation Services console, go to Settings then Administration then Manage Privileges.
Grant the privilege Write Back to database to the appropriate group.

Configuring the Services Gatekeeper Domain

You must complete the following tasks in your Services Gatekeeper domain after installing reporting support:

Configure the Analytics Data Source
Deploy the Analytics EAR File
Connect Services Gatekeeper to the Analytics Data Source

Configure the Analytics Data Source

Before you begin, make sure you have the following information for your analytics database.

Database Name
Host Name
Database Server Port
Database User Name
Database User's Password

To configure the analytics staging data source:

Make sure that the Services Gatekeeper administration server is running.
Open the following URL in your web browser:
```
http://hostname:port/console
```
Where hostname is the DNS name or IP address of the Services Gatekeeper administration server and port is the address of the port on which the administration server is listening for requests (8001 by default).
When the login page appears, enter the user name and the password you used to start the administration server (you may have specified this user name and password during the Services Gatekeeper installation process), or enter a user name that has been granted one of the default global security roles.
In the Change Center of the Administration Console, click Lock & Edit.
In the Domain Structure tree, select your Services Gatekeeper domain and expand Services then JDBC, then select Data Sources.
On the Summary of Data Sources page, click New and choose Generic Data Source from the drop down list.
On the JDBC Data Sources Properties page, enter or select the following information:
- Name: Enter the following name for the JDBC data source: analytic.datasource
- JNDI Name: Enter the following path to the JDBC data source: oracle.ocsg.edr.analytic
- Database Type: Select the DBMS type of the database you're using as your analytics staging database. If your DBMS is not listed, select Other.
Click Next to continue.
Select the JDBC driver you want to use to connect to the database.

Note:
You must install JDBC drivers before you can use them to create database connections. Some JDBC drivers are installed with WebLogic Server, but many are not installed.

Click Next to continue.
On the Connection Properties page, enter values for the following properties:
- Database Name: Enter the name of your analytics database.
- Host Name: Enter the DNS name or IP address of the server hosting the analytics database.
- Port: Enter the port on which the database server listens for connections requests.
- Database User Name: Enter the analytics database username.
- Password/Confirm Password: Enter the password for the analytics database user.
Click Next to continue.
On the Test Database Connection page, review the connection parameters and click Test Configuration.

Services Gatekeeper attempts to create a connection from the administration server to the database. Results from the connection test are displayed at the top of the page. If the test is unsuccessful, you should correct any configuration errors and retry the test.

Click Next to continue.
On the Select Targets page, select all of your Services Gatekeeper network tier servers or clusters.
Click Finish to save the JDBC data source configuration and deploy the data source to the targets that you selected.
To activate your changes, in the Change Center of the Administration Console, click Activate Changes.

Deploy the Analytics EAR File

To deploy the analytics EAR file, do the following:

Make sure that the Services Gatekeeper administration server is running.
Open the following URL in your web browser:
```
http://hostname:port/console
```
Where hostname is the DNS name or IP address of the Services Gatekeeper administration server and port is the address of the port on which the administration server is listening for requests (8001 by default).
When the login page appears, enter the user name and the password you used to start the administration server (you may have specified this user name and password during the Services Gatekeeper installation process), or enter a user name that has been granted one of the default global security roles.
If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.
In the left pane of the Console, select Deployments.
In the right pane, click Install.
On the Locate deployment to install and prepare for deployment page, enter to the following path:
```
Middleware_Home/ocsg_5.1/applications
```
where Middleware_Home is the home directory of your Services Gatekeeper installation. Press Enter to update the Current Location.
For standalone single-server environments, select edr_to_analytic-single.ear; for cluster environments, select edr_to_analytic.ear.

Click Next to continue.
On the Choose targeting style page, select Install this deployment as an application.

Click Next to continue.
On the Select deployment targets page, select the network tier servers or clusters that comprise your Services Gatekeeper installation.

Click Next to continue.
Do not modify any of the settings on the Optional Settings page and click Next to continue.
Click Finish.
In the Change Center click Activate Changes.
Select your Services Gatekeeper domain and choose Deployments.
In the Deployments table, select edr_to_analytic and then click Start and choose Servicing all requests.
Click Yes on the Start Deployments page.
For clustered environments, ensure that the deployed application is started on all of the network tier instances in your installation.

Connect Services Gatekeeper to the Analytics Data Source

To connect Services Gatekeeper to the analytics data source, do the following:

Make sure that the Services Gatekeeper administration server is running.
Open the following URL in your web browser:
```
http://hostname:port/console
```
Where hostname is the DNS name or IP address of the Services Gatekeeper administration server and port is the address of the port on which the administration server is listening for requests (8001 by default).
When the login page appears, enter the user name and the password you used to start the administration server (you may have specified this user name and password during the Services Gatekeeper installation process), or enter a user name that has been granted one of the default global security roles.
In the Domain Structure tree, expand OCSG and select any one of your network tier nodes.
On the Oracle Communications Services Gatekeeper page, expand Container Services and select EdrToAnalytic.
In the lower panel, select the Operations tab and then choose connectToDatasource from the Select An Operation drop down list box.
Click Invoke.
Ensure that the operation returns a successful connection.

Accessing Services Gatekeeper Reports

After completing the installation procedures for Services Gatekeeper reporting the following reports can be found in your OBI dashboard in the EDR Analysis Home Page:

API Related Reports

API Usage and Trend
API Response Time and Trend
API Failure Rate and Trend

API Others Reports

API Application Adoption
API Parameter Based

Application Related Reports

Application Usage and Trend
Application Response Time and Trend
Application Failure Rate and Trend

Subscriber Related Reports

Subscriber Application Usage

Installing Services Gatekeeper Portal Support

This section contains instructions for installing Services Gatekeeper reporting support. You must complete the following procedures:

Extending the OWP Domain for a Custom Portal
Installing Portal Support
Accessing Services Gatekeeper Portals

Caution:

Before continuing, make sure that all of the components of both your OWP installation is up and running. That includes administration servers, database servers, and any associated domains.

Extending the OWP Domain for a Custom Portal

The installation of Services Gatekeeper portal support requires extending your OWP domain with the WC_CustomPortal managed server. The OWP installation provides the oracle.wc_custom_portal_template_11.1.1.jar template file for extending your OWP domain.

See "Creating a Custom Managed Server for Framework Applications" in the Oracle Fusion Middleware Installation Guide for Oracle WebCenter Portal for information on extending your OWP domain with the custom portal managed server.

Installing Portal Support

To run the installer:

Copy the installer, ocsg510_generic_ext.jar, to the system that is hosting OWP.
If you are installing on a 64-bit system, ensure that a 64-bit JDK, or a hybrid 32/64-bit JDK, is installed on the target machine.

If it is not installed, install one. See "Supported Configurations" for information about supported JDK versions.
Run the java -version command, or java -d64 -version command on platforms using a 32/64-bit hybrid JDK to ensure that the JAVA_HOME environment variable is set to a 64- bit JDK.

If JAVA_HOME is not correctly set, set it to point to the correct JDK.
Add the bin directory of the appropriate JDK (which you have installed separately) to the beginning of the PATH variable definition on the target system. For example:
```
PATH=$JAVA_HOME/bin:$PATH
export PATH
```
Here, JAVA_HOME represents the full path to the JDK directory.
Change to the directory where you downloaded the installation program.
To start the generic installer, do one of the following:
- To start the generic installer on a system that uses a 32/64-bit hybrid JDK, such as the HP-PA, HPIA, and Solaris64 platforms, enter:
```
java -d64 -jar ocsg510_generic_ext.jar [-log=logfilename]
```
- To start the generic installer on a system that uses the Solaris_SPARC 64-bit JDK, enter:
```
java -Xmx1024m -jar ocsg510_generic_ext.jar [-log=logfilename]
```
- To start the generic installer on a 32-bit system, enter:
```
java -jar ocsg510_generic_ext.jar [-log=logfilename]
```
  After the installer, starts, the Welcome window appears.
  
  You can cancel the installation at any time by clicking Exit.
In the Welcome window, click Next to proceed with the installation.

The Choose Middleware Home Directory window appears.
Select Use an existing Middleware Home and choose the Middleware Home directory where your OWP domain is located.
Click Next.

The Choose Products and Components window appears.
In the Choose Products and Components window, ensure the Portal checkbox is selected.
Click Next.

The WebCenter Administration Console window appears.
In the WebCenter Administration Console window, enter the following information:
- URL: The Listen Address and Listen Port of the administration console for your OWP installation. For example, 127.0.0.1:7001.
- Login Name: The OWP domain administration server login name.
- Password: The password for the OWP domain administration server user.
Click Next.

The Portal Parameters window appears.
In the Portal Parameters window, enter the following information:
- WebCenter Portal Managed Server: The custom portal server created after extending the OWP domain. See "Extending the OWP Domain for a Custom Portal" for more information on extending the OWP domain.
- PRM Endpoint: A URL representing your Services Gatekeeper web service endpoint including the host name and port. For example, http://server:port where server is the name or IP address of your Services Gatekeeper host and port is your Services Gatekeeper web service endpoint port number.
- WebCenter Home Path: The local installation path for OWP. By default this is Middleware_Home/Oracle_WC1 where Middleware_Home is the WebLogic domain home directory used for the OWP installation.
Click Next.

The Product Installation Directories window appears.
In the Product Installation Directories fields, enter the directory in which you want to install the Services Gatekeeper extension software.
Click Next.

The Installation Summary window appears.
Make sure that the Installation Summary reflects that you have chosen to install the Portals. You can click the Previous button to navigate back so you can make changes.
Click Next to start the installation.

A progress bar indicates the status of the installation process.
When the Installation Complete window appears, click Done.

The installer exits.
Restart your OWP instance for the changes to take effect.

Accessing Services Gatekeeper Portals

Once you have configured a domain, and your installation is up and running, you must create a portal manager user using the Services Gatekeeper console. See "Create a Portal Manager Account" for more details.

After installation and configuration, you can access the portals at the following default URLs:

Partner Manager Portal: http://OWP_hostname:port/portal/faces/managerHome
Partner Portal: http://OWP_hostname:port/portal/faces/partnerHome

where OWP_hostname and port are the connection host and port (default 9704) for your OWP installation.