Production Operations Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Using Workshop for WebLogic Propagation Tools

This chapter explains how to use Workshop for WebLogic propagation tools to propagate a WebLogic Portal. Workshop for WebLogic provides propagation tools that guide you through the process of downloading and uploading portal inventories, merging portal inventories, setting scopes and policies, and committing a final inventory. If you would like to explore a more programmatic, automated approach to propagation, see Using the Propagation Ant Tasks.

Tip: Before reading this chapter, we recommend that you review Developing a Propagation Strategy and Propagation Topics.

This chapter includes these topics:

 

Overview

Workshop for WebLogic provides a set of tools that let you perform a complete portal propagation. The tools provided in the Workshop for WebLogic Propagation let you:

Workshop for WebLogic lets you merge inventory files, graphically depicts this merged inventory, and highlights the artifacts that have been added, removed, or updated during the merge. You then have a chance to tune the merged inventory and produce a final inventory file that you can upload to a destination server.

Tip: All of the propagation features that are available in Workshop for WebLogic are also available through the propagation Ant tasks. The Ant tasks offer a programmatic approach to propagation and offer additional features, such as the ability to place the server in maintenance mode, that are not offered in Workshop for WebLogic. See Using the Propagation Ant Tasks for more information.

Propagating a portal using Workshop for WebLogic involves these major steps. Each step is explained in this chapter.

  1. Use the import feature to download portal inventory files from the source and destination systems.
  2. Use the Propagation Session wizard to create a propagation project, import source and destination inventory files, and create a merged inventory file.
  3. Use the Propagation Perspective to view and tune the merged inventory file. This perspective provides a graphical view of your merged inventory, highlighting additions, deletions, and updates, and allowing you to make changes before generating the final merged inventory.
  4. Create a final merged inventory file.
  5. Upload and commit the final merged inventory file to the destination server.

 

Overview of the Propagation Perspective

Workshop for WebLogic provides a Propagation perspective which provides views for viewing and editing inventory files. This section introduces the Propagation perspective.

Figure 7-1 shows an example Propagation Perspective. The numbered areas are described briefly below the figure.

Figure 7-1 Example Propagation Perspective

Example Propagation Perspective

1. Navigator – Shows the contents of the propagation session, including source and destination files, merged inventory files, and properties files.

2. Merged Inventory/Inventories – This view lets you switch between a hierarchical representation of the merged inventory file or the source and destination inventories. To switch between these two views, click the Merged or the Inventories tab below the view.

3. Propagation Impact – This view shows you the inventory nodes that are affected when you modify a merged inventory file. For instance, if you deselect a node in the merged inventory, to remove it from the propagation scope, the Propagation Impact view highlights nodes that are dependent on the deleted node.

4. Outline – This view lets you view and navigate the portal inventory.

5. Properties – The Properties view displays information about the selected inventory node. This view also lists the policy that applies to the node and any manual changes that will be required if the policy is applied.

6. Propagation Dependencies – This view shows you assets upon which the selected asset depend. Removing any of the dependent assets will make the selected asset invalid.

7. Propagation Dependents – This view shows you the assets that depend on the selected asset. If you remove the selected asset, these dependent assets will become invalid.

 

Downloading an Inventory File

This section explains how to download a portal inventory file from a server. To propagate a portal, you need to download the source and the destination inventories, combine them, and then upload and commit the final combined inventory.

Note: This operation extracts the portal inventory and attempts to write it to a ZIP file. If the ZIP file created exceeds 4 GB, this operation fails and a message is written to the server log and the verbose log. If this occurs, try scoping your inventory to limit the size of the resulting archive file. See Understanding Scope for more information.
Tip: You can also use the OnlineDownloadTask Ant task to download an inventory file. See Propagation Ant Task Reference for more information.
  1. Select File > Import.
  2. In the Import – Select dialog, select Propagation Inventory from Server, as shown in Figure 7-2, and click Next.
    3. Figure 7-2 Import – Select Dialog


    Import – Select Dialog

  3. In the Import Inventory from Server dialog, complete the Server URL, Username, and Password fields. The server URL is the URL of the propagation servlet that is deployed on the target server. This URL is formed as follows:
    4. http://servername:portnumber/earProjectNamePropagation/inventorymanagement

    Where earProjectName is the name of the EAR project that contains the portal application that you are propagating. For example: myEARProjectPropagation. For example: 

    http://localhost:7001/myEARProjectPropagation/inventorymanagement
    Tip: The propagation servlet is deployed, by default, in all WebLogic Portal EAR projects. This servlet enables communication with remote propagation clients, such as the Workshop for WebLogic propagation tools and Propagation Ant Tasks. The servlet allows remote clients to perform online operations, such as downloading, uploading, and committing WebLogic Portal inventories.

    A sample Import Inventory from Server dialog is shown in Figure 7-3.

    Figure 7-3 Import From Server Parameters


    Import From Server Parameters

  4. Click Next. The Choose Inventory File dialog appears.
  5. In the Choose Inventory File dialog, select the folder in which to place the inventory file, and enter a name for the file, as shown in Figure 7-4.
Note: You can, if you want, add a .zip extension to this file. The extension is not added automatically. The extension is not required.
Figure 7-4 Choose Inventory File Dialog

Choose Inventory File Dialog

 

Creating a Propagation Project

This section explains how to use the Propagation Session wizard to set up a propagation project in Workshop for WebLogic. This section discusses the following tasks:

Create a Simple Project

A propagation project must reside in a project folder. If you do not currently have a project folder in which to put your propagation project, you need to create one first. In this initial task, you create a simple project for this purpose.

To create a simple project, do the following:

  1. Start Workshop for WebLogic.
  2. Select File > New > Project.
  3. In the New Project – Select a Wizard dialog, open the Simple folder, select Project, and click Next.
  4. In the New Project dialog, enter a name for the project and click Finish. The project appears in the Package Explorer, as shown in Figure 7-5.
    5. Figure 7-5 New Simple Project Folder


    New Simple Project Folder

Begin a Propagation Session

A propagation session provides a wizard that guides you through the process of importing inventory files, viewing them, and merging them.

To begin a propagation session, do the following:

  1. Select File > New > Other.
  2. In the New – Select a Wizard dialog, open the WebLogic Portal folder, select Propagation Session, and click Next.
  3. In the New Propagation Session dialog, select a parent folder, and enter a name for the session. The parent folder can be any project folder, such as the Simple Project folder you created previously.
  4. Click Next. The New Propagation Session – Choose source inventory files dialog appears.

Checkpoint: In the next task, you will import a source and a destination inventory file. Workshop for WebLogic then lets you view these files, adjust the scope and policies, and merge the files into a final merged inventory file that you can upload and commit to the destination server.

Import the Inventory Files

The propagation tools operate on a pair of WebLogic Portal inventory files: a source and a destination file. In this task, you import a previously downloaded source inventory file into the project.

Tip: You can download a portal inventory using Workshop for WebLogic or the OnlineDownloadTask Ant task. The Workshop for WebLogic method is described in Downloading an Inventory File. The Ant task is described in Using the Propagation Ant Tasks.

The imported inventory file describes the entire Enterprise application environment, as contained in the database, for that system. The source inventory file is stored in the form of XML files, which are grouped into a single ZIP file.

WARNING: Never edit the individual XML files in the exported inventory ZIP file.
  1. In the The New Propagation Session – Choose source inventory files dialog, select the link Click to import files, as shown in Figure 7-6. The Import – Select dialog appears.
    2. Figure 7-6 Choose Source Inventory File Dialog


    Choose Source Inventory File Dialog

  2. In the Import – Select dialog, select File system, as shown in Figure 7-7, and click Next.
    3. Tip: If you select the Import Inventory from Server option, the wizard lets you import the inventory directly from the server. If you choose this path, the basic steps are identical to the steps outlined in Downloading an Inventory File.
    Figure 7-7 Import – Select Dialog


    Import – Select Dialog

  3. In the Import – File System dialog, click Browse to locate the folder containing the inventory or inventories you want to import, and select the inventory files from the list box, as shown in Figure 7-8.
    4. Figure 7-8 Import – File System Dialog


    Import – File System Dialog

  4. Click Finish. This returns you to the New Propagation Session – Choose Source Inventory File dialog. Do not close the dialog; you will continue using it in the next section.
  5. Repeat this procedure to download the destination inventory file.
Tip: BEA recommends that you store all propagation session files within a source control system.

Checkpoint: You now have imported the source and destination inventory files into the propagation project. Now you will create a merged inventory file from the source and destination files.

Create a Merged Inventory File

In this task, you select the source and destination inventory files and generate a merged inventory file. A merged inventory file contains all of the artifacts resulting in the union of the source and destination files. Later, you can view and refine the merged inventory file before creating a final inventory file.

The files are merged using a set of rules, which include:

For detailed information on these rules, see Propagation Topics. For the example in this chapter, default rules are used.

Select the Source Inventory File

  1. In the Choose Source Inventory File dialog, select the source inventory file, as shown in Figure 7-9, and click Next.
    2. Figure 7-9 Choose Source Inventory Dialog


    Choose Source Inventory Dialog

Select the Destination Inventory File

  1. In the Choose Source Inventory File dialog, select the destination inventory file, as shown in Figure 7-10.
    2. Figure 7-10 Destination Inventory File Selected


    Destination Inventory File Selected

  2. Click Finish. The Open Associated Perspective dialog appears.
    3. Tip: By clicking Finish, you bypass the remaining dialogs of the Propagation Session wizard, accepting all of the default values. If you want to learn more about these options, see Propagation Topics.
  3. In the Open Associated Perspective dialog, click Yes. This action causes the Propagation Perspective to open. This perspective lets you view the merged inventory file and make changes to it if you want.
Tip: You can always open the Propagation Perspective manually by selecting Window > Open Perspective > Other, and selecting Propagation from the Select Perspective dialog.

The interim merged inventory file is created. By default, this file is named:

propSessionName.merged.zip

where propSessionName is the name of the propagation session file you created previously.

Checkpoint: At this point, you have imported a source and a destination inventory file into your propagation session and generated a merged inventory file, which is the union of the contents of the source and destination files. Next, you will view and tune the merged inventory file.

 

Viewing and Tuning the Merged Inventory

After you generate the merged inventory file, it appears in the Merged Inventory Tree View, as shown in Figure 7-11.

Note: You must be in the Propagation Perspective to see the merged inventory. You can open this perspective by selecting Window > Open Perspective > Other, and selecting Propagation from the Select Perspective dialog.

The tree view is a hierarchical description of the content of the merged inventory files.

Figure 7-11 Viewing the Merged Inventory

Viewing the Merged Inventory

By expanding the merged inventory tree, you can see the detailed contents of the inventory, including the artifacts that have been added, deleted, or updated. Figure 7-12 shows that as you drill down into an inventory view, added artifacts are indicated with a + (Plus) icon.

Figure 7-12 Expanded Inventory

Expanded Inventory

The merged inventory file graphically shows the state of each node with a combination of color and special icons badges. These visual cues include:

Table 7-1 Default Colors and Icon Badges in Merged Inventories
Icon Badge
Default Color
Meaning
+ (Plus sign)
Green
The artifact exists in the source, but not the destination. It will be added to the destination.
– (Minus sign)
Red
The artifact exists in the destination, but not the source. It will be deleted from the destination.
[ ] (Square)
Blue
The artifact exists in the source and destination. It has changed in the source and it will be updated in the destination.
Standard Eclipse error badge
Red
Error. Indicates that the change is impossible to make, possibly because of a conflicting dependency. In addition, a message is displayed in the Problems view.
Standard Eclipse warning badge
Yellow
Warning. Indicates a manual change is required. In addition, a message is displayed in the Problems view.
None
Green
Implicit change.

Tip: The default colors listed in Table 7-1 can be changed in the Eclipse IDE. To change the default colors, go to: Window > Preferences > General > Appearance > Colors and Fonts. Then, select WebLogic Portal > Propagation Tool.

Tuning the inventory refers to manually selecting or deselecting nodes in the inventory tree. If you deselect a node, the node and any dependent nodes will not be included in the final merged inventory file. Because many artifacts are dependent on other artifacts, deselecting one artifact often results in other artifacts automatically becoming deselected. Because the dependencies between portal artifacts are often complex, any discussion of modifying the merged inventory is beyond the scope of this chapter. For more information on editing the inventory, see Propagation Topics.

Tip: You can right-click a node to access additional functions, such as view filters. For example, you can filter the view to just show additions. Refer to online help in Workshop for WebLogic for more information.
Tip: The Propagation Dependencies and Propagation Dependents views help you asses the impact of adding or deleting portal assets from the merged view. For more information on these views, see Overview of the Propagation Perspective.

Checkpoint: After viewing and modifying the merged inventory, you are ready to create a final merged inventory file.

 

Creating a Final Merged Inventory File

After you are satisfied with the state of the interim merged inventory, you need to generate a final version of the merged file. At this time, any changes you made to the interim file are executed and a final, merged inventory file is created. The final inventory file is always smaller than the interim file. This is because the interim file has to maintain all of the artifacts resulting in the union of the source and destination files, while the final file contains only the merged contents of the two files.

  1. Select File > Export. The Export – Select dialog appears.
  2. In the Export – Select dialog, select Propagation Session to Inventory, as shown in Figure 7-13, and click Next.
    3. Figure 7-13 Export – Select Dialog


    Export – Select Dialog

  3. In the Choose Propagation Session dialog, select the propagation session file for the propagation session you are currently working on. To do this, you must open the project folder and select the propagation session file, as shown in Figure 7-14. After selecting the propagation file, click Next.
    4. Figure 7-14 Choose Propagation Session Dialog


    Choose Propagation Session Dialog

  4. In the Choose Inventory File dialog, select the folder in which you want to put the final inventory file, enter a name for the file, and click Finish.

    5. The final inventory file appears in the Package Explorer in the folder you designated, as shown in Figure 7-15.

    Figure 7-15 Final Inventory File


    Final Inventory File

 

Uploading the Final Inventory to the Server

This section explains how to upload the final inventory to a destination server.

Note: Workshop for WebLogic does not automatically place the server in maintenance mode to prevent users from changing portal data using the WebLogic Portal Administration Console or Visitor Tools on the production system. If a user makes changes on the production system after the inventory listing has been imported and validated, propagation results might be inaccurate and changes could be unsuccessful. If you want to place the destination system in maintenance mode, you can use the OnlineMaintenanceModeTask Ant task, which is described in Propagation Ant Task Reference.
WARNING: It is very important that you make no changes to the production system during the final upload.

Deploy the EAR File

Before you upload the final inventory, the source application EAR file must be deployed on the destination server. In other words, if you are propagating an application from the staging environment to the production environment, you must deploy the EAR from staging to production before you upload the inventory.

For more information, see Deploy the J2EE Application (EAR).

Propagate the Final Inventory to the Destination Server

When you propagate the inventory to the server, Workshop for WebLogic propagates the database assets in the final inventory file to the production server, according to the scope you assigned and the policies you selected previously.

Tip: In this step, Workshop for WebLogic uploads the file to the server and commits it. The propagation Ant tasks OnlineUploadTask and OnlineCommitTask can be used for the same purpose.
  1. Select File > Export. In the Export – Select dialog, select Propagation Inventory to Server, as shown in Figure 7-16, and click Next.
    2. Figure 7-16 Select Export Propagation Inventory to Server


    Select Export Propagation Inventory to Server

  2. In the Choose Propagation Inventory dialog, select the final merged inventory file, as shown in Figure 7-17, and click Next.
    3. Figure 7-17 Choose Propagation Inventory Dialog


    Choose Propagation Inventory Dialog

  3. In the Export to Server Parameters dialog, enter the URL of the propagation servlet running in the target web application, and the required username and password information, as shown in Figure 7-18, and click Finish.

    4. The servlet URL is: 

    http://servername:portnumber/earProjectNamePropagation/inventorymanagement

    Where earProjectName is the name of the EAR project that contains the portal application that you are propagating. For example: myEARProjectPropagation. For example: 

    http://localhost:7001/myEARProjectPropagation/inventorymanagement
Tip: The propagation servlet is deployed, by default, in all WebLogic Portal EAR projects. This servlet enables communication with remote propagation clients, such as the Workshop for WebLogic propagation tools and Propagation Ant Tasks. The servlet allows remote clients to perform online operations, such as downloading, uploading, and committing WebLogic Portal inventories.
Figure 7-18 Export To Server Parameters Dialog

Export To Server Parameters Dialog

Workshop for WebLogic deploys the merged inventory file to the server.

 

Enabling Verbose Logging

Verbose logging is useful in the event that a problem occurs with your propagation. You can choose to enable verbose logging in Workshop for WebLogic by following these steps:

  1. Exit Workshop for WebLogic.
  2. Open the following file in an editor:

    3. WEBLOGIC_HOME\workshop4WP\workshop4WP.ini

  3. Add the following property to the workshop4WP.ini file:

    4. -Dcom.bea.wlp.eclipse.proptool.verbosefolder=D:\propagation\elogs

    where D:\propagation\elogs is the directory in which you want the verbose logs to be saved.

  4. Restart Workshop for WebLogic.
Note: The verbose logs will be written to the specified directory. You must purge this directory from time to time, to avoid unwanted disk space use.

  Back to Top       Previous  Next