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.
This chapter includes the following sections:
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.
For more information about using the ICommand web service, see Section 59.5, "Using the ICommand Web Service."
For information about individual commands and their parameters see Appendix G, "Oracle BAM ICommand Operations and File Formats."
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/.
The basic structure of the ICommand command line entry is as follows:
icommand -username user_name -cmd command_name -name value -type value [-parameter value]
All parameters given on the command line are in the following form:
-parameter value
The parameter portion is not case sensitive. If the value portion contains spaces or other special characters, it must be enclosed in double quotation marks. For example
icommand -cmd export -name "/Samples/Call Center" -type dataobject -file C:\CallCenter.xml
It is required to use quotation marks around report names and file names that contain spaces and other special characters.
For some parameters, the value may be omitted. See Section G.2, "Detailed Operation Descriptions," for information about individual parameter values.
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:
<ICommand_Default_User_Name>user_name</ICommand_Default_User_Name> <ICommand_Default_Password>password</ICommand_Default_Password>
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:
icommand -cmd export -name TestDO -file C:\TestDO.xml -username user_name
On the command line, commands are specified by the value of the cmd parameter. Options for the command are specified by additional parameters. For example
icommand -cmd export -name TestDO -type dataobject -file C:\TestDO.xml
In an XML command file, commands are specified by the XML tag. Options for the command are given as XML attribute values of the command tag, in the form parametername=value.
Command names and parameter values (except for Active Data Cache item names) are not case sensitive.
For information about individual commands and their parameters see Appendix G, "Oracle BAM ICommand Operations and File Formats."
Whenever an object name is specified in a command, the following rules apply.
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.
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
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
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
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.
Specify the full name of the object.
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.
For example:
icommand -cmd export -type all -report,rule,folder:owner 1 -dataobject,folder:permissions 1 -systemobjects 1 -file filename.xml
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:
icommand -cmd export -type report -owner 1 ... icommand -cmd export -type rule -owner 1 ... icommand -cmd export -type folder -owner 1 ...
The following parameters can appear only on the command line:
Cmd
-cmd commandname
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.
See Section G.4, "Format of Log File" for more information about the log file format.
Logmode
-logmode mode
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.
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.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <BAMICommand> <ServerName>host_name</ServerName> <ServerPort>7001</ServerPort> <Communication_Protocol>t3</Communication_Protocol> <SensorFactory>oracle.bam.common.statistics.noop.SensorFactoryImpl</SensorFactor y> <GenericSatelliteChannelName>invm:topic/oracle.bam.messaging.systemobjectnotific ation</GenericSatelliteChannelName> </BAMICommand>
The Oracle BAM version installed on the remote system should be same as the Oracle BAM Server version (that is, both servers should be from the same label).