As a WebSphere AppServer or PortalServer administrator, your world can be a constant learning curve as new applications come along that utilize different aspects of the IBM middleware platforms. You may, for example, have mastered the art of deploying portal configurations using full or partial portal exports. This is convenient and easy to do. However, it may not give you the flexibility required for that new upcoming portal application that is being conceived in the minds of your company's Java developers. Luckily for you, XMLAccess is quite flexible.
Assuming you are familiar with the basic concepts of XMLAccess, the following refinements to the process should be straightforward. Instead of taking a full export from your production environment, suppose you wish to only export the portlets? In XMLAccess, the portlet is represented by the object type "web-app." Naturally you could generate an export of the portlets using the following XML (which is included in the samples shipped with Portal):
<?xml version="1.0" encoding="UTF-8"?>
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PortalConfig_1.3.xsd" type="export">
<portal action="locate">
<web-app action="export"
objectid="*"/>
</portal>
</request>
By importing this xml file, we direct the portal to export only the web-app object called '*' which is a wildcard for all web-apps. The command would be as follows:
xmlaccess.bat -in C:\temp\export_all_portlets.xml -user wpsadmin -pwd wpsadminpwd -url http://portal.example.com/wps/config -out C:\temp\outputfile_all_portlets.xml
Right, so very easy. However, this sort of thing is useful only if we already have a portal configured with all of the portlets. If we're exporting all "web-app" objects, this assumes we have some to export in the first place. Suppose you have 50 new portlets that all need to be installed, but you have no existing portal that has all of them in place. Are you going to use the portal admin interface and click-click-click your way through installing 50 portlets, assigning permissions, creating pages, putting the portlets on the pages, etc. etc. etc.? Probably not - at least, I know I wouldn't.
How can we use XMLAccess to build a portal configuration if we are deploying portal elements for the very first time? This task won't involve exporting a config from somewhere, since we don't have things configured in any environment yet. Instead we're going to construct our XML files from scratch and import them into a blank portal in order to build our configuration.
The various XML files referred to from this point forward are printed at the end of this article.
The Blank Portal
When installing WPS, it is often desirable to deploy the portal without the sample pages and labels and portlets; it is simply too much clutter. To install a blank portal, use the following command when invoking the installation program:
install.bat -W installPortlets Sequence.active="false"
Proceed through the portal install sequence as you normally would. When complete, start the portal and go the portal home page. You should now see the blank portal.
Before continuing, be sure to have all of your necessary files in place. That is, if you are installing a theme, place the folder containing the theme on the PortalServer in the correct location. The same goes for skins, portlet WARs, etc.
Theme folders go into:
C:\WebSphere\AppServer\installedApps\<nodename>\wps.ear\wps.war\themes\html\
Skin folders go into:
C:\WebSphere\AppServer\installedApps\<nodename>\wps.ear\wps.war\skins\html\
By default, portlet WAR files need to be placed in:
C:\WebSphere\PortalServer\installableApps
With our blank portal installed, and with our component files in place, let's begin constructing our new portal. We'll start with the skins and themes.
Install Skins and Themes
The XML to install the theme will of course include the standard XML header for WPS 5.1. After that, we will do the required locate action on the "portal" object. After this we will instruct XMLAccess to perform an "update" on our skin with the parameters that we specify as show in Listing 1.
The skin object we specified includes the objectid, uniquename, and resourceroot parameters. Objectid will be the skin's referential id within the portal database. For ease of use, we also have a uniquename specified for this skin so that we can easily refer to the skin from this point forward. The resourceroot indicates the case-sensitive folder name of our skin that we placed in the skins\html\ directory.
Let's save this file as import_skins.xml. Once we import this file, we will have installed the skins into our portal:
xmlaccess.bat -in C:\temp\import_skins.xml -user wpsadmin -pwd wpsadminpwd -url http://portal.example.com/wps/config
To install our themes, we need an XML file with similar information
Since a theme has default and allowed skins assigned to it, we first have to find these skins before we can assign them to the theme. So we do a 'locate' on our two skins that were added in Listing 1. Once we find them, we perform an "update" on the theme object.
The update uses defaultskinref to define the default skin for the theme. For the first theme, we used Skin_A as the default skin. The objectid and uniquename for the theme are defined (and can be different, as indicated). The resourceroot is the case-sensitive folder name of the themes\html\ directory.
Notice that in addition to defining the default skin for each theme, we can also define the other skins that can be used with this theme. Notice that for Theme_Blue we are using Skin_A as the default, but we allow Skin_A as well as Skin_B. This is defined in the <allowed-skin skin="..."> section. Notice that for Theme_Green we are using Skin_B as the default and we only allow that skin. After all, Skin_A is red. Mixing a red skin with a green theme is just plain ugly.
Now let's save the xml file as import_themes.xml and import our themes into the portal configuration:
xmlaccess.bat -in C:\temp\import_themes.xml -user wpsadmin -pwd wpsadminpwd -url http://portal.example.com/wps/config
Install Portlets
We have our themes and skins imported, now let's put those pesky portlets in place.
Constructing the XML file for portlet install is a little trickier. It involves knowing some key information about the portlets. This information is found in the portlet.xml and web.xml inside the portlet.war file. For this step Winzip is especially useful, as you will need to be able to open the portlet WAR file (see Listing 3). You may also be able to get this info from the portlet developer. After all, he can see this info in his portal toolkit inside WebSphere Studio. However, developers being as busy as they usually are, good luck extracting this info from them.
Okay. This is slightly more complex. Here we have 3 portlets that we're installing. You can see we're locating the portal (of course), and then we do an update on object "web-app" which represents the WAR file.
The next parameter is the web-app uid parameter. The uid must match the uid attribute of portlet-app in portlet.xml in the portlet WAR file.
Following the uid, we have to specify the location of the portlet WAR file. When we transferred our portlet WARs to the server, we placed them in C:\WebSphere\PortalServer\installableApps. To refer to this location, we can use the $server_root$ variable which gets set when the XMLAccess interface is invoked.
Next, we have to perform an update on the portlet-app object. This represents the portlet application and is the parent of all the portlets contained within. The next parameter is the portlet-app uid parameter. The uid must match the uid attribute of concrete-portlet-app in portlet.xml in the portlet WAR file.
Finally we have the update to be performed on each portlet in the portlet application. In this example we only have one portlet in each WAR file, but we could potentially have several in each one. If this were the case, we'd have multiple "portal" objects defined within the "portal-app" object. We give the portlet an objectid and we define the name. The portlet name parameter must match the content of the portlet-name subtag of concrete-portlet in portlet.xml in the portlet WAR file.
So let's go ahead and save the xml file as import_portlets.xml and execute:
xmlaccess.bat -in C:\temp\import_portlets.xml -user wpsadmin -pwd wpsadminpwd -url http://portal.example.com/wps/config
We should now have deployed skins, themes, and portlets. Let's create a page and drop some portlets on it.
Create Pages
This is very straightforward. We need pages on which to place our portlets. Pages and labels are represented in the XML files as "content-node." Seems pretty logical if you think about it. A node of content. A content-node. Brilliant.
Our XML will look like Listing 4. Think of it logically. We first locate the resources we need (themes, portlets) and then we create our pages using those resources. Piece of cake. In this example, we'll create a label in the Content Root called Home (Content Root is the highest node of the content hierarchy. It exists by default). Hanging off this label is a single page called Welcome. On this Welcome page is single row containing our portlet, PortletCharlie.
You can see that we start off by locating the necessary resources - first the theme, Theme_Blue and then the portlet, PortletCharlie. Finally we have to locate the Content Root.
The next step in the process is to create the Home label. We give it an objectid and a uniquename. We define the content-parentref to be this label's immediate parent. In our case, this is the objectid of Content Root. Because we're creating a label at this point and not a page, we can assign a theme to the label. So we define themeref to be Theme_Blue.
Once created, we must immediately "locate" the new label before it can be used in the rest of the XML file. Next, we want to create the page called Welcome that is on the label called Home. You can see the values we use to define this page. With a page, however, we can also define the columns and rows containers that compose the structure of a portal page. Within these containers, we place the portlets.
The rows and columns on the page are defined in the "component" section in that page. In this example, within the page definition for the content-node Welcome, we define a component with an orientation of "H," which stands for horizontal, which is therefore a row. Setting the orientation to "V" would of course create a column. Rows can contain columns and vice versa. Tweaking these settings is how you could create an incredibly complex nested row/column page structure, if you so chose.
There are other parameters you can tinker with. Changing "ordinal" will change the order in which this content-node appears (since we only have one content-node at this level, it doesn't matter, but if we had a whole row of pages on the toolbar, we could order them using the ordinal parameter). Setting the "active" parameter to false would de-activate this content-node; and on and on...
<component action="update" active="true" objectid="container1" ordinal="-1" orientation="H" type="container" width="300">
<portletinstance action="update" handle="" objectid="portletinstance1"portletref="Portlet_Charlie"></portletinstance>
</component>
Inside the component definition for the row on our page, you can see that we have put a portletinstance object with portletref set to Portlet_Charlie. This value must match the uid of the portlet that you wish to put in this container.
So here it is. Let's save this file as import_pages.xml and execute:
xmlaccess.bat -in C:\temp\import_pages.xml -user wpsadmin -pwd wpsadminpwd -url http://portal.example.com/wps/config
Once our import is complete, fire up a browser and go check out your brand new portal! Wunderbar! You should see your label with a page that has a portlet on it. Experiment.
Of course you can also go further and assign permissions to your objects using XML, or you could create XML files to remove portlets but leave the pages and so forth and so on.
Make liberal use of the example files in C:\WebSphere\PortalServer\doc\xml-samples, or the InfoCenter documents regarding XML Access. These pages are currently located at http://publib.boulder.ibm.com/infocenter/wp51help/topic/com.ibm.wp.ent.doc/wps/admxmlai.html.