What’s new with Version 2.0

The improvements to version 2.0 center around a couple different areas:

Direct communication with the content server

This was probably my biggest motivator towards developing a new version of the API as the web filter to content server communication is somewhat of an undocumented mystery.  I’ve written a couple custom filters to integrate UCM with some third part security/SSO providers, but never have really picked apart the actual protocol that’s going back and forth.  Turns out it’s basically just passing HTTP through, but there are a couple values you can add to set authentication.

If you’re ever curious about what happens after your request is made to the web server, you can actually connect to the content server on its listener port(usually 4444) with a telnet terminal.  If you turnon  the CGI_SEND_DUMP on from the filter administration page it will log all calls made to the content server from the web server plugin.  Those logged requests can then be copied out of the log, modified and then pasted in to the telnet window.  Make sure that if you’re using telnet or even this API that the server you are executing from is included in the host or IP filter for the content server, else you won’t be able to connect.

Asynchronous, Multithreaded Execution

I started out planning for just asynchronous execution and then broke a bit more off with the threading(threads are addictive).  What I was looking for was the capability to make a content server request and then for the result to be passed back via an event.  The previous version’s process consisted of an executeService call, waiting inline until the request is completed and then retrieving results from the ServerBean.  The entire process usually takes less than a second, but a more elegant method might be for the executeService call to be made and then for an event handler to process the results when they arrive.  This new version supports the old method and the new event handler.

In addition to the events, the API is also multi threaded so when running in asynchronous mode each content server request runs in it’s own in it’s own thread.  Calling executeService will queue up a content server request and also create and activate a new execution object for your next call.

The API has a setting for the maximum number of threads which can run concurrently.   So if you make 1000 requests the content server will not receive 1000 requests all on top of each other.  Rather it will queue up all 1000 requests, keeping only the max number of threads active during processing.

The Object Model

In copying the idcserver package, I originally figured copying the idcserver object model would make things easier to pick up and learn, but unfortunately I think it was also a little trickier to extend and customize.  The API was flexible and powerful, but if you wanted to build a more robust API, say one specific to your application or organization, things were a bit trickier to extend.

In this new version I’ve set up a more flexible object model(as well as breaking backwards compatibility..sorry about that).  Every object used in the API is referenced by interface, but also encapsulates all functionality in abstract classes.  The only class that this does not apply to is the ExecutionManagerFactory, which is basically a static class used only to create a new ExecutionManager object (the new server bean).

Some Examples

Looking at some code examples with the new API, you’ll find that for the most part they aren’t too different than the old version.  Most of the methods are still named the same only the object types have changed.

Check In New

This example is a synchronous inline operation which checks in a file.  If you compare it to code used with version 1 the similaritites should pop right out.

static void CheckInAFile()
{
  //create a new execution manager object
  ICSExecutionManager em = ExecutionManagerFactory.CreateExecutionManager();
  //set the connection mode.  We're going direct to the content server
  em.ConnectionDetails.ConnectionMode = ConnectionMode.ContentServer;
  //set the host
  em.ConnectionDetails.ContentServerHost = "localhost";
  //set the relative web root
  em.ConnectionDetails.ContentServerRelativeWebRoot = "stellent";
  //set the user to run the operation under
  em.ContentServerUser = "sysadmin";
  //set the service and other metadata
  em.putLocal("IdcService", "CHECKIN_NEW");
  em.putLocal("dDocTitle", "Picture of Me");
  em.putLocal("dDocType", "Image");
  em.putLocal("dSecurityGroup", "Public");
  em.putLocal("dDocAuthor", "sysadmin");
   //set the file
   em.putLocal("primaryFile", new FileInfo(@"C:\file.jpg));
   //execute the service
   em.executeService();
   //check the response
   Console.WriteLine(em.getLocal("StatusMessage"));
 }


This example demonstrates how the asyncronous, multi-threaded execution is utilized. The code will execute three search calls as three different users on the content server. Each execution will occur in it’s own thread, with the results being handled by the same event.


static void AsyncSearchByUser(){
  //create a new execution manager object
  ICSExecutionManager em = ExecutionManagerFactory.CreateExecutionManager();
  //set the connection to the content server
  em.ConnectionDetails.ConnectionMode = ConnectionMode.ContentServer;
  //set the host
  em.ConnectionDetails.ContentServerHost = "localhost";
  //set the relative web root
  em.ConnectionDetails.ContentServerRelativeWebRoot = "stellent";
  //this will be Asynchronous execution
  em.ProcessMode = ProcessMode.Asynchronous;
  //attach a complete event
  em.OnExecutionComplete += new OUCSNET.events.ExecutionCompleteHandler(SearchOnExecutionComplete);

//first call will be as the user droe
  em.ContentServerUser = "droe";
  //set the search crtiera, we want a count of everything
  em.putLocal("IdcService", "GET_SEARCH_RESULTS");
  em.putLocal("QueryText", "");
  //execute the server.
  //Since this is Asynchronous, exection will continue right on
  //with this search result request running in it's own thread
  em.executeService();

//The event handler for the exection object
static void SearchOnExecutionComplete(object sender, EventArgs e)
{
  //convert the sender object to an ICSExecution object
  ICSExecution execution = (ICSExecution)sender;
  //output some results
  Console.WriteLine(execution.ContentServerUser
 + " can access "
 + execution.getLocal("TotalRows")
 + " content items");
  //disposing the execution object will remove it
  //from the internal list of execution objects
  execution.Dispose();
}


Probably More Work To Do

There is an outstanding issue with the API, with regards to NTLM authentication.  The previous version utilized the .NET WebRequest object for content server communication which supported NTLM authentication.  This version, because it needs to connect to both the web server and the content server directly is using the TCPClient object which is basically one step up from a raw socket connection.  Any protocols(beyond TCP) need to be implemented manually, and NTLM has been a bit tricky to configure, basic authentication however seems to work just fine.

This version of the API obviously has quite a bit more functionality in it and I fully expect there to be some bugs that appear(though I hope they don’t).  At the very least I think there will probably be some suggestions for better behavior by API, and so if have some or if you find an issue, please let me know by posting them to the forums.

Not The Last Version

This will not be the last version of the API, so if you have any ideas I’d love to hear them.  Eventually I’m hoping this project will develop in to something close to par with Oracle’s own Content Integration Suite.  So far I am loosely planning on developing some web examples using the API with ASP.NET as well as some examples for .NET 3.5.

The new version of the API can be downloaded here:

.NET API for Oracle UCM Version 2.0

Despite my personal fandom of the WSDL component, it does have a couple drawbacks:

1.  Each web service is in it’s own namespace.  This makes it a bit of a pain when working with multi-step operations, for instance if you’re calling the DocInfo service with a WSDL it will return all custom metadata in an array of IdcProperty objects.  If you’re then planning on updating that item or checking in another related item, you’ll have to copy all your original IdcProperty objects over to new IdcProperty objects specific to the Checkin/Update service’s namespace.

2.  Aside from the seven or so pre-defined services, you have to define any additional WSDLS you wish to consume.  Not the end of the world, but it does make the development a little tricker when you need ensure your WSDL exists on each instance you connect to and that it’s defined to your specs.

There is an alternative; rather then using the WSDLs, you could just add IsSoap=1 to the end of any service call, which will then return you request in SOAP format.  Of course there’s no friendly WSDL to create all your proxy classes, leaving the SOAP parsing up to you.  In addition uploading files can also be pretty tricky as you essentially need to replicate a multi-part/form upload.

To make my life(and potentially yours) a little easier, I’ve been experimenting and ultimately developed a simple .NET API for the Stellent / Oracle Content Server.  Modeled after the Stellent’s Java-based idcserver package, the API can make IsSoap service calls to retrieve information, or just straight HTTP calls when downloading files.  In addition since all calls are made as multipart-form/data posts, one to many files may be uploaded and checked in.

The API has two public classes, the ServerBean which is the primary interface to the API and the ServerResultSet class which acts and behaves like a Stellent Resultset.  If you think you’ve seen those class names before, it’s because you have.  I tried to replicate the functionality of the Content Server’s idcserver package in .NET.

Here’s an example of a search results call using the API:

//create the object
ServerBean sb = new ServerBean();
//set the url to the content server
sb.ContentServerURL = "http://localhost/stellent/idcplg";
//set our credentials
sb.ContentServerCredentials = new System.Net.NetworkCredential("sysadmin", "idc");
//set the service
sb.putLocal("IdcService", "GET_SEARCH_RESULTS");
//pass in our query
sb.putLocal("QueryText", "dDocTitle <substring> `Test`");
//execute the service
sb.executeService();
//get our search results
ServerResultSet SearchResults = sb.getResultSet("SearchResults");
if (SearchResults != null)
{
  //loop through the search results
  for(SearchResults.first();SearchResults.isRowPresent();SearchResults.next()){
  //write the content id
  System.Diagnostics.Debug.WriteLine(SearchResults.getStringValue("dDocName"));
  }
} 

As you can see the syntax is extremely similar to the Content Server’s idcserver package.  Anyone familier with JSP development in the content server, should find it very familiar.

Uploading files is also very easy.  I’ve overriden the “putLocal” method so that it can accept a string or a FileInfo object as a value argument.

//create the object
ServerBean sb = new ServerBean();
//set our url
sb.ContentServerURL = "http://localhost/stellent/idcplg";
//set our credentials
sb.ContentServerCredentials = new System.Net.NetworkCredential("sysadmin", "idc");
//service is a check in new
sb.putLocal("IdcService", "CHECKIN_NEW");
//set the title and required arguments
sb.putLocal("dDocTitle", "NET TEST CHECKIN");
sb.putLocal("dDocType", "Document");
sb.putLocal("dDocAuthor", "sysadmin");
sb.putLocal("dSecurityGroup", "Public");
//create to fileinfo objects based on some local files
System.IO.FileInfo File1 = new System.IO.FileInfo(@"C:\Test Spreadsheet.xls");
System.IO.FileInfo File2 = new System.IO.FileInfo(@"C:\Test Text File.txt");
//add the files
sb.putLocal("primaryFile", File1);
sb.putLocal("alternateFile", File2);
//execute the service
sb.executeService();
//check our status
Console.WriteLine(sb.getLocal("StatusMessage"));


Since we also need to download files or retrieve raw results like a dynamic conversion, the underlying executeServiceEx method which is called by the executeService method and also returns a raw stream from the Content Server’s response is a public method.  Calling executeServiceEx directly will skip the lines of code realted to parsing the server’s response.

In this example, we perform a dynamic conversion and write the raw HTML to the console window

//Create the object
ServerBean sb = new ServerBean();
//set the url
sb.ContentServerURL = "http://localhost/stellent/idcplg";
//set our credentials
sb.ContentServerCredentials = new System.Net.NetworkCredential("sysadmin", "idc");
//set the dynamic conversion
sb.putLocal("IdcService", "GET_DYNAMIC_CONVERSION");
//set our required parameters
sb.putLocal("dDocName", "[Content ID]");
sb.putLocal("RevisionSelectionMethod", "LatestReleased");
//call executeServiceEx, which returns the raw stream
Stream resultStream = sb.executeServiceEx();
//create a reader
System.IO.StreamReader reader = new System.IO.StreamReader(resultStream);
//read the stream
String resultString = reader.ReadToEnd();
//write it to the console
Console.Write(resultString);

That’s the basic gist on how to work with the API, I will be following up this post with one going through the actual code.  Like any of my code examples, the API is provided without support or warrenty, but I plan keeping the API as sort of a a personal ongoing project so you can expect future versions and enhancements.  If you have any questions or ideas please let me know.  I’m really looking for some feedback on this one, so comment away.

I’ve bundled the source as well as an installer package together and posted them for download here.  Once installed the API will appear in your Visual Studio add references dialog as OUCSNET.

.NET API For Stellent / Oracle Content Server