Set Up Your System for Repository Development Under Source Control Management

To set up your system for repository development under source control management, you must set up an SCM configuration file with commands specific to your SCM system, and generate an MDS XML repository and check it into your SCM system.

This section contains the following topics:

Create an SCM Configuration File

To integrate the Administration Tool with your source control management system (SCM), you must create an XML configuration file based on your specific SCM system.

The configuration file contains the SCM system commands for adding, deleting, checking out, and renaming files. The Administration Tool issues these commands to the SCM system when repository objects are created or updated, resulting in corresponding new or changed MDS XML files. The Administration Tool doesn't commit the changes to the SCM system. The repository developer must always check the files into the SCM system directly. The separate check-in in the SCM system facilitates viewing any conflicts or implementing merge decisions in the SCM environment rather than the Administration Tool environment.

If you create or edit an SCM configuration file while an MDS XML repository is open, you must ensure that Use Source Control is selected to enable the New or Edit buttons.

The default location for SCM configuration files is Oracle_Home/user_projects/domains/bi/config/fmwconfig/biconfig/OBIS.

You shouldn't store security-sensitive environment variables in the configuration file. If security-sensitive variables are required by your SCM system, to avoid the security risk, you can launch the Administration Tool from Windows Command Prompt with any security-sensitive variables already set.

Open the Administration Tool and select Tools, then select Options.
Select the Source Control tab.
Click New to create a new configuration file. The Specify new configuration file window is displayed.
Provide a file name using the XML file extension, and click Save.
Click Load in the SCM Configuration Editor.
Select a template file, and click Open.
In the SCM Configuration Editor, provide an optional description, then enter or edit commands for your system in the Commands tab.
For longer commands, click the ellipsis button to enter commands in the Command Editor window.

Use the ${file}, ${filelist}, ${from}, and ${to} tokens to define the commands. You can also use the List File option in conjunction with the ${filelist} command to set the behavior. The tokens can be used as follows:
- ${file} specifies that a command must be run sequentially, one file at a time. ${file} is required for the Add Folder and Add File commands.
- The behavior of ${filelist} varies, depending on whether List File is selected:
  - ${filelist} without List File selected causes the Administration Tool to group as many files as possible for the given command such as Pre-Delete, Delete, or Check-out, staying under the 32k character limit for launching a process. Processing is repeated until all files have been processed.
  - ${filelist} with List File selected instructs the Administration Tool to create a temporary file that holds the file list. The file list format is one file name for each line, which is a typical format among SCM vendors. List File is valid for Pre-Delete, Delete or Check-out commands. It results in much faster operations and should always be selected for SCM systems that support it.
  You can use${file} or ${filelist} for Pre-Delete, Delete, and Checkout. List File only works in conjunction with ${filelist}.
- ${from} and ${to} are used to specify the original file name and new file name in Rename commands.
  
  Not all SCM systems support file rename operations natively. If this is the case, leave the Rename field blank rather than attempting to construct a rename operation by concatenating different commands. The Administration Tool performs the rename operation.
Note:

Some SCM systems don't include commands for working with folders. If this is the case, leave Add Folder blank. The Administration Tool always creates folders for you when needed.

Even if your SCM system does include folder management commands, the Administration Tool doesn't remove folders. You must remove folders directly in the SCM system if necessary.
Select the Environment Variables tab, and then specify environment variables required by your SCM system.
Click Test in the Environment Variables tab to open the Test SCM Configuration window. Then, enter a command and click Execute to test a particular command. If the environment is correct, the correct output should appear after running the command.
Select the Post-save comment tab to enter text that appears after changes are saved in the Administration Tool. You can use the Post-save comment to remind developers to check-in there changes.
Click OK to save the configuration file, or click Save As to save a copy if you loaded and modified a template configuration file.

Create an MDS XML Repository and Check In Files to the SCM System

To integrate with an SCM system, you must convert your Oracle BI repository to MDS XML format.

Use one of the following options to create an MDS XML repository and check it into your source control system:

Save an Existing Repository File in MDS XML Format

If you've an existing repository file, use these steps for initial import to convert it to MDS XML.

Open your existing Oracle BI repository file (RPD) in the Administration Tool in offline mode.
Select File, then select Save As, then select MDS XML Documents.
Select a root location for your MDS XML repository files, and then click OK.
Perform the steps in your source control management system to add and check in the files.

Use the specialized commands for bulk file import, available for most SCM systems. These commands are optimized to deliver entire trees of files to source control in a very efficient way. For example, in Subversion, use the following command:

svn import module_name -m "Initial import"

You can also use the biserverxmlgen utility with the -M and -D options to generate MDS XML from an existing Oracle BI repository. See Generating MDS XML from an Existing RPD Using a Command-Line Utility in the XML Schema Reference for Oracle Business Intelligence Enterprise Edition.

Create a New Repository in MDS XML Format

Use these steps to create a new repository in MDS XML format.

Open the Administration Tool and select File, then select New Repository to open the Create New Repository Wizard.
Select the MDS XML Documents option in the wizard. Complete the other wizard steps.
Perform the necessary steps in your source control management system to add and check in the files. For large repositories, use the specialized commands for bulk file import for your SCM system.

Don't create a new MDS XML-format repository, add objects, and then select Link to Source Control. This method doesn't work, and SCM commands aren't generated.

Link to Source Control Files to Convert Your Repository (Small Repositories Only)

For very small repositories, you can use the Link to Source Control files method to convert a binary Oracle BI repository file to MDS XML format.

Using the Link to Source Control Files method to initially import your repository is only recommended for very small repositories. This method is too slow for large repositories, tens of thousands of files, because the Administration Tool imports the files one at a time using the standard add file command, rather than using specialized commands for bulk file import.

The repeated invocation of the add file command might increase the chances of transient errors. If these occur, you might need to restart the process a few times before all files are successfully imported to source control.

See Create an SCM Configuration File.

Ensure that you've an SCM configuration file defined.
Create an empty root folder for the MDS XML repository.
Open your existing Oracle BI repository file in the Administration Tool in offline mode.
Select File, then select Source Control, then select Link to Source Control Files.
Select the root folder you created, and the appropriate SCM configuration file.

If you need to change the configuration file later, select Tools, select Options, select Source Control, and then click Edit to change the configuration file.
Click Save. An MDS XML repository is created, and the necessary add file operations are performed in your source control system.
Commit the changes in your SCM system.