Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.4.0)

Part Number E10224-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

58 Using ICommand

This chapter provides usage information for the ICommand command-line utility.

This chapter includes the following sections:

58.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.

For more information about using the ICommand web service, see Section 56.5, "Using the ICommand Web Service."

For information about individual commands and their parameters see Appendix G, "Oracle BAM ICommand Operations and File Formats."

58.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/.

58.3 Specifying the Command and Option Syntax

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.

58.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:

<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
    

58.3.2 How to Specify the Command

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."

58.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.

58.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.

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 ...

58.4 Using Command-line-only Parameters

The following parameters can appear only on the command line:

58.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.

<?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).