61 Using ICommand

This chapter describes how to use the ICommand command-line utility to perform operations on items in the Active Data Cache, such as exporting, importing, and renaming. It also describes how to run ICommand from a remote system and execute the commands on a server located remotely.

61.1 Introduction to ICommand

ICommand is a command-line utility (and web service) that provides a set of commands that perform various operations on items in the Active Data Cache. You can use ICommand to export, import, rename, clear, and delete items from Active Data Cache. The commands can be contained in an input XML file, or a single command can be entered on the command line. Informational and error messages may be output to either the command window or to an XML file.

61.2 Executing ICommand

ICommand can be executed using the ORACLE_HOME\bam\bin\icommand.bat file on the Microsoft Windows platform and ORACLE_HOME\bam\bin\icommand.sh shell script on UNIX platforms.

Just entering icommand on the command line provides the user with a summary of the ICommand operations and parameters.

Before attempting to execute ICommand, the JAVA_HOME environment variable must be set to point to the root directory of the supported version of Java Development Kit (see the Oracle BAM support matrix on Oracle Technology Network web site for supported JDK versions).

Note:

When Oracle BAM is installed, ICommand looks for the Oracle BAM Server on port 9001 by default. If the Oracle BAM Server port number is changed from the default during the setup and configuration of Oracle BAM, then the user must manually change the port number from 9001 to the new port number in the file BAMICommandConfig.xml.

The property to change is

<ServerPort>9001</ServerPort>

The BAMICommandConfig.xml file is located in WLS_HOME/user_projects/domains/base_domain/config/fmwconfig/servers/bam_server1/applications/oracle-bam_11.1.1/config/.

61.3.1 How to Specify the Security Credentials

ICommand requires users to provide security credentials when running operations. If no security credentials have been specified in the configuration file, ICommand securely prompts for a user name and password.

To use default credentials, add the ICommand_Default_User_Name and ICommand_Default_Password properties to the WLS_HOME/user_projects/domains/base_domain/config/fmwconfig/servers/bam_server1/applications/oracle-bam_11.1.1/config/BAMICommandConfig.xml file. For example:

However, command line entries always override the properties specified in the configuration file.

The user name and password for running ICommand operations can come from the configuration file, command line prompts, or command line options as follows:

If the user name and password are only specified in the configuration file (that is, -username parameter is not used in the command line), then the ICommand_Default_User_Name and ICommand_Default_Password values in the configuration file are used.

If only the user name is specified in the configuration file and the password is not, then the user name value is used, and ICommand prompts the user for the password at the command line.

If user name is specified on the command line, then that value is used, and ICommand prompts the user for a password. The password prompt occurs regardless of any properties specified in the configuration file. For example:

61.3.3 How to Specify Object Names

Whenever an object name is specified in a command, the following rules apply.

General rules

When specified on a command line, if the name contains spaces or characters that have special meaning to DOS or UNIX, the name must be quoted according to the rules for command lines.

When specified in an XML command file, if the name contains characters that have special meaning within XML, the standard XML escaping must be used.

Data Objects

If the Data Object is not at the root, the full path name must be given, as in the following example:

/MyFolder/MySubfolder/MyDataObject

If the Data Object is at the root, the leading slash (/) is optional. The following two examples are equivalent:

/MyDataObject
MyDataObject

Data Object Folders

To specify a folder in Data Objects you must include the prefix /public/DataObject/ at the beginning of the path to the folder.

/public/DataObject/MyFolder/MySubfolder

Reports and Report Folders

The full path name plus the appropriate prefix must be specified as in the following examples.

For shared reports the /public/Report/ prefix must be included as shown here:

"/public/Report/Subfolder1/My Report"

For private reports the /private:user_name/Report/ prefix must be included:

"/private:jsmith/Report/Subfolder1/My Report"

The /private:user_name/ part of the prefix may be omitted if the user running ICommand is the user that owns the report.

"Report/Subfolder1/My Report"

The path information without the public or private prefix is saved in the export file.

Similarly, a report folder can be specified using the appropriate prefix.

/public/Report/Subfolder1
/private:jsmith/Report/Subfolder1

Alert Rules

Either the name of the Alert, or the full name of the Alert may be specified. The following two examples are equivalent for Alerts if the user running ICommand is the user that owns Alert1:

Alert1

/private:user_name/Rule/Alert1

If the user running ICommand is not the owner of Alert1, then only the second form may be used.

All other object types

Specify the full name of the object.

61.3.4 How to Specify Multiple Parameter Targets

Instead of creating a separate command line for each Active Data Cache object type, such as Dataobject, Folder, Report, and Rule, on which to execute a particular command, ICommand enables you to pass parameter values to several object types in the same command line.

In this example, while exporting all of the objects in the system, the command passes owner = 1 to the report, rule, and folder Active Data Cache object types. The command also passes permissions = 1 to the dataobject and folder object types. The comma (,) separates the object types and the parameter is listed after a colon (:).

Supplying multiple values in the example single command line gives the same results as the following three commands:

61.4 Using Command-line-only Parameters

Optional parameter that specifies a single command to be executed. Any parameters needed for the command must also be on the command line.

The Cmdfile and cmd parameters are mutually exclusive. Exactly one of them must be present.

Cmdfile

-cmdfile file_name

Optional parameter that specifies the name of the file that contains commands to be processed. Because this is an XML file, it would usually have the XML extension, although that is not required.

The Cmdfile and cmd parameters are mutually exclusive. Exactly one of them must be present.

Debug

-debug flag

Optional parameter that indicates whether extra debugging information is to be output if there is an error. Any value other than 0 (zero), or the absence of any value, indicates that debugging information is to be output. If this parameter is not present, no debugging information is output.

Domain

-domain domain_name

Optional parameter that specifies the domain name to use to login to the Active Data Cache (the name of the computer on which the Active Data Cache server is running).

If this parameter is omitted, main is used, which means the server information is obtained from the ServerName property in the ICommand.exe.config file.

If the reserved value ADCInProcServer is used, then ICommand directly accesses the Active Data Cache database (which must be local on the same system on which ICommand is running) rather than contacting the Active Data Cache server. This option is necessary only when the Active Data Cache server is not running; otherwise corruption of the database could occur. The information about the location and structure of the Active Data Cache database is obtained from various keys in the ICommand.exe.config file.

Logfile

-logfile file_name

Optional parameter that specifies the name of the file to which results and errors are logged. If the file does not exist, it is created. If the file does exist, any contents are overwritten. Because this is an XML file, it would usually have the XML extension, although that is not required.

If this parameter is not present, results and errors are output to the console.

Optional parameter that indicates whether an existing log file is to be overwritten or appended to. The possible values for this parameter are append or overwrite. In either case, if the log file does not exist it is created.

If this parameter is not present, overwrite is assumed.

Because it is XML that is being added to the log file, if the append option is used the XML produced may not be strictly legal, as there is no top level root tag in the XML produced by successive appends (ICommand appends the same tag each time it is run). It is left up to the user to handle this.

Username

-username user_name

Optional parameter that specifies the username that the command should run as. There is no password parameter.

ICommand requires users to specify security credentials when running commands. ICommand securely prompts for a user name and password. If the -username parameter is specified on the command line, ICommand prompts the user for the password only.

61.5 Running ICommand Remotely

You can run ICommand from a remote system (where Oracle BAM is installed) and execute the commands on a server located remotely. To run ICommand remotely, add the properties ServerName and ServerPort in WLS_HOME/user_projects/domains/base_domain/config/fmwconfig/servers/bam_server1/applications/oracle-bam_11.1.1/config/BAMICommandConfig.xml, as shown below.