Using Dashboard Builder

Dashboard Builder layout

This section describes each of the panels available in the Dashboard Builder and how to use them effectively.

The menubar

Menu	Command	Description
File		Operations for opening, saving, and closing dashboards.
New	Create a new dashboard.
Open	Open an existing dashboard file by browsing.
Save	Save the dashboard file.
Save As	Save the dashboard to a specific file, possibly different to where it has been saved before.
Background Properties	Display the Background Properties dialog for setting the size and background color or image for the dashboard.
Print	Print the current contents of the dashboard.
Exit	Exit Dashboard Builder.
Edit		Operations for editing and manipulating dashboard objects
Add	Displays the Object Palette if not currently displayed.
Object Properties	Displays the Object Properties panel if not currently displayed.
Undo	Un-does the last Builder operation (that has not been undone already).
Redo	Re-does the last undone operation (that has not yet been re-done).
Copy	Copy the currently selected object into the copy buffer.
Paste	Paste the object in the copy buffer onto the dashboard.
Paste Data Attachments	Paste the data attachments of the object in the copy buffer onto the selected object. Only properties common to both objects will be pasted onto the selected object.
Paste Static Properties	Paste static properties only; do not include those properties that are attached to data.
Paste All Properties	Paste all properties, that is, those that are attached to data as well as static properties.
Align	Align the specified feature of the currently selected objects. For example, Align | Top aligns the tops of all currently selected objects with one another. The object that was selected first among all the currently selected objects does not move; all other objects are aligned with the first-selected object. Top, Bottom, and Center Horizontal arrange the objects horizontally, one next to the other. Left, Right, and Center Vertical arrange the objects vertically, one above the other.
Distribute	Distribute the currently selected objects so that they are spaced evenly, either horizontally or vertically, between the first-selected object and the last-selected one. The first and last objects do not move.
Order	Move the selected object in back of or in front of all other dashboard objects.
Select All	Select all objects on the current dashboard.
Delete	Delete the selected object.
View		Operations for zooming in and out on the dashboard.
	Zoom In	Zoom in on a location in the dashboard. This will switch the pointer to zoom mode as indicated by the pointer changing to a crosshair . In this mode you can click an area of the dashboard to zoom in on it; displaying it in greater detail. Right-click to exit zoom mode.
Zoom Out	Zoom out on a location in the dashboard. This will switch the pointer to zoom mode as indicated by the pointer changing to a crosshair . In this mode you can click an area of the dashboard to zoom out on it; displaying it in lesser detail. Right-click to exit zoom mode.
Zoom Rect	Zoom in on an area in the dashboard. This will switch the pointer to zoom mode as indicated by the pointer changing to a crosshair . In this mode you can click and drag to select an area of the dashboard to zoom in on. Right click to exit zoom mode.
Pan	Pan the dashboard to show areas not currently displayed. This will switch the pointer to zoom mode as indicated by the pointer changing to the pan pointer. In this mode you can click and drag the dashboard to reveal areas not displayed. Right-click to exit pan mode. It is not possible to pan if 100% of the dashboard is visible.
100%	Make the entire dashboard visible.
Tools		Operations for defining dashboard options and changing preferences.
Options…	Displays the Application Options dialog for defining data sources and setting other runtime options for deployed dashboards.
Builder Options…	Displays the Builder Options dialog for setting Dashboard Builder, such as grid characteristics. When snap-to-grid is enabled, object can be positioned only along grid lines, which facilitates object alignment and distribution.
Functions	Displays the Functions panel for defining dashboard functions.
Variables	Displays the Variables panel for defining dashboard variables.
Include Files	Displays the Include Files dialog for including dashboard files in the current dashboard.
Object List	Displays the Object List panel, which lists the name, class name, and position of each object on the current dashboard.
Preview Window	Preview the current dashboard, so you can test interactive functionality such text entry. Save your changes to enable this item.
Pause Display	Pause the automatic update of the dashboard. When not paused, the dashboard automatically updates as data changes; when paused, the dashboard does not. When paused, clicking on the dashboard causes it to update.
Reset Window Layout	Reset window size and panels to their default configuration.
Help		Information about Apama and Dashboard Builder.
Help Contents	Opens the Apama documentation to the Introduction in Building Dashboard Clients.
Command Line Options	Displays a list of the Builder options that you can supply at the command line.
About	Displays information about this version of the Dashboard Builder.

The toolbar

The toolbar contains a number of icons that correspond to commonly used operations. Note that all the operations accessible from the toolbar are also available on the menu bar. The operations are:

Button	Description
	Create a new dashboard file.
	Open an existing dashboard file.
	Save the current dashboard file.
	Preview the current dashboard. Save your changes to enable this tool.
	Copy the selected object to the copy buffer.
	Paste the object in the copy buffer onto the dashboard.
	Paste the data attachment properties.
	Paste the static properties.
	Paste all properties.
	Delete.
	Undo.
	Redo.
	Show or hide grid.
	Enable or disable snap to grid.
	Select by extent.
	Zoom in on the dashboard.
	Zoom out on the dashboard.
	Display the Object Palette.
	Display the Object Properties panel.
	Display the Application Options dialog.

The canvas

The canvas is where you lay out the objects for a dashboard. Objects can be added to the canvas, moved, and resized. As objects are attached to data sources, the objects will update in real time to reflect changes in the data. This allows you to see how the objects will appear when the dashboard is deployed.

The Object Palette

The Object Palette presents all object types that may be added to a dashboard. It is organized into separate tabs for different categories of objects.

The Object Properties panel

The Object Properties panel displays the properties and their values for the selected object on the canvas. If no object is selected, the properties panel is empty. The set of properties displayed depends on the type of object selected.

The type of object is identified following the Object Class Name label at the top of the properties panel; in this case the type is obj_text01.

To edit a property, click the property value. Some properties allow you to type in a value, some provide a drop down list of choices, and some present a “…” button for displaying a dialog for setting the property value.

Right-click a property name to display a menu for the property, for example:

Property values can be copied and pasted onto other properties. Properties can also be attached to data sources as detailed in subsequent chapters.

Properties are color coded as follows:

• Blue indicates a static property that cannot be attached to data.
• Green indicates a property that has been attached to data.
• Black indicates a property that may be attached to data.

Specifying data sources

Dashboard Builder supports building dashboards that display data for DataViews in a correlator as well as data from a properly formatted XML file.

To use a correlator or an XML file, you need to make it a known data source to the Dashboard Builder. The topics below detail how to define data sources in the Builder.

See also Using SQL data for information on JDBC data sources.

Specifying correlators

You must specify the correlator in which the scenario is running before you create a dashboard.

To create a dashboard for a scenario in the Dashboard Builder

1. From the Tools menu select Options.

2. In the tab list on the left of Applications Options dialog select Apama.

   The Correlator subtab displays the correlators known to the Builder. Initially only the default correlator for the localhost will be known. For each correlator the following fields are specified

   • Logical name – The name that will be used to refer to the correlator. This name cannot be changed once a correlator has been added.

   • Host – The host of the correlator.

     Info

     Non-ASCII characters are not allowed in host names.

   • Port – The port of the correlator.

   • Raw channel – Option to use the raw channel for communication with the correlator. By default the data channel is used.

3. Select the entry for localhost and click the Edit button.

   The Correlator Properties dialog allows you to specify the properties of a correlator.

4. Click Cancel to close the Correlator Properties dialog.

   If you are using the tutorial dashboard, do not change the properties of the default correlator unless you have loaded the tutorial DataView in a correlator running on a different host or on a different port.

5. Use the Add button to add a new correlator and the Delete button to delete the selected correlator.

Specifying XML data sources

Dashboard Builder enables you to augment your dashboard by using XML data files as a data source in addition to Apama DataView. The properties of dashboard objects can be attached to data elements in XML files. See Using XML data, for details on using XML data sources.

Activating data source specifications

To activate data source specifications

• In the Application Options dialog, click the OK or Apply to make any changes active for the current invocation of the Builder. This does not save them for future invocations.

Saving data source specifications

To save data source specifications

• Click the Save button to save options settings including data source definitions as detailed in section Saving options.

Setting the background properties

Background properties control the size, color, and an optional background image for a dashboard.

To set background properties

1. Select Background Properties from the File menu in the menu bar.

   The Background Properties dialog appears.

2. Set the fields Model Width and Model Height to specify the size of the dashboard. If the dashboard is made smaller than its current size, and the resize mode is crop (see below), one or more objects may no longer be visible.

3. Click on Model Properties.

   The Object Properties panel displays additional properties for the dashboard background.

   Use resizeHeightMin and resizeWidthMin to set the minimum display size. For web-based dashboards, scrollbars are present when the size is below the minimum. In Viewer, dashboards cannot be resized below the minimum.

4. To use an image as the background for a dashboard, check the Use Background Image check box, and either type in the relative path name to a .gif, .jpg, or .png image file or select an image file from the Image Name drop down list.

   The drop down list includes Image files that are located either in the same directory as the dashboard or in a subdirectory of the dashboard’s directory.

   Info

   If an image is used as the background for a dashboard, the dashboard is resized to the dimensions of the image, and the Model Width and Model Height fields are disabled.

5. To set a non-default resize mode, select an item from the Resize Mode drop down list. Resize modes are explained in About resize modes.

6. To set a non-default number of grid rows (which is used in Layout resize mode when an object’s dock property is set to Fill), enter a value greater than 1 in the Dock Fill Rows field. See About resize modes for detailed information.

7. To set a non-default number of grid columns (which is used in Layout mode when an object’s dock property is set to Fill), enter a value greater than 0 in the Dock Fill Columns field. See About resize modes for detailed information.

About resize modes

The Dashboard facility supports three window resize modes:

• Layout: When a window in this mode is resized, the display is resized to fit the available space. The objects in the display are laid out according to their anchor and dock properties (see below). The window is not forced to maintain its aspect ratio. Objects that are not docked or anchored move relative to their offset from the top left corner of the display. For example, if the object is centered on the display, the object moves 50% of the resize amount. If the object is centered at 3/4 of the display, it moves 75% of the resize amount.
• Scale: This is the default for the Dashboard Builder and Dashboard Viewer, as well as for all web-deployed dashboards. When a window in this mode is resized, the display and all of the objects in it are scaled to fit the available space. The window is forced to maintain its aspect ratio.
• Crop: This is the default for display server deployments. When a window in this mode is resized, the display stays the same size. If the window is bigger than the display, empty space appears around the display. If the window is smaller than the display, scrollbars appear. The window is not forced to maintain its aspect ratio.

All three resize modes support zooming the display (right-click and select Zoom In, Zoom Out, or Zoom Rect). In both Layout and Scale modes, if the window is resized while the display is zoomed, the resize further zooms the display.

In the Dashboard Builder, the window resize modes are only applied to drill down windows. The main window of the Dashboard Builder is always in crop mode.

You can set the window resize mode for each dashboard in the Background Properties dialog. If set to Default, the application level resize mode (see below) is used. Otherwise, the specified resize mode is used for that display. It is recommended that you set the resize mode on a per-dashboard basis, by using the Background Properties dialog.

The application level window resize mode can be set in the General tab of theApplication Options dialog or on the command line with the option -apama.resizeModemode, where mode is layout, scale, or crop.

If Default is selected, the default window resize mode is used. The default is Crop for display server (thin client) deployments, and Scale for local (Dashboard Viewer) deployments, as well as for Dashboard Builder.

If the window resize mode is changed in the Application Options dialog in the Dashboard Builder, the new value is only applied to new windows that are opened. Windows that are already open do not change modes.

Two new properties have been added to the Object group of all objects in order to support Layout mode:

• dock: Select None (default), Top, Left, Bottom, Right, or Fill.

  When the dock property on an object is set to one of the sides (Top, Bottom, Left, or Right), it is moved to the specified side of the display and stretched to fill that side of the display. If the size of the display changes, the docked objects stretch to fill the available space. For example, if the dock property is set to Top, the object is moved to the top of the display and the width of the object changes to fill the width of the display. If the display is then made wider, either by changing the Background Properties on the display or by resizing the window in Layout mode, the width of the object changes to match the new width of the display.

  Multiple objects can be docked to the same side of the display. In this case, the first object is docked against the side of the display, the next object is docked against the edge of the first object, and so on.

  When a display has multiple side-docked objects, the object order controls how the dock layout is applied. The layout is applied to the object list from back to front. For example, if the first object in a display is docked to the top, and the second object is docked to the left, the first object fills the entire width of the display, and the second object fills the left side of the display from the bottom of the first object to the bottom of the display.

  When the dock property on an object is set to Fill, it fills the available space left in the display after all of the side-docked objects have been positioned. When multiple objects in a display have the dock property set to Fill, those objects are laid out in a grid in the available space. By default, the grid has one row and as many columns as objects. You can change the grid rows and columns in the Background Properties dialog. If both are set to 0, the default is used. If both the rows and columns are specified, the row value is used and the number of columns is calculated based on the number of objects. If the row value is 0 and the column value is specified, the number of rows is calculated based on the number of objects. The objects are laid out left to right, top to bottom according to the order of the objects in the display. The objects with the dock property set to Fill are always laid out after all of the other docked objects.

  Once an object is docked, there are some limitations on how you can modify that object in the Dashboard Builder. You cannot move a docked object by dragging or changing objX and objY in the property sheet. Side-docked objects can only be resized toward the center of the display (for example, if the object is docked to the top of the display, it can only be resized to be taller). Fill-docked objects cannot be resized at all. You cannot resize any docked objects using the objWidth or objHeight properties in the property sheet. You must drag on the valid resize handle to resize it. It is not moved by Align or Distribute. Objects can be aligned against a docked object, but the docked object is not moved to align against another object. Docked objects are ignored by Distribute.

  Note that when an object is docked, the properties objX, objY, objWidth, and objHeight may change. For example, suppose that you instantiate a General object from the palette, and the properties of the object are as follows: objX:250, objY:250, objWidth:64, and objHeight:48. When you set the dock property to Top, the properties are modified as follows: objX:368, objY:520, objWidth:736, and objHeight:48 (no change). If you then change the dock property to Left, the objWidth isn’t changed, but the objHeight changes so that the object fills the entire height and width of the display. When you change the dock setting to None, these properties stay the same.

  Only objects that support the objWidth and objHeight properties have the dock property.

• anchor: Select zero or more of Top, Left, Bottom, and Right.

  The anchor property is only applied when the display is resized either by changing the Background Properties on the display or by resizing the window in Layout mode. The anchor property anchors the specified side of the object to the same side of the display. When the display resizes, the number of pixels between the specified side of the object and that side of the display remains constant. If an object is anchored on opposite sides (that is, both Top and Bottom or both Left and Right), the object is stretched to fill the available space.

  Only objects that support the objWidth and objHeight properties support anchoring on opposite sides. If an object has the dock property set, the anchor property is ignored.

The composite object supports both dock and opposing anchor sides, but does not behave like other objects if the property resizeMode is set to Size to Display. In this case, the composite size is controlled by the size of the display that it contains, so any changes to the width or height of the object result in the composite moving, not resizing. The composite object should not be docked if resizeMode is set to Layout.

About resize modes and display server deployments

The behavior of thin client, display server deployments differs from the description above in the following cases:

When the initial display is opened in the thin client, the browser frame is not resized to match the display size as it is, for example, in the Dashboard Viewer.

In crop mode, the display appears in its full size, and if the browser frame is larger than the display, unused space appears below and to the right of the display. In addition, if the browser frame is smaller than the display, scrollbars appear.

In layout and scale modes, the display briefly appears in its default size, and then resizes to fit the browser frame size. This may also occur if another tab is opened in the browser, the browser is resized, and then the browser tab that contains the thin client is re-opened.

In layout and scale modes, after the browser frame is resized, table objects revert to their original states. For example, if the user clicks on a column header in a table in order to sort the column, after a resize the table reverts to its default sort. Similarly, if the user scrolls in a table or resizes the legend, after a resize the scrollbars and legends revert to their initial position and size.

In scale mode, there is unused space in the browser frame. This is because the display uses the largest four-by-three rectangular area of the frame, to ensure equal scaling in both dimensions. The unused area has the same color as the display background, but does not have a gradient fill.

About resize modes and composite objects

A new property, resizeMode, has been added to the Composite category of the composite object. When set to Size to Display (the default), the size of the composite is determined by the size of the display that it contains, and the composite cannot be resized. If set to Layout, the composite can be resized and the objects in the composite display are laid out according to their anchor and dock properties.

If resizeMode is set to Layout, the dock and anchor properties may be set on the composite so that it resizes during a window resize if the window resize mode is also set to Layout. If the window resize mode for the display containing the composite is set to Scale, the composite object does a scale instead of a layout.

Note that the dock and anchor properties should not be setup to stretch the composite object if the resizeMode is Size to Display. This causes the object to toggle back and forth between stretched and not stretched when the window is resized in Layout mode.

Working with objects

This section details how to lay out a dashboard by adding objects to the canvas and setting their position and size.

Adding objects to a dashboard

To add an object to a dashboard

1. Select the object type that you want to add by clicking on it in the Object Palette.

2. Click on the canvas to add the object.

You can add more objects of the same type by clicking again on the canvas—you don’t need to select the same object type again. When you select an object from the Object Palette and then position the cursor over the canvas, the cursor changes to a crosshairs pointer. The appearance of the crosshairs pointer indicates that Builder is in add mode, and clicking will add an object to the canvas. You can adjust the position and size of the object after you have added it.

Selecting an object

Click an object on the canvas to select it. The selected object is indicated by a rectangle with handles.

The properties of the selected object are displayed in the Object Properties panel. Actions such as delete operate on the selected object.

To select multiple objects hold down the Shift key while clicking on the objects.

Resizing objects

To resize a selected object, drag a handle of the selection rectangle.

You can also set the size of an object by editing the objWidth and objHeight properties.

Moving objects

To move a selected object, drag the interior of the selection rectangle.

You can also set the position of an object by editing the objX and objY properties.

The dashboard canvas uses a Cartesian coordinate system, with the origin (0, 0) in the bottom left corner of the dashboard. The objX and objY properties are relative to the origin.

The objX and objY properties identify the position of the center of an object. An object positioned at (0, 0) will extend off the left and bottom of the canvas.

Copy and pasting objects

To copy an object, right-click it to display the object popup menu.

When you select Copy, Dashboard Builder places the object into the copy buffer. If the object is already selected, you can also press Ctrl-C or select Copy from the Edit menu in the menu bar.

Once Dashboard Builder has placed an object into the copy buffer, you can add a copy of the object to the canvas by selecting Paste from the popup menu (or the Edit menu in the menu bar) or by pressing Ctrl-V, and then clicking on the canvas. Note that when you select Paste or press Ctrl-V, the cursor to changes to the + pointer.

To copy multiple objects, select each while holding down the Shift key and then select Copy from a menu or press Ctrl-C. When you perform a paste, Dashboard Builder adds a copy of each object to the canvas.

Deleting objects

To delete an object, right-click the object and then select Delete from the popup menu. You can also click it to select it, and then press the Delete key or select the Delete option from the Edit menu in the menu bar. If multiple objects are selected, each will be deleted.

Setting Builder options

To specify Builder options, select Builder Options from the Tools menu.

The General tab allows you to specify the size of the list for history and recently opened dashboards, keyboard settings to move objects on the canvas, and set the style of the objects on the palette.

You can select the Palette Objects Style using the radio buttons: Flat and Classic.

• Flat. The flat style features a white background, no gradient fills or 3D effects, and fewer visible edges and borders around objects. It is intended to provide a simpler and cleaner look.
• Classic. The classic style features a gray background with gradient fills and other 3D effects.

The Grid tab allows you to specify properties of the grid that aids layout of the visualization objects on the Builder canvas.

The values set in this dialog are automatically restored on application startup and saved on application exit.

Setting dashboard options

You can specify dashboard options (user preferences as well as data source definitions) with the Applications Options dialog, described in this section, or with options to the Dashboard Viewer executable (see Using the Dashboard Viewer).

To display the Application Options dialog, select Options from the Tools menu. The Applications Options dialog box appears.

Setting options in the General tab group

To set options in the General tab group

• Select General in the tab group pane (on the left of the dialog).

  The General tab group appears.

Setting options in the General tab

1. In the Update Period field, enter the rate, in milliseconds, at which the dashboard will refresh. Setting this option to a larger number will reduce the CPU use by the dashboard but at the expense of reducing the frequency with which the dashboard updates.

2. In the Enable Data field, check to enable data updates. When data is not enabled, incoming data is ignored.

3. Check the Redraw After Data Update check box to specify data-driven redraws.

   Data from an asynchronous data source can arrive at any time between update periods. This means there could be a delay between the time an asynchronous data source receives a data update and when the display showing this data is updated. If selected, displays containing data from asynchronous data sources that have changed since the last update will be redrawn at the rate specified in the Max Data Redraw Rate field. Displays where no data has changed will only be redrawn on the update. If not selected, displays are only redrawn based on the update period.

4. In the Max Data Redraw Rate field, enter the maximum data redraw rate when data is updated. The default is 500 milliseconds.

5. In the Confirm Commands field, set the confirm policy for all command strings. Overrides confirm policies set on individual objects.

6. Check the Drill Down Windows Always on Top check box if you want windows displayed as the result of drilldowns to always be on top of their parent window.

7. Check the Enable Antialiasing check box to smooth graphics displayed in the dashboard.

8. Check the Single-Click for Drill Down Commands to perform drill downs with a single click; not a double-click.

9. In the Maximum Displays in Composite Object Cache field, enter the display caching for composite objects.

Setting options in the Substitutions tab

The Substitutions tab specifies settings that allows substitutions to be added, changed, or deleted.

Setting options in the data server tab

If you are an advanced user, the Data Server tab allows you to associate a logical name with the data server at a given host and port. Advanced users can then use the logical names to specify the data server to use for a given attachment or command. (The Attach to Apama and Define Apama Command dialogs include a Data Server field that can be set to a server’s logical name.)

The logical names defined in this tab are used by default for live dashboards viewed with Builder as well as for deployed dashboards. They can be overridden with the --namedDataServer option to the builder, viewer, or server executables. See Working with multiple data servers for more information.

Follow these steps to define data server logical names:

1. Select Options from the Tools menu.

   The Applications Options dialog box displays.

2. Select the Data Server tab in the General tab group.

3. Click the Add button to add a definition to the list.

   The Named Server Configuration dialog appears.

4. Fill in the dialog fields:

   • Name: Logical name of your choosing
   • Host: Host of the data server whose logical name you are defining
   • Port: Port of the data server whose logical name you are defining To edit or delete a logical-name definition, select the definition in the Application Options dialog and click the Edit or Delete button.

Setting options in the Custom Colors tab

The Custom Colors tab allows you to specify custom colors that you can use to set object property values. (You set color-valued object properties with the Color Chooser window, which has a Standard Colors tab and a Custom Colors tab.) Both standard and custom colors are pre-populated when Apama is installed, but you can supplement or modify the custom colors with the Custom Colors tab of the Application Options dialog.

1. Select Options from the Tools menu.

   The Applications Options dialog box is displayed.

2. Select the Custom Colors tab.

3. Click the Add button to add a custom color to the list.

   The Select Color dialog appears.

4. To specify a color, select one of the following tabs:

   • Swatches: Standard Java color palette. Mouse over any swatch to view the RGB values for that color
   • HSV: Select color choice by hue, saturation, value, and transparency
   • HSL: Select color choice by hue, saturation, lightness, and transparency
   • HSB: Color selection by hue, saturation and brightness
   • RGB: Color selection by red, green and blue intensity
   • CMYK: Select color by cyan, magenta, yellow, and black intensity well as alpha level To delete a color, click the Delete button.

Apama stores custom colors according to Color Index numbers, not RGB values. Therefore if an object property is defined by a custom color and you change the Color Index number, the color setting for that object property will revert to white. Color Index numbers must be greater than 5000.

To edit a color definition, in the Color fields click the … button of a selected color to edit that color definition with the Select Color dialog.

Object limitations: Some objects (for example, the bar graph legend, pie wedges and legend, and some control objects) cache their colors and therefore do not update when a custom color definition changes. To see the color change for these objects, restart Builder or reload the display.

Setting options in the Apama tab group

The Apama tab allows you to define correlators and specify data management options. For information on the Correlators sub tab, see Specifying correlators.

For information on the Data sub tab, see Specifying data sources.

Setting options in the SQL tab group

The SQL tab group has a single tab, SQL, which allows you to add or remove databases for use in Dashboard Builder and set a default database.

For more information on setting SQL options, see Specifying application options.

Setting options in the XML tab group

The XML tab group has a single tab, The XML tab, which allows XML data files to be defined as data sources for use in Dashboard Builder.

These options are detailed in Using XML data.

Saving options

Clicking the OK or Apply button saves options for future use.

Dashboard Builder saves options to the file OPTIONS.ini. If Builder was started with a --optionsFile argument, the options are saved to the specified location. Otherwise, if the Builder current directory is your project’s dashboards directory or the dashboards directory in your Apama installation’s work directory, the options and are saved there. Otherwise, clicking OK brings up a dialog that allows you to specify the location to which to save the options.

Dashboard Builder saves custom colors to the file COLORS.ini. If the Builder current directory is your project’s dashboards directory or the dashboards directory in your Apama installation’s work directory, the colors (if modified) are saved there. Otherwise, clicking OK brings up a dialog that allows you to specify the location to which to save the custom colors.

If Builder was started without a --optionsFile argument, it uses the options file in its current directory, if present. Otherwise, it uses the options file in the dashboards directory in your Apama installation’s work directory. In addition, Builder uses the colors file in its current directory, if present. Otherwise, it uses the colors file in the dashboards directory in your Apama installation’s work directory, if present. Otherwise it uses the colors file in the lib directory of your Apama installation (which contains your Apama installation’s initial set of custom colors).

Command-line options for the Dashboard Builder

The Dashboard Builder supports options that can be specified on the start-up command line to override the default values used by the builder. The executable for the Dashboard Builder is dashboard_builder, which can be found in the bin directory of the Apama installation.

Synopsis

To pass start-up options to the Dashboard Builder, run the following command:

dashboard_builder  [ options ] [ rtv-file-path ]

If you specify the full pathname of an rtv file, the builder will open it.

When you run this command with the -h option, the usage message for this command is shown.

Options

The dashboard_builder executable takes the following options:

-c default:localhost:15903:false
-c work1:somehost:19999:true

[retry:ms | fail:n | db:name | noinfo |
nopererr | quote]

-S $foo:hello -S $bar:can't -S $tom:"my oh my"
 -S $jerry:"\"yikes\""

--queryIndex Products_Table:prod_id,vend_id

Restrictions

This section lists the known restrictions of using dashboards.

• The substitution names should not contain any of the following characters:

  Colon (:), pipe (|), period (.), comma (,), semi-colon (;), equals (=), brackets (< >, ( ), { }, [ ]), quotation marks (’ “), ampersand (&), slashes (/ \)

• When a function is attached to the enabledFlag property of a check box, the Dashboard Viewer executes the actionCommand first and then evaluates the function. In the thin client, however, the function is evaluated first, and when the function returns 0, the actionCommand attached to the check box is never executed.

  The workaround for this issue is to add two check boxes, one stacked above the other, in z-order.

  The lower has objName = checkbox_enabled, enabledFlag = true, label = "Checkbox", actionCommand = "system browseUrl...", and sets $foold = 1.

  The upper has objName = checkbox_disabled, enabledFlag = false, label = "", actionCommand = "system browseUrl...", and visFlag is attached to $foold.

  So when the display is opened and $foold = "", then checkbox_disabled is invisible, and the user can click on checkbox_enabled to execute the command and set $foold = 1. That makes checkbox_disabled visible, which obscures checkbox_enabled so the user cannot click on it afterwards.