Scripts allow you to organize and run sequences of actions. This allows you to automate many of the tasks involved in operating a model. For example, the script shown to the right changes the run range, sets a value that represents the type of run, changes the controller, sets a date trigger referenced by rules, allows you to select a forecast percentage, changes a method selection, and clears a slot’s flags. This section presents key Script features and provides some examples of how they might be used.

Like the model itself, in a typical application the script will be created and configured once and then executed many times. In our discussion of Scripts, we use the term “modeler” to refer to the person who defines and configures the script and the term user for the person who runs the script.

Now that you know some of the features of scripts, why might you use them? Following are some applications or use scenarios.

This document describes the Script Manager, Script Editor, and Script Dashboard including all of the action types and settings. See “Script Dashboard” for details on running scripts.

The Script Manager is used to create, export/import, and delete scripts.

To access the Script Manager, from the workspace, use the Scripts, then Script Management menu. When there are scripts defined, the name of each script will show up in the Script Management menu. Select the name to open the Script Dashboard for that script.

The Script Manager contains lists of the defined scripts in the model. These scripts are all shown on the All Scripts tab, as shown in Figure 1.1. In addition, you can create your own tabs or groups; see “Working With Script Groups” for details.

Within any of the tabs, use the Edit Script button to open the Script Editor; see “Editing a Script” for details. Select the Open Dashboard button or double-click a script to open the Script Dashboard; see “Script Dashboard” for details.

The All Scripts tab contains the complete list of scripts, and it is the only group from which new scripts can be created or scripts can be deleted. When on the All Scripts tab, use the New Script button to create a script. Use the options in the Edit menu to delete an existing script.

The lower portion of the Script Manager shows the selected script’s description. This allows you to quickly see the description to know what the script does or why you would want to use it. The descriptions are edited as part of the script; see “Using the Script Editor” for details.

The Script Manager can be configured to automatically open upon loading a model by checking the Open Script Manager on model load toggle. You can specify which script group tab is initially displayed by selecting a script from the Default tab menu. The Default tab is shown when the Script Manager window is initially opened (either upon model load or manually) within a RiverWare session.

To create a user-defined script group, use the Script Manager's Edit, then New Group menu. To modify an existing user-defined group, select the tab and then use the Edit, then Edit Group menu item. Both of these menu items open the Script Group Editor, shown in Figure 1.2.

The Script Group Editor lists the scripts within the group and you can add, remove and reorder the scripts within the group.

To add a script to the group, select the green Plus button. This opens the Script Selector, which lists those scripts not already included in the script group. Select one or more scripts and select OK to add the scripts to the group.

Within the Script Manager, you can rearrange the tab groups by dragging a tab to a new position.

One or more Scripts or Script Groups can be exported from the model and then imported into another model. This section describes this process.

From the Script Manager, use the File, then Export Selected Script to export one or more scripts or groups to a file. This opens the Export Scripts and Script Groups.

First, specify a file for export. Either select from the menu, type in a file name or select the More button to choose a file on the system.

Then specify the scripts or groups to export.

The dialog contains two sections, one on the left, listing Script Groups and one on the right, listing all Scripts. The lower panel shows the description of the highlighted (not checked) script.

To export one or more Script Groups and the scripts referenced by the group, select the checkboxes in the left panel. All constituent scripts will be exported. Use the tree view arrows to see which scripts are part of the group. Also, as you select a group, the referenced scripts will also be checked and the background color will change in the Scripts panel on the right, as shown in Figure 1.3.

To select one or more scripts to export that are not part of a group, select them from the right panel. In Figure 1.4, five scripts will be exported.

Once you have checked the desired groups/scripts, make sure to specify a file name at the top of the dialog. Then select Export to export the file.

Use the File, then Import Script to import previously exported scripts. Choose the file name and select Open.

If there is a name duplication between a Script or Script Group being imported and an already existing Script or Script Group, the name being imported is automatically changed by appending "_nn" to the existing name, where nn is a two digit integer that is increased from 01 until a unique name is encountered. This scheme preserves imported-item name information without requiring detailed renaming actions during the import operation. You are notified that automatic renaming has occurred, in case you want to edit the names of the affected items afterwards.

The Script Editor is where you define the Actions that the script performs. In addition, you define how the script will appear in the Script Dashboard and what values can be edited by the script user. To open the Script Editor, select a script in the Script Manager and select Edit. Figure 1.5 identifies the sections of the Script Editor.

This section describes how to use the Script Editor to define the script. This assumes you have created a new Script from the Script Manager. The Script Editor opens automatically for new scripts or select Edit to open an existing script.

Table 1.1 describes the types of actions. Within the Script Editor, select Help for a quick reference of the actions. Each action type also has a link to additional information on its settings. See “Action Type Settings Reference” for details about the settings.

An action is controlled by user settings. Actions of all types have the following settings.

The following sections provide more information on certain settings or on settings that are shared by many actions that have additional controls.

Datetimes in a script can be specified either as absolute values or a symbolic values. There are two slightly different interfaces, but both have essentially the same functionality. Depending on the action and whether it is the editor or dashboard, one of the following interfaces will be used.

Following is additional information on each of these ways to specify the datetime.

Filenames can be entered manually or chosen using the file chooser. You can specify files using environment variables using the $VARIABLE syntax.

This action allows you to reorder items (rules, goals, groups, or even statements within the specified set. The new order is specified on a table slot. Following is an example that shows the use of this action. Figure 1.8 shows the ruleset before the script is executed.

Figure 1.9 shows the specified table that describes the desired ordering. The row labels must match the names of the items in the set.

Figure 1.10 shows a text description of this reordering.

Figure 1.11 shows the ruleset after reordering.

This section contains important information on the following actions that set slot values in the model:

“Configuring User Control on the Script Dashboard”describes how to configure user controls on the dashboard. Then, see “Setting Slot Values using a Global Function” for more information on setting numeric values using a global function.

This section applies when the “Set by” setting is using “Values” For actions that set values in the model (Set Scalar Slot Value, Set Series Slot Values, Set Table Slot Value), you can either specify the value to set or give a default, but allow the user of the script to override that value. This section describes configuring the action so that the user can modify the value using either a value editor, radio buttons or a slider. These are controlled by the settings shown in Figure 1.12.

The following sections describe the three “Yes” cases. In each case, an example will be shown where a script is setting a scalar slot called Data.Factor to a value between 0.1 and 1.5. Perhaps this factor is then referenced by a rule to compute demands or inflows. For reference, Figure 1.13 shows this scalar slot.

For all of the Yes selections for Allow Editing, you can also choose to Show Current Value. When Yes, the current value (for a single scalar slot only) is shown on the Dashboard below the editing controls.

When the Allow Editing setting is Yes: Editor, an editable field is shown on the Script Manager. The default value will be used unless the user enters a different value in the field. Figure 1.14 shows the settings to get this control.

When the Allow Editing setting is Yes: Radio Buttons and an Encoding Table Slot is specified, radio buttons are shown on the Script Manager. The default value will be used unless the user selects one of the radio buttons to use that value.

The Encoding Table Slot Name setting specifies a Table Slot whose row labels and values establish a textual encoding of values. Figure 1.15 shows a sample encoding table slot. The row labels are used as the labels on the radio buttons. The values in the table are displayed on the Script Manager and will be used by the action for that button.

When the Allow Editing setting is Yes: Slider and Minimum and Maximum Edit Values are defined, a slider will be shown on the Script Manager. The default value will be used unless the user moves the slider to a different value. Figure 1.16 shows the settings to configure this control. The available slider positions are computed by dividing the interval between the minimum and maximum by 100.

The three script actions allow slot values to be set to values as described above. They also allow the slot value to be set to numeric or datetime values using a RPL Global Function.

To use this functionality, in any of these three actions, in the “Set by” setting, choose “Function”. Then choose the desired RPL Global Functions Set and the specific RPL Global Function to use as shown in Figure 1.17.

The global function can contain various combinations of arguments based on the action. You can use zero, one or more arguments. The arguments passed for each action are: