OBIEE Software Configuration Management Part 3 : Version Controlling the Project

In the previous two articles in this series, we looked at the initial, and then subsequent, releases of an OBIEE project. We used the BI Administration tool to perform a three-way merge of the development, production, and baseline RPDs, and then used the Catalog Manager, along with a new plug-in called the Content Accelerator Framework, to migrate reports and dashboards.

A common question that we often hear when working in this sort of situation is around source control. OBIEE doesn't have any built-in source control features, but customers often want to store elements of an OBIEE project in a source control tool such as CVS or Subversion. Now we covered the basic use of Subversion with OBIEE in a previous article on this blog, but something we've found when working with this in practice is that it's not as simple as you'd initially think. For example:

  • Whilst you can extract elements of an RPD into UDML files, working with UDML isn't really supported and it doesn't really cover RPD constructs such as security settings;
  • Checking individual files in the webcat filesystem into a source control system is definitely not recommended, due to corruptions being potentially introduced into permissions;
  • Bearing in mind the above two points, the only tools that you're supposed to use to edit, check-in and check-out project metadata are the BI Administration tool and the Catalog Manager, and
  • If you follow the recommended approaches from Oracle, you can only check items into source control that their most "monolithic" level - the whole RPD, or archived copies of webcat folders
Given this, we take a fairly simple, conservative approach to using OBIEE with, for example, Subversion. We generally only check in whole RPDs, and whole archived Shared and Users webcat folders, into Subversion, together with configuration and other artifact files, and then check these out again before editing them in the BI Administration tool or the Catalog Manager. That way we still bring together the sets of files and metadata into a named release, but we don't try and store files in a more atomic form in the SVN repository and risk issues with permissions, using unsupported methods etc. Now we do therefore lose a large part of the power of a tool like Subversion in that we can't "diff" files, we can't use the tool to automatically branch and merge the code tree, but will cover how we do do this in the final part of the series. For now though, here are the steps we use to version our projects.
  1. Using a tool such as VisualSVN Server (a free download for Windows), create an SVN repository and set up the folders for our project. Typically you'd have "branch", "trunk" and "tags" folders, with subfolders then set up under the "trunk" folder for the various bits of OBIEE metadata you'll want to version control.


2. Using another tool called TortoiseSVN (which integrates with the Windows Explorer Shell, assuming your client is Windows), right-click and select SVN Checkout... to check out this empty SVN repository to your desktop or to a temporary directory. This will create the folder structure that you will place the various OBIEE files in to. Notice the "ticks" on top of each folder, this is a feature of TortoiseSVN that shows that the file is under version control.


3. Next, copy the RPD file that you want to put under version control into the relevant checked-out SVN folder. If the RPD is currently running offline, make sure you shut down the BI Server and make sure you've saved any outstanding changes, before you do the copy.


4. Next, use the Catalog Manager utility to archive the Shared folder, and optionally the Users folder, from the web catalog and save the archives to the relevant checked-out SVN folder.


5. Now copy across any configuration files, artifact files, web CSS files and so on, into the relevant SVN checked-out folders.


6. Now you're ready to upload to Subversion. Using the TortoiseSVN plug-in to Windows Explorer, right-click on the topmost checked-out SVN folder and select SVN Commit... TortoiseSVN will then present you with a list of any files that are in these folders but that aren't currently being versioned by SVN, you can then check all of them and have them uploaded to the SVN repository. If you're not using TortoiseSVN, you'll need to script this inclusion in the SVN versioning list to make sure they are subsequently uploaded to the SVN repository.


After this, you can work with your RPD, web catalog etc on the development environment, and when you want to save another version of the project, repeat the above process to save a copy. Getting hold of the latest copy (or any numbered version) of the project to do some development work will be as simple as selecting SVN Checkout... from the TortoiseSVN menu, downloading the project version you want, and working from there.


It's not as granular a versioning system as you'd normally expect on a software development project, but it at least allows you to store versions of the project in a way that shouldn't introduce corruptions into the BI EE metadata.