bfimport reference

Use the bfimport utility to import definitions for projects and other objects to the user interface that were previously exported to an XML file. You can also use the Import utility to import selected objects from the XML file.

This topic describes the syntax of the bfimport command and provides usage details.

Syntax

bfimport

bfimport [-L] <file_name>
bfimport [-p -I -s -S -e -c -C -u -T -f -d -r ] <file_name.xml>
bfimport [-L | [-p -I -s -S -e -c -C -u -T -f -d -r ]] <file_name.xml>

Restrictions and considerations

Server authorization passwords for servers are not included in the export file; you must manually enter server authorization passwords.

By default, on import if an object exists with the same name as an imported object, the object being imported is renamed to prevent the database object from being overwritten. Alternatively, you can choose to replace objects with the -r option if an object with the same name exists. For snapshot objects, the objects are compared by UUID rather than by name.

By default, objects are renamed by bfimport and the following naming convention is used:

<object_name>_IMPORT_<number>

For rename, snapshot objects lose their snapshot names and are imported as a new base or parent-level snapshot, even if the snapshot object is a child of a parent snapshot.

For details about rename, see Renaming and replacing objects on import.

To replace objects, you must specify the -r option. The replace option overwrites existing objects. For 7.0.2 and earlier export files, snapshot objects are not replaced. Instead, they are renamed using the <object_name>_IMPORT_<number> convention. For 7.1 export files, snapshot objects are replaced if their UUIDs match.

Prerequisites

Before using the bfimport utility, be sure that you have met these prerequisites:
  • An export XML file that was created by the bfexport command or the .export dot command.
  • Find the bfimport utility in your Build Forge installation directory.
  • The bfimport command must be able to find the buildforge.conf file and access the Build Forge database. Run bfimport from the directory where buildforge.conf is located, which is in <bfinstall> on Windows and in <bfinstall>/Platform on UNIX and Linux.
    Note: If a project you are importing has a notify group and the notify group is not a built-in group, such as Build Engineer, Developer, Guest, Operator, System Manager, you must create an access group before importing.

Usage

To complete common import tasks, use these command options:
  • To display command syntax, use bfimport with no options.
  • To display a summary list of the Build Forge objects in the XML file and their names, use bfimport -L <file_name.xml>.
  • On the zLinux platform, you must run the command as bfexport.pl. For all other platforms, the command does not require an extension.
  • If you specify no options, no objects are imported. You must specify options to import individual objects.
  • If you specify options for objects that do not exist, the import utility skips the objects that are not in the XML file and imports the objects that are in the file.

Examples

To list the Build Forge® objects in the XML file, specify the -L option and the XML file name only. The following example displays partial command output.

C:\Program Files\IBM\Build Forge>bfimport -L samples\projects\basic.xml
10/07/2008 5:31:55 PM: Import: 7624: CRRBF20081I: Importing export
file from a 7.0.10025 version console.
Project : [Basic Sample]
	Tag Variable : [MAJ]
	Tag Variable : [MIN]
	Step : [Checkout Source]
	Step : [Update Applet Version]
	Step : [Create Baseline]
Environment : [Basic Environment]
Class : [Production]
Filter : []
Selector : [Web Server]
Selector : [Local Server]

To import all the objects in an XML file, specify the options for the objects to be imported, as shown in the following example. Objects are renamed on import. A success statement displays if the import is successful.

C:\Program Files\IBM\Build Forge>bfimport -p -I -s -S -e -c -C -u -T -d -f 
"samples\projects\basic.xml"

Option descriptions

Option Description
<file_name.xml> The name of the export XML file that contains the Build Forge® objects to be imported. The XML file must be created using the bfexport command or the .export dot command. The XML file name is required and you must provide the path name if the XML file is not in the current directory, the directory from which you issue the bfexport command.

If the file name contains spaces, you must quote the name.

-L

Lists the objects in the export XML file and their object names. Use this option by itself; do not specify it with other bfimport options. Output from the -L option can be sent to stdout or redirected to an XML or text file.

-p Imports project configuration data from the XML file. Project configuration data includes step and project definition data, including tag variables.

On rename, a project name is imported to the UI as <project_name>_IMPORT_<number>.

-I Imports chained projects or libraries that are referenced at the project or step level.

On rename, a chained project or library is imported to the UI as <project_or_library_name>_IMPORT_<number> in the UI.

-S Imports the selector objects that are defined in the UI.

On rename, a selector is imported to the UI as <selector_name>_IMPORT_<number>.

-s Imports the server objects that are defined in the Management Console, if the -s option is specified for bfexport.

On rename, a server is imported to the UI as <server_name>_IMPORT_<number>.

Server authorization passwords for servers are not included in the export XML file; you must manually enter server authorization passwords.

-e Imports environments and their variables that are referenced at the project or step level.

On rename, an environment is imported as <environment_name>_IMPORT_<number>.

-c Imports classes that are referenced by projects.

On rename, a class is imported as <class_name>_IMPORT_<number>.

-C Imports collectors that are assigned to the servers for the project, if the -C option is specified for bfexport.

On rename, a collector is imported as <collector_name>_IMPORT_<number>.

-u Imports users who are members of the access groups designated to receive email notifications, if the -g option is specified for bfexport.

On rename, information for users is imported as <users>_IMPORT_<number>

-T Imports the user-created notification templates that are assigned to projects and steps, if the -n option is specified for bfexport.

On rename, a notification template is imported as <template_name>_IMPORT_<number>.

-f Imports log filters that are assigned to project steps, if the -n option is specified for bfexport.

On rename, the log filters are imported as <filter_name>_IMPORT_<number>.

-d Imports the LDAP domain controllers defined in the user interface, if the -L option is specified for bfexport.

On rename, the log filters are imported as <LDAP_domain_controller>_IMPORT_<number>.

-r Replaces the imported objects instead of renaming them. By default, imported objects are renamed and the following naming convention is used:
<object_name>_IMPORT_<number>

For 7.1 objects, if you specify the replace option, the bfimport command overwrites objects in the user interface for 7.1 objects.

For 7.0.2 and earlier objects, snapshot objects are not replaced. They are renamed using the following naming convention:
<object_name>_IMPORT_<number>
Important: snapshot objects are evaluated for replacement by UUID rather than by name.

For details, see Renaming and replacing objects on import.


Feedback