Production Operations User Guide
|
 |
 |
|
|
 |
 |
Developing a Propagation Strategy
The steps you take to successfully move a portal configuration from one environment to another depend on many variables. It is impossible to prescribe a single procedure that applies to all circumstances. Therefore, before you attempt to move or propagate a portal application, it is important to plan your strategy, pick the appropriate tools, and develop a set of procedures based on recommended best practices. This chapter explains what you need to consider before you attempt to move or propagate portal assets.
The topics included in this chapter are:
- What is Propagation?
- What Kind of Data Can Be Propagated?
- What Tools Does BEA Provide to Assist with Propagation?
- Choosing the Right Propagation Tool
- Propagation Roadmap
- Assessing Your Portal System Configuration
- General Propagation Scenarios
What is Propagation?
Specifically, propagation refers to moving the database contents of a portal application from one server environment to another. To accomplish this, BEA provides a tool called the Propagation Utility, which is discussed in detail in Inside the Propagation Utility and Using the Propagation Utility. BEA also provides a tool, the Export/Import Utility, for moving portal assets from the database of a staging environment to files that can be imported back into WebLogic Workshop. The Export/Import Utility is described in Using the Export/Import Utility. This utility also lets you move and merge portal assets from a WebLogic Workshop environment to a staging environment's database.
Figure shows the three typical environments between which portal assets are moved.
Figure 6-1 Moving Portals Between Environments
These three environments include:
- Development - In the development environment, a team of developers uses WebLogic Workshop to create portals and portal components, such as portlets.
- Staging - In the staging environment, administrators use the Administration Portal to build and configure portal desktops, create entitlements, and set up content repositories.
- Production - The production environment is the "live" website. In a production environment users access the web application and, optionally, customize it using Visitor Tools. Administrators can also use the Administration Portal to modify the production environment.
What Kind of Data Can Be Propagated?
Generally speaking, a WebLogic Portal application consists of an EAR file, an LDAP repository, and a database. The EAR file contains application code, such as JSPs and Java classes, and portal framework files that define portals, portlets, and datasync data. The embedded LDAP contains security-related data, such as entitlements, roles, users, and groups. The database contains representations of portal framework and datasync elements.
This section divides portal data into four categories, and lists the types of data that fall into each category. The categories include:
- Portal Framework Data - Refers to desktops, books, pages, and other portal framework elements that are created with the WebLogic Administration Portal
- Datasync Data - Refers to definition files, such as user profiles and content selectors that WebLogic Portal allows you to create. Within WebLogic Workshop, these definitions are exposed in the
/datasubdirectory. This data is deployed with the EAR file. If the destination server is running in production mode, datasync data is placed in the database. - Security Data - Refers to security data, such as entitilements and role definitions. This data is generated by administrators using the WebLogic Administration Portal.
- EAR Data - Refers to the final product of WebLogic Workshop development—a J2EE EAR file. The EAR must be deployed to a destination server using the deployment feature of the WebLogic Server Administration Console.
Table 6-1 lists the specific kinds of data that comprise each of these categories.
|
The following delegated administration policies: Note that definitions pertaining to Content Management are not propagated. |
Note: EAR data consists of files that are generated by developers using WebLogic Workshop. If you make a change to EAR data in WebLogic Workshop (for instance, modifying a theme), the only way to move those changes to a staging environment is to redeploy the EAR file. Note, however, that desktops, books, pages that are created in the Administration Portal usually contain references to EAR data. For instance, an administrator can assign a specific theme to a page using the Administration Portal, and a reference to the actual theme file is maintained in the database. When you propagate a desktop to another environment using the Propagation Utility, those references are propagated, but the actual file the reference points to (for example, a .theme file) is not. EAR deployment and the Propagation Utility are described in the following sections.
The following sections discuss the tools that BEA provides for moving portal data between environments.
What Tools Does BEA Provide to Assist with Propagation?
As you develop a propagation strategy, it is important that you know what tools are available to help you propagate a portal from one environment to another. This section introduces the primary tools at your disposal and their purposes.
WebLogic Server Administration Console (EAR Deployment)
Use the WebLogic Server Administration Console to deploy an Enterprise Application's EAR file to a target server. EAR deployment is almost always the first step in any propagation. The EAR file must be redeployed any time changes are made using WebLogic Workshop. For example, if developers add or remove pages from a .portal file, define content selectors, create new portlets and related Java resources (such as JSPs), then the EAR file must be built and deployed to propagate those changes to a new environment.
For detailed information on EAR deployment, see Preparing and Deploying the EAR File.
Propagation Utility
The Propagation Utility guides you through the process of propagating the configuration contents, including portal framework, datasync, and security data, of one portal domain environment to another. For example, the Propagation Utility can play a role whenever you move a portal application from a staging environment to the production environment.
Tip: Before using the Propagation Utility to propagate a portal, always deploy the EAR file in the target environment first.
Features of the Propagation Utility include:
- Exporting portal assets - The tool lets you export the portal assets stored in the portal application's database into an XML file.
- Differencing - The tool lets you view the differences between portal assets in the source application and the target application. For instance, you can tell at a glance if a particular page in a portal was added or removed from the target configuration.
- Importing portal assets - Portal assets that have been exported from a source configuration can be imported into the target. Before importing, you can view the differences between the assets stored in the two configurations. On import, merge decisions are made based on well-defined policies.
- Policies - Policies are well-defined conditions under which source assets will (or will not) be merged into a target configuration. For instance, a policy may state that if an asset exists on the source, but not on the destination, add it to the destination. Another policy may state that if an asset exists on the destination, but not on the source, delete it from the destination. The Propagation Utility allows you to customize the policies that govern these merge operations. For more information on policies, see Creating Policies for Merging Inventory Information.
- Scope - You can set a scope for the propagation. Scopes include Enterprise application, web application, and desktop. For more information on scope, see Setting the Scope.
For detailed information on using the GUI-based Propagation Utility, see Using the Propagation Utility.
Datasync Web Application
Datasync data includes personalization components, such as campaigns, catalog definitions, content selectors, discounts, placeholders, user segments, and user profile definitions. You can find these components in your Enterprise application's /data directory.
Note: You can propagate datasync data using either the Propagation Utility or the Datasync web application; however, the Propagation Utility is usually recommended. The only scenario where you must use the Datasync web application is when you need to propagate campaign data. The Propagation Utility ignores campaign data.
To use the Datasync web application, you must first deploy the EAR file on the destination server. The Datasync web application synchronizes file-based datasync data with the application's database. In other words, the web application pulls datasync data, such as content selector files (.sel files) out of the deployed EAR and merges that data into the database.
For detailed information on datasync data and using the Datasync web application, see Using the Datasync Web Application.
Export/Import Utility
The Export/Import Utility allows you to export desktops, books, and pages from a database to a .portal file. This .portal file can then be opened with WebLogic Workshop by a developer, modified, and then merged back into the database using the Export/Import Utility. Therefore, this utility allows developers to move portal assets in a "round trip" between a development environment and a staging environment, or between development environments.
The utility lets you scope its operations to the following levels:
- Library level - Assets that exist in the Library of the Administration Portal
- Administration level - Assets that exist in desktops created in the Administration Portal
- Visitor level - Asset instances that have been customized by users through Visitor Tools or user customizations
In addition, the utility lets you specify a set of rules to determine how the objects are merged. You can also specify different scoping rules, from the Enterprise Application scope (at the highest level) down to pages within books. This flexibility helps ensure that the user's and administrator's customizations will not be lost when the assets are merged.
For detailed information on the Export/Import Utility, see Using the Export/Import Utility.
Manual Propagation Steps
The propagation tools provided by BEA handle most of the work necessary to move a portal web application from one environment to another. However, there are some manual steps that you may need to perform to ensure a successful migration. In some cases, these steps are required by design. For instance, some security data is intentionally not propagated. Other cases involve known limitations in the tools themselves. For instance, propagation of campaign data and data from the content management system is currently not supported. Whenever possible, these cases are clearly documented and workarounds are discussed.
For detailed information on manual propagation steps, see Making Manual Changes Prior to Propagation.
Database Vendor Tools (Not Supported)
BEA does not support the use of database vendor tools as a means of propagating any WebLogic Portal assets from one database environment to another.
Choosing the Right Propagation Tool
Table 6-2 shows the appropriate propagation tool to use depending on the type of propagation and the specific kinds of changes to propagate. Items in the Changes to Propagate column are defined in What Kind of Data Can Be Propagated?, and the tools listed are summarized in What Tools Does BEA Provide to Assist with Propagation?.
For example, the first row of the table indicates that if you are making an initial deployment from a development to a staging environment, you simply deploy the EAR file.
* See Production Mode vs. Development Mode.
Propagation Roadmap
As you plan your propagation strategy, it is important to develop a roadmap of your system. This section describes the interrelationships between a typical system that includes development, staging, and production environments. The roadmap, Figure 6-2, shows how portals are moved across these environments and the tools that are used to move them.
This section is intended to help you understand not only the connections between the different systems on which portals exist, but the tools and methods used to move or propagate portals between those systems. The numbered parts of the figure are described in detail in the remainder of this section. Please refer to the figure as you read the following sections.
Figure 6-2 Propagation Roadmap
Development Environments
Portal development is typically spread out among members of a team using WebLogic Workshop on individual client machines. Refer to Managing a Team Development Environment for detailed information on setting up a multi-developer portal development environment.
It is important to remember that files are the primary, and often only, product of the IDE-based environment. WebLogic Workshop allows developers to create Java components that are used by portals, such as Java Pageflows, Controls, and JSPs. WebLogic Workshop also lets developers create portlets, portals, look and feels, layouts, and so on. All of these components are stored in files, such as .java, .jsp, .jpf, .jcs, .portal, .pinc, .portlet, .laf, and so on.
Source Control
Development typically occurs in conjunction with a source control system. As explained in Managing a Team Development Environment, a common domain is established for the team, but the web application itself is checked into source control where individual developers can check it out, create and modify files, and check them back into source control. Once built, the EAR file can also be checked into source control.
Managing a Team Development Environment discusses the use of source control in team development environments.
Moving from Development to Staging
When development is complete, an EAR file can be deployed to the staging environment. The easiest way to do this is to use FTP to move the EAR to the staging server, and then to use the WebLogic Server Deployment feature to deploy the EAR into the J2EE server environment. See Preparing and Deploying the EAR File for more details.
Note: It is possible to run the Administration Portal from WebLogic Workshop. Whenever the Administration Portal is used, the output is stored in a database, not in a file. Therefore, if you are in development and use the Administration Portal to create Desktops, users, groups, entitlements, or other administrative features, that information is stored in a database. Assets in the database are not included in the EAR file, and will not be transferred when you move and deploy the EAR.
Tip: The best practice in portal development is to use the WebLogic Administration Portal only in a staging or production environment. If you use the Administration Portal in a development environment, then you must use the Propagation Utility to move the database assets.
Staging Environment
In the staging environment the Administration Portal is used to assemble the portal components that were created in development into desktops, to create users and groups, assign administrative privileges, configure delegated administration rights, modify books and pages, and so on. It is important to remember that anytime you use the Administration Portal to modify a portal, all portal assets from that point on are stored in the database: the connection to the .portal and .pinc, files created in WebLogic Workshop is lost.
Tip: It is possible to return portal assets stored in the database back to files using the Export/Import Utility. To move portal assets to a production environment (database to database), the best practice is to use the Propagation Utility.
For details on the Export/Import Utility, see Using the Export/Import Utility. For details on the Propagation Utility, see Using the Propagation Utility.
Source Control in the Staging Environment
It is a best practice to employ source control in the staging environment. Two components to store in source control are the web application's EAR file and the application's portal-specific assets, or inventory. The easiest way to extract the inventory from a web application is to use the Propagation Utility to export the inventory into a ZIP file.
For details on the Propagation Utility, see Using the Propagation Utility.
Moving to the Production Environment
The Propagation Utility allows you to move a staged portal application to a live production environment.
Note: The Propagation Utility reads the portal inventory ZIP file that was created in staging and reports the differences between the staging inventory and the current production inventory. At this point, you can view these differences and decide whether or not to go ahead with the propagation. Differences can include portal assets that have been added, deleted, or updated. For example, if a page was added to a desktop in staging the Propagation Utility will report that a page was added if it does not exist in the production environment. Similarly, if a page was deleted from the production environment, the Propagation Utility will report that it was deleted and give you the option of adding it back or not (if it still exists on the staging server).
For information on EAR deployment, see Preparing and Deploying the EAR File.
For details on the Propagation Utility, see Using the Propagation Utility.
Assessing Your Portal System Configuration
It is important for each site that deploys WebLogic Portal to develop a strategy for propagating portal applications from one environment to another. When you plan a propagation strategy, it helps to assess carefully the structure of your site and your methods of portal development. Some questions to ask include:
- What is the portal life cycle pattern for your site? Will you be propagating primarily from a development server to a production server, or is there also an intermediate staging/testing environment? For example, in development, developers typically use WebLogic Workshop to create portal assets. In staging and production, administrators use the WebLogic Administration Portal to create and configure portal desktops. In addition, users of the production system can use Visitor Tools to customize portals. Also, extensive testing typically occurs in the staging environment. For an overview of the environments you can propagate to and from, see the previous section, Propagation Roadmap
- What mode is your production server in? For more information on modes, see Production Mode vs. Development Mode.
- Are you deploying your application for the first time, or are you redeploying it? For details, see General Propagation Scenarios.
- If you are redeploying an existing application, what kinds of changes were made to it, and how were they made? Did developers use WebLogic Workshop to modify, create, or remove portal resources (such as adding a new book and pages to a portal, and adding portlets to the pages)? Was your application modified in a staging environment by administrators using the Administration Portal? For details, see General Propagation Scenarios.
- What is the scope of your propagation? Do you wish to propagate the entire Enterprise application, a single web application, or a desktop? For details on scope, see Propagation Scope.
- Do you wish to push a portal from a staging or production environment back to a WebLogic Workshop environment? For information on accomplishing this task, see Using the Export/Import Utility.
- Do you wish to push a portal from a production environment back to a staging environment? This can be accomplished with the Propagation Utility. See Using the Propagation Utility.
- Have you defined entitlements for portal assets, such as portlets? If so, you need to be aware that some security information is by design never propagated by existing BEA tools, and you may need to manually recreate specific user and group definitions on the production server. For information on how security elements are handled during propagation, see Security Information and Propagation.
The next section discusses typical propagation scenarios and the tools and methods that are used in each.
General Propagation Scenarios
After you familiarize yourself with the available propagation tools, the next challenge is to decide when and where to use them. This section presents several general propagation scenarios and offers suggested best practices.
Example Environment
The scenarios outlined in this section assume an environment where there are separate development, staging, and production servers, as shown in Figure .
Figure 6-3 Example of a Portal Development and Production Environment
In a development environment, developers use WebLogic Workshop to create portals and portlets. In this environment, all portal-related data is file-based (stored in XML files, such as .portal and .portlet files). At the completion of development, these file-based assets, including Java and JSP files, configuration files, and datasync files, are assembled and compressed into an EAR file.
A staging environment has been established on a server that is separated from the development environment. The staging server will be used to test the application and to further configure it. In the staging environment, administrators use the Administration Portal to create and arrange portal desktops, entitle portal resources, create users and groups for testing purposes, and so on.
The production environment is the "live" Web site. In this environment, users are accessing and using portal applications. Both administrators and users can make changes to the portal in the production environment. Administrators use the Administration Portal to effect changes, and users use the Visitor Tools to customize their individual portal views.
Scenario 1: Deploying the EAR file for the first time
If you are deploying an EAR file to a server for the first time, the procedure is relatively easy. Typically, developers have used WebLogic Workshop to create portals, portlets, and other application features, and they wish to deploy the new application to a staging server.
For detailed information on deploying an EAR file, see Preparing and Deploying the EAR File.
Note: When you begin using the WebLogic Administration Portal, data stored in the EAR is automatically pulled out of the EAR and stored in the staging server's database. At this point, all subsequent modifications to the portal occur in the database only. Changes are not reflected back into the EAR file.
Scenario 2: Redeploying an EAR file
When redeploying, it is assumed that the target server is a staging or production server. As with the first deployment described previously, the first steps in redeploying are to build the EAR file, move it to the staging server, and use WebLogic Server Console to deploy the EAR on the staging server.
Tip: For detailed information on using WebLogic Server Console to redeploy an application, see Redeploying Applications.
If you are redeploying the application, there are caveats depending on whether the server you are deploying to is in development mode or production mode. Recall that you choose the server's mode when you create the domain. A server in production mode is optimized to run more efficiently than one in development mode.
If the Target Server is in Development Mode
- Any changes made to the EAR file, including datasync data, are automatically detected and deployed to the target server.
- New portlets are automatically detected and moved into the Library of the Administration Portal.
- New Books and Pages added to a portal are not automatically added to the Library. They are added only if you use the Administration Portal to create a new Desktop that uses the new books and pages.
If the Target Server is in Production Mode
- Datasync data is ignored if the EAR is deployed to a server in production mode. See the following section for information on moving the datasync data.
- New portlets are automatically detected and moved into the Library of the Administration Portal.
- New Books and Pages added to a portal are not automatically added to the Library. They are added only if you use the Administration Portal to create a new Desktop that uses the new books and pages.
Moving the Datasync Data
When you redeploy an Enterprise application, you have a choice between deploying an EAR file or an exploded EAR file. The way in which datasync data is handled during deployment depends on (a) whether you deploy an exploded EAR or an EAR file and (b) whether the server is in development mode or production mode. (See also Production Mode vs. Development Mode.)
As Figure 6-4 shows, when you deploy an Enterprise application, datasync data is placed in the /data directory (it is deployed to the filesystem) except in the case where you redeploy an EAR file to a server in production mode. In the later case, you must use either the Propagation Utility or the Datasync web application to move the datasync assets to the target server's database.
Figure 6-4 Where Datasync Data Is Located When You Deploy an Enterprise Application
When you redeploy an EAR file (not an exploded EAR) to a server that is in production mode, you have to propagate the datasync data as a separate operation.
To do this, you have two options:
- Use the Propagation Utility to propagate the database from the source to the target server. The Propagation Utility lets you view the differences between the two environments and automatically handles merging those differences based on configurable policies.
- Use the Datasync Web Application to synchronize the contents of the EAR file with the database.
Tip: The best practice is to always use the Propagation Utility to move datasync data. There are situations, however, where the Datasync Web Application must be used. For example, if the scope of the Propagation Utility is set to the Desktop level, datasync data will not be propagated (datasync data resides at the Enterprise Application level, and so would be out of scope in this case).
Scenario 3: Propagating from Staging to Production: Enterprise Scope
When propagating an Enterprise application from a staging to a production environment, it is assumed that the target server is in production mode. Having the production server in production mode is the best practice. However, nothing prevents a site from running the "live" production server in development mode. Be aware that if the target server is running in development mode, datasync data is automatically moved when the EAR is deployed. If the target is running in production mode, EAR-based datasync data is ignored.
The basic steps for propagating from staging to production environments are:
Note: Typically, the two environments will be out of sync. It is possible that changes were made to both the production and staging servers since the previous propagation. See the section Scenario 5: Propagating from Production to Staging: Both Have Changed.
Tip: Be aware that users and groups, by design, are not propagated by the Propagation Utility. Therefore, typically, items such as groups (which contain users) must be manually recreated on the production server (Although, if the staging and production servers share the same LDAP directory, and this authentication information is stored in LDAP, it is not necessary to recreate the users and groups.). For more information on LDAP propagation, see Security Information and Propagation.
Scenario 4: Propagating from Staging to Production: Desktop Scope
If you do not wish to propagate the entire Enterprise application, you can adjust the scope. For example, you can use the Propagation Utility to propagate only a desktop. In this case, you must be aware that datasync data will not be propagated because it resides at the Enterprise application scope, and is not included in the Desktop scope. Therefore, you need a strategy for propagating datasync data in this circumstance.
The basic steps for propagating with Desktop scope are the same as Enterprise scope, described in the previous section.
Tip: It is recommended as a best practice to initially scope to the Enterprise application level, and then to the desktop level.
To propagate the datasync data outside of the Desktop scope, use the Datasync web application. The recommended method for accomplishing this is to place the new datasync files in a JAR file and move the JAR file to the production server. Then, run the Datasync web application on that JAR file. The Datasync web application will insert, or bootstrap, the specified files into the production server's database. For more information on using the Datasync web application, see Using the Datasync Web Application.
Scenario 5: Propagating from Production to Staging: Both Have Changed
It is sometimes necessary to return a production environment configuration to a staging environment. Typically, this allows administrators and developers to add new features and fix known problems. The problem associated with this propagation is that both administrative and user customizations could have been made to the production system. For instance, an administrator may have added a new desktop, or removed a page. A user may have customized her individual view of a portal using Visitor Tools.
To complicate the scenario, additional development and customization may have occurred in the staging environment since the application was last propagated. The problem, then, is to identify the differences between the two environments and, decide which changes to keep and which to remove.
The Propagation Utility reports differences between the source and target environments. While the Propagation Utility policies allow you to set rules for merging portal assets, it is up to you to review the differences and verify that the changes you intend to make to the target are made.
Note: User customizations are not propagated, but they are preserved on the destination. The Propagation Utility modifies or removes user customizations on the destination server only under certain circumstances, such as if another change causes a conflict. For example, if a user customizes a portlet, but the portlet is deleted, the user customizations that reference the deleted portlet will be removed. For more information see User Customizations and Propagation.
Tip: If you make a change to the staging environment using the Administration Portal, the changes you make are saved in the database if the EAR file is compressed. If the EAR is uncompressed (exploded) changes are written to the filesystem. If you redeploy the EAR file at a later time, you must be sure to propagate datasync elements that have been changed. You can use the Propagation Utility or the Datasync Web Application to move datasync data. For more information, see Datasync Web Application and Production Mode vs. Development Mode.
Scenario 6: Round-Trip Development
The Export/Import Utility allows you to propagate desktops, books, and pages back and forth between development (WebLogic Workshop) and staging environments. Propagating from development to staging and back to development is called a round trip.
The Export/Import Utility exports desktops, books, and pages from the staging database to .portal and .pinc files that can be read into WebLogic Workshop. The utility also allows you to import .portal and .pinc files into a staging database. You can set the scope of imports and exports to the library, desktop, or visitor level.
Warning: When a new asset, such as a new book or page, is created in the Administration Portal, a unique identifier is generated for that asset. It is a best practice to avoid changing these definition labels once they have been propagated (or moved with the Export/Import Utility) for the first time. If you change a resource's definition label, the Export/Import Utility views the resource as a new resource rather than an updated resource. As a result, the Export/Import Utility will perform an add operation rather than an update operation.
Tip: An important feature of the Export/Import Utility is that it allows you to merge file-based assets from the development environment into a database-based staging environment. In other words, if you export an application to a file-based development environment, and then make changes in the development environment, you can use the Export/Import Utility to merge those changes back into the database of the staging environment.
Production Mode vs. Development Mode
When you configure a domain, you are given a choice between a development mode and a production mode. As a best practice, it makes sense for the production (live) environment to be in production mode because it runs more efficiently; however, some sites run their live production servers in development mode. Knowing the server's mode is important for understanding how certain portal assets are propagated. For instance, when you deploy an EAR file to a server that is in production mode, datasync data is ignored.
