WebFOCUS Online Help > Managed Reporting Administrator > Change Management > Change Management Load Utility

Change Management Load Utility

In this section:

How to:

Reference:

The Change Management Load Utility enables Managed Reporting administrators to load specific change packages created with the Change Management Extract Utility into another environment.

Change packages are loaded into the target repository using a Java program called IBILoadRepos. If an item's domain does not exist during the load process, the Change Management Load Utility creates the domain automatically and a message is written to the cmevent.log file.

It is recommended that you create domains in the development environment using the Domain Builder and allow the Change Management Load Utility to automatically create domains in your test and production environments. This is beneficial because creating and then deleting a domain in the target repository results in the Change Management Load Utility being unable to load items into it. When a domain is deleted, its entry in mrrepos.htm is set to disabled instead of being deleted. The Change Management Load Utility is unable to load items into a disabled domain and cannot create a new domain with the correct HREF. In this situation, an error is written to the cmevent.log file and the item is not loaded.

Top of page
Procedure: How to Access and Use the Change Management Load Utility
  1. Move the desired change packages from the source \utilities\cm\extract directory or other specified location, to the target environment's \utilities\cm\load directory or any of the subdirectories of \utilities\cm.

    Note: If the Realm Driver is being used in the target environment to authenticate and/or authorize to a relational DBMS, make sure that the path to the JDBC drivers are defined in your application server classpath. For example, if using MSSQL Server for MR authentication, the path to the drivers would be defined in the Java Classpath for Tomcat.

  2. Go to the WebFOCUS Welcome Page on the target environment where you want to load the change package created with the Change Management Extract Utility. 
    http://hostname[:port]/ibi_apps/

    where

    hostname[:port]

    Is the name of the Web server and optional port number where the WebFOCUS Web application in the desired target environment is deployed.

  3. Click the Managed Reporting Change Management Load link.
  4. Type your Managed Reporting Administrator user ID and password and click Logon.

    The Change Management Load Utility loads and displays any folders in the \utilities\cm directory that contain .zip files.

  5. Select a desired .zip file change package in the Available Change Packages pane to copy it to the Selected Change Packages pane. You can single-click, double-click, or drag and drop the change package as shown in the following image.

    The options you can select include Overwrite duplicates (default), Backup packages (available only when Overwrite duplicates is selected), Preserve Creation info, and Preserve Modifier info. For details, see Change Management Load Utility Options.

  6. To remove a selected change package from the Selected Change Packages list, select the item and press the Delete key. To remove all selected change packages, click the Clear File List button.
  7. Click Load Change Package to load the change package into the MR repository of your target environment.

    A pop-up message appears when the load process is completed. Click Open Log File to view the contents of the cmevent.log file that was created in the \utilities\cm\ directory. The log file displays helpful information about the success or failure of the load process.

Note: For additional convenience, the MR Change Management Load Utility is also available from the WebFOCUS Adminstration Console in the Utilities section of the main menu. For more information, see the WebFOCUS Security and Administration manual.

Top of page
Reference: Change Management Load Utility Options

The following describes the options you can apply when using the Change Management Load Utility to load change packages into an environment.

Top of page
Alternate Change Management Load Program

The following topics explain how to prepare for, and how to run, the alternate Change Management Load program.

Top of page
Reference: Preparing to Run the Alternate Change Management Load Program

In some cases you must edit the script file that calls IBILoadRepos before running the utility. This script file is found in the inst_dir\WebFOCUS76\utilities\cm directory and is named cmload.bat (cmload on UNIX).

  1. Verify that the setting MRID=admin is valid for your installation. You must set the variable MRID inside this script to a valid Managed Reporting (MR) user ID. Initially, this variable is set to admin to match the default MR administrator account. The ID specified does not need to have MR administration privileges; it must be a valid MR ID.
  2. Set JDBC_DRIVER_JARS, if necessary. When using the Realm Driver to authenticate and/or authorize to a relational DBMS system you must set JDBC_DRIVER_JARS to the full path to your driver's Jar file(s). If your driver is made up of multiple files, use the semi-colon ';' as a separator on Windows and a colon ':' as the separator on UNIX.
  3. If you are using a custom Realm Driver extension, you may need to include additional Jar file(s) in the class path of this utility to use it. Simply append these to the JDBC_DRIVER_JARS variable.
Top of page
Procedure: How to Run the Alternate Change Management Load Program
  1. Move the desired change packages from your source environment's /utilities/cm/extract directory to the target environment's /utilities/cm/load directory. By default, all change packages in this directory will be loaded. Make sure that only the change packages you want to process are located here.
  2. Navigate to the WebFOCUS76/utilities/cm directory.
  3. Execute the cmload.bat file (Windows systems) or cmload file (UNIX systems). A series of messages appear: 
    -------------------------------------------------
 Managed Reporting Change Management Load Utility
 WebFOCUS Release 7
-------------------------------------------------
Finished.
Press any key to continue . . .

    A log file, WebFOCUS76/utilities/cm/cmevent.log, is created with helpful information about the load. Each time a package is loaded, information is appended to cmevent.log file.

Top of page
Reference: IBILoadRepos Usage

The underlying program that loads change packages into a Managed Reporting Repository is written in Java and is contained in the archive WebFOCUS76/utilities/cm/IBILoadRepos.jar. You call the program directory (or modify the cmload batch file) by using the following usage reference.

 
java [options] -cp archivepath ibi.srv.cm.IBILoadRepos arguments-createBackout
-backoutDir 
-preserveCreationInfo 
-preserveModifierInfo

where options include:

-DinfoLogType={FILE|CON|OFF}

Optional. If you want informational messages associated with the load to be logged, select FILE to write them to cmevent.log in the current directory. Each time the load program is run, messages are appended to this file. If you want these messages echoed to the command console, select CON, otherwise select OFF. Not specifying this option is equivalent to selecting CON.

-DerrorLogType={FILE|CON|OFF}

Optional. If you want error messages associated with the load to be logged, select FILE to write them to cmevent.log in the current directory. Each time the load program is run, messages are appended to this file. If you want these messages echoed to the command console, select CON, otherwise select OFF. Not specifying this option is equivalent to selecting CON.

where:

archivepath

Is the full or relative path to the IBILoadRepos.jar file, and the following supporting files: ibi_resolver_1_1.jar, ibi_xalan_2_7_0.jar, ibi_xalan_2_7_0_serializer.jar, ibi_xerces_2_7_1.jar, and ibi_xml_apis_1_3.jar. If you are using the Realm Driver, you must also include uas.jar and supporting files (if any) such as your JDBC .jar files if the Realm Driver is using an RDBMS.

where arguments include:

-user userid

Required. The ID specified is required to initialize the IBILoadRepos program. This ID does not need to have MR administration privileges; it just needs to be a valid MR ID.

-confDir configpath

Required. Specifies the full or relative path to the directory containing the WebFOCUS deployment descriptor file (web.xml). IBILoadRepos reads this file to locate several settings necessary to initialize itself, including webfocus_client_root and WFENCR (optional encryption setting). With some application servers, this web.xml file is deployed to a different location in the file system. In this case, you may need to keep these files synchronized or point -confDir to the deployed file.

-d loaddirectory | -f loadfile

Either -d or -f is required. Specifies the absolute or relative path to the directory containing the change package .zip files or a single .zip file (depending on selection). If -d is selected, all .zip files in the specified directory are loaded (in sort order).

-noOverwrite

Optional. If specified, files found with the same internal reference are not overwritten during the load, and are loaded with a new internal reference instead. For example, if a report with the description "Sales Report" and internal reference "app/salesrep.fex" is being loaded with the -noOverwrite option and the same file already exists in the target repository, a new file is created with the description "Sales Report (Copy 1)" and new internal reference, for example, "app/gwrwko31.fex".

A back-out package containing the original versions of the files you are about to update can be created during the load. Open the batch file that calls IBILoadRepos and add: 

-createBackout

By default, the back-out package is created in the backout subdirectory of the current directory. If the backout directory does not exist, the utility creates it automatically. The name of the back-out package is the same name as the package being loaded, this is why the load and back-out directories must be different.

To specify a different directory, include the following with either a fully qualified or relative path:

-backoutDir

This directory must exist or an error is written to the log file and the item is not loaded.

To back-out a change, move the back-out package into the load directory and rerun the Load program.

You should create a different batch file for backing out changes because you do not want to specify the -createBackout option when running the utility to back out a change. If the items being added do not yet exist in the target environment, there will be no corresponding items in the back-out package, and you must use the GUI tools to back-out the added items.

To preserve change history creation information, include:

-preserveCreationInfo

This retains the report creation date and time, and the name (and user ID) of the person who created the report, by preserving the createdon and createdby flags found in the change package.

To preserve change history modifier information, include:

-preserveModifierInfo

This retains the last modification date and time for the report by preserving the lastmodby flag found in the change package.

WebFOCUS