The main configuration files for WebCenter Portal applications are adf-config.xml
and connections.xml
. This appendix describes both these files, how to locate them, and also when to configure these files and which tools to use. Other configuration files, such as web.xml
and webcenter-config.xml
are described here too. See also, Section 1.3.5, "WebCenter Portal Configuration Considerations."
This appendix includes the following sections:
See also, Appendix D, "Troubleshooting WebCenter Portal Configuration Issues".
adf-config.xml
, connections.xml
, and web.xml
are used to configure all WebCenter Portal applications (including Spaces) and their back-end services. In addition, the webcenter-config.xml
configuration file, which is specific to the Spaces application, is used to configure application-wide settings.
This section describes how WebCenter Portal applications use each file and the location of these files post deployment. This section includes the following subsections:
adf-config.xml
and connections.xml
both store design time configuration information, such as the discussions server, mail server, or content server that is used by the WebCenter Portal application in the development environment:
adf-config.xml - Stores application-level settings, such as which discussions server or mail server the WebCenter Portal application is currently using.
See also, Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
connections.xml - Stores connection details for WebCenter Portal services.
See also, Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
After you deploy a WebCenter Portal application to a production environment, Oracle recommends that you use Fusion Middleware Control or WebLogic Scripting Tool (WLST) commands to reconfigure properties in these files. For example, you may want to modify connection details to point to production server instances. See also, Appendix A, "Configuration Tools".
The main advantage of using Fusion Middleware Control and WLST commands is that any configuration changes that you make, post deployment, are stored as customizations in the WebCenter Portal application's Oracle Metadata Services (MDS) repository. MDS uses the original deployed versions of adf-config.xml
and connections.xml
as base documents and stores all subsequent customizations separately into MDS using a single customization layer. If the application is redeployed in the future, all previous configuration changes are retained.
When a WebCenter Portal application starts up, application customizations stored in MDS are applied to the appropriate base documents and the WebCenter Portal application uses the merged documents (base documents with customizations) as the final set of configuration properties.
This section includes the following subsections:
For more information on MDS customizations, see "Understanding the MDS Repository" in Oracle Fusion Middleware Administrator's Guide.
Reviewing Post Deployment Customizations in MDS
Post deployment, always use Fusion Middleware Control or WLST commands to review the latest configuration or make configuration changes. In Fusion Middleware Control you will mostly use WebCenter Portal application configuration screens but a useful Systems MBean Browser is also available for reviewing configuration settings. These tools always show you the current configuration so, typically, there is no need for you to examine or change the content of base documents or MDS customization data for files such as adf-config.xml
and connections.xml
.
At times it might be useful to 'see' the information in MDS. If for any reason you must extract or examine configuration file customizations that are stored in MDS, use the WLST command exportMetadata
.
See also:
For detailed syntax and examples, see "exportMetadata" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
For example, to determine MDS customizations for connections.xml
in a Spaces application, which always has the application name webcenter
and is deployed to the WC_Spaces
managed server, the file name and location is always /META-INF/mdssys/cust/adfshare/adfshare/connections.xml.xml
, you might specify:
exportMetadata(application='webcenter', server='WC_Spaces', toLocation='/tmp/mydata', docs='/META-INF/mdssys/cust/adfshare/adfshare/connections.xml.xml')
And similarly, to determine MDS customizations for adf-config.xml
:
exportMetadata(application='webcenter', server='WC_Spaces', toLocation='/tmp/mydata', docs='/META-INF/mdssys/cust/adfshare/adfshare/adf-config.xml.xml')
You choose where to save file customizations by specifying toLocation
. If, for example, toLocation
is set to /tmp/mydata
, then the requested file is saved to /tmp/mydata/META-INF/mdssys/cust/adfshare/adfshare
.
If no customizations exist for the requested file, then nothing is saved to the specified location—previously extracted customizations at the same location are not overwritten.
Exporting Configuration Files with MDS Customizations
You can use the System MBean Browser to obtain "current versions" of configuration files such as adf-config.xml
or connections.xml
, that is, a version of the file that includes the base document merged with MDS customizations.
To export adf-config.xml
or connections.xml
with MDS customizations from the System MBean Browser:
Log in to Fusion Middleware Control and navigate to the home page for Spaces or your Framework application. For more information, see:
Do one of the following:
For the Spaces application - From the WebCenter Portal menu, select System MBean Browser.
For Framework applications - From the Application Deployment menu, select System MBean Browser.
Expand Application Defined MBeans.
Navigate to the MBean associated with the file you want to export.
For example, navigate to MBeans for adf-config.xml
or connections.xml
as follows:
adf-config.xml
- Click oracle.adf.share.config > Server: name> Application: name> ADFConfig> ADFConfig
For the Spaces application: oracle.adf.share.config > Server: WC_Spaces> Application: webcenter> ADFConfig> ADFConfig
connections.xml
- Click oracle.adf.share.connections> Server: name> Application: name> ADFConnnections> ADFConnections
For the Spaces application: oracle.adf.share.config > Server: WC_Spaces> Application: webcenter> ADFConnections> ADFConnections
Click the Operations tab.
Click Export.
Alternatively, click ExportToDisk and then specify a sever location for the XML file.
Click Invoke.
If you selected the Export operation, the content of the XML file displays on the screen (Figure A-1).
Handling Configuration Conflicts
MDS customizations use references to elements in the base document to call out which elements must be inserted/deleted/replaced, and at what location. If an element is inadvertently removed from a future redeployment and MDS contains a reference to that element, then the WebCenter Portal application's configuration appears corrupt.
For example, consider a WebCenter Portal application built using JDeveloper called MyPortalApp
, with a connection, created at design-time, called myconnection
. The application was deployed to a managed server, and a URL in myconnection
was modified. This modification is stored in MDS as a customization instruction to update myconnection
to use the new URL. If in the future, myconnection
is removed at design time and the application redeployed using the same MDS details, a configuration conflict occurs, that is, the customization instruction in MDS attempts to find myconnection
but no such configuration exists.
You are unlikely to face this problem but should a previously deployed application appear corrupt after making changes to adf-config.xml
or connections.xml
you have the following options:
Remove the MDS customization causing conflict manually:
Extract MDS customization information for adf-config.xml
or connections.xml
.
exportMetadata(application='webcenter', server='WC_Spaces', toLocation='/tmp/mydata', docs='/META-INF/mdssys/cust/adfshare/adfshare/adf-config.xml.xml')
exportMetadata(application='webcenter', server='WC_Spaces', toLocation='/tmp/mydata', docs='/META-INF/mdssys/cust/adfshare/adfshare/connections.xml.xml')
Remove the customization instruction that is causing conflict from the document.
Import the modified document back in to MDS.
For example:
importMetadata(application='webcenter', server='WC_Spaces', fromLocation='/tmp/mydata', docs='/META-INF/mdssys/cust/adfshare/adfshare/connections.xml.xml')
importMetadata(application='webcenter', server='WC_Spaces', fromLocation='/tmp/mydata', docs='/META-INF/mdssys/cust/adfshare/adfshare/adf-config.xml.xml')
Restart the managed server.
Delete MDS customizations for adf-config.xml
or connections.xml
, deploy the new EAR file, and reconfigure your application from scratch using Fusion Middleware Control or WLST.
See below for detailed steps, "Deleting MDS Customizations for adf-config.xml or connections.xml".
Redeploy the EAR file on a new partition or a partition where older customizations are deleted. In either case, all data previously stored in MDS for the application is lost, including any application customizations for adf-config.xml
or connections.xml
, and all user customizations. You must reconfigure your application from scratch too, using Fusion Middleware Control or WLST.
See also, "deleteMetadata" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
Deleting MDS Customizations for adf-config.xml or connections.xml
This section describes how to remove all post-deployment configuration for connections.xml
or adf-config.xml
. This operation cannot be reversed; customizations are permanently removed.
If you do want to delete MDS customizations, Oracle recommends that you use the "exportMetadata
" command to save a copy of the existing files before completing the steps below.
Use the exportMetadata
command to backup connections.xml
and adf-config.xml
.
For example:
exportMetadata(application='webcenter', server='WC_Spaces', toLocation='/tmp/mydata', docs='/META-INF/mdssys/cust/adfshare/adfshare/connections.xml.xml')
exportMetadata(application='webcenter', server='WC_Spaces', toLocation='/tmp/mydata', docs='/META-INF/mdssys/cust/adfshare/adfshare/adf-config.xml.xml')
Delete customizations for connections.xml
, using WLST. For example:
deleteMetadata(application='webcenter', server='WC_Spaces', docs='/META-INF/mdssys/cust/adfshare/adfshare/connections.xml.xml')
Delete customizations for adf-config.xml
, using WLST. For example:
deleteMetadata (application='webcenter', server='WC_Spaces', docs='/META-INF/mdssys/cust/adfshare/adfshare/adf-config.xml.xml')
Restart the WebCenter Portal application.
Reconfigure your application from scratch using Fusion Middleware Control or WLST.
web.xml
is a standard J2EE application deployment descriptor file and it is located in the /META-INF
directory for your application. Typical run-time settings in web.xml
include initialization parameters, custom tag library locations, and security settings.
Most web.xml
properties are fairly static so they are specified for the application at design time. If you need to modify some properties in a deployed environment, you can edit most properties through the "Configure Web Modules" screen on the "Deployment Settings" page. See also, Figure 7-12 in Section 7.1.6.4, "Deploying Applications Using Fusion Middleware Control".
There are very few instances where you might be required to modify web.xml
, for example, if you must change:
Content repository upload parameters: UPLOAD_MAX_MEMORY
, UPLOAD_MAX_DISK_SPACE
, and UPLOAD_TEMP_DIR
. For details, see Section 11.12, "Changing the Maximum File Upload Size".
Note: In the Spaces application, you use the uploadedFileMaxDiskSpace
parameter in webcenter-config.xml
to configure a maximum upload size for files. For details, see Appendix A, "webcenter-config.xml".
Time after which HTTP sessions expire. For details, see Section 39.6, "Tuning Oracle WebCenter Portal Performance".
JSP page timeout value. For details, see Section 39.6, "Tuning Oracle WebCenter Portal Performance".
Unlike connections.xml
and adf-config.xml
, web.xml
does not store post deployment customizations in MDS. Also, you cannot use Fusion Middleware Control or WLST to modify web.xml
in an existing WebCenter Portal application deployment.
If you must modify settings in web.xml
follow the appropriate instructions for your application:
If specific web.xml
properties need to be updated, open the Spaces EAR file, edit web.xml
, and repackage the EAR as follows:
Navigate to your WebCenter Portal Oracle home directory.
Open the Spaces EAR file:
mkdir -p /tmp/my_ear cd /tmp/my_ear jar -xvf $WEBCENTER_HOME/archives/applications/webcenter.ear mkdir war cd war jar -xvf ../spaces.war
Edit WEB-INF/web.xml
and save the changes.
Create a modified .EAR file with the required web.xml
properties.
cd /tmp/my_ear/war jar -cvf ../spaces.war * cd .. rm -rf war jar -cvf ../webcenter.ear *
Copy /tmp/webcenter.ear
to $WEBCENTER_HOME/archives/applications/webcenter.ear
.
Restart the WC_Spaces managed server.
At startup, this automatically deploys the newer application with the modified web.xml
.
Caution:
Future Spaces patches will overwrite this configuration change, so you must remember to repeat such configuration changes after patching, that is, you must obtain the latest webcenter.ear
file and repeat these steps.
Typically, when specific web.xml
properties need to be modified, developers edit web.xml
at design time, and regenerate the application's EAR file to include the new values.
If this is not a viable option, you can open the current application EAR file, edit web.xml
, and repackage/redeploy the EAR as described above for the Spaces application, see Section A.1.2.1, "Editing web.xml Properties for Spaces".
webcenter-config.xml
is a Spaces configuration file containing application-level settings, such as the application name and logo. Most of the properties in this file are managed through Spaces administration screens so there is no need to edit webcenter-config.xml
directly. For more information, see "Accessing Spaces Administration Pages" and "Configuring Global Defaults" in Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.
There are very few instances where you might be required to manually modify settings in webcenter-config.xml
, for example, if you want to change the following:
Maximum file upload size (uploadedFileMaxDiskSpace
) - the default setting is 2 GB.
If you want to modify this setting, you must export the latest version of webcenter-config.xml
from MDS and modify the uploadedFileMaxDiskSpace
value as follows:
Export the latest webcenter-config.xml
from MDS.
For example:
exportMetadata(application='webcenter', server='WC_Spaces', toLocation='/tmp/mydata', docs='/oracle/webcenter/webcenterapp/metadata/mdssys/cust/site/webcenter/webcenter-config.xml.xml')
Note:
webcenter-config.xml.xml
is created in MDS the first time you configure "General" settings through Spaces Administration. If the file does not yet exist in MDS you can edit webcenter-config.xml
directly. The file is located at: /oracle/webcenter/webcenterapp/metadata/webcenter-config.xml
Open webcenter-config.xml.xml
exported from MDS in a text editor and add the following snippet, changing the uploadedFileMaxDiskSpace
value as required:
<mds:replace node="webcenter(xmlns(webcenter=http://xmlns.oracle.com/webcenter/webcenterapp))/webcenter:uploadedFileMaxDiskSpace"/> <mds:insert after="webcenter(xmlns(webcenter=http://xmlns.oracle.com/webcenter/webcenterapp))/webcenter:custom-attributes" parent="webcenter"> <uploadedFileMaxDiskSpace xmlns="http://xmlns.oracle.com/webcenter/webcenterapp">2147483648</uploadedFileMaxDiskSpace> </mds:insert>
Save and close webcenter-config.xml.xml
.
Import the updated webcenter-config.xml.xml
file to MDS.
For example:
importMetadata(application='webcenter', server='WC_Spaces', fromLocation='/tmp/mydata', docs='/oracle/webcenter/webcenterapp/metadata/mdssys/cust/site/webcenter/webcenter-config.xml.xml')
All post deployment configuration through Fusion Middleware Control, WLST, or the Systems MBean Browser is stored as customizations in the MDS repository. In a cluster environment, since the MDS repository is shared across all nodes, all WebCenter Portal configuration changes done on one node are visible to all nodes in the cluster. To effect configuration changes that are not dynamic, all nodes in the cluster must be restarted. See also Section 8.2, "Starting and Stopping Managed Servers for WebCenter Portal Application Deployments".
In WebCenter Portal applications most configuration changes that you make, through Fusion Middleware Control or using WLST, are not dynamic. For example, when you add or modify connection details for WebCenter Portal's services (Analytics, Activity Graph, Announcements, Discussions, Documents, Events, Mail, Instant Messaging and Presence, Search, Worklists) you must restart the application's managed server.There are two exceptions; portlet producer and external application registration is dynamic. Any new portlet producers and external applications that you register are immediately available in your WebCenter Portal application and any changes that you make to existing connections take effect immediately too.
If you edit configuration files in a cluster environment, then you must ensure that identical changes are made in each cluster member so that the overall cluster configuration remains synchronized.
Oracle offers a range of tools for configuring Spaces and other WebCenter Portal application deployments. This section outline which tools are available.
Note:
Most WebCenter Portal configuration parameters are immutable and cannot be changed at run time unless otherwise specified.
Post deployment, always use Fusion Middleware Control or WebLogic Scripting Tool (WLST) commands to review the latest configuration or make configuration changes. In Fusion Middleware Control you will mostly use WebCenter Portal application configuration screens but a useful Systems MBean Browser is also available for reviewing and modifying configuration settings.
For more information about these tools, read:
These tools always show you the current configuration so, typically, there is no need for you to examine or manually change the content of configuration files or MDS customization data for files such as adf-config.xml
or connections.xml
. If you use the same MDS details when you redeploy the application, all configuration performed using these tools is preserved.
What Configuration Tool to Use
You can use any tool for post-deployment configuration. However, if you intend to repeat the configuration steps multiple times, for example, when provisioning newer instances or for automation, screen-based configuration using tools such as Fusion Middleware Control becomes less efficient. In such cases, Oracle highly recommends that you write WLST scripts to perform the required configuration.
All WebCenter Portal configuration operations possible through Fusion Middleware Control are available using WebCenter Portal's WLST commands. You can also use WLST scripts to configure other components, for example, to deploy applications, create managed servers, set MDS properties for an application, configure data sources, and so on. If you want help to automate domain configuration, you can record configuration actions in the WLS Administration Console as a series of WLST commands and then use WLST to replay the commands. For more details on this topic, see "Recording WLST scripts" in Oracle Fusion Middleware Introduction to Oracle WebLogic Server.
Tip:
Where Oracle documentation describes steps in the WLS Administration Console, consider automating the process using the "Record" option.
Another way to configure deployment specific properties is through the WebCenter Portal application's deployment plan. Typical properties changed on deployment include:
Host/port properties for connections
Standard J2EE artifacts in web.xml
See also, Section 7.1.6, "Deploying the Application to a WebLogic Managed Server".
Note:
While reconfiguration is possible this way, any metadata repository and ADF connection configuration changes that you make are not saved as part of the deployment plan, that is, they are saved in the archive that is deployed. Therefore, your configuration changes must be repeated on subsequent redeployments.
If you redeploy your application multiple times, Oracle recommends that you use Fusion Middleware Control or WLST commands to perform your post-deployment configuration. This way, configurations changes are saved in MDS and remain intact on redeployment.