Control Tool Configuration

Control Tool Database Table Configuration

Control Tool actions are defined in two NMS database tables. The CONTROL_ACT table defines the actions and the CONTROL_AGGREGATES defines the order of execution for multi-step control sequences.

The Control Tool Workbook generates the CONTROL_ACT and CONTROL_AGGREGATES table insert statements; the SQL statements can then be added to your [project]_control.sql file. You can find the workbook at:

$NMS_BASE/OPAL/workbooks/Oracle_Utilities_NMS_Control_Tool_1.11.xls

CONTROL_ACT Database Table Configuration

The CONTROL_ACT database table contains the definitions for each control action used in the Control Tool, as well as some actions used exclusively by Web Switching and Web Safety.

Definition

• act_key: a unique index for the record.

• act_cls: the action type for the action (see below)

• act_idx: the action identifier (see below)

• action_name: the name of the JBot Action to be executed for this record

• label: the label to display on the Control Tool

• instruct_label: the label for the instruct version of the action on the Control Tool, if desired

• switching_desc: the text displayed for the action in Web Switching steps

• switching_code: the short code used when entering manual steps in Web Switching

• description: the description displayed in Web Switching, User Log, and Event Log

• undo_act_key: the act_key of the undo action, used when creating go-back steps in Web Switching

Valid values for act_cls/act_idx pairs:

act_cls	act_idx	Description
CONDADD	tag, note, <condition name>	Add a condition of the passed type
CONDDLG	tag, note, <condition name>	Display the edit dialog of conditions of the passed type.
CONDREM	tag, note, <condition name>	Remove a condition of the passed type.
Commissioning	Action	A commissioning action (automatically added by the Commissioning Tool). Use the commissioning action in the action_name (WSW_STEP_COMMISSION, WSW_STEP_DECOMMISSION, WSW_STEP_UNDO_COMMISSION, WSW_STEP_UNDO_DECOMMISSION).
DDS	CLOSE, OPEN	Close or open the device.
DDS	EARTH, EARTH_DW	Place or remove an earth/ground on the device. If the device is a switch, the Control Tool will display a side selection dialog.
DDS	MOMENTARY	Create a momentary on the device.
FLISR	ISOLATE_RESTORE	A FLISR Isolate & Restore block (automatically added when creating a FLISR plan.
HLMsg	NOOP	Comment steps. Also used as the first step of an aggregate.
JMS	<none>	An automatic JMService event step, used in the Event Log and User Log.
JMS	submit_calls, submit_amr_calls	Allows trainer to submit normal or AMI calls on or downstream from the selected device.
MTS	DISABLE_FLISR, ENABLE_FLISR	Disable or enable FLISR for the device.
Manual	NOOP	Manual steps.
NOOP	20, 30, <Number of seconds to wait>	Wait the specified number of steps. Only used by FLISR to wait for SCADA responses. The number of wait seconds is not supported outside of FLISR.
PFS	CREATE_FLA_FAULT, CREATE_FLISR_EVENT	Allows the user or trainer to trigger FLA and FLISR events with faults on the selected conductor.
SRS	PO_DOWN, PO_HERE, PO_UP	Move the outage downstream, to here, or upstream.
START	ControlEdit	Perform a model edit. See “Model Edit Configuration” for details.
Safety	Action	Safety actions. Use the action_name column to specify the action (issue, unissue, release, complete, abort)
ScadaCtrl	<1 and the attribute number, 2 and the attribute number>	Send a SCADA control for the passed digital attribute. Use 1 + the attribute to clear, and 2+ the attribute to set. For example, for attribute 3 (AutoReclose), you would set the act_idx to 13 to clear AutoReclose, and 23 to set AutoReclose.
Switching	Block	A Switching block. Use the action_name to specify the type of block (WSW_BLOCK_CONSTRUCTION, WSW_BLOCK_CUSTOM, WSW_BLOCK_DEFAULT, WSW_BLOCK_FAULT_LOCATION, WSW_BLOCK_ISOLATE, WSW_BLOCK_MAINTENANCE, WSW_BLOCK_NOMINAL, WSW_BLOCK_RESTORE)
WCE	submit_call, submit_amr_call	Allows trainer to submit a normal or AMI call for a specific customer. The description column will be used as the resulting step's Details column. There are substitution parameters available for the WSW_STEP_CALL_ENTRY action: • $ACCOUNT_NAME: the customer name or address, if name is empty. • $CODE_NAMES: trouble code short descriptions, delimited by a dash. This is similar to the Work Agenda's Clues column. Empty for AMI calls. • $COMMENT: the call comment. Populated only for calls submitted using Web Call Entry.
WSW_BLOCK_SCADA_SHED	Block	SCADA block of shed steps in Load Shed sheet.
WSW_BLOCK_SCADA_RESTORE	Block	SCADA block of restoration steps in Load Shed sheet

CONTROL_AGGREGATES Database Table Configuration

The CONTROL_AGGREGATES table lists the aggregate Control Tool actions in the order they are to be executed.

Note: Aggregates should not contain any SCADA actions because SCADA responses return to the NMS one at a time. As such, they need to be configured as separate actions and separate switching steps.

Definition

• parent_act_key: The first act_key, from the CONTROL_ACT table

• act_key: The nth act_key, also from the CONTROL_ACT table

• sequence_number: The order of the action

For example, if you had CONTROL_ACT records for:

• 100: HLMsg::NOOP, "Open & Tag"

• 200: DDS::OPEN, "Open"

• 300: CONDADD:tag, "Place Tag"

Then you would enter the following rows in your CONTROL_ACGGREGATES table:

• parent_act_key=100, act_key=200, sequence_number = 1

• parent_act_key=100, act_key=300, sequence_number = 2

CONTROL_ACT_PROMPTS Database Table Configuration

This table holds the attributes that are presented to the user when creating or editing a model edit. Model edit CONTROL_ACT records hold all their configuration parameters in the DESCRIPTION field. This field can contain user-editable parameters that are defined by $PROMPT(<name>). For example, the P-P Cross Phase Prompt... is defined in the CONTROL_ACT table as follows:

INSERT INTO control_act

(act_key, act_cls, act_idx, action_name, label, instruct_label,

switching_desc, switching_code, description, undo_act_key)

VALUES

(451, 'START', 'ControlEdit', 'ACT_PPCROSS', 'P-P Cross
Phase Prompt...', '', '', '', '‑jumper ‑status 0 -nominal 0 ‑deviceCls 447 ‑gapLength 20 ‑crossPhase ‑handle $DEVICE ‑alias $PROMPT(JmpAlias) ‑cesuser $CESUSER ‑x $WX ‑y $WY ‑symbolCls 44707 ‑coordSys $COORDSYS', 0);

This means that the user is presented with a "JmpAlias" prompt when creating the jumper, so this JmpAlias needs to be defined in the CONTROL_ACT_PROMPTS table:

INSERT INTO control_act_prompts

(prompt_key, prompt_string, required, data_type, default_value, list_values)

VALUES

('JmpAlias','Jumper Alias','Y','string','Jumper_$WX_$WY','');

These prompts are also used when editing model edit attributes. In this case, the prompt_key needs to match the column in the attributes view for that device class. See “Model Edit Configuration” for details.

The Control.xml File

Once you have defined the control actions, you need to specify which buttons to appear on the Control Tool for the device classes. You also need to map these buttons to the control actions that were defined in the CONTROL_ACT table, and you need to create JBot actions to match the CONTROL_ACT.action_name values.

Set up your <Button> or <PopupMenuItem> element like any other JBot button, but with a few important differences:

• Use the data_source attribute to list "DS_LABELS.<the button name>" or "DS_LABELS.<the button name>:INSTRUCT" to use the CONTROL_ACT.label or CONTROL_ACT.instruct_label.

• Set the <Visible> element based on the inheritance or the device class itself. It is recommended that you set up parent classes in your [project]_inheritance.dat for each logical grouping of device classes that will have different Control Tool options, then use those in these "when" clauses. For example:

• Add <ControlActions> and <ControlAction> elements to list the CONTROL_ACT keys to use for each device class or group of device classes. List the actions in order and use the "when" clause so the Control Tool knows which CONTROL_ACT record you want to use for each device class. The first matching CONTROL_ACT key will be used. You can configure a default at the end of the list with no "when" clause to catch all others that do not match earlier keys. For example, you may configure different actions and button labels for an Open button (Disconnect Generator, Disconnect Jumper, Open Switch, etc.):

</ControlActions>

• List the JBot actions to perform in the <PressPerform> element. For operations and other actions you record in switching, you should always add an ACT_BEGIN_ACTION and an ACT_END_ACTION call to set flags, reset the control tool, and prepare it for the next user action.

Note: buttons that only display other tools do not need the ACT_BEGIN_ACTION and ACT_END_ACTION actions.

Pass the $INSTRUCT_FLAG$ to the ACT_BEGIN_ACTION as true if this is an instruct button. Pass the $SEND_TO_SWITCHING$ flag to the ACT_END_ACTION if this actions should be recorded in Switching or the Misc Log.

• List the JBot action you configured as the CONTROL_ACT.action_name between the ACT_BEGIN_ACTION and ACT_END_ACTION actions. For example:

</Command>

</Command>

</Command>

</PressPerform>

Example Configuration

</ControlActions>

</ValidValues>

</Command>

</Command>

</Command>

</PressPerform>

</PopupMenuItem>

Mapping CONTROL_ACT Database Records to JBot Configuration

The Control.xml file defines a list of buttons and a <ControlAction> to perform when each button is pressed. The <ControlAction> "key" attribute should match the CONTROL_ACT.act_key in the database.

In the <PressPerform> element, the button should then prepare for an atomic action by calling the "ACT_BEGIN_ACTION", the specific action (as defined in a CONTROL_ACTIONS include file), then the "ACT_END_ACTION". In general, the button's specific action should match the CONTROL_ACT.action_name. All actions that are executed in the <PressPerform> element need to be defined in a CONTROL_ACTIONS include file.

When the recorded switching step is later instructed or executed in Web Switching, the CONTROL_ACT.action_name for this key is used to determine the correct action (from the CONTROL_ACTIONS include file) to execute. Any CONTROL_ACT.action_name actions that are not defined in a CONTROL_ACTIONS include file will error when attempting to instruct or execute the step in Web Switching

Commonly Used Flags and Datastore Values

Commonly used flags and datastore values that can be used in when clauses:

• OPEN_DEVICE/CLOSE_DEVICE: Open/Close are valid actions based on the state of the device.

• DS_CONTROL_DEFAULT.CURRENT_MODE: RT (real-time) or STUDY.

• DS_CONTROL_TOOL.DEVICE_CLASS_PARENTS: A set of all parent classes for the selected device.

• DS_CONTROL_TOOL.DEVICE_CLASS: The selected device class name.

• HAS_<condition class name>: Whether a condition of the class (capitalized) is active on the device. (For example, HAS_INSTRUCT, HAS_TAG, HAS_NOTE, etc.).

• HAS_<condition>_<status 0-10>: Whether a condition with status 0-10 is active on the device. (Example: HAS_INFO_0, HAS_HOLD_2, etc.).

• SCADA_OPERATED: If there is SCADA telemetry on the device status point.

• SCADA_CONTROL: If there is outbound SCADA control on the device status point.

• HAS_MEAS_<SCADA measurement>: Whether the device has a SCADA measurement (analog or digital) with the name (capitalized). (For example, HAS_AUTORECLOSE, HAS_AMPS, etc.)

• <SCADA measurement>_ON/<SCADA measurement>_OFF: Whether the digital measurement is ON or OFF. (For example, AUTORECLOSE_ON, AUTORECLOSE_OFF, FAULT_INDICATOR_ON, etc.)

• DS.CONTROL_TOOL.QUALITY_<scada measurement>: Datastore value is set to the quality string of the measurement. For example, QUALITY_STATUS might be blank (no quality), QUALITY_AUTO_RECLOSE might be M (manual), and QUALITY_AMPS might be IM (manual and inhibited).

• DS.CONTROL_TOOL.QUALITY_<scada measurement>_BITS: Datastore value is set to a bitwise integer containing all the quality bits.

• DS_LOGIN_ENTRY.WEB_SWITCHING_ENABLED: true or false.

• FROM_SWITCHING: Whether the action is being instructed or completed from Web Switching.

• HIDE_CONTROL_TOOL: Option

• INSTRUCT_ONLY: Whether the action being executed is an Instruct (as opposed to a Complete).

• IS_OPENED: The device is opened on all phases.

• IS_CLOSED: The device is closed on all phases.

• IS_ISOLATED: The device is marked as an isolation point.

• IS_SECURED: The device is marked as a secure point.

• IS_IGNORED: The device is ignored, either because it is pending construction or is decommissioned.

Optional Project Status Flags

• HIDE_CONTROL_TOOL: if set implemented in the project Control.xml and set to ‘true,’ this flag will close the Control Tool when another device is selected in the Viewer. If set to false, the Control Tool to remain open. This option is not included in the product version of Control.xml.

To implement this option, add the following (with or without the comment at the beginning of the code snippet) to the project Control.xml file:

</Command>

</Perform>

Project_Control_Actions.inc Include File

The product Control.xml file includes the CONTROL_ACTIONS.inc file, which contains all of the product <Action> definitions. Project-specific actions should be defined in a PROJECT_CONTROL_ACTIONS.inc file.

Note: You may find it useful to use the CONTROL_ACTIONS.inc as an example.

The following example illustrates how to define an action to add an Information tag. The condition class, info, is defined in the CLASSES table.

</Command>

</Action>

Web Switching executes actions when you instruct or complete steps in Web Switching; therefore, if there is any validation needed to prevent execution or completion of steps based on device states, you should add it to the <Action> element, using DisplayErrorCommand. You may add any number of specific error messages.

If you wanted, for example, to enforce that the system can only place an informational tag on a device that has no active instructs, then you could add the following:

</Command>

</Command>

</Action>

And in MessageCode_en_US.properties, you would need the following:

CANNOT_HAVE_INSTRUCT=Cannot perform this action when an instruct
is present.

CANNOT_HAVE_INSTRUCT.title=Action Failed

Or you might only want to perform that check for instructs if the user is not instructing the current action:

</Command>

</Command>

</Action>

And if, for example, you also wanted to make sure the tool is in study mode, you could add another specialized message before or after the other message:

</Command>

</Command>

</Command>

</Action>

and:

CANNOT_USE_RT=Cannot perform this action in real-time mode.

CANNOT_USE_RT.title=Action Failed

Using the Control Config Generator

The NMS Control Config Generator is a stand alone application that is used to read the Control Tool workbook, parse the contents, and generate the desired configuration files.

Below is a list of all files that can be generated with a brief description. Notice that [project] indicates that the files generated pertain to a specific project configuration.

Generating Data Files

1. Make the appropriate changes to the Control Tool workbook.

2. After the changes are made, open the Control Config Generator Tool from the command line by using one of the following methods:

a. On Unix, launch the generator by running the following script:

$NMS_BASE/bin/control‑config‑generator

b. To run on a Microsoft Windows PC, your first need to zip the NMS_BASE/bin/ControlConfigGenerator directory by running the following command on a Unix terminal:

zip -ry ControlConfigGenerator.zip $NMS_BASE/bin/ControlConfigGenerator

Then move the zip file to the PC, unzip the file, and then navigate to the ControlConfigGenerator directory, and double-click the ModelConfigGenerator.jar file to launch it (assuming java is installed).

3. Enter the project name, if it is not populated.

4. Browse to the location of the modified Control Tool Workbook.

The tool will read the workbook into memory.

5. Browse to a location where you want to save each of the configuration files.

6. Click Generate to generate the configuration files.

The Control Tool Generator Tool will generate the desired configuration files and create reports for any errors encountered.

7. The resulting files should be manually merged into the standard configuration files, as described above.

Configuration Example: Adding an Undo Close Action

Adding the Undo Close function to the Control Tool requires modifications to the project CONTROL_ACTIONS.inc, Control.xml, and Control_en_US.properties files.

Editing CONTROL_ACTIONS.inc

Add the ACT_UNDO_CLOSE action:

<Config name="breaker_info_fields"

value="FEEDER_ID_1,NOMINAL_VOLTAGE, INTERRUPTION_RATING"/>

</Command>

</Command>

</Action>

Editing Control.xml

Add the button/menu item to Control.xml.

Note: The value of control action key will depend on the project's configuration.

<Visible initial="false"

when="{DS_CONTROL_TOOL.DEVICE_CLASS_PARENTS == 'switch'}"/>

<ControlAction key="6480"

when="{DS_CONTROL_TOOL.DEVICE_CLASS_PARENTS == 'switch'}"/>

</ControlActions>

</ValidValues>

</Command>

</Command>

</Command>

</PressPerform>

</PopupMenuItem>

Control_en_US.properties

Add label and tooltip for the new button/menu item.

BTN_UNDO_CLOSE.text = Undo Close

BTN_UNDO_CLOSE.tooltip = Undo latest close operation for the selected switch

Control Tool Options in the Viewer Context Menu

Control Tool options in the Viewer’s context menu are configured in the VIEWER_POPUP.inc file. The context menu options reference Control.xml buttons and automatically use their <Visible> and <Enabled> elements.

When you right‑click in the Viewer, a call is configured to the ViewerRightClickCommand. This command populates the Control Tool data stores; based upon the visibility and enabled property of different buttons and menu items, it will make the Control Tool menu items visible in the Viewer’s context menu. These Viewer menu items need to have names that match the Control Tool buttons, but with MNU_ prefixes instead of BTN_ prefixes.

You can optionally pass the menu_names parameter to the ViewerRightClickCommand command. The menu_names parameter lists the context menu names to consider when looking for matching Control Tool buttons. OPERATE_POPUP is included by default. Include any additional context menus and separate them with commas.