B Configuring and Managing an Upgraded Oracle Application Server Portal Instance

Components of Oracle Application Server 10g Release 2 (10.1.2) are, by default, only aware of a Portal Schema in the Oracle Application Server Metadata Repository. The Portal Schema, in which Oracle Application Server Portal metadata is stored, is an indivisible component of the OracleAS Metadata Repository in a default installation of Oracle Application Server, or in a customer database installation performed by using the Oracle Application Server Metadata Repository Creation Assistant (OracleAS Metadata Repository Creation Assistant).

However, if you have a Portal Schema that has been upgraded from an earlier release and is not located in an OracleAS Metadata Repository, you will not be able to take advantage of some of the new management services for Oracle Application Server 10g Release 2 (10.1.2). Instead, you must perform some manual configuration steps. These limitations, however, do not affect the runtime of the portal, they only affect the manner in which you administer and change the configuration of the portal. This appendix discusses how to configure such a portal.

The following illustration shows a typical deployment topology in which an Oracle Application Server 10g Release 2 (10.1.2) middle-tier uses the services of a Portal schema, which is in turn configured to use the services of Oracle Identity Management.

Figure B-1 Typical Deployment Topology

Description of the illustration cg_depl_topl.gif

The database on the left contains the OracleAS Metadata Repository, which contains an empty default Portal schema. The database on the right contains another Portal schema, which is not contained in an OracleAS Metadata Repository. It is the management of the latter schema that is discussed in this appendix.This situation is typically the result of either upgrading a Portal 3.0.9 to Oracle Application Server 10g Release 2 (10.1.2), or the upgrade of Oracle9iAS Portal (9.0.2) that has been installed in a customer database and then upgraded to Oracle Application Server 10g Release 2 (10.1.2). In many cases the Database Access Descriptor (DAD) name of the portal is not "portal", which is the default DAD name for OracleAS Portal installed in an OracleAS Metadata Repository.

Note: To maintain forward compatibility when creating a portal in a customer database, you must now use OracleAS Metadata Repository Creation Assistant. In doing so, your schema will be part of an OracleAS Metadata Repository.

B.1 Configuring and Managing the Portal Instance

The following sections detail the additional steps that are required to manage your Oracle Application Server Portal instance when its schema resides outside the OracleAS Metadata Repository. The areas where additional configuration is required are:

• Changing the OracleAS Portal Schema Password

• Changing Oracle Identity Management Services

• Monitoring OracleAS Portal with Oracle Enterprise Manager 10g

• Updating iasconfig.xml When the Database Containing the Portal Schema Has Been Reconfigured

• Performing Advanced Configurations with ptlconfig

WARNING: Before you perform any of the configuration tasks in the preceding list, you must update the Portal Dependency Settings file iasconfig.xml with information about your portal by following the instructions in the section Updating iasconfig.xml.

Updating iasconfig.xml

To enable the use of the ptlconfig tool and the Application Server Control for managing an OracleAS Portal instance, you have to create an entry for the upgraded portal in Portal dependency settings file iasconfig.xml. To do this, perform the following steps:

Normally, configuring the OracleAS Single Sign-On data using the ptlconfig tool, to get the OracleAS Single Sign-On information, involves the use of OracleAS Metadata Repository . This works well for portals that are installed out-of-the-box. However, upgraded portals are not registered with the OracleAS Metadata Repository. In such a case, the OracleAS Single Sign-On information will have to be obtained from the OracleAS Single Sign-On server by querying the LDAP directory. To do this, the Oracle Internet Directory SSL port is required to make a connection to the LDAP store.

Perform the following steps to update the iasconfig.xml file with the Port information:

1. Run the ptlconfig tool as follows:

   ptlconfig -load -schema <schema username> -pw <schema password> -conn <connect string> [-lp ldap_ssl_port]
   
   

   For a description of the parameters used in the preceding script, refer to Table B-1, "ptlconfig Parameters".

   Table B-1 ptlconfig Parameters

   Parameter	Description
   -load	Creates and updates entries in iasconfig.xml with the configuration settings for a specific Portal schema.
   -schema	Name of the Portal schema.
   -pw	Portal schema password.
   -conn	Connect string to the Portal schema.

   
   

   The iasconfig.xml file has an optional property named LDAPSSLPort for the OIDDependency element, as shown in Example B-1 . This property contains the LDAP SSL port value, which is used to configure OracleAS Single Sign-On details for upgraded OracleAS Portal instances.

   Example B-1 Example LDAPSSLPort Entry

   <PortalInstance DADLocation="/pls/portal30" SchemaUsername="portal30" SchemaPassword="welcome1" connectString="dbserver.company.com:1521:orcl">
         <WebCacheDependency ContainerType="IASInstance" Name="midtier.abc.company.com"/>
         <OIDDependency ContainerType="IASInstance" LDAPSSLPort="4339" Name="infra.xyz.company.com"/>
         <EMDependency ContainerType="IASInstance" Name="midtier.abc.company.com"/>
   </PortalInstance>
   ...
   <IASConfig>
   
   

2. Open the iasconfig.xml file located by default in ORACLE_HOME/portal/conf, where ORACLE_HOME is the OracleAS Portal and Oracle Application Server Portal and Wireless middle-tier home.

3. Update the LDAPSSLPort property with the correct Oracle Internet Directory SSL port information.

B.1.1 Changing the OracleAS Portal Schema Password

Normally, you use Application Server Control to change the Portal schema password, but in the case of the portal instance whose schema resides outside the OracleAS Metadata Repository, you have to change the Portal schema password using SQL*Plus.

Follow these steps to change schema passwords directly in the database:

1. Connect to the database as a user with SYSDBA privileges

2. Enter the following command:

   SQL> ALTER USER <schema> IDENTIFIED BY <new_password>;
   
   

   For example, to change the PORTAL30 schema password to "abc123":

   SQL> ALTER USER PORTAL30 IDENTIFIED BY abc123;
   
   

Next, update the schema password in the Portal Dependency Settings file, iasconfig.xml as follows:

1. Locate the file iasconfig.xml. By default, it is located in the following directory:

   MID_TIER_ORACLE_HOME/portal/conf
   

   
   

   Note: The environment variable IASCONFIG_LOC is sometimes used to specify another directory for the location of this file.

   
   

2. Edit the iasconfig.xml file, by changing the value specified for the SchemaPassword attribute to your new password. The following example shows the changes made to the PortalInstance element in bold text:

   <PortalInstance DADLocation="/pls/portal" 
   SchemaUsername="portal" SchemaPassword="abc123"
   connectString="dbserver.company.com:1521:orcl">
      <WebCacheDependency ContainerType="IASInstance" 
   Name="midtier.abc.company.com"/>
      <OIDDependency ContainerType="IASInstance" 
   Name="infra.xyz.company.com"/>
      <EMDependency ContainerType="IASInstance" 
   Name="midtier.abc.company.com"/>
   </PortalInstance>
   
   

3. Encrypt the plain text password that you added in iasconfig.xml by running the following command:

   ptlconfig -encrypt

   
   

   Note: You do not have to run ptlconfig in another mode at this time.

   
   

After this, you have to update the Database Access Descriptor (DAD) with the new password. Follow these steps to update the DAD:

1. Using a Web browser, navigate to the Application Server Control, typically located at:

   http://<host>.<domain>:1812
   
   

2. Navigate to the Application Server instance in which you want to update the DAD.

3. Select HTTP Server from the System Components table.

4. Click Administration.

5. Click PL/SQL Properties.

6. In the DADs section, select the DAD you want to update.

7. In the Database Connectivity Information section, change the password in the Password field.

8. Click OK.

9. Restart the Oracle HTTP Server.

10. Restart the OC4J_Portal instance.

    To do this, navigate to the Application Server instance, select the OC4J_Portal check box, and click Restart.

This will update the dads.conf and the oradav.conf files.

B.1.2 Changing Oracle Identity Management Services

If your portal is using the Oracle Identity Management services from the Oracle Application Server Infrastructure that is registered with the Oracle Application Server middle-tier, then additional steps need to be performed whenever changes are made to the Oracle Identity Management services.

You may, for example, need to change the configuration if the administrative password of Oracle Internet Directory changes.

Normally, you make these changes using the Application Server Control, but in this case, you have to modify iasconfig.xml manually.

Perform the following steps to update iasconfig.xml with a new Oracle Internet Directory host name or port number:

1. Locate the file iasconfig.xml. By default it is located in the following directory:

   MIDDLE_TIER_ORACLE_HOME/portal/conf
   

   
   

   Note: To maintain forward compatibility when creating a portal in a customer database, you must now use OracleAS Metadata Repository Creation Assistant. In doing so, your schema will be part of an OracleAS Metadata Repository.

   
   

2. Edit the iasconfig.xml file, by changing the values specified for the OIDComponent attributes in the IASInstance element. The following example shows the changes made to the IASInstance element in bold text:

   <IASInstance Name="infra.xyz.company.com" Host="xyz.company.com" Version="10.1.2">      <OIDComponent AdminPassword="welcome9" PortSSLEnabled="false" LDAPPort="3002" AdminDN="cn=orcladmin"/>      <EMComponent ConsoleHTTPPort="1814" SSLEnabled="false"/></IASInstance>
   
   

3. Encrypt any plain text passwords in iasconfig.xml by running the following command:

   ptlconfig -encypt
   
   

4. Update the Portal Schema with the new configuration settings in iasconfig.xml, by running the following command:

   ptlconfig -dad <portal_dad_name> -site -oid
   
   

   Where portal_dad_name is your portal DAD name.

   For example:

   ptlconfig -dad portal30 -site -oid
   

B.1.3 Monitoring OracleAS Portal with Oracle Enterprise Manager 10g

OracleAS Portal can be monitored using either the Oracle Enterprise Manager 10g Application Server Control or the Oracle Enterprise Manager 10g Grid Control.

The Application Server Control is included when you install Oracle Application Server. From OracleAS Portal's perspective, this is an administration console for Oracle Application Server.

The Grid Control provides full enterprise management and extensive notification and alerting services.

Application Server Control and Grid Control each use information stored in their own targets.xml file to manage and monitor their targets. To manage and monitor your portal instance you must edit the targets.xml file manually. To do this, perform the following steps for the Application Server Control and then repeat these steps for the Grid Control if you have installed it.

1. Locate the targets.xml file.

   For the Application Server Control, it is located in the Oracle home of the Application Server middle-tier:

   MID_TIER_ORACLE_HOME/sysman/emd/targets.xml
   
   

   For the Grid Control, it is located in the Oracle home containing the Grid Control Central Agent:

   ORACLE_HOME/sysman/emd/targets.xml
   

   
   

   Note: You cannot use the Target Creation UI in Grid Control to create a portal target.

   
   

2. Make a backup copy of the targets.xml file before you modify it.

3. Copy and paste the following template for the new target entry in the targets.xml file is:

   <Target TYPE="oracle_portal" NAME="%Name%" 
   DISPLAY_NAME="%DisplayName%" VERSION="1.0">
    <Property NAME="version" VALUE="%Version%" />
    <Property NAME="OracleHome" VALUE="%OracleHome%" />
    <Property NAME="PortalListeningHostPort" 
   VALUE="%PortalListeningHostPort%" />
    <Property NAME="HTTPMachine" VALUE="%HTTPMachine%" />
    <Property NAME="HTTPPort" VALUE="%HTTPPort%" />
    <Property NAME='HTTPProtocol' VALUE="%protocol%" />
    <Property NAME="portal_DAD" VALUE="%portal_DAD%" />
    <Property NAME="OidRepSchemaName" VALUE="%portal_DAD_schema%" />
   <Property NAME="startComponent" 
   VALUE="%iasName%.%machine%_OC4J_Portal"/>
    <Property NAME='PPESuccessfulResponsesCriticalThreshold' 
   VALUE='80' />
    <Property NAME='PPESuccessfulResponsesWarningThreshold' VALUE='90' 
   />
    <Property NAME='modplsqlSuccessfulResponsesCriticalThreshold' 
   VALUE='80' />
    <Property NAME='modplsqlSuccessfulResponsesWarningThreshold' 
   VALUE='90' />
    <Property NAME='portletResponseCriticalThreshold' VALUE='4500' />
    <Property NAME='portletResponseWarningThreshold' VALUE='4000' />
    <CompositeMembership>
      <MemberOf TYPE="oracle_ias" 
   NAME="%iasName%.%machine%.%domain%"/>
    </CompositeMembership>
   </Target>
   
   

4. Edit the properties in the portal target and add your instance-specific property values. The following table lists the relevant targets.xml properties and their descriptions:

   Table B-2 Relevant targets.xml Properties

   Attribute	Description	Example
   NAME	The target name, using the following format: %iasName%.%machine_name%._Portal:%DAD name%	my1012PW.machine1.abc.com_Portal:portal30
   DISPLAY_NAME	The target display name visible in the UI. Format: Portal:%DAD name%	Portal:portal30
   version	The Portal version number.	10.1.2
   OracleHome	The Oracle home path.	/u01/app/oracle/product/my1012PW
   PortalListeningHostPort	The entry point to the portal excluding the DAD information.	machine1.abc.com:7778
   HTTPMachine	The machine name of the middle-tier machine running Oracle HTTP Server.	machine1.abc.com
   HTTPPort	Oracle HTTP Server port.	7778
   HTTPProtocol	Oracle HTTP Server protocol.	http or https
   portal_DAD	The Portal DAD.	portal30
   OidRepSchemaName	The database schema name of the Portal instance.	portal30

   
   

   Suppose you have an existing target portal and you now want to add a portal called "portal30". You must add the template and then make the changes shown in bold text:

   <Target TYPE="oracle_portal" 
   NAME="my1012PW.machine1.abc.com_Portal:portal30" 
   DISPLAY_NAME="Portal:portal30" VERSION="1.0">
    <Property NAME="version" VALUE="10.1.2"/>
    <Property NAME="OracleHome" VALUE="/u01/app/oracle/product/my1012PW"/>
    <Property NAME="PortalListeningHostPort" VALUE="machine1.abc.com:7778"/>
    <Property NAME="HTTPMachine" 
   VALUE="machine1.abc.com"/>
    <Property NAME="HTTPPort" VALUE="7778"/>
   <Property NAME="HTTPProtocol" VALUE="http"/>
    <Property NAME="portal_DAD" VALUE="portal30"/>
    <Property NAME="OidRepSchemaName" VALUE="portal30"/>
    <Property NAME="startComponent"  
   VALUE="my1012PW.machine1.abc.com_OC4J_Portal"/>
    <Property NAME="PPESuccessfulResponsesCriticalThreshold" VALUE="80"/>
    <Property NAME="PPESuccessfulResponsesWarningThreshold" VALUE="90"/>
    <Property NAME="portletResponseCriticalThreshold" VALUE="4500"/>
    <Property NAME="portletResponseWarningThreshold" VALUE="4000"/>
    <Property NAME="modplsqlSuccessfulResponsesCriticalThreshold" 
   VALUE="80"/>
    <Property NAME="modplsqlSuccessfulResponsesWarningThreshold" VALUE="90"/>
    <CompositeMembership>
      <MemberOf TYPE="oracle_ias" NAME="my1012PW.machine1.abc.com"/>
    </CompositeMembership>
   </Target>
   
   

5. Navigate to the ORACLE_HOME/bin directory of the Application Server Control or the Grid Control of which you have just edited the targets.xml file and run the following command:

   emctl reload
   
   

6. Verify that your target now shows up in the Application Server Control (or Grid Control). Using a Web browser, navigate to the Application Server Control, typically located at:

   http://<host>.<domain>:1812
   
   

   The new portal instance should appear in the list of System Components.

B.1.4 Updating iasconfig.xml When the Database Containing the Portal Schema Has Been Reconfigured

If you have reconfigured the database containing the portal schema such that the connection details for the database (for example, the server location, TNS port, or SID) have changed then you will need to edit the entry for the reconfigured portal in Portal dependency settings file iasconfig.xml. To do this, perform the following steps:

1. Locate the targets.xml file.

   For the Application Server Control, it is located in the Oracle home of the Application Server middle-tier:

   MID_TIER_ORACLE_HOME/sysman/emd/targets.xml
   
   

   For the Grid Control, it is located in the Oracle home containing the Grid Control Central Agent:

   ORACLE_HOME/sysman/emd/targets.xml
   

   
   

   Note: You cannot use the Target Creation UI in Grid Control to create a portal target.

   
   

2. Edit the iasconfig.xml file and change the connectString for the Portal instance to be reconfigured. The following example shows an updated entry:

   <PortalInstance DADLocation="/pls/portal30" 
   SchemaUsername="portal30" SchemaPassword="welcome1"
   connectString="abc.company.com:1521:db901dev">
      <WebCacheDependency ContainerType="IASInstance" 
   Name="midtier.abc.company.com"/>
      <OIDDependency ContainerType="IASInstance" 
   Name="infra.xyz.company.com"/>
      <EMDependency ContainerType="IASInstance" 
   Name="midtier.abc.company.com"/>
   </PortalInstance>
   
   

3. Update the OracleAS Metadata Repository with the new configuration settings in iasconfig.xml, by running the following command:

   ptlconfig -dad <dad_name> -wc -oid -em -site
   
   

   Where dad_name is the name of the portal DAD.

   
   

   Note: You cannot use the instructions for changing the Metadata Repository used by a middle-tier instance described in the Oracle Application Server Administrator's Guide, since the Portal schema is not contained in an OracleAS Metadata Repository.

   
   

B.1.5 Performing Advanced Configurations with ptlconfig

When making advanced configuration changes by using the ptlconfig command the documentation examples in this guide often use the default DAD name portal. For example, you may be instructed to run the ptlconfig tool as follows:

ptlconfig -dad portal

Remember to always substitute your actual DAD name if it is not "portal" (For example, portal30).

B.1.6 Conclusion

Upgraded OracleAS Portal instances whose schema resides outside of an OracleAS Metadata Repository require manual steps to perform a few configuration changes that an OracleAS Metadata Repository contained portal instance is able to complete by using the graphical user interface of Oracle Enterprise Manager 10g. The additional steps outlined in this appendix can be performed with a minimum of additional effort to achieve the same configuration and management operations.