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 OracleAS 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 run time 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 "Figure B-1 Typical Deployment Topology"

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 OracleAS Portal Instance

The following sections detail the additional steps that are required to manage your OracleAS 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

• Updating the Oracle Enterprise Manager 10g targets.xml File

• 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. See section "Updating iasconfig.xml" to follow instructions.

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.

   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

Typically, you use Application Server Control to change the OracleAS 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. Perform the following 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, oradav.conf, and targets.xml files.

In addition, for a portal schema that resides outside Oracle Application Server Metadata Repository, you must also update the password change in the targets.xml file. This file is used by the Oracle Enterprise Manager 10g monitoring technology to effectively monitor the OracleAS Portal target.

To update the password change in the targets.xml file, perform the following steps:

1. Back up the ORACLE_HOME/sysman/emd/targets.xml file.

2. Open the ORACLE_HOME/sysman/emd/targets.xml file using a text editor.

3. Search for the OracleAS Portal target for which TYPE="oracle_portal", and the portal_DAD value corresponds to the OracleAS Portal instance for which the password is being updated.

4. Update the portalDatabaseSchemaPassword property as shown in the following example:

   <Property NAME="portalDatabaseSchemaPassword" VALUE="abc123" ENCRYPTED="False"/>
   
   

   
   

   Note: If the password is updated, then you must enter the updated value in plain text and set ENCRYPTED to FALSE. These properties will be encrypted again on reloading the targets file.

   
   

5. Save the targets.xml file, and then reload the targets file by using the following command:

   ORACLE_HOME/bin/emctl reload

If OracleAS Portal is monitored using an Oracle Enterprise Manager 10g Grid Control Central Agent also, then these steps must also be performed in the Grid Control Central Agent Oracle home.

For Grid Control, the targets.xml file is located in the Oracle home containing the Grid Control Central Agent:

ORACLE_HOME/sysman/emd/targets.xml

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 Updating the Oracle Enterprise Manager 10g targets.xml File

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 the OracleAS Portal perspective, this is an administration console for Oracle Application Server.

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

You need to update the Oracle Enterprise Manager 10g targets.xml file for the following reasons:

• To enable monitoring of OracleAS Portal using Oracle Enterprise Manager 10g

  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 update any database connection changes in a nondefault portal

  If you have a nondefault portal instance whose schema resides outside OracleAS Metadata Repository, every time there is a change in the database connection information you must update the relevant properties in the targets.xml file.

To edit the targets.xml file, 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 user interface 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:

   <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="portalDatabaseMachineName" VALUE="%Database Host%" />
    <Property NAME="portalDatabasePort" VALUE="%Database Port%" />
    <Property NAME="portalDatabaseSchemaPassword" VALUE="%password%" ENCRYPTED="FALSE" />
    <Property NAME="portalDatabaseSchemaUsername" VALUE="%portal schema name%" />
    <Property NAME="OidRepSchemaName" VALUE="SIDFormat/ServiceNameFormat" />
    <!-- If OidRepSchemaName is set to SIDFormat: -->
    <Property NAME="portalDatabaseSID" VALUE="mySID" />
    <!-- If OidRepSchemaName is set to ServiceNameFormat: -->
    <Property NAME="portalDatabaseServiceName" VALUE="myServiceName" />
    <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. Table B-2 and Table B-3 list the relevant targets.xml properties and their descriptions.

   Table B-2 Relevant targets.xml Properties for Monitoring OracleAS Portal

   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 user interface. 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 computer name of the middle-tier computer 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

   
   

   Table B-3 Relevant targets.xml Properties for Updating Database Connection Changes

   Attribute	Description	Example
   portalDatabaseMachineName	Host name of the computer running the database in which OracleAS Portal is installed.	www.abc.com
   portalDatabasePort	Port Number.	1521
   portalDatabaseSchemaPassword	The OracleAS Portal database account password. The password is typically set at installation but you can change it by specifying a new password. Note: If the password is updated, then you must enter the updated value in plain text and set ENCRYPTED to FALSE. Then on reloading the targets file these properties will be encrypted again.	portal30
   portalDatabaseSchemaUserName	The OracleAS Portal database account username.	portal30
   OidRepSchemaName	The connect string format. The following two connect string formats are supported: SIDFormat ServiceNameFormat	SIDFormat
   portalDatabaseSID	The SID of the database running the nondefault portal schema. Set this property only if OidRepSchemaName is set to SIDFormat. Use this format when the connect string is in the format, host:port:sid. For example: myhost.oracle.com:1521:mydb	mySID
   portalDatabaseServiceName	The Service Name of the database running the nondefault portal schema. Set this property only if OidRepSchemaName is set to ServiceNameFormat. Use this format when the connect string is in the format, host:port:service_name. For example: www.abc.com:1521:www.xyz.com	myServiceName

   
   

   Suppose you have an existing target portal and you now want to add a portal called portal30, which uses a SIDFormat connect string, 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="portalDatabaseMachineName" VALUE="www.abc.com" />
    <Property NAME="portalDatabasePort" VALUE="1521" />
    <Property NAME="portalDatabaseSchemaPassword" VALUE="4c958c5c661cabd683d42b2e663da358" ENCRYPTED="TRUE" />
    <Property NAME="portalDatabaseSchemaUsername" VALUE="portal30" />
    <Property NAME="OidRepSchemaName" VALUE="SIDFormat" />
    <Property NAME="portalDatabaseSID" VALUE="mySID"/>
    <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 user interface 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, because 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.