Using ICommand performing BAM Server Operations

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.

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.

Example C:\Oracle\Middleware\Oracle_SOA1\bam\bin\icommand

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

Commands 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/Sample_DO" -type dataobject

-file C:\sample_do.xml

It is required to use quotation marks around report names and file names that contain spaces and other special characters.

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

1. Open C:\Oracle\Middleware\Oracle_SOA1\bam\config\BAMICommandConfig.xml

To specify credentials.

2. Open BAMICommandConfig.xml file.

3. Add bellow two lines brefore </BAMICommand> line in file.To configure credentials.

<ICommand_Default_User_Name>weblogic</ICommand_Default_User_Name>

<ICommand_Default_Password>welcome</ICommand_Default_Password>

Syntax of commands

On the command line, commands are specified by the value of the cmd parameter. Options for the command are specified by additional parameters

icommand -username user_name -cmd command_name -name value -type value [-parameter value]

***if you configured -username in configuration file no need to mention in ICommand.  

For example usage of export Command

icommand -cmd export -name "/Samples/Sample_DO" -type dataobject  -file C:\temp\sample_do.xml

Here icommand syntax is

-cmd :  export(command for export BAM server to outside)

-name: “/Sample/Sample_DO” (here exporting Sample_DO data object from bam server so, provide path for data object)

-type: dataobject (Provide type of exported name here Sample_DO is data object)

-file: C:\temp\sample_do.xml (destination file and path of destination)

1. To run this command Open ICommand.bat  on command prompt from C:\Oracle\Middleware\Oracle_SOA1\bam\bin

2. Run Export command

icommand -cmd export -name "/Samples/Sample_DO" -type dataobject  -file C:\temp\sample_do.xml

3. After successful exportation you will able to see Items Exported like shown in bellow.   

4. After exportation you will able to see exported file in your destination folder

C:\temp\sample_do.xml

Rules for specifying objects

General rules

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

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

1. If the Data Object is not at the root, the full path name must be given.

Example: /Samples/Sample_DO

2. If the Data Object is at the root, the leading slash (/) is optional.

Example: /CreditCardInfo  or CreditCardInfo

Data Object Folders

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

Example : /public/DataObject/Samples/Monitor Express

Reports and Report Folders

Reports:

The full path name plus the appropriate prefix must be specified.

1. For shared reports the /public/Report/ prefix must be included

Example: "/public/Report/Report1”

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

Example: "/private:joe/Report/Report1"

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

Example: "Report/Report1"

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

Report Folders:

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

/public/Report/Subfolder1

/private:joe/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 Alert_po:

Alert_po

/private:user_name/Rule/Alert_po

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

All other object types

Specify the full name of the object.

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 C:\Oracle\Middleware\Oracle_SOA1\bam\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).

ICommand commands and usages

I command mainly perform the fallowing Operations.

1. Clear
2. Delete
3. Export
4. Import
5. Rename

Clear operation:

Clears the contents of an item in the Active Data Cache.

What it means to be cleared depends upon the item type:

• For Data Objects, all existing rows within the Data Object are deleted.
• For Folders, all contents of the Folder are deleted.
• For Distribution Lists, all members (users and groups) are removed from the distribution list.

Clearing Data Object

1. Open BAM Architect, select Data Object  from  function list, navigates Data Objects->Samples  
2. Select BAM_BPEL_DO Data Object. And click on contents, you will able to see data from Data Object. Observer that four(4) rows content

3. Open ICommand.bat  on command prompt from C:\Oracle\Middleware\Oracle_SOA1\bam\bin

4. Run fallowing command  to clear content of  BAM_BPEL_DO Data Object

icommand -cmd clear -name "/Samples/BAM_BPEL_DO" -type dataobject

5. Once run, your able to see the Data Object “/Samples/BAM_BPEL_DO” cleared message, as shown in fallowing diagram

6. Open BAM Architect, select Data Object  from  function list, navigates Data Objects->Samples  
7. Select BAM_BPEL_DO Data Object. And click on contents, you will able to see data from Data Object. Observer no row is displaying.

Note: same way you can clear for Folders and for Distribution Lists also.

Delete operation :

Deletes an item from the Active Data Cache.

Deleting a Data Object

1. Open BAM Architect, select Data Object  from  function list, navigates Data Objects->Samples  
2. In Samples of Data Objects observer  Sample_DO Data Object

3. Usning ICommand, to delete Sample_DO run fallowing command.

icommand -cmd delete -name "/Samples/Sample_DO"

4. After running Icommand  in console your able to see DataObject “/Samples/Sample_DO” deleted.

5. Now Open BAM Architect, select Data Object  from  function list, navigates Data Objects->Samples  

6. In Samples of Data Objects observer  Sample_DO Data Object  is deleted or not.

Note:   same way you can delete Alert Rule, security filter defined on a data object,and All Objects using ICommand.

Alter Rule:  icommand -cmd delete -type rule -name "AlertPO"

Security Filter: icommand -cmd delete -type securityfilters -name "MyDataObject"

All Reports: icommand -cmd delete -type report -all 1

All Data Objects: icommand -cmd delete -type all

Export Operation:

Exports information about one or more objects in the Active Data Cache to an XML file.

Exporting a Data Object in a Folder

icommand -cmd export -name "/Samples/Sample_DO" -type dataobject  -file C:\temp\sample_do.xml

1. To run this command Open ICommand.bat  on command prompt from C:\Oracle\Middleware\Oracle_SOA1\bam\bin

2. Run Export command

icommand -cmd export -name "/Samples/Sample_DO" -type dataobject  -file C:\temp\sample_do.xml

3. After successful exportation you will able to see Items Exported like shown in bellow.   

4. After exportation you will able to see exported file in your destination folder

C:\temp\sample_do.xml

Note: you can export not only Data Objects!! You can Export Alerts, Reports, Distribution Lists, EDS, EMS and etc.  Some of examples are describes below.

Exporting a Data Object at the Root

icommand -cmd export -name TestDataObject -file "C:\temp\TestDataObject.xml"

Note that the data object name was not preceded by the slash (/). When a Data Object is in the root Data Objects folder, a slash is not required.

Exporting a Folder from My Reports

In the first case, the private:owner/Report prefix is used in the name parameter because the user exporting the folder is not the folder owner.

icommand -cmd export -  name"/private:bamadmin/Report/TestMainFolder/TestSubFolder"

-type folder -file C:\temp\FolderExportTest.xml

In the second case, the private:owner/Report prefix was not used in the name parameter because the user exporting the folder is the folder owner.

icommand -cmd export -name "/TestMainFolder/TestSubFolder" -type folder -file

C:\temp\FolderExportTest.xml

Exporting a Folder from Shared Reports

icommand -cmd export -name "/public/Report/MainFolderInShared" -type folder -file

C:\temp\FolderExportTest2.xml

Note that the public prefix is added to the name parameter.

Exporting a Folder from Data Objects

icommand -cmd export -name "/public/DataObject/Test Sub folder" -type folder -file

C:\temp\foldertest1.xml

Exporting a Private Report

There are two methods of exporting private reports.\

icommand -cmd export -name "/private:bamadmin/Report/MyReport" -type report -file C:\temp\MyReport.xml

icommand -cmd export -name MyReport -type report -file C:\temp\MyReport.xml

Exporting a Shared Report

icommand -cmd export -name "/public/Report/SharedReport" -type report -file C:\temp\SharedReport.xml

Exporting All of the Reports in the System

icommand -cmd export -type report -all -file C:\temp\TestAll.xml

Exporting an Alert Rule

icommand -cmd export -name Alert1 -type rule -file C:\temp\Alert1.xml

Exporting a Security Filter

icommand -cmd export -type securityfilters -name "TestDO" -file "C:\temp\TestFilter.xml"

Note that in the name parameter the name of the Data Object is specified rather than the name of the security filter.

Exporting a Distribution List

icommand -cmd export -name MyDistList -type distributionlist -file C:\temp\MyDistList.xml

Exporting an Enterprise Message Source

icommand -cmd export -type ems -name TestEMS -file C:\temp\TestEMS.xml

Exporting an External Data Source

icommand -cmd export -type eds -name TestEDS -file C:\temp\TestEDS.xml

Exporting All Oracle BAM Objects in the System

icommand -cmd export -type all -file C:\temp\TestAll.xml

Exporting a Data Object Using the Match Parameter

icommand -cmd export -match "/M*" -file "c/exportDOstartingwithM.xml"

Import Operation:

Imports the information from an XML file to an object in the Active Data Cache. The object may be created, replaced, or updated.

If the object does not exist, it is created if possible. For Data Objects, the input file must contain layout information to create the Data Object, and if the file contains no content information, then an empty Data Object is created.

Importing a Data Object

Importing Data Object using ICommand. Here importing Sample_DO Data Objects which you exported and Deleted from BAM Server

1. find location of  imported file, here c:\temp\sample_do.xml

2. Run Import  command

icommand -cmd import -file C:\temp\sample_do.xml

3. After running above Import command, you able to see success message in ICommand prompt as shown in below.  

4. Now Open BAM Architect, select Data Object  from  function list, navigates Data Objects->Samples  

5. In Samples of Data Objects observer Sample_DO Data Object is imported or not.

Note: you can import not only Data Objects; you can import reports, Alerts, EDS, EMS, and so on.

Rename Operation:

Renames an item in the Active Data Cache.

Renaming a Data Object in a Folder

icommand -cmd rename -type dataobject -name "/Samples/Sample_DO"

-newname NewSample_DO

1. Here you’re going  to rename Sample_DO  Data Object to NewSample_DO.  
2. Now Open BAM Architect, select Data Object  from  function list, navigates Data Objects->Samples  
3. In Samples of Data Objects observer Sample_DO Data Object name.

6. Run Import  command

icommand -cmd rename -type dataobject -name "/Samples/Sample_DO" -newname NewSample_DO

7. After successfully run Rename ICommand you able to see the fallowing message in ICommand Prompt.

Data Object "/Samples/Sample_DO" renamed to "/Samples/NewSample_DO”

8. Now Open BAM Architect, select Data Object  from  function list, navigates Data Objects->Samples  

9. In Samples of Data Objects observer Sample_DO Data Object is renamed to NewSample_DO as shown below diagram.

Note: you can also rename Alerts, Folders, Reports, and Distribution List etc. here  some of below example syntax’s are:

Renaming a data object folder:

icommand -cmd rename -type folder -name "/public/DataObject/TestFolder"

-newname "/public/DataObject/NewTestFolder"

Renaming a private report folder:

icommand -cmd rename -type folder -name "/private:weblogic/Report/MySubFolder"

-newname "/private:weblogic/Report/NewMySubFolder"

Renaming a shared report folder

icommand -cmd rename -type folder -name "/public/Report/TestSubFolder"

-newname "/public/Report/NewTestSubFolder"

Renaming a Report in a Private Folder

icommand -cmd rename -type report -name "/TestReportFolder/TestReport" -newname

NewTestReport

Renaming a Distribution List

icommand -cmd rename -type distributionlist -name TestList -newname MyDistList

Renaming an Alert Rule

For any ICommand operation on alerts, the value of the type parameter is rule. This command renames a rule named MyAlert.

icommand -cmd rename -type rule -name "MyAlert" -newname "MyRenamedAlert"