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! ###
