19 Using Oracle BAM Web Services
This chapter describes how to use Oracle Business Activity Monitoring (Oracle BAM) web services such as DOOperations, DODefinition, and ManualRuleFire to build applications that publish data to the Oracle BAM Server for use in dashboards.
This chapter includes the following sections:
19.1 Understanding Oracle BAM Web Services
The Oracle BAM web services allow users to build applications that publish data to the Oracle BAM Server for use in dashboards. Any client that can talk to standard web services can use these APIs to publish data to Oracle BAM.
The Oracle BAM web services interfaces allow integration of Oracle BAM with other components such as Oracle BPEL Process Manager and Oracle Mediator, and they facilitate SOA composite application development.
Note:
This option cannot be used for complex processing of messages, performing lookups in Oracle BAM to augment the data, or initial bulk uploads to set up a star schema.
The data objects in the Oracle BAM Server are available using the Oracle BAM web services.
External web services can be called by an Oracle BAM alert rule. See Creating an Alert for more information.
Oracle BAM provides the following static untyped web service APIs:
-
DataObjectOperationsByName allows developers to interact with data objects by their display names. For example, Call Center performs Delete, Get, Insert, Update, or Upsert operations on rows in data objects migrated from BAM 11g within a BAM 12c server.
-
DataObjectOperationsByID allows developers to interact with data objects by their IDs. For example, Call_Center performs Batch, Delete, Insert, Update, or Upsert operations on rows in data objects migrated from BAM 11g within a BAM 12c server.
-
DOOperations performs Batch, Delete, Get, Insert, Update, or Upsert operations on rows in BAM 12c data objects.
-
DODefinition performs Create, Delete, Get, or Update operations on definitions of BAM 12c data objects.
-
ManualRuleFire can be used by other Oracle BAM services to launch rules created in Oracle BAM Composer.
These services can be discovered within an Oracle BAM Server using a WSIL interface.
In addition, you can view definitions (metadata) for all BAM data objects using the following WSIL interface:
http://host:port/OracleBAMWS/WebServices/Wsil/baminspection.wsil
19.2 Using the Legacy Data Object Web Services
The legacy web services allow users to manipulate BAM 11g Data Objects in the Oracle BAM 12c Server by inserting, updating, deleting, and upserting rows into the Data Objects.
The following operations are supported by these web service interfaces.
-
Batch performs batch operations on a data object. Batch is not available in the DataObjectOperationsByName web service.
-
Delete removes a row from the data object.
-
Get fetches the details from a data object per the specifications in the XML payload. Get is not available in the DataObjectOperationsByID web service.
-
Insert adds a row to the data object.
-
Update inserts new data into an existing row in a data object.
-
Upsert inserts new data into an existing row in a data object if the row exists. If the row does not exist, a new row is created.
The request and response messages vary depending on the operation used. See DataObjectOperationsByName and DataObjectOperationsByID for information about using the operations supported by each of the web services.
19.2.1 How to Use the Legacy Data Object Web Services
To use these web services, create a web service proxy in your application in Oracle JDeveloper.
The Web Services Description Language (WSDL) files for the DataObjectOperations web services are available at the following URLs on the system where Oracle BAM web services are installed.
http://host:port/OracleBAMWS/WebServices/DataObjectOperationsByName?WSDL http://host:port/OracleBAMWS/WebServices/DataObjectOperationsByID?WSDL
Note:
The default port for Oracle BAM web services on the Administration Server is 7001. On managed servers the default port number is 9001. You can specify any port number while installing Oracle BAM.
19.2.2 DataObjectOperationsByName
The following operations are supported by the DataObjectOperationsByName web service for BAM 11g Data Objects.
19.2.2.1 Delete
Delete removes a row from the data object.
19.2.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. Here is a sample Delete payload:
<DataObject Name="Employees" Path="/Samples"> <Contents> <Row> <Column Name="Salesperson" Value="Greg Guan" /> </Row> </Contents> </DataObject>
19.2.2.2 Get
Get fetches the details from a data object per the specifications in the XML payload
19.2.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. Here is a sample Get payload:
<DataObject Name="Employees" Path="/Samples"> <Contents> <Row> <Column Name="Salesperson" Value="Greg Masters"/> </Row> </Contents> </DataObject>
19.2.2.3 Insert
Insert adds rows to the specified data object.
19.2.2.3.1 Request Message
The request message contains the following parameters.
xmlPayload (xsd:string)
The payload is specific to each data object. Here is a sample Insert payload.
<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>
19.2.2.4 Update
Update operation updates existing data with new data in a data object.
19.2.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. Here is a sample of an Update payload:
<DataObject Name="Employees" Path="/Samples"> <Contents> <Row> <Column Name="Salesperson" Value="Greg Guan" /> </Row> </Contents> </DataObject>
19.2.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.
19.2.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. Here is a sample of an Upsert payload:
<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>
19.2.3 DataObjectOperationsByID
The following operations are supported by the DataObjectOperationsByID web service for BAM 11g Data Objects.
19.2.3.1 Batch
Batch performs batch operations on a data object.
19.2.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. Here is a sample Batch payload:
<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>
19.2.3.2 Delete
Delete removes a row from the data object.
19.2.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>
19.2.3.3 Insert
Insert adds rows to the specified data object.
19.2.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>
19.2.3.4 Update
Update operation updates existing data with new data in a data object.
19.2.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>
19.2.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.
19.2.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>
19.3 Using the Data Object Web Services
The Data Object web services allow a web service client to create, update, delete, and get BAM 12c data object rows and definitions.
The following operations are supported by these web services.
-
Batch performs batch operations on a data object. Batch is not available in the DODefinition web service.
-
Create creates a data object. Create is only available in the DODefinition web service.
-
Delete removes a data object row or definition.
-
Get fetches the details from a data object per the specifications in the XML payload.
-
Insert adds a row to the data object. Insert is not available in the DODefinition web service.
-
Update inserts new data into an existing row in a data object or updates a data object definition.
-
Upsert inserts new data into an existing row in a data object if the row exists. If the row does not exist, a new row is created. Upsert is not available in the DODefinition web service.
The request and response messages vary depending on the operation used. See DOOperations and DODefinition for more information.
19.3.1 How to Use the Data Object Web Services
To use these web services, you create a web service proxy in your application in Oracle JDeveloper.
The WSDL files for the DOOperations and DODefinition web services are available at the following URLs on the system where Oracle BAM web services are installed.
http://host:port/OracleBAMWS/WebServices/DOOperations?WSDL http://host:port/OracleBAMWS/WebServices/DODefinition?WSDL
Note:
The default port for Oracle BAM web services on the Administration Server is 7001. On managed servers the default port number is 9001.
19.3.2 DOOperations
The following operations are supported by DOOperations web service.
19.3.2.1 Batch
Batch performs batch operations on a data object.
19.3.2.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. Here is a sample DOOperations Batch payload.
<dataObjectOperations>
<operations>
<upsert dataobject="Sales">
<filter-columns>
<string value="Greg Guan" name="Salesperson" predicate="EQ"/>
</filter-columns>
<update-columns>
<string value="Hanumesh" name="Salesperson"/>
<string value="Northeast" name="SalesArea"/>
<integer value="70000" name="SalesNumber"/>
</update-columns>
<insert-columns>
<string value="Greg Guan" name="Salesperson"/>
<string value="Northeast" name="SalesArea"/>
<integer value="50000" name="SalesNumber"/>
</insert-columns>
</upsert>
<insert dataobject="Sales">
<insert-columns>
<string value="Greg Guan1" name="Salesperson"/>
<string value="Northeast" name="SalesArea"/>
<integer value="50000" name="SalesNumber"/>
</insert-columns>
</insert>
</operations>
</dataObjectOperations>19.3.2.2 Delete
Delete removes a row from the data object.
19.3.2.2.1 Request Message
The request message contains the following parameter.
xmlPayload (xsd:string)
Payload for the where clause to delete rows in a data object. Here is a sample Delete DOOperations payload:
<dataObjectOperations>
<operations>
<delete dataobject="Sales">
<filter-columns>
<string value="Hanumesh1" name="Salesperson" predicate="EQ"/>
</filter-columns>
</delete>
</operations>
</dataObjectOperations>19.3.2.3 Get
Get fetches the details from a data object per the specifications in the XML payload.
19.3.2.3.1 Request Message
The request message contains the following parameters.
keysCSV (xsd:string)
Comma-separated column IDs must be used as keys, for example:
/Salesperson,Sales
xmlPayload (xsd:string)
The payload specifies what to get from the data object.
For the DOOperations web service the data object name is specified in the payload, for example:
<DataObject Name="Sales">
<Contents>
<Row>
<Column Name="Salesperson" Value="Hanumesh"/>
</Row>
</Contents>
</DataObject>19.3.2.4 Insert
Insert adds rows to the specified data object.
19.3.2.4.1 Request Message
The request message contains the following parameter.
xmlPayload (xsd:string)
The payload is specific to each data object. Here is a sample DOOperations Insert Payload:
<dataObjectOperations>
<operations>
<insert dataobject="Sales">
<insert-columns>
<string value="Greg Guan" name="Salesperson"/>
<string value="Northeast" name="SalesArea"/>
<integer value="50000" name="SalesNumber"/>
</insert-columns>
</insert>
</operations>
</dataObjectOperations>19.3.2.5 Update
Update updates existing data with new data in a data object.
19.3.2.5.1 Request Message
The request message contains the following parameter.
xmlPayload (xsd:string)
The payload for the update statement includes a where clause to update the rows in a data object. For example:
<dataObjectOperations>
<operations>
<update dataobject="Sales">
<filter-columns>
<string value="Greg Guan" name="Salesperson" predicate="EQ"/>
</filter-columns>
<update-columns>
<string value="Hanumesh" name="Salesperson"/>
<string value="Northeast" name="SalesArea"/>
<integer value="60000" name="SalesNumber"/>
</update-columns>
</update>
</operations>
</dataObjectOperations>19.3.2.6 Upsert
Upsert 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.
19.3.2.6.1 Request Message
The request message contains the following parameter.
xmlPayload (xsd:string)
Payload for the insert or update statement and a where clause to upsert rows in a data object. For example:
<dataObjectOperations>
<operations>
<upsert dataobject="Sales">
<filter-columns>
<string value="Greg Guan" name="Salesperson" predicate="EQ"/>
</filter-columns>
<update-columns>
<string value="Hanumesh" name="Salesperson"/>
<string value="Northeast" name="SalesArea"/>
<integer value="70000" name="SalesNumber"/>
</update-columns>
<insert-columns>
<string value="Greg Guan" name="Salesperson"/>
<string value="Northeast" name="SalesArea"/>
<integer value="50000" name="SalesNumber"/>
</insert-columns>
</upsert>
</operations>
</dataObjectOperations>
19.3.3 DODefinition
19.3.3.1 Create
Create creates a new data object. You can create all four data object types: simple, derived, logical, and external.
19.3.3.1.1 Request Message
The request message contains the following parameter.
xmlPayload (xsd:string)
Contains the payload to create a data object. For example:
<ns0:simpleDataObject xmlns:ns0="http://xmlns.oracle.com/bam/bam12">
<name>Sales</name>
<displayName>Sales</displayName>
<cqType>RELATION</cqType>
<cqArchived>true</cqArchived>
<hidden>false</hidden>
<columns>
<column>
<name>Salesperson</name>
<id>1621481da151473caedc1a66c19dc2e6</id>
<displayName>Salesperson</displayName>
<length>2000</length>
<nullable>true</nullable>
<unique>false</unique>
<dataType>VARCHAR</dataType>
<columnType>ATTRIBUTE</columnType>
<hidden>false</hidden>
<editable>true</editable>
</column>
</columns>
</ns0:simpleDataObject>
Here is the xmlPayload to create a Derived Data Object:
<ns0:derivedDataObject xmlns:ns0="http://xmlns.oracle.com/bam/bam12">
<name>DSales</name>
<displayName>DSales</displayName>
<internal>false</internal>
<cqType>RELATION</cqType>
<cqArchived>true</cqArchived>
<hidden>false</hidden>
<columns>
<column>
<name>Discount</name>
<id>20a032f502dc4d38b9889a57d081be15</id>
<displayName>Discount</displayName>
<internal>false</internal>
<length>2000</length>
<nullable>true</nullable>
<unique>false</unique>
<precision>38</precision>
<scale>10</scale>
<dataType>DECIMAL</dataType>
<columnType>ATTRIBUTE</columnType>
<hidden>false</hidden>
<editable>true</editable>
</column>
</columns>
<parent type="dataObjectRef">Sales</parent>
</ns0:derivedDataObject>
Here is the xmlPayload to create a Logical Data Object:
<ns0:logicalDataObject xmlns:ns0="http://xmlns.oracle.com/bam/bam12">
<name>LSales</name>
<displayName>LSales</displayName>
<timeHierarchies/>
<dataObjects>
<dataObject type="dataObjectRef">DSales</dataObject>
<dataObject type="dataObjectRef">Sales</dataObject>
</dataObjects>
<columns>
<column>
<name>Salesperson</name>
<displayName>Salesperson</displayName>
<internal>false</internal>
<columnRef>
<dataObject>Sales</dataObject>
<column>Salesperson</column>
</columnRef>
<hidden>false</hidden>
<columnType>ATTRIBUTE</columnType>
</column>
<column>
<name>Discount</name>
<displayName>Discount</displayName>
<internal>false</internal>
<columnRef>
<dataObject>DSales</dataObject>
<column>Discount</column>
</columnRef>
<hidden>false</hidden>
<columnType>ATTRIBUTE</columnType>
</column>
</columns>
<joins>
<join>
<id>b2d4e97ba8be400a847aaa354fc7b1a0</id>
<internal>false</internal>
<leftColumns>
<column>
<dataObject>Sales</dataObject>
<column>BEAM_ID</column>
</column>
</leftColumns>
<rightColumns>
<column>
<dataObject>DSales</dataObject>
<column>BEAM_ID</column>
</column>
</rightColumns>
</join>
</joins>
</ns0:logicalDataObject>
Here is the xmlPayload to create an External Data Object:
<ns0:externalDataObject xmlns:ns0="http://xmlns.oracle.com/bam/bam12">
<name>ESales</name>
<displayName>ESales</displayName>
<internal>false</internal>
<cqType>RELATION</cqType>
<cqArchived>true</cqArchived>
<hidden>false</hidden>
<columns>
<column>
<name>FULLNAME</name>
<internal>false</internal>
<length>2000</length>
<nullable>true</nullable>
<unique>false</unique>
<dataType>VARCHAR</dataType>
<columnType>ATTRIBUTE</columnType>
<label>label_FULLNAME</label>
<hidden>false</hidden>
<editable>true</editable>
<physicalName>FULLNAME</physicalName>
</column>
</columns>
<schema>DEV12_SOAINFRA</schema>
<sourceName>BamDataSource</sourceName>
<jndiName>jdbc/BeamDataSource</jndiName>
<factDO>true</factDO>
</ns0:externalDataObject>19.3.3.3 Get
Get retrieves an existing data object definition.
19.3.3.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
19.3.3.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. Here is the xmlPayload for the Get operation:
<ns0:simpleDataObject xmlns:ns0="http://xmlns.oracle.com/bam/bam12">
<name>Sales</name>
<displayName>Sales</displayName>
<internal>false</internal>
<createdBy>weblogic</createdBy>
<modifiedBy>weblogic</modifiedBy>
<cqType>RELATION</cqType>
<cqArchived>true</cqArchived>
<slowChangingDimension>false</slowChangingDimension>
<hidden>false</hidden>
<columns>
<column>
<name>Salesperson</name>
<displayName>Salesperson</displayName>
<internal>false</internal>
<length>2000</length>
<nullable>true</nullable>
<unique>false</unique>
<precision>38</precision>
<scale>10</scale>
<dataType>VARCHAR</dataType>
<columnType>ATTRIBUTE</columnType>
<hidden>false</hidden>
<editable>true</editable>
</column>
</columns>
<indexes/>
<hierarchies/>
</ns0:simpleDataObject>19.3.3.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.
19.3.3.4.1 Request Message
The request message contains the following parameter.
xmlPayload (xsd:string)
The payload for the Update operation is similar to the Create payload. For example:
<ns0:simpleDataObject xmlns:ns0="http://xmlns.oracle.com/bam/bam12">
<name>Sales</name>
<displayName>Sales</displayName>
<cqType>RELATION</cqType>
<cqArchived>true</cqArchived>
<hidden>false</hidden>
<columns>
<column>
<name>SalesArea</name>
<id>1621481da151473caedc1a66c19dc2e6</id>
<displayName>Salesperson</displayName>
<length>2000</length>
<nullable>true</nullable>
<unique>false</unique>
<dataType>VARCHAR</dataType>
<columnType>ATTRIBUTE</columnType>
<hidden>false</hidden>
<editable>true</editable>
</column>
</columns>
</ns0:simpleDataObject>19.4 Using the ManualRuleFire Web Service
The ManualRuleFire web service allows users to launch alerts in the Oracle BAM Server. FireRuleByName is the available operation.
See ManualRuleFire Operations for details.
For more information about alerts, see Creating Alerts. For a ManualRuleFire example, see Alert and Web Service Example.
19.4.1 How to Use the ManualRuleFire Web Service
To use the ManualRuleFire web service, you create a web service proxy in your application in Oracle JDeveloper.
The WSDL file for the ManualRuleFire web service is available at the following URL on the system where Oracle BAM web services are installed.
http://host:port/OracleBAMWS/WebServices/ManualRuleFire?WSDL
Note:
The default port for Oracle BAM web services on the Administration Server is 7001. On managed servers the default port number is 9001.
When the web service proxy is created, you see it in the Application Navigator under the Application Sources folder in your project.
19.4.2 ManualRuleFire Operations
The following operation is supported by ManualRuleFire web service.
19.4.2.1 FireRuleByName
Use this operation to manually launch an alert.
This web service takes a string parameter, which must have the project internal name, followed by a period, followed by the alert internal name, as follows:
projectname.alertname
The period is the separator between the project name and the alert name. The web service always treats last period in the string as the separator, allowing the project name to contain periods. For example:
project.nemo.alert1
It follows that you cannot use the ManualRuleFire web service with an alert containing a period in its internal name. Since you cannot change the internal name, you must recreate the alert with an internal name that does not contain any periods.
19.4.2.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>