Plugin Support

SCADA vendors may interpret MultiSpeak specification differently or use extensions, which are unique to each vendor. To address the issue of possible differences between various SCADA components, the NMS MultiSpeak adapter has a plugin interface.

Plugin is a Java class, which encapsulates functionality specific to a particular SCADA system. Plugin class must implement the interface com.splwg.oms.interfaces.scada.ScadaSystemPlugin.

Default implementation of the SCADA system plugin is provided by the com.splwg.oms.interfaces.scada.plugins.GenericScada class.

Methods

The available plugin methods, including description of how the default plugin class implements each method, are:

getScadaPointId

java.lang.String getScadaPointId(MspObject obj)

This method is used to extract SCADA Point ID from the incoming MultiSpeak message.

Parameters

obj - MultiSpeak object

Returns

SCADA Point ID

Default Implementation

Returns value of the objectID attribute if not empty, otherwise value of the objectName element

getScadaPointId

java.lang.String getScadaPointId(ScadaTag tag)

This method is used to extract SCADA Point ID from the incoming tag-related MultiSpeak message.

Parameters

tag - ScadaTag object

Returns

SCADA Point ID

Default Implementation

Returns value of the scadaPointID element

setScadaPointId

void setScadaPointId(ScadaTag tag, java.lang.String pointId)

This method is used to set SCADA Point ID in the outgoing tag update message.

Parameters

tag - ScadaTag object to be updated

pointId - SCADA Point ID

Default Implementation

Sets value of the scadaPointID element.

getStatus

StatusIdentifiers getStatus(final ScadaStatus status);

This method is used to extract device status value from the MultiSpeak device status update message.

Parameters

status - ScadaStatus object

Returns

MultiSpeak device status value

Default Implementation

Returns value of the status element.

getQualityCodes

java.util.List<java.lang.String> getQualityCodes(ScadaStatus status)

This method is used to extract quality values from MultiSpeak status update message.

Parameters

status - ScadaStatus object

Returns

list of MultiSpeak quality values

Default Implementation

Returns value of the quality element

getQualityCodes

java.util.List<java.lang.String> getQualityCodes(ScadaAnalog analog)

This method is used to extract quality values from MultiSpeak analog update message.

Parameters

analog - ScadaAnalog object

Returns

list of MultiSpeak quality values

Default Implementation

Returns value of the quality element

processChangeCounter

int processChangeCounter(StatusPoint point, int changeCounter)

This method is used to process SCADA change counter value.

Parameters

point - SCADA status point

changeCounter - new change counter value for the SCADA status point

Returns

Number of device operations, which occurred since the last processed update

Default Implementation

Assumes that change counter value received from SCADA is cumulative (total number of times device has changed state since some point in the past). Number of device operations is calculated as the difference between previous and current SCADA change counter values

getTagId

java.lang.String getTagId(ScadaTag tag)

This method is used to extract value from the tag update message, which is then used to populate external id of the corresponding condition in NMS. This value has to uniquely identify the tag in NMS.

Parameters

tag - ScadaTag object

Returns

SCADA tag id

Default Implementation

Returns value of the tagID element

setTagId

void setTagId(ScadaTag tag, java.lang.String tagId)

This method is used during synchronization process to set tag id value in the tag update message, which is later extracted by the getTagId method.

Parameters

tag - ScadaTag object to be updated

tagId - SCADA tag id

Default Implementation

Sets value of the tagID element

getTagHandle

Handle getTagHandle(ScadaTag tag)

This method is used to extract NMS condition handle from tag update message.

Parameters

tag - ScadaTag object

Returns

NMS condition handle

Default Implementation

Attempts to parse the objectID attribute as NMS handle and returns parsed value or null if the objectID attribute cannot be parsed as NMS handle.

setTagHandle

void setTagHandle(ScadaTag tag, Handle condHdl)

This method is used to set NMS condition handle in the outgoing tag update message.

Parameters

tag - ScadaTag object to be updated

condHdl - NMS condition handle

Default Implementation

Sets value of the objectID attribute.

getTagType

java.lang.String getTagType(ScadaTag tag)

This method is used to extract SCADA tag type from tag update message. This value is then used to determine corresponding NMS condition class.

Parameters

tag - ScadaTag object

Returns

SCADA tag type

Default Implementation

Returns value of the tagType element

setTagType

void setTagType(ScadaTag tag, java.lang.String tagType)

This method is used to set SCADA tag type in the outgoing tag update message.

Parameters

tag - ScadaTag object to be updated

tagType - SCADA tag type

Default Implementation

Sets value of the tagType element.

getTagData

java.util.Map<java.lang.String,java.lang.Object> getTagData(ScadaTag tag)

This method is used to extract additional tag data fields from tag message.

Parameters

tag - ScadaTag object

Returns

Map <tag field name -> tag field value>

Default Implementation

Returns map with a single entry ('text', value of the tagReason element)

setTagData

void setTagData(ScadaTag tag, java.util.Map<java.lang.String, java.lang.Object> data)

This method is used to set additional tag data fields in the outgoing tag update message.

Parameters

tag - ScadaTag object to be updated

data - Map <tag field name -> tag field value>

Default Implementation

Sets value of the tagReason element to the value of the 'text' entry in the data parameter.

getUserName

java.lang.String getUserName(ScadaTag tag)

Extracts operator username from tag update message.

Parameters

tag - ScadaTag object

Returns

SCADA operator username

Default Implementation

Returns value of the userName element

setUserName

void setUserName(ScadaTag tag, java.lang.String username)

This method sets operator username in the outgoing tag update message.

Parameters

tag - ScadaTag object to be updated

username - NMS operator username

Default Implementation

Sets value of the userName element.

getAction

Action getAction(ScadaTag tag)

This method is used to extract action from tag update message. Action determines if the request is to place a new tag, update an existing tag or remove an existing tag.

Parameters

tag - ScadaTag object

Returns

action

• NEW - add new tag

• CHANGE - update an existing tag

• DELETE - delete an existing tag

Default Implementation

Returns value of the verb attribute

setAction

void setAction(ScadaTag tag, Action action)

This method is used during synchronization process to set action value in the tag update message, which is later extracted by the getAction method.

Parameters

tag - ScadaTag object to be updated

action - action

• NEW - add new tag

• CHANGE - update an existing tag

• DELETE - delete an existing tag

Default Implementation

Sets value of the verb attribute

buildScadaPointId

java.lang.String buildScadaPointId(com.splwg.oms.common.intersys.Handle nmsDeviceHandle, java.lang.String nmsDeviceAlias, int phase)

throws java.lang.IllegalArgumentException

This method is used to construct SCADA point id for status of an NMS device.

Note: This is the first of two overloaded versions of the buildScadaPointId method.

Parameters

nmsDeviceHandle - NMS device handle

nmsDeviceAlias - NMS device alias

phase - phase

Returns

SCADA point id or null if not supported

Throws

java.lang.IllegalArgumentException - SCADA point id cannot be constructed for the given arguments

Default Implementation

Constructs SCADA point id of the following format:

• <base name>[#<phase text>]

• <base name> - nmsDeviceHandle if provided otherwise nmsDeviceAlias

• <phase code> - determined from the phase parameter according to the following rules: 1 - 'A', 2 - 'B', 4 - 'C', otherwise empty string

buildScadaPointId

java.lang.String

buildScadaPointId(com.splwg.oms.common.intersys.HandlenmsDeviceHandle
java.lang.String nmsDeviceAlias, int phase, java.lang.String scadaPointId)
throws java.lang.IllegalArgumentException

This method is used to construct SCADA point id for status of an NMS device.

Note: This is the second of two overloaded versions of the buildScadaPointId method.

Parameters

nmsDeviceHandle - NMS device handle

nmsDeviceAlias - NMS device alias

phase - phase

scadaPointId - SCADA point ID for the device status (only available for SCADA devices).

Returns

SCADA point id or null if not supported

Throws

java.lang.IllegalArgumentException - SCADA point id cannot be constructed for the given arguments

Default Implementation

Invokes the buildScadaPointId method. which does not accept the scadaPointId parameter. Thus the scadaPointId parameter passed to this method is not used in default implementation.

parseScadaPointId

ParsedSCADAPointId parseScadaPointId(java.lang.String scadaPointId)

throws java.lang.IllegalArgumentException

Parse SCADA point id.

Parameters

scadaPointId - SCADA point id

Returns

ParsedSCADAPountId object

Throws

java.lang.IllegalArgumentException - if scadaPointId cannot be parsed

Default Implementation

Populates NMS device id in ParsedSCADAPointId with scadaPointId argument.

generateControl

ScadaControl generateControl(ExpectedAction action)

This method is used to create ScadaControl object based on the received control request.

Parameters

action - control request

Returns

ScadaControl object or null is controls are not supported

Default Implementation

Returns null

isScadaPoint

boolean isScadaPoint(final MspObject obj)

This method is used to determine if obj is a SCADA-telemetered point. Currently this method gets invoked only for status points.

Parameters

obj - MultiSpeak object

Returns

true if obj is a SCADA-telemetered point, otherwise false

Default Implementation

Returns true

getPhaseName

java.lang.String getPhaseName(int phase)

This method is used to convert NMS phase code into phase name.

Parameters

phases - NMS phase code (1 - A, 2 - B, 4 - C)

Returns

phase name or empty string

Default Implementation

Returns 'A' if phase is 1, 'B' if phase is 2, and 'C' if phase is 4. Empty string is returned for any other input.

Building Custom SCADA Plug-ins

Prerequisites

• NMS is installed.

• nms-install-config --java script has been executed and nms-multispeak.ear file exists in the $NMS_HOME/java/deploy directory.

Steps

1. Unpack $NMS_BASE/sdk/java/samples/nms-multispeak-plugins.zip archive into desired location (this location will be referred as PLUGIN_HOME). It includes Java project directory structure including example of plugin class and Ant build files.

2. Create Java class implementing com.splwg.oms.interfaces.scada.ScadaSystemPlugin interface and place it into desired location under PLUGIN_HOME/NmsScadaPlugin/src directory.

3. Execute following command to compile plugin class(s), build jar file and incorporate the jar file into the nms-multispeak.ear file.

ant -Dplatforms.JDK_1.6.home=<JDK home> clean update-ear

where

<JDK home> is the location where Java Development Kit 1.6 or later is installed

4. Update configuration for the Oracle Utilities NMS MultiSpeak Adapter to use new plugin class (configuration property '<scada name>.plugin_class').

5. Updated nms-multispeak.ear file can now be deployed into WebLogic server.