Configure the HAB Collector for Tags

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.

In addition to tags, you can specify values for these parameters for alarms. We recommend that you create a separate collector instance to collect alarm data. You must then configure alarms 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. The default value is 8040.
    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.
    State 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, SCADA).
    Database The name of the Habitat database from which you want to collect data (for example, SCADAMOM).
    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, ANALOG,POINT,COUNT). Any record type that contains the composite key and MRID fields (because the collector uses these two fields to create tags).
    CollectionType Indicates whether you want to perform polled or unsolicited data collection.
    • Polled: Indicates a periodic data collection, where data is collected at a regular time interval (indicated as PERIODIC in Habitat).
    • Unsolicited: Indicates that data is collected only when values have changed since the last time data was collected (indicated as EXCEPTION in Habitat).
    Key The value that will be used to filter tags for data collection. You can use the wildcard character * to get a range of values. For example, if you want to collect data from all tags that begin with SUBSTN.LAKEVIEW, enter: SUBSTN.LAKEVIE*.*.*.*.*
    TagTemplate The list of tag properties for which you want to collect data. In Historian, we use the following tag properties:
    • Value
    • Timestamp
    • Quality
    You must map these properties with the corresponding ones in Habitat. For example, if the value, timestamp, and quality of a tag are stored in the DIS_ANALOG, SCTIME_ANALOG, and DFLAGS_ANALOG fields in Habitat, respectively, enter:
    <TagTemplate>
    <Value>DIS_ANALOG</value>
    <Timestamp>SCTIME_ANALOG</Timestamp>
    <Quality>DFLAGS_ANALOG</Quality>
</TagTemplate>

    For the Timestamp parameter, you can use a HDB timestamp or custom/alias timestamps.

    For analog, you can use:
    • FIELDTIME: A combination of FLDTIME_ANALOG and FLDMSEC_ANALOG, in the hour: min:sec: millisec format.
    • SCADATIME: Used to capture SCTIME_ANALOG in the hour: min:sec: millisec format.
    • SAMPLETIME: The time at which the data sample was collected in Habitat in the hour: min:sec format.
    For point, you can use:
    • FIELDTIME: A combination of FLDTIME_POINT and FLDMSEC_POINT, in the hour: min:sec: millisec format.
    • SCADATIME: Used to capture SCTIME_POINT in the hour: min:sec: millisec format.
    • SAMPLETIME: The time at which the data sample was collected in Habitat in the hour: min:sec format.
    For count, you can use:
    • FIELDTIME: A combination of FLDTIME_COUNT and FLDMSEC_COUNT, in the hour: min:sec: millisec format.
    • SAMPLETIME: The time at which the data sample was collected in Habitat in the hour: min:sec format.

    You can edit the names of these custom/alias timestamps using the registry entries FieldTimeCustomFieldName, ScadaTimeCustomFieldName, and SampleTimeCustomFieldName respectively.
    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:
    <DataCollectionDefinitions>
    <DataCollectionDefinition>
        <Name>ANALOG_HIST</Name>
        <id>1</id>
        <Site>Site1</Site>
        <Valid>TRUE</Valid>
        <Status>DISABLED</Status>
        <Family>DTS1</Family>
        <Application>SCADA1</Application>
        <Database>SCADAMOM1</Database>
        <RecordType>ANALOG</RecordType>
        <CollectionType>Unsolicited</CollectionType>
        <Key>*</Key>
        <TagTemplate>
            <Value>DIS_ANALOG</Value>
            <Timestamp>SCTIME_ANALOG</Timestamp>
            <Quality>DFLAGS_ANALOG</Quality>
        </TagTemplate>
        <SampleOptions>
            <SampleRate>5</SampleRate>
            <SampleUnit>sec</SampleUnit>
            <Permanent>FALSE</Permanent>
        </SampleOptions>
    </DataCollectionDefinition>
    <DataCollectionDefinition>
        <Name>ANALOG_HIST</Name>
        <id>2</id>
        <Site>Site1</Site>
        <Valid>TRUE</Valid>
        <Status>ENABLED</Status>
        <Family>DTS2</Family>
        <Application>SCADA2</Application>
        <Database>SCADAMOM2</Database>
        <RecordType>ANALOG</RecordType>
        <CollectionType>Polled</CollectionType>
        <Key>*</Key>
        <TagTemplate>
            <Value>DIS_ANALOG</Value>
            <Timestamp>SCTIME_ANALOG</Timestamp>
            <Quality>DFLAGS_ANALOG</Quality>
        </TagTemplate>
        <SampleOptions>
            <SampleRate>5</SampleRate>
            <SampleUnit>sec</SampleUnit>
            <Permanent>TRUE</Permanent>
        </SampleOptions>
    </DataCollectionDefinition>
</DataCollectionDefinitions>
  3. Save and close the file.
    The HAB collector is configured.

What to do next

Start the collector.