Developing and deploying a custom Java probe in BI Platform 4.0: Tutorial & Sample

[Toby_Johnston]

In this SCN document I'll demonstrate how to develop your own custom Java probe and successfully register it with your SAP Business Intelligence Platform 4.0.  Included in this tutorial is a basic sample which you can use as a starting point for your own custom probe development.  The sample in this tutorial takes as input parameters a host name and port number of a web server.  Upon execution the probe will attempt to make a socket connection to the host on the specific port and if successful the probe will return a success (in the language of BI4 watches, this is represented as a value of 1).  If the socket connection fails, the probe will return a failure (a value of 0).

Considerations before you get started

• For large productive landscapes it's recommended that you upgrade your BI Platform to SP4 Patch 12, SP6 Patch 1, or SP7.  Several corrections were made to improve stability and performance of the Monitoring Service (Adaptive Processing Server).  See note 1833881.
• Create a dedicated Adaptive Processing Server to run your Monitoring Services.  Best practice is to run no more than two dedicated Monitoring Services (two APS instances) as they work in a Active/Passive cluster.  For details on creating a dedicated Adaptive Processing Server, refer to Best Practices for SAPBO BI 4.0 Adaptive Processing Servers
• If you plan to keep historical details about the success or failure of your custom probe, you will need to enable the trending database.  For details, see the BI Platform 4.0 Administrator's Guide.

Health Probe, Diagnostic Probe, or Hybrid Probe

It is important to understand the different types of probes that can be created as they each have different requirements and serve a slightly different function.  Additionally, when you are ready to register your probe with BI Platform 4.0, you will need to define the type of probe so that the monitoring service will understand how to execute the probe.

• A health probe generates metrics of data types such as integer, Boolean, or string.  An example of a health probe is the default CMS Logon/Logoff probe which checks that a user may successfully logon/logoff the Central Management Server.
• A diagnostic probe generates reports containing current system information.  An example of a diagnostic probes is the default Stop/Start server probe. This probe checks all the servers, records the state of each server, restarts the servers and collects information about servers again.
• A hybrid probe functions as both a health probe and a diagnostic probe

The Web Server probe example in this tutorial will be defined as a health probe since it is not collecting any specific information.  Instead it is checking the availability of a Web Server listening port and returning success or failure.  In the included sample code, all the interfaces you will need to create a diagnostic or hybrid code is already imported (even though they are not all used).

Source code walk-through

In this section, I will break each piece of this example program into logical chunks and describe it's purpose.  You can download the complete source file which is attached to this document.  For reference purposes, download the BI Platform 4.0 Java API (Java Docs).

Step #1 -  Define your Java class as belonging to the package com.businessobjects.monitoring.probe.  Later, we will add our compiled class file to the existing package of BI 4.0 probes.

package com.businessobjects.monitoring.probe;

Step #2 -  Import the required SDK libraries for a BI 4.0 probe (and also the classes needed to test the Web Server port availability)

import java.util.Locale;
import java.util.Map;
import java.net.Socket;

import com.businessobjects.sdk.monitoring.plugin.desktop.probe.IProbeInfoObject;
import com.businessobjects.sdk.monitoring.probe.AbstractProbe;
import com.businessobjects.sdk.monitoring.probe.DiagnosticProbeResult;
import com.businessobjects.sdk.monitoring.probe.HealthProbeResult;
import com.businessobjects.sdk.monitoring.probe.IDiagnosticProbe;
import com.businessobjects.sdk.monitoring.probe.IDiagnosticProbeResult;
import com.businessobjects.sdk.monitoring.probe.IHealthProbe;
import com.businessobjects.sdk.monitoring.probe.IHealthProbeResult;
import com.businessobjects.sdk.monitoring.probe.common.ProbeLocHandler;
import com.businessobjects.sdk.monitoring.probe.common.ProbeLocKeys;
import com.crystaldecisions.sdk.exception.SDKException;
import com.crystaldecisions.sdk.exception.ServerExceptionCode;
import com.crystaldecisions.sdk.framework.IEnterpriseSession;
import com.crystaldecisions.sdk.occa.infostore.IInfoObjects;
import com.crystaldecisions.sdk.occa.infostore.IInfoStore;
import com.crystaldecisions.sdk.occa.infostore.internal.InfoStoreFactory;
import com.crystaldecisions.sdk.occa.security.internal.ISecuritySession;

Step #3 -  Your class must be a subclass of AbstractProbe and it must also implement the IHealthProbe interface so that it will inherit the required methods and objects needed for a probe

public class probeHTTP extends AbstractProbe implements IHealthProbe

{

Step #4 -  Initialize a new IProbeInfoObject and invoke the constructors of IProbeInfoObject.  You will need this object to get access to the input parameters later.

public IProbeInfoObject probeObject = null;

public probeHTTP(IProbeInfoObject probeInfoObject)
{
    super(probeInfoObject);
    probeObject = probeInfoObject;
}

Step #5 -  You must create an executeHealthProbe method which returns IHealthProbeResult for a health probe.  For a diagnostic probe, it must return IDiagnosticProbeResult.  Notice that when the probe is executed, the Enterprise session is passed in by the Probe Scheduling Service (Adaptive Job Server).  You can use this Enterprise session to access the CMS Infostore so that you can perform actions on the BI Platform (such as query the CMS repository for metrics, start servers, change settings, etc).

public IHealthProbeResult executeHealthProbe(IEnterpriseSession session)

{

    HealthProbeResult probeResult = new HealthProbeResult(getProbeInfoObject());

    Socket socket = null;

    boolean available = false;

Step #6 -  To parameterize your probe you need to create a new java.util.Map object. Call getInputParameters( ) to create a map of the probe parameters that have been selected by the administrator in the Central Management Console (see Step #4).  In this example, there are two parameters (Web Server Host Name, Port Number)

Map<String,Object> inputParams = null;

try

{
     inputParams = probeObject.getInputParameters();
}
catch(Exception e)
{
     System.err.println(e);
     e.printStackTrace();
}

String hostname = (String) inputParams.get("hostname");

String portnum = (String) inputParams.get("portnum");
int portnumint = Integer.parseInt(portnum);

Step #7 -  This example attempts to create a connection to the specified host and port number.  If it succeeds, our probe executes probeSucceeded( ).  If it fails, an exception is thrown and the probe executes probeFailed( ).  The probeResult specifies to the Probe Scheduling Service if the health probe itself was a success or failure.

try

{

                       //String, int

   socket = new Socket(hostname, portnumint);

   probeResult.probeSucceeded();

}

catch (Exception e)

{

   probeResult.probeFailed();

}

return probeResult;

Compile and register your probe

1. Add the required jar files to your CLASSPATH.  I have attached my CLASSPATH to this document as an example (classpath.txt).  The BI 4.0 Java SDK libraries are located in the directory <BOBJ_HOME>\SAP BusinessObjects Enterprise XI 4.0\java\lib.
2. Compile your Java class and export it from Eclipse as a jar file.
3. Create a folder named probes in the directory <BOBJHOME>\SAP BusinessObjects Enterprise XI 4.0\java\lib.
4. Add your custom jar and it's dependencies to the new probe directory.
5. Restart the Monitoring Service (Adaptive Processing Server) and Probe Scheduling Service (Adaptive Job Server)
6. Repeat steps 3,4, and 5 for each node running the Monitoring Service and Probe Scheduling Service
7. Register your custom probe as per the BI4 Java SDK Developer's Guide or via the Central Management Console > Monitoring Application.
8. During registration, specify the class name including the package name as com.businessobjects.monitoring.probe.yourClassName.
9. Configure the input parameters to match the name and data type as defined in the java.util.Map in your source code.
10. For an example, refer to Image A

Image A

Schedule the custom probe

1. In the Central Management Console browse to Monitoring > Probe tab and locate your new probe.
2. Right click on the probe and choose properties then check your input parameters (Image B)
3. Schedule the probe to Run Now and see the results (Image C and Image D)

Image B

Image C

Image D