Editing a Script
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.6 identifies the sections of the Script Editor.
Figure 1.6 Screenshot of the Script Editor
Script Settings
This set of items applies to the entire script and includes the following configuration:
• Script Name. The unique name of the script appears here and in the list of scripts in the Script Manager.
• Description Editor. Enter a description, if desired, that will appear in the Script Manager.
Actions panel
This is an ordered sequence of actions, each of which has one of the defined action types. Each item has either a default or user defined label and its type. E.g., Text: “Set the run range to:” Type: “Set Run Range”. Each action can be disabled (or enabled) using the checkbox.
Select one or more action from the panel using drag, Ctrl+Click and Shift+Click. Select multiple actions to move, copy, or delete multiple actions. Select a single action to edit the settings.
Settings panel for the Selected Action
Each action type has two or more associated parameters, each of which has an associated setting. For example, an action of type Set Method has two standard parameters, Show in Manager and Display Text, and three specific setting, Object Name, Category, and Method. These are configured in the settings panel for the selected action.
Note: If you select more than one action, then you can’t edit the settings. Only one action’s settings may be edited as a time.
Search
Search for actions that match the specified text. Select which action attributes (Text, Type, and/or Value of settings) in which to search.
Execution panel
When creating and debugging your script, it may be more convenient to run the script from here than opening the Script Dashboard. Use the Start button to execute the script.
Tip: Alternative, use the context menus to execute a single action (
Execute This Action) or that action and the rest of the script (
Execute Script From This Action). See
Executing Actions From the Script Editor for details.
The ability to run the script from the Editor is strictly for convenience while creating and editing the script. The interface and feedback for running a script is much better on the Script Dashboard; see
Script Dashboard for details.
Using 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.
1. Enter a meaningful name in the Name field.
2. Enter a description if desired.
3. Add an Action to the script; see
About Action Types for a complete list of the available actions. Select
Help ![](../AutomationTools/images/ScriptManagement_0012.png)
for a quick description of each action. Use the
Add Action menu and select the desired action. When you select the action it will automatically add it to the script and select it.
Tip: Copy and Paste of actions is available from the Edit menu, context menu, or using the Ctrl-C and Ctrl-V keyboard accelerators. See
Copy and Paste of Actions.
4. Configure that action. With the single action selected, the Settings panel shows the available parameters. For example, in
Figure 1.7, the Set Controller action is selected, so now the controller can be chosen from the list in the settings panel.
Figure 1.7
Each action has two or more settings that can be configured. For many of the settings, you provide a numeric value but can also specify that it is editable in the Script Manager. For example, you may use the Set Scalar Slot Value action to set a model trigger. You can specify that the value should default to 0 in the script but allow the user to override the default and use a slider bar in the Script Manager to change the value. See
Configuring User Control on the Script Dashboard for details on this type of configuration.
5. Repeat
Step 3. and
Step 4. until you have fully defined the script.
6. Use the arrows
![](../AutomationTools/images/ScriptManagement_0015.png)
to rearrange the actions as necessary. They will execute in order from top to bottom.
7. Once you have the script defined. consider what text to be show on the Script Manager. Use the
Show in Manager and
Display Text, to modify whether the setting is shown and if so, the text that is displayed, respectively. See
Common Settings for Action Types for details. In addition, you can disable actions using the check boxes. This is enabled/disabled setting is shown on the dashboard but can be re-enabled there too. See
Common Settings for Action Types for details.
8. Select OK to apply the changes and close the dialog.
Copy and Paste of Actions
You can copy one or more actions from a script and paste them in any other script. Standard multi-select controls allow you to select multiple actions: Drag or Shift+Click to select a contiguous block of actions, and Ctrl+Click to select non-contiguous actions.
With one or more script actions selected in the Script Editor, use the following operations in the Script Editor in the actions panel:
• Copy Action: Copy the selected action.
• Paste Action: Paste the copied action over the selected action(s) with a confirmation. Pasting over multiple actions only works with a contiguous selection.
• Paste Action Below: Paste the copied action below the last selected action.
To access these operations, use the
Edit menu as illustrated in
Figure 1.8 or from the context menu for the action list as shown in
Figure 1.9. Keyboard accelerators are also available: Copy: Ctrl+C and Paste: Ctrl+V.The context menu also gives access to slots referenced by the action, where applicable.
Figure 1.8 Script Editor Edit menu operations
Figure 1.9 Script Editor context operations
Also, on the script dashboard, the right-click context menu provides access to copy an action. These can then be pasted into a Script Editor as described above
Tip: To copy an entire script, from the Script Manager, use the Edit and then Duplicate Script operation.
Searching for Actions
Use the Search panel to find an action by text, type, or value in the script editor. This can be very useful if you have a script that issues an error as the message says the type of action and its name. Use the search to find that action in the editor. To open the Search panel, use the Search check box, use Edit menu and then Search or use the Ctrl+F keyboard shortcut.
Figure 1.10 Screenshot of Script Editor Search Panel
Then, type in the desired text and select the attributes in which to search. The attributes correspond to columns in the Script Editor’s action panel and settings panel:
• Text: Search in the action Text column. The default text or any specified display text is searched.
• Type: Search in the action Type column.
• Value: Search in the Value column for each setting. This is particularly useful as you can search for slots in slot selections, objects in object selections, datetimes or any other value in the settings.
To perform the search, select Enter or use the up or down arrows. When a matching action is found, that action is selected in the Action panel. The search will wrap when it meets the end of the script.
Executing Actions From the Script Editor
When creating and debugging your script, it may be convenient to run the script from the editor than opening the Script Dashboard. There are three ways to execute actions from the editor:
• Use the
Start button to execute the entire script.
![](../AutomationTools/images/ScriptManagement_0031.png)
• Use the Execute This Action context menus to execute a single action.
• Use the Execute Script From This Action context menu to execute a single action and the rest of the script.
These operations execute the actions but do not give status or display information on progress. As a result, running actions is best performed from the Script Dashboard; see
Script Dashboard for details.
About Action Types
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.
Table 1.1 Descriptions of the available actions
Action Type | Description | Link |
---|
Analyze Ensemble Data Set | Compute a specified statistic for an open ensemble data set. Statistics are computed across traces, resulting in a single value for each slot and date/time in the data set. | |
Apply Window Layout | Apply a window layout created with the Window Layout Manager. | |
Clear DMI Values | Clear the values set by a DMI (by using the DMI invocation manager functionality) | |
Clear Scalar Slot Values | Clear the values on a set of Scalar Slots (i.e. set them to NaN). | |
Clear Table Slot Values | Clear certain values on a set of Table slots (i.e. set them to Nan). | |
Compute Duration Curve | Compute a duration curve for specified slots for an open ensemble data set across traces and timesteps. | |
Compute Regression | Compute a multiple linear regression for an open ensemble data set. The regression is computed across traces, resulting in a set of regression coefficients and statistical outputs regarding the regression quality. | |
Configure MRM Index Sequential | For the specified MRM configuration, modify the configuration in terms of Index Sequential. | |
Configure MRM Input DMI | For the specified MRM configuration, modify the configuration in terms of Input DMIs, particularly the repeat count. | |
Configure MRM Output | For the specified MRM configuration, modify the configuration in terms of the Output. | |
Configure MRM Traces | For the specified MRM configuration, modify the first trace and number of traces. | |
Configure Trace Directory DMI | For the specified Trace Directory DMI, specify the Trace Number to use if executed outside of MRM. | |
Create Ensemble Data Set | Read an RDF file and add it to the list of data sets managed by the Ensemble Data Tool. | |
Create Slot Cache | Create a slot cache of workspace series slot values. | |
Create Snapshot | Create a Snapshot of the specified slots. | |
Delete Ensemble Data Set | Remove an ensemble data set, freeing up the memory required to represent those data. | |
Delete Link | Delete a link between two slots. | |
Delete Optimization Restore Points | Delete all optimization restore points currently in existence | |
Divider | Create a different colored row in the Script Editor and Script Dashboard to visually separate actions. | |
Enable Dispatching | Enable or disable dispatching of the specified objects. | |
Enable MRM Distributed Runs | For the specified MRM configuration, specify whether to distribute concurrent runs to multiple processors on the same machine. | |
Enable RPL Item | Enable or disable a RPL item (policy group, rule, method, or goal) | |
Evaluate Expression Slots | Evaluate a set of expression slots. | |
Execute DMI | Invoke a DMI or DMI group. | |
Execute MRM Run | Execute the runs for the specified MRM configuration. | |
Execute Run | Run the model. | |
Execute Script | Execute a script from within a script. | |
Export Database DMI | Export Database Data Management Interfaces (DMIs) to a file and optionally include name maps and datasets. | |
Export Object | Export Objects to a file and optionally include links, object attributes, slot notes and accounting items. Note, exporting clusters is not supported within a script. | |
Export Optimization Restore Point | Export the specified optimization restore point to a file | |
Export Table Slot as CSV | Export the selected table slot to a comma-separated values (CSV) file. | |
Generate Output Device | Generate the specified Output Device. This could be a file based device like a Model Report or a graphical device like a Plot Page. | |
Global Time Scroll | Scroll time and series displays to the specified symbolic date/time. | |
Import Database DMI | Import Database Data Management Interfaces (DMIs) from a file and specify how to resolve conflicts. | |
Import Object | Import Objects from a file and specify how to import object attributes, slot notes and object clusters, and how to locate the imported objects. | |
Import Optimization Restore Point | Import an optimization restore point from the specified file | |
Link Slots | Create a link between two slots. | |
Load Goal Set | Open and load a goal set (for Optimization runs). | |
Load Ruleset | Open and load a ruleset (for Rulebased Simulation runs) | |
Memo | Pause script execution and optionally open a confirmation dialog with your user specified message. While script execution is paused, you can interact with RiverWare or other applications in ways not directly supported by scripts. Select the script Start button to resume the script execution. | |
Open Ensemble Data Tool | Open the Ensemble Data Tool and bring it to the top layer of windows. | |
Open File | Open the specified external file, for example an Excel file or Word document. | |
Open Global Functions Set | Open a global function set. | |
Open Object | Open the specified objects. | |
Open SCT | Open an SCT with the specified filename. | |
Open Slots | Open the specified slots. | |
Remove RPL Set | Remove a selected RPL set from the model. An RBS Ruleset or Optimization Goal set is unloaded and closed, a Global Function Set is closed, and the Initialization Rules Set is cleared. | |
Reorder RPL Set | Reorder the items (rules, goals, statements) in a RPL set according to priority or index defined on the specified table slot. | |
Replace Initialization Rules Set from File | Replace the existing Initialization Rules Set from a file. | |
Save Model | Save the model to a file. | |
Set Account Method | Set the selected method in one of an account’s method categories. | |
Set Accounting Period | Set the time range of the accounting system (i.e., the Begin Accounting Period and End Accounting Period dates). | |
Set Controller | Set the current controller. | |
Set Dataset File | Set the DSS file for a DSS dataset, or the Excel workbook for an Excel dataset. | |
Set Excel Dataset Run Name | For the specified Database DMI Excel Dataset, set the run name type and/or specify a new single run name. | |
Set Init. Rules Exec. Flag | Set the “Execute Initialization Rules” run control flag. This flag controls whether or not the initialization rules are executed as part of each run. | |
Set Method | Set the selected method in the specified category for a set of objects. | |
Set MRM Descriptor | For the specified MRM configuration, set the specified keyword, value pair MRM Descriptor. | |
Set MRM Ruleset | In a given MRM configuration, set a new file path to a ruleset. | |
Set MRM Run Range | Set the time range of the run (i.e. the Run Start and End dates) for the specified MRM configuration. | |
Set Optimization Integer Parameter | Set the value of any integer optimization parameter | |
Set Periodic Slot Values | Set one or more Periodic Slot’s value at the specified row and column. | |
Set Run Range | Set the time range of the run (i.e. the Run Start and End dates). | |
Set Run Timestep | Set the timestep size of the run (E.g 1 Hour, 1 Day, 1 Month, 1 Year). Options are included to specify how to synchronize and optionally aggregate data. | |
Set Scalar Slot Value | Set one or more Scalar Slots values. | |
Set Series Slot Flags | Set the specified flag (input or output) on a set of series slots within the specified time range. | |
Set Series Slot Input Mode | Set the Input Mode for one or more Series Slots with Periodic Input slot. | |
Set Series Slot With Periodic Input | Set the periodic values of a Series Slot with Periodic Input slot. | |
Set Series Slot Values | Set Series Slot’s values within a time range. | |
Set Table Slot Value | Set one or more Table Slot’s value at the specified row and column. | |
Synchronize Objects | Set the time range for the specified objects. | |
Synchronize Slots | Set the time range for the specified slots. | |
Common Settings for Action Types
An action is controlled by user settings. Actions of all types have the following settings:
• Enabled/Disabled. Each action has a check box that determines whether it is enabled or disabled in the script editor. This setting is also used to indicate whether the action starts as enabled or disabled in the script dashboard, although it can be overridden in the dashboard.
• Show In Dashboard. This is a Yes/No value that controls whether the action is listed in the Script Dashboard.
• Display Text. This single line of text identifies the action. This text is shown in the dashboard. If the field is empty, default text is automatically generated based on the action type and settings.
• Description. This multi-line text provides a description, comment, or notes on the action. On the dashboard, the text is displayed below the Display Text. Select the description value to start the edit and then enter the text in the text box or use the
![](../AutomationTools/images/ScriptManagement_0015dTextEditorButton.png)
button to open a text editor.
Within the text editor, type or paste in your description. Enter line breaks as necessary. A sample editor is shown.
For this sample Set Scalar Slot action, the resulting description would show on the dashboard as two lines below the display text above any override controls:
Setting Information
The following sections provide more information on certain settings or on settings that are shared by many actions that have additional controls.
Datetime Information
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.
Note: The current menu is being transitioned to the updated menu. Common functionality has been highlighted in
Figure 1.11.
Figure 1.11
Following is additional information on each of these ways to specify the datetime.
• Choose a Datetime. Use the datetime spinner by selecting the More button or the Constant Datetime Editor option. This opens the Date/Time selector.
Note: This uses the model timestep size.
• Type a Datetime. Enter a date by typing. Use the HH:00 MMM DD, YYYY as a guide: Hour (H), Month (M), Day (D), Year (Y).
• Specify the Datetime Symbolically: Use one of the options shown and specify any of the pieces necessary like integers “N”, Hour (H), Month (M), Day (D), Year (Y). On the updated menu, select
Help for details on the symbolical datetimes. Basically, any fully specified datetime can be used. See
DATETIME in RiverWare Policy Language (RPL) for details.
Note: No @ or quotes “ ” are necessary when specifying the datetimes. In this context, “Current Timestep” means the machine/operating system time, rounded up to a controller timestep. So if you are running the script at noon on the 4th of July, 2014 in a model with a 1 Day timestep, “Current Timestep” would return 24:00 July 4th, 2014.
• Use a Global Function: To allow additional flexibility specifying datetimes, you can specify a RPL function from an opened Global Function Set; see
Global RPL Functions in RiverWare Policy Language (RPL) for details. You can type in the name of the function (original menu) of the form function() (see note below) or choose it using a selector (updated menu). This function must return a fully specified DATETIME variable
Note: Datetimes stored on slots cannot be set to NaN as an override on the dashboard, but can be configured to be set to NaN from the Script Editor.
Note: Originally, you could set a datetime to a RPL function using the function() notation on the Script Editor. Functions specified this way are still supported. But for new scripts or any edits, functions should be specified by changing the “Set by” setting to Function and choosing the function from the selector.
Filename Information
Filenames can be entered manually or chosen using the file chooser. You can specify files using environment variables using the $VARIABLE syntax.
RPL Reorder Set Action
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.12 shows the ruleset before the script is executed.
Note: Statements are shown using the View menu.
Figure 1.12
Figure 1.13 shows the specified table that describes the desired ordering. The row labels must match the names of the items in the set.
Figure 1.13
Figure 1.14 shows a text description of this reordering.
Figure 1.14
Figure 1.15 shows the ruleset after reordering.
Figure 1.15
Setting Slot Values
This section contains important information on the following actions that set slot values in the model:
Configuring User Control on the Script Dashboarddescribes 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.
Configuring User Control on the Script Dashboard
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, Set Periodic Slot Values), 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.16.
Figure 1.16
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.17 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.
Figure 1.17
Editor
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.18 shows the settings to get this control.
Figure 1.18
Radio Buttons
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.19 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.
Figure 1.19
Sliders
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.20 shows the settings to configure this control. The available slider positions are computed by dividing the interval between the minimum and maximum by 100.
Figure 1.20
Setting Slot Values Using a Global Function
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.21.
Figure 1.21 Screenshot of selecting a Global Function
Note: The Global Function must return a NUMERIC or DATETIME value. Setting Text Series Slots is not supported by this mechanism.
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:
• Set Scalar Slot Value: SLOT slotToSet. This action loops over each slot and calls the function passing in the slot as the argument.
• Set Series Slot Values: SLOT slotToSet, DATETIME date: This action loops over each slot and datetime and calls the function passing in the slot and datetime as the arguments.
• Set Table Slot Value: SLOT slotToSet, NUMERIC row, NUMERIC col. This action loops over each slot and calls the function passing in the slot, row, and column as the arguments.This action only sets the slot at the specified row and column. It does not loop over the rows and columns.
• Set Periodic Slot Value: SLOT slotToSet, NUMERIC row, NUMERIC col. This action loops over each slot and calls the function passing in the slot, row, and column as the arguments.This action only sets the slot at the specified row and column. It does not loop over the rows and columns.
Example 1.1 Using a RPL Global Function to set multiple series slots.
This is best explained with an example. Let’s assume we want to set five series slots to a value on a data object at each timestep in the run.
Set up the script as follows:
1. In the Set Series Slot Values action, “Slots” setting, choose the 5 slots to set.
2. Choose the Global Functions Set and the desired Global Function
3. Specify the Start and End Date
In our example, the settings and RPL function is shown in
Figure 1.22.
Figure 1.22 Screenshot of a Set Series Slot Values that calls a numeric RPL function
When this action is executed, it will loop over the 5 slots and all timesteps in the run. For each slot/timestep, it will call the GetSlotOffAnotherObject function and pass the slot and datetime into the function. The function computes a numeric, in this case looking up the value on another object. The action then sets that value.