Bill Benac's Blog

Bill Benac's Homepage
Bill Benac is a consultant in the West Region of BEA's Business Interaction Division. He has worked with dozens of BEA and Plumtree customers since the year 2000.

Want to remove /portal from the URL of your portal?

First take care of these prerequisites:

• Install base ALUI 6.1 MP1
• Install P1
• Load portal at http://company.com/portal/server.pt. It works!
• Because of a bug in MP1 related to alternate virtual directories, you need to also install the CF AquaLogicInteraction_6.1.1.325722. This does not apply to earlier or later releases. I'm sorry to say the only way to get that CF is to ask customer support for it. That's how CFs work.

But as we already decided, you don't like that default URL. You want to remove /portal entirely. So set up your machine with Metabase Explorer to easily copy your IIS config from the /portal virtual directory to your root directory. Metabase Explorer is part of the IIS Resource Toolkit available here.

Let's use it:

• Launch Metabase Explorer (Start->IIS Resources->Metabase Explorer->Metabase Explorer).
• Navigate the tree to the /portal virtual directory. This may be at LM/W3SVC/1/ROOT/portal.
• Within /portal, right-click on ScriptMaps and copy.
• Within /ROOT, right-click on ScriptMaps and paste.
• Within /portal, right-click on Path and copy.
• Within /ROOT, right-click on Path and paste.

Now you've got IIS configured. Let's move to the portal and get it squared away:

• Open %ALUI_HOME%\settings\portal\portalconfig.xml and edit it to remove "portal/" from the following settings:
  • VirtualDirectoryPath
  • AdminSiteBaseURL
  • SSOVirtualDirectoryPath
• Save the file
• Restart IIS

You should now be able to browse to http://company/server.pt. It worked for me!

In the case of ALUI 6.5, I was able to do this without worrying about a CF. In the case of ALUI 6.1.0.1 and Plumtree 5.0.4, I never tried removing the /portal virtual directory entirely, but I was able to rename that directory without difficulty so I believe renaming the virtual directory to "/" will not pose a problem.

Finally, as a bonus, let's say you don't like the server.pt extension. On IIS it turns out, you can use anything that ends in .pt. So you might choose to publish your portal's URL as something more apt such as http://company.com/a.pt.

Please let me know how this works for you. These aren't battle tested instructions, and this may not be a "supported" configuration. If you deploy this and have many users hitting the portal on a sustained basis, let me know with a comment. Or if you find my instructions are buggy? Let me know that too.

Enjoy!

Upgrade Presentation: BEA Participate 08

Validate Your Work During Upgrades

I've taken to following a test plan during these upgrade activities to double check that we complete every step on every server.

Most steps end up creating a finger print of some sort. For example:

• Running the ALUI installer changes the timestamp on AquaLogicInteraction_silent.properties to the present
• Installing a CF changes the timestamp on a DLL or JAR to the date the CF was released
• Updating the license.bea file changes its timestamp to the present
• Carefully copying back an i18n file with your customizations changes its timestamp from the default time
• Changing those various setting for foo results in new values for bar being put in place

And most of those fingerprints can be verified from the command line. You can easily check a timestamp using the dir or ls command. And you can use grep to find a section of a config file.

So what I've done of late is create a series of commands that I can paste into the prompt on a computer to check every server in the upgrade to verify an upgrade activity is complete. I put these into a spreadsheet. The first page allows me to enter the list of servers in my upgrade. The second page generates these verification commands for every server. As the system administrators go through each step of the upgrade, I copy columns from my spreadsheet into a command prompt, and I get a quick visual for every server whether the activity is complete. For example:

grep -1 set.LD_LIBRARY_PATH  \\ALUI-AS-01\plumtree\ptws\6.1\settings\config\wrapper.conf
grep -1 set.LD_LIBRARY_PATH  \\ALUI-IM-01\plumtree\ptws\6.1\settings\config\wrapper.conf
grep -1 set.LD_LIBRARY_PATH  \\ALUI-IM-02\plumtree\ptws\6.1\settings\config\wrapper.conf
grep -1 set.LD_LIBRARY_PATH  \\ALUI-JS-01\plumtree\ptws\6.1\settings\config\wrapper.conf
grep -1 set.LD_LIBRARY_PATH  \\ALUI-SS-01\plumtree\ptws\6.1\settings\config\wrapper.conf

I've done this in several upgrades, and it seems like for about half of those I find something had been missed. I can immediately point this out to the server admin, and we quickly get back on track. It's a very cheap test in terms of time, but it can save hours of debugging trouble at the end of the upgrade.

Take a look at my spreadsheet. You'll want to update it according to your needs, but it should get you started down a path of sweet success.

Enjoy!

Simplify Installation of Critical Fixes

A CF usually consists of a readme file and one or two DLLs or JARs. The readme describes the issues addressed by the fix and includes instructions on how to install it. The instructions though often have several steps. You can avoid manually doing this work though. Consider these instructions I recently received that are typical:

I am reluctant to use those steps for several reasons:

• In a large enterprise environment, it's can be tedious to follow those many steps on every portal server in every dev, test, and prod environment. The task grows if you have a few critical fixes that apply to your environment.
• Often time is of the essence, and anything that can save a minute or two during a system change window is worth doing.
• Every manual step opens the possibility of variance and error. This is even more of an issue during a late-night maintenance window when people's mental acuity can slide.
• Often system administrators process requests at their own pace, and I am not there to watch them install a CF. I'm less confident things are installed properly if they have several steps.

I am sure many others would agree with these reservations. So what can we do? Wrap the CF up in a batch file that does all the steps and logs it to a central location. What I do is create a folder on a network share that contains the CF documentation, the CF JARs or DLLs, and a batch file with a name like "install-cf-300253.bat." The batch file looks something like this:

set path_of_new_file="\\fileshare\alui\AquaLogicInteraction_6.1.1.316478"
set cfversion=6.1.1.316478
set logfile=%path_of_new_file%\ran.%cfversion%.%COMPUTERNAME%.log
set aluihome=i:\apps\plumtree
set servicename="w3svc"

@echo on
echo ----------- %date% %time% :: Begin install >> %logfile%
net stop %servicename% >> %logfile%


set thelib=openhttp.dll
echo Backing up previous %thelib% (2 locations)... >> %logfile%
move %aluihome%\ptportal\6.1\bin\assemblies\%thelib% %aluihome%\ptportal\6.1\bin\assemblies\pre.cf_%cfversion%.%thelib%.old   >> %logfile%
move %aluihome%\ptportal\6.1\webapp\portal\web\bin\%thelib% %aluihome%\ptportal\6.1\webapp\portal\web\bin\pre.cf_%cfversion%.%thelib%.old  >> %logfile%
echo Copying in new %thelib% (2 locations)... >> %logfile%
copy %path_of_new_file%\%thelib% %aluihome%\ptportal\6.1\bin\assemblies\%thelib% >> %logfile%
copy %path_of_new_file%\%thelib% %aluihome%\ptportal\6.1\webapp\portal\web\bin\%thelib% >> %logfile%


net start %servicename%  >> %logfile%

@echo off
pause

Then instead of giving the server administrator a long list of instructions, or instead of having error-prone steps on my list of late-night upgrade activities, I just say:

The script stops the service, backs up the necessary files, copies in the new ones, starts the service again, and logs all this activity to my central fileshare for easy auditing.

It's also easy to adapt this batch file for other CFs. When the CF has more than one DLL or JAR, for example, you can copy the block that begins with "set thelib=openhttp.dll" and modify the library you need. You do the same with the service name (perhaps you are working with the Automation server or Analytics).

Enjoy.

What's in that Patch?

BEA support suggested we roll back to the files as they had been before the Patch 1 installer, but since we did MP1 and Patch 1 as part of the same activity, we didn't have the backups support would have hoped for. Plus, we weren't sure whether Patch 1 modified config files.

I decided to identify the exact files that were modified to see if they could be easily backed out by just replacing some JARs and DLLs, and indeed, that was the case. My approach might be helpful to others. I did the following:

1. Install MP1 on a fresh VMWare host
2. Change the date on the VMWare host to tomorrow's date.
3. Set the timestamp on every file in the c:\bea\alui directory to the date of the VMWare host. I did this with the following command using unix-esque executables from unxutils:

   c:\add2path\find.exe c:\bea\alui -exec touch {} ;

4. Backup the c:\bea\alui directory as c:\bea\alui-mp1
5. Restore the date on the VMWare host to the correct date
6. Install MP1 Patch 1. This will result in timestamps of today or earlier for any file placed on the server by Patch 1.
7. Search for all files modified anytime up until today but not including tomorrow
8. Delete from c:\bea\alui-mp1 every file except those on the list of modified files
9. We were only concerned with rolling back Patch 1 on the portal servers, so I made a zip file of the remaining contents of c:\bea\alui-mp1\ptportal. I named the zip file ptportal-remove-patch1.zip

We then unzipped ptportal-remove-patch1.zip over the ptportal directory on the customer servers with good results. The following is the list of files that were installed or modified with Patch 1. Where the full path is not given, the file was under c:\bea\alui.

ptportal/6.1/bin/assemblies/openhttp.dll ptportal/6.1/bin/assemblies/openhttp.pdb ptportal/6.1/bin/assemblies/openkernel.dll ptportal/6.1/bin/assemblies/openkernel.pdb ptportal/6.1/bin/assemblies/openkernelsearch.dll ptportal/6.1/bin/assemblies/openkernelsearchimpl.dll ptportal/6.1/bin/assemblies/plumtreeserver.dll ptportal/6.1/bin/assemblies/plumtreeserver.pdb ptportal/6.1/bin/assemblies/pmb.dll ptportal/6.1/bin/assemblies/pmb.pdb ptportal/6.1/bin/assemblies/portalpages.dll ptportal/6.1/bin/assemblies/portalpages.pdb ptportal/6.1/bin/assemblies/portaluiinfrastructure.dll ptportal/6.1/bin/assemblies/portaluiinfrastructure.pdb ptportal/6.1/bin/assemblies/ptportalobjects.dll ptportal/6.1/bin/assemblies/ptportalobjects.pdb ptportal/6.1/bin/native/openkernelsearch_4-2j_0.dll ptportal/6.1/bin/native/openkernelsearch_4-2j_1.dll ptportal/6.1/bin/native/openkernelsearch_4-2j_2.dll ptportal/6.1/bin/native/openkernelsearch_4-2j_3.dll ptportal/6.1/lib/java/automationserver.jar ptportal/6.1/lib/java/openhttp.jar ptportal/6.1/lib/java/openkernel.jar ptportal/6.1/lib/java/plumtreeserver.jar ptportal/6.1/lib/java/pmb.jar ptportal/6.1/lib/java/ptportalobjects.jar ptportal/6.1/webapp/portal/web/bin/openhttp.dll ptportal/6.1/webapp/portal/web/bin/openhttp.pdb ptportal/6.1/webapp/portal/web/bin/openkernel.dll ptportal/6.1/webapp/portal/web/bin/openkernel.pdb ptportal/6.1/webapp/portal/web/bin/openkernelsearch.dll ptportal/6.1/webapp/portal/web/bin/openkernelsearchimpl.dll ptportal/6.1/webapp/portal/web/bin/plumtreeserver.dll ptportal/6.1/webapp/portal/web/bin/plumtreeserver.pdb ptportal/6.1/webapp/portal/web/bin/pmb.dll ptportal/6.1/webapp/portal/web/bin/pmb.pdb ptportal/6.1/webapp/portal/web/bin/portalpages.dll ptportal/6.1/webapp/portal/web/bin/portalpages.pdb ptportal/6.1/webapp/portal/web/bin/portaluiinfrastructure.dll ptportal/6.1/webapp/portal/web/bin/portaluiinfrastructure.pdb ptportal/6.1/webapp/portal/web/bin/ptportalobjects.dll ptportal/6.1/webapp/portal/web/bin/ptportalobjects.pdb ptsearchserver/6.1/bin/native/queryd.exe c:/bea/utils/utils.jar

But wait, you say. Why did you mess around with changing the timestamps on the files? Why didn't you just backup the MP1 directory, then install Patch 1 and compare the two directories? The concern there is that it's hard to tell whether a config file is identical both before and after Patch 1 is the same because it wasn't touched (good information) or because it was overwritten with an identical file that had the same timestamp (confusing). And if that file that is placed identically by the installers needs some modifications for your environment, then you really need to know whether the installer would overwrite your changes.

If you ever have the situation were you need to know after the fact what changed, then you might take this approach.

Enjoy,

Bill

Configuring ALUI when SQL Server Uses a Named Instance

MSSQL 2000 and 2005 allow multiple instances of the database to run on the same installation. When you create these instances, you distinguish them by a name that lets you refer to them in a human-centric way and a port number that is used across the network in a computer-centric way. For example, I might create a SQL Server instance named stagingdb to run on port 2048.

You can see how your server is configured as follows:

• Go to Programs -> Microsoft SQL Server 2005 -> Configuration Tools -> SQL Server Configuration Manager.
• Within that tool, go to SQL Server 2005 Network Configuration -> Protocols for {instance-name} -> TCP/IP Properties
• Go to the IP Addresses panel, then scroll down to the TCP Dynamic Ports to see what port number corresponds to the instance.

Microsoft tools such as Query Analyzer and SQL Server Management Studio let you connect to this in a friendly way, for example, I can specify that I want to connect to the database "mymachine\stagingdb," then behind the scenes it will connect on port 2048 to that instance.

However, if I have a Java application that is not aware of the Microsoft concept of named instances, then I will need to connect to it using the database "mymachine" and the port "2048."

So what about your portal? When you go through the Portal Configuration Manager (which has the same UI for Java and for .NET portals), the common UI doesn't allow you refer to your database using the instance name. You've got to drop the name and just use the port. For example, on my machine, I have this:

Notice that even though the Portal Configuration Manager prompts me with the default MSSQL port of 1433, I put in 1555. Also notice that even though my instance happens to be "localhost\SQLEXPRESS," I refer to it here as simply "localhost."

How to Revive a Failed Search Node

Ironically, you can't use the tools to reset a node if the node is broken and won't start. But you can go on the file system and clean it up with these steps--though make sure the node really is stopped before you do this.

In shorthand for the Unix-minded:

set search_home=d:\bea\alui\ptsearchserver\6.1
set node=alui-ss-0101
rm -rf %search_home%\%node%\index\*
mkdir %search_home%\%node%\index\1
echo 1 > %search_home%\%node%\index\ready
cd %search_home%\%node%\index\1
..\..\..\bin\native\emptyarchive lexicon archive
..\..\..\bin\native\emptyarchive spell spell

Or more prosaically for those who prefer Windows and a mouse:

1. Go into the index folder of the node. On my machine, it's d:\bea\alui\ptsearchserver\6.1\bbenac0201\index.
2. The index folder will contain a folder named 1. Open this folder and delete all its contents.
3. The index folder may also contain a folder named 2. If this is the case, delete the folder 2.
4. The index folder should contain a file named "ready." Open it and make sure it contains just the number 1. This "ready" file tells the node to look within folder 1 for its content.
5. Open a command prompt within the folder 1.
6. Run these commands, the first of which should create about 8 files, the second of which should create about 7:

   ..\..\..\bin\native\emptyarchive lexicon archive
   ..\..\..\bin\native\emptyarchive spell spell

The Basics of Configuring and Using Search Cluster Checkpoints

If your ALUI system isn't set to do daily checkpoints, configure them as follows:

1. Browse to the portal's admin section, then select the utility "Search Cluster Manager."
2. In the left navigation, select "Checkpoint Manager."
3. On the far right, click "Initiate Checkpoint" to open the Checkpoint Scheduler.
4. Select the "Scheduled" radio button, select today's date, set a time, and set it to repeat every 1 day. Click OK.
5. After the Checkpoint Scheduler closes, you'll see in the "Checkpoint Activity Status" section when the next scheduled checkpoint will run.
6. Click "Finish" and your system will then backup your search index daily into checkpoints.

If at some point you realize your cluster is corrupt and you need to restore it, and you've been creating checkpoints periodically, then:

1. Makes sure all the nodes in the search cluster are started. If one of the nodes won't start, you might want to use these instructions to revive it.
2. Browse to the portal's admin section, then select the utility "Search Cluster Manager."
3. In the left navigation, select "Checkpoint Manager."
4. In the center of the screen you'll see a list of checkpoints. The most recent ones will show themselves as "Available" in the last column.
5. Click on the checkpoint you want to restore. Its row will change from white to light green.
6. Click the "Restore Checkpoint" button on the right side of the screen below the list of checkpoints.
7. Watch the "Checkpoint Activity Status" section to see status. Use the refresh button at the top of the screen to update status. It may show messages like "Node pswwwlab-0301 completed copying - 0%."
8. When it completes, you'll see in the "Named Restore Status" area something like this:

   Cluster is currently in a named restore state.
   Cluster restored from c:\\bea\\alui\\ptsearchserver\\6.1\\cluster\checkpoints\0_1_0.
   The named restore state - SUCCEEDED.
   The named restore must either be discarded or committed.

9. Finally, you must "Commit" the checkpoint by using the "Commit" button at the bottom right of the screen.
10. At this point the search cluster will be restored.

Note that by default, the most recent three search checkpoints are stored. So on the fourth day, the first checkpoint gets deleted. In some cases, you may prefer to have more or fewer checkpoints. If this is the case, then edit the cluster.ini file in your search cluster. Add the following new parameter to set the desired number of saved checkpoints, in this case, 2:

RF_NUM_CHECKPOINTS_SAVED=2

Restart ALUI Services through External Operation Jobs

Such division of labor has its strengths, but in our case, the server administrator trusts the judgment of the portal administrator when it comes to restarting services--at least, in the development environment. So we decided to cut out the middle man.

We did this through the portal's external operation feature. The portal tells you "An external operation is used to execute batch files, shell scripts, or other system programs from the portal. Common examples of external operations include running shell scripts which can perform document queries, portal pings, or e-mail snapshot query results to subscribed users. Once created, these actions are scheduled as portal job operations."

Create the Batch File
To start we had to make sure we had the tools that we intended to use: sc.exe and sleep.exe. Sc lets you control services on local and remote servers. Sleep lets you wait between commands. Some of the latest Windows servers install these tools by default. If your server doesn't have them, then install the Windows Server Resource kit.

Then we wrote a batch file named restart.aluidev-03.service.bat.

set TargetService=SearchClusterUI
set ServiceHost=aluidev-03
set PathToSC=c:\WINNT\system32
set PathToSleep=e:\progra~1\Reskit

set LogFile=restart.service.log

echo %date% %time% Entering sequence to restart %TargetService% >> LogFile%
%PathToSC%\sc.exe \\%ServiceHost% stop %TargetService%
%PathToSleep%\sleep.exe 10
%PathToSC%\sc.exe \\%ServiceHost% start %TargetService%
%PathToSleep%\sleep.exe 30
%PathToSC%\sc.exe \\%ServiceHost% start %TargetService%
%PathToSleep%\sleep.exe 60
%PathToSC%\sc.exe \\%ServiceHost% start %TargetService%

echo %date% %time% Restarted %TargetService% >> %LogFile%

The script restarts the BEA ALI Search Cluster Manager service on the aluidev-03 server. A few comments on it:

• The sc command requires that you use the service name rather than the display name. So we went to the Services console, looked at the properties of the desired service, and we found the service name is SearchClusterUI.
• We call the sc and sleep commands using fully qualified paths because the portal external opration won't have the Path environment variables.
• After stopping, we try starting several times. The reason for this is that some services take longer than others to stop. If the service stops quickly, then our first start command will restart it. But if it stops slowly, we may not be able to start it on the first couple attempts. But after a total of 100 seconds? It should be ready to start.
• For auditing purposes, we log each time this batch file is used.

We select one of the ALUI automation servers as the host for our script and place the batch file in its %pthome%\ptportal\6.1\scripts directory. After we test the script and see that it works, we're ready to move on.

Create the Portal Objects
In the portal we now create an External Operation. We set the command as follows:

".\restart.aluidev-03.service.bat"

We then schedule this External Operation via a Job, and then we make sure the folder for that Job object is registered in the Automation Service to be run by the automation server with our batch file.

We also make absolutely sure the security on the External Operation and Job are set such that only administrators can use them.

Can the Parameters be Passed to the Batch File?
The server administrator realized that using the above steps, he would need to create a separate batch file for every service on every server. Sounds like a pain, so couldn't he just pass the parameters from the External Operation to the batch file? Technically, yes, this is possible. But it can get risky. You probably don't want the portal administrator to be able to arbitrarily restart any service on those other machines in your rack.

But you might allow them to just restart services on a specific server. This might be reasonable if you have a dedicated development server. Anyway, to do that you would first edit your External Operation to pass in a parameter of the desired service name:

".\restart.aluidev-03.service.bat" "SearchClusterUI"

Then you would edit the previous batch file so that it takes its service name from the parameter. The batch file would then begin with this:

set TargetService=$1

Enjoy, and make sure to use this power judiciously!

Deploying Portlets with the Server API

Portlet developers write code that integrates to the portal with varying depth. Let's not consider the simplest side of the spectrum where a pagelet has no ALUI-specific code and is only a portlet because the portal registered it. Examples of these are the Google Gadgets I previously wrote about.

We'll consider only portlet integrations that use an API to leverage ALUI features. But API, an acronym that stands for Application Programming Interface, needs some disambiguation since ALUI uses it in at least three ways related to portlets.

[1] First, there's the "BEA ALI API Service," a component installed on your ALUI system. Some portlets and other applications send SOAP requests through this service to get information into and out of the portal.

[2] Next is the AquaLogic IDK API. This used to be called the EDK, or just the remote API. A portlet can include the libraries for this API in its bin or lib directory. Such a portlet may run on a network external to the core portal, and can even be hosted by a third-party. These IDK libraries pass information through HTTP headers that only make sense in the request and response context of a portal. Portlets using the IDK can do things like get and set preferences from the portal database. Some IDK callls use the API service for deeper portal interaction such as creating certain types of portal objects. Usually developers require nothing more than the IDK to write their portlets.

A request from the portal to a portlet may include the following headers, which illustrates details available to the IDK:

CSP-Protocol-Version: 1.3
CSP-Can-Set: Gadget-User,User
CSP-Gateway-Specific-Config: PT-User-Name=Administrator,PT-User-ID=1,PT-Stylesheet-URI=http://www.a.com/imageserver/plumtree/common/public/css/mainstyle-en.css,PT-Hostpage-URI=http%u003A%u002F%u002Flocalhost%u002Fportal%u002Fserver%u002Ept%u003Fopen%u003Dspace%u0026name%u003DMyPage%u0026id%u003D9%u0026cached%u003Dtrue%u0026in%u005Fhi%u005Fuserid%u003D1%u0026control%u003DSetPage%u0026PageID%u003D208%u0026,PT-Community-ID=0,PT-Gadget-ID=226,PT-Gateway-Version=2.5,PT-Content-Mode=1,PT-Return-URI=http://localhost/portal/server.pt/gateway/PTARGS_16_0_0_0_43/a?b=c&,PT-Imageserver-URI=http://www.a.com/imageserver/,PT-User-Charset=UTF-8,PT-SOAP-API-URI=http://bbenac01:11905/ptapi/services/QueryInterfaceAPI,PT-Portal-UUID={bcdd12067bd44a26-10ff664aba20},PT-Class-ID=43,PT-Guest-User=0
CSP-Aggregation-Mode: Multiple
CSP-Global-Gadget-Pref: MaxObjectsToExamine=100

A response might have something like the following, sending a command to the portal about how the portlet should display (a very simple example):

CSP-Display-Mode: Hosted

[3] Finally, we have the core server API. This is the full library of DLLs or JARs that installs on a server that hosts components such as the ALUI Portal, Admin Portal, API Service, or Automation Service. The server API runs the core portal features, and developers use it for their portlets when they require more than what the IDK offers. Such portlets might create and delete users, audit portlet objects, or modify experience definitions.

Deploying Server-API Portlets

A portlet or other application that uses the core server API needs can easily be deployed on the same server as an ALUI portal or admin portal server since that box has all the server API libraries. It should work just as well to install the server API portlet on an automation server, but I recently found it didn't. Why not?

It turns out the ALUI 6.1.0.1 installer (that I was testing with) chooses not to drop some important files on the server when you install just the Automation Server component. This is a small annoyance easily overcome. At least on Windows, these are the required steps:

1. Make sure your Automation Server is installed and running properly.
2. Copy plumtree\ptportal\6.0\bin\assemblies from a portal server onto the automation server
3. Edit plumtree\settings\common\serverconfig.xml so that the adonet-license-file-directory value is the path to that assemblies directory.

For your Java portlets that use the server API? There's a good chance that they'll run on an Automation Server without needing any extra steps. The reason is that first, the Automation Server always runs on Java, and it already installs \ptportal\6.1\lib\java, which has the same libraries that the missing assemblies directory has. Second, the serverconfig.xml value for adonet-license-file-directory only applies to ADO connections.

My untested bet is that a machine with just the API service would behave like one with just the Automation Server component. Again, this is in always in Java.

Deploying Server-API Portlets on a Portlet Server

Some customers want to keep their portlets running on their portlet servers rather than moving them onto the portal server or the automation server. That's a fine idea, and it's accomplished by installing a core component on the portlet server. You can disable the service for that core component, and so essentially, this lets your portlet server run server API portlets without the overhead of that core server component.

Replicating the ALUI Grid Search Index

So there is no longer a need to write special scripts to replicate the 6.1 search index, right? Not if you are just trying to make your live index redundant. So the 6.1 product dropped the old "replicate" tool.

But larger customers have a use case that still requires index replication. If the customer has a failover datacenter for use when the primary system is unavailable for one reason or another, then the customer needs to replicate the search index to that site, and how do you this? It used to be very easy. Consider the following that did the job on ALUI 6.0 (in this case on RHEL). It was two easy commands:

SEARCHHOME=/usr/local/plumtree/ptsearchserver/6.0

echo ----------- copy the master search index to a backup directory
$SEARCHHOME/bin/replicate -incr_backup aqlsearch 15244 $SEARCHHOME/indexmaster $SEARCHHOME/incr_backup

echo ----------- restore the backup index to the failover search server
$SEARCHHOME/bin/replicate -restore aqlsearchfail 15244 $SEARCHHOME/index $SEARCHHOME/incr_backup

You can still attain the same result in the ALUI 6.1 releases, but hold onto your hat. It's a wild ride.
• Copy the %searchcluster%\checkpoints and %searchcluster%\requests folders from the origin server to a temporary directory on the destination server
• Make sure all search nodes and services are running properly
• Run the following command to empty the checkpoints folder and set the requests folder to only have an indexQueue.segment:
  
         %searchhome%\bin\native\cadmin.exe purge --remove
  
  
• Stop all nodes and services
• Copy the origin checkpoints and requests folders over their corresponding destination folders, including the indexQueue.segement:
• Replace the cluster.nodes file(s) in the checkpoints folder(s) with the one from destination cluster base. For example, copy %searchcluster%\cluster.nodes over %searchcluster%\checkpoints\0_106_30976\cluster.nodes
• Start all nodes and services. The nodes will restore from the checkpoint. If you have a large index, the nodes may take a while to start (five minutes for 1.2 million objects). If you have multiple nodes, they may take another several minutes to move from stall/recover.

Other migration methods may have trouble migrating checkpoints from a system with low-numbered checkpoint folders to a destination system with higher-numbered folders. This method however has no such problem.

These steps have been tested only on systems that use a single partition. The number of nodes in the partition is not significant; these steps have been tested when restoring the cluster to destination systems with different numbers of nodes than the origin.

The directories can be copied from the source while all services are up, and this should not cause synchronization issues later during the restore. So if you take a checkpoint, then later make several changes to the index, then later copy the checkpoints and requests folders to the destination, the destination will have all the changes in its restored index, including those made after the checkpoint.

This process was created with significant input from Dax Farhang, the product manager responsible for the search product. If we're lucky, he'll cook this feature into the 6.5 ALUI product so that this post will become obsolete. In the meantime, enjoy.

Easily Configure Grid Search Load Balancing

The reality is load balancing can be confusing. Some applications require sticky load balancing (like the portal), some require shared file system access (like the document repository), some require an external load balancer (like the image server), and some are load balanced internally by the portal (like most custom portlets). So not surprisingly, some customers approach load balancing with trepidation, or perhaps they just expect implementing it will require mad voodoo engineering skills.

Enter Grid Search. The 6.1 version of the search server was rewritten with a raft of design changes including improved scalability. Previously it didn't fully scale. Now it has a tool called the Search Cluster Manager, which tells the story, right?

Actually, though the Search Cluster Manager's name correctly says "we can cluster," it gives many people a false idea about how clustering works. Administrators use the Search Cluster Manager to add a new search node to the cluster, but that's it. The Search Cluster Manager isn't required at runtime for end users who need their queries managed across the multiple nodes in the cluster. This component would be better named something like "Search Cluster Administration." Those who are used to configuring components to sit behind load balancers frequently expect the portal needs to connect to the cluster manager to serve content from the nodes.

In fact, when an administrator installs a new search node and adds it to the cluster through the Search Cluster Manager, the product goes on auto-pilot, and the load balancing is done. When the portal had only one search node, it was configured in the Search Server Manager to use that single node as the search cluster contact node. The magic is that after adding a second node, the contact node doesn't need to change. The search server is smart enough to notify the portal of any other node participating in the cluster. So the portal knows all the servers toward which it can distribute search traffic.

When you click the Search Service Manager's "Show Status" button, you can verify that it knows of all your nodes even though it's configured to use just one of them as the Cluster Contact Node. Note that at the bottom of the page, each node is listed:

You can read a full document I put together that several people have told me provides useful enhancement to the standard documentation. It discusses installation, creation of nodes, the rationale behind your choices as you do this, and a little bit on load balancing. Feel free to download the file.

Using Google Portlets in ALUI

My first response is that I like Google's terminology. Ahh, the good old days before Plumtree changed its jargon to the "industry standard" of "portlets" instead of the arguably better "gadgets."

And functionally? Google's offerings are standard JavaScript-driven syndicated gadgets. Basically, they provide content you can display within your own portal. You can go to the Google gadgets website, read up on the concept, then click into the list of gadgets to see whether any are appropriate for you. The selection is great. Some are pure fun, designed for your blogging teenage sibling or child, such as the Tetris game. Others are likely candidates for a company's intranet, such as the weather and stock quotes portlets. Here's the (depressed) BEA stock quote as it displayed in my portal:

It's very easy to add this stuff to your portal. You pick the content you want, fill out some parameters for the desired size and colors, maybe a zip code for a weather portlet or a stock symbol, then click to get the HTML that you'll use for your portal to grab the content. The HTML string they provide is a single line. The format will be something like this:

<script src="http://gmodules.com/ig/ifr?url=http://content.provider.com/file.xml&various_parameters;output=js"></script>

If you want to get content into your portal quickly, this content could be very attractive to you.

On the other hand, the Google solution isn't perfect. For example, the content displays in your portal with its own stylesheet information, so it's likely that your portal stylesheet won't match the Google content's stylesheet. Portal managers are all over the map as far as how much they care about consistent look and feel. Some will find this anathema, and others won't even notice. Take a look at this, for example, where neither the font nor color of the Google portlet matches my portal:

Also, you may find it annoying that users are one click away from leaving your portal if you use these. You can't keep the clicked content within your portal, like you would with a custom portlet. For example, if you submit flight details into the portlet above, you'll go to the FlightStat.com website outside of the portal. Even if you were to set the URL of the content-provider as a gateway URL prefix for the web service and specified that gatewayed content should display under the portal banner, you still wouldn't be able to affect this behavior. That's because the content loads up directly by the user's browser via JavaScript instead of getting passed through the portal server where it would have its URLs manipulated based on those web service settings.

It's important to realize that Google's gadgets provide just one example of what many sites are doing: providing content that you can stick in your portal. Google is great because you can be confident it won't go away, and it's a magnet for content providers. But there are other options out there:

Moreover.com, which many years ago started providing news content this way, still lives. They provide great options for customizing presentation, since instead of just giving a single line to describe the content, they give you many dozens of lines that include their stylesheet definition, whether to include dates, and so forth. See how nicely the New York Times headlines appear in my portal:

Also, many of the originators of content let you sign up to get a snippet of code to create a portlet. Weather.com, for example, offers it here.

And then there are vast catalogs, filled with junk, but with jewels too, such as what you find at widgetbox.com or directory.snipperoo.com. I was feeling cheery, so I grabbed a nice terror alert portlet from widgetbox:

Anyway, the point is that this content is abundant. And how do you put this stuff into your ALUI portal exactly? Any customer can follow these steps:

1. Create an html file such as stockquote.html that contains the code snippet from Google (or whomever).
2. Place that file on a webserver of your choosing. You might drop in on your image server (I know you have one) in %pt_home%\ptimages\imageserver\RemoteGadgets.
3. Browse to the page to make sure you have the URL right: http://myserver.company.com/imageserver/RemoteGadgets/stockquote.html
4. Create a new web service, selecting a remote server object that points to your web server and entering the URL of your portlet:
   
5. Create a new portlet based on your web service.
6. Add the new portlet to your MyPage or Community page.

The folks who suggested I post about Google's gadgets? They gave me screenshots showing how this can be even easier with the ALUI Publisher product. The nice thing there is that you can use Publisher's Announcement template to immediately create a portlet that takes arbitrary HTML content (your Google gadget snippet) without requiring you to put anything on the file system as in my previous instructions. It's basically driven by portlet preferences, and if you know much about those, then you know that you can create this same affect with a custom-written preferences portlet that won't require you to purchase a big product like Publisher. Here are those Publisher screenshots, and you can imagine how this would work with your own prefs portlet too:

• Create a new Announcement portlet in the portal (AquaLogic Interaction). In the administrative preferences for that portlet toggle to the source view:

  

• Insert the tag and click finish:

  

• Add the portlet to your page.

Enjoy.

Using ALUI URLMappings, especially for debugging

This article will explain the URLMapping feature, show a common but limiting configuration with proxies or SSO, and show alternate configurations that are more flexible.

What are URLMappings?
The portal needs to know how to write its HTML so that links go to URLs that make sense to the end user. In the simplest portal configuration, users browse directly to the portal (http://simple/portal/server.pt), and the portal returns a page with links that continue to use http://simple/portal/server.pt. No mapping required. But consider a more advanced configuration that involves a load balancer. Users browse to http://public/portal/server.pt, then the load balancer fowards traffic to http://serverA/portal/server.pt and http://serverB/portal/server.pt. The portals needs to return HTML to the end user with the base of http://public instead of http://serverA. URLMappings instruct the portal how to do this.

How URLMappings Work
URLMappings are configured in \plumtree\settings\portal\portalconfig.xml or \plumtree\ptportal\5.0\settings\config\x_config.xml. You can create as many URLMappings on a system as you'd like. Each mapping has three elements:

• URLFromRequest is the URL the portal sees in the incoming request. This isn't necessarily what the user typed in, such as when the portal is behind a load balancer or proxy. The portal tries to match the incoming request to the URLFromRequest value, and if it finds a match, then it will map according to the values found in the next two elements. You can look in PTSpy for a message like this one to know what the portal sees: Entering handleRequest: GET http://serverA:80/portal/server.pt.
• ApplicationURL is the base URL the portal will use to rewrite links for HTTP traffic.
• SecureApplicationURL0 is the base URL the portal will use to rewrite links for SSL traffic.

The portal evaluates each URLMapping in its config file, and once it finds a matching URLFromRequest, it can rewrite URLs. The portal must find a match though, and so you must make the final URLFromRequest setting an asterisk to handle any case not matched by prior URLMapping rules (an IP address, for example).

Common Configurations
I show examples in the XML format used by 5.x portals since visually its more concise than the 6.x format. The concept is the same in both versions though. By default, the URLMapping section looks like this in 5.x portals:

<URLFromRequest0 value="*" /> 
<ApplicationURL0 value="*" /> 
<SecureApplicationURL0 value="*" /> 

With a load balancer, the URLMapping section could be as simple as this in the case that the user types in http://public to get to the load balancer, then the load balancer forwards traffic to http://serverA:

<URLFromRequest0 value="*" />  
<ApplicationURL0 value="http://public/portal/server.pt" />  
<SecureApplicationURL0 value="https://public/portal/server.pt" /> 

Advanced Configurations
Many customers don't go further than the above mappings. But lets say you have http://serverA and http://serverB behind your load balancer, and you want to be able to browse to a specific server. You could use the following URL mapping to do this. It tests whether the user requested a specific machine. If they did, they'll stay on that machine. Otherwise, they'll use the load balaner's URL:

<URLFromRequest0 value="http://serverA/portal/server.pt" />  
<ApplicationURL0 value="http://serverA/portal/server.pt" />  
<SecureApplicationURL0 value="https://serverA/portal/server.pt" /> 

<URLFromRequest1 value="http://serverB/portal/server.pt" /> 
<ApplicationURL1 value="http://serverB/portal/server.pt" /> 
<SecureApplicationURL1 value="https://serverB/portal/server.pt" /> 

<URLFromRequest2 value="*" />  
<ApplicationURL2 value="http://public/portal/server.pt" />  
<SecureApplicationURL2 value="https://public/portal/server.pt" /> 

<URLFromRequest0 value="http://localhost/portal/server.pt" />  
<ApplicationURL0 value="http://localhost/portal/server.pt" />  
<SecureApplicationURL0 value="https://localhost/portal/server.pt" /> 

<URLFromRequest1 value="*" /> 
<ApplicationURL1 value="http://public/portal/server.pt" /> 
<SecureApplicationURL1 value="https://public/portal/server.pt" /> 

It turns out there's a bug. Basically, gatewayed portlet content has URLMapping rules applied to it twice. So let's say initial configuration were this:

URLMapping0: http://internal1/portal/server.pt -> http://proxy1/portal/server.pt
URLMapping1: http://internal2/portal/server.pt -> http://proxy2/portal/server.pt
URLMapping3: http://internal3/portal/server.pt -> http://proxy3/portal/server.pt
URLMapping4: * -> http://everything.else/portal/server.pt

So a user browses to their My Page, and the URL for links to portal infrastructure such as other My Pages or Communities would propertly rewrite from http://internal1/portal/server.pt to http://proxy1/portal/server.pt. But within the gatewayed content of the portlet, a second rewriting would occur. In this case it would rewrite http://proxy1/portal/server.pt (which matches to *) to be http://everything.else/portal/server.pt.

The workaround isn't too hard. All you need to do is have a URL mapping section that matches the external URL and says "when this URL is encountered, leave it alone."

You would add mappings such that:

URLMapping0: http://internal1/portal/server.pt -> http://proxy1/portal/server.pt
URLMapping1: http://internal2/portal/server.pt -> http://proxy2/portal/server.pt
URLMapping3: http://internal3/portal/server.pt -> http://proxy3/portal/server.pt
URLMapping4: http://proxy1/portal/server.pt -> http://proxy1/portal/server.pt
URLMapping5: http://proxy2/portal/server.pt -> http://proxy2/portal/server.pt
URLMapping6: http://proxy3/portal/server.pt -> http://proxy3/portal/server.pt
URLMapping7: * -> http://everything.else/portal/server.pt

June 2008

Search this blog:

Archives

June 2008
May 2008
April 2008
March 2008
November 2007
August 2007
May 2007
March 2007

Categories

Recent Entries

Want to remove /portal from the URL of your portal?

Upgrade Presentation: BEA Participate 08

Validate Your Work During Upgrades