Results tagged “Portlets” from Bill Benac

API Check: Diagnostic Application for WCI's API Service


Unfortunately, WCI ships without providing an easy way to validate that the API service works properly. Some system administrators mistakenly believe the API service works if they see the message "Hi there, this is an AXIS service!" That message only confirms the service has been turned on and gives no information about whether it may have fatally failed at startup. To provide real health information for the API service, I've written the API Check application.

This application was tested on ALUI 6.1 and WCI 10gR3.

Contexts for Use

Portal administrators will most likely choose to run the API Check application within the WCI portal as a portlet. Portlet mode is always available when the API Check application is turned on. Some organizations will additionally wish to access the API Check application available outside the portal through its standalone mode. Standalone mode is most useful when the organization performs automated service monitoring such as for a load balancer and needs to see the status without logging into the portal.


In portlet mode, this application presents no security risks. The application will retrieve a login token from the portal's request allowing API Check to connect to the system as the calling user. This is the recommended approach. However, in standalone mode, there is a security risk because standalone mode requires a credential for a portal user be stored within the applications's web.xml file. This should be avoided when possible. If however you do choose to enable standalone mode, then be sure to use the credentials of a user with minimal rights to the portal. No special priviledges need be given to this account, and the account certainly should not have any administrative rights. The automated monitoring should scan for "DBQuerySuccess" to determine the service is up.


This application runs adjacent to your existing %WCI_HOME%\ptws\10.3.0\webapp\ptapi.war file so that it will start and stop as the API service starts and stops. To install:
  • Place apicheck.war into the API service's webapps directory.
  • Import apicheck.pte into your portal. That PTE file is located within apicheck.war's install-resources directory. You can get there via http://localhost:11905/apicheck/install-resources/APICheck.pte (using an appropriate host). The PTE file will create an administrative folder, a community, a remote server, a web service, and a portlet for the API Check application.
  • From the portal admin interface, edit the API Check remote server to go to the proper address.
  • Browse to the API Check community to verify the portlet works.

Optionally, follow these additional steps if you wish to use the standalone mode:

  • Make sure you have the credentials for a portal-based user with low privileges in the portal.
  • Unpack apicheck.war
  • Edit WEB-INF\web.xml such that the values for username and userpass represent the low-rights account that should connect
  • Repack apicheck.war with the new web.xml file
  • Restart the API service
  • Browse to http://localhost:11905/apicheck/index.jsp to validate that it works.

Get the Code

This application is available for download here.

Note: The code was updated on March 20 09 to test the search API with a lookup of communities (fast) instead of users (potentially slow). Read more.

API Check in Portlet Mode


API Check in Standalone Mode

An Invisible Portlet

I had heard of them before, but I had never seen them: Invisible Portlets. Now I can write them.

It turns out there can be a decent use case for an invisible portlet. I wanted to put a stylesheet on a page through a portlet, but I didn't want to have to tweak any of the other portlets to do it. And since the only purpose of my portlet is to deliver a stylesheet, I didn't want the portlet to show up with a header or a title. Perhaps you'll want to use this approach to put some JavaScript on the page for tracking purposes. In any case, the code is pretty simple.

The concept is that when it displays on the page, each portlet object renders with a class ID to let you manipulate it directly. In some cases, you might change the font in the title bar, but in this case, I'm taking the entire region and making it invisible. If you set it invisible through display=none, then it will not be visible to the user, but JavaScript and style instruction still apply to the page.  I use the $$TOKEN$$ concept to access the portet object ID, and that is used in the class ID. Here it is:

<pt:namespace pt:token="$$TOKEN$$" 
xmlns:pt=''/> <script> alert("Portlet $$TOKEN$$ will magically disappear!"); document.getElementById('pt-portlet-$$TOKEN$$').style.display = 'none'; </script> <link type="text/css"
rel="StyleSheet" lang="en" ></link>
For demonstration purposes, that code includes an alert line that will cause the portlet to first notify you that it's really live on the page and then after you acknowledge it, it disappears. You will most likely want to customize the alert message by deleting it :-P

The code is live on this web server, so you can load it into your portal for a look if you'd like. Find it at


Update: A Better Approach

Thanks to Steve who pointed out a better way of getting the result I described above. He suggested setting the display to none in CSS directly rather than through JavaScript. That approach would look like this:

<pt:namespace pt:token="$$TOKEN$$" 

Portlet $$TOKEN$$ should be invisible through CSS.

#pt-portlet-$$TOKEN$$ { display:none; }

The title tells me this is going to be boring to some readers, but I guarantee those who arrive from Google searches will be glad for it--especially since an early discussion of this that used to be on is now gone.

A funny problem arises when you take certain portlets written in .NET and load them into ALUI 6.5 or Oracle 10gR3 portals. The portlets at issue use the EDK/IDK's PRC library. Even though these portlets work fine when loaded into ALUI 6.1 portals, they suddenly fail with this deceptive message:

The underlying connection was closed: The server committed an HTTP protocol violation. at com.plumtree.remote.prc.soap.QueryInterfaceProcedures.GetVersionInfo() in e:\latestbuild\Release\devkit\5.4.x\prc\src\dotnet\portalprocedures\QueryInterfaceProcedures.cs:line 35 at com.plumtree.remote.prc.xp.XPRemoteSession.getAPIVersion() in e:\latestbuild\Release\devkit\5.4.x\prc\src\xpj2c\portalclient\com\plumtree\remote\prc\xp\XPRemoteSession.cs:line 352 at Plumtree.Remote.PRC.RemoteSessionWrapper.GetAPIVersion() in e:\latestbuild\Release\devkit\5.4.x\prc\src\dotnet\portalclient\RemoteSessionWrapper.cs:line 144 at apicheck.WebForm1.PageLoad(Object sender, EventArgs e) in d:\www\api-check\portlet.aspx.cs:line 60

The real problem though is that the application's web.config file needs an extra setting block dropped in just beneath system.web:

<servicePointManager expect100Continue="false" />

You'll have to do this with your custom portlets, but it's may also necessary with portlets that come from Oracle/BEA. I've encountered it with the SharePoint Console, for example.

Enjoy (no hugs though),


Recently I had a conversation with someone about the features available in ALUI for portlet developers. We spoke mostly about what the IDK offers, but there's more too. The IDK is largely about data access and content transformation on the back end, either at the remote server level or in the portal's "gateway" processing space. But much can be done on the browser side too using adaptive portlets. I wrote a guide for this a long while ago, and it's still relevant and helpful. So I'll post it here.

The guide starts with a Word document that gives an overview and screenshots of adaptive portlets. Then it gives installation instructions for the samples that are provided with the guide in its zip file. I'll put the first few pages of the Word document in this post so you can know whether you want to download the entire guide with its sample code.

Getting Started with  Adaptive Portlets

BEA uses the term "Adaptive Portlets" to refer to portlets using AJAX--technologies generally based in JavaScript and XML that allow richer application development.  A simple introduction to this technology is provided through the "Intro to Adaptive Portlets" community with its associated portlets. This document describes that community and how to install it on your own system.

The "Intro to Adaptive Portlets" community consists of several pages. The main page describes the adaptive portlet technology.  Subsequent pages of the community illustrate different design patterns individually, and then the last page shows all technologies together in a cacophonous celebration. Screenshots of the pages are below.

Main Page

Auto Refresh

Inline Navigator

Inline Post


Broadcast Listener

All in One!

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=,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/,PT-Imageserver-URI=,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 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. The API service is 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.

Using Google Portlets in ALUI

I was asked to take a look at the Google-powered "gadgets" that can quickly be added to an ALUI portal as portlets.

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=";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 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:, 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., for example, offers it here.

And then there are vast catalogs, filled with junk, but with jewels too, such as what you find at or 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:
  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.


Find recent content on the main index or look in the archives to find all content.