Switching Steps
Manual Step Addition
Web Switching normally records steps initiated from the Control Tool. So as not to clutter the Control Tool menu options, steps can also be added to a switching sheet's steps list using the Manual Step Addition (MSA) form. The form is capable of adding actions that may or may not be available from the Control Tool. The list of available actions are also filtered based on the device that is selected. If you have actions configured on the Control Tool and the control action has a switching code associated to it, then that action will be available for selection within the MSA form.
The first step in configuring an action for inclusion on the MSA form is to give the associated control action record in the CONTROL_ACT table a unique switching_code value. In the following example the action Check Open has a switching code equal to 'co'.
INSERT INTO control_act
(act_key, act_cls, act_idx, action_name, label, instruct_label,
switching_desc, switching_code, description, undo_act_key)
VALUES
(1550, 'HLMsg', 'NOOP', '', 'Check open', 'Instruct Check open',
'#swmanStep.deviceAlias%Check open {0}', 'co', 'Check open $ALIAS', 0);
Once your action have been configured in the control_act table, the next step is to configure a popup menu item on the Control Tool. The action does not need to be visible to the user from the Control Tool, but must be associated to a popup item or button on that tool. The Control Tool configuration for the button defines when the option is available for selection within the MSA form. For options that should not be visible to the user, then add the items within the HIDDEN_MANUAL_POPUP section within your Control.xml configuration. For instance the Check Open option is not available to the user on the Product Control Tool GUI, but if a switchable device has been populated into the MSA form, then the following operation will be available to the user:
<PopupMenuItem class="javax.swing.JMenuItem" name="BTN_MANUAL_CHECK_OPEN">
<Enabled initial="true"/>
<Visible initial="true"/>
<ControlActions>
<ControlAction key="1550" when="{DS_CONTROL_TOOL.DEVICE_CLASS_PARENTS == 'switch'}"/>
</ControlActions>
<PressPerform>
</PressPerform>
</PopupMenuItem>
The above Menu Item allows control action 1550 (Check Open) to be available to every device that inherits from class 'switch'.
State Transitions
State transitions for the switching sheet steps are all configured in the TE State Transition database tables where the app value to each of the tables is set to WSW.
Note: See tables te_valid_states, te_status_groups, te_statuses, te_state_transitions, te_state_actions, te_expressions, te_init_state_rules, te_state_callbacks, and te_state_cb_args for more information.
Do not cross reference step and sheet states. Keep them completely separate. For example, create a state for the step Completed state and another state for the sheet Completed state. Do not try to use a single state for both the sheets and the steps.
Control Tool Actions
Web Switching Management uses the same rules that the Control Tool uses to determine if a control action is valid or not. Product configuration is configured to keep the two tools in synch. If the Control Tool does not allow an Open operation on a device, then a switching step with that same action will not allow the operation either. To get around this, the JBot flag FROM_SWITCHING can be used within the control/xml/Control.xml file and its include files to give actions alternate rules when the action originates from Web Switching Management. For more information, see the Control Tool Configuration chapter.
Step Columns
Switching step column data is stored in the SWMAN_STEP table. Here are examples of how to reference a value from each of the tables.
SWMAN_STEP
key="swmanStep.comments"
For more information on the list of available data source values, refer to the DS_STEPS datastore documentation. Additional project-specific columns can be added to this table. The mapping for these columns is configured in the eclipselink-orm.xml file. See
Configuring Project-Specific Columns for more information.
Device Conditions
Web Switching has an optional Steps column that can be added to display a list of conditions that were on a device when the switching step was added. The conditions list will not dynamically update after the step is added and will only be populated when the step is recorded or manually added through the Manual Step Addition form.
To add enable the population of a conditions column in the Steps table, the following configuration changes will be required.
1. [project]\jconfig\override\fwserver.jar\META-INF\eclipselink-orm.xml:
A new step extension field with the name 'DEVICE_CONDITIONS' will need to be added to eclipselink-orm.xml file within the SwmanStep and SwmanStepView entities.
<basic name="DEVICE_CONDITIONS" access="VIRTUAL" attribute-
type="String">
<column name="DEVICE_CONDITIONS"/>
</basic>
The population of the device conditions field is triggered based on the field name, so the field name cannot be altered. See
Configuring Project-Specific Columns for more details on creating a project specific version of the eclipselink-orm.xml file.
2. [project]\sql\[project]_retain_web_swsheets.sql
Add a new character column called 'DEVICE_CONDITIONS' to the SWMAN_STEP table.
3. Update the JBot table definition for the Steps table and add the new column. Changes will be required in files:
• [project]\jconfig\ops\webswitching\properties\SwmanSteps_en_US.properties
• [project]\jconfig\ops\webswitching\xml\SwmanSteps.xml
Device Attributes (Addresses)
Switching Sheet Steps
One specialized capability that the switching steps have not related to step execution is the ability to update device attribute information. When the command SaveAttributesCommand is called with a switching step extension field name, the value updated in the step for that device is propagated to the other steps in the steps list and is also passed to the device's associated attribute table. From this point on, when the device is used to record switching steps, the newly saved attribute information is displayed. In Product configuration, we utilize this feature for device address information, which is normally stored in the LOCATION field of the attribute tables. The location data is accessed through the database view ATT_SUPPLEMENTAL_ATTRIBUTES. This view is model specific and has to be defined by each project. Here is an example of the view, which should be placed into the projects sql/[project]_schema_supplemental_attributes.sql file:
CREATE OR REPLACE VIEW att_supplemental_attributes (h_cls,h_idx,active,location,substation,voltage,feeder_name)
AS
(SELECT a.h_cls,
a.h_idx,
a.active,
TO_CHAR(a.location),
TO_CHAR(a.control_zone_4),
TO_CHAR(a.gmd_voltage),
TO_CHAR(NVL(a.feeder_id_1, a.control_zone_5))
FROM att_breaker a
WHERE a.active IN ('Y', 'A')
UNION
SELECT a.h_cls,
a.h_idx,
a.active,
TO_CHAR(a.location),
TO_CHAR(a.control_zone_4),
TO_CHAR(a.gmd_voltage),
TO_CHAR(NVL(a.feeder_id_1, a.control_zone_5))
FROM att_transformer a
WHERE a.active IN ('Y', 'A')
UNION
SELECT a.h_cls,
a.h_idx,
a.active,
TO_CHAR(a.location),
TO_CHAR(a.control_zone_4),
TO_CHAR(a.gmd_voltage),
TO_CHAR(NVL(a.feeder_id_1, a.control_zone_5))
FROM att_elbow a
WHERE a.active IN ('Y', 'A')
UNION
SELECT a.h_cls,
a.h_idx,
a.active,
TO_CHAR(a.location),
TO_CHAR(a.substation_name),
TO_CHAR(a.nominal_voltage),
TO_CHAR(a.feeder_id_1)
FROM att_generator a
WHERE a.active IN ('Y', 'A')
);
Each project should add any additional device types that are configured to be included in recordable device operations.
When defining a device attribute extension field for a step that should be automatically populated via the ATT_SUPPLEMENTAL_ATTRIBUTES database view, specify the extension name in lower case form. Mixed and upper case extension field names will not work.
The model attributes updated by Web Switching will be removed each time the attribute is updated from the GIS. This update can be setup to be ignored if a GIS update comes through with the old attribute value. In other words, we retain the attribute update from Web Switching as long as the GIS attribute value coming in is different. For more information, see chapter Building the System Data Model.
Switching Sheets and Safety Documents
Device attributes can also be populated into switching sheets and safety documents. The database view called ATT_SUPPLEMENTAL_ATTRIBUTES is used to populate these fields. This is the same view used to populate attribute values into switching sheet steps. In order for the JBot tool to include the attribute into a text field, the attribute has to be included as a column in the ATT_SUPPLEMENTAL_ATTRIBUTES database view.
To include attributes into a JBot text field, use the command UpdateAttributeValuesCommand. See the command's documentation for further details. With this command, a text field can be configured to be populated with a distinct comma delimited list of attribute values. For Product configuration, the values are pulled using the sheet device, step devices and for safety documents, the safety document devices.
The command can be used in any JBot tool, so the functionality is not limited to just Web Switching and Web Safety.
The ATT_SUPPLEMENTAL_ATTRIBUTES database view can also be setup as a database table and can be populated and maintained like any other attribute table. It is up to the project to determine which method is easier to maintain. The project's modeling personnel would have to be involved if the view is converted to a table. Product also includes a script to help with the initial definition of the ATT_SUPPLEMENTAL_ATTRIBUTES database view. See script nms‑generate‑supplemental‑attributes‑view and configure the header section of the script before running the script on your project. The script will output the statements needed to be included in the project file sql/[project]_schema_supplemental_attributes.sql. Read the comments in the header section of that script for more details. The script should be used to generate a baseline version of the view. It may not generate a perfect version of the database view and further updates should be made to the generated SQL instead of trying to update the script.
SCADA Auto-Transitioning
You can enable or disable auto-transitioning of SCADA switching steps using the AutoTransitionSCADASteps property, which is a property found in the SwmanParameters.properties file. If auto-transitioning is allowed, as it is in the product configuration, the property is set to true:
AutoTransitionSCADASteps = true
To disable auto-transitioning of SCADA switching steps, set the property to false:
AutoTransitionSCADASteps = false
View Areas
Each switching sheet creates a Dynamic View Area that is created the first time the sheet is saved. The default Auto-load viewer for this view area is "None." If your project would like the dynamic view area to be auto loaded into a particular viewer each time the switching sheet takes focus, then set the following parameter in each of the Swman<Sheet Type>Tool.xml configuration files. For instance, set the following property in SwmanPlannedTool.xml.
<StringProperty name="view_area.auto_load_unset_value"
value="VIEW;0;2"/>
The view_area.auto_load_unset_value property should be assigned one of the valid key values as defined for the CMB_VIEWER_NAME combo box configured in the TBL_VIEW_AREA JBot table. For Product configuration, the possible values include VIEW;0;1, VIEW;0;2 or none. By default "none" is used if the property is not defined.
Toggling Study Mode
Each sheet type can be configured with one or more Viewers that track the mode change. This is configured with the "switching.connected_viewers" property. For product, this is configured to just track with Viewer1, but, for example, you can change your SwmanPlannedTool.xml to make both Viewer1 and Viewer2 toggle into and out of study mode along with your sheet:
<StringProperty name="switching.connected_viewers" value="Viewer1,Viewer2"/>
Step Order Execution Rules
Each switching sheet type can be configured to force in-order step execution rules. When the rule is enforced, the Instruct, Complete, Abort and Fail options will only be enabled when all the steps prior to the selected step have been Instructed, Completed, Aborted or Failed. The same rule can also be applied for grouped steps. Normally, the sheets are configured so that grouped steps have the opposite rule applied to them so that users have the option of having some steps following the rule and others more relaxed.
The two rules are each defined in the Swman<Sheet Type>Tool.xml files. They are:
<BooleanProperty name="out_of_order_execution" value="false"/>
<BooleanProperty name="group_out_of_order_execution"
value="true"/>
out_of_order_execution: When set to true, steps in a switching sheet can be Instructed, Completed, Aborted and Failed in any order. For Product configuration, this is set to True for Emergency switching sheets. Planned, Outage Correction and Template sheets have this option set to false.
group_out_of_order_execution: When set to true, steps in a step grouping can be executed out of order. If out_of_order_execution is set to true, then any steps listed prior to a grouping have to be completed before these steps can be completed out of order. For Product configuration, this option is set to true in Planned and Template sheets. It is set to false in Emergency and Outage Correction sheets.
To alter the step execution rules for a sheet type, simply alter these values in your project version of the Swman<Sheet Type>Tool.xml file.
Instructed Actions
Web Switching and the Control Tool have options to treat instructed actions as if they are completed when performing a new instruct action. When configured, instructed steps in the active sheet will be considered as completed when computing the Look Ahead and associated dialogs.
For example, say you recorded an Instruct Tag step. With this option configured, you would be allowed to record an Instruct Remove Tag step with no errors. Without this configuration, you would receive an error that you cannot remove a tag that is not already applied.
This is useful for projects that instruct multiple steps to a crew at a single time. This is the default behavior for product configuration.
This configuration resides in two places, since each governs a slightly different aspect of this behavior. If you wish that instruct actions validate against the current active model, you will need to unconfigure each of these two pieces. This is not recommended unless your project instructs one step at a time.
1. In CONTROL_ACTIONS.inc, the CollectInstructedStepsCommand call in the ACT_BEGIN_ACTION Action tells the Control Tool to consider instructed steps in the current sheet. This means that an active sheet that is recording in the same mode as the Control Tool will change the Look Ahead and all associated warnings and errors to display results as if the instructed steps were already completed. This only occurs when instructing an action in the Control Tool. Remove this Command if you do not desire this behavior.
2. In SwmanStepsHeader.xml, the "apply_instructed_steps_to_lookahead" option is passed as true to the ExecuteStepsCommand so that the sheet's instructed steps affect the Look Ahead and associated dialogs, as above. This is only valid for "instruct_step" actions. Change this to false if you do not desire this behavior.
Configuring the Sensitivity of Step Execution Buttons
The DS_SWITCHING_DEFAULT.VALID_ACTIONS data element contains a list of all actions names that are available for the selected step(s) but not for any previous steps. For example, for a sheet that uses in-order execution, you would want the Complete button to be enabled when the selected step(s) are the next steps that can be completed. So, DS_SWITCHING_DEFAULT.VALID_ACTIONS would need to contain:
"SWS-complete_step":
when="{DS_SWITCHING_DEFAULT.VALID_ACTIONS == 'SWS-complete_step'}"
The DS_SWITCHING_DEFAULT.REVERSE_VALID_ACTIONS data element contains a list of all actions names that are available for the selected step(s) but not for any subsequent steps. For example, for a sheet that uses in-order execution, you would want the Uninstruct button to be enabled when the selected step(s) are the last steps that can be undone. So, DS_SWITCHING_DEFAULT.REVERSE_VALID_ACTIONS would need to contain:
"SWS-uninstruct_step":
when="{DS_SWITCHING_DEFAULT.REVERSE_VALID_ACTIONS == 'SWS-uninstruct_step'}"
Switching Sheet Email Attachment Configuration
Web Switching Management’s default behavior when emailing a switching sheet is to automatically name the switching sheet and attach the file to a new email message. The default naming convention is:
• {sheet type}_{sheet index}.{report format}
Examples:
• Planned_1003.pdf
• Emergency_1004.rtf
An alternative configuration option allows you to provide the user with a Save As dialog to name the switching sheet prior to attachment to the message. To implement this option, you will need to change the value of the $SKIP_SAVE_DIALOG$ parameter from true to false in any of the files that you wish to turn the Save As dialog on for:
• SwmanPlannedTool.xml
• SwmanEmergencyTool.xml
• SwmanOutageCorrectionTool.xml
• SwmanTemplateTool.xml
• SwmanTrainingTool.xml
• SwmanVoltVarTool.xml
• SwmanStandAloneSafetyTool.xml
• SwmanLoadShedTool.xml
To force the Save As dialog for all the sheet types and for stand alone safety documents, set the $SKIP_SAVE_DIALOG$ parameter from true to false in the following files:
• SwmanToolBar.xml
• SwmanStandAloneSafetyMenuToolBar.xml
Automatic Crew Population Option for Steps
As part of standard Product configuration, the step’s Instructed To field is populated by selecting a step followed by a crew from the switching sheet’s Crews list. This method can also be used to pre-assign steps to crews. However, this may not line up with the business process of every project. In some cases, it may be more appropriate to automatically populate the steps based on the crews assigned to the switching sheet.
Note: If this is a requirement for your project, then review the manual migration details for bugs 25469645 and 26101215.