6 Using ICommand

This chapter provides usage and reference material for the ICommand command-line utility and web service. It contains the following topics:

Introducing ICommand
General Command and Option Syntax
Command-line-only Parameters
Summary of Individual Commands
Detailed Command Descriptions
Item Name Syntax
Format of Command File
Format of Log File
Sample DOS Command Lines
Sample export file
Regular Expressions
Using ICommand Web Service

6.1 Introducing 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 and the Enterprise Link Repository.

The commands may be in an input XML file, or a single command may be given on the command line.

Informational and error messages may be output to either the command window or to an XML file.

6.2 General Command and Option Syntax

All parameters given on the DOS command line are in the form name=value. The name portion is not case sensitive. If the value portion must contain spaces or other special characters, it may be enclosed in quotes. For some parameters, the value may be omitted.

On the DOS command line, commands are specified by the value of the cmd=commandname parameter. Options for the command are specified by parametername=value parameters.

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.

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

You can specify multiple Active Data Cache types in a single command and pass parameters to them. For example:

icommand.exe cmd=export type=all report,rule,folder:owner=1 folder,dataobject:permissions=1 systemobjects=1 file=filename.xml

In this example, the command will pass owner=1 to the report, rule, and folder Active Data Cache object types. The comma (,) separates the object types and the parameter is listed after a colon (:).

This accomplishes the same end as the following three commands:

icommand.exe cmd=export type=report owner=1 .....icommand.exe cmd=export type=rule owner=1 .....icommand.exe cmd=export type=folder owner=1 .....

6.3 Command-line-only Parameters

The following parameters can appear only on the command line:

Domain=domain

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

If this parameter is omitted, main is used, which means the server information will be obtained from the ADCServerName key in the ICommand.exe.config file.

If the reserved value ADCInProcServer is used, then ICommand will directly access the Active Data Cache database (which must be local on the same machine on which ICommand is running) rather than contacting the Active Data Cache server. This option should be used 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=filename

Optional parameter that specifies the name of the file to which results and errors are logged. If the file does not exist, it will be created. If the file does exist, any contents will be overwritten. Since 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 will be output to the console.
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 will be created.

If this parameter is not present, overwrite is assumed.

Note that 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 will be no top level root tag in the XML produced by successive appends (ICommand will append the same tag each time it is run). It is left up to the user to handle this.
Cmdfile=filename

Optional parameter that specifies the name of the file that contains commands to be processed. Since 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.
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.
Debug=flag

Optional parameter that indicates whether extra debugging information is to be output in the event of 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 will be output.

6.4 Summary of Individual Commands

Table 6-1 summarizes the commands.

Table 6-1 ICommand Command Summary

Command	Parameters
`export`	`file=filename` [`name=itemname`] [`type=dataobject\|securityfilters\|folder\|report\|rule\|` `user\|role\|distributionlist\|ems\|emstype\|eds\|edstype\|` plan\|all] [`match=pattern`] [`regex=regularexpression`] [`all[=0\|1]`] [`systemobjects[=0\|1]`] [`dependencies[=0\|1]`] [`layout[=0\|1]`] [`contents[=0\|1]`] [`permissions[=0\|1]`] [`privileges[=0\|1]`] [`members[=0\|1]`] [`owner[=0\|1]`] `[planmonitorservicename=servicename`] [`header[=0\|1]`] [`footer[=0\|1]`] [`append[=0\|1]`] [`preview[=0\|1]`]
`import`	`file=filename` [`delay=milliseconds`] [`updatelayout`] [`mode=preserveid\|update\|overwrite\|append\|rename\|error`] [`preserveowner`] [`setcol`=`col_name`/[`null`\|`now`\|`value`:`override_value`]]
`delete`	[`name=itemname`] [`type=dataobject\|securityfilters\|folder\|report\|rule\|` user\|`role`\|`distributionlist\|ems\|eds\|plan\|all`] [`match=pattern`] [`regex=regularexpression`] [`all[=0\|1]`] [`systemobjects[=0\|1]`]
`rename`	`name=itemname` `newname=newitemname` [`type=dataobject\|folder\|report\|rule\|user\|role\|` `distributionlist`\|`ems\|eds\|plan`]
`clear`	`name=itemname` [`type=dataobject\|folder\|role\|distributionlist`]
`run`	`name=planname` [`type=plan`]
`stop`	`requestid=planexecutionrequestid` [`type=plan`]
`Setmonitoring`	[`name=plan_name`] [`type=plan`] [`match=dos_pattern`] [`regex=regular_expression`] [`all[=0\|1]`] [`planmonitorservicename=service_name`] [`enabled[=0\|1]`] [`restartoncompletion=never\|always\|count`] [`restartonfailure=never\|always\|count`] [`restartfrequencymax=none\|count_in_minutes`] [`preferredservicename=service_name`\|`empty_string`]

6.5 Detailed Command Descriptions

Export

Exports information about one or more items to an XML file.

Table 6-2 Export Command

Parameter	Description
`file=filename`	The name of the file to export to. Required. If the file does not exist, it will be created. If the file does exist, any contents will be overwritten, unless the `append` parameter is used. Since the file will contain XML, it would usually have an XML extension.
`name=itemname`	The name of the item to be exported.
`type=itemtype`	The type of the item to be exported. Must be one of the following: `dataobject` `securityfilters` (For the specified Data Objects) `folder` `report` `rule` `user` `role` `distributionlist` `ems` (Enterprise Message Source) `emstype` `eds` (External Data Source) `edstype` `plan` `all` `dataobject` 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 will be exported.
`regex=regularexpr`	A regular expression pattern matching string. The items whose names match the pattern will be exported.
`all[=0\|1]`	Controls whether all items of the specified type will be 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 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.
`[systemobjects[=0\|1]]`	Controls whether Data Objects in the System folder are included when the `all`, `match`, or `regex` parameters are used. Zero means these data objects are not included. Zero is assumed if this parameter is omitted.
`dependencies[=0\|1]`	Applies to only to Data Objects. Controls whether other Data Objects that the exported Data Objects depend on in the lookup columns will also be exported. A nonzero value or the parameter present with no value specifies that if the Data Objects being exported contain lookup columns, then the Data Objects that are looked up will also be exported.
`layout[=0\|1]`	Applies only to Data Objects. Controls whether layout information is to be exported. A nonzero value means export layout information. Zero means do not export layout information. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`contents[=0\|1]`	Applies only to Data Objects. Controls whether content information (row, column values) is to be exported. A nonzero value means export content information. Zero means do not export content 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 means do not export permission information. nonzero 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.
`privileges[=0\|1]`	Applies only to Roles. Controls whether the privilege settings in the Roles being exported are exported. A nonzero value means export the privilege settings. Zero means do not export the privilege settings. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`members[=0\|1]`	Applies only to Roles. Controls whether the list of users in the Roles being exported are exported. A nonzero value means export the list of users. Zero means do not export the list of users. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`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 means do not export the owner information. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`header[=0\|1]`	Controls whether XML header information is written to the front of the export file. This can be used to 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 means do not write the header. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`footer[=0\|1]`	Controls whether closing XML information is written to the end of the export file. This can be used to 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 means do not write the closing information. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`append[=0\|1]`	Controls whether the exported information is appended to any existing file. A nonzero value means append. Zero means overwrite the contents of any existing files. nonzero 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 exporting all of the specified items, but does not actually output any information. This can be used to 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 is assumed if the parameter is omitted.
`planmonitorservicename=servicename`	Applies only to Rules and Plans. A value that specifies Plan Monitor service location. If not specified, retrieves the value from various keys in the ICommand.exe.config file. First it tries for a service name from the PlanMonitor.ServiceName key. If no service name is specified, it tries for a service URL from the PlanMonitor.ServiceURL key. If no service URL is specified, it tries for individual settings from the following set of keys: PlanMonitor.ServiceMachine, PlanMonitor.ServiceChannel, and PlanMonitor.ServicePort.

Import

Imports the information from an XML file to an item. The item may be created, replaced, or updated.

If the item does not exist, it will be created if possible. For Data Objects, the input file must contain layout information in order to create the Data Object, and if the file contains no content information, then an empty Data Object will be 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 6-3 Import Command

Parameter	Description
`file=filename`	The name of the file to import from. Required. This would usually be a file that was created through the export command.
`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 be used to 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 will be no delay.
`updatelayout`	Applies only to Data Objects. Controls whether, if the Data Object being imported already 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.
`mode=mode`	The following modes are valid for the following item types: The following values are valid for Folders, Reports, Users, Roles, EMS, EMSTypes, EDS. EDSTypes, and Plans: `overwrite` If the item already exists, replace it with the imported item. `rename` If the item already exists, change the name of the imported item. The new name is computed automatically and reported in a message. `error` If the item already exists, terminate the import with an error. The following values are valid for Distribution Lists: `overwrite` If the item already exists, replace it with the imported item. `rename` If the item already exists, change the name of the imported item. The new name is computed automatically and reported in a message. `append` If the item already exists, append the users in the imported list to the already existing list. `error` If the item already exists, terminate the import with an error. Only the following values are valid for Data Objects: `preserveid` If the imported Data Object does not already exist and must be created, ICommand will attempt to assign the Data Object the same internal ID that the exported Data Object had. If it is unable to, the import will be terminated with an error. This option is important because some other items, such as Reports, point to the Data Objects they use by ID, not by name. `Update` Normally, 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 already contains at least one Security Filter, the import will be aborted with an error. This parameter is not supported for Rules.
`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. nonzero is assumed if this parameter is omitted, or if the value is omitted.
`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 one of the columns 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, as long as 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 will be 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 at the time that 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.In order to allow more than one column to be overridden, any number of `setcol` parameters may be present. However, since duplicate parameters are not permitted, ICommand will recognize any parameter name that starts with `setcol` as a `setcol` parameter (for example, `setcol1`, `setcol`2, and so on).Example command line: `icommand cmd=import file=myfile.xml setcol1=Field1/null setcol2=Field3/now setcol3="Customer Name/value:John Q. Public"`
`planmonitorservicename`=`servicename`	Applies only to Rules and Plans. A value that specifies Plan Monitor service location. If not specified, retrieves the value from various keys in the ICommand.exe.config file. First it tries for a service name from the PlanMonitor.ServiceName key. If no service name is specified, it tries for a service URL from the PlanMonitor.ServiceURL key. If no service URL is specified, it tries for individual settings from the following set of keys: PlanMonitor.ServiceMachine, PlanMonitor.ServiceChannel, and PlanMonitor.ServicePort.

Delete

Deletes an item.

Table 6-4 Delete Command

Parameter	Description
`name=itemname`	The name of the item to be deleted.
`type=itemtype`	The type of the item to be deleted. Must be one of the following: `dataobject` `securityfilters` (For the specified Data Objects) `folder` `report` `rule` `user` `role` `distributionlist` `ems` (Enterprise Message Source) `emstype` `eds` (External Data Source) `edstype` `plan` `all` `dataobject` 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 will be deleted.
`regex=regularexpr`	A regular expression pattern matching string. The items whose names match the pattern will be deleted.
`all[=0\|1]`	Controls whether all items of the specified type will be deleted. A nonzero or omitted value means delete all items of the specified type, a zero value means only delete the named (or matched) items. Zero is assumed if this parameter is omitted.
`[systemobjects[=0\|1]]`	Controls whether Data Objects in the System folder are included when the `all`, `match`, or `regex` parameters are used. Zero means these data objects are not included. Zero is assumed if this parameter is omitted.
`planmonitorservicename`=`servicename`	Applies only to Rules and Plans. A value that specifies Plan Monitor service location. If not specified, retrieves the value from various keys in the ICommand.exe.config file. First it tries for a service name from the PlanMonitor.ServiceName key. If no service name is specified, it tries for a service URL from the PlanMonitor.ServiceURL key. If no service URL is specified, it tries for individual settings from the following set of keys: PlanMonitor.ServiceMachine, PlanMonitor.ServiceChannel, and PlanMonitor.ServicePort.

Rename

Renames an item.

Table 6-5 Rename Command

Parameter	Description
`name=itemname`	The name of the item to be renamed. Required.
`newname=newitemname`	The new name for the item. Required. For Data Objects, Reports and Folders, only the new base name should be given, with no path (for example Report1).
`type=itemtype`	The type of the item to be renamed. Must be one of the following: `dataobject` `folder` `report` `rule` `user` `role` `distributionlist` `ems` (Enterprise Message Source) `emstype` `eds` (External Data Source) `edstype` `plan` `dataobject` is assumed if this parameter is omitted.
`planmonitorservicename`=`servicename`	Applies only to Rules and Plans. A value that specifies Plan Monitor service location. If not specified, retrieves the value from various keys in the ICommand.exe.config file. First it tries for a service name from the PlanMonitor.ServiceName key. If no service name is specified, it tries for a service URL from the PlanMonitor.ServiceURL key. If no service URL is specified, it tries for individual settings from the following set of keys: PlanMonitor.ServiceMachine, PlanMonitor.ServiceChannel, and PlanMonitor.ServicePort.

Clear

Clears the contents of an item.

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 Roles and Distribution Lists, all members (users) are removed.

Table 6-6 Clear Command

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. Must be one of the following: `dataobject` `folder` `role` `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. Must be one of the following:

dataobject
folder
role
distributionlist

dataobject is assumed if this parameter is omitted.

Run

Causes an instance of an Enterprise Link Plan to begin running.

Note that even if one or more instances of the Plan are already running, this command will cause another instance to begin running.

Table 6-7 Run Command

Parameter	Description
`name=planname`	The name of the Plan to run. Required.
`type=plan`	Optional. If present, the value must be `plan`.
`planmonitorservicename`=`servicename`	Applies only to Rules and Plans. A value that specifies Plan Monitor service location. If not specified, retrieves the value from various keys in the ICommand.exe.config file. First it tries for a service name from the PlanMonitor.ServiceName key. If no service name is specified, it tries for a service URL from the PlanMonitor.ServiceURL key. If no service URL is specified, it tries for individual settings from the following set of keys: PlanMonitor.ServiceMachine, PlanMonitor.ServiceChannel, and PlanMonitor.ServicePort.

Stop

Causes a running instance of an Enterprise Link Plan to be stopped.

Table 6-8 Stop Command

Parameter	Description
`requestid=id`	The Request ID of the running instance of a Plan, as assigned by the Enterprise Link Data Flow Service when the Plan was started.
type=plan	Optional. If present, the value must be `plan`.

6.6 Item Name Syntax

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

General rules

When specified on a DOS command line, if the name contains spaces or characters that have special meaning to DOS, the name must be quoted according to the rules for DOS 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:

/My Folder/My Subfolder/My Data Object

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

/My Data Object
My Data Object

Reports

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

For shared reports:

"/public/Report/Subfolder1/My Report"

For private reports:

"/private:username/Report/Subfolder1/My Report"

For private reports the /private:username/ prefix may be omitted if the user running ICommand is the user that owns the report.

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

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:username/Rule/Alert1

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

All other item types

Specify the full name of the item.

6.7 Format of Command File

This section comtains the following topics:

Inline Content
Command IDs
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>

6.7.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" encoding="utf-8"?>
<OracleBAMCommands>
<Import inline="1">
<Export Version="504.0" Build="3.0.3697.0">
  <DataObject Version="13" Name="Employees" ID="_Employees" Path="/Samples"    External="0">
    <Layout>
      <Column Name="Salesperson" ID="_Salesperson" Type="string" MaxSize="100"         Nullable="1" />
      <Column Name="Sales Area" ID="_Sales_Area" Type="string" MaxSize="100"         Nullable="1"/>
      <Column Name="Sales Number" ID="_Sales_Number" Type="integer" Nullable="1"         />
      <Column Name="Timestamp" ID="_Timestamp" Type="timestamp" Nullable="0" />
      <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.5600000-07:00" />
      </Row>
    </Contents>
  </DataObject>
</Import>
</OracleBAMCommands>

6.7.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 will be included in the Result or Error elements of any output related to that command.

Sample Input:

<OracleBAMCommands>
  <Delete id="1" type="role" name="Report Creator" />
  <Delete id="2" type="user" name="joeschmoe" /></OracleBAMCommands>

Sample Output:

<ICommandLog Login="MSOLNIT-PC\ASPNET">
  <Results Command="Delete" ID="1">Role "Report Creator" deleted.</Results>
  <Error Command="Delete" ID="2">
    <![CDATA[Error while processing command "Delete". [ErrorSource="ICommandEngine", ErrorID="ICommandEngine.Error"] There is no User named "joeschmoe". [ErrorSource="ICommandEngine", ErrorID="ICommandEngine.UserExist"]]]>
  </Error>
</ICommandLog>

6.7.3 Continue On Error

Ordinarily, ICommand will execute 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 will be executed. This behavior can be changed by using the continueonerror attribute at either a global level or for each command.

Example 6-1 shows how to use the continueonerror attribute so that all commands will be executed regardless of if any failures occur

Example 6-1 Enabling Global Continue-On-Error

<OracleBAMCommands continueonerror="1">
  <Delete id="1" type="role" name="Report Creator" />
  <Delete id="2" type="user" name="joeschmoe" />
</OracleBAMCommands>

In Example 6-2, continueonerror only applies to the command that deletes user joeschmoe. If this command fails, then ICommand will output the error and continue. But if any other command fails, ICommand will immediately stop.

Example 6-2 Enabling Command Continue-On-Error

<OracleBAMCommands>
  <Delete id="1" type="role" name="Report Creator" />
  <Delete id="2" type="user" name="joeschmoe" continueonerror="1" />
  <Delete id="3" type="user" name="user2" />
  <Delete id="4" type="user" name="user3" />
</OracleBAMCommands>

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

Sample log file (output from the preceding sample command file):

<?xml version="1.0" encoding="utf-8"?>
<ICommandLog Login="MYDOMAIN\myaccount">
  <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>

6.9 Sample DOS Command Lines

Here are a few sample DOS command lines:

ICommand cmdfile=cmd.xml logfile=log.xml logmode=append

ICommand cmd=export name=WebLog2 file=WebLog2.xml

ICommand cmdfile=cmd.xml

ICommand cmd=export file=EveryEMS.xml all type=ems

6.10 Sample export file

<?xml version="1.0" encoding="utf-8"?>
<OracleBAMExport Version="504.0" Build="3.0.3697.0">
  <DataObject Version="13" Name="Employees" ID="_Employees" Path="/Samples"
   External="0">
    <Layout>
      <Column Name="Salesperson" ID="_Salesperson" Type="string" MaxSize="100"
       Nullable="1" />
      <Column Name="Sales Area" ID="_Sales_Area" Type="string" MaxSize="100"
       Nullable="1" />
      <Column Name="Sales Number" ID="_Sales_Number" Type="integer" 
       Nullable="1" />
      <Column Name="Timestamp" ID="_Timestamp" Type="timestamp" Nullable="0" />
      <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.5600000-07:00" />
      </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.5600000-07:00" />
      </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.5600000-07:00" />
      </Row>
    </Contents>
  </DataObject>
</OracleBAMExport>

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

The following table contains the complete list of metacharacters and their behavior in the context of regular expressions:

Table 6-9 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 one 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 (©).

6.12 Using ICommand Web Service

ICommand is available as a web service for application developers who want to interact with ICommand features over HTTP.

This section contains the following topics:

Differences between the ICommand Web Service and the ICommand Command-Line Utility
Using the ICommand Web Service
Security Issues

6.12.1 Differences between the ICommand Web Service and the ICommand Command-Line Utility

The ICommand web service includes most of the same features as the command-line utility. For example, you can use it to:

Delete a data object
Create a user account
Import rows into a data object
Export a report
Run a plan

The key differences revolve around the fact that the Web service cannot access files on the remote system. Therefore, you cannot pass in a file name when using the import command or the export command.

Instead, you must pass in the import content inline. Similarly, you will receive back the export content inline.

Commands other than import and export generally work the same as with the command-line utility.

6.12.2 Using the ICommand Web Service

The ICommand web service is available on the machine where Report Server has been installed. It is at the URL

http://<host>:<http_port>/oraclebam/services/ICommand.asmx.

In addition, a WSDL document describing the web service can be found at

http://<host>:<http_port>/oraclebam/services/ICommand.asmx?WSDL.

This WSDL document is useful for binding to the web service from Visual Studio .NET or using the Java Web Services Developer Pack.

The ICommand web service has a single method, called Batch. It takes a single input parameter, which is a string containing a set of commands in the syntax described in "Format of Command File". The return value is a string containing the results of executing each command, in the log syntax described in "Format of Log File".

Example 6-3 Importing a Role (Input)

<OracleBAMCommands>
  <Import inline='1'>
    <OracleBAMExport Version="1003.0" Build="3.5.5603.0">
      <Role Name="Report Architect" ID="2">
        <Description>Has access to features for creating data objects and reports.</Description>
        <Privileges>
          <Privilege Name="ActiveStudio" />
          <Privilege Name="ActiveViewer" />
          <Privilege Name="Architect" />
          <Privilege Name="CreateAlertRule" />
          <Privilege Name="CreateDataObject" />
          <Privilege Name="CreateReport" />
          <Privilege Name="EmailRenderedReport" />
        </Privileges>
        <Members />
      </Role>
    </OracleBAMExport>
  </Import>
</OracleBAMCommands>

Example 6-4 Importing a Role (Output)

<ICommandLog Login="MSOLNIT-PC\ASPNET">
  <Results Command="Import">Role "Report Architect" importedsuccessfully.</Results>
  <Results Command="Import">1 items imported.</Results>
</ICommandLog>

Example 6-5 Exporting a Data Object (Input)

<OracleBAMCommands>
  <Export name='/Samples/Film Sales' inline='1'/>
</ OracleBAMCommands>

Example 6-6 Exporting a Data Object (Output)

<ICommandLog Login="MSOLNIT-PC\ASPNET">
  <OracleBAMExport Version="1003.0" Build="3.5.5603.0">
    <DataObject Version="14" Name="Film Sales" ID="_Film_Sales"
Path="/Samples" External="0">
      <Layout>
        <Column Name="Region" ID="_Region" Type="string" MaxSize="100" Nullable="1" Public="1" />
        <Column Name="State" ID="_State" Type="string" MaxSize="100" Nullable="1" Public="1" />
        <Column Name="Category" ID="_Category" Type="string" MaxSize="100" Nullable="1" Public="1" />
        <Column Name="Brand" ID="_Brand" Type="string" MaxSize="100" Nullable="1" Public="1" />
        <Column Name="Description" ID="_Description" Type="string" MaxSize="100" Nullable="1" Public="1" />
        <Column Name="Sales" ID="_Sales" Type="integer" Nullable="1" Public="1" />
        <Indexes />
      </Layout>
      <Contents>
        <Row ID="1">
          <Column ID="_Region" Value="Western Region" />
          <Column ID="_State" Value="Arizona" />
          <Column ID="_Category" Value="Film" />
          <Column ID="_Brand" Value="Kodak" />
          <Column ID="_Description" Value="35mm 200" />
          <Column ID="_Sales" Value="2000" />
        </Row>
        <Row ID="2">
          <Column ID="_Region" Value="Western Region" />
          <Column ID="_State" Value="Arizona" />
          <Column ID="_Category" Value="Film" />
          <Column ID="_Brand" Value="Kodak" />
          <Column ID="_Description" Value="35mm 400" />
          <Column ID="_Sales" Value="2100" />
        </Row>
      </Contents>
    </DataObject>
  </OracleBAMExport>
  <Results Command="Export">Exporting Data Object "/Samples/Film Sales"...</Results>
  <Results Command="Export">Data Object "/Samples/Film Sales" exported successfully (29 rows).</Results>
  <Results Command="Export">1 items exported successfully.</Results>
</ICommandLog>

6.12.3 Security Issues

The following are security issues with using the ICommand web service.

6.12.3.1 IIS Security (HTTP 401 error)

The Web server might not be configured to allow anonymous access to the Web service. In this case, you must include credentials in the Web service call. The method for doing this varies depending on your host environment (.NET, Java, and so on).

6.12.3.2 Active Data Cache Security

If the Web server does allow anonymous access, then it will typically run using a low-privilege account (such as the local ASPNET account). This account may not have access to all Oracle Business Activity Monitoring features, such as creating users or manipulating data objects.