|
|
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:
Specifically, propagation refers to moving the database contents of a portal application from one server environment to another. To accomplish this, Oracle provides these tools:
Each of these utilities are discussed further in the following section, What Tools Does Oracle Provide to Assist with Propagation?.
Figure 5-1 shows the three typical environments between which portal assets are moved.
These three environments include:
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.
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 Workshop for WebLogic. 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 Deploying Portal Applications.
Workshop for WebLogic provides tools that guide 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, you can create a Propagation Session to move a portal application from a staging environment to the production environment.
| Tip: | Before propagating a portal, always deploy the EAR file in the target environment first. |
Features of the propagation tools include:
For detailed information on using the Workshop for WebLogic propagation tools, see Using Workshop for WebLogic Propagation Tools.
Instead of using Workshop for WebLogic to propagate a portal, you can use Ant tasks to create customized propagation scripts. In many cases, task based propagation provides an even greater measure of control over your propagation than is provided by Workshop for WebLogic. For detailed information on the Ant tasks, see Using the Propagation Ant Tasks and Propagation Ant Task Reference.
The propagation tools provided by Oracle 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 automatically propagated by the tools.
For detailed information on manual propagation steps, see Make Required Manual Changes.
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 Workshop for WebLogic, modified, and then merged back into the database using the Export/Import Utility. 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:
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.
Oracle does not support the use of database vendor tools as a means of propagating any WebLogic Portal assets from one database environment to another.
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, datasync elements, and content management data used by the portal runtime.
This section divides portal data into four categories, and lists the types of data that fall into each category. The categories include:
Table 5-1 lists the specific kinds of data that comprise each of these categories.
| Note: | EAR data consists of files that are generated by developers using Workshop for WebLogic. If you make a change to EAR data in Workshop for WebLogic (for instance, modifying a theme), the only way to move those changes to another environment is to redeploy the EAR file. Note, however, that desktops, books, pages that are created in the WebLogic Portal Administration Console usually contain references to EAR data. For instance, an administrator can assign a specific theme to a page using the WebLogic Portal Administration Console, and a reference to the actual theme file is maintained in the database. When you propagate a desktop to another environment using the propagation tools, those references are propagated, but the actual file the reference points to (for example, a .theme file) is not. EAR deployment and the propagation tools are described in the following sections. |
The following sections discuss the tools that WebLogic Portal provides for moving portal data between environments.
Table 5-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 Oracle 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 (Workshop for WebLogic) environment to a staging environment, you simply deploy the EAR file. However, on redeployment, you need to also use the propagation tools to move datasync data to the target (see also Moving the Datasync Data).
* It is a best practice to always run staging and production servers in production mode. See also Production Mode Versus Development Mode.
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 5-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.
Development Environments
Portal development is typically spread out among members of a team using Workshop for WebLogic 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. Workshop for WebLogic allows developers to create Java components that are used by portals, such as Java Pageflows, Controls, and JSPs. Workshop for WebLogic 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, .page, .book, .portlet, .laf, and others.
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.
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 Deploying Portal Applications for more details.
| Note: | It is possible to run the Administration Console from Workshop for WebLogic. Whenever the Administration Console is used, the output is stored in a database, not in a file. Therefore, if you are in development and use the Administration Console 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. If you use the Administration Console in a development environment, then you must use the propagation tools to move the database assets to the staging environment. |
Staging Environment
In the staging environment the WebLogic Portal Administration Console 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 WebLogic Portal Administration Console to modify a portal, all portal assets from that point on are stored in the database: the connection to the original .portal and other files created in Workshop for WebLogic is lost.
| Tip: | It is possible to return portal framework 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 Workshop for WebLogic propagation tools or Ant tasks. |
For details on the Export/Import Utility, see Using the Export/Import Utility. For details on the propagation tools, see Using Workshop for WebLogic Propagation Tools.
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. You can extract the inventory from a web application using the Workshop for WebLogic based propagation tools or the propagation Ant tasks to export the inventory into a ZIP file.
For details on the propagation tools, see Using Workshop for WebLogic Propagation Tools. For details on the propagation Ant tasks, see Propagation Ant Task Reference.
Perform Offline Tasks
You work with exported inventories offline. That is, you work with them directly on the filesystem, with no connection to the source or destination server. The offline tasks include creating a merged inventory, viewing and tuning the merged inventory, and combining the merged inventory into a final inventory.
| Note: | At this point, you can view the differences between the source and destination inventories (the merged view) 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 tools 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 tools 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). |
Before you can perform offline tasks, you need to download a source and a destination inventory. When you finish the offline tasks, you upload the final inventory to the destination system. You can upload and download inventories using the OnlineUploadTask and OnlineDownloadTask Ant tasks or use the Import and Export features in Workshop for WebLogic.
Committing the Final Inventory
After you have uploaded the final inventory to the destination server, you must commit it. You can use the OnlineCommitTask Ant task to commit the final inventory, or use the Export feature in Workshop for WebLogic.
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:
The next section discusses typical propagation scenarios and the tools and methods that are used in each.
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.
The scenarios outlined in this section assume an environment where there are separate development, staging, and production servers, as shown in Figure 5-3.
In a development environment, developers use Workshop for WebLogic 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 Console 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 Console to effect changes, and users use the Visitor Tools to customize their individual portal views.
If you are deploying an EAR file to a server for the first time, the procedure is relatively easy. Typically, developers have used Workshop for WebLogic 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 Deploying Portal Applications.
| Note: | When a WLP EAR file is deployed to the server, certain data stored in the EAR is automatically pulled out of the EAR and stored in the destination server’s database. At this point, all subsequent modifications to the portal made using the WLP Administration Console occur in the database only. Changes are not reflected back into the EAR file. |
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 to a Staging or Production Environment. |
When you redeploy 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. The caveats are explained in the following sections.
.book and .page files that you add to your portal project. The way in which datasync data is handled during deployment depends on whether the server is in development mode or production mode. (See also Production Mode Versus Development Mode.)
As Table 5-3 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 latter case, use appropriate WebLogic Portal propagation tools to move the datasync assets to the target server’s database.
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, use the propagation tools to propagate the database from the source to the target server. The propagation tools let you view the differences between the two environments and automatically handle merging those differences based on configurable policies.
When propagating a portal application that is scoped to the highest level (enterprise scope) from a staging to a production environment, it is assumed that the target server is in production mode. In this case, everything that can be propagated is propagated.
| Tip: | For detailed information on scoping an inventory, see Scoping an Inventory. |
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 redeployed. 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. 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. |
If you do not wish to propagate the entire enterprise application, you can adjust the scope. For example, you can use the propagation tools to propagate only a desktop. In this case, you must be aware that certain data will not be propagated because it resides at the Enterprise application scope and is not included in the propagation that is scoped to the desktop level. This includes datasync data and content management data. Therefore, you need to propagate the datasync and content management data separately in this circumstance using the propagation tools.
| Tip: | For detailed information on scoping an inventory, see Scoping an Inventory. |
The basic steps for propagating an inventory that is scoped to the desktop level are the same as enterprise scope, described in the previous section.
| Note: | It is recommended as a best practice to scope to the Enterprise application level for the first propagation, and then for subsequent propagations, to scope to something more granular than the application level, such as the desktop level. |
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 tools report differences between the source and target environments. While the propagation 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. Changes introduced through the propagation tools have the same impact on user customizations as similar changes made through the WebLogic Portal Administration Console. For more information see User Customizations and Propagation. |
| Tip: | If you make a change to the staging environment using the WebLogic Portal Administration Console, 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. To do this, use the propagation tools. For more information, see Production Mode Versus Development Mode. |
The Export/Import Utility allows you to propagate desktops, books, and pages back and forth between development (Workshop for WebLogic) 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, .book, and .page files that can be read into Workshop for WebLogic. The utility also allows you to import .portal, .book, and .page 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 Console, 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. |
Figure 5-4 shows the definition label for a page, displayed in the Properties view in Workshop for WebLogic.
| 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. |
When you configure a domain, you are given a choice between Development mode and Production mode.
| Tip: | As a best practice, always run staging (testing) and production (live) environments in production mode. For developers using Workshop for WebLogic, the best practice is to run the server 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. See Scenario 2: Redeploying an EAR file.
Proliferation refers to the process by which changes made to the Library instance of a portal asset are pushed into user-customized instances of that asset. For example, if a portal administrator deletes a portlet from a desktop, that change must be reflected into user-customized instances of that desktop. Before you propagate a portal, consider the way in which proliferation is configured for your portal.
If your desktops include a large number of user customizations, we recommend that you change the Portal Resources Proliferation of Updates Configuration setting to either Asynchronous or Off. This change reduces the amount of time required to complete the propagation.
You can do this in the WebLogic Portal Administration Console under Configuration Settings > Service Administration > Portal Resources > Portal Resources Proliferation of Updates Configuration. The proliferation settings include Asynchronous, Synchronous, or Off.
|