Where’s the Document Object?

The problem with CIS was that as a design it was, forgive me, a little weird.  It’s not that it didn’t work, it actually worked pretty well in most situations, but there were a couple of oddities.

• It  has what you might call and easy-to-use command pattern that hid underyling service calls from the application.  So for instance you would call if you wanted to make a DOC_INFO service call, you’d call the getDocumentInformationAPI method.  Not the end of the world, but also not really an intuative API for UCM.  I think the reason was that this pattern fit much better in Java web app and so it was designed a little more for that rather than as just a standard Java API.
• Because you’re working with strict objects, it makes it sort of tough to call new services, like Site Studio ones, directly.  There is a work around, which involves using what’s called the administrative API(sort of the base API for the whole thing).  Typically I’ve  just used this for all my calls,(and incidentally it would then look a lot like RIDC code), but looking at all of CIS, it just seems like you needed a lot of different classes to do really the same thing, make service calls.
• If you crack open the CIS jar, you’ll find that there’s a slightly loco version of Spring in there(based on 1.5 I think) along with a modified classloader.  I’ve only run in to issues in one location(you know who you are), but with all that extra code in there, I’ve always been hesitant to use it with other Spring versions for fear of class conflicts.
• Inside of UCM there’s already a Java API called the jspserver.jar.  It’s about 5-6 classes total, allows you to call any service, uses objects that look and acts very much like normal Content Server objects.  I’ve based all my remote API’s on it(.NET and ActionScript)..it was such a simple and elegant design, I always wondered why the CIS people never talked to the jspserver people.  Well that’s pretty much what RIDC is.

And here’s some code.

Since code samples always make for exciting reading, lets jump right in with some examples.

Here’s the example included in the CIS developer manual for how to make a DOC_INFO call.

//get the active API
SCSActiveAPI activeAPI = m_cisApplication.getUCPMAPI().getActiveAPI();

//create a document object
ISCSDocumentID documentID = (ISCSDocumentID) m_cisApplication.getUCPMAPI().createObject(ISCSDocumentID.class);

//set the dID
documentID.setDocumentID("10");

//make the call, get the doc response
ISCSDocumentInformationResponse docResponse = activeAPI.getDocumentInformationAPI ().getDocumentInformationByID(m_context, documentID);

//and there's the content
ISCSContent content = docResponse.getDocNode();

What do you think?  Granted I copied the CIS example out of the doc and it’s not a prefect one-to-one comparison to the RDIC one I’m about to show you(designed for a web environment where the connection is already established), but doesn’t that seem like a lot of casting and nested objects?  I know I’m complaining about code looking too complicated, but seriously try to explain that to someone.  It really just doesn’t even look like UCM.

Take a look at the same call with RIDC…..way simpler, and I think if you understand UCM at all, it follows a rather intuitive flow. If you’ve done any Java component development, you’re learning curve should be near nil.

//create the client manager
IdcClientManager idcClientManager = new IdcClientManager();

//and then create a client to the content server
IntradocClient client = (IntradocClient)idcClientManager.createClient("idc://localhost:4444");

//create a binder object
DataBinder binder = client.createBinder();

//add our service values
binder.putLocal("IdcService","DOC_INFO");
binder.putLocal("dID","10");

//and make the call...too easy.
ServiceResponse response = client.sendRequest(new IdcContext("sysadmin"), binder);


Binders, putLocal methods and clients…everything you’d expect in a remote API.  You can call any service; custom ones and new ones added via components like Site Studio and other Oracle add-ons are all there.  I haven’t opened up RDIC yet, but check out how much smaller the new API is vs it’s older sibling.

I’m not going to rush out and re-factor all of my CIS-based applications, I can solidly say I’ve moved on for future projects.  I have a couple of portal examples forthcoming and hope to have some RIDC in there, so check back soon.

There was of course some excitement for Solaris, but really it’s pretty clear that Java was the buy:

Java is one of the computer industry’s best-known brands and most widely deployed technologies, and it is the most important software Oracle has ever acquired. Oracle Fusion Middleware, Oracle’s fastest growing business, is built on top of Sun’s Java language and software. Oracle can now ensure continued innovation and investment in Java technology for the benefit of customers and the Java community.

Oracle really isn’t just a database company any more.  They really haven’t been that for some time, but now they are a software company that also sells a database.  The fact is that they now own the language and ultimately the platform of which many of the best selling enterprise applications are built on.  That fact would actually be a little more interesting to think about if they had not already purchased  all of the best selling enterprise applications already.

Who’s Next

I really know nothing about who or what Oracle wants to acquire(in fact I don’t think I could know less), but how much sense does Red Hat make?  Red Hat is just about the gold standard in Linux distros(I don’t want to hear it Ubuntu fans, I’m talking servers), plus they get the last real application server out there that doesn’t have “sphere” in the name and they, like Sun, are major, major proponents of open source technologies.

It’s really crazy…Java.com will be an Oracle site….wow…double wow.

A little background

In Site Studio there are two types of pages;  Primary pages, which are essentially the landing pages for a folder(think home, search and listing pages).  They are almost always named index.htm and what’s unique about them is that when they are called they only refence specific content items.  Secondary pages, which could be viewed as everything else in a folder differ as they are used in more of traditional templated, delivery fashion, where the content is delivered through a reuseable template.  I butchering those descriptions a little for simplicities sack, but for the most part that’s how they work.

Out of the box, Site Studio lets you reference a content item using it’s content id in the url.  So if you had a content item called 000525, it would be referenced in a folder with it’s content id at the end(http://SiteStudio.com/site/folder/000525 for example).  Since all templates are mapped to thier folder, everything you need to render a page can be found in the URL…it’s all pretty simple.  The thing is, what if you aren’t too crazy about the 000525 name though?  It’s not really all that intuative of a name; you could make the content id friendly or you could use also take advantage of the SSUrlFieldName property in Site Studio.  The SSUrlFieldName property allows you to map a custom metadata field(perhaps one longer than the 30 characters you get for a content id?) as the file name idenifiier used when reference in a URL.

So content item 000525 can also have a metadata field tagged as “autofillthatfriendlyname.htm” and so when refereced as a url, it could look like this: http://SiteStudio.com/site/folder/autofillthatfriendlyname.htm.  That’s pretty cool, right?  There is a bit of a catch though, like the content id the value used in the friendly name field should be unique.  The only problem though is that there’s no automatic validation for the values, so there’s nothing to tell the contributor if they’ve duplicated a value.

What the component does

The code for this component is pretty simple, we’re hooking in to the validateCheckinData event and then basically updating whatever field is identified in the SSUrlFieldName property with a friendly name.  I like the validateCheckinData filter quite bit for situations like this where I need to update or add some metadata at check in or update time.  If I have to kick a process off or do something to a piece of content that has just been checked in, so after it’s in the system, I usually prefer the afterLoadRecordWebChange, but that’s probably for another post.

Getting back on track, once a piece of content is checked in which has a xWebsiteSection value(meaning it’s been assigned a default URL in a web site), it pulls the dDocTitle value out of the binder and makes it friendly(removes any spaces or special characters I could think of).  It then appends a file extension(set in the environmental config) and checks the value against the database.  If the friendly name has been used before on another content item it goes back and adds a 1 to the end of the title part of the file name(I know…not very imaginative).  Each time the component assembles a name it checks it against a max character count also found in the component’s enviornmental config.

Installing this puppy

The install on this component is not really unlike any other.  You of course do need to make sure Site Studio is installed on your content server and that the SSUrlFieldName property has been set in the config.cfg file.  I should note that when you set the SSUrlFieldName property, you need to leave the little x prefixing all custom metadata fields off.  So no xFieldName formats…just FieldName.  You probably will need to tell the component what the size of your friendly name field is.  It’s defaulted to 80 characters, so if you  plan on using less or more, you might want to update it in the component’s environmental config file.

You can download the component here:  Auto Fill Friendly Name

The one issue I’ve run in to though is when developing web sites in Site Studio I find it’s hard to tap in to all of that wonderful localization functionality without changing the default system locale.  The problem appears to be that the localization is based on the user and since all anonymous users are essentially using the same account, they all appear to have the same locale.  I’ve read some posts on how to change the user’s locale by updating a cookie, either server side or by Javascript, but to be honest I’m not super crazy about that method.  Odds are everything will work fine 99.99% of the time, but what if a user has cookies disable or if the user is actually a search crawler which is ignoring cookies? It’s probably not going to work so well.

Enter the IdcLocale object

Changing the user’s locale during a service execution is actually an extremely easy thing to do.  Localization data is held in the IdcLocale object(intradoc.common package), which is stored during exection as a cached object named “UserLocale”.  If you wanted to access a user’s IdcLocale object, the syntax looks something like this:

IdcLocale MyLocale = (IdcLocale)context.getCachedObject("UserLocale");

Changing the locale take a couple more steps.  You first need load a new IdcLocale object specific to your locale and then you need to overwrite the old one.  Creating a new IdcLocale object is pretty simple, you use the LocaleResources object and call the static method, getLocale.  It takes a single argument, the name of the Locale you’re loading:

IdcLocale ItalianLocale = LocaleResources.getLocale("Italiano");

Once you have the new IdcLocale object, you only need to overwrite the old one and your locale is changed :

context.setCachedObject("UserLocale", ItalianLocale);

Putting it in action

I’ve put together a sample component which adds functionality for changing the user’s locale dynamically.  In tinkering with user locales, there are two customizations which I think can come in handy.

The first is customization is a filter attached to the ‘afterInitLocale’ event, which is fired right after the user’s locale is set during a service call and I’m pretty sure was put there specifically for changing the locale. In the component, the filter looks for a local binder value called ForceUserLocale. If it’s there and it’s a valid Locale name, then it swaps out the current user’s IdcLocale object with a new one. Post-switch, the service continues it’s execution evaluting the new Locale object.

The other customization basically wraps that same code in a new IDOC script function called setLocale. SetLocale takes a single argument, LocaleName, which is of course the name of a valid locale in the system. Calling the function immediatly switches out the user’s Locale with a new one. This is pretty cool if you’re working on a web page or template and wish to show the same or multiple strings in different languages.

Using the new setLocale function, the following code would display the same string on the same page in different languages:
<$setLocale("Italiano")$>
<$lc("wwPoweredBy")$>
<$setLocale("Italiano")$>
< $lc("wwPoweredBy")$>

Controllato dal sistema di gestione dei contenuti
Powered by Content Management System

Changing the Locale dynamically with a local binder value might not be the best fit for all implementations. If you install the sample component adding ForceUserLocale=Italiano to the URL will change the locale to Italian, which may or may not be undesirable. Nevertheless, I think the component demostrates some of the cool things you can do with the IdcLocale object.

The sample Anonymous User Locale component is can be downloaded here:
Anonymous User Locale Component

However it’s done, I think their server has a huge amount of potential from an ECM perspective.  Nearly every client of mine has asked about offering some level of automation to their meta-tagging while contributing content.  While many of the enterprise vendors offer applications to automatically tag content, I find that they are usually focused on batch loading or migrating content, rather than assisting the every day contributor.  In my ideal world I’d love to see contribution forms come up pre-loaded with system recommended meta-data, allowing contributors to make only necessary edits and then simply approve thier submissions.

I was pretty pumped when I ran across Yahoo’s service, so I decided to throw together a quick component to take advantage of it for  Stellent / Oracle Universal Content Server.  Nothing too crazy here, the component basically adds an additional option to the Content Action menu called “Add Yahoo Terms”, which executes a service called “ADD_YAHOO_TERMS”.

The service then does the following:

• Performs a dynamic conversion on the document
• Reads the contents of the resulting HCST output file
• Posts the HTML to Yahoo’s Terms Extraction service
• Parses(XML) the terms returned
• Creates a comma delimited list of the best terms
• Saves the list to the binder in a predesignated memo meta-data field(the default is xComments)

The remainder of the service is basically the GET_UPDATE_FORM service, which brings up the update form.  Since the terms are in the binder as a meta-data field, the update forms comes up pre-loaded with the document’s meta-data as well as the Yahoo terms in the pre-designated field.  From there on you are on the standard Stellent / Oracle update form, so saving will commit your changes.

It’s a pretty simple integration, nothing revolutionary, but I think it’s a decent example of how one might integrate Stellent with Yahoo’s service.

Feel free to download the component here:

Yahoo Terms Extractor Integration for Stellent / Oracle

The concept behind the example component, Security Overrides, is an IDOC enabled version of the Security Filter example, which is part of Stellent’s HowToComponents Bundle.  Stellent’s SecurityFilter component is an example of how to use the alterUserCredentials filter to change the rights of a user during a specific service request.  The primary example is the BlackHole check in example which grants everyone write access when checking in an item using the Black Hole service.

Creating security filters or overrides with the alterUserCredentials can be a tricky proposition.  Depending on your implementation, you’re basically altering the behavior of the content server with no real visible indication that it’s being done.  In addition the alterUserCredentials filter is called with every service call, so it’s a great place to cause a performance problem with inefficient code, or just by adding multiple security filter components.

So how does the Security Overrides component and more importantly IDOC help the situation?  The component creates a central, administrator controlled, interface for creating and managing overrides. What’s more, each service configured has an IDOC script prompt, which is used in the final decisioning of whether to apply the override or not.  For example if an administrator desired to only allow the “sysadmin” account access to the providers page, they would configure an override  that removed all permissions for the “GET_ALL_PROVIDERS” service.  In the IDOC prompt script would be added to evaluate the dUser variable, ensuring it was the “sysadmin” account.

The beautiful thing here is that because the component is processing IDOC for it’s final decsioning logic, the override becomes extremely simple to alter as well as include addtional actions down the road if desired.  And as you’ll see in the code, creating a component which can support IDOC scripting takes very little additional work.

In addition to integrating IDOC scripting in a Java-based component, the component also demonstrates:

• Creating an installation filter, which creates a database table after start up
• Working with the YUI library to create a model, pop-up form as well as creating and handling AJAX requests
• The run-time creation and altering of environment variables
• Customizing the Stellent / Oracle interface

As you might have guessed from the word “Introduction” in the title, I plan on making the review of this component a multi-part series, rather then one long post.  The component along with it’s source code will be available for download here.

I should also mention that Oracle has a fully supported component available for download which has some of the same features as this one.  It’s called the “Need to Know” component and if you are considering using my example in a production system, please take a look at their component first.

Security Overrides Component for Stellent / Oracle