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.
Note:
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 $value variable 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.