Customizing Applications

Applications may be extended by providing custom commands, which may then be configured as part of the application. Additionally, NMS commands may be called from an external systems.

This section contains the following topics:

• Customization Examples using the Demo Tool

• Creating Custom Functions for Displaying Data

• Using Additional Libraries

• Invoking Commands from an External System

• Invoking Commands Using a Web Service

Customization Examples using the Demo Tool

Introduction

Prerequisites

This assumes the user is familiar with programming in Java and with Oracle Utilities Network Management System configuration.

The demo commands and tool are included as part of the OPAL configuration. Therefore, this documentation assumes that either the OPAL model is used or all the demo tools and configuration are copied to the correct project directory.

Setup

To run these examples, the following should be added to WorkspaceMenuBarTool. This will add a button to Web Workspace to display the demo tool:

</Command>

</PressPerform>

</MenuItem>

Using the Demo Tool

The Demo Tool provides examples for various text fields, a table, and buttons that demonstrate how to integrate a custom application into an Oracle Utilities Network Management System.

• The Hello World example displays a dialog.

• The AddCommand example adds two numbers and saves them in a third field.

• The IncrementCommand example shows how to access and change data.

• The DemoFocusCommand example shows how to call existing JBot commands.

The example code is in $NMS_CONFIG/jconfig/java/src. This is where any custom commands should be saved.

Access to data in Oracle Utilities Network Management System is saved in datastores, which are bound to the actual java swing components.

The demo tool is saved to $NMS_CONFIG/jconfig/ops/test/xml/DemoTool.xml.

Using the Demo Tool Sample Code

Hello World

The Hello World example code provides a simple command to display a dialog box displaying text:

See $NMS_CONFIG/jconfig/java/src/demo/HelloWorldCommand.java:

package demo;

import com.splwg.oms.jbot.JBotCommand;

import javax.swing.JOptionPane;

public class HelloWorldCommand extends JBotCommand {

public void execute() {

JOptionPane.showMessageDialog(null, "Hello World!");

}

AddCommand

The AddCommand example provides a command that reads two values from the system and saves the sum to a third value.

package demo;

import com.splwg.oms.jbot.JBotCommand;

import java.awt.AWTEvent;

import java.awt.Component;

import javax.swing.JOptionPane;

/**

* This command adds two numbers

public class AddCommand extends JBotCommand {

public void execute() {

// This parameter must exist or else an error will occur

String var1 = getRequiredParameter("var1");

// If this parameter does not exist, the value will be null

String var2 = getParameter("var2");

String result = getRequiredParameter("result");

double retVal;

try {

String number1 = (String)getDataSourceValue(var1);

retVal = Double.parseDouble(number1);

if (var2 != null) {

String number2 = (String)getDataSourceValue(var2);

retVal += Double.parseDouble(number2);

}

setDataSourceValue(result, retVal);

} catch (Exception e) {

AWTEvent awtEvent = (AWTEvent)getJBotEvent().getEvent();

Component component = (Component)awtEvent.getSource();

JOptionPane.showMessageDialog(component,

"Could not add the numbers", "Error",

JOptionPane.ERROR_MESSAGE);

setAbort(true);

}

IncrementCommand

The IncrementCommand example shows how to read and write to multiple rows in a datastore:

package demo;

import com.splwg.oms.jbot.IDataRow;

import com.splwg.oms.jbot.IDataStore;

import com.splwg.oms.jbot.JBotCommand;

import java.awt.AWTEvent;

import java.awt.Component;

import javax.swing.JOptionPane;

/**

* This example show how to access and update a datastore that

* has multiple rows.

public class IncrementCommand extends JBotCommand {

public void execute() {

IDataStore ds = getDataStore("DS_DEMO_TABLE");

synchronized(ds.getLockObject()) {

for (IDataRow row : ds) {

Integer count = (Integer) row.getValue("count");

row.setValue("count", Integer.valueOf(count + 1)); }

}

ds.notifyObservers();

}

DemoFocusCommand

The DemoFocusCommand is an example on how to call existing JBot commands from within a custom JBot command. The example can be used to focus on a device in the viewer:

package demo;

import com.splwg.oms.client.viewer.FocusOnHandleCommand;

import com.splwg.oms.jbot.JBotCommand;

import com.splwg.oms.jbot.JBotException;

import java.util.HashMap;

/**

* This is an example of calling an existing JBot command. It will

* focus on a device with a given handle, given a datastore

* values of the class and index of the device handle.

public class DemoFocusCommand extends JBotCommand {

public void execute() {

String dataSource = getRequiredParameter("handle");

String handleStr = getDataSourceValue(dataSource).toString();

int pos = handleStr.indexOf(".");

if (pos == 0) {

throw new JBotException("Invalid handle");

}

String handleCls = handleStr.substring(0, pos);

String handleIdx = handleStr.substring(pos+1);

HashMap map = new HashMap();

map.put("handle_cls", handleCls);

map.put("handle_idx", handleIdx);

// the options to this are the command name, a map of parameters

// (or null if it doesn't take parameters, and the source for this

// command (which can normally be left as null)

getEnv().getTool().getAdapter()

.runCommand(FocusOnHandleCommand.class.getName(), map, null);

}

Creating Custom Functions for Displaying Data

There are times when you want to display data that integrates information from another system, or format data in a way that calculated fields do not have the flexibility to display. In this case, calculated functions can be used.

The following is an example of calling a custom function:

Normally, items to the left of the % are the list of columns. Custom functions take those columns and perform an operation on them. For example, the above call reverses the characters in the first column listed.

Function ReverseFormat Source

package demo;

import com.splwg.oms.jbot.CustomFormat;

public class ReverseFormat extends CustomFormat {

public Object[] format(Object[] source) {

String input = (String)source[0];

char[] chars = new char[input.length()];

for (int i=0; i < chars.length; i++) {

chars[chars.length - 1 - i] = input.charAt(i);

}

source[0] = new String(chars);

return source;

}

Custom Formats

NMS provides the following custom formats:

• MatcherFormat: Uses regular expressions to parse a string.

• MatchSubstringFormat: Returns a string if it contains a certian string, otherwise returns an empty value.

• UserLookupFormat: Returns the full username for a given userid.

• MultiplyFormat: allows you to add column multipliers to any DataStore that includes numbers.

See CustomFormat in the Javadocs for further information.

Using Additional Libraries

If additional client libraries are needed, they should be saved to $NMS_CONFIG/java/lib. Any jar files in this directory will be unjarred, and included as part of nms_config.jar.

Invoking Commands from an External System

Commands can be invoked by sending high level messages, either by using the "Action" command or by using a web service. (It is recommended that the web service be used for production use).

A listener for a high level message is defined as follows:

</Perform>

This should be defined in the ToolBehavior portion of the tool you wish to integrate with.

The type is an arbitrary identifier of the action.

This can be invoked by running the following from the Oracle Utilities Network Management System server:

Action -java USER.* DISPLAY_MESSAGE '"Hello World"'

USER should be replaced with the user name of the nms user.

This configuration calls the following command:

package demo;

import com.splwg.oms.jbot.HLMEvent;

import com.splwg.oms.jbot.JBotCommand;

import java.util.List;

import javax.swing.JOptionPane;

/**

* This displays a message to the user from an external system

public class DisplayMessageCommand extends JBotCommand {

public void execute() {

HLMEvent hlmEvent = (HLMEvent) getEvent();

List<String> args = hlmEvent.getMessage().getArgs();

String message = args.get(0);

JOptionPane.showMessageDialog(null, message);

}

Invoking Commands Using a Web Service

This should be invoked by using the sendHLM web service message.

The wsdl for the web service is located as follows:

• For WebLogic:

http://nms-server:7001/MessageBean/MessageBeanService?wsdl

(Replace nms-server with the dns name or IP address of the Oracle Utilities Network Management System system to connect to.)

Elements of the sendHLM Message

• String_1: username (used to determine destination environment)

• HLMessage_2/from: sender

Note: the sender must be a valid user in the WebLogic security realm with the NmsService role.

• HLMessage_2/message: command

• HLMessage_2/to: destination tool

• HLMessage_2/windowName: not used

• boolean_3: synchronous message flag (if true, then web service call will return only after the message has been delivered).

The following command, which delivers the message 'DISPLAY_MESSAGE "Hello world"' to the tool 'demo' running in the environment of user 'user',

Action -java user.demo DISPLAY_MESSAGE "Hello world"

corresponds to the following web service message

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://oms.splwg.com/ws/message">

<soapenv:Header/>

<soapenv:Body>

<mes:sendHLM>

<String_1>user</String_1>

<HLMessage_2>

<message>DISPLAY_MESSAGE "Hello world"</message>

</HLMessage_2>

<boolean_3>true</boolean_3>

</mes:sendHLM>

</soapenv:Body>

</soapenv:Envelope>

Communicating with Other Programs Using Named Pipes

Clients can communicate with other applications running on the local box by using named pipes. This can be used to communicate with a SCADA application, for example. The pipes have to be set up by the other application. See the commands ReadPipeCommand, WritePipeCommand, and ActionFromHLMCommand for details.