This story does not have to end on such a sad note. Stories like this one can happen any time we open up a system for change. The rest of this post shows examples of how to use version control software with Oracle EPM. Let’s get to it.

For some reason the safety is off. Nothing can touch you and you are at the height of human productivity. That quarterly bonus is as good as yours and its only the first week of the month! So… you delete some old files, change a few (hundred) scripts and head out for lunch.

Your were just about to eat that double-double animal style hamburger and well-done animal style fries when your phone cried out. You look down to your surprise, its your boss. She is frantic because a bunch of files in production were wiped out and almost every script was modified. “This can’t be happening!”, she exclaimed. Your heart skipped a few beats and you broke out into a cold sweat. You had changed code in production instead of development! You dropped your burger and flew back to the office to begin your walk of shame.

What is Version Control?

Famous Time Machine

Before we get to how and why you should use version control, let’s talk about what it is. Version control tools are not time machines but they can effectively travel back in time. They are not usually autonomous but they can be automated. Here is a general definition from the Internet:

Source Code Management (Revision control), also known as version control and source control, is the management of changes to documents, computer programs, large web sites, and other collections of information. Changes are usually identified by a number or letter code, termed the “revision number”, “revision level”, or simply “revision”. For example, an initial set of files is “revision 1”. When the first change is made, the resulting set is “revision 2”, and so on.

Version control tools (in this context) are made of computer software. The software needs to be installed on a computer or server somewhere. Once installed, a repository (special kind of database) can be created to store source code. When code is put into a version control repository the software will help track changes to files on one or more computers. They also help to restore files or revert code to a previous version. Examples of version control tools include:

This is a small sample. There are many more version control tools available. Some are open source (free to use) and others are commercial. Some are centralized (where versions are tracked by a central repository server) and some are distributed (where everyone has their own copy of the repository). Here is an example of a “working copy” from a repository I am using to track changes for an Oracle EPM solution.

Example Working Copy

Note: You may not have access to the same version control tools I discuss here. That is OK. Just get one and start using it. Ask someone in your IT department for assistance or setup your own. The examples I provide here will use Subversion (SVN) with a Windows Explorer plugin called Tortoise SVN. For the past couple of years I have favored Mercurial but I have been using Subversion for almost a decade. Both Subversion and Mercurial are open source and Windows or Linux friendly.

I would have to write a book to cover all of the version control terminology, processes and best practices. I will not do that here. This post is meant to be a catalyst for change in your development work process and is not a deep-dive into version control technology nor the in’s and out’s of how to use it. I only will cover some of the broad topics where relevant.

I will also not cover installing or configuring a version control tool or setting up the source code repository. I leave those tasks as homework for the self-motivated but here is a handy check-list to get you started:

  1. Install a version control tool
  2. Create / Initialize a repository
  3. Checkout a “working copy” of the repository (i.e.: HEAD)
  4. Copy your source code to the folder
  5. Add the source code (files and folders) to the repository
  6. Commit your changes to the repository

The Internet already contains a wealth of knowledge about the basics of version control and each of the tools listed also includes some “getting started” guides that should help.

Benefits of Version Control

Since it is unlikely that any of us will ever get to jump into a time machine we should all consider version control tools as the next best thing. Version control tools have been around for a long time. A version control tool will provide the following:

  1. Improved collaboration (multiple developers, environments, etc…)
  2. Store versions of text and binary files
  3. Unlimited “undo” operations
  4. Built-in redundancy
  5. Automatic change control documentation
  6. Simple and controlled migration of files between environments

In my opinion, these are some of the biggest benefits of using any version control tool. Simply apply the tools to get those same benefits for an Oracle EPM solution. I have met a lot of EPM developers over the years who did not start in IT or simply have never seen version control. NB: It takes some discipline to incorporate version control tools into your work but once you do, your life will forever change. Working with version control tools with Oracle EPM also requires a change in your development process.

The Development Process

Let’s take a look at the process for using version control tools with Oracle EPM development. The process is considered circular and each time the process repeats a new version of your code will be created.

Development With Version Control

When you incorporate version control tools into your work process you generally have new (mostly pain-free) steps to perform. Note: This process assumes that you are using a version of Oracle EPM with Life Cycle Management (LCM). Here are the steps at a high-level:

  1. Development (Code)
  2. New: LCM Export (Optional)
  3. New: Add / Remove Files (Optional)
  4. New: Commit Changes (Required)

Before LCM we could still use version control tools and the approach was more custom in some areas. Instead of LCM exporting files to the version control repository, we used batch or shell scripts to copy files. LCM eliminated much of the work previously required to export code or copy files for EPM applications. These steps represent the most basic workflow.

You should use this process to keep track of any changes that are going on inside your EPM applications. You can also include “external code” or batch scripts, MaxL scripts, Etc…

Oracle has provided a very high-level overview for incorporating version control with LCM for code migration and promotion. LCM is still used to export code to version control but additional steps are added to migrate code between environments using an LCM import. Keep in mind that there may still be some manual effort required during a migration.

In addition to the benefits previously described, a crisis like the one in the opening story will no longer be so painful.

New Steps for Development

Before you start developing you will need to get a working copy of your source code by “checking out” the latest version of the code that already exists in the repository. This may be a one-time step. If you already have a working copy of the code checked out then you may just need to “update” your copy to sync up with the latest version stored in the repository.

Example of Tortoise SVN Update

Example of SVN Update

What is a working copy?

Before you started using version control your code was probably just stored un-versioned in a folder somewhere. Code that is stored in a version control repository is considered “versioned” with a specific set of files at a point in time. When you want to make changes to the code stored in the repository you will “checkout” a copy of the code to work on it. The process of checking out code puts a copy of it into a folder where you can make changes. That is your working copy of the code.

Once you have a working copy you should just continue doing your development. This could include things like updating rules in Calculation Manager, changing hierarchies in Hyperion Planning, updating member formulas in Workforce Planning, writing calculation scripts in Essbase, updating MaxL scripts in your automation folders or just about anything you normally do when working with Oracle EPM.

Step 2: LCM Export (Optional)

The second step of your process will be to create an LCM export of your Oracle EPM code. You can skip this step if you are making changes to code outside of Oracle EPM artifacts (batch scripts, MaxL, Etc…)

I assume that you are already familiar with using LCM and the command-line utility for LCM called Utility.bat. Using this batch file, execute an LCM export that will get pushed to your working copy somewhere. You probably need to execute the export on the Foundation server. Here is an example of the command I use to drop the LCM export into my working copy.

call <path_to_bin>\Utility.bat export_all.xml -b D:\Project\LCM\current

I used the -b option to tell LCM where to save the LCM export. Thus, it is exported to my working copy. The working copy technically starts at D:\Project but I have other code in my repository so this is purely my personal preference to keep things organized the way I like. Note: Before I run a new LCM export from Oracle EPM I always delete the current directory from my working copy to make sure that I only keep code that is supposed to be there. This ensures that any objects deleted in the Hyperion application front-end are not erroneously kept in the version control repository.

Step 3: Add/Remove Files (Optional)

At this point you are stepping into the realm of the version control tools. From my experience, version control software does not usually track the addition or deletion of files until you tell it to. You must explicitly tell the tool, “hey, I’m adding some files.” How you do this will vary slightly in each tool. In Subversion you simply say svn add and the software will take care of identifying new files to add next time you commit your changes.

Example of SVN ADD

If you delete a file from your working copy (accidentally or on purpose) without telling the version control tool that it happened the file will show up with a status of “missing” from your working copy. On the command line version of SVN this appears as an exclamation mark next to the file name.

Example of SVN Status

If you intended to delete the file you can tell SVN to mark it as deleted. If you did not mean to delete the file you can restore it from the version control repository. In this case I did not mean to delete that file. So I will restore it by running an svn update.

Example of SVN Update and Restore

This step is optional because you may not have added new files or removed any existing files. If so, you can skip this step. All commands to add, remove or restore files from the repository can be executed from the command-line program that comes with Subversion. You can also automate the process of adding new files or deleting files that no longer exist in your LCM exports.

See svn help for more information on the available commands and their usage from the command prompt. Next up is the final commit.

Step 4: Commit Changes

Once all necessary changes have been made to the code in the working copy, the last step is to commit the changes back to the version control repository.

Example of SVN Commit

A commit should include a short message describing the reason for the changes. This description will show up in the commit log next to each version of the Oracle EPM application source code. Automated commits will also include some message so that you can tell a version of the code was from an automated LCM export.

Example Log Message

Note: If you rely solely on automated exports then the frequency of the version control “commits” will dictate the level of granularity in your version history and therefore the level of opportunity for code restoration. I generally add automated exports from an Oracle EPM solution at a minimum with version control commits. From there I also incorporate on-demand exports and commits during any periods of heavy development.

If you made a mistake at this point you can always go back to a previous version of your source code and restore old files, compare versions of code, or identify which files were changed and by who. With Oracle EPM, if you made a mistake and need to restore a previous version of your code you may need to perform an LCM import of that code.

Final Thoughts

Adding version control tools to your Oracle EPM development can give you a great deal of benefit for a few small changes to your development work process. The activity of storing your Oracle EPM source code in a version control tool can also be automated. Here is an outline of the steps you probably need to include in your batch or shell script when automating an LCM export and version control process using Subversion: (assuming you start with a working copy already setup)

  1. Perform an svn update (brings your working copy to current)
  2. Erase the target LCM export folder if it already exists
  3. Perform an LCM export using Utility.bat (or .sh)
  4. Perform an svn delete for missing files
  5. Perform an svn add for new files
  6. Perform an svn commit to version the latest LCM export

Note: Some of these svn commands may require the use of the --force option from the command-line when batch scripting the version control process.

If you plan to automate your LCM export / version control process it is probably best scripted from your EPM Foundation server. I have done this from non-Foundation servers in the past but the Foundation services code must still be installed on the server even if not configured and this may also require you to copy LCM-related files to various folders to get Utility.bat working correctly.

I have only skimmed the surface here of what you can do with version control and Oracle EPM. I hope you found this post to be useful and that you can see how much you will benefit from adding version control to your Oracle EPM infrastructure.

Cheers!