Query filters explained, at last

I can’t even begin to count the number of times I’ve been asked how to write a query filter in Plumtree. Yesterday, I had to write one for myself and lo and behold, I was confused. I’ve come to the conclusion that they’re just hard to write. Despite this, they’re incredibly useful when trying to lookup objects in the Plumtree API.

(Note: this post does not apply to writing portlets or other integrations. It’s only useful when writing Pluggable Navigation, PEIs, or other customizations to the UI.)

To use a query filter, you’ll first need access to a Plumtree user’s session. Let’s assume that you have one in the variable plumtreeSession and that it’s already connected as a user who has at least read-level access to some objects. This query will work for any object, but just for the sake of example, let’s use Groups. Also, I wrote this in Java, but it works almost exactly the same way in C#.

First you need to get an IPTObjectManager as shown here:

IPTObjectManager groups = plumtreeSession.GetUserGroups();

Next, we’ll build up the query filter, which is always an Object[][].

Object[][] filter = new Object[3][1];
filter[0][0] = new Integer(PT_PROPIDS.PT_PROPID_NAME);
filter[1][0] = new Integer(PT_FILTEROPS.PT_FILTEROP_EQ_NOCASE);
filter[2][0] = "Everyone";

Let’s go through that line by line. First of all, why did I choose 3,1 for my array dimensions? All query filters are 2D arrays. The first dimension always has three items:

    1. The name of the property on which you’re filtering
    2. The operator (equals, less than, greater than, etc.)
    3. The value of the property you’re evaluating

Since it’s an Object[][], we can’t use primatives, so we must box our constants in Integer objects because the constants themselves are primatives.

When using the Query method that supports a query filter, you also need to specify an ordering attribute. You can only order ascending, but you can order by up to three properties which will be applied in the order they are put in the array, as shown below:

int[] orderBy = {PT_PROPIDS.PT_PROPID_NAME, PT_PROPIDS.PT_PROPID_OBJECTID};

In the code above, I’m asking to order first by name, then by object ID. (Since no two names can be the same in Plumtree, this dual ordering doesn’t really make much sense, but oh well.)

Now, finally, it’s time to run the query:

IPTQueryResult group = groups.Query(PT_PROPIDS.PT_PROPID_OBJECTID + PT_PROPIDS.PT_PROPID_NAME, -1, orderBy, 0, -1, filter);

Let’s break down those parameters one by one. The first, PT_PROPIDS.PT_PROPID_OBJECTID + PT_PROPIDS.PT_PROPID_NAME is a bitmask of properties you want to include in your results.

The second, -1, means query all folders in the admin directory. (If you want to restrict your query to a single folder (and all folders below it), use the folder id here. If you want to query down two distinct folder trees, you’ll need to run two queries.

The third, orderBy is your ordering attribute(s), explained above.

The fourth, 0 is your starting row.

The fifth, -1 is the number of rows to return (-1 means all rows). This parameter, along with the starting row, can be very useful for pagination.

The sixth and final parameter is your beloved query filter.

We did it! Now that wasn’t so bad, eh? Iterating through the results set is trivial, so I won’t cover it here, but if you have you have a question, feel free to make a comment here or post on the developer forums.

We’ve moved!

Effective immediately, bdg’s new place of business is located at 13800 Coppermine Road in Herndon, Virginia, just 10 minutes from Washington Dulles International Airport and in the heart of the Dulles Tech Corridor. You may now reach us at 703 234 7910.

If you’re in the area, arrange to pay us a visit by sending a note to [email protected].

bdg’s new hires and site changes

All of us at bdg are very pleased to welcome the newest members of our team: Rich Weinhold and Eric Bucchere.

Rich, our resident PHP and Plumtree guru, has made his claim to fame by developing the PHP EDK, which is now available for download on the Plumtree Code Share (requires a login and password) or by contacting bdg.

Eric, bdg’s Account Manager, serves as the main POC for all of our implementations, helping customers get their issues resolved quickly and efficiently.

We’ve updated the Web site to reflect these new additions and also made a few other changes, including adding a page about our committment to open source development, which has come to fruition with the release of the Plumtree PHP EDK 5.1.

Resources for running Plumtree on Oracle

Many of our customers run Plumtree on Oracle, for better or worse.

Despite it’s complexities and eccentricities, it’s been a good platform albeit not without it’s driver issues, configuration issues and other weirdnesses.

While doing some research on running Oracle over TCPS (TCP + SSL), I discovered two excellent Oracle resources in the blogosphere:

1. http://vanbortel.blogspot.com
2. http://tkyte.blogspot.com

Enjoy!

bdg launches the PHP EDK 5.1

I am very pleased to announce that on Friday, 8 July 2005, bdg released the PHP EDK 5.1 to the Plumtree Code Share. Largely due to a Herculean effort on the part of Rich Weinhold, our resident PHP and Plumtree Guru, we were able to take the com.plumtree.remote.portlet.* package from zero to released in just three weeks.

We are offering this code up for redistribution and use under the BSD License, which is the standard for the Plumtree Code Share.

In order to access the code (for now), you’ll need to create a login on portal.plumtree.com. We are currently considering other distribution methods, such as SourceForge, and we’ll make an announcement should we choose to go down that path.

We look forward to seeing some PHP portlets start to emerge for the Plumtree platform. If you’re interested in developing a PHP portlet for Plumtree, let us know — we’d love to hear from you.

Server-to-server SSL with Plumtree

Two different customers of ours have recently experienced problems with server-to-server SSL and Plumtree, so I thought I would shed some light on the issue in the hope that it might help someone else who’s having the same problem.

The reality is that server-to-server SSL is no different with Plumtree than it is in any other environment, but it’s just poorly understood in general. Also, Plumtree makes server-to-server requests in places where you might not think to look. For example, you might think that only end users hit the Image Server, but in fact both the Portal Server and the Collaboration Server make server-to-server connections to the Image Server to pull down javascript files. (It’s possible that Content Server, Studio Server and the new Analytics Server make similar requests; I just haven’t run into problems with these products — yet.)

So, here’s the gist: in order for a server to communicate with another server over SSL, the requesting server needs to have the host server’s certificate installed in it’s keystore. Doing this is pretty straighforward and well documented. First, you need to export the certificate from the host server and copy it over to the requesting server. You can read about how to do this in IIS or how to do this in a JVM-based application server such as Weblogic or Tomcat.

After exporting the cert, you’ll end up with a .cer file that you’ll need to install on the requesting server. Say that server is a Tomcat instance on which you’ve installed Plumtree’s Collaboration Server. In this case, this set of instructions should help you get that part working.

One gotcha is that the name of the server in the certificate must match the name being placed in requests made to that server. For example, if the requesting server is making a call to https://images.mycompany.com, you need to have images.mycompany.com as the name of the server in its certificate.

How to search for other Plumtree deployments

If you’d like to see what people are doing with Plumtree on the open internet, you can search Google using the allinurl: portal/server.pt syntax.

Bear in mind that Plumtree portal administrators can change both “portal” and “server.pt” to anything, but most do not choose (or do not know how) to change this. Really, it’s easy — just change the VirtualDirectoryPath and the HTTPEntryPoint in j_config.xml or n_config.xml.

bdg takes Wind River live on Plumtree 5.0.4J

All of us at bdg are very pleased to announce that our very own Andrew Morris has led Wind River to a successful launch of 5.0.4J on their corporate extranet with an extremely slick and highly customized UI. In fact, the UI is so good that if it weren’t for the portal/server.pt in the URL, you seriously wouldn’t know that it’s a Plumtree Portal!

To pull this off, Andrew leveraged bdg’s extensive knowledge of Plumtree UI customization (especially pluggable navigation) in Java along with a boatload of Plumtree Content Server magic. Up until now, I thought SunTrust was the most creative Plumtree 5x deployment in terms of UI tweaking, but this one trumps it. By a lot. If you don’t believe me, take a look for yourself.