Switching Sheets

Automated Emails

Web Switching along with BI Publisher reports, supports the ability to automatically send emails triggered by the user through button selections or through state transitions of a switching sheet. The emails can be setup to be sent to a pre-configured recipient and/or addresses pulled from the switching sheet's data fields.

It should be noted that these automated email requests are fulfilled from WebLogic and the user's email client is not involved in this method of emailing switching sheets.

If any value specified in the TO, CC or BCC fields of the email are not properly formatted like an email address, then this will result in the email not being sent. If the email request was initiated from the NMS client application,then an error dialog will be displayed to the user. If the emails are part of a back-end state transition request, then an error will be displayed in the server log.

One method for initiating the automated emails is to configure the action as part of the sheet's TE state transitions. Below is an example of the callback and arguments used to generate the automated email behind the scenes. Any errors will not be displayed back to the user.

INSERT INTO te_state_callbacks

(app, cb_key, state_key, condition, action, abort_on_fail, can_undo,

error_code)

VALUES

('WSW', 155, 170, 'PRE_ENTER', 'email', 'Y', 'N', -155);

INSERT INTO te_state_cb_args

(app, cb_key, arg_key, arg_name, arg_value)

VALUES

('WSW', 155, 140, 'REPORT_TYPE', 'SwitchSheetsStateEmail');

INSERT INTO te_state_cb_args

(app, cb_key, arg_key, arg_name, arg_value)

VALUES

('WSW', 155, 150, 'REPORT_SUBTYPE', '$swmanSheetCls.switchSheetCls$');

Another method is to use the JBot command ExecuteStateCallbackCommand. In this case you'll need to make a call to the callback method SendEmailJob and pass in arguments like what was done with the TE state arguments. This JBot command allows you to use the same configuration to initiate state transition based emails along with client initiated emails based on user actions.

</Command>8

Once the initiating calls are in place, the back-end configuration needs to be applied. This all occurs from within the SwmanUserText_en_US.properties file. Below is an example of the different options and arguments used to create the emails.

# Automatic emailing of switching report. The email will only be

# sent out if the email_to field value is not empty. Variables are derived

# from the SwmanSheet object and not a datastore, thus the variables are

# wrapped in "$" symbols. Extension values have to start with "extensions.".

# BI Publisher report location, template name and type.

BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.report_location = /WebSwitching/Templates.xdo

BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.report_template = PlannedSheet

BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.report_format = pdf

# The optional user_flag is a value on the sheet that the user can alter

# to disable automatic emails for this request. The flag has to have a

# value of Y, Yes, or True to cancel the email request.

#BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.user_flag = $extensions.disableEmailNotifiations$

# Indicate report parameters here delimited by semicolons.

# Example: SHOW_STEPS=false; SHOW_DEBUG=true;

BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.report_params = SHEET_CLS=$swmanSheetCls.switchSheetCls$; SHEET_IDX=$switchSheetIdx$; ATTACH_EXTERNAL_DOCUMENTS=true;

# The filename of the report to generate.

BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.base_file_name = $swmanSheetCls.switchSheetType$_$switchSheetIdx$

# The email subject.

BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.email_subject = Scheduled Switching Sheet - $swmanSheetCls.switchSheetType$ $switchSheetIdx$

# If an email_from value is not given, then the user's login ID is used along with

# the username_to_email database query specified in the CentricityServer.properties file.

# That query can be used to apply a domain to the user's ID or to translate a user's ID

# to a valid email address. If your project prefers to keep the "from" email address

# generic, then uncomment the following parameter and specify an email address.

#BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.email_from = no_reply@somedomain.com

BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.email_to = $extensions.RequesterEmailAddress$

#BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.email_cc = $extensions.EmailAddress2$

#BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.email_bcc = $extensions.GroupEmailAlias$

# This is text that will show up in the body of the email that will be sent

# out. The Switching Sheet report will be an attachment to the email. If

# external documents are included, then they will be attached to the email

# as well.

BIP_GENERATE_REPORT.SwitchSheetsStateEmail.3117.email_body = Email body message for $swmanSheetCls.switchSheetType$ $switchSheetIdx$.\n\nSwitching Sheet Description: $extensions.Description$.

Sheet Types

Each of the switching sheet types are defined in the SWMAN_SHEET_CLS configuration table. Each switching sheet type has its own class. See Configuring Classes and Inheritance for further details on adding a class.

Within the SWMAN_SHEET_CLS configuration table, define which JBot tool configuration should be used when the sheet is loaded within the Web Workspace environment. The switching sheet types can either share the same configuration or have their own. For instance, multiple Planned switching sheet types can all use the same SwmanPlannedTool definition and then within the tool configuration, define minor differences between the types based on the class of switching sheet being displayed.

State Transitions

State transitions for the switching sheets and their individual 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.

Web Switching sheets support the following callbacks.

Callback Action Name	Description
safety_state_check	Determine if the sheet's associated safety documents are in the completed state. Switching sheets should not be completed when there are outstanding safety documents still issued to crews.
unrestored_pln_check	Determine if the switching sheet has any unrestored Planned events associated to it. In most cases, Planned switching sheets should not leave customers out of power.
create_switching_job	Create the Master switching sheet event that is normally used for Planned switching sheets.
complete_switching_job	Complete the Master and any Planned events associated to the switching sheet. This callback is normally used by Planned switching sheets.
remove_crews	Removes the crews that are associated to a switching sheet. This is normally initiated after a switching sheet has been completed.
update_dms_job	Update a dms job associated with the switching sheet. This is used by VVO.

The following is an example for the Issue state:

INSERT INTO te_state_callbacks

(app, cb_key, state_key, condition, action, abort_on_fail, can_undo,

error_code)

VALUES

('WSW', 130, 232, 'PRE_ENTER', 'safety_state_check', 'Y', 'N', -130);

INSERT INTO te_state_callbacks

(app, cb_key, state_key, condition, action, abort_on_fail, can_undo,

error_code)

VALUES

('WSW', 140, 232, 'PRE_ENTER', 'unrestored_pln_check', 'Y', 'N', -140);

INSERT INTO te_state_callbacks

(app, cb_key, state_key, condition, action, abort_on_fail, can_undo,

error_code)

VALUES

('WSW', 160, 232, 'PRE_ENTER', 'complete_switching_job', 'Y', 'N', -160);

The error_codes are used to display distinct dialog messages to the user when the action fails. The messages for these error codes are configured in the MessageCode_en_US.properties file.

The following is an example for error code "-130", which was referenced in the above te_state_callbacks example.

OmsClientException.WSW.STATE.CALLBACK.130 = Not all safety documents are completed

OmsClientException.WSW.STATE.CALLBACK.130.title = State Transition Failed

Sheet Data Fields

Data fields in this case are in reference to the fields found on the Request tab of the sheet. Data fields can be found anywhere on the sheet, but Product configuration has grouped the majority of them to one tab. The data fields are stored in the SWMAN_SHEET table.

The following is an example of how to reference a value from the table.

SWMAN_SHEET

For core values not defined in the eclipselink-orm.xml file, the following format should be used.

data_source="DS_SWITCHING_SHEET_LOCAL.deviceAlias"

For any fields defined in the eclipselink-orm.xml file, use the following format:

data_source="DS_SWITCHING_SHEET_LOCAL.extension.RequesterPhoneNumber"

For more information on the list of available data source values, refer to the DS_SWITCHING_SHEET datastore documentation.

Open Switching Sheet List

The Open Switching Sheet list is populated through the DS_OPEN_SWITCHING_SHEET_LIST datastore, which is populated from the view SWMAN_SHEETS_LIST. The amount of data displayed in this list should be kept to a reasonable level. The more data that is displayed, the longer it will take the dialog to be displayed. The list of sheets populated into the list should be limited as much as possible for performance reasons. This is done by specifying a where clause in the "additional_constraints" configuration parameter of the DisplayOpenNMSDialogCommand command. This where clause is applied when querying the SWMAN_SHEETS_LIST database view. Projects can configure any number of calls to this command with unique where clauses and have separately configured options on the Open Switching Sheet list to display different sets of switching sheets.

The Open Switching Sheet list is initiated from the Web Workspace File menu or toolbar. The command that initiates that request is DisplayOpenNMSDialogCommand. Refer to the NMS Commands documentation for further details about this command.

Not only should the where clauses be used to limit the amount of data being passed to the client, but the database view SWMAN_SHEETS_LIST should also be defined with only the extension fields that are displayed on the Open Switching Sheet list. Query for data not displayed on the GUI is wasteful and should be avoided.

New Switching Sheet List

The New Switching Sheet type list is populated through the DS_SWITCHING_SHEET_CLS datastore, which is populated from the SWMAN_SHEET_CLS database table. The pre-created sheet list displayed on this dialog is populated through the DS_NEW_SWITCHING_SHEET_TEMPLATE_LIST datastore, which is populated from the database view SWMAN_SHEETS_LIST. The amount of data displayed in this list should be kept to a reasonable level. The more data that is displayed, the longer it will take the dialog to be displayed.

The New Switching Sheet list is initiated from the Web Workspace File menu or toolbar. The command that initiates that request is DisplayNewNMSDialogCommand. This command accepts a where clause to use to gather the data from the database. The where clause is configured with the command’s "additional_contraints" configuration parameter. The same where clauses used by the DisplayOpenNMSDialogCommand can be used with this command as well. Refer to the NMS Commands documentation for further details about this command.

Search Switching Sheet

The Search Switching Sheet list is populated through the DS_SEARCH_SWITCHING_SHEET_LIST, which is populated from the SWMAN_SHEETS_LIST database view. The amount of data displayed in this list will be limited to 1000 entries.

The GUI and command calls are configured in the DLG_SEARCH_SWITCHING_DIALOG.xml file.

The Search Switching Sheet list is initiated by selecting Switching Sheet Search... from the Open option in the Web Workspace File menu. The SearchSwitchOrSafetyCommand command requests the search results. This command has a parameter called "search_fields" that limits the number of fields to search in within the SWMAN_SHEET_LIST database view. It is strongly advised that your project keep this list to a minimum since the more fields to be searched, the more intensive the query will be on the system.

Device to Sheet Operation List

The Device to Sheet Operation List is launched from the Control Tool for a device selected in the Viewer. The Device to Sheet Operation List is populated through the DS_DEVICE_SHEETS_LOCAL datastore, which is populated from the SWMAN_DEVICE_SHEET database view. The list displays the switching actions associated to the device. The view is configured to gather all the steps associated to active switching sheets and to also pull in the last 30 days worth of completed actions as well. The filtering criteria are defined in the oracle view, which can be redefined by copying the view definition from the nms_schema_web_swsheets.sql file and placing it into the project version of this file.The Product dialog DLG_DEVICE_SHEETS has been configured to only pull in the sheet extension value called "Description." If projects require additional fields in this dialog, then they will have to create a custom project version of this dialog and add the necessary fields to the table defined in the dialog.

Model Verification

The Web Switching service initiates a query each time it receives a notification of a model build or edit. When this notification comes through, the following query is initiated:

SELECT sheet.switch_sheet_cls, sheet.switch_sheet_idx,

step.step_cls, step.step_idx

FROM swman_sheet sheet, swman_step step,

network_components nc, swman_patches sp

WHERE sheet.seq_sheet_id = step.seq_sheet_id AND

// Exclude Block steps

step.parent_step_id IS NOT NULL AND

( (step.dev_cls = nc.h_cls AND step.dev_idx = nc.h_idx) OR

(step.gnd_node_cls = nc.port_a_cls AND

step.gnd_node_idx = nc.port_a_idx) OR

(step.gnd_node_cls = nc.port_b_cls AND

step.gnd_node_idx = nc.port_b_idx) ) AND

(nc.death > sp.patch_time OR nc.birth > sp.patch_time) AND

// Where the sheet and step are not in a termination state

step.state_key NOT IN (<<List of terminal step states>>) AND

sheet.state_key NOT IN (<<List of terminal sheet states>>) AND

sheet.switch_sheet_cls not in (<<Outage Correction Sheet Types>>)

ORDER BY step.seq_sheet_id, step.step_idx

The MB_EDIT field in the SWMAN_STEP table is updated for each of the step records returned by this query. These steps will have to be validated by the user before switching sheet step executions can continue in the switching sheet.

The switching sheet and step terminal states are determined by running the following query:

SELECT state_key FROM te_valid_states tevs

WHERE tevs.app='WSW' AND tevs.state_key NOT IN

(SELECT DISTINCT from_state_key FROM te_state_transitions te

WHERE te.app='WSW')

Default Crews

To configure default crews for switching sheets, add the following sections to [project]_web_swsheets.sql:

DELETE FROM swman_crews WHERE seq_sheet_id = 0;

INSERT INTO swman_crews(seq_sheet_id, crew_key)

SELECT 0, crew_key FROM crews WHERE active='Y' AND

crew_name IN ('Default_Crew_1', 'Default_Crew_2');

Replacing 'Default_Crew_1', 'Default_Crew_2' with a comma-separated list of the names of the default crews as they exist in the crews table.

The SWMAN_CREW_EVENT database view will also need to be updated to include the crews that were previously inserted into the SWMAN_CREWS table. Do this by including an "or" statement at the end of view definition so that all crews with seq_sheet_id equal to 0 are included.

or sc.seq_sheet_id = 0

The view definition can be found in file [project]_schema_web_swsheets.sql.

Versioning

Switching sheet versioning can occur manually or automatically. Product configuration is setup to automatically check in the switching sheet when it reaches the Issued state. This is done by initiating a call to the command CheckInSheetVersionCommand.

The version of a switching sheet will be automatically incremented when steps are manipulated (added, cut, pasted or deleted) within the sheet and when the switching sheet field CHECKED_IN has been set to Y. This field is stored in the SWMAN_SHEET table. The JBot flag VERSION_CHECKED_IN is set based on the value of the CHECKED_IN field. This flag is used by the JBot configuration to determine when to initiate commands based on version control.

Product configuration has been setup to increment the version automatically if any of the fields on the Request tab are altered. This is done by initiating the call to the command IncrementVersionCommand. This command will only execute if the switching sheet's CHECKED_IN database field is set to Y.

The current version of the switching sheet is stored in the REVISION field of the SWMAN_SHEET database table.

Versioning can be disabled globally for all the switching sheets through a global parameter DisableVersioning found in SwmanParameters.properties file. By default, Product Configuration has this value set to false. To disable all the versioning, one can set the DisableVersioning value to true.

If there is a requirement to enable versioning for a specific action when the global versioning is disabled(DisableVersioning is set to true), a "force" parameter can be used to force the checking in and incrementing of the sheet's version in the command calls to CheckInSheetVersionCommand and IncrementVersionCommand in required places.

For example:

</Command>

Overlaps

The switching sheet overlaps list uses the DS_OVERLAPS datastore. This datastore is populated from the SWMAN_OVERLAPS database view. The database view is defined in the product/sql/nms_schema_web_swsheets.sql file. This same view is used by the Global Overlaps list, so any changes to this view will impact that list as well.

Product is configured to only include sheets classified under the categories of PLANNED and EMERGENCY. The list is also filtered based on the state of the sheet. The list of state keys is included in the view definition. If any switching sheet states have been added to a projects configuration, this view may need to be redefined by the project.

External Documents

The switching sheet external documents list uses the DS_EXTERNAL_DOCUMENTS datastore. This datastore is populated from the SWMAN_SHEET_DOCUMENTS database table.

This functionality can be limited to certain file types. See the “Attachment Security” for more details.

The External Documents functionality cannot be altered other than to change the column labels and sensitivity of the button options. The command DisplayFileChooserCommand, is used to gather files to be included in the list. Any changes to the file list are not saved to the database until the switching sheet is saved.

Generate Isolation Steps

The JBot command GenerateIsolateStepsCommand is used from the Control Tool to create a set of steps to isolate a piece of conductor within the model. The steps are generated based on the session the command was initiated from. If the Control Tool is in Real Time, then the Real Time model is used. If the Control Tool is in Study mode, then the user's study session is used. You also need to have a switching plan pre-created and in record mode in order to accept the generated steps. Both the session and the switching sheet requirements cannot be altered.

At this time, the command only supports isolating a conductor. The command uses the classes ss_isolate and ss_secure to determine what device types to create switching steps for. The command arguments determine the types of steps to generate for the isolate and secure device types. For more information, see the command documentation and the description of ss_isolate and ss_secure classes in the Configuring Classes and Inheritance section (see “Configuring Classes and Inheritance” for information).

Generic Tables

You can add generic tables to your Switch Sheets by following these steps:

1. Create your retain database table to hold the data. This should include the SEQ_SHEET_ID column, so that these records are tied to the Switch Sheet.

2. Add a DragSource to the source table in that tool. For example, in the DDSAlarms.xml, you can add the following to the table definition:

<DragSource flavor="DDS_ALARM" enable_copy="true"

enable_cut="false"/>

3. Create a new JDBCDataStore in your Switch Sheet. For example:

<DataStoreClass name="DS_SWMAN_ALARMS" scope="local"

class="com.splwg.oms.jbot.JDBCDataStore"

table="SWMAN_SHEET_ALARMS">

</DataStoreClass>

4. Create your destination table in your Switch Sheet. This should include the DragPerform. For example:

<TablePlacement anchor="NORTHWEST" fill="BOTH" height="1"

insets="2,2,2,2" ipad="1,1" start="0,1" weight="1,1" width="10"/>

<TableBehavior auto_resize_columns="true" click_to_sort="true"

display_header="true" intercell_spacing="1,1"

reorder_columns="true" resize_columns="true"

selection_policy="multiple" row_height="16"

row_selection_allowed="true" show_horizontal_lines="true"

show_vertical_lines="true" unselect_if_filtered="false"

even_bg_color="224,224,224" data_source="DS_SWMAN_ALARMS">

</Column>

</Column>

</Column>

</Column>

...

<Config name="columns" value="eventHdl.classNumber,

eventHdl.instanceNumber,eventType,#DATE_TIME,

#feeder,alias,description,#source

#state,phases,#attributeName,#nominal,quality,

limit,whoAck,timeAck,objectHdl.classNumber,

objectHdl.instanceNumber,rtiAlias"/>

<Config name="destination_columns" value="ALARM_CLS,

ALARM_IDX,ALARM_TYPE,SYSTEM_TIME,FEEDER,

ALIAS,DESCRIPTION,SOURCE,STATE,PHASES,

ATTRIBUTE_NAME,NOMINAL,QUALITY,LIMIT,

WHO_ACK,TIME_ACK,DEVICE_CLS,

DEVICE_IDX,RTI_ALIAS"/>

<Config name="common_sources"

value="DS_SWITCHING_SHEET_LOCAL.seqSheetId"/>

<Config name="no_selection_msg"

value="SWITCHING.NO_DDS_ALARMS_SELECTED"/>

<Config name="duplicate_row_msg"

value="SWITCHING.DUPLICATE_DDS_ALARMS"/>

</Command>

</DropPerform>

</Command>

</Perform>

</TableBehavior>

</Table>

You can also add buttons to copy and remove rows. For example:

<Config name="destination_datastore"

value="DS_SWMAN_ALARMS"/>

<Config name="columns"

value="eventHdl.classNumber,eventHdl.instanceNumber,

eventType,#DATE_TIME,#feeder,alias,description,

#source,#state,phases,#attributeName,

#nominal,quality,limit,whoAck,timeAck,
objectHdl.classNumber,objectHdl.instanceNumber,rtiAlias"/>

<Config name="destination_columns"

value="ALARM_CLS,ALARM_IDX,ALARM_TYPE,SYSTEM_TIME,

FEEDER,ALIAS,DESCRIPTION,

SOURCE,STATE,PHASES,ATTRIBUTE_NAME,

NOMINAL,QUALITY,LIMIT,WHO_ACK,TIME_ACK,

DEVICE_CLS,DEVICE_IDX,RTI_ALIAS"/>

<Config name="common_sources"

value="DS_SWITCHING_SHEET_LOCAL.seqSheetId"/>

<Config name="no_selection_msg"

value="SWITCHING.NO_DDS_ALARMS_SELECTED"/>

<Config name="duplicate_row_msg"

value="SWITCHING.DUPLICATE_DDS_ALARMS"/>

</Command>

</Command>

</PressPerform>

</ButtonBehavior>

</Button>