|Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal
10g Release 3 (10.3.4)
Part Number E14245-03
This chapter provides instructions for updating portal application datasync data, such as user profile properties, user segments, content selectors, campaigns, and other property sets, which must be bootstrapped to the database in a separate deployment process.
Note:The Datasync Web Application is deprecated. It is recommended that you use the propagation tools to propagate datasync data. If you want to use the Datasync Web Application in a browser, you need to add the following WAR file to your application:
Note:In a WebLogic Portal cluster where the Managed Servers are running on different computers than the Administration Server, the ListenAddress attribute of each Managed Server must be set to its own IP address or DNS name; this allows datasync to propagate updates throughout the cluster. Setting the cluster addresses to DNS addresses is covered in the WebLogic Server document "Setting Up WebLogic Clusters" at
This chapter includes the following topics:
WebLogic Portal allows you to author a number of definition files, such as user profiles and content selectors, that must be managed carefully when moving from development to production and back.
Within Oracle Enterprise Pack for Eclipse, portal definitions are created in a special datasync project. This project can contain user profile property sets, user segments, content selectors, campaigns, event property sets, and session and request property sets.
During development, all files created in the datasync project are stored in a datasync project. To provide optimum access from runtime components to the definitions, a datasync facility provides an in-memory cache of the files. This cache intelligently polls for changes to definitions, loads new contents into memory, and provides listener-based notification services when content changes, letting developers preview datasync functionality in the development environment.
Datasync definition modifications are made not only by Oracle Enterprise Pack for Eclipse developers, but also by business users and portal administrators, who can modify user segments, campaigns, placeholders, and content selectors with the WebLogic Portal Administration Console. In the development environment, both Oracle Enterprise Pack for Eclipse and the WebLogic Portal Administration Console write to the files in the datasync project directory.
When deployed into a production system, portal definitions often need to be modifiable using the WebLogic Portal Administration Console. In most production environments, the portal application will be deployed as a compressed EAR file, which limits the ability to write modifications to these files. In a production environment, all datasync assets must be loaded from the file system into the database so the application can be updated.
Figure 12-1 shows how the
/data directory from the updated portal application is put into a standalone JAR and bootstrapped to the database.
Alternatively, some production environments deploy their portal applications as uncompressed EARs.
For both compressed and uncompressed EAR files, you can view and update datasync definitions using the Datasync Web Application.
Note:If you want to use the Datasync Web Application in a browser, you need to add the following WAR file to your application:
Each portal application contains a Datasync Web Application located in
datasync.war in the application root directory. Typically, the URL to the Datasync web application is
DataSync. For example, http://localhost:7001/portalAppDataSync. You can also find the URL to your Datasync web application by loading the WebLogic Server Administration Console and selecting Deployments > Applications > appName > *DataSync and clicking the Testing tab to view the URL.
The Datasync web application allows you to view the contents of the repository and upload new content, as shown in Figure 12-2.
Working with the Repository Browser – When working with the Data Repository Browser, you have the option to work with all the files in the repository using the icons on the left hand side of the page, or drill down into a particular sub-repository, such as the repository that contains all Property Set definitions.
View Contents – To view the contents of a repository, click on the binoculars icon to bring up the window shown in Figure 12-3.
From this list, click on a particular data item to see its contents, as shown in Figure 12-4.
As you can see in Figure 12-4, you can view the XML data for a particular content item.
To remove content from a repository, click the trash can icon on the left side of the page.
When the application is deployed, if the JDBC Repository is empty (contains no data), then the files in the EAR will be used to bootstrap (initialize) the database. The Datasync assets are stored in the following tables:
DATA_SYNC_VERSION. The bootstrap operation by default happens only if the database is empty. When you want to do incremental updates, the Datasync web application provides the ability to load new definitions directly into the database. This can be done as part of redeploying a portal application, or independently using a special JAR file that contains your definitions, as shown in Figure 12-4.
When you click the load data icon, the following page appears, which lets you load data into the database.
When you bootstrap, you choose a bootstrap source, which is either your deployed portal application or a stand-alone JAR file. For example, if you have an updated portal application that you have redeployed to your production environment, you can add any new definitions it contains to your portal. Alternatively, if you have authored new definitions that you want to load independently, you can create a JAR file with only those definitions and load them at any point.
Either way, when you update the data repository, you can choose to "Overwrite ALL data in the Master Data Repository," "Bootstrap only if the Mastery Repository is empty," or "Merge with Master Data Repository–latest timestamp wins."
If you are redeploy an existing EAR application and want to load any new definitions into the database, choose the Application Data (META-INF/data) as your bootstrap source, and then choose the appropriate Bootstrap Mode. To ensure that you do not lose any information, you may want to follow the instructions in the section entitled, Section 12.3.4, "Pulling Definitions from Production" to create a backup first. It is not possible to bootstrap definition data from an EAR file that is not deployed.
To bootstrap new definition files independently of updates to your portal application, you can create a JAR file that is loaded onto the server that contains the files (content selectors, campaigns, user segments, and so on) that you want to add to the production system.
To do this, you can use the jar command from your
META-INF/data directory. For example:
jar -cvf myfiles.jar *
This example will create a JAR file called
myfiles.jar that contains all the files in your data directory, in the root of the JAR file. Then, you can bootstrap information from this JAR file by choosing Jar File on Server as your data source, specifying the full physical path to the JAR file and choosing the appropriate bootstrap mode. By running this process you can upgrade all the files that are packaged in your JAR. Controlling the contents of your JAR allows you to be selective in what pieces you want to update.
When creating the JAR file, the contents of the
META-INF/data directory should be in the root of the JAR file. Do not jar the files into a
META-INF/data directory in the JAR itself.
Developers and testers may be interested in bringing datasync definitions that are being modified in a production environment back into their development domains. As the modified files are stored in the database, WebLogic Portal provides a mechanism for exporting XML from the database back into files.
One approach is to use the browse capability of the Datasync web application to view all XML stored in the database in a web browser. This information can then be cut and pasted into a file.
A better alternative is to use the DataRepositoryQuery Command Line Tool, which allows you to fetch particular files from the database using an FTP-like interface.
The DataRepositoryQuery Command Line Tool supports a basic, FTP-style interface for querying the data repository on a server.
The command line class is
com.bea.p13n.management.data.DataRepositoryQuery. In order to use it, you must have the following in your CLASSPATH:
Note:You can obtain p13n_ejb.jar by copying it from <WLPORTAL_HOME>/p13n/lib/j2ee-modules/p13n-app-lib.ear to a location on your system.
Run the class with the argument
help to print basic usage help.
set classpath=<WLPORTAL_HOME>\p13n\lib\system\p13n_system.jar; <FILE_PATH>\p13n_ejb.jar; <WEBLOGIC_HOME>\server\lib\weblogic.jar java com.bea.p13n.management.data.DataRepositoryQuery help
Several optional command arguments are used for connecting to the server. The default values are probably adequate for samples provided by Oracle. In real deployments, the options will be necessary.
|User name of a privileged user (an administrator)||N/A|
|Password for the privileged user||N/A|
|Application to manage||Default = @7001|
Only one of
-url may be used, as they represent two alternate ways to describe how to connect to a server.
The URL is the most direct route to the server, but it must point to the
DataRepositoryQuery servlet in the Datasync web application. This servlet should have the URI of
DataRepositoryQuery, but you also need to know the hostname, port, and the
context-root used to deploy
datasync.war in your application. So the URL might be something like
datasync.war was deployed with a
-app option allows you to be a bit less specific. All you need to know is the hostname, port number, and the name of the application. If there is only one
datasync.war deployed, you do not even need to know the application name. The form of the
-app description is
appname@host:port, but you can leave out some pieces if they match the default of a single application on localhost port 7001.
-app option can be slow, as it has to perform many queries to the server, but it will print the URL that it finds, so you can use that with the
-url option on future invocations.
This section lists examples of using the
CLASSPATH is set as previously described:
Find the application named p13nBase running on localhost port 7001:
java com.bea.p13n.management.data.DataRepositoryQuery -app p13nBase -username weblogic -password webl0gic
Find the application named p13nBase running on snidely port 7501:
java com.bea.p13n.management.data.DataRepositoryQuery -app p13nBase@snidely:7501 -username weblogic -password webl0gic
Find the single application running on localhost port 7101:
java com.bea.p13n.management.data.DataRepositoryQuery -app @7101 -username weblogic -password webl0gic
Find the single application running on snidely port 7001:
java com.bea.p13n.management.data.DataRepositoryQuery -app @snidely -username weblogic -password webl0gic
Find the single application running on snidely port 7501:
java com.bea.p13n.management.data.DataRepositoryQuery -app @snidely:7501 -username weblogic -password webl0gic
In each of the examples, the first line of output will be something like this:
Using url: http://snidely:7001/myApp/datasync/DataRepositoryQuery
The easiest way to use the tool is in shell mode. To use this mode, invoke
DataRepositoryQuery without any arguments (other than those needed to connect as described previously).
In this mode, the tool starts a command shell (you will see a
drq> prompt) where you can interactively type commands, similar to how you would use something like
Alternatively, you can supply a single command (and its arguments), and
DataRepositoryQuery will run that command and exit.
HELP command gives you help on the commands you can use. Or use
HELP command to get help on a specific command.
The available commands are:
|Help on command line options|
|Help on a specific command|
|Help on wildcards that can be used with URI arguments|
LIST [-l] [uri(s)]
|List available data items|
INFO [-l] [-d]
|Print repository info|
|Print a data item (the xml)|
GET [-f] uri [filename]
|Retrieve a data item to a file|
MGET [-f] [uri(s)]
|Retrieve multiple data items as files. Not specifying a URI retrieves all files.|
||Exit the shell (shell only)|
Commands are not case-sensitive, but arguments such as filenames and data item URIs may be. More help than what is listed above can be obtained by using
HELP command for the command you are interested in.
Where multiple URIs are allowed (indicated by
uri(s) in the help), you can use simple wildcards, or you can specify multiple URIs. The result of the command includes all matching data items.
Options in square brackets (
) are optional and have the following meanings:
|Output a longer, more detailed listing|
|Include URIs of data items contained in each repository|
|Force overwrite of existing files|
The following example retrieves all assets from the repository as files:
java com.bea.p13n.management.data.DataRepositoryQuery -app mget
There are a number of general concepts to think about when iteratively deploying datasync definitions into a production system. In general, adding new datasync definitions to a production system is a routine process that you can do at any time. However, removing or making destructive modifications to datasync definitions can have unintended consequences if you are not careful.
When removing or making destructive modifications to datasync definitions, you should first consider whether there are other components that are linked to those components. There are several types of bindings that might exist between definitions.
Note:For some of these bindings, it is very important to understand that they may have been defined on the production server using the WebLogic Portal Administration Console and may not be known by the developers.
One example of bindings is that you may have two datasync definitions bound together. An example of this is a campaign that is based on a user property defined in a user property set. If you remove the property set or the specify property, that campaign will no longer execute properly. In this case, you should update any associated datasync definitions before removing the property set or property.
A second scenario is that you have defined an entitlement rule that is bound to a datasync definition. For example, you might have locked down a portlet based on a dynamic role that checks if a user has a particular user property value. In this case, you should update that dynamic role before removing the property set or property.
A third scenario is that there are in-page bindings between datasync items and Portal JSP tags. An example is a
<pz:contentSelector> tag that references a content selector. Update the content selector tag in the production environment before you remove the content selector. This is one type of binding that is only configured in Oracle Enterprise Pack for Eclipse at development time rather than in the WebLogic Portal Administration Console.
A good guideline for developers is not to remove or make significant changes to existing datasync definitions that are in production. Instead, create new definitions with the changes that are needed. This can be accomplished by creating new versions of, for example, campaigns where there is no chance that they are being used in unanticipated ways. Additionally, perform datasync bootstraps of the production system's existing datasync definitions back into development on a regular basis.