Setting 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:

Creating an SCM Configuration File

To integrate the Oracle BI Administration Tool with your source control management system, 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.

Note:

The Administration Tool does not commit the changes to the SCM system. The repository developer must always check the files into the SCM system directly. This way, the repository developer can view any conflicts or make merge decisions in the SCM environment rather than the Administration Tool environment.

To create a configuration file for your SCM system:

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.

Note: This procedure assumes that you do not have an open MDS XML repository in the Administration Tool. 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.
Provide a file name and click Save. The file must have the XML file extension.

The default location for SCM configuration files is ORACLE_INSTANCE/config/OracleBIServerComponent/coreapplication_obisn. Although templates are also available in this location, do not select a template file during this step. Instead, you can load a template in the next step.

Note:

The SCM configuration template files are called scm-conf-ade.template.xml and scm-conf-svn.template.xml. In addition to being available in the ORACLE_INSTANCE location indicated, they are also available on the Oracle Technology Network (OTN) at:

http://www.oracle.com/technetwork/middleware/bi-foundation/downloads/obieescmconfigfiles-1568980.zip
To load a template configuration file, click Load in the SCM Configuration Editor. Then, select a template file (for example, scm-conf-svn.template) and click Open.

Unless it is your intention to modify the configuration file template itself, ensure that Edit in Configuration Editor is not selected. If you select this option, the file name displayed in the Configuration File field in the SCM Configuration Editor changes from the file name you provided in the proceeding step to the template file name, and changes are saved by default to the template file.
In the SCM Configuration Editor, provide an optional description, then enter or edit commands for your system in the Commands subtab. 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. Execution 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 either ${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 will do this for you with greater efficiency.
Note:

Some SCM systems do not 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 does not remove folders. You must remove folders directly in the SCM system if necessary.

Select the Environment Variables subtab, and then specify environment variables required by your SCM system.

You can paste environment variables directly from your operating system variable list, paste environment variables from the clipboard, or manually add environment variables. The table describes the options available for managing environment variables in the Environment Variables subtab.

Option	Description
Paste environment variables	Enables you to paste environment variables directly from your operating system. Click this option to open a window where you can enter filter criteria, then click OK. Enter * in the filter window to paste all environment variables.
Paste from clipboard	Enables you to paste text from the clipboard. To use this option, copy text in the following format: variable_name1=variable_value1 variable_name2=variable_value2 Each environment variable must be on its own line. Note: The standard Windows command `set` provides output in this format for environment variables.
Add	Adds a row to the table so that you can manually enter environment variables. Provide the variable name in the Variable column, and its definition in the Value column. Leading and trailing white space is trimmed. You can use %VAR% in the variable definition to reference a previously defined variable.
Delete	Deletes the given row in the environment variables table.

Note:

You should not 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 a DOS window with any security-sensitive variables already set.

Click Test in the Environment Variables subtab 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 executing the command.
Select the Post-save comment subtab to enter text that will appear after changes are saved in the Administration Tool. This capability is a way to remind developers to check files directly into their SCM system after saving. For example, a post-save comment might indicate:

Files have been synchronized to source control. Remember to check in changes after testing.
Click OK to save the configuration file, or click Save As to save a copy if you loaded and modified a template configuration file.

Creating an MDS XML Repository and Checking 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:

Saving an Existing Repository File in MDS XML Format

If you have an existing repository file, use these steps to convert it to MDS XML.

The steps described in this section are the recommended method for initial import.

To save an existing repository file in MDS XML format:

Open your existing 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 necessary 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"

Note:

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

Creating a New Repository in MDS XML Format

Learn to create a new repository in MDS XML format.

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.

Note:

Do not create a new MDS XML-format repository, add objects, and then select Link to Source Control. This method will not work, and no SCM commands will be generated.

Linking 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 RPD file to MDS XML format.

To link to source control files to convert your repository:

Ensure that you have an SCM configuration file defined. See Creating an SCM Configuration File for more information.
Create an empty root folder for the MDS XML repository.
Open your existing RPD 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.

Note:

If you need to change the configuration file later, you can go Tools > Options > Source Control and 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.

Note:

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.

Note also that 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.