US-Analytics RPD Merge Script: see on Github
Git is a cornerstone technology for anyone looking to improve the efficiency of their development team. It can help improve code quality, expedite release schedules, and reduce development costs. Without a Source Code Management (SCM) tool such as Git, developers are handicapped while the competition continues to innovate.
Even monolithic technologies such as Oracle BI (OBIEE, OAC, BI Apps) can benefit from an SCM tool. Many articles have been written on how this can be accomplished, and many tools exists which facilitate the use of Git for OBIEE developers. However, Git brings some of its own problems to the table, especially in the case of Oracle BI. The chief of which is how to manage the RPD.
Of course, the RPD can be managed with the OBIEE MUD/MUDE process, but this process is not applicable to other workflows. The RPD development workflow with Git is exactly the same with any other artifact, making it simple to translate to other artifacts.
The crux of the problem comes from how the RPD file is represented. In its default state, an RPD is a binary file – something which Git has trouble working with. A simple workaround is to save the RPD file as the only other supported format, MDS XML, but this comes with its own host of problems. The long and short of it is — there are many ways and many workarounds, but none are really perfect.
Our approach seeks to be the one perfect solution to this problem. Better yet, it’s free and open-source. But before we get into it, how does it work?
Git has the ability to be extended with custom merge drivers. A merge driver is basically a piece of code which tells Git how to merge (or combine) files of a specific type. Since the Administration Tool can be used in a “headless” mode, and can perform RPD merges itself, it’s possible to actually configure Git to offload the merge responsibilities to the Administration Tool.
This is where you may want to send this article to your developers, as it starts getting a little technical.
Custom Merge Driver for RPD files
Configuring Git with custom merge drivers isn’t too difficult, you just need some scripting knowledge in the language of your choice. Lucky for you, we’ve already done the heavy lifting. We’ve developed a custom merge driver and its available as open source:
All you have to do is the configuration. Don’t worry, we’re here to help with that too.
There are several methods for configuring custom merge drivers. We’ve found this way to be the most flexible and powerful.
The process below isn’t too difficult but be sure to pay special attention to any parameters that need to be updated for your environment — specifically, passwords and paths.
Also, since the Administration Tool is Windows only, this plugin only works for Windows, and thus the steps below are on a Windows environment.
- Install python 3 if it is not already on the machine. You can check if it is already installed by opening PowerShell or CMD and executing python -V.
The script is not currently compatible with Python 2, it must be Python 3.
- Install Git if it is not already on the machine. You can check if it is already installed by opening PowerShell or CMD and executing git --version.
- Grab the merge-rpd.py script from the git repository and move it to a specific location on your system. Be sure to remember where you put it, as you will need it later. I suggest the structure <path>\US-Analytics\merge-rpd\bin.
- Open the script with Notepad++ (or Notepad, if you must). Go to lines 30, 31, and 32. This is where we need to make the most important changes.
- On line 30, set the rpd_password variable to the RPD password. In this example, the RPD Password is Password01.
- On line 31, set the admin_tool_exe variable to the path for the Administration Tool. In this example, the Admin Tool is at C:\Oracle\OBIEEClient\bi\bitools\bin\admintool.cmd. However, be sure to use ‘\\’ instead of ‘\’ in this path. It’s a programming thing.
- On line 32, set the repository_path variable to the path for the Git repository which contains the RPD. Again, be sure to use ‘\\’ instead of ‘\’.
- Find your .gitconfig This can be done by executing the command git config –global –list –show-origin.
The command shows us the location of our global .gitconfig file.
- Open your .gitconfig file and append the contents of our .gitconfig file in the open source repository.
Your .gitconfig file may end up looking different than ours, but as long as the last block shown is present, you should be fine.
- Copy the .gitattributes file we provide into your Git repository. If you have your own .gitattributes file, then just combine the files.
This is our Git repository. It now includes the .gitattributes Notice the file name is actually .gitattributes, and not .gitattributes.txt. This is important. You can confirm it’s the correct name by checking the File name extensions option.
- Append the path of the merge-rpd.py script to the PATH environment variable. Don’t forget to use a semicolon as a delimiter!
- Append .PY to the end of the PATHEXT environment variable. Again, use a semicolon as a delimiter.
- Restart PowerShell/CMD or create a new session. Execute the command merge-rpd. If you receive the output below, then you’re all set. If not, return to the steps above and see if you can find where you went wrong.
Even though the script tells us it encountered an error, that’s okay.
Git should now be able to handle the rest! Let’s test it out and see how it works.
Let’s start with what our Git repository looks like. Of course, we have our RPD file, GCBC12c.rpd, as well as our previously created .gitattributes file.
I’ll open the base RPD to show what’s currently in it. I want to keep these examples simple, and really all the effort is being performed by the Administration Tool, so it isn’t anything we haven’t seen before.
As you can see, our initial RPD has nothing in the Presentation Layer.
Like I said, simple. Now let’s see what the RPD for one of our branches looks like.
In the other branch, we’ve built a different Subject Area.
Let’s perform an RPD merge using standard Git commands:
git merge example-branch-1
git merge example-branch-2
The first merge won’t open the Admin Tool. That’s okay, don’t fret. Git is smart enough to know the main branch hasn’t changed, so it knows it doesn’t need to perform a merge, just a replace.
Now, when we merge the second branch is where Git needs to perform the RPD merge (since the base has changed).
Our configurations now tell Git to, instead of trying to merge an RPD file itself, use our Python script. Our Python script then opens up the Administration Tool, provides all the information it needs, and performs the merge for us.
An RPD which is the combined result of the other two RPDs. Screenshots don’t do the process justice, though. Let’s see it in real-time:
It’s almost magic.
Advantages and Drawbacks
Now that we see how easy it is to use, let’s take a closer look at what this approach affords us, as well as what it costs.
What we gain
- The RPD can be maintained in Git, alongside your other artifacts. Full versioning and concurrent development on the RPD is now available.
- The RPD in Git is now indifferent to any workflow, branching structure, GUI, etc. This isn’t a custom tool which abstracts Git away, it’s just extending the capabilities.
- Since the RPD merge process uses the Merge command in the Administration Tool, we have the confidence that the merge process uses the best available method.
- Merge Conflicts are still handled through the Administration Tool. If a merge conflict occurs, it actually stops processing and prompts the user to make decisions. No new process or methods to learn here!
What we lose
- We can’t do a “diff” operation on the RPD using Git. It’s possible to compare RPDs through some other command-line utilities provided from Oracle, as well as the Admin Tool, but Git can’t show us the differences.
- The .gitattributes file must be present, or else it won’t work. One solution is to put it in your master branch and propagate it down to all other branches. Still, there’s always the potential for the file to be accidentally deleted.
- Since the merge process uses the Merge command in the Administration Tool, it’s not possible to perform the Merge operations on any OS besides Windows. This may make it difficult to incorporate into a Continuous Integration (CI) or Continuous Delivery (CD) environment.
There are many techniques and approaches to performing an RPD merge in the OBIEE development process. From the MUD process to working with an RPD in Git, the important thing is to decide on an approach that works best for your organization. The approach shown above provides the most flexibility, while also being the most reliable, but with the typical costs of using a binary RPD file.
Empowering developers with Git shouldn’t be scary, it should be exciting. Contact us to see how Git can help empower your developers and your business.