G Oracle BAM ICommand Operations and File Formats

This appendix describes in detail each operation and parameter available in the ICommand command-line utility and web service.

This appendix includes the following sections:

Section G.1, "Summary of Individual Operations"
Section G.2, "Detailed Operation Descriptions"
Section G.3, "Format of Command File"
Section G.4, "Format of Log File"
Section G.5, "Sample Export File"
Section G.6, "Regular Expressions"

For more information about ICommand see the following topics:

G.1 Summary of Individual Operations

This section summarizes the parameters that can be used with each ICommand operation. You can also see a summary of these operations in the command window by entering icommand (without any parameters) at the command prompt.

Table G-1 summarizes the commands available in ICommand.

Table G-1 ICommand Command Summary

Command	Parameters
`clear`	`-name` `itemname` [`-type [dataobject\|folder\|distributionlist]`] For more information about `clear` see Section G.2.1, "Clear."
`delete`	[`-name` `itemname`] [`-type [dataobject\|folder\|report\|rule\|securityfilters\|` `distributionlist\|ems\|eds\|all]`] [`-match` `pattern`] [`-regex` `regularexpression`] [`-all [0\|1]`] [`-systemobjects [0\|1]`] For more information about `delete` see Section G.2.2, "Delete."
`export`	`-file` `file_name` [`-name` `itemname`] [`-type [dataobject\|folder\|report\|rule\|securityfilters\|` `distributionlist\|ems\|eds\|all]`] [`-match` `pattern`] [`-regex` `regularexpression`] [`-all [0\|1]`] [`-systemobjects [0\|1]`] [`-dependencies [0\|1]`] [`-layout [0\|1]`] [`-contents [0\|1]`] [`-permissions [0\|1]`] [`-owner [0\|1]`] [`-header [0\|1]`] [`-footer [0\|1]`] [`-append [0\|1]`] [`-preview [0\|1]`] For more information about `export` see Section G.2.3, "Export."
`import`	`-file` `file_name` `-continueonerror` [`-delay` `milliseconds`] [`-updatelayout`] [`-mode [preserveid\|update\|overwrite\|append\|rename\|error]`] [`-preserveowner`] [`-setcol` `col_name`/[`null`\|`now`\|`value`:`override_value`]] `[-preview]` For more information about `import` see Section G.2.4, "Import."
`rename`	`-name` `itemname` `-newname` `newitemname` [`-type [dataobject\|folder\|report\|rule\|`distributionlist\|ems\| `eds]`] For more information about `rename` see Section G.2.5, "Rename."

G.2 Detailed Operation Descriptions

This section details each of the ICommand commands, their parameters, and gives examples. It includes the following topics:

Section G.2.1, "Clear"
Section G.2.2, "Delete"
Section G.2.3, "Export"
Section G.2.4, "Import"
Section G.2.5, "Rename"

G.2.1 Clear

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.

Table G-2 Clear Command Parameters

Parameter Description

Parameter	Description
`-name` `itemname`	The name of the item to be cleared. Required.
`-type` `itemtype`	The type of the item to be cleared. The following are valid: `dataobject` (see Example G-1) `folder` `distributionlist` `dataobject` is assumed if this parameter is omitted.

-name itemname

The name of the item to be cleared. Required.

-type itemtype

The type of the item to be cleared. The following are valid:

dataobject (see Example G-1)
folder
distributionlist

dataobject is assumed if this parameter is omitted.

Example G-1 Clearing a Data Object

icommand -cmd clear -name "/Samples/Call Center" -type dataobject

G.2.2 Delete

Deletes an item from the Active Data Cache.

Table G-3 Delete Command Parameters

Parameter	Description
`-all [0\|1]`	Controls whether all items of the specified type are deleted (see Example G-5). A nonzero or omitted value means delete all items of the specified type, a zero (0) value means only delete the named (or matched) items. Zero is assumed if this parameter is omitted.
`-match` `pattern`	A DOS-style pattern matching string, using the asterisk (*) and question mark (?) characters. The items whose names match the pattern are deleted.
`-name` `itemname`	The name of the item to be deleted.
`-regex` `regularexpr`	A regular expression pattern matching string. The items whose names match the pattern are deleted. See Section G.6, "Regular Expressions" for more information.
`-systemobjects [0\|1]`	Controls whether data objects in the `System` folder are included when the `all`, `match`, or `regex` parameters are used. Zero (0) means these data objects are not included. Zero is assumed if this parameter is omitted.
`-type` `itemtype`	The type of the item to be deleted. The following are valid: `dataobject` (see Example G-2) `folder` `report` (see Example G-5) `rule` `securityfilters` (For the specified Data Objects) `distributionlist` `ems` (Enterprise Message Source) `eds` (External Data Source) `all` (see Example G-6) `dataobject` is assumed if this parameter is omitted.

Example G-2 Deleting a Data Object

This command deletes a data object named TestDO. Note that dataobject type is assumed if the type parameter is not specified.

icommand -cmd delete -name TestDO

Example G-3 Deleting an Alert Rule

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

icommand -cmd delete -type rule -name "MyAlert"

Example G-4 Deleting security filter defined on a data object

To delete security filters defined on a data object, the name of the data object must be specified, instead of name of the security filter. This command deletes all security filters defined on the data object MyDataObject.

icommand -cmd delete -type securityfilters -name "MyDataObject"

Example G-5 Deleting All Reports

This command deletes all objects of type report.

icommand -cmd delete -type report -all 1

Example G-6 Deleting All Objects

This command deletes all items except systemobjects (data objects in the System folder).

icommand -cmd delete -type all

G.2.3 Export

Exports information about one or more objects in the Active Data Cache to an XML file. See Section G.5, "Sample Export File" for an example of an exported data object.

Table G-4 Export Command Parameters

Parameter	Description
`-all [0\|1]`	Controls whether all items of the specified type are exported. A nonzero or omitted value means export all items of the specified type, a zero value means only export the named (or matched) items. Zero (0) is assumed if this parameter is omitted. For Reports, Folders, and Rules, only the items owned by the user running ICommand are exported, unless the user running ICommand is an administrator. When an administrator runs ICommand, any user's items may be exported. See Example G-14, "Exporting All of the Reports in the System"
`-append [0\|1]`	Controls whether the exported information is appended to any existing file. A nonzero value means append. Zero (0) means overwrite the contents of any existing files. Zero is assumed if this parameter is omitted, or if the value is omitted. The Append parameter must be used with the Header and Footer parameters as described in Example G-23, "Using Append Parameter in Export". When the Append parameter is used, the Header and Footer parameters must be defined. If they are not, ICommand includes XML header information and closing XML </OracleBAMExport> tags after each append to the export file. The file is unusable for importing into Oracle BAM, because the import stops when it finds the first </OracleBAMExport> closing tag and ignores the rest of the objects.
`-contents [0\|1]`	Controls whether content information (row, column values) is to be exported. Applies only to Data Objects. Cannot be used with the `-type all` parameter as `contents` parameter is not available for other artifacts. A nonzero value means export content information. Zero (0) means do not export content information. A nonzero value is assumed if this parameter is omitted, or if the value is omitted. In addition, can only be used when: all the data objects are exported using the parameter `-all 1` a set of data objects is exported using the `regex` or `match` parameter a single data object is exported
`-dependencies [0\|1]`	Applies to reports and to Data Objects. Reports: Controls whether reports that the specified report depends on are exported. Icommand will automatically determine whether the specified report is dependent on other reports and will export them, as well. The dependent report or reports will be exported first, followed by the report you specify in the command. When you import the report file, all the dependent reports will be imported first, followed by the report you chose to export. See Example G-22, "Exporting Reports With Associated Dependent Reports" for a sample using this parameter. Data Objects: Controls whether other Data Objects that the exported Data Objects depend on in the lookup columns are exported. A nonzero value or the parameter present with no value specifies that report or Data Object dependencies are exported. Zero is assumed if this parameter is omitted.
`-file` `file_name`	The name of the file to export to. Required. If the file does not exist, it is created. If the file does exist, any contents are overwritten, unless the `append` parameter is used. Because the file contains XML, it usually has an XML extension.
`-footer [0\|1]`	Controls whether closing XML information is written to the end of the export file. This can allow successive executions of ICommand to assemble one XML file by repeatedly appending to the same file. A nonzero value means write the closing information. Zero (0) means do not write the closing information. nonzero is assumed if this parameter is omitted, or if the value is omitted. When used with the Append parameter, you must set the Footer value appropriately, or the file cannot be used with ICommand Import. If Footer is not defined, each append includes closing </OracleBAMExport> tags and the import stops when the first closing tag is read and does not import the remaining objects defined in the file. See Example G-23, "Using Append Parameter in Export" for a sample using this parameter.
`-header [0\|1]`	Controls whether XML header information is written to the front of the export file. This can allow successive executions of ICommand to assemble one XML file by repeatedly appending to the same file. A nonzero value means write the header. Zero(0) means do not write the header. nonzero is assumed if this parameter is omitted, or if the value is omitted. See Example G-23, "Using Append Parameter in Export" for a sample using this parameter.
`-layout [0\|1]`	Applies only to Data Objects. Controls whether layout information is to be exported. A nonzero value means export layout information. Zero (0) means do not export layout information. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`-match` `pattern`	A DOS-style pattern matching string, using the asterisk (*) and question mark (?) characters. The items whose names match the pattern are exported (see Example G-21, "Exporting a Data Object Using the Match Parameter").
`-name` `itemname`	The name of the item to be exported.
`-owner [0\|1]`	Applies only to Folders, Reports, and Rules. Controls whether the information about the owner of the items being exported is included in the export. A nonzero value means export the owner information. Zero (0) means do not export the owner information. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`-permissions [0\|1]`	Applies only to Data Objects and Folders. Controls whether permissions information is to be exported. A nonzero value means export information about the permission settings of the exported Data Objects or Folders. Zero (0) means do not export permission information. Zero is assumed if this parameter is omitted, or if the value is omitted. For Data Objects, only the permissions of the Data Object itself are exported. Any permissions that might be on the folders or subfolders that the Data Objects are contained within are not included. For Folders, the permissions reflect the cumulative permissions of all parent Folders of the Folders being exported.
`-preview [0\|1]`	In `preview` mode, ICommand goes through the motions of exporting all of the specified items, but does not actually output any information. This can see what would be exported for a given command line, and what errors might occur. In this mode, ICommand export continues processing even after some errors that would cause non-preview mode to stop the export. A nonzero value means preview mode. nonzero is assumed if the value is omitted. Zero (0) is assumed if the parameter is omitted.
`-regex` `regularexpr`	A regular expression pattern matching string. The items whose names match the pattern are exported. See Section G.6, "Regular Expressions" for more information.
`-systemobjects [0\|1]`	Controls whether Data Objects in the System folder are included when the `all`, `match`, or `regex` parameters are used. Zero (0) means these data objects are not included. Zero is assumed if this parameter is omitted.
`-type` `itemtype`	The type of the item to be exported. The following are valid: `dataobject` (see Example G-7 and Example G-8) `folder` (see Example G-9, Example G-10, and Example G-11) `report` (see Example G-12, Example G-13, and Example G-14) `rule` (see Example G-15) `securityfilters` (For the specified Data Objects) (see Example G-16) `distributionlist` (see Example G-17) `ems` (Enterprise Message Source) (see Example G-18) `eds` (External Data Source) (see Example G-19) `all` (see Example G-20) `dataobject` is assumed if this parameter is omitted.

Example G-7 Exporting a Data Object in a Folder

icommand -cmd export -name "/Samples/Call Center" -file "C:\CallCenter.xml"

Note that the type parameter was not included in this example. By default dataobject is assigned to type if it is not specified.

Example G-8 Exporting a Data Object at the Root

icommand -cmd export -name TestDataObject -file "C:\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.

Example G-9 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:\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:\FolderExportTest.xml

Example G-10 Exporting a Folder from Shared Reports

icommand -cmd export -name "/public/Report/MainFolderInShared" -type folder -file
 C:\FolderExportTest2.xml

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

Example G-11 Exporting a Folder from Data Objects

icommand -cmd export -name "/public/DataObject/Test Sub folder" -type folder -file
 C:\foldertest1.xml

Example G-12 Exporting a Private Report

As in Example G-9, there are two methods of exporting private reports.

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

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

Example G-13 Exporting a Shared Report

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

Example G-14 Exporting All of the Reports in the System

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

Example G-15 Exporting an Alert Rule

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

Example G-16 Exporting a Security Filter

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

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

Example G-17 Exporting a Distribution List

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

Example G-18 Exporting an Enterprise Message Source

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

Example G-19 Exporting an External Data Source

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

Example G-20 Exporting All Oracle BAM Objects in the System

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

Example G-21 Exporting a Data Object Using the Match Parameter

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

Example G-22 Exporting Reports With Associated Dependent Reports

icommand -cmd export -type report -name Report1 -dependencies 1 -file Report1.xml

The dependent reports are automatically determined and exported first. They are imported again when you import the specified report.

Example G-23 Using Append Parameter in Export

In the first case (the incorrect example), Append is used without setting the Header and Footer parameters (by default Header and Footer are set to 1).

icommand -cmd export -type dataobject -name "/Samples/Call Center" -file do.xml
icommand -cmd export -type dataobject -name "/Samples/Employees" -file do.xml -append
icommand -cmd export -type dataobject -name "/Samples/Film Sales" -file do.xml  -append

The output from these commands is as follows. Notice that an XML header and closing tags are included with each append to the file. If this file is used for importing data into Oracle BAM, only the first object is imported. As soon as the first </OracleBAMExport> is read at line 4, the import stops.

<?xml version="1.0"?>
<OracleBAMExport Version="2020">
  <exported object/>
</OracleBAMExport>
<?xml version="1.0"?>
<OracleBAMExport Version="2020">
  <exported object/>
</OracleBAMExport>
<?xml version="1.0"?>
<OracleBAMExport Version="2020">
  <exported object/>
</OracleBAMExport>

In the second case (the correct example), The Header and Footer parameters are specified to produce the necessary output.

icommand -cmd export -type dataobject -name "/Samples/Call Center" -file do2.xml
 -header 1 -footer 0
 //only the footer is supressed in the first command
icommand -cmd export -type dataobject -name "/Samples/Employees" -file do2.xml
 -append 1 -header 0 -footer 0
 //both the header and the footer are suppressed in the intermediate commands
icommand -cmd export -type dataobject -name "/Samples/Film Sales" -file do2.xml
 -append 1 -header 0 -footer 1
 //only the header is suppressed in the last commands

The output file produced by these commands can import the objects into Oracle BAM Server.

<?xml version="1.0"?>
<OracleBAMExport Version="2020">
  <exported object>
  <exported object>
</OracleBAMExport>

G.2.4 Import

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.

If the user running ICommand is not an administrator, Reports are always imported to the private folders of the user running ICommand. If the path information in the import file exactly matches existing private folders of the user running ICommand, the imported report is placed in that location. Otherwise, it is placed into the root of that user's private folders.

If the user running ICommand is an administrator, then the preserveowner option may be used to allow Folders, Reports and Rules to be imported with their original ownership and to their original location.

Table G-5 Import Command Parameters

Parameter	Description
`-continueonerror [0\|1]`	While importing objects from a file, by default, ICommand stops whenever an error is encountered. If you are importing several objects and do not want to stop when an error is found in one, use the continueonerror parameter to continue importing the rest of the objects specified in the command. Specify a one (1) to ignore errors and continue importing other objects (see Example G-24).
`-delay` `millisec`	Applies only to Data Objects. A value that specifies a delay that is to occur between each row insertion or update. This can simulate active data at a specified rate. The number is the number of milliseconds to wait between each row. It must be greater than zero. If this parameter is omitted, there is no delay. See Example G-24, "Importing a Data Object With Delay"
`-file` `file_name`	The name of the file to import from. Required. This would usually be a file that was created through the export command.
`-preserveowner`	Applies only to Folders, Reports, and Rules. Controls whether, when the item is imported, the ownership of the item is set as specified in the import file. This setting of ownership can only be done if the ownership was included in the file during export, and if the user running ICommand is an administrator. A nonzero value means set the ownership as specified in the import file. Zero (0) means the imported items remain owned by the user running ICommand. Zero is assumed if this parameter is omitted, or if the value is omitted.
`-preview [0\|1]`	In `preview` mode, ICommand goes through the motions of importing all of the specified items, but does not actually input any information. This can see what would be imported for a given command line, and what errors might occur. In this mode, ICommand import continues processing even after some errors that would cause non-preview mode to stop the import. A nonzero value means preview mode. nonzero is assumed if the value is omitted. Zero (0) is assumed if the parameter is omitted. This parameter is supported for the following objects: Rule, Distribution list, EDS, EMS, Report, Folder, and Security Filters. See Example G-25, "Importing a Report in Preview mode"
`-mode` `mode`	By default, if the mode parameter is not specified, the value Error is assumed for objects of type Folder, Report, EDS, EMS, and Distribution List. The following mode values are valid for Folders, Reports, EMS, and EDS objects: `overwrite` If the item exists, replaces it with the imported item. `rename` If the item exists, changes the name of the imported item. The new name is computed automatically and reported in a message. `error` If the item exists, terminates the import with an error. The following values are valid for Distribution List objects: `overwrite` If the item exists, replaces it with the imported item. `rename` If the item exists, changes the name of the imported item. The new name is computed automatically and reported in a message. `append` If the item exists, appends the users in the imported list to the existing list. `error` If the item exists, terminates the import with an error. The following value is supported for Data Objects or Reports: `preserveid` This option is important because some other items, such as Reports, point to the Data Objects they use by ID, not by name. Data Object Usage: If the imported Data Object does not exist and must be created, ICommand attempts to assign the Data Object the same internal ID that the exported Data Object had. If it cannot, the import is terminated with an error. Report Usage: If the imported Report does not exist and must be created, ICommand attempts to assign the Report the same internal ID that the exported Report had. If it cannot, the import is terminated with an error.
`-mode` `mode` (cont.)	Only the following value is valid for Data Objects: `update` Typically, when ICommand imports a Data Object, it creates a new Data Object or locates the existing Data Object and inserts the imported rows into that Data Object. In `update` mode, ICommand instead attempts to locate existing matching rows by Row ID, and updates those existing rows with the values in the import file. Unmatched rows are inserted. For matching Row IDs in the import file that have no data columns specified, the rows are deleted from the existing Data Object. For Security Filters, the only value supported is `overwrite`. If `overwrite` is not specified and the Data Object contains at least one Security Filter, the import is terminated with an error. This parameter is not supported for Rules.
`-setcol`	Allows override of column values from the command line during import, including setting to current date/time. `-setcol` `column_name`/`NULL` `-setcol` `column_name`/`NOW` `-setcol` `column_name`/`VALUE`:`override-value` `column_name` is the name of a column in the Data Object being imported. This cannot be a column of type lookup or calculated. Column names that are not contained in the input XML being imported can be specified, if they are columns in the Data Object being imported into.The portion after the slash specifies a value that should be substituted for that column on each row that is imported -- any value for that column in the import file is ignored (overridden). Note that slash is the one character that is not permitted in column names, so there is no potential conflict with any column names in this syntax. `NULL` specifies that the column value should be set to null. The column must be defined as "nullable" in the Data Object's layout. `NOW` specifies that the column value should be set to the current date/time when the column value is being set into the row. This option can only be used for columns of type datetime, timestamp, and string. `VALUE`:`override-value` specifies an arbitrary constant value (after the colon) that the column should be set to. The value must be a legal value for the type of the column.To allow multiple columns to be overridden, any number of `setcol` parameters may be present. However, because duplicate parameters are not permitted, ICommand recognizes any parameter name that starts with `setcol` as a `setcol` parameter (for example, `setcol1`, `setcol`2, and so on).Sample command line: `icommand -cmd import -file myfile.xml -setcol1 Field1/null -setcol2 Field3/now -setcol3 "Customer Name/value:John Q. Public"`
`-updatelayout`	Applies only to Data Objects. Controls whether, if the Data Object being imported exists, the layout (schema) of the Data Object is updated according to the layout information in the import file. True if parameter is present; false if parameter is not present.

Example G-24 Importing a Data Object With Delay

icommand -cmd import -file C:\TestDO.xml -delay 1000 -continueonerror 1

Example G-25 Importing a Report in Preview mode

icommand -cmd import -file C:\TestReport.xml -preview 1

G.2.5 Rename

Renames an item in the Active Data Cache.

Table G-6 Rename Command Parameters

Parameter Description

Parameter	Description
`-name` `itemname`	The name of the item to be renamed. Required. The full folder path must be given when renaming objects of type Folder (see Example G-27, "Renaming Folders").
`-newname` `newitemname`	The new name for the item. Required. The full folder path must be given when renaming objects of type Folder (see Example G-27, "Renaming Folders"). For Data Objects and Reports, only the new base name should be given, with no path (for example -newname "MyReport").
`-type` `itemtype`	The type of object to be renamed. The following are valid: `dataobject` (see Example G-26) `folder` (see Example G-27) `report` (see Example G-28) `rule` `distributionlist` (see Example G-29) `ems` (Enterprise Message Source) `eds` (External Data Source) `dataobject` is assumed if this parameter is omitted. `all` is not supported as an item type in the `rename` command.

-name itemname

The name of the item to be renamed. Required.

The full folder path must be given when renaming objects of type Folder (see Example G-27, "Renaming Folders").

-newname newitemname

The new name for the item. Required.

The full folder path must be given when renaming objects of type Folder (see Example G-27, "Renaming Folders").

For Data Objects and Reports, only the new base name should be given, with no path (for example -newname "MyReport").

-type itemtype

The type of object to be renamed. The following are valid:

dataobject (see Example G-26)
folder (see Example G-27)
report (see Example G-28)
rule
distributionlist (see Example G-29)
ems (Enterprise Message Source)
eds (External Data Source)

dataobject is assumed if this parameter is omitted. all is not supported as an item type in the rename command.

Example G-26 Renaming a Data Object in a Folder

icommand -cmd rename -type dataobject -name "/TestDataObjectFolder/TestDataObject"
 -newname NewTestDataObject

Example G-27 Renaming Folders

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"

Example G-28 Renaming a Report in a Private Folder

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

Example G-29 Renaming a Distribution List

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

Example G-30 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"

G.3 Format of Command File

This section contains the following topics:

Section G.3.1, "Inline Content"
Section G.3.2, "Command IDs"
Section G.3.3, "Continue On Error"

The command file contains the root tag OracleBAMCommands.

Within the root tag is a tag for every command to be executed. The tag name is the command name, and the parameters for the command are attributes.

Sample command file:

<?xml version="1.0" encoding="utf-8"?>
<OracleBAMCommands continueonerror="1">
  <Export name="Samples/Media Sales" file="MediaSales.xml" contents="0" />
  <Rename name="Samples/Call Center" newname="Call Centre" />
  <Delete type="EMS" name="WebLog" />
  <Delete type="EMS" name="WebLog2" />
</OracleBAMCommands>

The output of this sample command file is shown in Section G.4, "Format of Log File."

G.3.1 Inline Content

When using a command file to import, the inline option enables you to include the import content inside the command file, rather than in a separate import file. Here is an example:

<?xml version="1.0"?>
<OracleBAMCommands>
<Import inline="1">
<OracleBAMExport Version="2013">
  <DataObject Version="14" Name="Employees_Inline" ID="_Employees_Inline"
    Path="/Samples" External="0">
    <Layout>
      <Column Name="Salesperson" ID="_Salesperson" Type="string" MaxSize="100"
        Nullable="1" Public="1"/>
      <Column Name="Sales Area" ID="_Sales_Area" Type="string" MaxSize="100"
        Nullable="1" Public="1"/>
      <Column Name="Sales Number" ID="_Sales_Number" Type="integer"
        Nullable="1" Public="1"/>
      <Column Name="Timestamp" ID="_Timestamp" Type="timestamp" Nullable="0"
        Public="1"/>
      <Indexes/>
    </Layout>
    <Contents>
      <Row ID="1">
        <Column ID="_Salesperson" Value="Greg Masters"/>
        <Column ID="_Sales_Area" Value="Northeast"/>
        <Column ID="_Sales_Number" Value="567"/>
        <Column ID="_Timestamp" Value="2004-09-14T14:07:41.0000560PDT"/>
      </Row>
      <Row ID="2">
        <Column ID="_Salesperson" Value="Lynette Jones"/>
        <Column ID="_Sales_Area" Value="Southwest"/>
        <Column ID="_Sales_Number" Value="228"/>
        <Column ID="_Timestamp" Value="2004-09-14T14:07:41.0000560PDT"/>
      </Row>
      <Row ID="3">
        <Column ID="_Salesperson" Value="Noel Rogers"/>
        <Column ID="_Sales_Area" Value="Northwest"/>
        <Column ID="_Sales_Number" Value="459"/>
        <Column ID="_Timestamp" Value="2004-09-14T14:07:41.0000560PDT"/>
      </Row>
    </Contents>
  </DataObject>
</OracleBAMExport>
</Import>
</OracleBAMCommands>

G.3.2 Command IDs

This feature is only used when output is being sent to a log file. To make the parsing of log results easier, each command can be given an ID. This ID is included in the Result or Error elements of any output related to that command.

Sample Input:

<OracleBAMCommands continueonerror="1">
  <Delete id="1" type="dataobject" name="Data Object A"/>
  <Delete id="2" type="dataobject" name="Data Object B"/>
</OracleBAMCommands>

Sample Output Log File:

<?xml version="1.0"?>
<ICommandLog Login="weblogic">
  <Results Command="Delete" ID="1">Data Object &quot;/Data Object A&quot;
 deleted.</Results>
  <Error Command="Delete" ID="2">
    <![CDATA[BAM-02409: There is no Data Object named "Data Object B".
    [ErrorSource="ICommandEngine",ErrorID="ICommandEngine.DOExist"]]]>
  </Error>
</ICommandLog>

G.3.3 Continue On Error

Ordinarily, ICommand executes commands in a command file until a failure occurs, or until they all complete successfully. In other words, if a command file contains 20 commands, and the second command fails for any reason, then no further commands are executed. This behavior can be changed by using the continueonerror attribute at either a global level or for each command.

Example G-31 shows how to use the continueonerror attribute so that all commands are executed regardless of if any failures occur

Example G-31 Enabling Global ContinueOnError Mode

<OracleBAMCommands  continueonerror="1">
  <Delete id="1" type="dataobject" name="Data Object A"/>
  <Delete id="2" type="dataobject" name="Data Object B"/>
</OracleBAMCommands>

In Example G-32, continueonerror only applies to the command that deletes Data Object A. If this command fails, then ICommand outputs the error and continues. But if any other command fails, ICommand stops immediately.

Example G-32 Enabling Command-Level ContinueOnError Mode

<OracleBAMCommands>
  <Delete id="1" type="dataobject" name="Data Object A" continueonerror="1"/>
  <Delete id="2" type="dataobject" name="Data Object B"/>
  <Delete id="3" type="dataobject" name="Data Object C"/>
  <Delete id="4" type="dataobject" name="Data Object D"/>
</OracleBAMCommands>

G.4 Format of Log File

The log file contains the root tag ICommandLog.

Within the root tag is an entry for every error or informational message logged.

Errors are logged with the tag Error.

Informational messages are logged with the tag Results.

Both Results and Error tags optionally contain an attribute of the form Command=cmdname, if appropriate, that contains the name of the command that generated the error or informational message.

This sample log file is output of command file given in Section G.3, "Format of Command File":

<?xml version="1.0" encoding="utf-8"?>
<ICommandLog Login="user_name">
  <Results Command="Export">Data Object "/Samples/Media Sales" exported
 successfully (0 rows).</Results>
  <Results Command="Export">1 items exported successfully.</Results>
  <Results Command="Rename">Data Object "/Samples/Call Center" renamed to
 "/Samples/Call Centre".</Results>
  <Results Command="Delete">Enterprise Message Source "WebLog" deleted.</Results>
  <Error Command="Delete"><![CDATA[Error while processing command "Delete".
 [ErrorSource="ICommand", ErrorID="ICommand.Error"] There is no Enterprise Message
 Source named "WebLog2". [ErrorSource="ICommand",
 ErrorID="ICommand.EMSExist"]]]></Error>
</ICommandLog>

G.5 Sample Export File

The following example shows a sample file resulting from exporting a Data Object.

<?xml version="1.0"?>
<OracleBAMExport Version="2018">
  <DataObject Version="14" Name="Employees" ID="_Employees" Path="/Samples"
 External="0">
    <Layout>
      <Column Name="Salesperson" ID="_Salesperson" Type="string" MaxSize="100"
 Nullable="1" Public="1"/>
      <Column Name="Sales Area" ID="_Sales_Area" Type="string" MaxSize="100"
 Nullable="1" Public="1"/>
      <Column Name="Sales Number" ID="_Sales_Number" Type="integer" Nullable="1"
 Public="1"/>
      <Column Name="Timestamp" ID="_Timestamp" Type="timestamp" Nullable="0"
 Public="1"/>
      <Indexes/>
    </Layout>
    <Contents>
      <Row ID="1">
        <Column ID="_Salesperson" Value="Greg Masters"/>
        <Column ID="_Sales_Area" Value="Northeast"/>
        <Column ID="_Sales_Number" Value="567"/>
        <Column ID="_Timestamp" Value="2004-09-14T14:07:41.0000560PDT"/>
      </Row>
      <Row ID="2">
        <Column ID="_Salesperson" Value="Lynette Jones"/>
        <Column ID="_Sales_Area" Value="Southwest"/>
        <Column ID="_Sales_Number" Value="228"/>
        <Column ID="_Timestamp" Value="2004-09-14T14:07:41.0000560PDT"/>
      </Row>
      <Row ID="3">
        <Column ID="_Salesperson" Value="Noel Rogers"/>
        <Column ID="_Sales_Area" Value="Northwest"/>
        <Column ID="_Sales_Number" Value="459"/>
        <Column ID="_Timestamp" Value="2004-09-14T14:07:41.0000560PDT"/>
      </Row>
    </Contents>
  </DataObject>
</OracleBAMExport>

G.6 Regular Expressions

The export and delete commands optionally accept a regular expression with the regex parameter.

A regular expression is a pattern of text that consists of ordinary characters (for example, letters a through z) and special characters, known as metacharacters. The pattern describes one or more strings to match when searching for items by name.

Note:

The behavior of ICommand -regex is exactly like the java.util.regex package for matching character sequences against patterns specified by regular expressions.

Table G-7 contains the complete list of metacharacters and their behavior in the context of regular expressions.

Table G-7 Metacharacters for Regular Expressions

Character	Description
\	Marks the next character as a special character, a literal, a backreference, or an octal escape. For example, 'n' matches the character "n". '\n' matches a newline character. The sequence '\\' matches "\" and "\(" matches "(".
^	Matches the position at the beginning of the input string. If the RegExp object's `Multiline` property is set, ^ also matches the position following '\n' or '\r'.
$	Matches the position at the end of the input string. If the RegExp object's `Multiline` property is set, $ also matches the position preceding '\n' or '\r'.
*	Matches the preceding character or subexpression zero or more times. For example, zo* matches "z" and "zoo". * is equivalent to {0,}.
+	Matches the preceding character or subexpression one or more times. For example, 'zo+' matches "zo" and "zoo", but not "z". + is equivalent to {1,}.
?	Matches the preceding character or subexpression zero or one time. For example, "do(es)?" matches the "do" in "do" or "does". ? is equivalent to {0,1}
{n}	n is a nonnegative integer. Matches exactly n times. For example, 'o{2}' does not match the 'o' in "Bob," but matches the two o's in "food".
{n,}	n is a nonnegative integer. Matches at least n times. For example, 'o{2,}' does not match the "o" in "Bob" and matches all the o's in "foooood". 'o{1,}' is equivalent to 'o+'. 'o{0,}' is equivalent to 'o*'.
{n,m}	M and n are nonnegative integers, where n <= m. Matches at least n and at most m times. For example, "o{1,3}" matches the first three o's in "fooooood". 'o{0,1}' is equivalent to 'o?'. Note that you cannot put a space between the comma and the numbers.
?	When this character immediately follows any of the other quantifiers (*, +, ?, {n}, {n,}, {n,m}), the matching pattern is non-greedy. A non-greedy pattern matches as little of the searched string as possible, whereas the default greedy pattern matches as much of the searched string as possible. For example, in the string "oooo", 'o+?' matches a single "o", while 'o+' matches all 'o's.
.	Matches any single character except "\n". To match any character including the '\n', use a pattern such as '[\s\S]'.
(pattern)	A subexpression that matches pattern and captures the match. The captured match can be retrieved from the resulting Matches collection using the `$0...$9` properties. To match parentheses characters ( ), use '$' or '$'.
(?:pattern)	A subexpression that matches pattern but does not capture the match, that is, it is a non-capturing match that is not stored for possible later use. This is useful for combining parts of a pattern with the "or" character (\|). For example, 'industr(?:y\|ies) is a more economical expression than 'industry\|industries'.
(?=pattern)	A subexpression that performs a positive lookahead search, which matches the string at any point where a string matching pattern begins. This is a non-capturing match, that is, the match is not captured for possible later use. For example 'Windows (?=95\|98\|NT\|2000)' matches "Windows" in "Windows 2000" but not "Windows" in "Windows 3.1". Lookaheads do not consume characters, that is, after a match occurs, the search for the next match begins immediately following the last match, not after the characters that comprised the lookahead.
(?!pattern)	A subexpression that performs a negative lookahead search, which matches the search string at any point where a string not matching pattern begins. This is a non-capturing match, that is, the match is not captured for possible later use. For example 'Windows (?!95\|98\|NT\|2000)' matches "Windows" in "Windows 3.1" but does not match "Windows" in "Windows 2000". Lookaheads do not consume characters, that is, after a match occurs, the search for the next match begins immediately following the last match, not after the characters that comprised the lookahead.
x\|y	Matches either x or y. For example, 'z\|food' matches "z" or "food". '(z\|f)ood' matches "zood" or "food".
[xyz]	A character set. Matches any of the enclosed characters. For example, '[abc]' matches the 'a' in "plain".
[^xyz]	A negative character set. Matches any character not enclosed. For example, '[^abc]' matches the 'p' in "plain".
[a-z]	A range of characters. Matches any character in the specified range. For example, '[a-z]' matches any lowercase alphabetic character in the range 'a' through 'z'.
[^a-z]	A negative range characters. Matches any character not in the specified range. For example, '[^a-z]' matches any character not in the range 'a' through 'z'.
\b	Matches a word boundary, that is, the position between a word and a space. For example, 'er\b' matches the 'er' in "never" but not the 'er' in "verb".
\B	Matches a nonword boundary. 'er\B' matches the 'er' in "verb" but not the 'er' in "never".
\cx	Matches the control character indicated by x. For example, \cM matches a Control-M or carriage return character. The value of x must be in the range of A-Z or a-z. If not, c is assumed to be a literal 'c' character.
\d	Matches a digit character. Equivalent to [0-9].
\D	Matches a nondigit character. Equivalent to [^0-9].
\f	Matches a form-feed character. Equivalent to \x0c and \cL.
\n	Matches a newline character. Equivalent to \x0a and \cJ.
\r	Matches a carriage return character. Equivalent to \x0d and \cM.
\s	Matches any white space character including space, tab, form-feed, and so on. Equivalent to [ \f\n\r\t\v].
\S	Matches any non-white space character. Equivalent to [^ \f\n\r\t\v].
\t	Matches a tab character. Equivalent to \x09 and \cI.
\v	Matches a vertical tab character. Equivalent to \x0b and \cK.
\w	Matches any word character including underscore. Equivalent to '[A-Za-z0-9_]'.
\W	Matches any nonword character. Equivalent to '[^A-Za-z0-9_]'.
\xn	Matches n, where n is a hexadecimal escape value. Hexadecimal escape values must be exactly two digits long. For example, '\x41' matches "A". '\x041' is equivalent to '\x04' & "1". Allows ASCII codes to be used in regular expressions.
\num	Matches num, where num is a positive integer. A reference back to captured matches. For example, '(.)\1' matches two consecutive identical characters.
\n	Identifies either an octal escape value or a backreference. If \n is preceded by at least n captured subexpressions, n is a backreference. Otherwise, n is an octal escape value if n is an octal digit (0-7).
\nm	Identifies either an octal escape value or a backreference. If \nm is preceded by at least nm captured subexpressions, nm is a backreference. If \nm is preceded by at least n captures, n is a backreference followed by literal m. If neither of the preceding conditions exists, \nm matches octal escape value nm when n and m are octal digits (0-7).
\nml	Matches octal escape value nml when n is an octal digit (0-3) and m and l are octal digits (0-7).
\un	Matches n, where n is a Unicode character expressed as four hexadecimal digits. For example, \u00A9 matches the copyright symbol (©).