Software Configuration
Configuration for the Oracle Utilities Network Management System MultiSpeak Adapter comes from the following sources:
• CES_PARAMETERS database table;
• SCADA_IDS database table;
• SCADA_LINKS database table;
• SCADA_LINK_OPS database table;
• SCADA_SYNONYMS database table.
CES_PARAMETERS
Entries in the CES_PARAMETERS database table for the SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter should have the value SCADAInterface in the APP column. Column ATTRIB should contain the name of the configuration parameter and column VALUE its value. See Overriding Configuration Parameters for more information.
Common Configuration Parameters
The following table describes the common configuration parameters.
Parameter
Description
config.credentials
Absolute path to the file containing user credentials the adapter will use to communicate with Oracle Utilities Network Management System.
Either this parameter or both config.username and config.password parameters should be provided. If all are present then config.username/config.password pair is used.
config.enabled
Enables SCADA processing.
 
Default: false
config.message_credentials_required
If this parameter is set to false then credentials for authenticating with NMS are taken from the MultiSpeak header of the incoming message.
If this parameter is set to false and credentials are not present in the MultiSpeak header of the incoming message then username and password configured in the adapter is used to authenticate with NMS.
 
Valid Values: true|false.
 
Default: true
config.password
NMS user password. Value of this parameter should be encrypted.
config.nms_url
URL for accessing Oracle Utilities Network Management System. If this parameter is not provided then it
is assumed that MultiSpeak Adapter is deployed on the same Managed Server as cesejb.ear.
This parameter is specified for each component of the adapter, but only one value is actually used; all components will connect to the same NMS instance.
The value is taken from the first enabled component according to the following order of precedence:
1. SCADA
2. AMR
3. AVL
Note: This parameter replaces the Foreign JNDI configuration used in earlier versions of the Adapter.
config.strict_scada_name_check
 
SCADA name validation. If set to 'false' and only one SCADA system is configured for the MultiSpeak Adapter in the SCADA_IDS database table then SCADA name check is skipped. Otherwise field UserID in the MultiSpeak message header or username of the web services caller (if UserID is empty) is matched against the values in the SCADA_NAME field in the SCADA_IDS database table. Request is rejected if matched value is not found.
 
Default: true
config.username
Valid NMS username, which has the 'NmsService' role in WebLogic Server.
Per SCADA System Configuration Parameters
The following configuration parameters are configured individually for each SCADA system the adapter is communicating with. Names of such parameters are prefixed with the name of the SCADA system they apply to (value from the SCADA_NAME column in the SCADA_IDS table).
Authentication with the SCADA System
The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter passes credentials to the SCADA system in the UserID and Pwd fields of the MultiSpeak message header.
Parameter
Description
<scada name>.headers.UserID
Username to be passed to the SCADA system.
<scada name>.headers.Pwd
Password to be passed to the SCADA system.
Note: Other MultiSpeak message header fields can be set by using desired field name in the parameter name.
JNDI Name for JMS Connection Factory
When JMS transport is used this parameter defines JNDI name of the JMS connection factory used for NMS to SCADA data flows.
Parameter
Description
<scada name>.jms_cf_name
JNDI name of the JMS connection factory which should be used for NMS to SCADA data flows.
 
Default: ConnectionFactory
JMS Connection Credentials
These parameters are used if credentials are required to establish connection to JMS server. They are passed to the createConnection method of JMS connection factory.
Parameter
Description
<scada name>.jms_user
JMS connection username.
<scada name>.jms_password
JMS connection password.
SCADA System Plugin Class
Plugin class is a Java class, which encapsulates functionality of the adapter, which is specific to a particular SCADA system.
Parameter
Description
<scada name>.plugin_class
Full name of the Java class implementing ScadaSystemPlugin interface for the SCADA system the adapter is connected to.
 
Default: com.splwg.oms.interfaces.scada.plugins.GenericScada
Support for Tags
These parameters control tag-related data flows.
Parameter
Description
<scada name>.support_tags
Enable/disable support for incoming tags.
 
Default: false (incoming tags are not supported)
<scada name>.outgoing_tag.class.<idx>
Names of the NMS condition classes for which updates should be sent to the SCADA system. This applies to the children of the configured classes as well.
<scada name>.outgoing_tag.block_size
Block size for the outgoing condition messages.
 
Default: 10
<scada name>.outgoing_tag.only_scada
Only send outgoing tag messages for SCADA devices. If set to 'true' only tags on SCADA devices will be reported to SCADA; otherwise, tags on all devices are reported.
 
Default: false
<scada name>.outgoing_tag.add_gang_point
When tag is placed on a phase-operable device send outgoing tag message for the point representing all device phases. This message is sent in addition to the messages for points representing individual tagged phases which are always sent.
 
Default: false
<idx> - suffix used to make parameter name unique; any value can be used as long as resulting configuration parameter name is unique.
Synchronization Sequence Timeout
This parameter limits how long synchronization sequence can last. If this value is exceeded then link failure is declared.
Parameter
Description
<scada name>.sync_timeout
Maximum allowed duration (in seconds) of synchronization sequence.
 
Default: 3600
Automatic Synchronization of Measurements Values
SCADA systems can have large number of analog measurements and synchronizing those can be a lengthy task. This configuration parameter allows analog measurements to be excluded from automated synchronization sequence, which is executed when connection to SCADA system is established.
It is always possible to manually trigger synchronization of analog measurements regardless of the value of this parameter.
Parameter
Description
<scada name>.sync_analogs
Include measurement values into automated synchronization sequence.
 
Default: true
Adapter Status Alarm Messages
NMS MultiSpeak adapter can generate system alarms to alert NMS operator about following conditions:
• Adapter has been started
• Adapter has been stopped
• Connection to SCADA system has been established
• Connection to SCADA system has failed
• Synchronization sequence has finished
Parameter
Description
<scada name>.msg.started
Text of the alarm generated when adapter has been started.
<scada name>.msg.stopped
Text of the alarm generated when adapter has been stopped.
<scada name>.msg.established
Text of the alarm generated when connection to SCADA system has been established.
<scada name>.msg.failed
Text of the alarm generated when connection to SCADA system has failed.
<scada name>.msg.synchronized
Text of the alarm generated when synchronization sequence has finished.
 
If alarm text is not configured then corresponding alarm will not be generated.
Dynamic SCADA Point Configuration
When SCADA system has knowledge of NMS device aliases or device handles it is possible to have process of SCADA point configuration to be performed by the adapter as part of integrity check. New SCADA points are added to the database tables ANALOG_MEASUREMENTS, DIGITAL_MEASUREMENTS and SCADA_MEASUREMENTS_ST. Orphaned SCADA points can be removed from the SCADA_MEASUREMENTS_ST database table.
No additional actions are required for new SCADA points to take effect (users may have to refresh SCADA Summary to see new points). Command 'UpdateDDS -recacheMeasures' need to be executed to propagate record deletions to runtime tables (ANALOG_MEASUREMENTS and DIGITAL_MEASUREMENTS).
In order for dynamic SCADA point configuration to be possible SCADA system plugin must implement buildScadaPointId and parseScadaPointId methods.
Parameter
Description
<scada name>.dynamic_point_config
Dynamic SCADA point configuration support.
Valid values:
• full – dynamic addition and removal of SCADA points is supported
• add – only dynamic addition of SCADA points is supported
• none – not supported
Default: none.
Sending Device Status Information from NMS to SCADA
The adapter can be configured to send NMS device status information to SCADA system. List of NMS devices classes has to be configured to enable this functionality (<scada name>.outgoing_status.class.<idx> parameter).
Class inheritance is taken into account so if a device class is configured to have status changes to be sent to SCADA system then status changes for all the child classes would also be sent out.
For conductors quality value in the outgoing message is set to Other. In all other cases quality value is not set.
Status information for inline jumpers is reported as status on the underlying conductor.
Point-to-point jumpers are not supported.
Parameter
Description
<scada name>.outgoing_status.class.<idx>
Device classes for which status information should be sent to SCADA system.
<scada name>.outgoing_status.block_size
Block size for outgoing device status messages.
 
Default: 10
<scada name>.outgoing_status.allow_scada
Allow device status updates for SCADA devices to be sent to the SCADA system. This is disabled by default because SCADA system is the master for the information about SCADA devices.
 
Default: false
<scada name>.outgoing_status.allow_pending_construction
Allow device status updates for pending construction devices as well as changes in pending construction status of devices to be sent to the SCADA system.
 
Default: false
<scada name>.conductor.class.<idx>
NMS conductor device classes.
<scada name>.jumper.class.<idx>
NMS jumper device classes.
 
<idx> - suffix used to make parameter name unique; any value can be used as long as resulting configuration parameter name is unique.
Synchronization Method
The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter supports two methods of synchronizing device statuses and measurements with the SCADA system: synchronous and asynchronous.
Parameter
Description
<scada name>.preferred_sync_method
Preferred method of synchronization with the SCADA system.
 
Valid values:
• sync: synchronous
• async: asynchronous
 
Default: async.
<scada name>.need_sync_points
Whether full list of SCADA points known to NMS should be sent to SCADA during synchronization process. Only applicable when preferred_sync_method is async.
 
Valid Values: true|false
 
Default: false
Device Operation Time During Synchronization
When synchronizing device statuses with the SCADA system the SCADA component of the NMS MultiSpeak Adapter can use either device operation time reported by SCADA or the synchronization time to report device operations to NMS. .
Parameter
Description
<scada name>.use_scada_time_during_sync
Use device operation time reported by SCADA to record device during synchronization process for device statuses.
 
Default: false (use timestamp from MultiSpeak message header if available and current time otherwise).
SOAP Protocol Version
Oracle Utilities Network Management System MultiSpeak Adapter can use SOAP protocol versions 1.1 or 1.2.
Parameter
Description
<scada name>.soap12
Whether SOAP 1.2 should be used.
 
Valid Values:
• true: use SOAP 1.2.
• false: use SOAP 1.1
 
Default: false
Outbound Controls
The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter supports sending control requests to the SCADA system.
Parameter
Description
<scada name>.allow_controls
Whether control requests should be sent to SCADA.
Valid values: true/false
 
Default: false (controls are not allowed)
<scada name>.allow_multiphase_controls
Allows sending of a single control request when all phases of a phase-operable device are operated.
 
Default: false (for phase-operable devices, a separate control request is sent for each phase).
Heartbeat Interval
The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter periodically sends PingURL message to the SCADA system to check status of the link. Heartbeat failure causes adapter to switch to alternate link (if available).
Parameter
Description
<scada name>.heartbeat_
interval
Interval in seconds between heartbeat messages.
 
Default: 60 seconds
<scada name>.heartbeat_failure_
timeout
Number of seconds that needs to elapse without heartbeat message being successfully sent to SCADA system before the link to this SCADA system is considered to be down.
 
Note: Failure to send any message other than heartbeat to SCADA system causes link to be considered down immediately.
 
Default: 0 (link is down on first heartbeat failure).
Support for Operating Non-SCADA Devices in the NMS Model
If set to 'true' this configuration parameter allows SCADA system to operate devices, which are not SCADA-telemetered, in NMS model. For this to be possible the adapter must be able to derive NMS device handle from SCADA point id. In addition if dynamic point configuration is enabled, then SCADA plugin must implement 'isScadaPoint' method to allow adapter to distinguish between status updates for SCADA and non-SCADA devices.
Parameter
Description
<scada name>.allow_non_
scada_ops
Allow SCADA to operate non-SCADA devices in NMS model.
Default: false (do not allow SCADA to operate non‑SCADA devices)
Obtaining a List of Configured SCADA Points
SCADA system can retrieve list of SCADA points configured in NMS for that particular SCADA system using the GetAllSCADAPoints MultiSpeak operation. The information is returned in blocks and the caller may have to invoke this operation multiple times to retrieve all configured points.
Parameter
Description
<scada name>.points.block_
size
Block size for responses to GetAllSCADAPoints requests.
This is the maximum number of ScadaPoint objects which will be included into a single response to GetAllSCADAPoints request.
 
Default: 100
Own Web Service URL
There are cases when the SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter needs to send an URL of its own web service to the SCADA system. For example, when sending asynchronous request to the SCADA system, it needs to provide a URL where the response should be sent when the results become available.
Parameter
Description
<scada name>.OA.url
URL where the incoming web service of the Oracle Utilities Network Management System MultiSpeak Adapter is deployed.
SCADA_IDS
This database table is used to configure the list of SCADA systems that the adapter will be communicating with. For SCADA systems compatible with this adapter, the column ADAPTER_TYPE should have value MULTISPEAK.
Example
INSERT INTO scada_ids (id, scada_name, adapter_type, active)
VALUES (200, 'SCADA1', 'MULTISPEAK', 'Y');
 
INSERT INTO scada_ids (id, scada_name, adapter_type, active)
VALUES (201, 'SCADA2', 'MULTISPEAK', 'Y');
SCADA_LINKS
This database table is used to configure communication links to the SCADA systems. It is allowed to configure multiple links to a single SCADA system. If one link fails the adapter will switch to another one in the order determined by the PRIORITY field (only one link is active at any given time). HTTPS and JMS links are supported.
• For HTTP links, the WS_URL column is used to specify the URL of the SCADA system web service.
• For JMS links, the columns REQUEST_QUEUE and RESPONSE_QUEUE are used to specify the JNDI names of the JMS queues used to send requests to and receive responses from the SCADA system.
• The value in the TIMEOUT column controls how long the adapter should wait for a response from the SCADA system (in seconds). This is only applicable to JMS links. The maximum allowed value is 3600 (1 hour).
• The value in the PERSISTENT column defines the delivery mode for JMS messages. If set to 'Y' then JMS messages are persistent, otherwise they are not persistent. By default messages are not persistent. This is only applicable to JMS links.
• The value in the SITE column should contain the site name, as also used in the CES_PARAMETERS table.
 
Example
INSERT INTO scada_links (id, scada_id, ws_url, timeout, priority,
active, site)
VALUES (1, 200, 'http://scada-server1:8088/SCADA', 30, 1, 'Y', 'SiteA');
INSERT INTO scada_links (id, scada_id, ws_url, timeout, priority,
active, site)
VALUES (2, 200, 'http://scada-server2:8088/SCADA', 30, 2, 'Y', 'SiteA');
INSERT INTO scada_links (id, scada_id, request_queue, response_queue,
timeout, persistent, priority, active, site)
VALUES (3, 200, 'queue/ScadaRequest', 'queue/ScadaResponse', 30, 'N',
3, 'Y', 'SiteA');
SCADA_LINK_OPS
This table can be used to configure communication parameters differently for individual outgoing web service operations. If an operation does not have a record in the SCADA_LINK_OPS table then values from the parent SCADA_LINKS record are used.
• Column LINK_ID is the foreign key into the SCADA_LINKS table.
• Column OPERATION is used to specify web service operation name. Supported operation names:
• PingURL
• GetMethods
• InitiateAnalogReadByPointID
• InitiateStatusReadByPointID
• InitiateTagReadByPointID
• InitiateControl
• GetAllSCADAAnalogs
• GetAllSCADAStatus
• GetAllSCADATags
• SCADAStatusChangedNotification
• SCADAStatusChangedNotificationByPointID
• StatusChangedNotificationByPointID
• HighlightObjectInDisplay
• SCADATagChangedNotification
• TagChangedNotificationByPointID
 
For HTTP links, the WS_URL column is used to specify the URL of the SCADA system web service. For JMS links, the columns REQUEST_QUEUE and RESPONSE_QUEUE are used to specify the JNDI names of the JMS queues used to send requests to and receive responses from the SCADA system.
• Value in the TIMEOUT column controls how long the adapter should wait for response from SCADA system (in seconds). Maximum allowed value is 3600 (1 hour).
• Value in the PERSISTENT column defines delivery mode for JMS messages. If set to 'Y' then JMS messages are persistent, otherwise they are not persistent. By default messages are not persistent.
• The value in the SITE column should contain the site name, as also used in the CES_PARAMETERS table.
Example
INSERT INTO scada_link_ops (id, link_id, operation, request_queue,
response_queue, timeout, persistent, site)
VALUES (31, 3, 'PingURL', 'queue/ScadaRequest_PingURL',
'queue/ScadaResponse_PingURL', 30, 'N', 'SiteA');
INSERT INTO scada_link_ops (id, link_id, operation, ws_url, timeout,
persistent, site)
VALUES (32, 4, 'GetMethods', 'http://scada-server:8080/GetMethods',
30, 'N', 'SiteA');
SCADA_SYNONYMS
This database table is used configure mapping of different data elements between SCADA and NMS systems. The SCADA_ID column should always be populated with the id of the SCADA system (value of the ID column in the SCADA_IDS table) the mapping applies to.
Device Status Mapping
By default the adapter maps MultiSpeak device status values 'Open' and 'Closed' to the corresponding device statuses in NMS and ignores all other device status values defined by MultiSpeak 4.1 specification. SCADA_SYNONYMS table allows customization of device status mapping by associating MultiSpeak device status value to a combination of NMS device status and quality code.
The MultiSpeak device status value should be entered into the KEYWORD column. The NMS device status value should be entered into the STATUS_VALUE column. Valid values are 'Open', 'Closed' or NULL.
If this column is NULL, the device status in NMS will not be affected.
The NMS quality code should be entered in the INT_VALUE column. It will be combined with the quality code received in the MultiSpeak message. The PROCESS_TYPE should be 'S'.
The following example maps the 'Travel' device status received from SCADA to quality code 8192 and keeps device status in NMS unchanged.
INSERT INTO scada_synonyms (id, scada_id, keyword, status_value, int_value, process_type)
VALUES (tmp_seq.nextval, 200, 'Travel', null, 262144, 'S');
Attribute Mapping
Attribute mapping is used when SCADA point ID does not uniquely identify both NMS device and attribute. SCADA attribute name/key should be entered into the KEYWORD column. NMS attribute key should be entered into the INT_VALUE column. PROCESS_TYPE should be 'D' for digital measurements and 'A' for analogs.
Example
INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type)
VALUES (1, 200, 'faultIndicator', 23, 'D');
INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type)
VALUES (2, 200, 'Amps', 1012, 'A');
 
An additional method for configuring mapping for digital measurements is available. It applies specifically to the case when digital measurement is submitted to NMS via SCADAStatusChangedNotification, SCADAStatusChangedNotificationByPointID or StatusChangedNotificationByPointID operation. This is only possible when SCADA point id uniquely identifies digital measurement in NMS.
SCADA attribute name/key should be entered into the KEYWORD column.
NMS attribute name should be entered into ATTRIBUTE_ALIAS column.
Status value received from SCADA should be entered into STATUS_VALUE column.
Corresponding NMS attribute value should be entered into INT_VALUE column.
PROCESS_TYPE should be 'D'.
Column VALUE is not used.
 
Example configuration for AutoReclose digital attribute. Receiving status 'Open' from SCADA would set AutoReclose attribute for a device to 1. Receiving status 'Closed' from SCADA would set AutoReclose attribute for a device to 0.
 
INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type,
attribute_alias, status_value, value)
VALUES (247, 200, 'AutoReclose', 1, 'D', 'AutoReclose', 'Open', 'On');
INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type,
attribute_alias, status_value, value)
VALUES (248, 200, 'AutoReclose', 0, 'D', 'AutoReclose', 'Closed', 'Off');
 
Quality Code Mapping
The SCADA quality value should be entered into the KEYWORD column. The MultiSpeak 4.1 specification defines the following quality values: Measured, Default, Estimated, Calculated, Initial, Last, and Failed.
The NMS quality code should be entered into the INT_VALUE column (lower 11 bits are reserved for NMS-specific quality codes).
The PROCESS_TYPE should be 'Q'.
 
Example
INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type)
VALUES (3, 200, 'Measured', 4096, 'Q');
Tag Type Mapping
For incoming SCADA tags:
The SCADA tag type should be entered into the KEYWORD column.
The NMS condition class name should be entered into VALUE column.
For outgoing NMS conditions:
NMS condition class name should be entered into the KEYWORD column.
SCADA tag type should be entered into the VALUE column.
The PROCESS_TYPE should be 'C'.
 
Examples
Incoming
INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)
VALUES (11, 200, 'Hold', 'hold', 'C');
INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)
VALUES (12, 200, 'Tag', 'tag', 'C');
INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)
VALUES (13, 200, 'Clear', 'clear', 'C');
 
Outgoing
INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)
VALUES (21, 200, 'hold', 'Hold', 'C');
INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)
VALUES (22, 200, 'hot', 'Hot', 'C');
INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)
VALUES (23, 200, 'note', 'Note', 'C');
 
 
CORBA Publisher Configuration for Outbound Controls
If the SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter is configured to allow outgoing controls to SCADA system, the 'scada-controls' source should be present and active in the PUBLISHER_SOURCES database table.
Example
INSERT INTO publisher_sources(source_id, source, active)
VALUES(16, 'scada-controls', 'Y');
SCADA Point Configuration
The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter loads SCADA point configuration from the ANALOG_MEASUREMENTS and DIGITAL_MEASUREMENTS database tables. It normally happens during initialization. The adapter can be forced to reload the SCADA point configuration during runtime using the following command:
Action -java multispeak.SCADA reload
The synchronization sequence will be automatically started after the SCADA point configuration is reloaded.
SCADA Configuration for Bellwether Meters
In order for the reading from bellwether meters to be reflected in NMS they need to be configured as SCADA measurements in the SCADA component of the NMS MultiSpeak adapter. The following set of steps should be used to perform such configuration.
1. Add entry to the SCADA_IDS table. The entry should match the 'config.bellwether_scada_name' configuration parameter of the AMR component of the NMS MultiSpeak adapter.
2. Add entries to the SCADA_MEASUREMENT_ST table for the measurement values coming from bellwether meters. The RTI_ALIAS field must be populated using format "<meter id>-<field name>", where <meter id> is the NMS meter identifier (AMR_CU_METERS.METER_ID) and <field name> is the meter reading field name coming from the AMR system (e.g., "Voltage").
3. Populate SCADA_SYNONYMS table with attribute mappings.
4. Populate SCADA_SYNONYMS table with quality code mappings. The quality code for meter readings is always "Measured."
Note: Do not populate SCADA_LINKS table to indicate that this is "input-only" SCADA system. It will prevent MultiSpeak adapter from attempting to send heartbeat requests to the AMR system.