6 Using the Oracle BPEL Process Analytics Web Service

This chapter describes the Oracle BPEL Process Analytics Web service that enables applications, such as Oracle BPEL Process Manager, Microsoft Excel spreadsheets, portals, and any application that can invoke a Web service, to access Oracle BPEL Process Analytics KPIs and metrics. For example, an Oracle BPEL Process Manager process, can invoke the Oracle BPEL Process Analytics Web service to get LoanFlow metric and KPI values, and then alter the loan annual percentage rate (APR) dynamically, based on these values.

In addition, this chapter describes the Oracle BPEL Process Manager Web service wrapper, that enables you (or an application) to invoke the Oracle BPEL Process Analytics Web service from the Oracle BPEL Process Manager Console.

This chapter includes the following topics:

Web Service End Point Definition
Web Service Features
Web Service Operations – Reference
Invoking the Web Service from Oracle BPEL Process Manager

Note:

The directory paths shown in this chapter follow Microsoft Windows conventions (using backslashes (\)). If you are using Unix, modify the directory paths as required (using slashes (/)).

Web Service End Point Definition

When you install Oracle BPEL Process Analytics in the Oracle Application Server middle tier, the Web Service Design Language (WSDL) file, BAMService.wsdl, and the XML schema file, bamws.xsd, are installed. These files are placed in the following locations, respectively, where system-name is the system on which you installed Oracle Application Server, and port is the port number returned during the Oracle Application Server installation (at which you can access the Oracle Application Server main page).

WSDL and schema file location:

http://system-name:port/bam-ws/BAMService
http://system-name:port/bam-ws/bamws.xsd

The Web service endpoint:

http://mysystem.mycompany.com:1788/bam-ws/BAMService

Web Service Features

The Oracle BPEL Process Analytics Web service is a document/literal style Web service. As illustrated in Figure 6-1, it allows any Web Service client to access real-time metrics and KPIs computed by Oracle BPEL Process Analytics.

Figure 6-1 Web Service Request Response Model

Description of the illustration xipug008.gif

The Web Service supports the following operations:

getEvents – Returns the events monitored by Oracle BPEL Process Analytics using a specified composite event within a given time window
getKPIValue – Returns the value of a KPI that was defined through the Oracle BPEL Process Analytics Console
getKPIDrilldownByDimensions – Returns the value of a KPI that was defined through the Oracle BPEL Process Analytics Console, filtered by a specified dimension value
publishEvents – Publishes events to Oracle BPEL Process Analytics

These operations are described in detail in "Web Service Operations – Reference".

Web Service Operations – Reference

The Oracle BPEL Process Analytics Web service supports four operations, as described in the following topics:

getEvents Operation
getKPIValue Operation
getKPIDrilldownByDimensions Operation
publishEvents Operation

getEvents Operation

Returns the events monitored by Oracle BPEL Process Analytics using a specified composite event within a given time window.

Before using the getEvents operation, you must create an event source and create a composite event that contains the events that you want returned by this operation.

See "Creating, Modifying, and Deleting Event Source Connections" and "Modeling Composite Events and Composite Event Groups" for more information about creating the prerequisite objects.

getEvents Request

/bam:GetEventsRequest/bam:UserName

A valid Oracle BPEL Process Analytics Administrator account name.

/bam:GetEventsRequest/bam:Password

A valid Oracle BPEL Process Analytics Administrator account password.

/bam:GetEventsRequest/bam:CompositeEvent/bam:Window

The time frame, n, in which events are to be returned, in seconds. The getEvents operation returns all of the events monitored by Oracle BPEL Process Analytics in last n seconds.

/bam:GetEventsRequest/bam:CompositeEvent/bam:Filter

Filters the type of events that are returned. Valid filter values are as follow:

All

Specifies that all of the events in the time frame be returned
Pending

Specifies that all of the events in the composite event that have not yet completed be returned
Timeout

Specifies that all of the events in the composite event that have timed out in the current time frame be returned
Complete

Specifies that all of the events in the composite event that have completed within the current time frame be returned

/bam:GetEventsRequest/bam:CompositeEvent/bam:Dimension

Specifies the dimension name by which to filter the returned events within a composite event.

/bam:GetEventsRequest/bam:CompositeEvent/@name

Specifies the name of the composite event for which you want events returned.

/bam:GetEventsRequest/bam:CompositeEvent/@details

Specifies whether or not event attributes are to be returned with the event. Set to this element to true to have event attributes returned with the event; otherwise set it to false.

getEvents Request Document Schema

<xsd:element name="GetEventsRequest"
              type="GetEventsRequestType"/>

   <xsd:complexType name="GetEventsRequestType">
     <xsd:sequence>
       <xsd:element username="UserName"
                        type="xsd:string"/>
       <xsd:element password="Password"
                        type="xsd:string"/>
      <xsd:element name="CompositeEvent"
                   type="EventRequestType"/>
     </xsd:sequence>
   </xsd:complexType>

   <xsd:complexType name="EventRequestType">
     <xsd:sequence>
       <xsd:element name="Window" type="xsd:int"/>
       <xsd:element name="Filter" type="xsd:string"/>
       <xsd:element name="Dimension" type="xsd:string"/>
     </xsd:sequence>
     <xsd:attribute name="name" type="xsd:string" />
     <xsd:attribute name="details" type="xsd:boolean"/>
   </xsd:complexType>

getEvents Response

/bam:GetEvents/bam:Event

Within the specified time frame, the array of events returned a composite event.

/bam:GetEventsResponse/bam:Event/Timestamp

The time stamp of the returned event in this format:

yyyy-MM-dd'T'HH:mm:ss[.SSS][Z | [+|-]hh:mm

The values for yyyy-MM-dd'T'HH:mm:ss and time zone are required. The milliseconds are optional. See the "Required Date Format" for a description of the format values.

/bam:GetEventsResponse/bam:Event/@name

The name of the event within the returned composite event.

/bam:GetEventsResponse/bam:Event/@id

The ID of the event within the returned composite event.

/bam:GetEventsResponse/bam:Event/CompositeEvent/@name

The name of the composite event to which the returned event belongs.

/bam:GetEventsResponse/bam:Event/CompositeEvent/@id

The ID of the composite event to which the returned event belongs.

/bam:GetEventsResponse/bam:Event/bam:Attribute

The array of attributes returned for an event instance. The attributes are returned only if the details element is set to true in the input document.

/bam:GetEventsResponse/bam:Event/bam:Attribute/@Value

The value of an attribute within an event instance.

/bam:GetEventsResponse/bam:Event/bam:Attribute/@name

The name of an attribute within an event instance.

/bam:GetEventsResponse/bam:Event/bam:Attribute/@type

The data type of an attribute within an event instance. Oracle BPEL Process Analytics attributes can be any one of the following data types:

Number

Includes integers, doubles, floats, and so on
Text

Any string type
Date

A date specification in the format:
```
yyyy-MM-dd'T'HH:mm:ss[.SSS] Z | [+|-]hh:mm
```
The values for yyyy-MM-dd'T'HH:mm:ss and Z are required. The milliseconds are optional. See the "Required Date Format" for a description of the format values.

getEvents Response Document Schema

<xsd:element name="GetEventsResponse"
             type="GetEventsResponseType"/>

   <xsd:complexType name="GetEventsResponseType">
     <xsd:sequence>
       <xsd:element name="Event" type="EventDetailsType"
               maxOccurs="unbounded"/>
     </xsd:sequence>
   </xsd:complexType>

   <xsd:complexType name="EventDetailsType">
     <xsd:sequence>
       <xsd:element name="Timestamp" type="xsd:dateTime"/>
       <xsd:element name="CompositeEvent"
                    type="CompositeEventType"/>
       <xsd:element name="Attribute"
                    type="AttributeType"
                    maxOccurs = "unbounded"
                    minOccurs="0"/>
     </xsd:sequence>
     <xsd:attribute name="name" type="xsd:string"/>
     <xsd:attribute name="id" type="xsd:string"/>
   </xsd:complexType>

   <xsd:complexType name="CompositeEventType">
     <xsd:attribute name="name" type="xsd:string"/>
     <xsd:attribute name="id" type="xsd:string"/>
   </xsd:complexType>


   <xsd:complexType name="AttributeType">
     <xsd:sequence>
       <xsd:element name="Value" type="xsd:string"/>
     </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string"/>
        <xsd:attribute name="type" type="xsd:string"/>
   </xsd:complexType>

getEvents Operation Examples

The following are examples of request and response documents for the getEvents operation:

Example 1 getEvents Request Document

<GetEventsRequest xmlns="http://xmlns.oracle.com/integration/service/bam">
  <AuthenticateLogin>
    <UserName>Administrator</UserName>
    <Password>Administrator</Password>
  </AuthenticateLogin>
  <CompositeEvent name="LoanFlow" details="true">
    <Window>1000</Window>
    <Filter>All</Filter>  
  </CompositeEvent>
</GetEventsRequest>

Example 2 getEvents Response Document

<GetEventsResponse xmlns="http://xmlns.oracle.com/integration/service/bam">
 <Event name="LoanRequest" id="oc4j-1234">
   <CompositeEvent name="LoanFlow" id="LoanFlow-1234"/>
   <Timestamp>2004/10/16 16:31:43.453 PDT</Timestamp>
   <Attribute name="SSN" type="Text">123-456-7890</Attribute>
   <Attribute name="Amount" type="Number">20000.0</Attribute>
 </Event>
 <Event name="LoanOfferResponse" id="AD19A634C6399ED6167DF6CBE25351CF" >
    <CompositeEvent name="LoanFlow" id="LoanFlow-1234"/>
    <Timestamp>2004-10-25 13:04:16</Timestamp>
    <Attribute name="APR" type="number" >7</Attribute>
    <Attribute name="LoanApplicationId" type="number" >36168</Attribute>
    <Attribute name="LoanApproved" type="text" >true</Attribute>
    <Attribute name="ProviderName" type="text" >StarLoan Provider</Attribute>
 </Event>
</GetEventsResponse>

getKPIValue Operation

Returns the value of a key performance indicator (KPI) that was configured in the Oracle BPEL Process Analytics Console.

Before using the getKPIValue operation, you must create an event source, create a composite event, and create the KPI for which you want to get values.

See "Creating, Modifying, and Deleting Event Source Connections", and "Modeling Composite Events and Composite Event Groups", and "Modeling KPIs and Related Objects" for more information about creating the prerequisite objects.

getKPIValue Request

/bam:GetEventsRequest/bam:UserName

A valid Oracle BPEL Process Analytics Administrator account name.

/bam:GetEventsRequest/bam:Password

A valid Oracle BPEL Process Analytics Administrator account password.

/bam:GetKPIValueRequest/bam:KPI/bam:TimeGrain

The time grain over which the KPI value is computed. Valid values are:

Day
Month
Quarter
Year

/bam:GetKPIValueRequest/bam:KPI/bam:Periods

The number of time periods for which the KPI value is to be returned. The values are returned beginning with the current period and working backward. The length of time required to complete this operation corresponds to the number of time periods requested.

/bam:GetKPIValueRequest/bam:KPI/@name

The name of the KPI for which you want values to be returned.

/bam:GetKPIValueRequest/bam:KPI/@CompositeEvent

The composite event on which the KPI to be returned is defined.

/bam:GetKPIValueRequest/bam:KPI/bam:Dimension/@name

The name of the dimension with which to filter the KPI value. If no dimension name is specified, then the KPI value for all of the dimension values is returned.

/bam:GetKPIValueRequest/bam:KPI/bam:Dimension/Value

The value for the dimension with which to filter the KPI value. This element is optional.

getKPIValue Request

<xsd:element name="GetKPIValueRequest"
              type="GetKPIValueRequestType"/>
<xsd:complexType name="GetKPIValueRequestType">
   <xsd:sequence>
     <xsd:element username="UserName"
                      type="xsd:string"/>
     <xsd:element password="Password"
                      type="xsd:string"/>
     <xsd:element name="KPI"
                  type="KPIRequestType"/>
   </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="KPIRequestType">
  <xsd:sequence>
    <xsd:element name="TimeGrain" type="xsd:string" />
    <xsd:element name="Periods" type="xsd:int" />
    <xsd:element name="Dimension" type="DimensionType"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string" />
  <xsd:attribute name="CompositeEvent" type="xsd:string" />
</xsd:complexType>
 
<xsd:complexType name="DimensionType">
    <xsd:sequence>
      <xsd:element name="Value" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
</xsd:complexType>

getKPIValue Response

/bam:GetKPIValueResponse/bam:KPI/@name

The name of the KPI for which you want values returned.

/bam:GetKPIValueResponse/bam:KPI/bam:KPIValue

An array of KPI values. There is one array element for each of the time periods requested.

/bam:GetKPIValueResponse/bam:KPI/bam:KPIValue/bam:For

The duration over which the KPI value is computed. Valid duration values are:

Day
Month
Quarter
Year

/bam:GetKPIValueResponse/bam:KPI/bam:KPIValue/bam:Value

The value of the KPI for the time duration specified.

/bam:GetKPIValueResponse/bam:KPI/bam:KPIValue/bam:Target

If specified, the target value specified for the KPI.

/bam:GetKPIValueResponse/bam:KPI/bam:KPIValue/bam:PerformanceBand

The KPI status with respect to the performance band.

/bam:GetKPIValueResponse/bam:KPI/bam:KPIValue/bam:Variance

The variance of the KPI value, with respect to the target value (if a target value was specified).

/bam:GetKPIValueResponse/bam:KPI/bam:KPIValue/bam:Trend

The upward or downward trend of the KPI, with respect to previous KPI values.

getKPIValue Response Document Schema

<xsd:element name="GetKPIValueResponse"
              type="GetKPIValueResponseType"/>

<xsd:complexType name="GetKPIValueResponseType">
  <xsd:sequence>
    <xsd:element name="KPI" type="KPIType"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string" />
</xsd:complexType>

<xsd:complexType name="KPIType">
  <xsd:sequence>
    <xsd:element name="KPIValue"
                 type="KPIValueType"
            maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="KPIValueType">
  <xsd:sequence>
    <xsd:element name="For" type="xsd:string"/>
    <xsd:element name="Value" type="xsd:int"/>
    <xsd:element name="Target" type="xsd:int"/>
    <xsd:element name="PerformanceBand" type="xsd:string" />
    <xsd:element name="Variance" type="xsd:int" />
    <xsd:element name="Trend" type="xsd:string" />
  </xsd:sequence>
</xsd:complexType>

getKPIValue Operation Examples

The following are examples of request and response documents for the getKPIValue operation:

Example 1 getKPIValue Request Document

<GetKPIValueRequest xmlns="http://xmlns.oracle.com/integration/service/bam >
  <AuthenticateLogin>
    <UserName>Administrator</UserName>
    <Password>Administrator</Password>
  </AuthenticateLogin>
  <KPI name="POCount" CompositeEvent="PurchaseOrders">
    <TimeGrain>Day</TimeGrain>
    <Periods>2</Periods>
    <Dimension name="Product">Laptop</Dimension>
  </KPI>
</GetKPIValueRequest>

Example 2 getKPIValue Response Document

<GetKPIValueResponse>
  <KPI name="POCount">
    <KPIValue>
      <For TimeGrain="Day">2004-08-11</For>
      <Value>25</Value>
      <Target>30</Target>
      <PerformanceBand>normal_performer</PerformanceBand>
      <Variance>30</Variance>
      <Trend>Up</Trend>
    </KPIValue>
    <KPIValue>
      <For TimeGrain="Day">2004-08-10</For>
      <Value>30</Value>
      <Target>50</Target>
      <PerformanceBand>under_performer</PerformanceBand>
      <Variance>30</Variance>
      <Trend>Down</Trend>
    </KPIValue>
  </KPI>
</GetKPIValueResponse>

getKPIDrilldownByDimensions Operation

Returns the value of a key performance indicator (KPI) that was configured in the Oracle BPEL Process Analytics Console, filtered by a specified dimension name and value.

Before using the getKPIDrilldownByDimensions operation, you must create an event source, create a composite event, and create the KPI for which you want to get values.

getKPIDrilldownByDimensions Request

/bam:GetEventsRequest/bam:UserName

A valid Oracle BPEL Process Analytics Administrator account name.

/bam:GetEventsRequest/bam:Password

A valid Oracle BPEL Process Analytics Administrator account password.

/bam:GetKPIValueRequest/bam:KPI/bam:TimeGrain

The time grain over which the KPI value is computed. Valid values are:

Day
Month
Quarter
Year

/bam:GetKPIValueRequest/bam:KPI/bam:Periods

/bam:GetKPIValueRequest/bam:KPI/@name

The name of the KPI for which you want values to be returned.

/bam:GetKPIValueRequest/bam:KPI/@CompositeEvent

The composite event on which the KPI to be returned is defined.

/bam:GetKPIValueRequest/bam:KPI/bam:Dimension/Value

The value for the dimension by which to filter the KPI value.

/bam:GetKPIValueRequest/bam:KPI/bam:Dimension/@name

The name of the dimension by which to filter the KPI value. If no dimension name is specified, then the KPI value for all of the dimension values is returned.

getKPIDrilldownByDimensions Request Document Schema

<xsd:element name="GetKPIValueRequest"
             type="GetKPIValueRequestType"/>

<xsd:complexType name="GetKPIValueRequestType">
  <xsd:sequence>
    <xsd:element username="UserName"
                     type="xsd:string"/>
    <xsd:element password="Password"
                     type="xsd:string"/>
    <xsd:element name="KPI"
                 type="KPIRequestType"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="KPIRequestType">
  <xsd:sequence>
    <xsd:element name="TimeGrain" type="xsd:string" />
    <xsd:element name="Periods" type="xsd:int" />
    <xsd:element name="Dimension" type="DimensionType"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string" />
  <xsd:attribute name="CompositeEvent" type="xsd:string" />
</xsd:complexType>

<xsd:complexType name="DimensionType">
  <xsd:sequence>
    <xsd:element name="Value" type="xsd:string" minOccurs="0"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string"/>
</xsd:complexType>

getKPIDrilldownByDimensions Response

/bam:GetKPIDrilldownByDimensions/bam:KPIResponse/@KPI: The name of the KPI.
/bam:GetKPIDrilldownByDimensions/bam:KPIResponse@Dimension: The name of the dimension by which returned KPI values are filtered.
/bam:GetKPIDrilldownByDimensions/bam:KPIResponse/@Constraint: The value of the constraint by which returned KPI values are filtered.
/bam:GetKPIDrilldownByDimensions/bam:Period/bam:Count: The number of periods over which the KPI value is calculated.
/bam:GetKPIDrilldownByDimensions/bam:Period/bam:Performance: The performance band in which the KPI falls.

getKPIDrilldownByDimensions Response Document Schema

<xsd:element name="GetKPIDrilldownByDimensions"
              type="GetKPIDrilldownByDimensionsType"/>

<xsd:complexType name="GetKPIDrilldownByDimensionsType">
  <xsd:sequence>
    <xsd:element name="KPIResponse" type="KPIResponseType"
                               maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="KPIResponseType">
  <xsd:sequence>
    <xsd:element name="Period" type ="PeriodType" 
            maxOccurs="unbounded" />
  </xsd:sequence>
  <xsd:attribute name="KPI"  type="xsd:string"/>
  <xsd:attribute name="Dimension" type="xsd:string"/>
  <xsd:attribute name="Constraint"  type="xsd:string"/>
</xsd:complexType>

<xsd:complexType name = "PeriodType">
  <xsd:sequence>
    <xsd:element name="Count" type="xsd:int"/>
    <xsd:element name="Performance" type="xsd:string"/>
  </xsd:sequence>
</xsd:complexType>

getKPIDrilldownByDimensions Operation Examples

The following are examples of request and response documents for the getKPIDrilldownByDimensions operation:

Example 1 getKPIDrilldownByDimensions Request Document Schema

<GetKPIValueRequest>
   <AuthenticateLogin>
      <UserName>Administrator</UserName>
      <Password>Administrator</Password>
   </AuthenticateLogin>
   <KPI name="POCount" CompositeEvent="PurchaseOrders">    
      <TimeGrain>Day</TimeGrain>
      <Periods>2</Periods>
      <Dimension name="CarModel">All</Dimension>
   </KPI>
</GetKPIValueRequest>

Example 2 getKPIDrilldownByDimensions Response Document Schema

<GetKPIDrillDownResponse>
  <KPIResponse KPI="LoanFlow.CountReq" Dimension="CarModel" Constraint="Ford">
    <Period Date="Mon Feb 07 00:00:00 PST 2005">
       <Count>34</Count>
       <Performance>strong_performer</Performance>
    </Period>
  </KPIResponse> 
  <KPIResponse KPI="LoanFlow.CountReq" Dimension="CarModel"
 Constraint="Toyota">
    <Period Date="Mon Feb 07 00:00:00 PST 2005">
       <Count>40</Count>
       <Performance>strong_performer</Performance>
    </Period>
  </KPIResponse>
  <KPIResponse KPI="LoanFlow.CountReq" Dimension="CarModel" Constraint="Nissan">
    <Period Date="Mon Feb 07 00:00:00 PST 2005">
       <Count>38</Count>
       <Performance>strong_performer</Performance>
    </Period>
  </KPIResponse>
  <KPIResponse KPI="LoanFlow.CountReq" Dimension="CarModel" Constraint="Saturn">
    <Period Date="Mon Feb 07 00:00:00 PST 2005">
       <Count>45</Count>
       <Performance>strong_performer</Performance>
    </Period>
  </KPIResponse>
</GetKPIDrillDownResponse>

publishEvents Operation

Publishes events to Oracle BPEL Process Analytics. There is no response schema for this operation.

Before using the publishEvents operation, you must create a generic event source and create a composite event that contains the events that you to publish using this operation.

See "Generic Event Source Configuration Values" and "Modeling Composite Events and Composite Event Groups" for more information about creating the prerequisite objects.

publishEvents Request

/bam:publishEvents/bam:PublishEventsRequest/bam:UserName

A valid Oracle BPEL Process Analytics Administrator account name.

/bam:publishEvents/bam:PublishEventsRequest/bam:Password

A valid Oracle BPEL Process Analytics Administrator account password.

/bam:publishEvents/bam:bamEvent/bam:PublishEventsRequest/bam:payload

The published event data. The data must use the format of the event definition.xsd file that Oracle BPEL Process Analytics loaded when the composite event was created. The composite event must be created on a generic event source.

The .xsd files that Oracle BPEL Process Analytics loads are located in the following directory, where OAS_HOME is the directory specification for the Oracle Application Server home into which you installed Oracle BPEL Process Analytics:

OAS_HOME/integration/bam/config/generic

Note:

Do not alter any .xsd file in the OAS_HOME/integration/bam/config/generic directory. Doing so will result in Oracle BPEL Process Analytics being unable to monitor events defined in the altered .xsd file.

/bam:publishEvents/bam:PublishEventsRequest/bam:header/bam:timestamp

The time stamp at which the published event occurred.

See the "Required Date Format" for more information.

/bam:publishEvents/bam:PublishEventsRequest/bam:header/bam:timezone

The time zone in which the published event occurred.

See the "Required Date Format" for more information.

/bam:publishEvents/bam:PublishEventsRequest/bam:header/bam:type

The name of the event that you want to publish. This is one of the event names that was specified when the composite event was created on the generic event source.

publishEvents Request Document Schema

<xsd:element name="PublishEventsRequest"
              type="PublishEventsRequestType" />

<xsd:complexType name="PublishEventsRequestType">
  <xsd:sequence>
    <xsd:element name="UserName" type="xsd:string"/>
    <xsd:element name="Password" type="xsd:string"/>
    <xsd:element name="bamEvent" type="bamEventType"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="bamEventType">
  <xsd:sequence>
    <xsd:element name="header" type="headerType"/>
    <xsd:element name="payload"  type="payloadType"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="headerType">
  <xsd:sequence>
    <xsd:element name="id"  type="xsd:int" />
    <xsd:element name="timestamp" type="xsd:dateTime"/>
    <xsd:element name="timezone" type="xsd:string"/>
    <xsd:element name="type" type="xsd:string"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="payloadType">
  <!--event-specific schema -->     
</xsd:complexType>

publishEvents Example

The following is an example of a response document for the publishEvents operation:

<PublishEventsRequest xmlns=""http://xmlns.oracle.com/integration/services/bam">
   <AuthenticateLogin>
     <UserName>Administrator</UserName>
     <Password>Administrator</Password>
   </AuthenticateLogin>
     <bamEvent>
       <header>
        <timestamp>2004-10-16T16:31:43.453</timestamp>
        <timezone>-07:00</timezone>
        <type>Employee>
        <eventsourcename>MyEventSource</eventsourcename>
       </header>
       <payload>
         <ROWSET>
          <ROW num="1">
           <EMPNO>7369</EMPNO>
           <ENAME>SMITH</ENAME>
           <JOB>CLERK</JOB>
           <MGR>7902</MGR>
           <HIREDATE>1980-10-17T00:00:00</HIREDATE>
           <SAL>800</SAL>
           <COMM>0</COMM>
           <DEPTNO>20</DEPTNO>
         </ROW>
        </ROWSET>
       </paylload>
      </bamEvent>
    </PublishEventsRequest>

Invoking the Web Service from Oracle BPEL Process Manager

A sample BPEL process, BAMServiceWrapper, is provided that enables you to invoke the Oracle BPEL Process Analytics Web Service from Oracle BPEL Process Manager. The following topics provide step-by-step instructions:

Setting Up and Deploying the BAMServiceWrapper Process
Running the BAMServiceWrapper Process

Setting Up and Deploying the BAMServiceWrapper Process

The files (bpel.xml and BAMServiceWrapper.wsdl) required for invoking BAMServiceWrapper are located in the following directory, where OAS_HOME is the directory specification for the Oracle Application Server home into which you installed Oracle BPEL Process Analytics:

OAS_HOME\integration\bam\test\tutorials\webservices\BAMServiceWrapper

The following steps provide an example that describes how to set up and deploy BAMServiceWrapper. These steps assume that you have specified Oracle BPEL Process Manager as an event source and have created some KPIs.

If Oracle BPEL Process Manager and Oracle BPEL Process Analytics are not installed on the same system, copy all of the files in the BAMServiceWrapper directory from the Oracle BPEL Process Analytics system to a directory on the Oracle BPEL Process Manager system.

On the Oracle BPEL Process Manager system, open the bpel.xml file in a text editor, and change all occurrences of the wsdlLocation value to the system where you have installed Oracle BPEL Process Analytics.

For example, if your system is mysys.myco.com:1788, the edited file should appear as follows:

<?xml version = '1.0' encoding = 'UTF-8'?>
<BPELSuitcase>
  <BPELProcess id="BAMServiceWrapper" src="BAMServiceWrapper.bpel">
    <partnerLinkBindings>
       <partnerLinkBinding name="client">
          <property name="wsdlLocation">BAMServiceWrapper.wsdl</property>
       </partnerLinkBinding>
       <partnerLinkBinding name="BAMAuthentication">
          <property name="wsdlLocation">http://mysys.myco.com:1788/bam-ws/BAMService.wsdl</property>
       </partnerLinkBinding>
       <partnerLinkBinding name="BAMGetKPI">
          <property name="wsdlLocation">http://mysys.myco.com:1788/bam-ws/BAMService.wsdl</property>
       </partnerLinkBinding>
       <partnerLinkBinding name="BAMGetEvents">
          <property name="wsdlLocation">http://mysys.myco.com:1788/bam-ws/BAMService.wsdl</property>
       </partnerLinkBinding>
       <partnerLinkBinding name="BAMPublishEvents">
          <property name="wsdlLocation">http://mysys.myco.com:1788/bam-ws/BAMService.wsdl</property>
       </partnerLinkBinding>
    </partnerLinkBindings>
  </BPELProcess>
</BPELSuitcase>

On the Oracle BPEL Process Manager system, open the BAMServiceWrapper.wsdl file in a text editor and specify the system where you installed Oracle BPEL Process Analytics as the schema location in the Type Definitions section of the file.

For example, if your system is mysystem.myco.com:1788, the Type Definitions section should appear as follows:
```

  <types>
   <schema xmlns="http://www.w3.org/2001/XMLSchema">
    <import namespace="http://xmlns.oracle.com/integration/services/bam"
     schemaLocation="http://mysys.myco.com:1788/bam-ws/bamws.xsd"/>
   </schema>
 </types>
```
If it is not already started, start the Oracle BPEL Process Analytics Server.
Start the Oracle BPEL Process Manager Server.
Deploy the Oracle BPEL Process Analytics Service Wrapper, by opening a command window on your system and running the obant command in the BAMServiceWrapper directory on the Oracle BPEL Process Manager system. Your path must be set to the following directory:
```
BPEL_HOME\integration\orabpel\bin
```

Note:

The directory paths shown in this topic follow Microsoft Windows conventions (using backslashes (\)). If you are using Unix, modify the directory paths as required (using slashes (/)).

Running the BAMServiceWrapper Process

This section provides step-by-step instructions on running the BAMServiceWrapper process. It is assumed that you have already followed the steps described in "Setting Up and Deploying the BAMServiceWrapper Process".

Open the Oracle BPEL Process Manager Console, and log in to the default domain.
On the Dashboard tab, click BAMServiceWrapper. The BPEL Processes tab displays.
Select getKPIValue, then click select the operation.

Enter values as described in the following table, and then click Post XML Message. Figure 6-2 shows the values you might enter if you previously defined a composite event named LoanFlow, for which you created a KPI named CountLoanOffers. Data is returned, similar to that shown in Figure 6-3.

Page Element	Description
Username	The Oracle BPEL Process Analytics Administrator account user name.
Password	The Oracle BPEL Process Analytics Administrator account password.
KPI name	The name of the KPI for which you want to view values.
CompositeEvent	The name of the composite event on which the named KPI is defined.
TimeGrain	The time grain over which you want the KPI value computed.Valid values are Day, Month, Quarter, and Year.
Periods	The number of time periods for which you want the KPI value to be returned.
Dimension name	The name of the dimension with which you want to filter the returned KPI values. This field is optional.
Dimension value	If you specify a dimension name, the dimension value with which you want to filter the returned KPI values.

Click Audit Instance at the bottom of the page.

The Instances tab displays, such as shown in Figure 6-4.
Click the More link to see details about the instance.

Figure 6-2 Getting KPI Values

Description of bamservicewrapper1.gif follows

Description of the illustration bamservicewrapper1.gif

Figure 6-3 Value Returned

Description of bamservicewrapper2.gif follows

Description of the illustration bamservicewrapper2.gif

Figure 6-4 Instances Tab

Description of bamservicewrapper3.gif follows

Description of the illustration bamservicewrapper3.gif