This section includes the following topics:

JBot is a system developed by the Oracle Utilities Network Management System group for representing GUI forms as XML documents. Product versions of files are stored in ${NMS_BASE}/dist/baseconfig. Project versions are stored under ${NMS_CONFIG}/jconfig.

This document contains a description of the configuration needed for all Oracle Utilities Network Management System Java Tools. This includes configuration to:

 

This section contains a sample image of each Component, a description of the Component and the Component's name, which is used in the Component's XML tag.

Schemas describes the information required to create a valid XML file, what each element has as its child elements, their attributes, and any restrictions on them. The JBot schema has the following conventions:

JBot Tool XML files are based on the jbot.xsd schema, which has the following structure:

The GlobalProperties section defines properties that are used for tool specific configuration values. Global properties are often included by reference to a <toolname>_GLOBAL_PROPERTIES.inc file.

Typically defines what commands to run upon opening or closing the dialog.

Defines the GUI layout of the tool. Includes the following elements:

This section defines a command. If a command is used either by the tool or by a dialog called from the tool, it must be listed here.

This section defines paths for commands so that a command can be used without specifying the full path.

All datastores that are used by the tool or any dialogs called by this tool must be listed here. However, a tool is allowed to use a datastore defined by a different tool, as long as the other tool is loaded first. There are also some instances where a datastore can be defined in the code. This is mainly the case in the crew tools.

Dialogs in the list will be loaded on tool startup; dialogs that are not in the list will be loaded the first time they are called.

This section is no longer necessary. If an existing JBot configuration file has this section, it can be removed without a problem. If such a tag does exist, it is ignored.

use standard XML based xi:include tags. The included files are delivered to the client and they are combined by the application at runtime. This allows for specific XML code that is repeated to be defined once, but used in multiple places.

To define an include file, xmlns, xmlns:xsi, and xsi:schemaLocation must be defined.

For example given this XML fragment:

should be changed to:

The include files should be saved with an .xml extension.

To reference this file in another XML file, use the following syntax:

This allows the second XML document to use the XML code defined in the include file. The above example defines filters that will be used by multiple tools within Web Switching. Therefore, when filters need to be changed, they can be changed once and it will be applied to all tools that are using the include file.

the main limitation on xi:include tags is that they can only be used to insert a single element. While that approach works fine in the body of a JBot configuration, it doesn't work well for inserting tool properties, actions, or datastores.

In these cases, it is easier to use the build time based <Include> element. In this case the build process that creates the nms_config.jar file will perform the inclusions.

These include files should be saved without any extra attributes, and saved with an .inc extension.

To reference the file, use the following syntax:

JBot commands are operations performed as a result of an event. Some examples of events are button presses, table editing and row selecting. Commands are defined in a "Perform" tag. The actual options for the Perform tags vary with the component type.

Here is an example of configuring a command to be run when a menu is selected:

This will display the dialog DLG_EMERGENCY_CONTENT_SELECTION.

There are many JBot commands available. The HTML-based command reference is available at:

All commands accept the following <Config> parameters:

JBot actions allow you to define a list of commands that can be reused multiple times in a configuration. Defining a command directly on a component works well if there is only one place where the command is needed. However, if there are multiple places where the same commands are called, such as a menu item and a button, this provides a way to only define the action once.

Actions should be defined in the ToolBehavior or DialogBehavior tags.

Then to use this action, the ExecuteActionCommand command should be called:

The action is run just like another jbot command. Other commands or actions can also be defined before or after the action command, just like any other jbot command.

Actions can also call other actions, by using the ExecuteActionCommand from within another action.

It is also possible for actions to take parameters. For example:

This will replace the token $REPORT_NAME$ with the value PlannedSwitching. Any text in the configuration can be replaced this way. You cannot, however, replace the Command names themselves.

If you wish to use an Action defined in a different XML file there are two options. The first option is if you wish to run the action in the other tool. In that case, you can use the "runInTool" option, like other commands. However, if you wish to run the action in the current tool, even though it is defined in another tool, use the tool config option.

Various elements can have a when clause that indicates that the configuration should only be used if the when clause returns true. For example:

This will only be run if the status flag VIEWER_STUDY_MODE is true, and if the datastore value DS_FLM_GLOBAL.PF_IS_ON equals the text literal "true".

The following example will only show the component if the datastore value is not Y.

Note that the $ in front of the system is used to indicate the value is a string, if it has not been populated yet. Otherwise this would not return a true because a comparison with a null always returns false.

The validation toolkit provides a way of validating user data, as well as another way of coloring tables or other components. While most JBot commands work off of the underlying data, the validation toolkit works off of GUI widgets.

The Validation Testing Tool shows various examples what can be configured using the validation toolkit. The example is in:

To run this tool, add the following code to WorkspaceMenuBarTool.xml to create a menu item that will start the Validation Testing Tool:

In WorkspaceMenuBarTool_en_US.properties add:

 

Feel free to try various values in the form to understand how the validation toolkit can be used. The form is defined by Validation.xml. To use this form, find the section on the from that is like the validation you wish to perform, then look at Validation.xml to see the code needed.

The [toolname]_[language]_[locale].properties file contains all language related properties for the components. They are identified with the syntax:

 

When there is no locale, the tool tries these file names.

 

If there is a locale defined, the tools will try these file names.

Here are some reserved words that you may use in property files. It is recommended that when used, it should be placed at the top of the file.

 

Sample use of include is in MessageCode_en_US.properties file.

The include directive should be treated like a "replace or add" operation. Any property found in the current file that is also in the included file will be replaced by what is specified in the included file. In order to override settings in an included file, you need to add an additional property file with those overridden values or you can specify [base property name]_SELF to use the properties in the current property file. Specifying this "_SELF" option as the last included file will ensure that the settings in this file will always take precedence over any included property value.

This example demonstrates usage of include where we override some properties from the included property file.

SwmanTool_en_US.properites has many property settings including the following entry:

SwmanEmergencyTool_en_US.properties may have very few settings and may only have the following:

In this case, all of the properties in SwmanTool_en_US.properties will be included in the SwmanEmergencyTool_en_US.properties property file along with the one overridden property setting for TAB_STEPS.text. Since ordering matters when including properties, the properties in the current file (SwmanEmergencyTool_SELF) will override the properties from the previously included files.

If no properties need to be overridden, then the inclusion of include file [base property file name]_SELF or in the example above "SwmanEmergencyTool_SELF" is not required.

Layout values are based on Java's GridBagLayout component.

The fill value is a string. When set to BOTH, the component will fill its entire x,y coordinates. When set to NONE, the component will fit only the area that it needs to. For example, if a button is set to NONE, then the button will only fill around the text. To be even more specific, if two text letters are on a button, then it will be smaller than if there are six text letters on the button.

Fill can also be specified to be HORIZONTAL or VERTICAL for specific fill in one direction. Note that for labels, fill should generally be set to NONE. If it is not NONE, then attempts to right-justify the label by setting the anchor to "EAST" will fail.

Insets are given as four different values: top, bottom, left, and right. Each of these values will buffer a component from all other components. For example, if all of the values are 2, then the component will be two pixels on all four sides from the closest components.

The weight is given as x and y values. The x stands for horizontal and y stands for vertical. The weight indicates how much to stretch the component relative to the other components on the frame.

Labels can have their font defined by the optional <Font> tag under the <LabelBehavior> tag.

Oracle Utilities Network Management System code uses the Java Font.decode() method (see the Java Font class documentation for further information).

To ensure that this method returns the desired Font, format the name parameter in one of these ways:

in which style is one of the four case-insensitive strings: "PLAIN", "BOLD", "BOLDITALIC", or "ITALIC", and pointsize is a positive decimal integer representation of the point size. For example, if you want a font that is Arial, bold, with a point size of 18, you would call this method with: "Arial-BOLD-18".

If a style name field is not one of the valid style strings, it is interpreted as part of the font name, and the default style is used.

Only one of ' ' or '-' may be used to separate fields in the input. The identified separator is the one closest to the end of the string that separates a valid pointsize or a valid style name from the rest of the string. Null (empty) pointsize and style fields are treated as valid fields with the default value for that field.

Some font names may include the separator characters ' ' or '-'. If str is not formed with three components (e.g., style or pointsize fields are not present in str) and fontname contains the separator character, then these characters may be interpreted as separators. In this case, the font name may not be properly recognised.

The default size is 12 and the default style is PLAIN. If the name does not specify a valid size, the returned Font has a size of 12. If the name does not specify a valid style, the returned Font has a style of PLAIN. If you do not specify a valid font name in the name argument, this method will return a font with the family name "Dialog".

Labels can be defined as plain, bold, italic, or bold italic. This is done by the optional <Font> tag under the <LabelBehavior> tag.

This is an example of an italic label:

This is an example of a bold label:

This is an example of a label that is neither bold or italic:

This is an example of a label that is both bold and italic:

 

This section describes components that provide more intricate configuration options.

 

For other properties that can be modified, see the product version of theme.properties.

Tables, Tree Tables, Crew Icons, and Crews in the Viewer can be configured to respond to drag and drop. Using the same mechanism, copy and paste can also be supported.

To support Dragging from a component, a DragSource should be configured in the behavior tag. See this example from Workagenda.xml:

This enables dragging and copying. There are two defined "flavors." The EVENT means that it can be the source of a component has a DropPerform configured to EVENT. The "String:" defines a comma separated format that can be copied to the clipboard and saved to other applications, such as Microsoft Excel.

By default, all columns will be copied to the clipboard. If only a subset is required, they may be defined by listing them in the flavor:

Drag support can be enabled or disabled by adding a "when" attribute. For example:

DropPerform should be defined as part of the elements behavior element.

This example supports both dropping and pasting to component. It will accept any components with a DragSource flavor of CREW_KEY.

JBot dialogs are defined in xml files that start with DLG_. They have a similar configuration to JBot tools. One difference is that the dialogs use the datastores and jbot statuses of the tool they are attached to.

Here is an example of the start of a dialog configuration:

If a command or a list of commands needs to be run in response to a window action, such as a tool opening or closing, it can be defined using the <ToolBehavior> and <DialogBehavior> tags. These tags use a <Perform> subtag that takes a name and a category. The "name" attribute should be "Window" and the category name will be either windowOpened or windowClosing. windowOpened will allow the users to run code when the window opens for the first time. windowClosing will run when the users has requested that the tool close, but before the system actually closes the window (to allow the system to validate data, etc.). Other window events can also be caught. Please see the Java documentation for the WindowListener Interface for further information; the methods in that class can be used as the "category" attribute in this tag.

Here is an example on running a command when a tool opens:

Here is an example of a command running when a tool closes:

Setting component height and widths normally, the size of the tool, along with the weight and fill attributes determine the size of the components. However, sometimes it is necessary to have a component be a certain size. To do this, specify a component_width and component_height attributes in the behavior tag. For example:

JBot has a rather complicated way of defining text substitution and formatting of fields. Normally, a component refers to a column as it exists in a datastore. (For example, DS_TABLE.code refers to the column code in the datastore DS_TABLE.) This section has examples of most of the different combinations that can be done with calculated fields. For each example, the field name and a sample output is given. The output uses the following datastore as its source:

 

Calculated fields are indicated by preceding the field with a #. The format is:

The format definition is based on the java.text.MessageFormat class. (Please refer to the official Java documentation for more information on the MessageFormat class.)

Concatenating two fields together with a comma separating them:

Concatenating two or more fields together with a space separating them:

Replacing a field’s value with another value:

 

Replacing a field’s value with a value from a property file:

 

In addition, five custom date formats are available to configure in the Global_en_US.properties file.

This allows for the definition of additional date/time formats. For example, displaying time with milliseconds precision:

Format: Date%{0,date,subformat1}

Value: 01/02/08 12:33:44.123

To define coloring rules, it is sometimes helpful to return a value if a value matches anywhere in a column. This can be done with the MatchSubstringFormat. The following example will return "Out" if "Out" appears anywhere in the string, or an empty string if it does not contain it.

It is possible to use regular expressions to parse data. For example, to create a column that displays the area code of a phone number (where the phone # is in the format ###-###-####), the following can be used:

If you have a task that could be done with either MatchSubstringFormat or MatcherFormat, it is best to use MatcherFormat as it is more efficient.

 

You can use the ApplyFilterCommand to predefine filters on any JTable or DataStore.

For example, the following filters the TBL_COMMENTS to only show rows where the "messages" field = "Y":

The following creates a filter named "ANALOG_QUALITY_ALARMS" using the DS_NMS_ALARMS where the ddsEventType=3, isAlarm=true, and source!=4. This filter named "ANALOG_QUALITY_ALARMS" can then be referenced in other commands, such as ConfigureAudiblesCommand:

You can also use the <Filter> and <FilterItem> elements to define a filter that you use in a Filter menu.

For example, this creates a filter where the row value "eventTypeAndAlarm" is equal to "1:true", "1:false", etc. and the "source" field is not "FLISR", "FLM", or "OPT":

See the command documentation for ApplyFilterCommand and ConfigureAudiblesCommand for more details and available options.

To add a docking container to an existing tool, use the following:

To specify a docking location of a tool, use the "dock" attribute of the <JBotTool> element:

You can use: NORTH, SOUTH, EAST, WEST, or CENTER

In order to dock a tool in this way, the tool should already be visible.

To aid the implementer in determining the available columns for a datastore, it is possible to create a report that contains all the current values of a datastore for a running system. Because each system can have different configured columns, it is necessary to create this documentation from a running system.

The report contains all the datastores that are currently valid for the application, along with all of the valid columns.

See the following excerpt from the report, which describes the DS_WA_ALARMS datastore from Work Agenda.

 

Note that some of the columns listed are objects that would never be printed. For example, see the excerpt below:

The crew.zone_hdl is an object that would not be displayed. That object contains the class_number, instance_number, and app, which can be displayed.