Managing Event Publishing with WSO2 Data Analytics Server

This sections explains how to configure WSO2 Data Analytics Server (WSO2 DAS) with WSO2 EMM in a production environment, to publish events. Follow the steps given below:

1. Port offset WSO2 DAS by 1 and start the server. There are two ways to set an offset to a port:

   • Pass the port offset to the server during startup. The following command starts the server with the default port incremented by 1.

     ./wso2server.sh -DportOffset=1

   • Set the Ports section of the <EMM_HOME>/repository/conf/carbon.xml file as follows: <Offset>1</Offset>
     Once you have port offset start WSO2 DAS using the following command.

     ./wso2server.sh

2. Configure the device-analytics-config.xml file that is in the <EMM_HOME>/repository/conf/etc directory.

   • Enable the settings by assigning true as the value within the <Enabled> tag.

   • ReceiverServerURL: The URL must be in the protocol://hostname:port format. Since you port offset WSO2 DAS, make sure to update the port accordingly.
     Example: tcp://localhost:7611 if you have not port offset and tcp://localhost:7611+n if you have port offset by n.

   • AdminUsername: Provide the administrator username. The default username is admin.
   • AdminPassword: Provide the password of the administrator. The default password is admin.

   Example: Single receiver

   <AnalyticsConfiguration>
      <Enabled>true</Enabled>
      <ReceiverServerUrl>tcp://localhost:7612</ReceiverServerUrl>
      <AdminUsername>admin</AdminUsername>
      <AdminPassword>admin</AdminPassword>
   </AnalyticsConfiguration>

3. Configure the <EMM_HOME>/repository/conf/analytics/analytics-data-config.xml file to specify the data service access mode and the URL.

   • There are three data service access modes, such as LOCAL, REMOTE and AUTO. WSO2 EMM only supports the REMOTE mode.

     In the REMOTE mode the Analytics API only accesses the Analytics Data Services OSGI service in a remote instance. This mode is suitable when the node is a lightweight node and does not contain an Analytics Data Services OSGi service. Fore more information on the configurations that need to take place after the node is set, see WSO2 DAS documentation on configuring the connection related parameters.

   • Provide the URL of WSO2 DAS after it was port offset.

   Example:

   <AnalyticsDataConfiguration>
       <!--Mode can be either as LOCAL, REMOTE or AUTO. If LOCAL mode is configured the analytics api will lookup -->
       <!--necessary services within the the same node, and will invoke then directly without going through network.-->
       <!--But If the current node is a light weight node, and doesn't have analytics data services, -->
       <!--then the mode should be configured as REMOTE. If AUTO mode is configured, based on the data service availability
       it will automatically switch the mode with LOCAL and REMOTE -->
       <Mode>REMOTE</Mode>
       <!--Note: The following parameters will be used only when the mode is configured to REMOTE.-->
       <!--The URL of the analytics data service is being hosted-->
       <URL>http://10.10.10.189:9764</URL>
   </AnalyticsDataConfiguration> 

4. Creating an event stream and receiver.

    Click here for more information on creating an event stream and receiver.

   The following subsections will guide you to create a new event stream and receiver in WSO2 DAS.

   • Creating a new event stream
   • Creating a new event receiver

   Creating a new event stream

   Follow the steps given below to create a new event stream:

   1. Login to the Management console of WSO2 DAS: https://<DAS_HOST>:<DAS_PORT>/carbon/  
   2. Click Streams that is under Events in the Main tab.
   3. Click Add Event Stream.
      

   4. Enter the required details to create an event stream.

      • Define the Event Stream Name as android_agent.

      • Add the following attributes.

        Attribute	Type
        deviceIdentifier	String
        payload	String
        type	String

      Example:
      
   5. Click Next [Persist Event].
   6. Persisting the event.
      1. Select Persist Event Stream.
      2. Select Persist Attribute filed to persist all the attributes and select the Index Column of each attribute.
      3. Click Save Event Stream.
      
   7. Click OK on the confirm message indicating that the event stream was created successfully. 
      You can view it in the Available Event Streams list as shown below.
      

   Creating a new event receiver

   You can create a new event stream using any of the methods given below:

   • Creating an event receiver via the WSO2 DAS management console
   • Creating an event receiver via the WSO2 DAS configuration files

   Creating an event receiver via the WSO2 DAS management console

   Follow the steps given below:

   1. Login to the Management console of WSO2 DAS: https://<DAS_HOST>:<DAS_PORT>/carbon/
   2. Click Receivers that is under Events in the Main tab.

   3. Click Add Event Receiver. 
      

   4. Enter the required details and click Add Event Receiver.

      • Enter a name for Event Receiver Name. (Do not use spaces between the words in the name of the event receiver.)

      • Select the input transport from which you want to receive events for the Input Event Adapter Type, and enter the Adapter Properties accordingly. In this scenario select wso2event. 

      • Select the android_agent for the Event Stream.

        Example:
        

   5. Click OK on the confirm message indicating that the event receiver was created successfully. 
      You can view it in the Available Event Receivers list as shown below.
       

   Creating an event receiver via the WSO2 DAS configuration files

   Follow the steps below to create an event receiver using a configuration file.

   1. Create an XML file with the following event receiver configurations. An event receiver implementation must start with <eventReceiver> as the root element.

      <eventReceiver name="EVENT-RECEIVER-NAME" statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventreceiver">
          <from eventAdapterType="EVENT-ADAPTER-TYPE">
             .................................
          </from>
          <mapping customMapping="disable" type="xml"/>
          <to streamName="Test Stream" version="1.0.0"/>
      </eventReceiver>

      The properties of the above configuration are described below:

      Adapter property	Description
      name	Name of the event receiver.
      statistics	Define if the monitoring event statistics is enabled for the receiver.
      trace	Define if tracing events are enabled for the receiver.
      xmlns	XML namespace for event receivers.
      eventAdapterType	Type of the event adapter.
      customMapping	Define if a custom mapping is enabled on the receiver.
      type	Type of the enabled custom mapping.
      streamName	Name of the event stream to which the receiver is mapped.

   2. Create a new eventreceivers file in the <EMM_HOME>/repository/deployment/server directory, and save the XML file in it. Since hot deployment is supported in the product, you can simply add/remove event receiver configuration files to deploy/undeploy event receivers to/from the server.

   First define the stream to which the receiver is publishing data to activate the receiver. When receiving WSO2Events, the incoming stream definition that you select in the advanced input mappings must also be defined, to activate the event receiver. When you click Inactive Event Receivers in the Available Event Receivers screen, if an event receiver is in the inactive state due to some issue in the configurations, you view a short message specifying the reason why the event receiver is inactive as shown below. A similar message is also printed on the CLI.