This documentation is for WSO2 Business Activity Monitor 2.3.0. View the home page of the latest release.

Unknown macro: {next_previous_link3}
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

BAM Mediator is a mediator for WSO2 ESB that captures data events from the ESB mediation sequences and sends to the BAM server. BAM server receives data events via its Thrift API. This uses a binary protocol and enables fast data transmission between the ESB and BAM server.

The BAM mediator can be configured early. The data to be extracted from ESB configuration context can be pre-configured. In the configuration panel, the user can specify the BAM server (Thrift server) related information in the BAM Server Profile. In each BAM Server Profile, the user should define a set of event streams that can be used at the BAM mediator declaration time. When a BAM mediator is declared in an ESB sequence, the user has to select a BAM Server Profile from the given list and a Stream (uniquely identified by a name and a version) available in the selected BAM Server Profile.

Installing BAM Mediator Feature

The following installation instructions apply to WSO2 ESB version 4.5.x onwards. But, BAM mediator is available by default from ESB 4.6.0 onwards and you do not have to install it separately.

1. Download the WSO2 ESB from location: http://wso2.com/products/enterprise-service-bus.

2. Since both ESB and BAM server will be run concurrently, change the port number of ESB by applying an offset. To apply an offset, navigate to <ESB_HOME>/repository/conf and open file, carbon.xml, where <ESB_HOME> is the WSO2 ESB's product distribution directory. Then change the value in xpath Server/Ports/Offset from 0 to some other integer. For example,

<!-- Ports offset. This entry will set the value of the ports defined below to the define value + Offset. e.g. Offset=2 and HTTPS port=9443 will set the effective HTTPS port to 9445-->
<Offset>2</Offset>

3. To the WSO2 ESB server,

  • on Linux, run <ESB_HOME>\bin\wso2server.sh

  • on MS Windows, run <ESB_HOME>/bin/wso2server.bat

4. After starting the server, log in to ESB's management console and select menu "Configure -> Features -> Repository Management" menu. Add a new P2 repository through either through a URL or from a file system. For more information on adding a P2 feature repository, refer to section Managing the Feature Repository.



5. Once done, navigate to "Available Features" tab and select the repository added in the previous step. Click the "Find Features" button. It will take a while to list out all the available features in the feature repository. Once listed, select "BAM Mediator Aggregate" feature. If you can't see "BAM Mediator Aggregate feature", retry with one of the following suggestions:

  • Deselect the 'Group features by category' check box and then click 'Find Features' button again.
  • Try adding a more recent P2 repository. It is possible the one you have is deprecated.
  • Check for the feature in the "Installed Features" tab.



6. Once the feature is selected, click "Install" link and proceed with the installation. For more information on feature installation, refer to section Installing Features.

7. Once the installation is completed, restart the WSO2 ESB server. 

Using BAM Mediator

There are few configurations that need to be done before using a BAM Mediator in a mediation sequence. When editing a mediation sequence, the user can only use the existing BAM Mediator configurations. These steps are explicitly described for a sample in the following sections.

Configuring BAM Server Profiles and Streams

Before adding a BAM mediator to a mediator sequence, BAM mediator configurations should be updated as below. Configuration information are basically considered as a set of BAM server profiles, which contains transport and credential data required to connect to the BAM server. In each BAM server profile, one or many Event Stream configurations should be defined. Streams contain Thrift API event-stream-related information like Stream Name, Stream Version etc. and data to be extracted from the configuration context of the mediation sequence.

1. Navigate to the ESB management console and select menu "Configure -> BAM -> Server Profile".

2. If there are no existing Profiles, add one using the "Add Profile" link.

3. If there are Profiles already existing, you can edit them using the "Edit Profile" link. If there are unnecessary profiles, they can be deleted using the "Remove Profile" link.


4. Enter the profile information shown in the following example,

  • Profile Name: Name for BAM server profile.
  • Server Credential: admin/admin by default.
  • Server Transport: Thrift as the default Protocol.
  • Enable Load Balancer: Enable if want to load balance with Thrift from the client side to several hosts. Then enter comma separated connection URLs of hosts as URL Set. e.g.: tcp://10.200.3.218:7611, tcp://10.100.3.97:7611. refer more details on using load balancing publishing in this page.
  • Enable Security: If message confidentiality is required from ESB server to BAM server, select this option.
  • IP Address: IP of the BAM server's Thrift server. By default, it is the IP address of the localhost.
  • Receiver Port:  If security is not enabled, this option will have to be given. Enter 7611 by default, which is the Thrift server port.
  • Authentication Port: Port number is 100 times greater than the Receiver Port, if the latter exists. Default Authentication Port number is 7711.
  • Test Server button: Using this, availability of the BAM server can be tested for the given IP Address and the Authentication Port.

5. Then, you can define a set of Stream Configurations among which the required Stream Configuration can be selected in the mediator definition time. Each Stream Configuration must have,

  • Name: Stream Name can be any string with alpha-numeric characters.
  • Version: Stream Version distinguishes different streams with the same Stream Name. Default version should be 1.0.0.
  • Nickname: This is a user-preferred nick name to the Stream Name in alpha-numeric characters.
  • Description: A description about the particular stream defined by Stream Name/Stream Version pair. Description should also consist of alpha-numeric characters.

When editing a stream, check on "Dump header" or "Dump body," if you want to record SOAP header or SOAP body of messages respectively. In "Stream Properties" the user can extract several types of properties from the message. Basically, Stream Properties are divided into two.

  • Value: A constant alpha-numeric string value entered to Value field is set as the property.
  • Expression: The given expression in Value field is considered as an expression and executed on the message to get the property. XPath properties and functions available in ESB are valid in the expression. (Note : At the moment, there is no way to add namespaces to xpath expressions which is to be completed in future. It is given in JIRA https://wso2.org/jira/browse/BAM-539 . As a workaround, you can use Property Mediator in ESB, to get the xpath and add it to the message context as a property which can then be captured from the BAM mediator using the get-property expression.)
  • Type drop down list: The required type to be converted in which the property should be sent via Thrift.

6. After "Stream Payload" and "Stream Properties" are added/edited, click the "Update" icon to reflect changes in the specific Stream Configuration. Next, click the "Add" icon to add the new Stream Property to the properties list. The "Cancel" button ignores the updated Stream Properties data.

7. After the changes are properly made to the BAM Server Profile, click on "Save" button to save all the configuration data to the secondary storage.

  1. After modifying the BAM Server Profile data the user can go back to BAM Server Profiles list to see the new set of existing BAM Server Profiles by clicking on the BAM Server Profile link on the top of the page.
  2. Similarly the user may add enough number of BAM Server Profiles and many unique Stream Configurations under a one BAM Server Profile.
Setting the Backend Server for ESB Endpoint

In order to test the functionality of the BAM mediator user can define a sample WSDL Proxy Service. Before creating that service the user needs to create an Endpoint service to the WSDL Proxy Service. Here are the steps to create an Endpoint service.

  1. In the ESB product directory go to $esb_home/samples/axis2Server/src/SimpleStockQuoteService and build the backend service with Apache Ant. (You need to install Apache Ant before that.)
  2. Go to $esb_home/samples/axis2Server and run the Axis2 server.

    For Linux,

    axis2server.sh

    For Windows,

    axis2server.bat

     

  3. Now test whether the proxy service WSDL exists in http://localhost:9000/services/SimpleStockQuoteService?wsdl
Adding a proxy service to WSO2 ESB

These are the steps to create a sample WSDL Proxy Service to test the BAM mediator.

  1. Go to ESB management console and select Main→Web Services→Add→Proxy Service from the side panel.
  2. Click on WSDL Based Proxy to create a new WSDL based proxy.
  3. Fill the form.
    1. Insert suitable Proxy Service Name (eg: Simple_Stock_Quote_Service_Proxy).
    2. Set http://localhost:9000/services/SimpleStockQuoteService?wsdl as the WSDL URI.
    3. Set SimpleStockQuoteService as the WSDL Service.
    4. Set SimpleStockQuoteServiceHttpSoap11Endpoint as the WSDL Port.
  4. Click Create.
  5. Select newly created proxy's name (here Simple_Stock_Quote_Service_Proxy) form the shown list to see the Service Dashboard of it.
Adding a BAM Mediator to WSDL Proxy Service

After creating a sample WSDL Proxy Service, the user can add one or more BAM mediators to the sequence of WSDL Proxy Service as follows.

  1. Go to ESB management console and select Main→Axis2 Services→List from side panel.
  2. Click on Simple_Stock_Quote_Service_Proxy to go to its dashboard.
  3. Click on Edit link under category, Specific Configuration.
  4. Click on Next> button.
  5. Select option Define Inline under category, Define In Sequence and click on its Create link.
  6. Click on Configuration Registry link, select [Sequence]-fault from the drop down list and click OK button.

  7. Click on Add Child link on the Root, select Agent→BAM from menus.

  8. Select BAM element from the sequence tree and go to the form appeared below.
  9. Select Server Profile from the available set of server profiles in the drop down list.
  10. Select Stream Name from the available set of stream names with the selected BAM server profile in the drop down list.
  11. Select Stream Version from the available set of stream versions with the selected stream name in the drop down list.

  12. Click Update button. You can observe the mediator XML generated for the BAM Mediator by clicking on switch to source view link. You can go back to the design view by clicking on switch to design view link.
    The mediator XML is in the following format. (This is an example.)
    <bam xmlns="http://ws.apache.org/ns/synapse">
       <serverProfile name="profile1">
          <streamConfig name="stream1" version="1.0.0" ></streamConfig>
       </serverProfile>
    </bam>

  13. Add more mediators to the WSDL Proxy Service if required.
  14. Click Save button.
  15. Click Next> button.
  16. Click Finish button. Now the BAM mediator is added to the WSDL Proxy Service, Simple_Stock_Quote_Service_Proxy.
Send Messages To the ESB

At the moment all above mentioned steps should be finished to test the BAM mediator. In this step the user can send custom messages through the previously created WSDL Proxy Service and test whether they are correctly stored in the Cassandra database. This is only an example but the same type of steps can be followed to use the BAM mediator in the production environment.

  1. As the ESB pack was downloaded and started, downloaded and start the WSO2 BAM without the same port offset as ESB.
  2. In the ESB product directory go to $esb_home/samples/axis2Client
  3. Build the backend service with Apache Ant (You need to install Apache Ant before that.) with the following code.
    ant stockquote -Daddurl=https://localhost:8244/services/Simple_Stock_Quote_Service_Proxy -Dmode=fullquote -Dsymbol=testString

    (Here addurl value should be given from the https endpoint located in Simple_Stock_Quote_Service_Proxy's service dashboard that can be navigated by going to the ESB management console Main→Web Services→List from side panel and selecting Simple_Stock_Quote_Service_Proxy. Any preferred string can be used instead of the testString for symbol ) 


    Now BAM mediator in the proxy service, Simple_Stock_Quote_Service_Proxy should have dumped data extracted from the ESB to the key-space, EVENT_KS in the Cassandra database, with column family name same as the Stream Name. Data in the Cassandra database can be seen from the Cassandra Explorer in the BAM server.

  • No labels
Unknown macro: {next_previous_links2}

 
Copyright © WSO2 Inc. 2005-2014