B Using Oracle Portal Installation and Configuration Scripts

After installing Oracle Portal as part of the Oracle Fusion Middleware installation, several scripts are available for post-installation configuration.

The specific topics covered in this appendix include:

Managing the Invalidation Message Processing Job Using cachjsub.sql
Configuring for IP Check During Session Cookie Validation
Using the secupoid.sql Script
Configuring the Portal Session Cookie
Managing the Session Cleanup Job
Timing and Caching Statistics
Using the cfgiasw Script to Configure Mobile Settings
Using the cfgxodnc.pl Script to Change the Mobile Device Component of the Cache Key
Using the Category and Perspective Scripts
Using the PDK-Java Preference Store Migration and Upgrade Utility
Using the Schema Validation Utility

B.1 Managing the Invalidation Message Processing Job Using cachjsub.sql

Oracle Portal uses caching to improve its performance. One type of caching it uses is the invalidation-based caching. In invalidation-based caching, Oracle Portal caches various objects (pages, portlets, and so on) for a set amount of time. When these objects are requested, they are retrieved from the cache, if available; otherwise they are regenerated from the Metadata Repository. The cache for these objects will expire when the maxcache time has been reached, or when the objects are explicitly invalidated (expired) by invalidation messages.

Oracle Portal uses invalidation messages when it needs to expire objects in the cache. Invalidation messages are categorized as hard and soft invalidations. Hard invalidations take effect immediately, that is, the objects that they intend to invalidate expire from cache immediately. Soft invalidations take effect when they are processed by the invalidation processing job. The frequency by which the invalidation job executes is configurable. This is done using the cachjsub.sql script.

To change the execution frequency of the invalidation processing job:

Locate the following directory:

ORACLE_HOME\portal\admin\plsql\wwc
On the database where the portal schema is installed, log on to SQL*Plus with the appropriate user name and password for that schema.

For example:
```
sqlplus portal/portal
```
Enter the following command to update the execution frequency of the invalidation job:
```
SQL> @cachjsub.sql <start_time> <start_time_fmt> <interval_mins>
```
cachjsub.sql takes three parameters:
- start_time is either when the first job should be run or START.
- start_time_fmt is the Oracle date format model to be applied to the value of start_time. Refer to the database documentation library for more information about the Oracle date format model.
- interval_mins is how many minutes each run is scheduled apart.
  
  Note:
  
  If START is provided for the first parameter, the second parameter is ignored, and it will default the start time to the current time.
Example 1:
```
SQL> @cachjsub.sql START null 120
```
Example 2:
```
SQL> @cachjsub.sql '02-22-2005 7:30' 'MM-DD-YYYY HH:MI' 1440
```
Example 3:
```
SQL> @cachjsub.sql '06-14-2005 15:30' 'MM-DD-YYYY HH24:MI' 60
```
Note: Example 3 shows time in the 24-hour format.

B.2 Configuring for IP Check During Session Cookie Validation

As part of the process of validating the session cookie of a user's request (even if that user is orcladmin), Oracle Portal can be configured to perform a comparison between the IP address stored in the cookie with the IP address of the current client. Only if the two values are the same will Oracle Portal consider the request legitimate.

By default, Oracle Portal does not perform this check. When a proxy exists between the user's client and the portal, the IP address stored in the session cookie is that of the proxy, and not that of the client.

Depending on the network configuration into which the Oracle Fusion Middleware is installed, it may be possible to enable IP checking in cookie validation, for added security.

To change the state of IP checking in cookie validation, use SQL*Plus to update data in the portal schema as detailed in Table B-1.

Table B-1 Enabling and Disabling the IP Check

Portal Schema SSO Schema

	Portal Schema	SSO Schema
Enable IP Checking	`update wwsec_enabler_config_info$` `set url_cookie_ip_check = 'Y';` `commit;`	`update wwsec_enabler_config_info$` `set url_cookie_ip_check ='Y';` `update wwsso_ls_configuration_info$` `set cookie_ip_check = 'Y';` `commit;`
Disable IP Checking	`update wwsec_enabler_config_info$` `set url_cookie_ip_check = 'N';` `commit;`	`update wwsec_enabler_config_info$` `set url_cookie_ip_check ='N';` `update wwsso_ls_configuration_info$` `set cookie_ip_check = 'N';` `commit;`

Enable

IP Checking

update wwsec_enabler_config_info$

set url_cookie_ip_check = 'Y';

commit;

update wwsec_enabler_config_info$

set url_cookie_ip_check ='Y';

update wwsso_ls_configuration_info$

set cookie_ip_check = 'Y';

commit;

Disable

IP Checking

update wwsec_enabler_config_info$

set url_cookie_ip_check = 'N';

commit;

update wwsec_enabler_config_info$

set url_cookie_ip_check ='N';

update wwsso_ls_configuration_info$

set cookie_ip_check = 'N';

commit;

B.3 Using the secupoid.sql Script

By default, Oracle Portal connects to Oracle Internet Directory using LDAP without SSL. If the Oracle Internet Directory server is configured for an SSL port, though, Oracle Portal can be configured to use LDAP over SSL, also known as LDAPS.

B.4 Configuring the Portal Session Cookie

Oracle Portal uses a session cookie to maintain session state for portal applications. For portal to work correctly, the client browser must be configured to accept cookies from the server. Upon installation, the portal session cookie has a default name, scope, and security that are set appropriately for most installations. This section describes these defaults, and how they can be changed if needed.

B.4.1 Configuring the Cookie Name

By default the portal's session cookie is named portal after the default Database Access Descriptor (DAD) used to access the portal schema. You can use Oracle Enterprise Manager 11g to change the cookie name, if it needs to explicitly be set to something else. To do this, you must access the DAD Edit page in the Oracle Enterprise Manager 11g Fusion Middleware Control. This page is located under mod_plsql services of the Oracle Portal middle-tier component. The cookie name can be set on the Document Alias and Session Parameter page. To change the name of the cookie, provide the desired name in the Session Cookie Name field of the Session Cookie section.

B.4.2 Configuring the Scope of the Cookie

In cases where you want access to the same portal from two middle tiers at the same time, or if you want to open the portal cookie domain as required by the PL/SQL Adapter functionality, you must define the scope of the Oracle Portal session cookie to be sent to all the middle-tier servers involved in the architecture. By default, the session cookie's domain is scoped to the host from which it was generated. The path for the cookie is set to "/".

Note:

You should make these changes when there is no traffic on the portal, otherwise existing sessions will experience session errors (ORA-20000) after you change the session cookie name.

For example, if the cookie was generated from www.company.com, then the cookie domain is www.company.com. However, let's say that another server, portal.company.com is also a middle-tier server that needs access to that session cookie. Then the cookie domain would need to be widened so that the portal.company.com server can also see the cookie.

Follow these steps to modify the scope of the portal session cookie:

Locate the following directory:
```
ORACLE_HOME\portal\admin\plsql\wwc 
```
On the database where your Oracle Portal schema is installed, log on to SQL*Plus as the portal schema. For example:
```
sqlplus portal\portal_pwd
```

Enter the following command:

SQL> @ctxckupd
OracleAS Portal
Current Settings for Portal Session Cookie:
Cookie Domain : Only send cookie back to originating host:port
Set Cookie as Secure: Y
Enter the domain for the session cookie: .company.com
Should cookie be flagged as secure for HTTPS sessions? (Y/N): N
Settings changed to
Cookie Domain : .company.com
Do not set cookie as secure. (N)
SQL>

This enables you to set the cookie domain for the session cookie. In this example, the cookie domain is set to .company.com.

Notes:

If you want to use different listeners or keep the session cookie throughout different domains, specify a Cookie Domain to be the host name only. For example, if you access Oracle Portal from two computers:

— machine1.us.company.com:3000

— machine2.us.company.com:4000

When running ctxckupd.sql, set the cookie domain to .us.company.com.
The cookie domain also determines the scope of the NLS_LANGUAGE cookie, which is a persistent cookie that determines the user's preferred language. This NLS_LANGUAGE cookie is set when selecting languages in the set language portlet.

B.4.3 Securing the Cookie

In this release of Oracle Portal, the script ctxckupd.sql contains an additional option, Set Cookie as Secure.

The default location for this script is ORACLE_HOME\portal\admin\plsql\wwc. When you run this script, you see the following output:

SQL> @ctxckupd
OracleAS Portal
Current Settings for Portal Session Cookie:
Cookie Domain : Only send cookie back to originating host:port
Set Cookie as Secure: Y
Enter the domain for the session cookie...
Leave blank to scope to originating host:
Should cookie be flagged as secure for HTTPS sessions? (Y/N): N
Settings changed to
Cookie Domain : Only send cookie back to originating host:port
Do not set cookie as secure. (N)
SQL>

Set Cookie as Secure indicates that the cookie should be sent back to the server if the request is over an HTTPS connection only. This setting ensures that the session cookie is not transmitted over an insecure connection when it needs to be protected. By default, this option is set to Yes and is sufficient for most deployments.

In some cases, you may need to set the Set Cookie as Secure option to No. For example, if your portal is accessed over both HTTP and HTTPS and you want the session cookie to be shared across both protocols (possible if they are running on the default ports 80 (HTTP) and 443 (HTTPS)). In this instance, when Set Cookie as Secure is set to No, the same cookie produced over an HTTPSrequest, is sent over any subsequent HTTP requests.

B.5 Managing the Session Cleanup Job

Oracle Portal and OracleAS Single Sign-On perform session management similar to other Web-based applications. Sessions are tracked with cookies. Session information is stored in a table in the Oracle Portal and OracleAS Single Sign-On schema. When a user logs out, the session information is marked inactive. A DBMS job subsequently cleans up the inactive rows.

The session table accumulates a number of rows that are flagged as active. When a user shuts down the browser instead of logging out, the row is "active", even though it is not actually in use. The cleanup job cleans up the active rows that are older than a specified duration.

When Oracle Portal is installed, a DBMS job is installed to perform session cleanup of the session table, WWCTX_SSO_SESSION$. The cleanup job is set to run every 24 hours. The first scheduled cleanup occurs 24 hours after the installation of the job.

When the job runs, it deletes all inactive sessions and all sessions marked active (WWCTX_SSO_SESSION$.ACTIVE = 1), that are older than 7 days (WWCTX_SSO_SESSION$.SESSION_START_TIME < sysdate - 7).

These default settings can be modified by running some job management scripts in the Oracle Portal schema to manage portal sessions, or in the OracleAS Single Sign-On schema to manage OracleAS Single Sign-On sessions. They utilize the same session management infrastructure.

Follow these steps to obtain the current cleanup job information:

Locate the following directory:
```
ORACLE_HOME\portal\admin\plsql\wwc
```
On the database where the Oracle Portal or OracleAS Single Sign-On schema is installed, log in to SQL*Plus with the appropriate user name and password for that schema.

For example:
```
sqlplus portal\portal
```

Enter the following command to get the current job information:

SQL> @ctxjget

The command results in the display of the currently installed job information, as returned by the DBMS_JOB package:

The session cleanup job is job ID 7381
dbms_job.isubmit(job=>7381,what=>'begin execute immediate''begin
wwctx_sso.cleanup_sessions(p_hours_old => 168); end;''; exception when
others then null; end;',next_date=>to_date('2001-04-17:14:07:20',
'YYYY-MM-DD:HH24:MI:SS'),interval=>'SYSDATE + 24/24',no_parse=>TRUE);

PL/SQL procedure successfully completed.

The results indicate which procedure is executed, what parameters are passed to it, and when the next invocation is to occur. This particular example indicates that the job is to clean up active sessions that are a week old (168 hours). It also indicates that the next scheduled job execution is on 4/17/2001 at 5:14 pm, and the job should run every 24 hours thereafter.

If the job execution must be modified, either to adjust the age of sessions that should be deleted, or to increase or decrease the frequency of cleanup, you can run the ctxjsub.sql script to submit modified execution parameters.

Follow these steps to submit modified job execution parameters:

Locate the following directory:
```
ORACLE_HOME\portal\admin\plsql\wwc
```
On the database where the Oracle Portal or OracleAS Single Sign-On schema is installed, log on to SQL*Plus with the appropriate user name and password for that schema. For example:
```
sqlplus portal\portal
```

Enter the following command to submit new cleanup job information:

@ctxjsub <hours_old> <start_time> <time_format> <interval_hours>

Table B-2 lists the ctxjsub parameters.

Table B-2 ctxjsub Parameters

Parameter	Description
`hours_old`	The age of an active session that should be deleted.
`start_time`	The time that the next job should run.
`time_format`	The time format string that specifies how `start_time` is formatted.
`interval_hours`	The amount of time, in hours, between runs of the cleanup job.

For example:

SQL> @ctxjsub 200 '04/17/2001 10:00' 'MM/DD/YYYY HH24:MI' 12

The job information is displayed, similar to:

Created path for job id.
DBMS_JOB id = 7381
Cleanup job updated. Job ID = 7381

PL/SQL procedure successfully completed.

The cleanup job submission script can be run any number of times to modify the execution parameters. Each invocation updates the job information associated with the job ID for the cleanup job. This job ID is maintained in the preference store so that the job information is updated instead of submitting multiple jobs.

You can also specify a start_time of START, in which case, the time_format parameter is ignored, but you still need to pass it a value (such as NOW). The result is to run the job <interval_hours> hours from now:

SQL> @ctxjsub 168 START NOW 24

This submits the job as it does in the installation.

If you want the cleanup job to execute immediately, then obtain the job ID by calling ctxjget.sql. Once you know the job ID, you can execute the job by issuing the following command in the product schema:

SQL> exec dbms_job.run(7381);

In the preceding example, 7381 is the job ID returned by the call to ctxjget.sql. When you execute a job in this manner, the next automated invocation of the job occurs at interval_hours after this manual invocation. To run the job on the original schedule, resubmit the start_time desired using ctxjsub.sql.

B.6 Timing and Caching Statistics

All Oracle Portal pages can be run in a special mode in which timing and caching information is displayed. If you want to see this debug information on every page you can set the Parallel Page Engine Parameter showPageDebug to true in the appConfig.xml file.

Value	Timing and Caching Statistics?	Flag Forwarded to Providers? (as value 1)	logmode Raised to a Minimum of	Log Messages Written to Page Response?
0	Yes	-	-	-
1	Yes	Yes	-	-
2	Yes	Yes	debug	Yes
3	Yes	Yes	request	Yes
4	Yes	Yes	content	Yes
5	Yes	Yes	parsing	Yes

B.6.1 Portlet Statistics

In Figure B-1, you can see a number of Portlet related statistics listed under each portlet. Each Portlet has a unique internal reference identification number. This number is used in the "Information for Portlet" summary. For the portlet in the top left corner of Figure B-1, you can see that this number is 6256.

For each portlet the following statistics are listed:

B.6.1.1 Portlet Timing Information

Portlet Timing (msecs) (wait msecs)

Indicates how many milliseconds it took to retrieve the portlet, and how long the request was queued, also in milliseconds.
Timing Status

This is deprecated and no longer in use.
XSLT Timing (msecs)

Displays the number of milliseconds that were needed to retrieve the XSL style sheet, in case the portlet is an XML portlet.

B.6.1.2 Portlet Caching Information

Portlet Cache status Web Cache (values) File System Cache (values)

This is the Cache status from both Oracle Web Cache and the portal cache.

Valid values for Oracle Web Cache are:
- MISS, or NEW [M] indicating a cache miss in Oracle Web Cache and that the content that is generated by the portlet is new.
- MISS, or STALE [G] indicating a cache miss, due to stale content in Oracle Web Cache.
- HIT [H] indicating an Oracle Web Cache hit.
Valid values for File System Cache are:
- HIT_PING indicating a cache hit for a validation-based portlet.
- HIT_EXPIRES indicating a cache hit for an expiry-based portlet.
- MISS_STALE indicating a cache miss due to stale content in the Cache. This applies to both expiry, and validation-based portlets.
- MISS_NEW indicating a cache miss and that the content that is generated by the portlet is new. This applies to both expiry, and validation-based portlets.
If a portlet uses the File System Cache, then the information mentioned in the preceding text will be listed. Otherwise it will be null.

If there is a hit on Oracle Web Cache, no details about File System Cache will be displayed because the content is served directly out of Oracle Web Cache. Additionally, if a portlet does not use Oracle Web Cache, then no Web Cache information will be printed.
From Cache: Web Cache Cache Expires (seconds), Age in Cache (secs), File System Cache (values).

Information from both Oracle Web Cache and File System Cache will be printed here based on the type of caching that the portlet uses.

See Also:

Oracle Fusion Middleware Administrator's Guide for Oracle Web Cache

"Cache Expires" lists the number of seconds after which the portlet content in Oracle Web Cache will expire.

"Age in Cache" lists the number of seconds that the portlet content has been Cached in Oracle Web Cache.

"File System Cache" displays the information obtained from the File System Cache about Cache Key, Cache Expiry and about the Cache Level in case of a cache hit, with the Cache Status of either HIT_PING, or HIT_EXPIRES.

In case of a cache hit, the Cache Key and Cache Level (for Validation-based portlets) and Cache Expires and Cache Level (for expiry-based portlets) are displayed, with the Cache Status value of either HIT_PING or HIT_EXPIRES.

For Validation-based and Expires-based portlets, "None" is printed when there is a cache miss due to the portlet content being new. (Cache Status: MISS_NEW) The portlet is contacted to get the new Cache Key, Cache Expiry and Cache Level.

For Validation-based portlets, if the content in the Cache has become stale resulting in a cache miss, the current values in the cache for Cache Key and Cache Level are displayed. In this case, the portlet is contacted to get the updated Cache Key and the level (Cache Status: MISS_STALE).

For Expires-based portlets, when the content in the cache has become stale resulting in a cache miss, a value of INVALID in the Expires field and Cache Level are displayed. In this case, the portlet is contacted to get the updated Cache Expiry and Cache Level (Cache Status: MISS_STALE).
From Portlet: (Cache Key) (Cache Level)

From Portlet: (Cache Key) (Cache Level)

This is the information obtained from the portlet about File System Cache Key, Cache Expiry, and Cache Level when there is a cache miss and when portlet is contacted for the updated, or new values (Cache Status: MISS_NEW, or MISS_STALE). Note that there is no Oracle Web Cache related information displayed in this section.

For Validation-based portlets, when there is a cache hit and if the ping is successful, meaning the content in the Cache is still valid, then the portlet does not return a new Cache Key and Cache Level; instead it will indicate that the cache is still valid. In this case, "Ping Success" is displayed (Cache Status: HIT_PING).

For Expires-based portlets, when there is a cache hit and if the content has not expired, then the portlet is not contacted for the content. In this case, "Not contacted" is displayed (Cache Status: HIT_EXPIRES).

Following are a few examples that show different caching scenarios and the resulting output. Note that the other page and portlet related output is not shown here.

Note:

In this release, page portlets are requested as portlets, separate from the container page definition. Therefore, portlet and page caching information is displayed for each page portlet in the debug output.
Example B-1 Caching Information Debug Output 1

Portlet Cache: File System Cache, Caching Type: Validation-based, Status: MISS, STALE.
```
Caching information for portlet: 
Portlet Cache status: File System Cache:- MISS,STALE 
From Cache: File System Cache:- Cache Key: 42, Cache Level: USER 
From Portlet: Cache Key: 44, Cache Level: USER 
```
Example B-2 Caching Information Debug Output 2

Portlet Cache: File System Cache, Caching Type: Expires-based, Status: MISS, NEW.
```
Caching information for portlet: 
Portlet Cache status:File System Cache:-  MISS,NEW 
From Cache: File System Cache:-None 
From Portlet: Cache Expires: 1, Cache Level: USER 
```
Example B-3 Caching Information Debug Output 3

Portlet Cache: File System Cache, Web Cache, Caching Type: Validation and Invalidation-based, Status: MISS, NEW in File System Cache and Web Cache.
```
Caching information for portlet: 
Portlet Cache status: Web Cache:- MISS,NEW [M], File System Cache:- MISS,NEW 
From Cache: Web Cache:- Cache Expires: 86400 secs, Age in Cache: 0 secs , File System Cache:- None 
From Portlet: Cache Key: 9.0.2.2.1502:04:18:09:19:56, Cache Level: SYSTEM 
```
Example B-4 Caching Information Debug Output 4

Portlet Cache: Web Cache, Caching Type: Invalidation-based, Status: HIT in Web Cache.
```
Caching information for portlet: 
Portlet Cache status: Web Cache:- HIT [H] 
From Cache: Web Cache:- Cache Expires: 86400 secs, Age in Cache: 58 secs 
From Portlet: - 
```

B.6.2 Page Statistics

Every page has a unique internal reference identification number, similar to the portlets on the page, shown in Figure B-1.

For the page, the following statistics are listed:

Elapsed Time (msecs)

This is the total amount of time required to generate the page calculated in the Parallel Page Engine (PPE). The actual generation time in the browser can be higher, due to network overhead.

Elapsed time is made up of page meta WAIT time and Stream time. Page meta WAIT time is the time taken to wait on content through an HTTP connection. Stream time is the time taken streaming and assembling the content pieces. Stream time is in turn composed of the following elements:
- Page meta time
- Time waiting for portlets to complete
- Time taken streaming content to the browser
Effectively, elapsed time is the total amount of time (in milliseconds) that it takes to put the page together, from the time the request was received to the last byte being written to the browser.
Page meta-time (msecs) (wait = msecs)

Displays the time that it takes to retrieve the page meta data. The wait time (msecs) represents how long the request was queued.
Page meta Cache Status (Web Cache values), (Cache Expires msecs), (Age in Cache msecs), (File System Cache values)

Represents the cache status from both Oracle Web Cache and portal cache. Valid values for Oracle Web Cache are MISS, or NEW and HIT. Valid values for portal cache are HIT, or PING, and MISS, or STALE. The Web Cache Expires value and the Age in Cache are both measured in milliseconds.
Login meta-time (msecs) (wait msecs)

Displays the time (in milliseconds) that it takes to retrieve the login meta data. The wait time represents the total amount of time (in milliseconds) that the request spends in the request queue.
Login meta Cache Status

Similar to Page meta Cache Status mentioned earlier, represents the cache status for the login meta data from both Web Cache and portal cache.

B.6.3 Additional Summary Statistics

Stream info (msecs)

Represents (in milliseconds) how long it takes for the page to stream to the browser.
processing (msecs)

Processing time (in milliseconds) for streaming.
write (msecs)

The write lines can repeat several times. The lines represent each physical buffer write to the stream itself. This are one set for each buffer write.
flush (msecs)

The flush logs indicate that the writing stream was flushed. This is logged to keep track of the number of network round trips.

B.7 Using the cfgiasw Script to Configure Mobile Settings

If you want to change portal's references to Oracle Portal or OracleAS Wireless' portal service URLs, you must use the cfgiasw.pl script to manually update the references. The script file is located here:

ORACLE_HOME\assistants\opca

Running the script without parameters will print its usage to the screen, which is shown next:

Usage:

perl cfgiasw.pl -s portal_schema 
     -w ias wireless url 
     -h portal home page url 
     -c connect_string

Table B-4 Oracle Application Server Wireless Configuration Parameters

Parameter	Description
-s	Oracle Database schema for Oracle Portal database objects. `Default = PORTAL`
-w	The URL of the Oracle Application Server Wireless gateway for mobile requests to Oracle Portal. This parameter is mandatory (no default). The value for this parameter must be enclosed in double quotation marks.
-h	The URL of the Oracle Portal home page. This is used within portal to determine the character set of the Oracle Portal middle tier. This information is required when creating an Oracle Application Server Wireless service This parameter is not mandatory (no default). The value for this parameter must be enclosed in double quotation marks.
-c	Connect string for database (no default).

Note:

Ensure that you are using the Perl version that is available as part of the Oracle Portal installation, by setting the path variable as follows:

For Windows:
```
PATH ORACLE_HOME\perl\bin\
```
For Solaris or Linux:
```
PATH ORACLE_HOME/perl/bin
```
While running the cfgiasw script you are prompted for the password. Specify the portal schema password for the script to proceed.

For non-hosted Portals, the OracleAS Wireless' Portal service URL reference can be set in the Mobile tab of the Global Settings page, except the URL of the Oracle Portal home page, which can only be set using the cfgiasw script.

This script is used to set references to both the OracleAS Wireless Portal Service URL and the Oracle Portal home page URL, in Oracle Portal. It can be used in a hosted environment to set the URL references, and will affect all subscribers, because this information is not configured separately for each subscriber. For example:

perl cfgiasw.pl -s portal -c portal_db -w "http://<iaswhost>:<port>/ptg/rm?PAoid=$wireless_service_id"

In the preceding example, if a mobile device makes a request to the Oracle Portal directly without being mediated by an Oracle Application Server Wireless server, Oracle Portal redirects the client to the URL specified here. This URL should be the Oracle Portal's service URL on the Oracle Application Server Wireless server, in the form:

http://<host>:<port>/ptg/rm?PAoid=<service_id>

If this setting is blank, then mobile client requests made directly to Oracle Portal receive an HTTP status indicating that their request is not supported.

See Section 5.7, "Configuring Mobile Support in Oracle Portal" for configuring other mobile settings in Oracle Portal.

B.8 Using the cfgxodnc.pl Script to Change the Mobile Device Component of the Cache Key

The cache key used by Oracle Portal is composed of numerous components. One of these components is based on the URL, and another is based on the OracleAS Wireless header, X-Oracle-Device.Class. These components allow portlet content to be cached based on the class of the mobile device used. Examples of device classes include pcbrowser, pdabrowser, microbrowser, and so on.

You can enable portlet content to be cached based on the name of a specific device rather than the device class. To do this, the X-Oracle-Device.Class header in the device component of the cache key must be replaced with the X-Oracle-Device.Name header.

To ensure that Oracle Portal works properly with portlet content that is cached based on the value of the X-Oracle-Device.Name header, you must do the following:

Enable Oracle Portal to use this header. Refer to Section B.8.1, "Adding the PlsqlCGIEnvironmentList Parameter to the portal_dads.conf File" for the steps to be performed.
Disable caching or configure Oracle Portal to cache content based on the X-Oracle-Device.Name header. To configure Oracle Portal to cache portlet content based on the X-Oracle-Device.Name header, you must perform the following tasks:
See Also:

Oracle Fusion Middleware Administrator's Guide for Oracle Web Cache for the procedure to disable caching of portal content.

B.8.1 Adding the PlsqlCGIEnvironmentList Parameter to the portal_dads.conf File

To enable Oracle Portal to use the X-Oracle-Device.Name header, you must add a new parameter, PlsqlCGIEnvironmentList, to the portal_dads.conf file for the Oracle Fusion Middleware instance. To edit the portal_dads.conf file, perform the following steps:

Open the portal_dads.conf file located in the following directory:

DOMAIN_HOME\config\fmwconfig\servers\WLS_PORTAL\applications\portal\configuration

Add the following entry to the file:

PlsqlCGIEnvironmentList HTTP_X_ORACLE_DEVICE_NAME

Save the portal_dads.conf file.

Note:

Although you can manually edit the portal_dads.conf file, we recommend using Application Server Control. To do this, follow the steps outlined in Section A.2, "DAD Configuration File (portal_dads.conf)" using Fusion Middleware Control.

If you manually edit the portal_dads.conf file, then you must add the necessary mod_rewrite and mod_weblogic directives to the httpd.conf and mod_weblogic.conf files respectively.
Run the following command to restart Oracle HTTP Server:
```
INSTANNCE_HOME\bin\opmnctl restartproc type=OHS
```

If you now try to access Oracle Portal using a mobile device, then content will be rendered based on the mobile device used. The cache will also have an increased capacity.

B.8.2 Running the cfgxodnc.pl script

To enable Oracle Portal to use the X-Oracle-Device.Name header, run the cfgxodnc.pl script in the on mode. This script is available at the following location:

Oracle_HOME\assistants\opca

Usage:

perl cfgxodnc.pl -s portal_schema
     -c portal_connect_string 
     -on|-off

To run this script, you must specify all the parameters.

Table B-5 The cfgxodnc Script Parameters

Parameter Description

Parameter	Description
-s	Oracle Database schema for Oracle Portal database objects. Default = `PORTAL`
-c	Connect string for database (no default).
-on/-off	Option to enable or disable use of `X-Oracle-Device`.Name in the cache key.

-s

Oracle Database schema for Oracle Portal database objects.

Default = PORTAL

-c

Connect string for database (no default).

-on/-off

Option to enable or disable use of X-Oracle-Device.Name in the cache key.

Note:

Ensure that you are using the Perl version that is available as part of the Oracle Fusion Middleware installation, by setting the path variable as follows:

For Windows:

PATH ORACLE_INSTANCE\perl\bin\

For Solaris or Linux:

PATH ORACLE_INSTANCE/perl/bin

Note:

While running the cfgxodnc.pl script you are prompted for the password. Specify the portal schema password for the script to proceed.

The following is an example showing the usage of the cfgxodnc.pl script to enable the X-Oracle-Device.Name header:

perl cfgxodnc.pl -s PORTAL -c portal_database -on

The cache size increases when the X-Oracle-Device.Name header is used in the device component of the cache key. If you revert to using the X-Oracle-Device.Class header, then the cache size decreases again.

You can revert to using the X-Oracle-Device.Class header in the device component of the cache key by running the cfgxodnc.pl script in the off mode.

B.8.3 Adding the useDeviceNameCacheKeys parameter to the PPE Configuration file

To use device names instead of device classes when building cache keys, set the useDeviceNameCacheKeys by editing the appConfig.xml file as mentioned below:

Open the appConfig.xml file located in the following directory:

DOMAIN_HOME\config\fmwconfig\servers\WLS_PORTAL\applications\portal\configuration

Add the following entry to the file:
```
useDeviceNameCacheKeys
```
Save the appConf.xml file.
Restart the Oracle HTTP Server and WLS_PORTAL.

Refer to Section 5.6.3, "Stopping and Starting Portal Components Using Fusion Middleware Control" for information on restarting the Oracle HTTP Server and WLS_PORTAL components.

B.8.4 Clearing Cached Data

To ensure that new cache keys are built based on the device name, you must clear all cached data, both in Oracle Web Cache and Oracle Portal File System Cache. Refer to Section 6.7.3, "Configuring Portal Web Cache Settings Using WLST" for information about clearing data cached in Oracle Web Cache. Refer to Section 5.6.8, "Clearing the Portal Cache" for information about clearing data cached in the File System Cache.

B.9 Using the Category and Perspective Scripts

To ensure that all new category and perspective pages are created without errors and that all existing category and perspective pages display their associated items and pages as expected, you must run the category and perspective scripts.

The scripts required are:

ORACLE_HOME\portal\admin\plsql\wws\pstdefin.sql
ORACLE_HOME\portal\admin\plsql\wws\pstpgshw.sql
ORACLE_HOME\portal\admin\plsql\wws\pstundef.sql
ORACLE_HOME\portal\admin\plsql\wws\pstpgcre.sql
ORACLE_HOME\portal\admin\plsql\wws\pstprcpg.sql

To run these scripts:

Delete the current category or perspective templates.
Connect to Oracle Portal using SQL*Plus as the portal schema user.
Configure the pstdefin.sql file with:
- Page group information. You can re-create the pages in a single page group, several page groups or all page groups.
- Page information. You can re-create category pages only, perspective pages only, or both.
Descriptions for these settings are in the pstdefin.sql file. If necessary, use the script pstpgshw.sql to retrieve information from Oracle Portal to configure the pstdefin.sql file.
Run the script pstpgcre.sql to apply the changes. For example:
```
SQL> @pstpgcre.sql
```

If a template exists in the page group when the new pages are created, new category and perspective pages are created based on that template. If you delete the template before running the scripts or the template is missing, then a new template is created in the page group and the new pages are based on this template.

B.10 Using the PDK-Java Preference Store Migration and Upgrade Utility

A preference store is a mechanism for storing information like user preference data, portlet and provider settings, or even portlet data, while using Oracle Portal. Currently, PDK-Java has two PreferenceStore implementations, DBPreferenceStore and FilePreferenceStore. DBPreferenceStore persists data using a JDBC compatible relational database and FilePreferenceStore persists data using the file system.

This utility allows users to migrate existing data between different preference stores (for example, from FilePreferenceStore to DBPreferenceStore) and to upgrade from previous releases of PDK-Java and Oracle Portal to manage portlet preference data generated by existing portlets. The tool allows upgrading users to ensure that their existing locale-specific portlet preference data uses a naming format compatible with the latest PDK and Oracle Portal releases.

If you have already installed OracleAS PDK, you can manage the information stored in the preference store by using the Preference Store Migration and Upgrade Utility, which is included in the pdkjava.jar file.

For a complete description of the syntax of the Preference Store Migration and Upgrade Utility, run the following command:

java -classpath $ORACLE_HOME/portal/jlib/pdkjava.jar;
 $ORACLE_HOME/portal/jlib/ptlshare.jar
 oracle.portal.provider.v2.preference.MigrationTool

Note:

For filetodb mode of migration, in addition to the pdkjava.jar and ptlshare.jar files that are included in the classpath in the above command, you should include $ORACLE_HOME/jdbc/lib/ojdbc6.jar.

You can run the Preference Store Migration and Upgrade Utility in either of the following modes based on the -mode you select while running the command:

Upgrade mode
Migration mode

Note:

After running the utility, restart WLS_PORTAL and Oracle HTTP Server to ensure that the latest preference store information is used.

Upgrade Mode

Use an upgrade mode (file or db) to upgrade data in place, and to modify existing locale-specific preferences in the preference store so that the naming format used is compatible with the current version of Oracle Portal and a given localePersonalizationLevel setting.

Table B-6 describes the upgrade modes in which you can run the utility.

Table B-6 Upgrade Modes in Which to Run the Utility

Mode	Description
`file`	Use when data in a `FilePreferenceStore` must be upgraded.
`db`	Use when data in a `DBPreferenceStore` must be upgraded.

An upgrade mode (file or db) can be used in the following scenarios:

You have upgraded from OracleAS PDK 9.0.4.0.0 or earlier and want to use existing portlets with the default localePersonalizationLevel setting of language (In earlier releases, the default setting was locale).
You have upgraded from Oracle Portal 9.0.2.0.0 or earlier and want to use existing portlets with a localePersonalizationLevel setting of locale (Oracle Portal now uses different names for some locales and therefore some existing data must be remapped).
You want to change the localePersonalizationLevel for an existing portlet from locale to language or vice-versa.

When using an upgrade mode (file or db), you must use the -remap option to specify the localePersonalizationLevel (language or locale) that you are upgrading to. You can also use the -countries option to specify a prioritized list of ISO country codes, indicating your order of preference in case of a collision between remapped preferences for different countries. For example, if you specify -remap language -countries GB,US in the command, it means that if the utility comes across both US English and British English preferences (en_US and en_GB) in a given preference store, it will remap the British English preference to become the English-wide preference (en).

Note:

While running the utility in db mode, for the pref1User and pref1password properties, use the values specified in the JDBC connection definition in the data-sources.xml file.

Migration Mode

Use a migration mode (filetodb, filetofile, dbtofile, or dbtodb) to copy data from a source preference store to a target preference store. When the utility is run in this mode, the preference stores for all the portlet definitions are updated.

Table B-7 describes the migration modes in which you can run the utility.

Table B-7 Migration Modes in Which to Run the Utility

Mode	Description
`filetodb`	Use when data must be copied from a `FilePreferenceStore` to a `DBPreferenceStore`.
`filetofile`	Use when data must be copied from one `FilePreferenceStore` to another `FilePreferenceStore` that is in a different location.
`dbtofile`	Use when data must be copied from a `DBPreferenceStore` to a `FilePreferenceStore`.
`dbtodb`	Use when data must be copied from one `DBPreferenceStore` to another `DBPreferenceStore` that is based on a different database table.

When using a migration mode (filetodb, filetofile, dbtofile, or dbtodb), you can use the -remap and -countries options to specify that the data should be upgraded in the course of being migrated, that is, locale-specific preferences should be remapped appropriately.

The other options accepted by the utility are used to specify the properties of the preference stores involved in the upgrade or migration process. These options must correspond to the tags you specify in provider.xml to describe the preference stores. For more information about the properties you can set on a preference store, see the PDK-Java XML Provider Definition Tag Reference at:

http://www.oracle.com/technology/products/webcenter/files/pdk_downloads/xml_tag_reference_v2.html

Properties beginning with the prefix -pref1 correspond to properties of the source preference store. In an upgrade mode (file or db), this is the only preference store. For example, specifying -pref1UseHashing true -pref1RootDirectory j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/sample would set the useHashing and rootDirectory properties of a source FilePreferenceStore.

Note:

If you installed the Portal Development Kit, then the source preference store will be available in the following location:

DOMAIN_HOME\servers\WLS_PORTAL\tmp\_WL_user\jpdk\dir_name\war\WEB-INF\providers

When one of the migration basic modes is selected, properties beginning with the prefix -pref2 correspond to properties of the target preference store. For example, specifying -pref2User portlet_prefs -pref2Password portlet_prefs -pref2URL jdbc:oracle:thin:@myserver.mydomain.com:1521:mysid would set the database connection details on a target DBPreferenceStore.

The following are examples of the usage of the utility in UNIX:

java -classpath $ORACLE_HOME/portal/jlib/pdkjava.jar;
 $ORACLE_HOME/portal/jlib/ptlshare.jar
 oracle.portal.provider.v2.preference.MigrationTool -mode file -remap language
 -countries GB,US -pref1UseHashing true
 -pref1RootDirectory $DOMAIN_HOME/servers/WLS_PORTAL/tmp/_WL_user/jpdk/dir/war/WEB-INF/providers

java -classpath $ORACLE_HOME/portal/jlib/pdkjava.jar;
 $ORACLE_HOME/portal/jlib/ptlshare.jar; $ORACLE_HOME/jdbc/lib/ojdbc6.jar
 oracle.portal.provider.v2.preference.MigrationTool -mode filetodb -remap locale
 -countries AR,MX -pref1UseHashing true
 -pref1RootDirectory $DOMAIN_HOME/servers/WLS_PORTAL/tmp/_WL_user/jpdk/dir/war/WEB-INF/providers
 -pref2User portlet_prefs -pref2Password portlet_prefs
 -pref2URL jdbc:oracle:thin:@myserver.mydomain.com:1521:mysid

B.11 Using the Schema Validation Utility

The Schema Validation Utility (SVU) is used to clean up and report any data inconsistencies in the Portal schema. The SVU performs validations on Page Group objects and DB Provider objects.

Some of the benefits of using the SVU are:

It prevents Oracle Portal import from failing due to data inconsistencies between the source and target Portal instances.
It prevents Oracle Portal patching from failing when applying a patch to update a version of Portal.

Schema Validation Utility can be run in the following scenarios:

During the Oracle Portal Export and Import process.
When errors such as ORA-1403, ORA-1422, and ORA-4088 are seen when using the Oracle Portal user interface.

For a more detailed explanation of how the validation is performed, and to download the SVU script, svu_rept.sql, log in to Oracle Metalink at http://metalink.oracle.com and read the article Schema Validation Utility. The Doc ID for this article is 286619.1.

There are two ways of running the Schema Validation Utility, which are:

Using the Schema Validation Utility with Oracle Portal Export and Import
Using the Standalone Schema Validation Utility

B.11.1 Using the Schema Validation Utility with Oracle Portal Export and Import

In Oracle Portal Export and Import, the SVU is run automatically in REPORT mode by default in the background during export and import, in the following stages:

Before exporting - To clean up any data inconsistencies that exist on the source instance.
Before importing - To clean up any data inconsistencies that exist on the target instance that could affect the import process.
After importing - To clean up any data inconsistencies that may have been introduced by the import process.

If the SVU reports any inconsistencies, the export or import process will fail with an ABORT status. If the export or import process is aborted, you will see an error message detailing the inconsistency and providing you with a "cleanup mode" link. Clicking on the link runs SVU in CLEANUP mode so that you can complete the export/import process.

B.11.2 Using the Standalone Schema Validation Utility

The SVU can be run in standalone mode when there are data inconsistencies reported or observed. To run the utility in standalone mode, you need to execute the script svu_rept.sql as the Oracle Portal schema owner (PORTAL):

SQL> @svu_rept.sql

You will be prompted to specify the mode and type to run the script.

Mode:

REPORT - Reports data inconsistencies.
CLEANUP - Cleans up data inconsistencies.

Type:

ALL - Validates both page group objects and DB Provider objects.
PAGEGROUP - Validates page group objects only.
DBPROV - Validates DB Provider objects only.

After you have provided the mode and type, you will be prompted to specify a path to save the log file. You can enter a path like c:\temp\svu.log here. Run the SVU in REPORT mode first, before running it in CLEANUP mode.

IMPORTANT:

Always take a valid backup of the database before running the SVU in CLEANUP mode.
If you run the SVU in CLEANUP mode and then in REPORT mode, inconsistencies should not be reported. If any inconsistencies are reported, you must contact Oracle Support Services.