Defining dashboard commands

Defining commands

A command is defined by associating it with an action property of a dashboard object such as a push button. When the action is triggered, in this case, when the button is pressed, the command is performed.

For control objects such as push buttons, commands are defined by setting the actionCommand property. For other objects such as labels and charts, the commands are defined by setting the command property.

To see how this works

1. Create a new dashboard.

2. From the Controls tab in the Object Palette, select the Push Button object and add it to the dashboard canvas.

3. With the push button object selected, in the Object Properties panel, right-click the actionCommand property and select Define Command > Apama from the popup menu.

   This displays the Define Apama Command dialog.

4. To define a command, select a command type and specify values for the remaining fields.

   The fields vary based on the command being defined. The common set of fields is as follows.

   • Command — The command to be performed when the action is triggered. The command selected will hide or show many of the other fields.
   • Correlator — The correlator where the command is to be run. If creating a new instance, this is the correlator where the instance will be created.
   • Data server — Advanced users can specify the logical name of the data server to serve the data for the command execution. For more information, see Working with multiple data servers. In this documentation, some of the Define Apama Command dialogs are shown without the Data server field, which was added in a later release.

   The fields in the Parameters section are specific to the specified instance.

   Info

   When executing commands in display server deployed dashboards, warning and error dialogs are not displayed to warn of error conditions that occur.

Using dashboard variables in commands

The value of all fields in the Define Apama Command dialog, with the exception of the Command field, can be set to dashboard variables. This allows you to dynamically configure the command or set its parameters at run time.

For example, you will typically set the field Instance to the dashboard variable $instanceId. The instanceId field identifies the instance the command is to affect, and the variable $instanceId gets set to the unique id of the dashboard’s currently-selected instance. If you then trigger a scenario command, the command will affect the instance identified by $instanceId, which is the instance selected on the dashboard.

Understanding dashboard variables is essential to being able to add scenario commands to a dashboard. Most commands take parameters that you need to supply values for and in most cases you’ll want to prompt the user for the values.

To create an instance of the tutorial, the event apamax.dashboard_tutorial.AddUpdateInstrument (defined in tutorial.mon) needs to be sent. This event requires DataView values for the Instrument and Clip Size variables to be specified. To enable the user to do this, the dashboard needs to include input fields where the values can be specified. These values then need to be used as parameters to the command. This is done through the use of dashboard variables.

To get the value a user has entered in an input field, you need to associate the input field with a dashboard variable so that the variable is updated when the user enters a value in the field. This is done by setting the varToSet property of the input field.

To review the process

1. Create a new dashboard.

2. From the Controls tab in the Object Palette, select the first text field object and add it to the dashboard canvas.

3. From the Labels tab in the Object Palette, select the second label object and add it to the dashboard canvas.

   You will now associate the text field with a variable so that when its value changes the label object updates to show the value.

4. Add the dashboard variable $value by selecting Variables from the Tools menu and adding it in the Variables panel.

5. Ensure that Use As Substitution is checked. Be sure to click the Add button to add it the list of variables.

   Info

   Several substitution variables are automatically created when you create a dashboard.

6. Select the label object and in the Object Properties panel, right click the valueString property and select Attach to Data > Variable.

7. Select $value and click OK.

   The label object will contain no text; it is attached to the $valuevariable which has not been set.

8. Select the text field object and in the Object Properties panel, attach its varToSet property to the dashboard variable $value.

9. Select the executeOnLostFocusFlag property and enable it.

   The text field is now bound to $value. When text is entered into the field $value will change and the label object will update to show the new value. You are now ready to test this.

   Control objects such as text fields and push buttons are not enabled in the Builder canvas. To test these objects, you need to save the dashboard and then select Tools | Preview Window….

10. Type text into the text field object in the preview window, and press Enter. The label object will update to show the text that was entered.

Binding control objects to dashboard variables makes the values available for use not only as property attachments but also as parameters to commands. For fields in the Define Apama Command dialog, you can either hard code a value by typing it in or select a dashboard substitution variable, such as $value, to use as the value. The latter will be the most common case as control objects such as text fields will typically be used to get the value for command parameters.

Defining commands for creating an instance

To add the Create function to a dashboard, you need to add control objects such as text fields and check boxes to the dashboard to prompt the user for the values of input variables. You need to then create dashboard variables to hold the values of the control objects and the objects bound to the variables through their varToSet property.

You next need to add a control object, such as a push button, to the dashboard to perform the command. In the Define Apama Command dialog, select the command Create DataView instance and use the dashboard variables as the values for the variables.

To define commands for creating a DataView instance

1. Open the file tutorial-create.rtv by selecting Create Instance in the tutorial main page.

2. Double-click the object labeled Test to display the dashboard in a new window such that the control objects are enabled.

   This dashboard displays a summary table of all instances of the tutorial DataView and a form for creating new instances.

3. In the form enter APPL for the Instrument and 100 for the Clip Size and click the Create button. This will create a new instance.

   This dashboard has the dashboard variables $instrument and $clipSize defined. The text fields are bound to these such that the variables are set when text is entered in the fields. The actionCommand property for the Create button is set to perform the Create command and use the value of the variables as command parameters.

4. Select the Create button and in the properties panel double-click the actionCommand property.

   If the test window appears, you need to first close it so that you can select Create button in the Dashboard Builder main window.

Here the command is defined to create an instance of the tutorial DataView on the default correlator. You can see that the values for the input variables Instrument and Clip Size are set to the value of the dashboard variables $instrument and $clipSize.

When creating an instance, you must specify a value for each of the input variables. If you do not, you will receive an error when you try to perform the command.

Defining commands for editing an instance

Adding the Edit function to a dashboard is similar to you adding the Create function. You need to add control objects such as text fields and check boxes to the dashboard to prompt the user for the values of DataView input variables. Then you need to create dashboard variables to hold the values of the control objects and the objects bound to the variables via their varToSet property.

You next need to add a control object, such as a push button to the dashboard to perform the command.

The differences are that when defining the command in the Define Apama Command dialog, you need to identify which instance to edit. You also need to identify which variables are to be edited. Unlike the Create command, a subset of variables can be changed with the Edit command. Users cannot edit the variables that have been declared immutable.

To define commands for editing an instance

1. Open the file tutorial-edit.rtv by selecting Edit Instance in the tutorial main page.

2. Double-click the object labeled Test to display the dashboard in a new window such that the control objects are enabled.

   This dashboard displays a summary table of all instances of the tutorial and a form for editing them.

3. Double-click the APMA row in the table. This will cause the instance for APMA to become selected and its input variables to be displayed in the form.

4. In the form, change the Clip Size to 200 and press the Edit button. The value of Clip Size will change for APMA in the table indicating the instances has been edited.

   As in the Create sample, this dashboard has the dashboard variables $instrumentand $clipSize defined. The text fields are bound to these such that the variables are set when text is entered in the fields. The actionCommand property for the Edit button is set to perform the Edit command and use the value of the variables as command parameters.

5. Select the Edit button and in the Object Properties panel, double-click the actionCommand property.

Here the command is defined to edit the instance of the tutorial whose instance id equals $instanceId. You can see that the values for the input variables Instrument and Clip Size are set to the value of the dashboard variables $instrument and $clipSize.

The checkbox next to each variable field is used to specify that the variable is to be edited. When performing an Edit you do not need to specify values for all the variables; only those you want to change.

The Filter fields are used to identify the instance to be edited. In this sample $instanceId is set when you select a row in the table to the apama.instanceId of the selected instance.

The properties of table and other objects in Dashboard Builder are pre-configured to set $instanceId when a drilldown is performed. However, you can use dashboard variables other than $instanceId to hold the apama.instanceId of an instance.

Supporting deletion of an instance

To delete an instance, you have to add a control object, such as a push button and set its action to perform delete operation.

To define commands for deleting an instance

1. Open the file tutorial-delete.rtv by selecting Delete Instance in the tutorial main page.

2. Double-click the object labeled Test to display the dashboard in a new window such that the control objects are enabled.

   This dashboard displays a summary table of all instances of the tutorial and a Delete button for deleting the selected instance.

3. Double-click the APMA row in the table. This will cause the instance for APMA to become selected and its Instrument name displayed in the form above the Delete button.

4. Click Delete. This will delete the APMA instance as indicated by the APMA row being removed from the table.

   As with Edit, when performing a Delete you need to identify the instance to be deleted.

5. Select the Delete button and in the Object Properties panel, double-click the actionCommand property.

   Here the command is defined to delete the instance of the tutorial whose instance id equals $instanceId.

Supporting deletion of all instances

For a dashboard, you may want to provide an option to delete all instances. This can be done by including a control object and setting its action command as follows.

Deleting all instances will only delete those instances to which the user has delete access. By default, these are the instances created by the user.

Defining commands for creating a query instance

Use the command Create query instance to create a new instance of a particular query. For more information, see Defining commands for creating an instance.

To define commands for creating a query instance

1. In Define Apama Command dialog, select the command Create query instance.

2. In the Query field, select the query to use for this command.

3. Provide any input parameters for the create command in the Parameters section.

Defining commands for editing a query instance

Use the Edit query instance command to edit a query instance by changing its input parameters (if any). This command will be performed on a selected (filtered by $instanceId) query instance. For more information, see Defining commands for editing an instance.

To define commands for editing a query instance

1. In Define Apama Command dialog, select the command Edit query instance.

2. In the Query field, select the query to use for this command.

3. Edit any input parameters in the Parameters section.

Supporting deletion of a query instance

Use the Delete query instance command to delete a particular query instance. This command deletes a selected (filtered by $instanceId) query instance. You have to add a control object, such as a push button and set its action to perform the delete operation. See Supporting deletion of an instance for more information.

To define commands for deleting a query instance

1. In Define Apama Command dialog, select the command Delete query instance.

2. In the Query field, select the query to use for this command.

3. Select the filtering criteria.

Supporting deletion of all instances of a query

For a dashboard you may want to provide an option to delete all instances of a query. This can be performed by including a control object and setting its action command as Delete all instances of a query in the Define Apama Command dialog. Deleting all instances of a query will only delete those instances to which the user has delete access. By default, these are the instances created by the user.

Using popup dialogs for commands

For the Create and Edit commands you might not want to integrate the input fields with the main dashboard. They might, for example, occupy space that is better used for display information about running DataViews. An alternative is to place the input fields in separate dialog windows. In this case, the main dashboard contains Create and Edit buttons. Clicking them displays the appropriate dialogs where users enter the parameters for the command in the input fields and then click the OK button to perform the command. You can set up popup dialogs like this in Dashboard Builder.

To use popup dialogs for commands

1. Open tutorial-create-popup.rtv by selecting Create Instance Popup from the tutorial main page.

2. Double-click the Test label to display the dashboard in a new window such that the control objects are enabled.

   Here the dashboard contains a Create button but no fields for setting the input variables.

3. Click on the Create button. This will display a dialog window with the fields for creating an instance.

   This dialog is really just another dashboard, in this case tutorial-create-form.rtv. The Create button displays this dialog by performing a drilldown and displaying tutorial-create-form.rtv in a new window.

4. Select the Create button object and double-click the actionCommand property in the Object Properties panel.

   The command is defined to perform the Drill Down or Set Substitution system command.

5. Click on the Edit Drill Down Target button.

   The drilldown is set to display tutorial-create-form.rtv in a new window.

   The dashboard for the popup dialog was created in Dashboard Builder.

6. Open the file tutorial-create-form.rtv.

   You can now select objects in the form and examine their properties in the property panel. The settings are very similar to those in the previous create instance example. The dashboard contains the variables $instrument and $clipSize which are bound to the text fields. The actionCommand property on the OK button is defined to perform the create operation using the values of these variables.

   What is different is that when OK is pressed, the command will be performed and the dialog window closed. The option to close the window is set in the closeWindowOnSuccess property.

7. In the Builder window, select the OK button object.

8. Here the closeWindowOnSuccess property is enabled. If this property is enabled, the dashboard closes the window that performed the command if the command completes successfully. If the command generates an error, the window will not be closed.

9. The Cancel button also has a command associated with it. To see this, select the Cancel button object and in the Object Properties panel, double-click the actionCommand property.

Command options

The Object Properties pane provides some properties that control some command options:

• commandCloseWindowOnSuccess — If enabled, the dashboard will close the window that performed the command if the command completes successfully. If the command generates an error the window will not be closed.
• commandConfirm — If enabled, the dashboard will display a confirmation message (specified by the commandConfirmText property) before performing the command. It is recommended that this be enabled for delete commands.
• commandConfirmText — If commandConfirm is enabled, the dashboard will display the value of this property as a confirmation message.

Associating a command with keystrokes

This chapter’s previous examples define commands that are to be invoked by the dashboard users via mouse actions. You can also define commands that are to be invoked by dashboard users via keystrokes.

You do this by adding a HotKey object to the Builder canvas.

The HotKey object is located in the Controls tab of the object palette:

When you add a HotKey object to the Builder canvas, it does not appear on the end user’s dashboard. But as dashboard builder, you set HotKey properties in order to associate keystrokes with a command:

• hotKey property: Specify the keystrokes that you want dashboard users to use in order to invoke the command. The value of this property is a text string whose format is described below.
• command property: Specify the command to be invoked. Do this as described in this chapter, above.

The hotKey property value must be a text string that consists of a sequence of keystroke-designators. A simple keystroke designator is one of the following:

• Function key designator: F1, F2, F3,…, or F12.
• digit or letter: a, b, c,…, z, 0, 1, 2,…, or 9.

You can also form a keystroke designator by adding one of the following prefixes to a simple keystroke designator:

• SHIFT+
• CTRL+
• ALT+
• CTRL+SHIFT+
• ALT+SHIFT+
• CTRL+ALT+
• CTRL+ALT+SHIFT+

So for example, the keystroke that results from holding down the control and the shift key and striking the F1-function key is designated as follows

CTRL+SHIFT+F1

And the keystroke that result from holding down the shift key and striking the letter f is designated as follows:

  `SHIFT+`f

For the dashboard user, when focus is on the dashboard, the specified key sequence triggers execution of the command.

Defining multiple commands

You can associate multiple commands with an action by using the Define Multiple Commands dialog.

To define multiple commands

1. Right-click command property and select Define Command > MULTIPLE.

2. In the Define Multiple Commands dialog, choose APAMA in the New Command combo box, and then click the Add button to add an Apama command.

   Important: The commands are launched in an arbitrary order, and are run asynchronously; there is no guarantee that one command will finish before the next one in the sequence starts.

   See Apama set substitution command.

Creating custom commands

To provide a data server or display server with a library of custom commands

1. Develop an implementation of com.apama.dashboard.function.ICommandLibrary. See Developing a custom-command library.

2. Install your implementation. See Installing a Custom-Command Library.

Developing a custom-command library

Your implementation of ICommandLibrary must implement the following methods:

• getCommandDescriptors: Creates a command descriptor for each function that the library supports; returns a list of com.apama.dashboard.command.ICommandDescriptors. This method is called once at data server or display server startup.
• invokeCommand: Performs the command with the specified name, using the specified arguments.

When you compile your implementation, ensure that ap-dashboard-client.jar is on your class path. This jar file is in the lib directory of your Apama installation.

Your implementation of invokeCommand can set or retrieve substitution values, if necessary, by using the following methods of com.apama.dashboard.DashboardManager and com.apama.dashboard.IDashboardContext:

• DashoardManager.getCommandDashboardContext: This static method returns an instance of IDashboardContext.
• IDashboardContext.getSubstitutionValue: Gets the value of a substitution with a given name.
• IDashboardContext.setSubstitution: Sets the value of a substitution with a given name.
• IDashboardContext.setSubstitutions: Sets the values of substitutions, where the substitutions and values are specified with String vectors.

Each set method has a boolean argument, triggerUpdate, which controls whether objects attached to the substitution are updated. If it is false, they are not. If the substitutions are only used as command parameters or in drilldowns, you can improve performance by specifying false.

Following is an example:

import com.apama.dashboard.DashboardManager;
import com.apama.dashboard.IDashboardContext;
...
IDashboardContext ctxt =
   DashboardManager.getCommandDashboardContext();
String val1 = ctxt.getSubstitutionValue("$subst1");
...
ctxt.setSubstitution("$subst2", "val2", false);

Installing a Custom-Command Library

To install your function library for a given data server or display server

1. Include a line in the data server or display server’s EXTENSIONS.ini file that specifies the fully qualified name of your ICommandLibrary implementation. The line must have the following form:

   command fully-qualified-classname
   

2. Create a jar file that contains your ICommandLibrary implementation, and add it to APAMA_DASHBOARD_CLASSPATH (changes to this environment variable are picked up by dashboard processes only at process startup). You can also use the --dashboardExtraJars command line argument to specify this jar file.

A data server or display server’s EXTENSIONS.INI is, by default, located in the lib directory of its Apama installation. You can specify a data server or display server’s EXTENSIONS.ini file at startup by using the -X or --extensionFile option — see Deploying and Managing Apama Applications.

The EXTENSIONS.ini specifies the function library to use. This file identifies all the user supplied extension classes (including function libraries and scenario authorities). Here is a sample EXTENSIONS.ini:

function com.apama.dashboard.sample.SampleFunctionLibrary
command com.apama.dashboard.sample.SampleCommandLibrary
scenarioAuthority com.apama.dashboard.sample.SampleScenarioAuthority

This file installs a function library, a command library, and a scenario authority.

Apama set substitution command

Use the Apama set substitution command to set substitution values without using the Drill Down or Set Substitution system command.

To set substitution values

1. Right-click the command property and select System.

2. In the Command Type combo box of the Define System Command dialog, select Run Custom Command.

3. In the Command Name: field, type Apama_SetSub1.0.

4. In the Command Value: field, type a string in the following format:

   Sub=Value[;Sub=Value...]
   

   For example, to set $MySub1 to value1 and $MySub2 to value2, enter the following command value:

   MySub1=value1;MySub2=value2
   

   Remember to remove the $ from the substitution name.