Technical Note Connecting and Reading Alarm and Event … GMSCS0123-01E Exaquantum Auto AE... · Auto AE Configuration Tool R3.01: Technical Note 3 1. INTRODUCTION This document describes

Technical Note TN GMSCS0123-01E

Yokogawa Electric Corporation 2-9-32, Nakacho, Musashino-shi, Tokyo, 180-8750 Japan

TN GMSCS0123-01E ©Copyright R3.01 Issue 1.0

October 2015

Connecting and Reading

Alarm and Event data from a 3rd Party OPC Server

Auto AE Configuration Tool R3.01: Technical Note

1

DOCUMENT REVISION RECORD

Date Issue No Revised Sections

Description of Change

27th October 2015 R3.01 Issue 1.0

First Formal Release of Document

QMS-3130-09E Issue 1

1. INTRODUCTION ............................................................................................................. 3 1.1. Audience.................................................................................................................... 3 1.2. Overview of Procedure .............................................................................................. 3 1.3. References ................................................................................................................ 3 1.4. Restrictions ................................................................................................................ 3

2. EXAQUANTUM OPC SERVER TYPE WIZARD ............................................................. 4 2.1. Startup ....................................................................................................................... 4 2.2. Screens ..................................................................................................................... 4

3. USING THE EXAQUANTUM AUTOAECONFIG TOOL .................................................. 5 3.1. Introduction ................................................................................................................ 5 3.2. Startup ....................................................................................................................... 5 3.3. User Interface ............................................................................................................ 5 3.4. Configuration Sequence for 3rd Party OPC Server ................................................... 7

3.4.1. Adding AE data capability to an existing OPC gateway ....................................... 7 3.4.2. Configuring AE storage and metadata without a specific gateway ...................... 7

3.5. Manual AE Configuration Tool ................................................................................... 8 3.6. Processing and Storage ............................................................................................ 9

3.6.1. Reviewing the processing log .............................................................................. 9 3.6.2. Error, warning and processing log ....................................................................... 9 3.6.3. Storage .............................................................................................................. 11

4. EXAQUANTUM OPC GATEWAY TOOL ....................................................................... 12 4.1. Startup ..................................................................................................................... 12 4.2. Fields ....................................................................................................................... 12

5. COLLECTION OF ALARM AND EVENT DATA FROM YOKOGAWA PRM / STARDOM .................................................................................................................... 13

5.1. Yokogawa PRM ....................................................................................................... 13 5.1.1. Category: Device Alarm ..................................................................................... 13 5.1.2. Category: Device Configuration ......................................................................... 14 5.1.3. Category: Device Event ..................................................................................... 14 5.1.4. Category: Diagnosis Alarm ................................................................................ 14 5.1.5. Category: Diagnosis Event ................................................................................ 15 5.1.6. Category: PAS Alarm ......................................................................................... 15 5.1.7. Category: PAS Event ......................................................................................... 15 5.1.8. Category: PRM Log ........................................................................................... 16 5.1.9. Category: System Log ....................................................................................... 16 5.1.10. Category: User Event ...................................................................................... 16


2

5.2. Yokogawa Stardom ................................................................................................. 16 5.2.1. Category: Application alarm ............................................................................... 16 5.2.2. Category: Application event ............................................................................... 16 5.2.3. Category: Internal or source connection ............................................................ 17 5.2.4. Category: Process alarm ................................................................................... 17 5.2.5. Category: System alarm .................................................................................... 17 5.2.6. Category: System event .................................................................................... 17


3

1. INTRODUCTION This document describes how to configure Exaquantum to read Alarm and Event data from Third Party OPC servers. This function makes use of the following tools in Exaquantum: • OPC Server Type Wizard • Automatic AE Configuration Tool • Admin Tools – OPC Gateway

In order for this to be successful, the following must be provided: • ProgIDs of the Third Party OPC Server

1.1. Audience This Technical note is provided for IT and Exaquantum Administrators.

1.2. Overview of Procedure The Automatic AE Configuration Tool provides a method of automatic configuration of Alarm and Event Data. The Automatic AE Configuration Tool is a GUI based utility that reads Alarm and Event configuration data, from the specified OPC Server, and creates the necessary configuration in Exaquantum. There are three steps to reading Alarm and Event data into Exaquantum from a Third party OPC Server.

Step Description Section

1. Run the Exaquantum OPC Server Type Wizard to define the Third Party OPC Server Type. 2

2. Run the Exaquantum AutoAEConfig tool to get the Alarm and Event Configuration from the Third Party OPC Server.

3

3. Add an Exaquantum OPC Gateway to connect to the Third Party OPC Server. 4

1.3. References Reference Document title and number

1. Exaquantum Engineering Guide Volume 3. IM36J04A15-03E-015

2. Exaquantum PIMS Users Manual. IM36J04A11-101E-015

1.4. Restrictions Please see Section 6 for restrictions on what can be collected from the following OPC Server Types: • Yokogawa PRM • Yokogawa Stardom


4

2. EXAQUANTUM OPC SERVER TYPE WIZARD Please refer to Reference 1 for details (CH 17.5)

2.1. Startup To launch the Exaquantum OPC Server Type Wizard double-click the OPC Server Type Wizard.exe file in the following folder: <Exaquantum Install Folder>\Developer Tools

Table 2-1 Permissions required for the Automatic AE Configuration Tool

Security Model Permissions required

Legacy Member of QAdministrators Group

Standard Member of QTM_MAINTENANCE Group

The tool may be run with Exaquantum in either the stopped or the running state.

2.2. Screens Table 2-2 OPC Server Type Wizard – screens

Step Screen Action

1. OPC Server Type Configuration Select the Create option

2. OPC Server Type Creation

Enter in the name of the OPC Server Type to be created. The option Use an existing OPC Server Type as a template is optional.

3. Add / Modify the settings as required.

Defined in Table 2 1. This table only defines the fields that require data.

4. Finish Screen Review the definition and click Finish.

Table 2-3 Add / Modify settings screen - field values

Field Setting OPC Server Type Name As defined in Step 2 in Table 2-2

OPC DA Manager ProgID YokogawaMarex.QOPCDAMgr.

OPC AE Server ProgID

The Prog ID of the Third Party OPC Server (AE). This must be obtained from the provider of the Third Party OPC Server.

OPC HAE Server ProgID

The Prog ID of the Third Party OPC Server (HAE). Optional if HAE data required. This must be obtained from the provider of the Third Party OPC Server.


5

3. USING THE EXAQUANTUM AUTOAECONFIG TOOL

3.1. Introduction Automatic AE configuration tool is designed to simplify configuration of 3rd party Alarm and Event OPC Gateways by generating the necessary Exaquantum configuration directly from the metadata supplied by the gateway.

3.2. Startup To launch the Automatic AE Configuration Tool double-click the AutoAEConfig executable file in the following folder: <Exaquantum Install Folder>\Developer Tools

Table 3-1 Permissions required for the Automatic AE Configuration Tool

Security Model Permissions required Legacy Member of QAdministrators Group Standard Member of QTM_MAINTENANCE Group

The tool may be run with Exaquantum in either the stopped or the running state.

3.3. User Interface Figure 3-1 Automatic AE Configuration Tool


6

Table 3-2 Automatic AE Tool – Control Details

Category Setting Item Description

OPC Gateway

Detail

Add new A&E configuration data to an existing OPC gateway(DA

Must be checked if deploying the A&E configuration data to an existing OPC gateway (DA).

OPC Gateway Name

After clicking the drop-down button, the drop-down list is shown. Select OPC Gateway Name from the list. If “OPC gateway does not exist”, the control is disabled.

OPC Gateway Type

After clicking the drop-down button, the drop-down list is shown. Select OPC Gateway Type from the list. (See Note.)

OPC Gateway Computer

After clicking the drop-down button, the OPC Gateway Computer list is shown. Select OPC Gateway Computer from the list. Alternatively, enter the computer name directly. (See Note.)

Logon Check

Enable Logon Check

Must be checked if the 3rd party OPC server supports enhanced connection security. (See Note.)

User name

Allows the user to enter the user name when the “Enable Logon Check” is checked. If not checked, this control is disabled. If “OPC gateway already exists”, this control is disabled. (See Note.)

Password Allows the user to enter the password when the “Enable Logon Check” is checked. If not checked, this control is disabled.

Buttons

View Log Opens the progress report file showing full detail of the utilities’ execution.

Create

Run automatic configuration of Alarm and Event data. This button is enabled when: The mode “Add new A&E configuration data to an existing OPC gateway(DA)” is not selected, and OPC Gateway Type and OPC Gateway Computer are defined. .If “Enable Logon Check” is checked, then at least a user name, and optionally a password must be entered. The mode “Add new A&E configuration data to an existing OPC gateway(DA)” is selected, and OPC Gateway Name is defined All GUI controls are disabled and the hourglass icon is displayed when the utility is processing. At the end of processing or on encountering an error a dialogue box is displayed

Cancel Close the Automatic AE Configuration tool. While processing, this button is disabled.


7

NOTE: If the control “Deploy the A&E configuration data to the existing OPC gateway (DA)” is un-checked, the OPC Gateway Type, Enable Logon Check, User name and Password control are disabled.

3.4. Configuration Sequence for 3rd Party OPC Server This section discusses the two possible scenarios for using the Automatic AE configuration utility.

3.4.1. Adding AE data capability to an existing OPC gateway In this scenario the third party OPC server is already configured as OPC gateway in Exaquantum and used to collect DA data. However, AE storage configuration for this server type is not present in Exaquantum. The following steps need to be performed in order to configure this existing gateway for AE data collection:

1. Run the Automatic AE configuration utility with “OPC Gateway already exists”

selected, specifying the existing OPC gateway parameter. The Automatic AE configuration utility will then create Alarm and Event storage configuration in the QConfig database, and generate the tables in QHistorianData database, if they do not exist.

2. Enable Alarm and Event data on the gateway, as shown in Figure 5-2.

3.4.2. Configuring AE storage and metadata without a specific gateway Here the objective is to prepare Exaquantum to be able to connect to 3rd party OPC servers of a specific type without the need to set up such connections immediately. It is assumed that an OPC server of the desired type is present to serve as a prototype for gathering AE metadata. In this case the following steps need to be performed:

1. Add OPC server ProgID(s) and CLSID(s) to the Windows registry (This step is

only necessary if the OPC Server does not support OPC Enum and if the ProgID(s) and CLSID(s) are not already in the Windows registry).

2. Create new OPC gateway type using OPC Server Type Wizard. Optionally, set Alarm and Event ProgID to that defined in step 1. (This step is only required if the OPC gateway type does not already exist).

3. Run the Automatic AE configuration utility with “OPC Gateway does not exist” selected, specifying OPC server, gateway type, and authentication details. If the server progID and CLSID are not defined at this point, the Automatic AE configuration utility will read these from the OPC Server using OPC Enum. The utility will then create Alarm and Event storage configuration in the QConfig database, and generate the tables in QHistorianData database, if they do not exist. No new gateways are created.


8

Figure 3-2 OPC Gateways Form – Collect Alarm and Event Data

3.5. Manual AE Configuration Tool The manual AE configuration tool (AEConfig.exe) is included to supplement the automatic configuration facility. It is intended to be used in the following cases:

• Automatic configuration is unable to process all event attributes for a particular

category (for example, attribute data types are not supported). In that case the additional attributes can be added manually. If the defined attribute type is not supported by Exaquantum (e.g. unsigned integer) then the attribute should be manually defined with a compatible supported type (e.g. integer).

• Modifying existing configuration when OPC server configuration changes. Automatic configuration will not alter any category definitions that already exist


9

3.6. Processing and Storage This section contains an overview of how the Automatic AE Configuration utility processes and stores the Alarm and Event configuration.

3.6.1. Reviewing the processing log Following the configuration of Alarm and Event data, the log is saved in the below path. <Exaquantum Installation Folder>\log\AE\<date and time>-<opc server name>.log After the configuration, the log can be viewed. The log includes the following information:

• Header information. (OPC gateway name, OPC gateway type and OPC gateway

computer) • Main information. Start time (Local time) of process and the detail of each

process. (The Date and time format is YYYY-MM-DD hh:mm:ss)

The detail of the log is described on next section. Figure 3-3 shows a sample log output.

NOTE:

Only English language output is supported. Figure 3-3 Sample Log Output

---------------------------------------- Setting information [OPC Gateway Name:] [OPC Gateway Type:] NEWOPCTYPE01 [OPC Gateway Computer:] JUPITER ---------------------------------------- Processing log (UTC) 2014-10-14 09:36:47.842: Started AE automatic configuration process 2014-10-14 09:36:49.003: Connected to OPC server, reading AE metadata 2014-10-14 09:40:01.378: Accumulated AE metadata (3 event categories) 2014-10-14 09:40:02.000: Performing SQL steps 2014-10-14 09:40:02.000: Adding category: TestAlarmCategory 2014-10-14 09:40:09.167: Successfully added category (TestAlarmCategory) with 3 custom attributes 2014-10-14 09:40:09.168: Adding category: ProcessAlarm 2014-10-14 09:40:11.004: Failed to add category (ProcessAlarm) - category already exists for this OPC Gateway type 2014-10-14 09:40:11.004: Adding category: SpecialAlarms 2014-10-14 09:40:12.112: Failed to add custom attribute CustomAttribute1 to category SpecialAlarms: datatype not supported by exaquantum 2014-10-14 09:40:13.000: Successfully added category (SpecialAlarms) with 4 custom attributes (1 custom attribute failed) 2014-10-14 09:40:13.003: Finished AE automatic configuration process

3.6.2. Error, warning and processing log This section defines the error, warning and processing log for the Automatic AE Configuration utility. The log has both initialization errors and processing warnings. If an Initialization error is encountered, no processing is attempted. Then an error dialogue is displayed. If a processing warning occurs, then further processing is attempted, and the warning is written to the log. Secondly, the processing log has the detail of each process. All errors, warnings and processing information messages are stored in the processing log.


10

Figure 3-4 Initialization and Processing Warnings

Type Error message Error description

Initialization error

Failed to connect to OPC Server

Failed to create instance of the COM interface to the OPC server. Could be caused by network or configuration issues. HRESULT code is included for more detailed diagnostics.

Failed to authenticate to OPC Server with the specified credentials

Failed to authenticate to the OPC Server, either because private credentials are incorrect or because OPC Server does not support this authentication method.

Failed to query event categories

Querying event category date from the OPC server resulted in an error.

User not in correct Windows group

User invoking the AutoAE process needs to be in the appropriate maintenance group.

<any valid SQL Server error message>

If Automatic AE encounters an SQL server error, the error text is passed through. Initialization SQL errors include (but are not limited to) failure to connect to SQL server, lack of appropriate permissions and missing/inaccessible databases.

Processing warning

Unsupported data type

A data type of an AE attribute has been read from the OPC Server, for which no equivalent exists in Exaquantum. If Exaquantum supports a sufficiently similar data type (e.g. server supplies unsigned integer, Exaquantum supports integer) the attribute can be manually added using an Engineering tool.

Category <category> failed validation or already exists. It will not be added to the database

The <category> information is already present in Exaquantum. No attempt is made to reconcile any mismatch of category definition. The process will attempt to create the storage, if it does not exist. If the metadata and storages need to be re-created the original category needs to be deleted first (using an Engineering tool)

Storage <storage name> already exists in Exaquantum

The <storage name> already exists in Exaquantum. No attempt is made to reconcile any mismatch of storage definition. If storage needs to be re-created it must first be deleted manually.

<any valid SQL Server error message>

An SQL error was encountered. The errors are generated during execution of stored procedures that configure AE metadata and storages and may include both standard SQL server messages and any custom error messages explicitly produced by the stored procedures.

Failed to add <attribute> to <category>

A custom attribute could not be added to the specified category. This is a generic error. The rest of the log should be reviewed in order to determine appropriate action.


11

Table 3-3 Processing Log Messages

Message Description Started AE automatic configuration process

Indicated the beginning of the processing action

Finished AE automatic configuration process Indicates the end of the processing action

Metadata for <category> added successfully

Metadata for the listed <category> was successfully added to Exaquantum.

Metadata for <attribute> added successfully to <category>

A custom attribute could not be added to the specified category

<Non-error diagnostic messages from SQL Server>

If any of the stored procedures called produces any additional logging information it will be captured by the progress report

3.6.3. Storage Exaquantum stores Alarm and Event data in SQL Server. This consists of two parts: • Metadata – stored in the QConfig database • Storage – the tables storing actual Alarm and Event data. The tables reside in

QHistorianData. NOTES

1. When a storage table is created in SQL Server (QHistorianData), the table name has the format:

<opc server type>_<opc category name>

Where: <opc server type> - the OPC server type as defined in Exaquantum. <opc category name> - the OPC category name. For example Exaopc_CSSystemAlarm


12

4. EXAQUANTUM OPC GATEWAY TOOL Please refer to Reference 2 for details (CH 2)

4.1. Startup Run the Exaquantum Administration Tools from the Windows Start menu. Select the OPC gateways tool.

Table 4-1 Permissions required for the OPC Gateway Tool

Security Model Permissions required

Legacy Member of QAdministrators Group

Standard Member of QTM_MAINTENANCE Group

The tool can only be run with Exaquantum in running state.

4.2. Fields Table 4-2 OPC Gateway Tool – fields

Step Field/Action Action

1. OPC Gateway Name

Enter the Gateway name as it is to be known in Exaquantum

2. OPC Gateway Type Enter the OPC Server Type, as defined in Section 2

3. OPC Gateway Computer

Enter in the name (NetBIOS name) of the Computer where the Third Party OPC Server is running.

4.

Enable Exaquantum Alarms and Events

Check this box to enable Exaquantum to read AE data from this OPC Server

5. Enable Logon Check

If connection to the Third Party OPC Server requires a logon name and password – check the Logon Check option, and enter the User name and password.

6. Apply Click Apply to commit the definition. Alarm and Event data should now be stored in Exaquantum from the Third Party OPC Server.


13

5. COLLECTION OF ALARM AND EVENT DATA FROM YOKOGAWA PRM / STARDOM Collection of Alarm and Event Data from PRM and Stardom OPC Servers. A limited set of attributes can be collected. A limited set of attributes can be defined (by the AUTO-AE Config Tool) and therefore collected from the following OPC Server types: • Yokogawa PRM • Yokogawa Stardom

Please note that attributes with duplicate ids cannot be configured. The attributes that are collected are listed by opc server type and category, below.

5.1. Yokogawa PRM

5.1.1. Category: Device Alarm • TimeStamp • Source • Severity • Message • Cookie • PairKey • SubCondition • GroupID • MemoFileName • Message priority level • GroupName • ActiveShelf • OperationGroupID • Bus name • Node number • Slot number • Port number • Reaction • User account • Device availability • Plant hierarchy • Auxiliary information 1 • Auxiliary information 2 • Auxiliary information 3 • Extra action


14

5.1.2. Category: Device Configuration • Timestamp • Source • Severity • Message • Cookie • PairKey

5.1.3. Category: Device Event • Timestamp • Source • Severity • Message • Cookie • PairKey

5.1.4. Category: Diagnosis Alarm • Timestamp • Source • Severity • Message • Cookie • SubCondition • GroupID • MemoFileName • Message priority level (Character string) • GroupName • ActiveShelf • OperationGroupID • Bus name • Node number • Slot number • Port number • Reaction • User account • Diagnosis ID • Diagnosis name • Name of machine in which diagnosis is executed • Diagnosis tag • Alarm message of diagnosis • Device availability • Plant hierarchy • Auxiliary information 1 • Auxiliary information 2 • Auxiliary information 3 • Extra action


15

5.1.5. Category: Diagnosis Event • Timestamp • Source • Severity • Message • Cookie

5.1.6. Category: PAS Alarm • Timestamp • Source • Severity • Message • Cookie • SubCondition • GroupID • MemoFileName • Message priority level (Character string) • GroupName • ActiveShelf • OperationGroupID • Bus name • Node number • Slot number • Port number • Reaction • User account • Device availability • Plant hierarchy • Auxiliary information 1 • Auxiliary information 2 • Auxiliary information 3 • Extra action

5.1.7. Category: PAS Event • Timestamp • Source • Severity • Message • Cookie


16

5.1.8. Category: PRM Log • Timestamp • Source • Severity • Message • Cookie

5.1.9. Category: System Log • Timestamp • Source • Severity • Message • Cookie

5.1.10. Category: User Event • Timestamp • Source • Severity • Message • Cookie

5.2. Yokogawa Stardom

5.2.1. Category: Application alarm • Timestamp • Source • Severity • Message • Cookie • CENTUMMsgId • StationName • DataValue

5.2.2. Category: Application event • Timestamp • Source • Severity • Message • Cookie • CENTUMMsgId • StationName • DataValue


17

5.2.3. Category: Internal or source connection • Timestamp • Source • Severity • Message • Cookie

5.2.4. Category: Process alarm • Timestamp • Source • Severity • Message • Cookie • ActorID • ConditionName • SubConditionName • ChangeMask • NewState • ConditionQuality • AckRequired • ActiveTime • CENTUMMsgId • StationName • DataValue

5.2.5. Category: System alarm • Timestamp • Source • Severity • Message • Cookie • CENTUMMsgId • StationName • DataValue

5.2.6. Category: System event • Timestamp • Source • Severity • Message • Cookie • CENTUMMsgId • StationName • DataValue.

Documents

Technical Note Connecting and Reading Alarm and Event … GMSCS0123-01E Exaquantum Auto AE... · Auto AE Configuration Tool R3.01: Technical Note 3 1. INTRODUCTION This document describes