Skip Headers
Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal
10g Release 3 (10.3.2)

Part Number E14245-02
Go to Documentation Home
Go to Table of Contents
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

12 Using the Datasync Web Application

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.


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:



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:

12.1 Portal Datasync Definitions

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.

12.2 Datasync Definition Usage During Development

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.

12.3 Compressed Versus Uncompressed EAR

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.

Figure 12-1 Loading Updated Datasync Files to the Database

Description of Figure 12-1 follows
Description of "Figure 12-1 Loading Updated Datasync Files 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.

12.3.1 Datasync Web Application


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 http://server:port/appNameDataSync. 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.

Figure 12-2 Datasync Web Application Home Page

Description of Figure 12-2 follows
Description of "Figure 12-2 Datasync Web Application Home Page"

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.

Figure 12-3 Browsing the Datasync Repository

Description of Figure 12-3 follows
Description of "Figure 12-3 Browsing the Datasync Repository"

From this list, click on a particular data item to see its contents, as shown in Figure 12-4.

Figure 12-4 Data Item Contents

Description of Figure 12-4 follows
Description of "Figure 12-4 Data Item Contents"

As you can see in Figure 12-4, you can view the XML data for a particular content item.

12.3.2 Removing Content

To remove content from a repository, click the trash can icon on the left side of the page.

12.3.3 Working with a Compressed EAR File

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_APPLICATION, DATA_SYNC_ITEM, DATA_SYNC_SCHEMA_URI, and 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. Uploading new contents

When you click the load data icon, the following page appears, which lets you load data into the database.

Figure 12-5 Uploading New Datasync Data

Description of Figure 12-5 follows
Description of "Figure 12-5 Uploading New Datasync Data"

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." Bootstrapping from an EAR

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. Creating a JAR file

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. Validating Contents

After bootstrapping data, it is a good idea to validate the contents of what you loaded by using the View functionality of the Datasync web application.

12.3.4 Pulling Definitions from Production

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 In order to use it, you must have the following in your CLASSPATH: p13n_ejb.jar, p13n_system.jar, and weblogic.jar.


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.

For example:

set classpath=<WLPORTAL_HOME>\p13n\lib\system\p13n_system.jar;
java help

12.3.5 Options for Connecting to the Server

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.

Option Description Default
-username userid 
User name of a privileged user (an administrator) N/A
-password password 
Password for the privileged user N/A
-app appName@host:port
Application to manage Default = @7001
-url url
URL to DataRepositoryQuery servlet N/A

Only one of -app or -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 http://localhost:7001/datasync/DataRepositoryQuery if datasync.war was deployed with a context-root of datasync.

The -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.

The -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.

12.3.6 Examples

This section lists examples of using the DataRepositoryQuery command.

Assuming CLASSPATH is set as previously described:

Find the application named p13nBase running on localhost port 7001:

java -app p13nBase -username weblogic -password webl0gic

Find the application named p13nBase running on snidely port 7501:

java -app p13nBase@snidely:7501 -username weblogic -password webl0gic

Find the single application running on localhost port 7101:

java -app @7101 -username weblogic -password webl0gic

Find the single application running on snidely port 7001:

java -app @snidely -username weblogic -password webl0gic

Find the single application running on snidely port 7501:

java -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

12.3.7 Usage

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 ftp.

Alternatively, you can supply a single command (and its arguments), and DataRepositoryQuery will run that command and exit.

12.3.8 Commands

The 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:

Command Description
Basic Help
Help on command line options
HELP command
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 or QUIT 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:

Option Description
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 -app mget

12.4 Rules for Deploying Datasync Definitions

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.


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.

12.4.1 Removing Property Sets

When you remove a property set, any existing values being stored locally by WebLogic Portal in the database will NOT be removed automatically. You need to examine the PROPERTY_KEY and PROPERTY_VALUE tables to clean up the data if desired.