by Christian Screen
Published September 2012
This tutorial was developed so that anyone with a basic understanding of the Oracle Business Intelligence (OBI) development lifecycle can learn how to configure the Oracle Business Intelligence 11g (22.214.171.124) metadata repository for development using the new MDS XML source control management functionality.
Oracle BI 11g version 126.96.36.199 has integrated the concept of Source Control Management (SCM) into the Oracle BI server metadata repository (RPD). This allows Oracle BI metadata modeling efforts to conform, in a small way, to modern source control systems. Most organizations currently leverage some SCM system such as ClearCase, Git, Subversion, Perforce, or Mercurial to version development efforts.
This article explains how to use Git, the open source software Version Control System (VCS), in compliance with the new Oracle BI MDS XML SCM option. The focus is on Git because it is the system gaining the quickest adoption in enterprise development efforts. Git has many benefits over other SCM tools, such as its cost, branching model, and localized integration. Git was also developed by the revered father of Linux, Linus Torvalds, making it a great fit for Oracle Linux. Another reason this article focuses on Git is that while the new SCM functionality in Oracle BI 11g is SCM agnostic, the only SCM interaction templates provided for this integration are for the Subversion SCM. Those who need to port to SCM tools other than Git or Subversion will find insight in this article, as well.
The Administration Tool used to develop the Oracle BI metadata repository is a Microsoft Windows based application. The Administration Tool will communicate with the Git SCM repository using the Git client software. Thus, the first step to configure the new Oracle BI MDS XML SCM functionality is to install the Git client onto the workstation on which you will be developing:
MDS XML syntax varies little when compared to the core XML standard. However, MDS XML has several specific references that make it compatible with the Oracle Metadata Service standard (yes, think MDS schema that gets created using the RCU utility). It is also different from the XML that gets generated when using the Oracle BI XML API, which outputs only a single XML file. The MDS XML outputs a large number of separate but logically-referencing XML files that allow for separation of metadata in order to better leverage XSD compliance and storage capabilities.
Setting up this functionality boils down to three main operations:
An Oracle BI metadata repository developer needs to have the ability to open the current development RPD in offline mode in order to create the MDS XML file directory necessary to leverage SCM support.
You've now created the MDS XML directory structure and files that will be used for the SCM functionality. However, right now your Oracle BI 188.8.131.52+ client tool has no idea what SCM utility you plan to use to manage those newly created files. You have to tell it by configuring an XML file via the Administration Tool options area.
Ultimately the Administration Tool will reference an XML-based configuration file to understand how to execute commands via the SCM tool of choice—in this case Git. Because the Oracle BI SCM functionality is SCM client agnostic, the Administration Tool only communicates general function calls to the SCM client. Those commands specific to the SCM client must be outlined in an XML Configuration file that is created with the assistance of an option found within the Administration Tool. To configure the SCM specific commands:
Now, update the fields according to the Git client command line switches and commands. By the way, if you used the default installation path for the Git client the Git executable is here, C:\Program Files\Git\cmd\. But since you used the PATH variable option when you installed the Git client earlier, you don't need to use the full path name.
Make the command fields appear as indicated in Figure 4.
You may have noticed that we didn't configure any items in the Environment Variables or Post-save comment tabs in the SCM Configuration Editor. The environment variables for an SCM client usually get set with the client installation process. The Post-save comment tab allows you to enter a message that will appear after the repository under source control is saved and the SCM commands have been called successfully by the Administration tool. To add a comment that appears after the SCM Commands are called:
At this point you've created the MDS XML directory and files and configured your Oracle BI Administration Tool with the commands necessary to interact with the Git SCM. Now you must make a local Git SCM repository to stage the MDS XML files and hold versioning for your development efforts. Remember at this point we are talking about two separate tools: The Oracle BI Administration Tool, and Git. There is no real transparently integrated relationship here. So you'll create a Git repository to hold the metadata about your MDS XML files. You'll then import those files into the local Git SCM repository so that Git can keep track of them and their changes. Here's how to initially import the MDS XML files:
You've now executed some rudimentary Git SCM instantiation commands. The git init command creates the repository folder .git in the root directory. The git add . command acknowledges all files and folders that should be added to the Git repository. Finally, the git commit -m "Initial Commit" command puts the files added from the git add . command into the repository with a comment to describe the transaction. Lastly, you can verify that the files were in fact committed by doing the following:
The concept of opening the Oracle BI repository in the Administration Tool is similar to opening the binary RPD file but opening the MDS XML repository under SCM can only be conducted in Offline mode:
If you look at the application title bar you will see that it is suffixed with "(under source control)" in the text. Now that you've opened the MDS XML directory under Source Control your SCM configuration options are automatically set to persist. So the next time you open this MDS XML directory in the Administration Tool you won't to choose the Source Control option—it will load automatically.
In order to understand how changes to the repository under SCM affect the local Git repository, this exercise will step you through making a simple change to the repository in order to mimic a real-world development effort:
Since changes were visible in the Source Control Log and there were no error messages, it is safe to assume that the SCM commands were called properly by the Administration Tool. The files were modified and are placed in what is called the Unstaged Working Area of the Git repository. These unstaged files will need to be "staged." This is the term used before changes are permanently made to the current workspace, in this case the main branch, of the local SCM repository. It is best to verify the status of these files in the SCM system itself using the client tools. This can be done in two different ways: Command-Line or Graphically.
To view status of any modified files using the Command Line Interface, follow these steps:
The result of this command shows the same information that was shown in the Administration Tool prompt after you saved the changes you made in the previous step.
To view the status of any modified files using the Git GUI, follow these steps:
The files inside the Unstaged Changes area show the same files shown to be modified when we saved the repository. This verifies that the Administration Tool and the SCM commands have worked successfully together at this point. You've now completed the sanity check on the modified files and now you're ready to stage and commit those files to the local Git repository in order to solidify the changes.
Moving modified files and changes in the Unstaged Changes area to Staged Changes status and conducting the commit of those changes cannot be done by the Administration Tool. It must be done by the developer using the SCM client. This is the case regardless of which SCM tool you've chosen to use. Either the Command Line Interface (CLI) or the GUI interface could be used. The Git GUI interface is fairly straightforward - just click the Stage Changed button, enter a message in the Commit Message area, and click the Commit button. The steps outlined below will use the CLI in order to commit the changes.
You can now verify that the changes were committed to the repository by entering the commands git status or git log.
After you've committed the changes manually using the Git SCM client tools you have successfully leveraged the Oracle BI SCM functionality. There are a few other ancillary tasks that you will wish to conduct as part of the development lifecycle.
One of the next tasks that will arise during the development cycle is for you to deploy the repository into online mode so that you can view and test any changes that you've been making offline using the MDS XML SCM functionality. You cannot deploy the MDS XML files directly to the Oracle BI server. You must convert the files back to a binary RPD format before deploying.
To save the MDS XML back to a binary RPD format:
Notice that the title of the Administration Tool application has changed back to the name of the RPD and is no longer displaying the text suffix, (under source control). You may now use the Enterprise Manager Fusion Control to upload this saved binary RPD file to the Oracle BI Server.
Another task that you should be aware of is viewing the log file and handling errors. If an error occurs, always be sure that you use the method described above to save the MDS XML back into a binary RPD format. You can then address the errors you've encountered occurring between the Administration Tool and your SCM repository using the SCM client tools. Once you've fixed the issue you may re-open the MDS XML files and continue with development.
The log file containing all commands sent to your SCM tool is generally available for you to review. While in the MDS XML SCM mode select File | Source Control | View Logs from the file menu bar. This log is also available on the file system from the following location, C:\Program Files\OBIEEClient11116\oraclebi\orainst\diagnostics\logs\OracleBIServerComponent\coreapplication\<windows_username>__NQSAdminTool.log where C:\Program Files\OBIEClient11116\ is the path in which the Oracle BI Client tools were installed.
The general idea of using a Source Control Management system is not new to Oracle but is new to the Oracle BI development lifecycle. The ability to split the repository into many smaller XML files allows for using a differencing engine to determine the delta of modified files. It also makes searching for specific keywords across the repository metadata much easier. It is no replacement for the existing Multiuser Development Environment and although there are only two default SCM command templates provided with the Oracle BI installation files there is no guidance on whether one SCM tool is better than another for this functionality. Regardless, the SCM agnostic capability provided by this functionality is a progressive option for the tool which should assist with its adoption by Oracle BI developers.
Christian Screen, a Senior Manager for Capgemini North America's Oracle Analytics Practice, is a Business Intelligence evangelist with over 15 years of experience in technology, ranging from low-level programming, e-commerce, Data Warehousing, Enterprise Performance Management, and Business Intelligence. He is an Oracle ACE, an Oracle Deputy CTO, and holds several technology and project management certifications.