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.