Production Operations User Guide
|
 |
 |
|
|
 |
 |
Using the Datasync Web Application
This chaper provides instructions for updating portal application datasync data, such as user profile properties, user segments, content selectors, campaigns, discounts, and other property sets, which must be bootstrapped to the database in a separate deployment process.
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 Creating a Production Cluster Environment with the Configuration Wizard.
This chapter includes the following topics:
- Portal Datasync Definitions
- Datasync Definition Usage During Development
- Compressed Versus Uncompressed EAR
- Rules for Deploying Datasync Definitions
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 WebLogic Workshop, portal definitions are created in a special datasync project, exposed in the WebLogic Workshop Application window as a /data subdirectory. (On the filesystem, the directory exists in the application's /META-INF/data directory.) This project can contain user profile property sets, user segments, content selectors, campaigns, discounts, catalog property sets, event property sets, and session and request property sets.
Datasync Definition Usage During Development
During development, all files created in the datasync project are stored in the META-INF/data directory of the portal application and exposed in WebLogic Workshop in the portalApplication/data directory. To provide optimim 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 WebLogic Workshop developers, but also by business users and portal administrators, who can modify user segments, campaigns, placeholders, and content selectors with the Weblogic Administration Portal. In the development environment, both WebLogic Workshop and the WebLogic Administration Portal write to the files in the META-INF/data directory.
Compressed Versus Uncompressed EAR
When deployed into a production system, portal definitions often need to be modifiable using the Weblogic Administration Portal. 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 filesystem into the database so the application can be updated.
Figure 10-1 shows how the /data directory from the updated portal application is put into a standalone JAR and bootstrapped to the database.
Figure 10-1 Loading Updated Datasync Files to the Database
Alternatively, some production environments deploy their portal applications as uncompressed EARs. In this case, the deployed portal application on the administration server is the primary store of datasync definitions. Work done in the WebLogic Administration Portal on any managed server is automatically synchronized with the primary store.
For both compressed and uncompressed EAR files, you can view and update datasync definitions using the Datasync Web Application.
Datasync Web 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 10-2.
Figure 10-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 
icon to bring up the window shown in Figure 10-3.
Figure 10-3 Browsing the Datasync Repository
From this list, click on a particular data item to see its contents, as shown in Figure 10-4.
Figure 10-4 Data Item Contents
As you can see in Figure 10-4, you can view the XML data for a particular content item.
Removing Content
To remove content from a repository, click the trash can icon on the left side of the page.
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 10-4, Data Item Contents, on page 10-6.
Uploading new contents
When you click the 
icon, the following page appears, which lets you load data into the database.
Figure 10-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, 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.
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, 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: p13n_ejb.jar, p13n_system.jar, and weblogic.jar.
Run the class with the argument help to print basic usage help.
set classpath=c:\bea\weblogic81\p13n\lib\p13n_system.jar;
c:\bea\weblogic81\p13n\lib\p13n_ejb.jar;
C:\bea\weblogic81\server\lib\weblogic.jar
java com.bea.p13n.management.data.DataRepositoryQuery help
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 BEA. In real deployments, the options will be necessary.
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.
Examples
This section lists examples of using the DataRepositoryQuery command.
Assuming CLASSPATH is set as previously described, and the default username/password of weblogic/weblogic is valid):
Find the application named p13nBase running on localhost port 7001:
java com.bea.p13n.management.data.DataRepositoryQuery -app p13nBase
Find the application named p13nBase running on snidely port 7501:
java com.bea.p13n.management.data.DataRepositoryQuery -app p13nBase@snidely:7501
Find the single application running on localhost port 7101:
java com.bea.p13n.management.data.DataRepositoryQuery -app @7101
Find the single application running on snidely port 7001:
java com.bea.p13n.management.data.DataRepositoryQuery -app @snidely
Find the single application running on snidely port 7501:
java com.bea.p13n.management.data.DataRepositoryQuery -app @snidely:7501
In each of the examples, the first line of output will be something like this:Using url: http://snidely:7001/myApp/datasync/DataRepositoryQuery
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.
Commands
The HELP command gives you help on the commands you can use. Or use HELP command to get help on a specific command.
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:
The following example retrieves all assets from the repository as files:
java com.bea.p13n.management.data.DataRepositoryQuery -app mget
Working with an Uncompressed EAR File
When working with a production server with an uncompressed EAR, the only difference from development mode is that there is no poller thread.
When updating definition files using the WebLogic Administration Portal, the files are updated on the administration server in the deployed uncompressed EAR directory automatically. This means that the WebLogic Administration Portal can be used from any managed server in the cluster, but the primary store always resides on the administration server. If the deployable EAR directory is read-only, the WebLogic Administration Portal cannot be used to modify files.
Making sure you are not overwriting files - When working with an uncompressed EAR file in production, special care needs to be taken when working with definition files. When you redeploy your application to your production environment, the existing definition files are replaced. If you have administrators updating definitions using the WebLogic Administration Portal, their changes will be lost upon redeploying an updated application.
Copying back to development - To prevent overwriting any changes done by administrators to definition files when redeploying a new portal application, you must first copy all the definition files from the administration server back to development manually or using the Datasync web application.
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.
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 Administration Portal 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 WebLogic Workshop at development time rather than in the WebLogic Administration Portal.
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.
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.
