Configure the HAB Collector for Alarms

Before you begin

Create an instance of the HAB collector.

About this task

A configuration file is created when you install collectors. This file contains the following types of information, which are required for the Sampler application to connect to Habitat.
  • Site parameters: Contains the location details of Habitat from which you want to collect data. A single site can contain one or two nodes (the two nodes are used for a primary/standby configuration).

    A configuration file can contain only one Site section.

  • Collector parameters: Contains the following parameters:
    • Automatic tag sync: If the automatic tag sync option is enabled in the configuration file, when tags are added, renamed, or deleted in Habitat, the changes are reflected automatically in Historian. No manual steps are required; data collection begins automatically depending on the collection definition that you have provided in the configuration file. If, however, the automatic tag sync in disabled, you must approve tag changes, and only then they are reflected in Historian. For more information, refer to Approve Tag Changes. Depending on the collection definition that you have provided in the configuration file, tags are created in Historian, and data collection is initiated.
    • Tag deletion versus disablement: For tags deleted in Habitat, you must specify whether they must be deleted in Historian or just disabled for data collection.
    A configuration file can contain only one CollectorParameter section.
  • Collection definition parameters: Specifies which data to collect and how. For example, the Habitat application, database, and the family from which you want to collect data, whether the data is polled or unsolicited (that is, periodic or exception), the mapping between tag properties and the corresponding fields in Habitat, etc. There are two types of collection definition parameters: tag data collection and alarm data collection.

    A configuration file can contain multiple DataCollectionDefinition sections. If you do not want to use a collection definition for now, you can set the State parameter to DISABLED.

If you have created multiple instances of the collector, you must create one configuration file for each instance.

In addition to alarms, you can specify values for these parameters for tags. We recommend that you create a separate collector instance to collect tag data. You must then configure tags in a separate file.

Procedure

  1. Access the <collector name>_Config.xml file. By default, it is located at C:\Program Files\GE Digital\Historian HAB Collector\Server.
  2. Enter values as specified in the following tables.
    Table 1. Site Parameters
    Parameter Description
    Name The name that you want to assign to the site.
    Node1 The host name or IP address of the Habitat server (node) in the site from which you want to collect data. This server acts as the primary/active server from which the collector receives data.
    Node2 If you want to achieve high availability by connecting to redundant Habitat servers, provide the host names or IP addresses of both the servers - the active server in Node1 and the standby server in Node2.
    Note: You can provide the IP addresses of up to four Habitat servers - two of them in Node1 and other two in Node2, separated by commas.
    For example, if you want to connect to MachineA, MachineB, MachineC, and MachineD, enter:
    <Node1>MachineA,MachineB</Node1>
<Noade2>MachineC,MachineD</Node2>
    If you do so, MachineA becomes the active Habitat server, and in case of a failover, MachineB, MachineC, and MachineD each become active servers - one-by-one, in that order.
    For information on the various ways of achieving high availability, refer to High Availability.
    Socket The socket number (port number) used by the Habitat Sampler application to connect. Each collector instance can connect to only one socket.
    Retry The duration, in seconds, after which the collector tries to communicate with the site. The default value is 5.
    Example:
    <Site>
    <Name>Site1</Name>    
    <Node1>Host1</Node1>
    <Node2>Host2</Node2>
    <Socket>8040</Socket>
    <Retry>5</Retry>
</Site>
    Table 2. Collector Parameters
    Parameter Description Valid Values
    AutoTagSync Indicates whether tags must be created initially when the collector is connected to the Habitat Sampler application. It also indicates whether tags must be created, renamed, or deleted later automatically when the corresponding changes are done in Habitat.

    If you disable this option, you must manually confirm these changes. For example, if 10 tags are added in Habitat, you must confirm which of them must be created in Historian. For instructions, refer to Approve Tag Changes.
    • TRUE
    • FALSE
    TagDeletionType Specifies whether tags deleted in Habitat must be deleted or just disabled for data collection in Historian.
    • DISABLE_TAG
    • DELETE_TAG
    Example:
    <CollectorParameter>
    <AutoTagSync>TRUE</AutoTagSync>
    <TagDeletionType>DISABLE_TAG</TagDeletionType>
</CollectorParameter>
    Table 3. Collection Definition Parameters
    Parameter Description Valid Values
    Name The name of the collection definition. A value is required and must be unique.
    Important: You must not change the name after the collector starts collecting data. If, however, you want to change the name after the collector has started collecting data, refer to FAQs on HAB Collector.
    id Identifies the collection definition. A value is required and must be unique.
    Important: You must not change the ID after the collector starts collecting data. If, however, you want to change the ID after the collector has started collecting data, refer to FAQs on HAB Collector.
    Site The name of the site in Habitat from which you want to collect data. Provide the same value as the one you provided for the Name parameter in the Site section.
    Valid Indicates whether the collection definition is valid.
    • TRUE: Indicates that the collection definition is valid.
    • FALSE: Indicates that an error has occurred while processing the collection definition. In this case, the collector also sets the State parameter to DISABLED so that this collection definition is not considered.
    Status Indicates whether the collection definition is enabled.
    • ENABLED: Indicates that the collector is processing the collection definition.
    • DISABLED: Indicates that this data collection is not being used. You can manually disable a collection definition. Or if an error has occurred while processing the collection definition, the collector automatically sets this parameter to DISABLED.
    Application The name of the Habitat application from which you want to collect data (for example, ALARM).
    Database The name of the Habitat database from which you want to collect data (for example, ALARMLST).
    Family The name of the Habitat family from which you want to collect data (for example, EMS, DTS). A value is required and must be unique.
    RecordType The name of the HDB record from which you want to collect data (for example, CIRCLG). Any record type that contains the composite key and MRID fields (because the collector uses these two fields to create tags).
    CollectionType Indicates the collection type. For alarms, only unsolicited data collection is supported, which indicates that data is collected only when values have changed since the last time data was collected. Unsolicited (indicated as EXCEPTION in Habitat).
    Key This parameter is not applicable to alarms. Enter *.
    AlarmFilter The list of options to filter alarm data. It contains the following parameters:
    • Enabled: Enter TRUE or FALSE to specify whether you want to filter alarm data. The default value is TRUE.
    • Location, Area, Category, Priority, Exception: For each of these parameters, enter the criteria using which you want to filter alarm data. You can enter multiple values separated by commas (for example, LAKEVIEW,RICHVIEW). The default value is *, which indicates that data for that parameter is not filtered.
    For example, if you want to retrieve only the alarm data related to LAKEVIEW and RICHVIEW, in the area Australia, with priority 3, enter:
    <AlarmFilter>
    <Enabled>True</Enabled>
    <Location>LAKEVIEW,RICHVIEW</Location>
    <Area>Australia</Area>
    <Category>SCADATOP</Category>
    <Priority>3</Priority>
    <Exception>*</Exception>
</AlarmFilter>
    Note that data is filtered only if the criteria for all the parameters is satisfied.
    Important: The property names of the parameters for which you want to filter data must be included in the <Value> parameter under <TagTemplate>. For example, if the location, area, and priority are stored in the LOC_CIRCLG, AREA_CIRCLG, and PRIOR_CIRCLG fields respectively, enter <Value>LOC_CIRCLG,AREA_CIRCLG,PRIOR_CIRCLG</Value>
    TagNameFields Determines how the tags created in Historian must be named.

    For example, if you want the tags to be named after the value in the LOC_CIRCLG field, enter <TagNameFields>LOC_CIRCLG</TagNameFields>. When you do so, if the value in the LOC_CIRCLG field in Habitat is DOUGLAS, the tag created in Historian will be named <TagPrefix value>.<AlarmPrefix value>.DOUGLAS.

    You can enter multiple values separated by commas.

    For example, if you want the tags to be named after the values in the LOC_CIRCLG and PRIOR_CIRCLG fields, enter: 
    <TagNameFields>LOC_CIRCLG,PRIOR_CIRCLG</TagNameFields>
    When you do so, if the values in the LOC_CIRCLG and PRIOR_CIRCLG fields are Douglas and 1 respectively, the tag created in Historian will be named <TagPrefix value>.<AlarmPrefix value>.DOUGLAS.1.
    TagPrefix The prefix that you want to use for tags. You can provide a different value for each collection definition, which helps you identify tags based on the collection definition.
    TagTemplate The list of tag properties for which you want to collect data. In Historian, we use the Value tag property.
    You must map these properties with the corresponding ones in Habitat. For example, if the value of a tag is stored in the TEXT_CIRCLG field in Habitat, enter:
    <TagTemplate>
    <Value>TEXT_CIRCLG</value>
    <Timestamp></Timestamp>
    <Quality></Quality>   
</TagTemplate>
    For the Value parameter, if you want to collect data from multiple fields, enter them separated by commas. The values will then be concatenated in the corresponding Historian tag (for example, <Value>TEXT_CIRCLG, PRIOR_CIRCLG, TIME_CIRCLG</Value>).
    Important:
    • Quality is not applicable to alarms. In addition, to provide the timestamp column name, include it in the <Value> element itself separated by a comma. Therefore, do NOT enter values for the <Timestamp> and <Quality> elements, but retain the elements.
    • If you have provided filter criteria under <AlarmFilter>, enter the names of those fields in the <Value> parameter.
    SampleOptions Contains the following elements:
    • SampleRate: The rate at which you want to collect data.
    • SampleUnit: The unit of measurement for the sample rate.
    • Permanent: Indicates whether you want to store the data in buffer files in Habitat in the event of a connection loss. We strongly recommend that you set this parameter to true to prevent loss of data.
    For example, if you want to collect data every 5 seconds, enter:
    <SampleOptions>
    <SampleRate>5</SampleRate>
    <SampleUnit>sec</SampleUnit>
    <Permanent>TRUE</Permanent>
</SampleOptions>
    		 Valid values for SampleUnit:
    • sec
    • min
    • hour
    • day
    • week
    • month
    Valid values for Permanent:
    • TRUE
    • FALSE
    Example:
    <AlarmCollectionDefinitions>
    <AlarmCollectionDefinition>
        <Name>ALARM</Name>
        <id>1</id>
        <Site> Site1</Site>
        <Valid>TRUE</Valid>
        <Status>ENABLED</Status>
        <Family>DTS</Family>
        <Application>ALARM</Application>
        <Database>ALARMLST</Database>
        <RecordType>CIRCLG</RecordType>
        <CollectionType>Unsolicited</CollectionType>
        <Key>*</Key>
        <AlarmFilter>
            <Enabled>True</Enabled>
            <Location>LAKEVIEW,RICHVIEW</Location>
            <Area>Australia</Area>
            <Category>SCADATOP</Category>
            <Priority>3</Priority>
            <Exception>*</Exception>
        </AlarmFilter>
        <TagNameFields>LOC_CIRCLG</TagNameFields>
        <TagPrefix>ALARM.</TagPrefix>       
        <TagTemplate>
     	<Value>TEXT_CIRCLG,PRIOR_CIRCLG,LOC_CIRCLG,AREA_CIRCLG</Value>
     	<Timestamp>SCADATIME</Timestamp>
     	<Quality></Quality>
        </TagTemplate>
        <SampleOptions>
            <SampleRate>5</SampleRate>
            <SampleUnit>sec</SampleUnit>
            <Permanent>FALSE</Permanent>
        </SampleOptions>
    </AlarmCollectionDefinition>
</AlarmCollectionDefinitions>
  3. Save and close the file.
    The HAB collector is configured.

What to do next

Start the collector.