The Importance of a Run Book for your Fusion Applications Upgrade

The Importance of a Run Book to your FA Upgrade

Proper planning for you Fusion Applications (FA) Upgrade is probably the most important factor in determining the success of your upgrade.

Several factors go into the planning for your upgrade; these include but are not limited to:

  • Your current release level (e.g., release 9)
    • JDeveloper customizations to that release
    • Customized BI reports
  • The desired end point (e.g., release 12)
  • Your upgrade timeframe and window
  • The number of environments being upgraded

Now that we have looked at a few of the considerations to incorporate into your planning, we can now look at the planning itself. While every upgrade should be treated as a project itself, at least from a planning perspective, this article will focus on one of the most important artifacts that should come out of your upgrade planning and execution – the run book.

Before we go much further, it might be a good idea to quickly discuss the “Why do I need a run book question”. The simplest answer is to say; by building the run book using the methodology below you will improve the efficiency of each upgrade following the first one, when following the same upgrade path for multiple environments on the way to a production upgrade. Sure, the first one is a bit slower as you are taking the time to get the knowledge base built, but all other and most importantly your production upgrade will be more efficient as a result of having a robust run book.

What is a Run Book

Simply stated, the run book is a record of not only how you plan to execute the upgrade, essentially the steps you intend to follow and the execution order of those steps. Additionally, and of no less importance the run book is a record of your experience with executing each step you planned to execute. As you can see the construction of the run book is very iterative in nature; you will make several passes through it while compiling the first one. I say the first one, because most often you will be upgrading several environments in succession on the way to your production upgrade. The run book for each environment will build on the previous environment.

A question we often receive is “why can’t I just follow the upgrade guide?”. The run book is focused on documenting your experience with your environment, when using the upgrade guide. It also captures the items from the release notes that are relevant to your installation. The power of the on-premise install is that it can be molded to fit your business and process to a degree; this translates to the likelihood of your environment having some unique characteristics is higher. So documenting how your environment behaves when going through the upgrade is an important facet of having a successful production upgrade with a minimum maintenance window.

Format for the Run Book

While the actual format of the run book ultimately comes down to personal preference, yet we have found that a run book written in Oracle Open Office Writer (or similar) tends to work best because it allows for easier cutting and pasting of screen shots, and allows for a more narrative step by step approach to the document flow.

Typical Contents of the Run Book

We often get the question, “What should be in my run book”. Below is a list of the types of things that should be in your run book on using a two iteration approach to the development.

Iteration 1

Iteration 1 of your run book is all about setting forth the steps you intend to follow and the patches that you may need to apply both prior to the upgrade starting and as part of the upgrade itself. Patches are going to come from a variety of sources.

The following sources of information will help you populate your run book during the first iteration:

  • Release notes for the version of FA you are currently running
  • Release notes for the version of FA to which you are upgrading
  • Patch readme files (patches that are one-off’s, P4FA, functional bundle and upgrade repository)
  • Upgrade guide for the release you are moving towards (prior to release 6 the upgrade instructions were located in the patching guide)

Strictly speaking, the P4FA patches and any functional bundles patches are not a part of the upgrade itself, yet many customers do include them as part of their upgrade process. Although, this may not hold true in the future as patching frameworks do tend to change over time. Whenever possible, these normal system maintenance items should be implemented in their own separate maintenance window outside of the upgrade maintenance window. All that said, if you are upgrading from say release 9 to release 12, then the application of these patch bundles may fall within your upgrade window for all but the base release you are currently using, in this example release 9.

The reason we look at the patches first is so that we can understand any prerequisite patching requirements that may be present and get the existence and order in which they should be applied understood and documented. The same goes for any post implementation steps, in that they should be understood and documented in the context of your environment (commands using the details of your environment documented). The other thing we want to ensure is that all patches are accessible. There is nothing worse than being in your downtime window and finding a prerequisite patch at the last minute or finding out that the patch you need requires a password and not being able to obtain it in a timely manner; and yes, patches are sometimes password controlled. Remember that you should also go through the upgrade repository itself to understand any prerequisites that may reside there as well.

In addition to patches, here is a list of other items that should appear in iteration 1 of your run book:

  • Environment information – this is specific to your environment, recording machine names etc., anything around the environment that is applicable to the upgrade.
  • The procedure you are going to follow to validate your environment
  • If your It infrastructure is distributed across countries, then an assignment matrix is needed, so a record of which office performed a step or is planned to perform a step so all involved know their roles and responsibilities.

Remember to be as detailed as possible so you don’t have to any of the initial research again.

Iteration 2

While iteration 1 was all about planning for and documenting the steps you are going to follow, iteration 2 is about execution of those steps and documenting the results, issues and fixes. The goal of iteration 2 is to get your experience with your environment documented so the next environment that you apply the upgrade to can be informed by what you experienced the first time.

Here is a short list of the items you should be focused on with iteration 2:

  • Any issues you encountered and well as the steps you took to resolve the issue; this applies to patches as well as the running of the upgrade orchestrator itself.
  • Timings, how long each step took – this is expressed in elapsed time including problem solving. So when you run the same steps again on the next environment you can see if your timings can be improved. How else will you know if your production outage window is indeed achievable?
  • If your IT environment is distributed across multiple geographies. It becomes very important to know who actually executed the steps – This way if there are questions about what got documented, the reader knows whom to ask.

At the end of iteration 2, you basically want enough documented to where you would have the ability to hand the run book off to someone that is not as well versed in the upgrade and have them be able to perform the upgrade based on what you have captured.

When you do your first upgrade is when the construction of the run book takes place, then every subsequent upgrade uses the same run book and updates it with their experiences, issues, fixes, timings, etc.

How it all hangs together

Sometimes a picture helps to solidify how all the pieces fit together. Below is a depiction of how the run book is constructed in 2 iterations and the pieces of data that inform the contents.


Run Book


The importance of a run book to the success of your upgrade cannot be under stated. Capturing everything you need to do to complete your upgrade in a single document that can then be used to repeat the process on subsequent environments that will experience the same upgrade is a tried and true method of:

  • Determining how long each step of the upgrade may take – useful in planning upgrade windows
  • Discovering any issues and documenting not only the issue but how it will be addressed if it occurs again
  • Determining which issues can be dealt with prior to the upgrade being started, so as to avoid an impact to your upgrade window
  • Developing a prescriptive plan that can serve as a guide and remove any instances of memory lapse, those “How did we do this last time” moments.

Recall from the beginning; having a solid run book will help ensure you have a smooth, time efficient upgrade experience when it counts – production.

Add Your Comment