Production Operations User Guide
|
 |
 |
|
|
 |
 |
Using the Export/Import Utility
The Export/Import Utility provides a round-trip feature that allows you to move books, pages, and desktops, back and forth between development and staging environments. The utility, also called the xip utility (eXport/Import Portal), lets you import .portal and .pinc (portal include) files into the database, and lets you export these files from the database. The exported files can be loaded back into WebLogic Workshop, or imported into another WebLogic Portal database. For more information on the specific elements the utility handles, see Overview of the Export/Import Utility.
Figure 9-1 shows how the Export/Import Utility moves files between environments.
Figure 9-1 Export/ImporT Utility Allows Round-Trip Development
This chapter explains how to use the Export/Import Utility. The chapter includes background information on the utility and its purpose. In addition, detailed examples are provided that illustrate common use cases.
This chapter includes the following topics:
- Installing the Export/Import Utility
- Before You Use the Export/Import Utility
- Overview of the Export/Import Utility
- Understanding the Properties File
- Exporting a Desktop
- Importing a .portal File
- Exporting a Page
- Importing a Page
- Managing the Cache
Installing the Export/Import Utility
For information on installing the utility, see Installing the Propagation Software.
Before You Use the Export/Import Utility
Before you use the Export/Import Utility, it is important to understand some basic portal concepts and terms. If you review this section, the explanations and examples provided in the rest of this chapter will be more clear.
Understanding .portal Files vs. Desktops
The .portal file that you create in WebLogic Workshop is a fully functioning portal. However, it can also be used as a template to create a desktop. In this template you create books, pages and references to portlets. When you view the .portal file with your browser, the portal is rendered in "single file mode," meaning that you are viewing the portal from your filesystem as opposed to a database; the .portal file's XML is parsed and the rendered portal is returned to the browser. The creation and use of a .portal is intended for development purposes and for static portals (portals that are not customized by the end user or administrator). Because there is no database involved you cannot take advantage of functionality such as user customization or entitlements.
Once you have created a .portal file you can use it as a template to create desktops for a staging or production environment. A desktop is a particular view of a portal that visitors access. When you create a desktop based on the .portal file in the WebLogic Administration Portal, a desktop and its books and pages are placed into the database. The desktop, books, and pages reference shells, menus, look and feels, and portlets. The settings in the .portal file template, such as the look and feel, serve as defaults to the desktop. Once a new desktop is created from a .portal template, the desktop is decoupled from the template, and modifications to the .portal file do not affect the desktop, and vice versa. For example, when you change a desktop's look and feel in the WebLogic Administration Portal, the change is made only to the desktop, not to the original .portal file. When you view a desktop with a browser it is rendered in "streaming mode" (from the database). Now that a database is involved, desktop customizations can be saved and delegated administration policies and entitlements can be set on portal resources.
Understanding .pinc Files
A .pinc file is a portal include file. Just like a JSP can include other JSPs, a .portal can include other .pinc files. The .pinc files help reduce the size of .portal files and prevent conflicts caused by many developers trying to access the same resources simultaneously. A .pinc file must begin with a page or book as its root element. The book or page may then contain other nested books and pages.
Understanding Export and Import Scope
Exports and imports can be scoped to the library, admin, or visitor levels. The first two levels correspond to the Library and Portals nodes in the Portal Resources tree of the WebLogic Administration Portal, as shown in Figure 9-2. The visitor level includes changes made by users to individual desktops using the Visitor Tools.
Figure 9-2 Portal Resources Tree of the WebLogic Administration Portal
The relationshiop between library, admin, and visitor views is hierarchical, and properties from objects up the hierarchy can be inherited by objects down the hierarchy. For example, a change to a library element is inherited by desktops that use that element and by visitor views that use those desktops.
Figure 9-3 shows the hierarchy in which library, admin, and visitor instances are organized, the direction in which changes are inherited, and the tools that are typically used to make modifications at the different levels in the hierarchy.
Library Scope
An object (book, page, or portlet) can exist in the library and not be referenced by any desktop. A developer or administrator may create a page or book in the library only, outside the context of a desktop. This page or book can then be placed on a desktop at a later point in time. Changes made to objects in the library cascade down through all desktops that reference those objects. For more information on library inheritance, see Scope and Library Inheritance.
Admin Scope
The admin scope represents the "default desktop." This is where an administrator creates and modifies individual desktops. Changes made by an administrator to a desktop may use elements from the library, but desktop changes are never reflected back up into the library. Furthermore, changes made to individual desktops do not affect other desktops. However, changes made to desktops are cascaded down to the visitor views. See also Scope and Library Inheritance.
Visitor Scope
Visitors (users who access desktops) may be permitted to customize their desktop. Changes made to a visitor's desktop are restricted to that visitor's view. The changes do not show up in either the admin-level desktop, which the visitor view references, or in the library level. The changes also do not show up in other visitor's views.
Customization
Customization refers to modifying a portal through an API. This API is typically called from the WebLogic Administration Portal and Visitor Tools, but it is also exposed to developers who wish to modify desktops. The API provides all the create, read, update, and delete (CRUD) operations needed to modify a desktop and all of its components (portlets, books, pages, menus, and so on).
Note: Customization and personalization are two distinctly different features. With customization, someone is making a conscious decision to change the makeup of a desktop. With personalization, desktops are modified based on rules and user behavior.
Overview of the Export/Import Utility
The Export/Import Utility allows a full round-trip development life cycle, where you can easily move portals between a WebLogic Workshop environment and a staging or production environment, as shown in Figure 9-1. The utility performs its work in a single database transaction. If the utility fails for some reason, the database is not affected.
What the Utility Moves
The Export/Import Utility moves desktops, portlet references, books, pages, and localization definitions. In other words, the utility exports .portal and .pinc files from a database, and imports the contents of .portal and .pinc files into a database. These XML files describe fully functioning portals, and books and pages that are included in portals.
Tip: For detailed information on the portal framework, see the following documents:
http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/lookandfeel/lookandfeel.html
http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/whitepapers/netix/index.html
Note: The actual definitions for portlets, look and feels, shells, menus, layouts, themes, JSPs, and other code are contained in the EAR file. These files are stored in directories in portal web applications, such as the framework/markup directory. If any of these file-based elements change, you must rebuild and redeploy the EAR. The .portal and .pinc files simply refer to the definition files.
What the Utility Does Not Move
The Export/Import Utility does not handle the following items: campaigns, behavior tracking events, content management assets, entitlements, WSRP producer registration, portlet categories, localization resources, user profiles, and commerce data.
Merging and Scoping Rules
To refine and customize the export and import of .portal and .pinc files to and from the database, you can:
- Specify rules to determine how portal elements are merged. For instance, in a manner similar to that of a source code control mechanism, changes in a
.portalfile can be merged with changes in the database. - Specify scoping rules. Scoping rules determine how new books and pages will be merged into the new environment. Note that user and administrator customizations are preserved when assets are merged.
As shown in Figure 9-4, the Export/Import Utility offers flexibility with respect to importing, exporting, and scoping. You can scope changes to the library, admin (desktop), or visitor (individual user) level. For instance, if you import a desktop at the admin scope, the imported changes will be applied only to the specified desktop. If a user has customized that particular desktop, then the changes will also be inherited by the user desktop. Note, however, that changes are never inherited up the hierarchy: elements in the library will not inherit changes made to a desktop.
Tip: For a more in depth discussion of the relationship between the library, desktops, and user views, see Scope and Library Inheritance.
Figure 9-4 Import, Export, and Scoping Options Offered by the Export/Import Utility
To summarize, the Export/Import Utility allows you to select an object (desktop, book or page) at any level (library, admin, visitor) and import it or export it, according to specified rules.
Using the Export/Import Utility
Before using the utility, you must install it. For installation instructions, see Installing the Propagation Software. The utility is a Java program that reads a properties file. After parameters are read from the properties file, the Java program calls an API that executes the appropriate actions on the server. For instance, if you wish to import a page and scope the change to the admin level, you must specify this in the properites file. The following sections explain how to configure the properties file and present common use cases.
Tip: The Java client's source code is freely available in the installation directory of the Export/Import Utility. You are free to use this source code to develop your own client interface, if you wish.
Understanding the Properties File
By default the Export/Import Utility retrieves all of its parameters from a properties file. You must edit this properties file appropriately to configure the export or import parameters.
Specifying the Properties File Location
By default, the properties file that is used to configure the Export/Import Utility is called xip.properties. It is located in the installation directory of the Export/Import Utility. You can specify an alternate properties file by editing the Ant build file build.xml, which is also included in the installation directory of the utility. Listing 9-1 shows the Ant target definition to edit:
Listing 9-1 Modifying the Location of the Properties File in the Ant Script
<target name="run" depends="jar" description="Run the Xip utility">
<java classname="com.bea.wlp.xip.Xip" fork="true" failonerror="true">
<arg value="-verbose"/>
<arg value="-properties=my.properties"/>
<classpath>
<pathelement path="${wls.classpath}"/>
<pathelement path="${wlp.classpath}"/>
<pathelement path="${jarfile}"/>
</classpath>
</java>
</target>
Specifying Parameters in the Properties File
In the properties file you can specify such things as server configuration information, export import commands, objects, scoping rules, and propagation rules.
Listing 9-2 shows the default xip.properties file.
Listing 9-2 The Default xip.properties File
# Export/Import Properties file. The properties in this file are read by the Xip
# (pronounced zip) utility. You may specify an alternate properties file via the
# -properties command line argument.
#
# Server connfiguration information
#
xip.config.url=t3://localhost:7003
xip.config.username=weblogic
xip.config.password=weblogic
xip.config.application=myEnterpriseApp
#
# command - Are we exporting or importing. Valid values are: "export", "import"
#
#xip.command=export
xip.command=import
#
# object - The "thing" you want to export/import (desktop, book, page)
xip.object=desktop
#xip.object=book
#xip.object=page
#
# Identifier properties, tells the import export utility how to identify the
# artifacts to be retrieved or updated. When importing and exporting books and
# pages (.pinc files). If scoping changes to the admin desktop (default desktop)
# or visitor desktop then "portal.path" and "desktop.path" must be specified. If
# you are exporting a book or page then the book.label or page.label need to be
# specified.
#
#page.label and book.label are not used on import as the labels are pulled from
#the .pinc files themselves.
#
# The webapp must always be specified. This is the webapp name not necessarily
# the directory name. If you are export or importing this is where you are export
# from or importing to respectively.
#
xip.identifier.webapp=myPortal
xip.identifier.portal.path=myPortal
xip.identifier.desktop.path=myDesktop
xip.identifier.book.label=
xip.identifier.page.label=
#
# Input and output files. These can be .pinc or .portal files. These files are
# relative to the "xip" directory
#
#xip.input.file=Book1.pinc
xip.input.file=myPortal.portal
xip.output.file=myPortal1.portal
xip.output.encoding=UTF-8
#
# Import options - these options are used as rules to the export/import utility
#
# scope - Changes can be scoped to the "library", "admin", or "visitor" when
# importing a .pinc file, and "admin" or "visitor" when exporting a .portal file.
# If this property # has a value of "admin" or "visitor" then a
# xip.identifier.portal.path and xip.identifier.desktop.path # must be specified
# above. Of course to scope exports to the "library" or "admin" you must be in
# the Admin or PortalSystemAdministrator Role.
#
#
# deletes - If true, then books, pages and portlets that are currently on the
# existing desktop in the database but not in the new import file (.portal or
# .pinc) will be removed from exiting desktop.
#
# moves - (innerMoves) If true, then existing books, pages and portlets that are
# in different locations on the same parent will be moved to the correct location.
# If you want to move books, pages and portlets across different parents
# then see outermoves
#
# outermoves - If true, then existing books, pages and portlets that are moved
# from different parents will be moved to the new parent. If this is not set then
# it will be handled as a remove and add (different customizations are lost)
#
# updates - If true, then books, pages and portlets that are currently not on
# the existing desktop will be added, and any instance attributes on the books,
# page, and portlet will be updated in the database.
#
# abort.if.portlets.missing - if true, then if the new .portal or .pinc file
# references a portlet that is not in the current webapp then abort, otherwise
# skip the portlet and continue on.
#
# modify.definitions - If this flag is set to true then any changes in the import
# file will effect the defintions and not just the instances. These include
# things like markup (backing files, rollover images, isHidden, ... for a more|
# complete list refer to the database schema). It is important to note that these
# changes may effect other desktops outside the one you are scoping it to.
#
# propagate.changes - Typically all changes that are made to Library artifacts
# are cascaded down to the admin's desktop and subsequently cascaded down to the
# visitor'ss view. If this property is set to "sync" then
# these changes will occur synchronously as part of this transaction. If this
# property is set to "off" then changes will not get cascaded for the artifacts
# which have been modified. For books, pages and portlets that have not
# been modified at the admin or visitor level, then these will always receive
# the changes as they point to the default.
#
# create.portal - If this flag is set then when importing a desktop and the given
# portal is not already create then one will be created for you.
#
# portal.title - If the above flag is set and a new portal is being created it
# needs a title. This property value will be the new portal's title.
#
# locale - the locale of the titles and descriptions in the .portal or .pinc
# file. Note the encoding is defined in the file itself.
#
xip.import.context.scope=admin
xip.import.context.deletes=false
xip.import.context.moves=false
xip.import.context.outermoves=false
xip.import.context.updates=true
xip.import.context.abort.if.portlets.missing=false
xip.import.context.modify.definitions=true
xip.import.context.propagate.changes=off
xip.import.context.create.portal=true
xip.import.context.portal.title=My Green Portal
xip.import.context.locale.language=en
xip.import.context.locale.country=
xip.import.context.locale.variant=
#
# Export Options
#
# scope - Changes can be scoped to the "library", "admin", or "visitor" when
# importing a .pinc file, and "admin" or "visitor" when exporting a .portal file.
# If this property has a value of "admin" or "visitor" then a
# xip.identifier.portal.path and xip.identifier.desktop.path
# must be specified above. Of course to scope exports to the "library" or "admin"
# you must be in the Admin or PortalSystemAdministrator Role.
#
# locale - the locale of the titles and descriptions in the .portal or .pinc file.
#
xip.export.context.scope=admin
xip.export.context.locale.language=en
xip.export.context.locale.country=
xip.export.context.locale.variant=
Exporting a Desktop
This section explains how to export a desktop using the Export/Import Utility. Exporting a desktop means retrieving the attributes of a desktop from the database and restoring them in a .portal file. The exported .portal file can then be loaded into WebLogic Workshop for further development. To export a desktop, you need to edit the xip.properties file and run an Ant build script.
Editing the Properties File
To export an existing desktop as a .portal file you need to specify attributes in the xip.properties file. This section highlights the required changes.
xip.config.application=portalProject
You must specify the name of Enterprise application from which you are exporting. In WebLogic Workshop, this value corresponds to the Application name, as shown in the following figure:
Figure 9-5 Application Name Shown in the Administration Portal
xip.command=export
Specify that you wish to export, rather than import.
xip.object=desktop
Specify the object you wish to export—in this example, a desktop.
xip.identifier.webapp=PortalWebApp_1
xip.identifier.portal.path=yourPortalPath
xip.identifier.desktop.path=yourDesktopPath
Note: These lines identify the objects you wish to export. For information on where to find the values for these properties, if you do not know what they are, see Specifying Identifiers for more information.
The web webapp property must always be specified.
If you scope the export to the admin or visitor level, then you must specify the portal.path and desktop.path properties.
xip.output.file=myportal.portal
Specify where you wish to save the result (the exported .portal file). In this example, the resulting file is called myportal.portal, and it is placed in a location relative to where the utility was run.
Note: You do not need to specify the encoding as this information is in the database.
xip.export.context.scope=admin
Specify the scope of the export. In this example, the admin scope is specified. For more information on scope, see Understanding Export and Import Scope.
xip.export.context.locale.language=en
Specify the locale of the exported desktop (in this example, English). Only one locale can be exported or imported at a time.
Running the Build Script
Once the property attributes are defined, you can run the Ant build script, as shown in Listing 9-3. The build script's task writes status information, also shown below, to the console window.
Listing 9-3 Running the Ant Build Script
C:\dev\xip>ant run
Buildfile: build.xml
init:
compile:
jar:
run:
[java] Using: Properties from file [xip.properties]
[java] Name [xip.config.url] Value [t3://localhost:7003]
[java] Name [xip.config.username] Value [weblogic]
[java] Name [xip.config.password] Value [********]
[java] Name [xip.config.application] Value [portalProject]
[java] Name [xip.command] Value [export]
[java] Name [xip.object] Value [desktop]
[java] Name [xip.identifier.webapp] Value [PortalWebApp_1]
[java] Name [xip.identifier.portal.path] Value [yourPortalPath]
[java] Name [xip.identifier.desktop.path] Value [yourPortalDesktop]
[java] Name [xip.identifier.book.label] Value [mainBook]
[java] Name [xip.identifier.page.label] Value []
[java] Name [xip.input.file] Value [yourPortal.portal]
[java] Name [xip.output.file] Value [myportal.portal]
[java] Name [xip.import.context.deletes] Value [false]
[java] Name [xip.import.context.moves] Value [false]
[java] Name [xip.import.context.outermoves] Value [false]
[java] Name [xip.import.context.updates] Value [true]
[java] Name [xip.import.context.abort.on.collisions] Value [null]
[java] Name [xip.import.context.abort.if.portlets.missing] Value [false]
[java] Name [xip.import.context.scope] Value [admin]
[java] Name [xip.import.context.modify.definitions] Value [false]
[java] Name [xip.import.context.propagate.changes] Value [sync]
[java] Name [xip.import.context.create.portal] Value [true]
[java] Name [xip.import.context.portal.title] Value [My Portal]
[java] Name [xip.import.context.locale.language] Value [en]
[java] Name [xip.import.context.locale.country] Value []
[java] Name [xip.import.context.locale.variant] Value []
[java] Name [xip.export.context.scope] Value [admin]
[java] Name [xip.export.context.locale.language] Value [en]
[java] Name [xip.export.context.locale.country] Value []
[java] Name [xip.export.context.locale.variant] Value []
[java] Executing command: export
[java] Exporting desktop [Webapp: [PortalWebApp_1] PortalPath: [yourPortalPath] DesktopPath: [yourDesktopPath]] to file [myportal.portal]
[java] Connection to host: t3://localhost:7003
[java] Saving changes to: myportal.portal
[java] Done. time taken 6 sec.
BUILD SUCCESSFUL
Total time: 8 seconds
C:\dev\xip>
The file myportal.portal can now be reloaded into WebLogic Workshop or imported into another staging or production (database) environment.
Importing a .portal File
This section explains how to import a .portal file into a desktop using the Export/Import Utility. When importing a .portal file into a desktop, there are two possible cases: the desktop already exists in the database or it does not. If the desktop does not already exist in the database, then the Export/Import Utility automatically creates it. If, however, the desktop does already exist in the database, you need to specify merging options. As with other kinds of options, you specify merge options in the xip.properties file, as explained in the following sections.
Editing the Properties File
To import an existing .portal file into a desktop, you need to specify attributes in the xip.properties file. This section highlights the required changes.
xip.config.application=portalProject
You must specify the name of Enterprise application you are importing to. In WebLogic Workshop, this value corresponds to the Application name, as shown in the following figure:
xip.command=import
Specify that you wish to import, rather than export.
xip.object=desktop
The object you are interested in importing - in this example a desktop.
xip.identifier.webapp=PortalWebApp_1
xip.identifier.portal.path=yourPortalPath
xip.identifier.desktop.path=yourDesktopPath
Note: These lines identify the objects you wish to export. For information on where to find the values for these properties, if you do not know what they are, see Specifying Identifiers.
The web webapp property must always be specified.
If you scope the export to the admin or visitor level, then you must specify the portal.path and desktop.path properties.
xip.input.file=myportal.portal
Specify the .portal file that you wish to import from. The utility looks for the file in a location relative to where the utility is installed.
Note: You do not need to specify an encoding as that is defined in the .portal file itself.
xip.import.context.scope=admin
Specify the scope of the import. In this example, you wish to import a desktop at the admin level. For detailed information on scope, see Understanding Export and Import Scope.
xip.import.context.deletes=false
You must specify how to handle deletes. See Handling Deletes for detailed information.
xip.import.context.moves=false
xip.import.context.outermoves=true
You must specify how to handle moves. See Handling Moves for detailed information.
xip.import.context.updates=true
If xip.import.context.updates is true then new portlets, books, and pages that do not exist in the desktop but exist in the .portal will be added to the new desktop. Also instance level resources will be updated.
xip.import.context.abort.if.portlets.missing=true
If xip.import.context.abort.if.portlets.missing is true then if a portlet is referenced in the .portal file but does not exist in the web application then the import is halted. If this flag is false a warning is logged and the import continues.
xip.import.context.modify.definitions=true
If xip.import.context.modify.definitions is true, when updating books and pages the utility also updates the library definition. A library definition consists of markup, which includes backing files, activate, deactivate, and rollover images. Also titles and descriptions for books and pages, and the is_hidden flag are stored in these definitions.
Note: Be aware that if you modify a library definition, desktop instances that share that library definition could be affected. Therefore, if you scope to a particular desktop, you may inadvertently affect other desktops if this property is set to true. For a detailed discussion about the relationship between library definitions and desktop instances, see Scope and Library Inheritance.
xip.import.context.propagate.changes=sync
The xip.import.context.propagate.changes property lets you specify whether or not to propagate changes down the hierarchy of portal elements. Valid values for this property are sync or off.
When adding, removing, or moving portlets, pages or books, the changes typically are propagated down the hierarchy. In other words, changes made in the library are seen in all desktops, and changes made to the admin view (default desktop) are seen by all users.
A user's desktop view initially points to (inherits its properties from) the default desktop (admin view). If the default desktop changes, the changes are propagated downward to the user view.
When users customize their views, each user's view receives a copy of the customized portions of their view, and the rest of the portal continues to reference the default, or parent, desktop.
This property gives you the ability to control how changes are propagated down the hierarchy when users have customized their portals. If a user's or admin's portal is never customized, their views will always inherit changes from up the hierarchy, even if this property is set to off.
If, however, a user has customized a portion of a portal, and the same portion is modified up the hierarchy, this property allows you to control whether or not the change is propagated down the hierarchy. In this case, if you set this property to off, admin and user views will not inherit updates made to parent components. If set to synch, changes will be propagated downward, even if the user customized his or her view.
Tip: You may want to turn this property off if you do not want to modify the pages or books that the user or administrator considers to be privately owned.
Tip: It is considered good practice to allow your users to modify only a certain section of the portal and lock down the rest (for instance, one page that they have full control over), instead of allowing them free control over the entire portal. This promotes better scalablity and makes portals more manageable when a large number of users make customizations.
xip.import.context.create.portal=true
If xip.import.context.create.portal is set to true and a portal does not exist in the database, one will be created for you. In addition, you must specify a title for the new portal using the next property.
xip.import.context.portal.title=My Portal
If xip.import.context.create.portal (described previously) is set to true, then you must specify a title using this property.
xip.import.context.locale.language=en
xip.import.context.locale.country=
xip.import.context.locale.variant=
These properties define the locale for the .portal file's titles and descriptions.
Running the Build Script
Once the property attributes are defined, you can run the build script, as shown in Listing 9-4. The build script's task writes status information, also shown below, to the console window.
Listing 9-4 Running the Ant Build Script
C:\dev\xip>ant run
[java] Using: Properties from file [xip.properties]
[java] Name [xip.config.url] Value [t3://localhost:7003]
[java] Name [xip.config.username] Value [weblogic]
[java] Name [xip.config.password] Value [weblogic]
[java] Name [xip.config.application] Value [portalProject]
[java] Name [xip.command] Value [import]
[java] Name [xip.object] Value [desktop]
[java] Name [xip.identifier.webapp] Value [PortalWebApp_1]
[java] Name [xip.identifier.portal.path] Value [yourPortal]
[java] Name [xip.identifier.desktop.path] Value [yourDesktop]
[java] Name [xip.identifier.book.label] Value []
[java] Name [xip.identifier.page.label] Value []
[java] Name [xip.input.file] Value [myportal.portal]
[java] Name [xip.output.file] Value []
[java] Name [xip.import.context.deletes] Value [false]
[java] Name [xip.import.context.moves] Value [false]
[java] Name [xip.import.context.outermoves] Value [false]
[java] Name [xip.import.context.updates] Value [true]
[java] Name [xip.import.context.abort.on.collisions] Value [null]
[java] Name [xip.import.context.abort.if.portlets.missing] Value [false]
[java] Name [xip.import.context.scope] Value [admin]
[java] Name [xip.import.context.modify.definitions] Value [false]
[java] Name [xip.import.context.propagate.changes] Value [sync]
[java] Name [xip.import.context.create.portal] Value [true]
[java] Name [xip.import.context.portal.title] Value [My Portal]
[java] Name [xip.import.context.locale.language] Value [en]
[java] Name [xip.import.context.locale.country] Value []
[java] Name [xip.import.context.locale.variant] Value []
[java] Name [xip.export.context.scope] Value [admin]
[java] Name [xip.export.context.locale.language] Value [en]
[java] Name [xip.export.context.locale.country] Value []
[java] Name [xip.export.context.locale.variant] Value []
[java] Executing command: import
[java] Importing desktop: Webapp: [PortalWebApp_1] PortalPath: [yourPortalPath] DesktopPath: [yourDesktopPath]
[java] Connection to host: t3://localhost:7003
[java] Uploading file: myportal.portal
[java] Done. time taken 40 sec.
BUILD SUCCESSFUL
Total time: 52 seconds
Exporting a Page
If you do not wish to export an entire desktop, you can configure the utility to export a single page.
Tip: While this section explicitly deals with exporting pages, the same basic procedure applies to exporting books.
This section explains how to export a page from a desktop. Exporting a page is another common use case. When you export a page or a book, the result is a .pinc file. For more information, see Understanding .pinc Files.
Note: If you export a page or a book, all children of that page or book are exported as well.
Editing the Properties File
To export an existing page as a .pinc file you will need to specify attributes in the xip.properties file. This section highlights the required changes.
xip.config.application=portalProject
You must specify the name of Enterprise application you are exporting from. In WebLogic Workshop, this value corresponds to the Application name, as shown in the following figure:
xip.command=export
Specify that you wish to export, rather than import.
xip.object=page
The object you are interested in exporting - in this example a page.
xip.identifier.webapp=PortalWebApp_1
xip.identifier.portal.path=yourPortalPath
xip.identifier.desktop.path=yourDesktopPath
Note: These lines identify the objects you wish to export. For information on where to find the values for these properties (if you do not know what they are), see Specifying Identifiers.
The web webapp property must always be specified.
If you scope the export to the admin or visitor level, then you must specify the portal.path and desktop.path properties. If you are exporting a book or a page, then the book.label or page.label properties must be specified.
If you scope the export to the library then you do not need to supply a portal.path and desktop.path, but you still need to supply a webapp name.
xip.identifier.book.label=
xip.identifier.page.label=P200134591113965077078
You need to identify the page or book that you wish to export. To do this, specify the definition label of the page or book using the xip.identifier.page.label property. The definition label is typically supplied by the developer in WebLogic Workshop, but it could also have been automatically generated by the Administration Portal. See Specifying Identifiers for information on finding the definition label.
xip.output.file=mypage.pinc
Use this property to specify a file in which to save the result. In this example, the file mypage.pinc is saved in the directory in which the utility is run.
Note: You do not need to specify the encoding as this information is in the database.
xip.export.context.scope=admin
Specify the scope of the export. In this example, the page is exported from within a desktop (admin scope). If you want to export a page from the library, set the scope to library.
xip.export.context.locale.language=en
Specify the locale of the exported page.
Running the Build Script
Once the property attributes are defined, you can run the Ant build script, as shown in Listing 9-5. The build script's task writes status information, also shown below, to the console window.
Listing 9-5 Running the Ant Build Script
C:\dev\xip>ant run
Buildfile: build.xml
init:
compile:
jar:
run:
[java] Using: Properties from file [xip.properties]
[java] Name [xip.config.url] Value [t3://localhost:7003]
[java] Name [xip.config.username] Value [weblogic]
[java] Name [xip.config.password] Value [********]
[java] Name [xip.config.application] Value [portalProject]
[java] Name [xip.command] Value [export]
[java] Name [xip.object] Value [page]
[java] Name [xip.identifier.webapp] Value [yourPortal]
[java] Name [xip.identifier.portal.path] Value [yourPortalPath]
[java] Name [xip.identifier.desktop.path] Value [yourDesktopPath]
[java] Name [xip.identifier.book.label] Value []
[java] Name [xip.identifier.page.label] Value [P200134591113965077078]
[java] Name [xip.input.file] Value []
[java] Name [xip.output.file] Value [mypage.pinc]
[java] Name [xip.import.context.deletes] Value [false]
[java] Name [xip.import.context.moves] Value [false]
[java] Name [xip.import.context.outermoves] Value [false]
[java] Name [xip.import.context.updates] Value [true]
[java] Name [xip.import.context.abort.on.collisions] Value [null]
[java] Name [xip.import.context.abort.if.portlets.missing] Value [false]
[java] Name [xip.import.context.scope] Value [admin]
[java] Name [xip.import.context.modify.definitions] Value [false]
[java] Name [xip.import.context.propagate.changes] Value [sync]
[java] Name [xip.import.context.create.portal] Value [true]
[java] Name [xip.import.context.portal.title] Value [My Portal]
[java] Name [xip.import.context.locale.language] Value [en]
[java] Name [xip.import.context.locale.country] Value []
[java] Name [xip.import.context.locale.variant] Value []
[java] Name [xip.export.context.scope] Value [admin]
[java] Name [xip.export.context.locale.language] Value [en]
[java] Name [xip.export.context.locale.country] Value []
[java] Name [xip.export.context.locale.variant] Value []
[java] Executing command: export
[java] Exporting page [mypage] scoped to desktop: Webapp: [PortalWebApp_1] PortalPath: [yourPortalPath] DesktopPath: [yourDesktopPath]]
[java] Connection to host: t3://localhost:7003
[java] Saving changes to: mypage.pinc
[java] Done. time taken 6 sec.
BUILD SUCCESSFUL
Total time: 8 seconds
Importing a Page
This section explains how to import a single page.
Tip: While this section explicitly deals with pages, the same procedure applies to importing a book.
The imported page could have been created in WebLogic Workshop or exported from another staging or production environment. Either way you are importing a .pinc file into the database.
Note: When you import or export a page or book, all the children are imported as well.
Editing the Properties File
To import an existing .pinc file you must specify attributes in the xip.properties file. This section highlights the required changes you must make to the properties file to import a page.
xip.config.application=portalProject
You must specify the name of Enterprise application you are importing to. In WebLogic Workshop, this value corresponds to the Application name, as shown in the following figure:
xip.command=import
Specify that you wish to import, rather than export.
xip.object=page
The object you are interested in importing - in this example a page.
xip.identifier.webapp=PortalWebApp_1xip.identifier.book.label=
xip.identifier.portal.path=yourPortalPath
xip.identifier.desktop.path=yourDesktopPath
xip.identifier.page.label=
Note: These lines identify the objects you wish to export. For information on where to find the values for these properties (if you do not know what they are), see Specifying Identifiers.
If you scope the import to the admin or visitor level, then you must specify the portal.path and desktop.path properties. If you are importing a book or a page, then the book.label or page.label properties must be specified.
The web webapp property must always be specified.
Note: The page.label property is not needed on imports. This is because the page label is defined in the .pinc file as an attribute of the <netuix:page ... /> element.
xip.input.file=mypage.pinc
Specify the .pinc file to import from. By default, the utility locates the file in a directory relative to where you run the utility.
xip.import.context.scope=admin
Identify the scope of the import. In this example you are importing a page at the admin level.
xip.import.context.deletes=false
You need to specify how to handle deletes. See Handling Deletes for more information on this property.
xip.import.context.moves=false
You need to specify how to handle moves. See Handling Moves for more information on this property.
xip.import.context.updates=true
If xip.import.context.updates is true then new portlets, book and pages that don't exist in the desktop but exist in the .portal will be added to the new desktop. Also instance level resources will be updated.
xip.import.context.abort.if.portlets.missing=true
If xip.import.context.abort.if.portlets.missing is true then if a portlet is referenced in the .portal file but does not exist in the web application then the utility will halt the import. If this flag is false then the utility logs a warning and continues.
xip.import.context.modify.definitions=true
If xip.import.context.modify.definitions is true, when updating books and pages the utility also updates the library definition. A library definition consists of markup, which includes backing files, activate, deactivate, and rollover images. Also titles and descriptions for books and pages, and the is_hidden flag are stored in these definitions.
Note: Be aware that if you modify a library definition, desktop instances that share that library definition could be affected. Therefore, if you scope to a particular desktop, you may inadvertently affect other desktops if this property is set to true. For a detailed discussion about the relationship between library definitions and desktop instances, see Scope and Library Inheritance.
xip.import.context.propagate.changes=sync
The xip.import.context.propagate.changes property lets you specify whether or not to propagate changes down the hierarchy of portal elements. Valid values for this property are sync or off.
When adding, removing, or moving portlets, pages or books, the changes typically are propagated down the hierarchy. In other words changes made in the library are seen in all desktops. And changes made to the admin view (desktop) are seen by all users.
A user's desktop view inherits its properties from the default desktop (admin view). If the default desktop changes, the changes are propagated downward to the user view. When a users customize their views, each user's view receives a copy of the customized portions of their view, and the rest of the portal continues to reference the default, or parent, desktop.
This property gives you the ability to control how changes are propagated down the hierarchy when users have customized their portals. If a user's or admin's portal is never customized, their views will always inherit changes from up the hierarchy, even if this property is set to off.
If, however, they have customized a portion of a portal, and the same portion is modified up the hierarchy, this property allows you to control whether or not the change is propagated down the hierarchy. In this case, if you set this property to off, admin and user views will not inherit updates made to parent components. If set to synch, changes will be propagated downward, even if the user customized his or her view.
Tip: You may wish to turn this property off if you do not want to modify the pages or books that the user or administrator considers to be privately owned.
Tip: It is considered good practice to only allow your users to modify a certain section of the portal and lock down the rest (for instance, one page that they have full control over), instead of allowing them free control over the entire portal. This promotes better scalablity and makes portals more manageable when a large number of users make customizations.
xip.import.context.locale.language=en
xip.import.context.locale.country=
xip.import.context.locale.variant=
These properties define the locale for the .pinc file's titles and descriptions.
Running the Build Script
Once the property attributes are defined, you can run the build script, as shown in Listing 9-6. The build script's task writes status information, also shown below, to the console window.
Listing 9-6 Running the Ant Build Script
C:\dev\xip>ant run
[java] Using: Properties from file [xip.properties]
[java] Name [xip.config.url] Value [t3://localhost:7003]
[java] Name [xip.config.username] Value [weblogic]
[java] Name [xip.config.password] Value [weblogic]
[java] Name [xip.config.application] Value [portalProject]
[java] Name [xip.command] Value [import]
[java] Name [xip.object] Value [page]
[java] Name [xip.identifier.webapp] Value [PortalWebApp_1]
[java] Name [xip.identifier.portal.path] Value [yourPortalPath]
[java] Name [xip.identifier.desktop.path] Value [yourDesktopPath]
[java] Name [xip.identifier.book.label] Value []
[java] Name [xip.identifier.page.label] Value []
[java] Name [xip.input.file] Value [mypage.pinc]
[java] Name [xip.output.file] Value []
[java] Name [xip.import.context.deletes] Value [false]
[java] Name [xip.import.context.moves] Value [false]
[java] Name [xip.import.context.outermoves] Value [false]
[java] Name [xip.import.context.updates] Value [true]
[java] Name [xip.import.context.abort.on.collisions] Value [null]
[java] Name [xip.import.context.abort.if.portlets.missing] Value [false]
[java] Name [xip.import.context.scope] Value [admin]
[java] Name [xip.import.context.modify.definitions] Value [false]
[java] Name [xip.import.context.propagate.changes] Value [sync]
[java] Name [xip.import.context.create.portal] Value [true]
[java] Name [xip.import.context.portal.title] Value [My Portal]
[java] Name [xip.import.context.locale.language] Value [en]
[java] Name [xip.import.context.locale.country] Value []
[java] Name [xip.import.context.locale.variant] Value []
[java] Name [xip.export.context.scope] Value [admin]
[java] Name [xip.export.context.locale.language] Value [en]
[java] Name [xip.export.context.locale.country] Value []
[java] Name [xip.export.context.locale.variant] Value []
[java] Executing command: import
[java] Importing page scoped to desktop: Webapp: [PortalWebApp_1] PortalPath: [yourPortalPath] DesktopPath: [yourDesktopPath]
[java] Connection to host: t3://localhost:7003
[java] Uploading file: mypage.pinc
[java] Done. time taken 20 sec.
BUILD SUCCESSFUL
Total time: 25 seconds
Handling Deletes
The xip.import.context.deletes property lets you control how portal assets are merged during an import. As shown in Figure 9-10, if you set this property to false, the contents of the imported pages are combined with the existing pages.
Note: This example refers to portlets; however, the same merge operations would apply as well for pages on a book.
Figure 9-9 Merge Results with Deletes = false
As shown in Figure 9-10, if you set this property to true, any portlets that do not exist in the .portal file but do exist in the desktop are deleted.
Note: This example refers to portlets; however, the same merge operations would apply as well for pages on a book.
Figure 9-10 Merge Result with Deletes = true
Handling Moves
The xip.import.context.moves and xip.import.context.outermoves properties let you specify how moves are handled when portal assets are imported. To understand how moves operate, you need to understand the meaning of inner moves and outer moves.
Inner Moves
When an asset such as a portlet or a page is moved within the context of a single parent, the move is called an inner move. For example, if you move a portlet to a different placeholder within a page, it is an inner move because the parent (the page) remains the same. Likewise, if you move a page to a different position in a book, it is an inner move because the parent (the book) remains the same. The following figure illustrates this concept:
Figure 9-11 Inner Move: Pages P1 and P2 Swap Positions Within the Same Book
Set the xip.import.context.moves property to true to allow inner moves. If the property is set to false, the positions of assets will not change; however, the contents will be updated appropriately. If you want to move books, pages, or portlets across different parents, then use the xip.import.context.outermoves property, described in the next section.
Outer Moves
When an asset such as a portlet or a page is moved from one parent to another, the move is called an outer move. For example, if you move a page from one book to a different book, that is an outer move because the parent (the book) is different. The following figure illustrates this concept:
Figure 9-12 Outer Move: Pages P1 and P4 Swap Positions Across Different Books
Set the xip.import.context.outermoves property to true to allow outer moves. If the property is set to false, then the operation handles the requested move as a deletion and addition operation.
Note: Move operations preserve customizations. When a deletion/addition operation is performed, some customizations are lost.
If you want to move books, pages, or portlets across the same parent, then use the xip.import.context.moves property, described in the previous section.
Specifying Identifiers
This section explains how to find the values for the identifier properties in the xip.properties file. These properties help to identify the portal element to export or import. The identifier properties include:
xip.identifier.webapp=xip.identifier.book.label=
xip.identifier.portal.path=
xip.identifier.desktop.path=
xip.identifier.page.label=
The web webapp property must always be specified. The web application name is listed in the WebLogic Administration Portal, as shown in the following figure:
Figure 9-13 The Web Application Name
If you scope the export to the admin or visitor level, then you must specify the portal.path and desktop.path properties. You can find the correct value in the Administration Portal. The portal path is shown in the Portal Properties tab, and the desktop path is shown in the Desktop Properties tab. For example, the portal path is shown in the following figure:
Figure 9-14 The Portal Path Value As Shown in the Portal Properties Tab
If you are exporting or importing a page or book, you need to specify the definition label of the page or book using the xip.identifier.page.label or xip.identifier.book.label property. Definition labels are typically supplied by the developer in WebLogic Workshop; however, they can also be created in the Administration Portal. If the page was created using the Administration Portal, a definition label is assigned automatically.
Note: If you are exporting a book or a page, then the book.label or page.label properties must be specified. If you are importing a book or a page, the book.label or page.label properties are not needed, because these values are obtained directly from the .pinc files.
Locating the Definition Label for a Page
You can locate the definition label for a page in the Administration Portal on the Page Properties tab. Figure 9-15 shows the definition label for a page.
Figure 9-15 The Location of a Page's Definition Label in the Weblogic Administration Portal
Locating the Definition Label for a Book
To find the definition label of a book, you need to look at the Manage Book Contents tab of the book's parent book. You will find the labels of all of the child books listed there.
Managing the Cache
Proper cache management greatly improves portal performance. Whenever a cache is invalidated, the portal API must retreive fresh data from the database. It is inefficient when the API retrieves data that has not changed. The Export/Import Utility invalidates only the caches (specifically, the portalControlTreeCache) for portal resources that have changed. The invalidation of the cache is governed by the following properties:
xip.config.application
xip.identifier.webapp
xip.identifier.portal.path
xip.identifier.desktop.path
xip.import.context.scope
xip.import.context.modify.definitions
These properties are described below.
Note: Be sure to understand these properties and how they affect the invalidation of the cache. Understanding your changes, scoping them correctly, and tuning these properties correctly will greatly improve your production system's performance.
xip.config.application
Specifies the name of the Enterprise application. Only portals under this Enterprise application will be affected. In WebLogic Workshop, this value corresponds to the Application name, as shown in the following figure:
Specifies the name of the web application. Only portals under this web application will be affected. See also Specifying Identifiers.
Specifies the scope of the change. If the scope is set to library then all portalControlTree caches for the entire web application are invalidated. If the scope is set to admin then only the cache for the desktop defined by xip.identifier.portal.path and xip.identifier.desktop.path is affected, leaving the other desktop caches intact. If the scope is set to visitor then only the cache of an individual user's view is invalidated. See also Specifying Identifiers.
xip.import.context.modify.definitions
If set to true, library definitions may be modified. Since definitions are shared across all instances of library resources, the entire web application cache must be invalidated, even if the scope is set to admin. If you are just adding pages or portlets to the books and pages there is no reason to update the definitions.
Note: A library definition consists of markup, which includes backing files, activate, deactivate, and rollover images. Also titles and descriptions for books and pages, and the is_hidden flag are stored in these definitions.
Warning: Be aware that if you modify a library definition, desktop instances that share that library definition could be affected. Therefore, if you scope to a particular desktop, you may inadvertently affect other desktops if this property is set to true. For a detailed discussion about the relationship between library definitions and desktop instances, see Scope and Library Inheritance.
