It's no secret that Docupresentment (part of the Oracle Documaker suite) is powerful tool for integrating on-demand and interactive applications for publishing with the Oracle Documaker framework. It's also no secret there are are many details with respect to the configuration of Docupresentment that can elude even the most erudite of of techies. To be sure, Docupresentment will work for you right out of the box, and in most cases will suit your needs without toying with a configuration file. But, where's the adventure in that? With this inaugural post to That's The Way, I'm going to introduce myself, and what my aim is with this blog. If you didn't figure it out already by checking out my profile, my name is Andy and I've been with Oracle (nee Skywire Software nee Docucorp nee Formmaker) since the formative years of 1998. Strangely, it doesn't seem that long ago, but it's certainly a lifetime in the age of technology. I recall running a BBS from my parent's basement on a 1200 baud modem, and the trepidation and sweaty-palmed excitement of upgrading to the power and speed of 2400 baud! Fine, I'll admit that perhaps I'm inflating the experience a bit, but I was kid! This is the stuff of War Games and King's Quest I and the demise of TI-99 4/A. Exciting times. So fast-forward a bit and I'm 12 years into a career in the world of document automation and publishing working for the best (IMHO) software company on the planet. With That's The Way I hope to shed a little light and peek under the covers of some of the more interesting aspects of implementations involving the tech space within the Oracle Insurance Global Business Unit (IGBU), which includes Oracle Documaker, Rating & Underwriting, and Policy Administration to name a few. I may delve off course a bit, and you'll likely get a dose of humor (at least in my mind) but I hope you'll glean at least a tidbit of usefulness with each post. Feel free to comment as I'm a fairly conversant guy and happy to talk -- it's stopping the talking that's the hard part... So, back to our regularly-scheduled post, already in progress. By this time you've visited Oracle's E-Delivery site and acquired your properly-licensed version of Oracle Documaker. Wait -- you didn't find it? Understandable -- navigating the voluminous download library within Oracle can be a daunting task. It's pretty simple once you’ve done it a few times. Login to the e-delivery site, and accept the license terms and restrictions. Then, you’ll be able to select the Oracle Insurance Applications product pack and your appropriate platform. Click Go and you’ll see a list of applicable products, and you’ll click on Oracle Documaker Media Pack (as I went to press with this article the version is 11.4): Finally, click the Download button next to Docupresentment (again, version at press time is 2.2 p5). This should give you a ZIP file that contains the installation packages for the Docupresentment Server and Client, cryptically named IDSServer22P05W32.exe and IDSClient22P05W32.exe. At this time, I’d like to take a little detour and explain that the world of Oracle, like most technical companies, is rife with acronyms. One of the reasons Skywire Software was a appealing to Oracle was our use of many acronyms, including the occasional use of multiple acronyms with the same meaning. I apologize in advance and will try to point these out along the way. Here’s your first sticky note to go along with that: IDS = Internet Document Server = Docupresentment Once you’ve completed the installation, you’ll have a shiny new Docupresentment server and client, and if you installed the default location it will be living in c:\docserv. Unix users, I’m one of you! You’ll find it by default in ~/docupresentment/docserv. Forging onward with the meat of this post is learning about some special configuration options. By now you’ve read the documentation included with the download (specifically ids_book.pdf) which goes into some detail of the rubric of the configuration file and in fact there’s even a handy utility that provides an interface to the configuration file (see Running IDSConfig in the documentation). But who wants to deal with a configuration utility when we have the tools and technology to edit the file <gasp> by hand! I shall now proceed with the standard Information Technology Under the Hood Disclaimer: Please remember to back up any files before you make changes. I am not responsible for any havoc you may wreak! Go to your installation directory, and locate your docserv.xml file. Open it in your favorite XML editor. I happen to be fond of Notepad++ with the XML Tools plugin. Almost immediately you will behold the splendor of the configuration file. Just take a moment and let that sink in. Ok – moving on. If you reviewed the documentation you know that inside the root <configuration> node there are multiple <section> nodes, each containing a specific group of settings. Let’s take a look at <section name=”DocumentServer”>: There are a few entries I’d like to discuss. First, <entry name=”StartCommand”>. This should be pretty self-explanatory; it’s the name of the executable that’s run when you fire up Docupresentment. Immediately following that is <entry name=”StartArguments”> and as you might imagine these are the arguments passed to the executable. A few things to point out: The –Dids.configuration=docserv.xml parameter specifies the name of your configuration file. The –Dlogging.configuration=logconf.xml parameter specifies the name of your logging configuration file (this uses log4j so bone up on that before you delve here). The -Djava.endorsed.dirs=lib/endorsed parameter specifies the path where 3rd party Java libraries can be located for use with Docupresentment. More on that in another post. The <entry name=”Instances”> allows you to specify the number of instances of Docupresentment that will be started. By default this is two, and generally two instances per CPU is adequate, however you will always need to perform load testing to determine the sweet spot based on your hardware and types of transactions. You may have many, many more instances than 2. Time for a sidebar on instances. An instance is nothing more than a separate process of Docupresentment. The Docupresentment service that you fire up with docserver.bat or docserver.sh actually starts a watchdog process, which is then responsible for starting up the actual Docupresentment processes. Each of these act independently from one another, so if one crashes, it does not affect any others. In the case of a crashed process, the watchdog will start up another instance so the number of configured instances are always running. Bottom line: instance = Docupresentment process. And now, finally, to the settings which gave me pause on an not-too-long-ago implementation! Docupresentment includes a feature that watches configuration files (such as docserv.xml and logconf.xml) and will automatically
restart its instances to load the changes. You can configure the time that Docupresentment waits to check these files using the setting <entry name=”FileWatchTimeMillis”>. By default the number is 12000ms, or 12 seconds. You can save yourself a few CPU cycles by extending this time, or by disabling the check altogether by setting the value to 0. This may or may not be appropriate for your environment; if you have 100% uptime requirements then you probably don’t want to bring down an entire set of processes just to accept a new configuration value, so it’s best to leave this somewhere between 12 seconds to a few minutes. Another point to keep in mind: if you are using Documaker real-time processing under Docupresentment the Master Resource Library (MRL) files and INI options are cached, and if you need to affect a change, you’ll have to “restart” Docupresentment. Touching the docserv.xml file is an easy way to do this (other methods including using the RSS request, but that’s another post). The next item up: <entry name=”FilePurgeTimeSeconds”>. You may already know that the Docupresentment system can generate many temporary files based on certain request types that are processed through the system. What you may not know is how those files are cleaned up. There are many rules in Docupresentment that cause the creation of temporary files. When these files are created, Docupresentment writes an entry into a properties file called the file cache. This file contains the name, creation date, and expiration time of each temporary file created by each instance of Docupresentment. Periodically Docupresentment will check the file cache to determine if there are files that are past the expiration time, not unlike that block of cheese festering away in the back of my refrigerator. However, unlike my ‘fridge cleaning tendencies, Docupresentment is quick to remove files that are past their expiration time. You, my friend, have the power to control how often Docupresentment inspects the file cache. Simply set the value for <entry name=”FilePurgeTimeSeconds”> to the number of seconds appropriate for your requirements and you’re set. Note that file purging happens on a separate thread from normal request processing, so this shouldn’t interfere with response times unless the CPU happens to be really taxed at the point of cache processing. Finally, after all of this, we get to the final setting I’m going to address in this post: <entry name=”FilePurgeList”>. The default is “filecache.properties”. This establishes the root name for the Docupresentment file cache that I mentioned previously. Docupresentment creates a separate cache file for each instance based on this setting. If you have two instances, you’ll see two files created: filecache.properties.1 and filecache.properties.2. Feel free to open these up and check them out. I hope you’ve enjoyed this first foray into the configuration file of Docupresentment. If you did enjoy it, feel free to drop a comment, I welcome feedback. If you have ideas for other posts you’d like to see, please do let me know. You can reach me at
[email protected]. ‘Til next time! ###
