E Oracle BAM Web Services Operations

This appendix is a reference for the operations provided by the Oracle BAM DataObjectOperations and DataObjectDefinition web services. More information about the Oracle BAM web services is available in Chapter 56, "Using Oracle BAM Web Services."

This appendix includes the following sections:

E.1 DataObjectOperations10131

The following operations are supported by the DataObjectOperations10131 web service:

E.1.1 Batch

Batch performs batch operations on a data object.

E.1.1.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

xmlPayload (xsd:string)

Contains the batch payload for any operations to be performed. For example:

<payload>
  <_Employees operation="insert">
    <_Salesperson>Tim Bray</_Salesperson>
    <_Sales_Area>EMEA</_Sales_Area>
    <_Sales_Number>12345</_Sales_Number>
  </_Employees>
  <_Employees operation="update" keys="_Sales_Number">
    <_Salesperson>Tim Bray</_Salesperson>
    <_Sales_Area>EMEA</_Sales_Area>
    <_Sales_Number>12345</_Sales_Number>
  </_Employees>
</payload>

E.1.2 Delete

Delete removes a row from the data object.

E.1.2.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

_Sales_Number,_Sales_Area

xmlPayload (xsd:string)

Payload for the where clause to delete rows in a data object. For example:

<_Employees>
  <_Sales_Number>12345</_Sales_Number>
</_Employees>

E.1.3 Insert

Insert adds rows to the specified data object.

E.1.3.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

xmlPayload (xsd:string)

The payload is specific to each data object.

<_Employees>
  <_Salesperson>Time Bray</_Salesperson>
  <_Sales_Area>EMEA</_Sales_Area>
  <_Sales_Number>12345</_Sales_Number>
</_Employees>

E.1.4 Update

Update operation updates existing data with new data in a data object.

E.1.4.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

_Sales_Number,_Sales_Area

xmlPayload (xsd:string)

Payload for the update statement and where clause to update rows in a data object. For example:

<_Employees>
  <_Sales_Area>Asia Pacific</_Sales_Area>
  <_Sales_Number>12345</_Sales_Number>
</_Employees>

E.1.5 Upsert

Upsert operation updates existing data with new data in an existing row in a data object. If the row does not exist a new row is created.

E.1.5.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

_Sales_Number,_Sales_Area

xmlPayload (xsd:string)

Payload for the insert or update statement and where clause to upsert rows in a data object. For example:

<_Employees>
  <_Salesperson>Time Bray</_Salesperson>
  <_Sales_Area>EMEA</_Sales_Area>
  <_Sales_Number>12345</_Sales_Number>
</_Employees>

E.2 DataObjectOperationsByName

The following operations are supported by the DataObjectOperations10131, DataObjectOperationsByName, and DataObjectOperationsByID web services.

E.2.1 Delete

Delete removes a row from the data object.

E.2.1.1 Request Message

The request message contains the following parameters.

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

Sales Number, Sales Area

xmlPayload (xsd:string)

Payload for the where clause to delete rows in a data object. For example:

<DataObject Name="Employees" Path="/Samples">
  <Contents>
    <Row>
      <Column Name="Salesperson" Value="Greg Guan" />
    </Row>
  </Contents>
</DataObject>

E.2.2 Get

Get fetches the details from a data object per the specifications in the XML payload

Get is only available in DataObjectOperationsByName web service.

E.2.2.1 Request Message

The request message contains the following parameters.

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

Sales Number, Sales Area

xmlPayload (xsd:string)

The payload specifies what to get from the data object.

For the DataObjectOperationsByName web service the data object name is specified in the payload, for example:

<DataObject Name="Employees" Path="/Samples">
  <Contents>
    <Row>
      <Column Name="Salesperson" Value="Greg Masters"/>
    </Row>
  </Contents>
</DataObject>

E.2.3 Insert

Insert adds rows to the specified data object.

E.2.3.1 Request Message

The request message contains the following parameters.

xmlPayload (xsd:string)

The payload is specific to each data object.

<DataObject Name="Employees" Path="/Samples">
  <Contents>
    <Row>
      <Column Name="Salesperson" Value="Greg Guan" />
      <Column Name="Sales Area" Value="Northeast" />
      <column Name="Sales Number" Value="5671" />
    </Row>
  </Contents>
</DataObject>

E.2.4 Update

Update operation updates existing data with new data in a data object.

E.2.4.1 Request Message

The request message contains the following parameters.

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

Sales Number, Sales Area

xmlPayload (xsd:string)

Payload for the update statement and where clause to update rows in a data object. For example:

<DataObject Name="Employees" Path="/Samples">
  <Contents>
    <Row>
      <Column Name="Salesperson" Value="Greg Guan" />
    </Row>
  </Contents>
</DataObject>

E.2.5 Upsert

Upsert operation updates existing data with new data in an existing row in a data object. If the row does not exist a new row is created.

E.2.5.1 Request Message

The request message contains the following parameters.

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

Sales Number, Sales Area

xmlPayload (xsd:string)

Payload for the insert or update statement and where clause to upsert rows in a data object. For example:

<DataObject Name="Employees" Path="/Samples">
  <Contents>
    <Row>
      <Column Name="Salesperson" Value="Greg Guan" />
      <Column Name="Sales Area" Value="Northeast" />
      <column Name="Sales Number" Value="5671" />
    </Row>
  </Contents>
</DataObject>

E.3 DataObjectOperationsByID

The following operations are supported by the DataObjectOperations10131, DataObjectOperationsByName, and DataObjectOperationsByID web services.

E.3.1 Batch

Batch performs batch operations on a data object.

E.3.1.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

xmlPayload (xsd:string)

Contains the batch payload for any operations to be performed. For example:

<payload>
  <_Employees operation="insert">
    <_Salesperson>Tim Bray</_Salesperson>
    <_Sales_Area>EMEA</_Sales_Area>
    <_Sales_Number>12345</_Sales_Number>
  </_Employees>
  <_Employees operation="update" keys="_Sales_Number">
    <_Salesperson>Tim Bray</_Salesperson>
    <_Sales_Area>EMEA</_Sales_Area>
    <_Sales_Number>12345</_Sales_Number>
  </_Employees>
</payload>

E.3.2 Delete

Delete removes a row from the data object.

E.3.2.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

This parameter is not required by the DataObjectOperationsByName web service because the data object name and path are part of the payload.

Full relative path and name of the data object, for example:

/Samples/Employees

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

_Sales_Number,_Sales_Area

xmlPayload (xsd:string)

Payload for the where clause to delete rows in a data object. For example:

<_Employees>
  <_Sales_Number>12345</_Sales_Number>
</_Employees>

E.3.3 Insert

Insert adds rows to the specified data object.

E.3.3.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

xmlPayload (xsd:string)

The payload is specific to each data object.

For the DataObjectOperationsByName web service the data object name is specified in the payload, for example:

<_Employees>
  <_Salesperson>Time Bray</_Salesperson>
  <_Sales_Area>EMEA</_Sales_Area>
  <_Sales_Number>12345</_Sales_Number>
</_Employees>

E.3.4 Update

Update operation updates existing data with new data in a data object.

E.3.4.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

_Sales_Number,_Sales_Area

xmlPayload (xsd:string)

Payload for the update statement and where clause to update rows in a data object. For example:

<_Employees>
  <_Sales_Area>Asia Pacific</_Sales_Area>
  <_Sales_Number>12345</_Sales_Number>
</_Employees>

E.3.5 Upsert

Upsert operation updates existing data with new data in an existing row in a data object. If the row does not exist a new row is created.

E.3.5.1 Request Message

The request message contains the following parameters.

dataObject (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Employees

keysCSV (xsd:string)

Comma separated column IDs that must be used as keys, for example:

_Sales_Number,_Sales_Area

xmlPayload (xsd:string)

Payload for the insert or update statement and where clause to upsert rows in a data object. For example:

<_Employees>
  <_Salesperson>Time Bray</_Salesperson>
  <_Sales_Area>EMEA</_Sales_Area>
  <_Sales_Number>12345</_Sales_Number>
</_Employees>

E.4 DataObjectDefinition Operations

The following operations are supported by DataObjectDefinition web service.

E.4.1 Create

Create creates a new data object. By specifying columnar elements, you can create calculated and lookup fields in addition to regular fields ass show in the examples.

E.4.1.1 Request Message

The request message contains the following parameter.

xmlPayload (xsd:string)

Contains the payload to create a data object.

Table E-1 xmlPayload Elements and Descriptions and Valid Values

Element Description and Values

/DataObject/@External

0 (zero) indicates that the data object is not from an external data source (default).

1 indicates that the data object is from an external data source.

/DataObject/@Name

Name of the data object to be created not including the directory path.

/DataObject/@Path

Directory path in which to create the data object.

/DataObject/@Version

Data objects can be versioned 0 (default) through 14.

/DataObject/@TipText

Description of the data object to be created.

/DataObject/Layout/Column/@Name

Name of the column (field) in the data object.

/DataObject/Layout/Column/@Type

The following values are valid for column type: auto-incr-integer boolean calculated clob datetime decimal float iterID integer lookup string timestamp

/DataObject/Layout/Column/@Nullable

1 (default) indicates that the column supports null values.

0 (zero) indicates that the column does not support null values.

/DataObject/Layout/Column/@Public

1 (default) indicates that the column is public.

0 (zero) indicates that the column is not public.

/DataObject/Layout/Column/@MaxSize

For string type columns, this attribute specifies the maximum permissible string size.

Default value is 30.

/DataObject/Layout/Column/@Precision

For decimal type columns, this attribute specifies the precision of the decimal value.

/DataObject/Layout/Column/@Scale

For decimal type columns, this attribute specifies the scale of the decimal value.

/DataObject/Layout/Column/@TipText

Column description


Example E-1 xmlPayload to Create Data Object With Regular Columns

<DataObject Version="14" Name="Employees3" ID="_Employees3" Path="/Samples"
            External="0">
  <Layout>
    <Column Name="Salesperson" ID="_Salesperson" Type="string" MaxSize="30"
            Nullable="1" Public="1" />
    <Column Name="Sales Number" ID="_Sales_Number" Type="decimal" 
            Nullable="1" Public="1" />
    <Column Name="Timestamp" ID="_Timestamp" Type="timestamp" 
            Nullable="0" Public="1" />
    <Indexes />
  </Layout>
</DataObject>

Example E-2 xmlPayload to Create Data Object With Lookup Field

<DataObject Version="14" Name="LookupDO" ID="_LookupDO" Path="/Samples">
  <Layout>
    <Description><![CDATA[Lookup]]></Description>
    <Column Name="Name" ID="_Name" Type="string" MaxSize="100" 
            Nullable="1" Public="1" />
    <Column Name="ID" ID="_ID" Type="integer" Nullable="1" Public="1" />
    <Column Name="Sales Area" ID="_Sales_Area" Type="lookup">
      <Lookup>
        <DataObject>
          <ID>_Employees</ID>
          <Path>/Samples</Path>
        </DataObject>
        <LookupFieldID>_Sales_Area</LookupFieldID>
        <MatchFields>
          <KeyPair>
            <PrimaryKeyID>_Sales_Number</PrimaryKeyID>
            <ForeignKeyID>_ID</ForeignKeyID>
          </KeyPair>
        </MatchFields>
      </Lookup>
    </Column>
    <Indexes />
  </Layout>
</DataObject>

Note that when you construct the XML payload for the Create operation, and the data object version is lower than 12, use PrimaryKey instead of PrimaryKeyID, ForeignKey instead of ForeignKeyID, LookupField instead of LookupFieldID, and provide name values instead of IDs for those fields.

Example E-3 xmlPayload to Create Data Object With Calculated Field

<DataObject Version="14" Name="CalculatedDO" ID="_CalculatedDO" Path="/Samples">
  <Layout>
    <Description><![CDATA[Calculated Column]]></Description>
    <Column Name="Name" ID="_Name" Type="string" MaxSize="100" Nullable="1"
            Public="1" />
    <Column Name="Address" ID="_Address" Type="string" MaxSize="100" Nullable="1"
            Public="1" />
    <Column Name="Salary" ID="_Salary" Type="decimal" Scale="10" Nullable="1"
            Public="1" />
    <Column Name="Income Tax" ID="_Income_Tax" Type="calculated"
            CalculatedExpression="&lt;expression type=&quot;MathExpression&quot;
&gt;&lt;operation&gt;&lt;left&gt;&lt;type&gt;FieldID&lt;/type&gt;&lt;ivalue&gt;
_Salary&lt;/ivalue&gt;&lt;/left&gt;&lt;operator&gt;*&lt;/operator&gt;&lt;right&gt;
&lt;type&gt;DECIMAL&lt;/type&gt;&lt;ivalue&gt;0.3&lt;/ivalue&gt;&lt;/right&gt;&lt;
/operation&gt;&lt;/expression&gt;" ExpressionUserText="(Salary * 0.3)" />
    <Indexes />
  </Layout>
</DataObject>

E.4.1.2 Response Message

void

E.4.2 Delete

Delete removes a data object definition and its contents.

E.4.2.1 Request Message

The request message contains the following parameter.

dataObjectFullName (xsd:string)

Full relative path and name of the data object to be deleted. For example:

/Samples/Employees

E.4.2.2 Response Message

void

E.4.3 Get

Get retrieves an existing data object definition.

E.4.3.1 Request Message

The request message contains the following parameters.

dataObjectFullName (xsd:string)

Full relative path and name of the data object, for example:

/Samples/Sales

E.4.3.2 Response Message

The response message contains the following parameter.

xmlPayload (xsd:string)

An XML description of the data object is returned. The schema used is the same definition as described for the Create and Update operations. You can use this operation to find the ID values of the data object and any columns.

Example E-4 xmlPayload for Get Operation

<DataObject Version="14" Name="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>
</DataObject>

E.4.4 Update

Update updates the definition of an existing data object. If a specified column exists in the original definition, the new column definition overwrites the old one. If columns in the existing definition are not specified in the new definition, their definitions are removed. The data object index definition can be updated as well.

E.4.4.1 Request Message

The request message contains the following parameters.

xmlPayload (xsd:string)

Payload for the Update operation is similar to the Create payload with one additional attribute. For example:

<DataObject Version="14" Name="Employees4" ID="_Employees4" Path="/Samples" External="0">
  <Layout>
    <Column Name="Salesperson" ID="_Salesperson" Type="string" MaxSize="50"
            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>
</DataObject>

E.4.4.2 Response Message

void

E.5 ManualRuleFire Operations

The following operation is supported by ManualRuleFire web service.

E.5.1 FireRuleByName

Use this operation to manually launch a rule.

This web service takes a string parameter, which should have user name, followed by a period (.), followed by the alert name. For example:

user_name.alertname

The period is used as a separator between the user name and the alert name. The web service always treats last period in the string as the separator, allowing the user name to contain periods. For example

user.nema.alerrtname

It follows then that the alert names cannot contain a period. If you must use the ManualRuleFire web service with an alert containing a period in its name, the alert must be renamed so that it does not contain any periods.

E.5.1.1 Request Message

The request message contains the following parameter.

xmlPayload (xsd:string)

An example:

<FireRuleByName xmlns="http://xmlns.oracle.com/bam">
  <strRuleName>string</strRuleName>
</FireRuleByName>

E.5.1.2 Response Message

Returns (xsd:string)

<FireRuleByNameResponse xmlns="http://xmlns.oracle.com/bam">
  <FireRuleByNameResult>string</FireRuleByNameResult>
</FireRuleByNameResponse>