Technical info and insight on using Oracle Documaker for customer communication and document automation

Thinking about upgrading Documaker Standard?

Andy Little
Technical Director

In some recent discussions I was asked to describe the general steps for performing an upgrade of Documaker Standard edition and when planning should start for such an upgrade. Note: Documaker Enterprise Edition shares some common upgrade tasks but is a different animal when it comes to upgrading. If you have an ODEE environment, you can read this but know that your needs will be different!


First, let me point out that most implementations are specialized to the requirements of the organization in which the software is installed. There are often similarities, but typically no two systems are the same. As such it can be difficult to write a one-size-fits-all guide, nor provide any documentation to reference in cases like these. This makes it a little daunting to approach an upgrade but it doesn't have to be. Read on!


The absolute first step is understanding what you're going to upgrade. That means taking an inventory of what you have: software and versions, hardware and specifics, Documaker implementation specifics, as well as related software systems. You need to be able to answer questions like What version of Documaker are you running? Are you using Docupresentment? Do you have custom rules in Documaker or Docupresentment? What are your integrations with third-party software? 


Ideally you have been maintaining documentation about your system over its lifetime. If your system was implemented by Docucorp/Skywire/Oracle, it is likely that you have system installation and configuration documentation that you have been maintaining (you have been, right?) and this will be immensely helpful in answering these questions, and you’ll see why in a moment.


Next you need to determine the upgrade method, which is either going to be in-place or side-by-side. Side-by-side is the most common and means having a new implementation that runs next to an existing one. An in-place upgrade is rarely done, and involves literally installing the new software over the existing software, and is usually done only when budgets and timelines are extremely tight and new environments cannot be procured to support the new version. Keep in mind that as soon as cutover to production is 100% complete, the old system can be retired/repurposed, so your hardware investment should not grow significantly.


It’s time to conduct the upgrade assessment. This is the hardest step as it is the most complex, especially if you have a much older system, or you haven’t been maintaining your system documentation. The objective here is to document the system specifics both for the existing system and the target system.

  • Review the readme/release notes for the target version and identify additions/changes you might use or might affect you. Note: readme/release notes are not cumulative so if skipping a version (e.g. 12.4 to 12.6) you’ll need to review the notes for each version.
  • Identify any touchpoint and integrations with outside systems. If the system is complex and far-reaching, it may be difficult to discover all the touchpoints, as some system could be using an output without your knowledge. It’s unlikely that an ODSE upgrade will change an output, but it could happen, so you need to know what to test to make sure it’s still working after the upgrade.
  • Identify any customizations. In an ODSE there are two typical areas where custom code comes into play: CUSLIB and Docupresentment. There are other areas too, but these are the most prevalent. CUSLIB customizations are usually done to introduce new behavior into Documaker to meet a requirement that cannot be satisfied with the base rules and functionality in Documaker. For systems that have been in place for a long time, it is typical that old custom code can be replaced with base rules and functionality.
  • Analyze customizations. If you have customizations, you should analyze the functionality of the target system and determine if you still need the customization(s). If you determine you need to keep the custom code in CUSLIB, you’ll have to plan for  recompiling against the new version. Note: for custom rules in Docupresentment, it’s possible you could have custom rules there as well, but these rules rarely (practically never) need to be recompiled.
  • Determine impact of changes to configuration. This step is ambiguous in its definition, but once you have conducted the prior steps it should be pretty clear. If you are implementing new rules to replace custom code, then those rules could need new configuration options enabled, or changing existing ones. If you are doing an implementation on a new server that has a different directory structure, you might have to change some configuration settings. The objective here is to know what needs to be changed in the configuration. It most cases, the answer is very little or nothing.


Next you need to establish your upgrade plan. This will be based on your previous analysis and needs, and depends largely on your upgrade method, implementation particulars, and corporate standards. This is typically a sequential list of tasks that will be completed, who will complete them, and when they will be completed. You need to account for establishing the new environment. If doing in-place, this is not necessary. For side-by-side, this can mean a new directory on an existing server or a new physical/virtual server. The software doesn’t care either way, but it depends on what your particular needs are. You need to account for how you will perform the installation and configuration (typically, run the installation, then copy the configuration (INI files) from the existing system and perform any necessary modifications to the configuration for the new environment (e.g. if you have renamed directories that are referenced in the configuration, then you need to update the configuration).


A typical strategy includes a regression test wherein a set of test cases are executed against the existing system and the outputs retained for comparison. When the new system is installed and configured, the regression test cases are run in the new system and the outputs compared to determine if there are any differences. The strategy made also include a smoke test to validate that the installation is successful, followed by some period of comparative side-by-side execution, which is essentially running production data in the old system and the new system at the same time, while still using the output from the old system and selectively comparing to the output from the new system to ensure the fidelity is similar. Typically these methods are used if there are significant changes to the codebase (e.g. moving from custom rules to built-in rules) and less-so for like-for-like upgrades.


So now you’ve created the plan… what comes next? It should be obvious at this point, but the next step is to execute the plan. If this seems daunting, don’t worry - you can always contact an Oracle Consulting representative to help you through this process. We’ve done this many, many times, and we’re the experts here, so don’t hesitate to reach out.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.